extend Interoperability Suite

Welcome to extend Interoperability Suite

  • Overview of ACUCOBOL-GT
  • Product Information
  • Getting Started
  • ACUCOBOL-GT User's Guide
  • License Management
  • License Files for extend Products
New features

What's new

  • What's New
  • Changes Affecting Version 10.2.0
Featured sections

Featured sections

  • Interoperability
  • Appendix A. Specifications
  • Configuration Variables
  • Program Structure
  • Transitioning Your COBOL
  • Using BIS
Tutorials and demonstrations

Tutorials and demonstrations

  • BIS Tutorial
  • Tutorial: Using RMNet to Move Data Between Your Program and a Web Server
Samples

Code samples

  • Sample Programs
  • Programming GUI Objects
  • AcuSQL ESQL Demonstration Programs
  • AcuSort Code Sample
  • Sample client.cfg File
Online resources

Online resources

  • Micro Focus Infocenter
  • Micro Focus SupportLine
  • Micro Focus Product Updates
  • Micro Focus Knowledge Base
  • Micro Focus Community Forums
  • Micro Focus Training Store
Provide feedback

Provide feedback

  • Contacting Micro Focus
  • Email us feedback regarding this Help


ACUCOBOL-GT Version 10.2.0 Getting Started Guide

  • Product Information
  • Getting Started
  • License Management
  • Troubleshooting
    This section provides solutions to some issues you may encounter when setting up extend products.
Parent topic: extend Interoperability Suite


Product Information

This Product Information covers information available at the time of writing. Up-to-date information is downloadable from the SupportLine Web site.

  • Copyright Statement
  • What's New
  • extend System Requirements
  • Windows Installation
  • UNIX Installation
  • VMS and OpenVMS Installation
  • Known Errors and Restrictions
  • Micro Focus Services and Solutions
Parent topic: ACUCOBOL-GT Version 10.2.0 Getting Started Guide


Copyright Statement

Copyright © Micro Focus. 1988-2018. All rights reserved. Acucorp, ACUCOBOL-GT, Acu4GL, AcuBench, AcuConnect, AcuServer, AcuSQL, AcuXDBC, extend , and "The new face of COBOL" are registered trademarks or registered service marks of Micro Focus. "COBOL Virtual Machine" is a trademark of Micro Focus. Acu4GL is protected by U.S. patent 5,640,550, and AcuXDBC is protected by U.S. patent 5,826,076.

Microsoft and Windows are registered trademarks of Microsoft Corporation in the United States and/or other countries. UNIX is a registered trademark of the Open Group in the United States and other countries. Solaris is a trademark of Sun Microsystems, Inc., in the United States and other countries. Other brand and product names are trademarks or registered trademarks of their respective holders.

Parent topic: Product Information
Parent topic: ACUCOBOL-GT Version 10.2.0 Documentation Set
Parent topic: ACUCOBOL-GT Version 10.2.0 Run-Time Manual
Parent topic: Acu4GL Version 10.2.0 User's Guide
Parent topic: AcuConnect Version 10.2.0 User's Guide
Parent topic: AcuServer Version 10.2.0 User's Guide
Parent topic: AcuSQL Version 10.2.0 User's Guide
Parent topic: AcuToWeb Version 10.2.0 User's Guide
Parent topic: AcuXDBC Version 10.2.0 User's Guide
Parent topic: A Programmer’s Guide to the Internet Version 10.2.0
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


What's New

The following items are new for this release:

  • ACUCOBOL-GT Enhancements
    Contains a list with all ACUCOBOL-GT enhancements.
  • Acu4GL Enhancements
    Contains a list with all Acu4GL enhancements.
  • AcuBench Enhancements
    Contains a list with all AcuBench enhancements.
  • AcuConnect Enhancements
    Contains a list with all AcuConnect enhancements.
  • AcuServer Enhancements
    Contains a list with all AcuServer enhancements.
  • AcuSQL Enhancements
    Contains a list of all AcuSQL enhancements.
  • AcuToWeb Enhancements
    Contains a list with all AcuToWeb enhancements.
  • AcuXDBC Enhancements
    Contains a list with all AcuXDBC enhancements.
Parent topic: Product Information


ACUCOBOL-GT Enhancements

This section includes the enhancements related to ACUCOBOL-GT.

  • ECN-4438 vutil -key now allows you to create and modify keys that do not allow duplicates
  • ECN-4439 New vutil -info option to display key descriptor information
  • ECN-4440 vutil key information display reformatted
  • ECN-4481 Vision 2 file format support discontinued
  • ECN-4484 New control properties for AcuToWeb styles
  • ECN-4487 New intrinsic function: INTERVAL-TIMER
  • ECN-4489 Intrinsic function syntax enhancement
  • ECN-4490 New intrinsic functions
  • ECN-4491 x64 and AMD64 native code generation
  • ECN-4501 ACCEPT statement enhanced with AcuToWeb TERMINAL-ABILITIES
  • ECN-4519 New PDF printing library routine for UNIX and Windows
Parent topic: What's New


ECN-4438 vutil -key now allows you to create and modify keys that do not allow duplicates

Product: ACUCOBOL-GT

Module: vutil

Machines Affected: all

DESCRIPTION:

The vutil -key enhancement introduced in 10.1.0 (ECN-4430) had a caveat that new and modified keys would always allow duplicates, regardless of the setting in the key description. This enhancement removes that caveat. The setting for duplicate key values in the key descriptor will now be honored and keys not allowing duplicate key values can be created. However, if duplicate key values are found while indexing the key, the key will allow duplicate key values regardless of the setting in the key description.

Parent topic: ACUCOBOL-GT Enhancements
Related reference
Modifying Keys in an Existing File


ECN-4439 New vutil -info option to display key descriptor information

Product: ACUCOBOL-GT

Module: vutil

Machines Affected: all

DESCRIPTION:

The vutil -info function now takes a new option, d, which displays details of the key descriptors in the specified Vision file. The key descriptors are strings that describe a key and display in the same format as kdesc when vutil -key is used. For example:

vutil32 -info -d IDX2.vis
IDX2.vis  [vision version 6]
0: 1,0,10,0
1: 1,1,40,10
Restriction: This option cannot be used with either options -k or -x.
Parent topic: ACUCOBOL-GT Enhancements
Related reference
Examining File Information


ECN-4440 vutil key information display reformatted

Product: ACUCOBOL-GT

Module: vutil

Machines Affected: all

DESCRIPTION:

The key information displayed by vutil -info -k has been reformatted to a simple table in order to better display keys with many segments. The following example shows a file with a key made up of 16 segments:

$ vutil -info -k keyfile
keyfile [vision version 6]

# of records:              9
# of deleted records:      0 (0+0)
file size:             16896 (keyfile)
file size:             61952 (keyfile.vix)
total file size:       78848
record size:              49
# of keys:               120
user count:                0

Key Dups Segment Size  Offset
  0    N     0      2       1
             1      2       4
             2      2       7
             3      2      10
             4      2      13
             5      2      16
             6      2      19
             7      2      22
             8      2      25
             9      2      28
            10      2      31
            11      2      34
            12      2      37
            13      2      40
            14      2      43
            15      2      46
Parent topic: ACUCOBOL-GT Enhancements
Related reference
Examining File Information


ECN-4481 Vision 2 file format support discontinued

Product: ACUCOBOL-GT

Module: Vision

Machines Affected: all

DESCRIPTION:

Support for the Vision 2 file format is discontinued in this version of the extend Interoperability Suite. The Vision 2 file format was not portable between systems with different architectures, and was superseded by the Vision 3 file format over 24 years ago. Use of the Vision 2 file format has not been recommended for a very long time.

Any remaining Vision 2 files should be rebuilt to a newer Vision file format; see Rebuilding Files for more details. Vision 3 is a portable single-file format containing the index and records in a single file, and is limited to file sizes less than 2GB; Vision 4 and Vision 5 are portable dual file formats using multiple segments to support large files; and Vision 6 is a portable dual file format supporting files larger than 2GB. Vision 6 is the default Vision file format, and for best results use this file format where possible.

Parent topic: ACUCOBOL-GT Enhancements


ECN-4484 New control properties for AcuToWeb styles

RPI Number: 626320

Product: ACUCOBOL-GT

Module: Compiler

Machines Affected: All

DESCRIPTION:

Two new properties for controls and windows have been introduced to allow you to control their appearance when run through AcuToWeb. The two properties are able to correspond with a class or ID set in the cascading style sheet used as a theme when running through the AcuToWeb gateway.

The two new properties are:

  • ATW-CSS-CLASS - Set to a string value that corresponds to a class in the cascading style sheet used as the current theme in AcuToWeb. This property can be applied to more than one control in your program.
  • ATW-CSS-ID - Set to a string value that corresponds to an ID in a cascading style sheet used as the current theme in AcuToWeb. This property must have a unique value and be applied to just one control in your program.

These properties take a string as their value and can be applied to the control or window through editing the source code, or via the Properties pane in AcuBench.

The following excerpt contains a screen with two push buttons. The first button (Pb-1) has specified the class basicpbclass, and the second button (Pb-2) has specified the ID runpbid.

...
01 Screen1.
   03 Pb-1, Push-Button, COL 38.30, LINE 15.00,
      LINES 3.50 CELLS, SIZE 14.00 CELLS, ATW-CSS-CLASS "basicpbclass" ID IS 1, CANCEL-BUTTON, TITLE "Exit".
   03 Pb-2, Push-Button,COL 1.80, LINE 10.10,
      LINES 3.50 CELLS, SIZE 28.40 CELLS,EXCEPTION-VALUE 81, ID IS 2, ATW-CSS-ID "runpbid"
      TITLE "Run".
...

If you run the full program through AcuToWeb whilst using a theme containing definitions for both the class and ID, these push buttons will be styled appropriately; for example:

.basicpbclass{
       border-width: 1px;
       border-radius: 2px;
       background-color:  #ff2247 !important;
             }
#runpbid{
       border-width: 1px;
       border-radius: 4px;
       background-color:  #21ff43 !important;
        }
Parent topic: ACUCOBOL-GT Enhancements
Related reference
ECN-WB661 AcuToWeb properties available in AcuBench


ECN-4487 New intrinsic function: INTERVAL-TIMER

Product: ACUCOBOL-GT

Module: Compiler/Runtime

Machines Affected: All

Known Versions Affected: All

DESCRIPTION:

A new intrinsic function has been introduced, INTERVAL-TIMER, that is suitable for measuring short time intervals with comparatively high precision. It can be useful in cases where ACCEPT FROM TIME does not report enough resolution.

The function takes no parameters, and returns a value of some number of seconds starting from an arbitrary point. Typically, you will want to use the function twice or more in order to take differences between the return values in order to time an interval.

Another potential use would be to get a higher-resolution timestamp to distinguish items with identical keys.

Refer to Appendix F Intrinsic Functions for full syntactical details and notes of the function.

Parent topic: ACUCOBOL-GT Enhancements
Related reference
Introduction to Intrinsic Functions


ECN-4489 Intrinsic function syntax enhancement

Product: ACUCOBOL-GT

Module: Compiler

Machines Affected: All

Known Versions Affected: All

DESCRIPTION:

As a programming convenience, you can now replace the word FUNCTION with $ when calling an intrinsic function. For example:

compute result = function max( function sqrt(src), last-result )

can now also be written as:

compute result = $max( $sqrt(src), last-result )
Parent topic: ACUCOBOL-GT Enhancements
Related reference
Introduction to Intrinsic Functions


ECN-4490 New intrinsic functions

Product: ACUCOBOL-GT

Module: Compiler/Runtime

Machines Affected: All

Known Versions Affected: All

DESCRIPTION:

The following intrinsic functions have been added to assist with text handling:

  • TRIM - Trims a particular character from the start and end of an alphanumeric string.
  • COUNT-LEADING - Returns the number of consecutive times that a character appears at the beginning of a string.
  • COUNT-TRAILING - Returns the number of consecutive times that a character appears at the end of a string.

Refer to Appendix F Intrinsic Functions for full syntactical details of each function.

Parent topic: ACUCOBOL-GT Enhancements
Related reference
Introduction to Intrinsic Functions


ECN-4491 x64 and AMD64 native code generation

Product: ACUCOBOL-GT

Module: cblutil

Machines Affected: All

Known Versions Affected: All

DESCRIPTION:

It is now possible to generate native 64-bit object code for Intel x64 and AMD64 processors. The benefit to native code is substantially superior performance for CPU-heavy portions of code; however, the drawback remains that portability of the object files is limited to similar platforms.

Use the ccbl and cblutil -native syntax, followed by one of the new parameters to generate x64 native code:

  • --x64_Win
  • --x64_Unix (or --x64_Linux)

Note that x64 object code is not portable between Windows and Unix/Linux platforms, hence the two distinct options. The --x64_Unix and --x64_Linux options are synonymous with each other.

Examples:

To compile a COBOL program to x64 native code for a UNIX platform:

ccbl --x64_Unix program.cbl

To assemble a number of COBOL program to x64 native code for a UNIX platform:

cblutil -native --x64_Unix *.acu
Parent topic: ACUCOBOL-GT Enhancements
Related reference
Native Code Options


ECN-4501 ACCEPT statement enhanced with AcuToWeb TERMINAL-ABILITIES

RPI Number: 623474

Product: ACUCOBOL-GT

Module: Runtime

Machines Affected: All

DESCRIPTION:

When using AcuToWeb to run a remote program, the runtime now returns the following information when executing ACCEPT FROM TERMINAL-ABILITIES.

03 ATW-BROWSER-NAME PIC X(30).
03 ATW-BROWSER-VERSION PIC X(10).
03 ATW-ENGINE-NAME PIC X(30).
03 ATW-ENGINE-VERSION PIC X(10).
03 ATW-CLIENT-OS-NAME PIC X(30).
03 ATW-CLIENT-OS-VERSION PIC X(10).
03 ATW-CLIENT-DEVICE-TYPE PIC X(30).
03 ATW-CLIENT-DEVICE-VENDOR PIC X(30).
03 ATW-CLIENT-DEVICE-MODEL PIC X(30).

If you are not using AcuToWeb, these fields will remain blank.

Parent topic: ACUCOBOL-GT Enhancements


ECN-4519 New PDF printing library routine for UNIX and Windows

Product: ACUCOBOL-GT

Module: Runtime

Machines Affected: all

DESCRIPTION:

A new library routine, C$PDF, has been introduced to enable PDF printing.

The library routine calls into the libharu PDF printing library (http://libharu.org/) to give a comprehensive range of PDF print functionality that you can embed in your COBOL programs. It provides more flexibility than using the existing PDF printing mechanism (-P PDF option).

For example, the following COBOL calls are used to create a new PDF document and add a page:

call "C$PDF" using HPDF-NEW
             giving HPDF-DOC.
call "C$PDF" using HPDF-ADDPAGE,
             HPDF-DOC,
             giving HPDF-PAGE.

The run time then passes the resulting information to the libharu API to run its equivalent functions:

HPDF_Doc HPDF_New (HPDF_Error_Handler user_error_fn,
                   void *user_data);
HPDF_Page HPDF_AddPage (HPDF_Doc pdf);
Parent topic: ACUCOBOL-GT Enhancements
Related reference
C$PDF


Acu4GL Enhancements

This section includes the enhancements related to Acu4GL.

  • ECN-GL557 Multi-subnet clustering support
  • ECN-GL558 Column type GUID now supported for Microsoft SQL Server
  • ECN-GL561 Acu4GL for ODBC now available on Linux/UNIX platforms
  • ECN-GL563 MSSQL is now available on Linux platforms
Parent topic: What's New


ECN-GL557 Multi-subnet clustering support

Product: Acu4GL

Module: MSSQL

Machines Affected: Windows

DESCRIPTION:

Acu4GL now supports connecting to a Microsoft SQL Server running a multi-subnet failover cluster. To use this feature requires changes to the connection string sent to the server, which is accomplished by using the following 4 new configuration variables:

  • A_MSSQL_MULTI_SUBNET_FAILOVER - set to TRUE to enable a connection that supports multi-subnet failover support. If set to FALSE (the default) support is not enabled, and the other configuration variables have no effect.
  • A_MSSQL_FAILOVER_PARTNER - the name of the failover partner used. Refer to your SQL Server documentation for valid values.
  • A_MSSQL_FAILOVER_PARTNER_SPN - the name of the failover partner SPN used. Refer to your SQL Server documentation for valid values.
  • A_MSSQL_SERVER_SPN - the name of the Server SPN. Refer to your SQL Server documentation for valid values.
Parent topic: Acu4GL Enhancements
Related reference
Configuration File Variables


ECN-GL558 Column type GUID now supported for Microsoft SQL Server

Incidents: 2886841

RPI Number: 1108310

Product: Acu4GL

Module: MSSQL

Machines Affected: Windows

Known Versions Affected: All

DESCRIPTION:

Acu4GL for SQL Server now supports columns of type GUID for existing SQL tables.

A new configuration variable, A_MSSQL_IGNORE_GUID_COLUMNS, determines the behavior when handling existing tables that contain a column of this type. Acu4GL cannot create a new column of this type.

When A_MSSQL_IGNORE_GUID_COLUMNS is set to its default setting of FALSE, you must use COBOL data items that are at least 36 characters in size for GUID columns, otherwise an error is returned when the row is read. When writing or rewriting a row when the GUID data item is too small, SQL Server may produce an error. If you have a GUID that is larger that 36 characters, Acu4GL will only read the first 36 characters; the rest are padded with spaces.

Note: Older ODBC drivers may not be able to handle GUID column types, in which case, the results of those operations are undefined.

If you set A_MSSQL_IGNORE_GUID_COLUMNS to TRUE, columns of type GUID are ignored for any SELECT, UPDATE, or INSERT statements sent to the server. You do not need to specify a COBOL data item for these columns when reading or writing a row.

Parent topic: Acu4GL Enhancements
Related reference
A_MSSQL_IGNORE_GUID_COLUMNS configuration variable


ECN-GL561 Acu4GL for ODBC now available on Linux/UNIX platforms

Product: Acu4GL

Module: ODBC

Machines Affected: Linux/UNIX

Known Versions Affected: All

DESCRIPTION:

Acu4GL for ODBC is now available on Linux/UNIX platforms if you have a shared libraries build of the extend Interoperability Suite and use one of the following supported UNIX ODBC Driver Managers:

  • unixODBC (www.unixodbc.org)
  • DataDirect (www.progress.com)
  • iODBC (www.iodbc.org)

Contact the appropriate vendor for information about how to install and configure these driver managers. When correctly configured, you need to ensure that the lib directory of the driver manager, and the lib directory for the ACUCOBOL-GT install is included in the LD_LIBRARY_PATH environment variable.

Parent topic: Acu4GL Enhancements
Related reference
Installation of Acu4GL for ODBC


ECN-GL563 MSSQL is now available on Linux platforms

Product: Acu4GL

Module: MSSQL

Machines Affected: Linux only

DESCRIPTION:

Acu4GL for MSSQL is now available on certain Linux platforms if you are running a 64-bit shared libraries build of the extend Interoperability Suite; see the Microsoft SQL Server support web pages for an up-to-date list of specific supported platforms.

Your Linux clients can connect to an MSSQL Server on a Linux machine or a Windows machine. You can also use a Windows client to connect to an instance of SQL Server running on Linux. (Note that setting up SQL Server on a Linux machine is beyond the scope of our documentation.)

If you are connecting to a Windows SQL Server, set up your Linux client in the same way that you would when using a Windows client. For setting up a connector to a Linux database, you must run a new script (ms_inst.sh), included with your install, to create the SQL script that creates the stored procedures, tables, error messages, etc. required to connect to the server. Run this script in the same way that you would run ms_inst.cmd on Windows: you execute the script using an argument of the name of a database that will hold the lock tables.

Running this script produces a .sql script, which you must execute using the tools supplied with your SQL Server installation.

The runtime configuration settings are the same for Windows and Linux. See your Acu4GL for MSSQL documentation for those variables.

The connector itself is included as a shared object that can be loaded dynamically by the runtime, so no relinking of the runtime is necessary in order to use the functionality described above.

Parent topic: Acu4GL Enhancements
Related reference
Appendix B: Acu4GL for Microsoft SQL Server


AcuBench Enhancements

This section includes the enhancements related to AcuBench.

  • ECN-WB661 AcuToWeb properties available in AcuBench
Parent topic: What's New


ECN-WB661 AcuToWeb properties available in AcuBench

Product: AcuBench

Module: AcuBench.exe

Machines Affected: Windows

DESCRIPTION:

In this release, ECN-4484 introduced new properties for use with AcuToWeb cascading style sheets: ATW-CSS-CLASS and ATW-CSS-ID. These two properties are now available in the AcuBench user interface.

As with other controls/properties, there are also 'property-name VARIABLE' versions of these properties, enabling you to create working-storage items for the properties in you source code.

Parent topic: AcuBench Enhancements
Related reference
ECN-4484 New control properties for AcuToWeb styles


AcuConnect Enhancements

This section includes the enhancements related to AcuConnect.

  • ECN-AC099 AcuConnect Control Panel enhancements
Parent topic: What's New


ECN-AC099 AcuConnect Control Panel enhancements

Product: AcuConnect

Module: AcuRCL

Machines Affected: Windows

Known Versions Affected: All

DESCRIPTION:

The AcuConnect Control Panel now includes the following enhancements:

  • The Access tab automatically opens the most recently used access file. If required, click Open to open another access file.
  • The Alias tab automatically opens the most recently used alias file. If required, click Open to open another alias file.
  • The Services tab includes two new options:
    Edit config ...
    This option enables you to edit the server configuration file specified for the selected service. If one does not exist, you are prompted to create one. The file is opened in Notepad, where you can edit and save it, as required.
    Edit error file ...
    This option enables you to view or edit the error file specified for the selected service. If the service is currently running, then the file will be in use; therefore, a snapshot of the file is taken, and it this copy that is displayed. The file is opened in Notepad, where you can view, edit, and save it, as required.
    Note: Whilst using either of these options, the control panel is in a 'wait' state, and you need to close Notepad before continuing to use the control panel.
Parent topic: AcuConnect Enhancements


AcuServer Enhancements

This section includes the enhancements related to AcuServer.

  • ECN-AS161 AcuServer Control Panel enhancements
Parent topic: What's New


ECN-AS161 AcuServer Control Panel enhancements

Product: AcuServer

Module: AcuServe

Machines Affected: Windows

Known Versions Affected: All

DESCRIPTION:

The AcuServer Control Panel now includes the following enhancements:

  • The Access tab automatically opens the most recently used access file. If required, click Open to open another access file.
  • The Services tab includes two new options:
    Edit config ...
    This option enables you to edit the server configuration file specified for the selected service. If one does not exist, you are prompted to create one. The file is opened in Notepad, where you can edit and save it, as required.
    Edit error file ...
    This option enables you to view or edit the error file specified for the selected service. If the service is currently running, then the file will be in use; therefore, a snapshot of the file is taken, and it this copy that is displayed. The file is opened in Notepad, where you can view, edit, and save it, as required.
    Note: Whilst using either of these options, the control panel is in a 'wait' state, and you need to close Notepad before continuing to use the control panel.
Parent topic: AcuServer Enhancements


AcuSQL Enhancements

This section includes the enhancements related to AcuSQL for this release.

  • ECN-SQL155 No longer required to relink the runtime to use AcuSQL on UNIX
Parent topic: What's New


ECN-SQL155 No longer required to relink the runtime to use AcuSQL on UNIX

Product: AcuSQL

Module: Runtime

Machines Affected: UNIX

Known Versions Affected: All

DESCRIPTION:

In the past, to use AcuSQL on UNIX you were required to relink the runtime to include the ODBC level 2 API software library. This is no longer necessary if you use a shared libraries build of the extend Interoperability Suite and use one of the supported ODBC Driver Managers:

  • unixODBC (www.unixodbc.org)
  • DataDirect (www.progress.com)
  • iODBC (www.iodbc.org)

Contact the appropriate vendor for information about how to install and configure these driver managers. When correctly configured, you need to additionally ensure that the lib directory of the driver manager is on the LD_LIBRARY_PATH.

Note: If you have a static version of extend Interoperability Suite or you do not want to rely on this new layer of software, you must still relink the runtime to include the functionality. See the Installation Under UNIX topic in the Getting Started section of the AcuSQL product documentation for more details.
Parent topic: AcuSQL Enhancements
Related reference
Installation Under UNIX


AcuToWeb Enhancements

This section includes the enhancements related to AcuToWeb.

  • ECN-AW042 Gateway configuration file now supports plain text format
  • ECN-AW052 AcuToWeb Control Panel enhancements
  • ECN-AW056 fillcombo.js file location now configurable
  • ECN-AW073 Navigating AcuToWeb on mobile devices
  • ECN-AW080 Message Box buttons now display using OS language
  • ECN-AW081 Additional W$BITMAP support added
Parent topic: What's New


ECN-AW042 Gateway configuration file now supports plain text format

RPI: 627632

Product: AcuToWeb

Module: AcuToWeb

Machines Affected: all

DESCRIPTION:

The AcuToWeb configuration file, named gateway.conf by default, is now supported as a plain text file, as well as the existing JavaScript format. As a plain text file, you can include comments in the configuration file. Syntax rules for the plain text format are:
  • Lines starting with # are comments
  • All other lines are key-value pairs
  • Key-value pairs are separated by spaces, tabs or = characters
  • Keys are case insensitive

By default, the gateway.conf file resides in C:\etc (Windows) or /etc (UNIX) directory.

If you use the AcuToWeb Control Panel to specify an existing gateway.conf file that is in JavaScript format, it is automatically converted to plain text format.

Parent topic: AcuToWeb Enhancements


ECN-AW052 AcuToWeb Control Panel enhancements

Product: AcuToWeb

Module: AcuToWeb

Machines Affected: Windows

Known Versions Affected: All

DESCRIPTION:

The AcuToWeb Control Panel now includes the following enhancements:

  • The Access tab automatically opens the most recently used access file. If required, click Open to open another access file.
  • The Alias tab automatically opens the most recently used alias file. If required, click Open to open another alias file.
  • The Services tab includes two new options:
    Edit config ...
    This option enables you to edit the server configuration file specified for the selected service. If one does not exist, you are prompted to create one. The file is opened in Notepad, where you can edit and save it, as required.
    Edit error file ...
    This option enables you to view or edit the error file specified for the selected service. If the service is currently running, then the file will be in use; therefore, a snapshot of the file is taken, and it this copy that is displayed. The file is opened in Notepad, where you can view, edit, and save it, as required.
    Note: Whilst using either of these options, the control panel is in a 'wait' state, and you need to close Notepad before continuing to use the control panel.
Parent topic: AcuToWeb Enhancements
Related reference
AcuToWeb Control Panel


ECN-AW056 fillcombo.js file location now configurable

RPI: 628360

Product: AcuToWeb

Module: AcuToWeb

Machines Affected: all

DESCRIPTION:

The contents of the drop list available on the Alias field of the Connection Setup screen is configurable using the fillcombo.js file. The location (on the AcuToWeb server) of this file can now be configured using the PATH_FILL_COMBO configuration variable. This variable should be specified in your AcuToWeb Gateway configuration file:

PATH_FILL_COMBO C:\path\to\fillcombo.js

Parent topic: AcuToWeb Enhancements


ECN-AW073 Navigating AcuToWeb on mobile devices

RPI: 628692

Product: AcuToWeb

Module: AcuToWeb

Machines Affected: all

DESCRIPTION:

To enable existing desktop applications to run on mobile devices usually requires a certain amount of redesign and redevelopment, and often results in a mobile version of the application being produced. One of the main reason that a redesign is required is for navigational issues - if your application relies on extended keyboard functionality such as function keys, the ability to use these keys is often lost unless the program is rewritten to accommodate them on a mobile device.

With AcuToWeb, you can enable a mobile virtual keyboard, which provides extended keyboard functionality such as function keys and navigational keys, by displaying additional icons along the top of your application. This should compliment the alphanumeric virtual keyboard that your mobile device already provides.

You enable the mobile virtual keyboard using the Show Mobile Virtual Keyboard option on the Connection Setup screen.

Note: This option is enabled by default; however, if you are running on a non-mobile device, this option will have no effect.

Parent topic: AcuToWeb Enhancements
Related reference
Using AcuToWeb on a Mobile Device


ECN-AW080 Message Box buttons now display using OS language

RPI: 1109208

Product: AcuToWeb

Module: AcuToWeb

Machines Affected: all

DESCRIPTION:

Type 4 message boxes now display using the default language of the operating system.

Parent topic: AcuToWeb Enhancements


ECN-AW081 Additional W$BITMAP support added

Product: AcuToWeb

Module: AcuToWeb

Machines Affected: all

DESCRIPTION:

AcuToWeb now supports the following operations of W$BITMAP:

  • WBITMAP-CAPTURE-IMAGE
  • WBITMAP-CAPTURE-DESKTOP
Parent topic: AcuToWeb Enhancements
Related reference
W$BITMAP


AcuXDBC Enhancements

This section includes the enhancements related to AcuXDBC.

  • ECN-XD113 Hexadecimal literals in a WHERE clause containing a binary field
  • ECN-XD114 Wildcards now support forward slashes when connecting to a Windows Server
Parent topic: What's New


ECN-XD113 Hexadecimal literals in a WHERE clause containing a binary field

RPI: 631197

Product: AcuXDBC

Module: AcuXDBC

Machines Affected: all

DESCRIPTION:

In a query, you can now use a WHERE clause containing a field that is specified as $xfd BINARY; for example:

SELECT some_binary_field FROM
       public.table WHERE some_binary_field = 0xFFFE2020
Parent topic: AcuXDBC Enhancements


ECN-XD114 Wildcards now support forward slashes when connecting to a Windows Server

RPI: 1112306

Product: AcuXDBC

Module: AcuXDBC

Machines Affected: all

DESCRIPTION:

When using wildcards to resolve a DSN, forward slashes in the wildcard string are now working correctly when attempting to access a mapped drive on a Windows server.

Parent topic: AcuXDBC Enhancements


extend System Requirements

Note: This product includes software developed by the University of California, Berkeley and its contributors.

Hardware Requirements

extend software has the following requirements:

For Windows:

  • The amount of disk space needed to install the ACUCOBOL-GT development system is typically less than 35 MB.
  • AcuBench® requires at least 20 MB for installation.
  • You need an additional 40 MB to install all of the other extend products.
  • Use of .NET controls with the runtime and thin client requires .NET Framework 4.0.
For all other platforms:
  • The amount of disk space needed to install all extend products is typically less than 35 MB.

Supported Operating Systems

Note: AcuBench no longer supports Windows XP or Windows Server 2003 (or any Windows platforms that pre-date these). This is because AcuBench utilizes a number of third-party libraries that have ceased to be supported on those platforms.

For this release, if you are running on the AIX 7.1 platform, the minimum requirement is version 7.1 Technology Level 4 (7100-04).

For a full list of the supported operating systems, check the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx.

Additional Requirements

General requirements

Linux-based platforms require glibc version 2.5 or later.

AcuServer:

  • Each server machine must be networked to UNIX, Linux, or Windows clients with TCP/IP. TCP/IP is not sold or supplied by Micro Focus.
  • All servers must have a copy of the AcuServer license management file.
  • Windows clients can run any TCP/IP software that uses a WINSOCK2 compliant ws2_32.dll.
  • Unless you have an unlimited license for AcuServer, all UNIX servers must run the current version of acushare, which is included on the AcuServer distribution media.
  • All servers must have a copy of the license file activated by the product installation script. This file is named acuserve.alc.
  • Client machines must have an ACUCOBOL-GT AcuServer-enabled runtime. All Windows runtimes Version 5.0 and later are AcuServer-enabled. To verify that your UNIX runtime is AcuServer-enabled, type runcbl -v in a Command prompt and look for this line.
    AcuServer client
  • Servers being accessed by the ACUCOBOL-GT Web runtime must have a multiple-user ACUCOBOL-GT runtime license that accommodates each concurrent user that is anticipated. (If you anticipate 100 concurrent users of the Web runtime, you need a 100-user runtime license on the server in addition to the AcuServer license file. Alternatively, runtime users can install a local or network floating license for the runtime themselves.

AcuBench:

  • Intel Pentium III CPU, 300 MHz; Intel Pentium IV, 2 GHz recommended
  • 128 MB of RAM recommended
  • 120 MB of available hard disk space recommended
  • mouse
  • 800 x 600 VGA display or better; 1024 x 768 VGA display recommended
Note: On Windows 7, if you receive the following error when starting AcuBench, you need to manually install the KB2999226 (Universal CRT) Windows update from the Microsoft Download Center:
api-ms-win-crt-runtime-l1-1-0.dll is missing

AcuToWeb

AIX and Solaris platforms require the Foreign Function Interface Library (libffi) is installed. More information and the installation packages can be found at the following:

AIX platforms: You can download an RPM package from:

http://www.bullfreeware.com/affichage.php?id=3638

And then install it using:

rpm -Uvh http://www.bullfreeware.com/download/bin/3638/libffi-20170516-1.aix6.1.ppc.rpm

Solaris platforms: You can download the package from:

https://www.opencsw.org/packages/libffi6/

General information on libffi can be found at:

https://cffi.readthedocs.io/en/latest/installation.html

If you are running on the Solaris 11 platform, the minimum version required to run the AcuToWeb Gateway is version 11.3.

AcuSQL:

  • Your COBOL application must run on a Windows system or a UNIX system supported by Micro Focus. Unless otherwise indicated, the references to Windows in this manual denote supported Windows operating systems. Where necessary, individual versions of those operating systems are referred to by their specific version numbers.
  • AcuSQL must be installed with the ACUCOBOL-GT development system on your Windows or UNIX system.
  • If using a database other than Microsoft SQL Server, you must have a working ODBC level 2 API connection to your database, including any required networking software support.
  • For SQL Server, if running the AcuSQL interface to Microsoft SQL Server, you must have the SQL Server client software from Microsoft. Use the Query Analyzer to see if the SQL Server client software from Microsoft is on your system. For information on opening the Query Analyzer, see the SQL Server client documentation. If the Query Analyzer opens and you are able to connect to the database, the client libraries are most likely all present. Your SQL Server data source may be hosted on one or more of the supported server operating systems.
  • If you are running the AcuSQL interface to MySQL, you must have the following software:
    • MySQL 5.0 Database Server Version 5.0.18 or later (Generally Available release). Testing was done with MySQL 5.0.18 Standard.
    • MySQL Connector/ODBC Version 3.51.11 or later (Generally Available release). Testing was done with the libmyodbc3-3.51.12.so library. This file is available from http://dev.mysql.com.
    You can check the version of your server by connecting using mysql. The version prints upon connection. For example:
    [testing ]: mysql
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 29 to server version:
5.0.18-standard
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
    Once in MySQL, you can also use the following:
    mysql> select version();
+-----------------+
| version()       |
+-----------------+
| 5.0.18-standard |
+-----------------+
1 row in set (0.09 sec)
  • If your application accesses DB2 data, IBM's DB2 Connect™ software is recommended. Access to DB2 databases has been tested with DB2 Connect. However, any vendor's properly configured ODBC level 2 API connectivity software should work. Your DB2 data source may be hosted on one (or more) of the supported operating systems.

Acu4GL (for ODBC) driver requirements:

Your ODBC driver must include the following functions:

  • all Core ODBC driver functions
  • the Level 1 function SQLColumns
  • the Level 1 function SQLTables

Depending on the method of record locking you choose, your driver may also need to support some of the following function calls:

  • SQLSetStmtOption
  • SQLSetScrollOptions
  • SQLExtendedFetch
  • SQLSetPos

See A_ODBC_LOCK_METHOD in the extend online help for more information.

To test the capabilities of your ODBC driver, we have included a driver test program on your Acu4GL for ODBC installation disks. You can also consult your driver documentation to ensure that it meets these requirements.

Parent topic: Product Information


Windows Installation

  • License Files for Windows
  • Installation on Windows Platforms
  • Launching extend Products on Windows 8 or Later
  • Compiling Your Programs
  • Running Your Programs
  • Printing and Spooler Issues
Parent topic: Product Information


License Files for Windows

You may request a license file for one or more users. The number of users (user limit) is set in your license agreement with Micro Focus.

When you receive your products, the package includes product codes and product keys for every product you ordered. You must have the product codes and product keys to create the license file.

When you install or update your license file, place it in the appropriate directory for your version of Windows. The location is:

C:\ProgramData\Micro Focus\extend\x.x.x\x86\product-license.alc

(Where x.x.x is the product version number.)

Note: This location is new to extend 9.0 and later, and differs from past versions of extend products. See Appendix C - Changes Affecting Previous Versions in the ACUCOBOL-GT Appendices manual for details.

When you have multiple users or products, you may copy the license file onto each machine containing the corresponding product or place the products and license file on a shared drive. Each product must be able to locate its license file in order to function.

Note: The ACUCOBOL-GT Transaction Server runtime license file is named wrun32.1lc. If you are using other extend products, the license files must be concatenated into a special file.
  • The Activator Utility
  • Changing or Updating a Windows License File
Parent topic: Windows Installation


The Activator Utility

The Activator Utility automates the process of creating a license file.

During installation, select Install License Activator on the Installation Settings page to install the Activator Utility (activator.exe). It is installed in the \AcuGT\bin sub-directory of the installation directory.

Note: Always use the version of the Activator supplied with the version of the product you have installed.

To create the required license files during installation, select Launch License Activator on the Installation Settings page. This will launch the Activator Utility when the selected products have installed, enabling you to enter the product code and key pairs required to create the license files.

You can also create license files after the installation by running the Activator Utility (activator.exe) from the location detailed above or from the Start menu.

During product installation, if the Activator detects the presence of an existing license file, the extension of the existing file is changed before a new license file is created. For example, runcbl.alc is renamed runcbl.al!. If the Activator is unable to rename the existing license file, it quits with an error message, and no new license file is created. If a license file with the back-up extension already exists, the Activator attempts to overwrite it. If that fails, the Activator quits with an error message and no new license file is created. On Windows platforms, file attributes such as Read Only are also preserved.

Parent topic: License Files for Windows
Related tasks
Installation Steps


Changing or Updating a Windows License File

If you need to alter your license file information, contact your Micro Focus extend representative for updated product code(s) and product key(s). When you receive them, launch the Activator and enter the new information as prompted.

Note: If you have copied a license file to a non-default directory, remember to replace that file with a copy of the updated license file.
Parent topic: License Files for Windows


Installation on Windows Platforms

The Windows installation requires little interaction; the setup program copies the files into a directory you designate, or C:\Program Files\Micro Focus\extend x.x.x (where x.x.x is the version number) by default. On 64-bit machines, 32-bit executables are installed to C:\Program Files (x86).

Before you run an installation, you should ensure that you have your product codes and product keys, and the product media to hand. Refer to the appropriate installation instructions below.

Also, you should ensure that you do not have another version of the extend Interoperability Suite referenced in the PATH system environment variable, as having more than one version specified may cause unexpected results.

After the installation is complete, if you have installed both the compiler and runtime, you can begin to compile and execute your COBOL programs. Basic compilation and execution techniques are described in Compiling Your Programs and Running Your Programs.

Note: If you move or delete any .dll files that have been installed, your products may not run as expected.

AcuBench and AcuXDBC™ must be installed locally (on the client). Server-side products such as AcuServer™, AcuXDBC™ Server and AcuConnect® are to be installed only on server machines.

  • Supported Windows Platforms
  • Installation Steps
  • Silent Installation
  • Windows 64-bit Installations
  • Notes on AcuConnect and AcuServer Installation
  • BIN-REDIST and REDIST Installation Directories
  • Uninstalling or Modifying Your Installation
Parent topic: Windows Installation


Supported Windows Platforms

For a full list of the supported operating systems, check the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx.

Parent topic: Installation on Windows Platforms
Related information
Installation Steps
Silent Installation
Windows 64-bit Installations
Notes on AcuConnect and AcuServer Installation
BIN-REDIST and REDIST Installation Directories
Uninstalling or Modifying Your Installation


Installation Steps

Attention: The installation is supplied in two formats: .exe and .msi. On the installation CD, the .exe is located in the top level folder, and the .msi is located in the msi folder. If you plan to install Xcentrisity Business Information Server, or start AcuServer or AcuConnect from the installer, you must run the installation with administrator privileges, from an account that is in the Administrator group.

If you install from the CD, it will automatically run the .exe version with administrator privileges. If you run the .msi, it does not automatically run with administrator privileges. To run the .msi with administrator privileges, click Start, and in the Search programs and files field, type cmd.exe, then in the list displayed, right-click cmd.exe and select Run as administrator: this opens a command prompt with administrator privileges, where you can run the install by typing the full path name of the .msi file.

Follow these steps to install your products.

  1. Insert the product CD, or use the provided link to download the installation package from the Micro Focus website.

    If you are using the CD, it runs the .exe version automatically.

  2. If the .exe version does not start automatically, or you are using the downloaded installation package, do one of the following:
    • Navigate to the CD drive, then double-click the .exe.
    • Navigate to the location of the downloaded file, then double-click it. (See the above note if you are running the .msi version.)

    The installation starts.

  3. On the Welcome page, click Next.
  4. On the End-User License Agreement page, select I accept the terms in the License Agreement, then click Next.

  5. On the Select Installation Folder page, click Browse and select installation directories for 32-bit and 64-bit (if applicable) products. Alternatively, you can accept the default location(s), then click Next.

    Restriction: If you specify a mapped drive, it must map to a local directory; remote mapped drives are not supported.
  6. On the Product Selection page, select the required products, then click Next.

    You must have product codes and keys to activate each product; however, you can install all products now, and activate those products for which you do not have a license at a later date. (Be aware that if you attempt to use products for which you do not have a license, you may receive error messages indicating that no license file is available.)

    Note: Ensure you select Documentation on this page to install and access the product user guides.
  7. On the Installation Settings page, select one or more of the following, then click Next:
    Select | To
    Install License Activator | Install a copy of the License Activator
    Launch License Activator | Launch the License Activator at the end of the installation process
    Start AcuServer | Start AcuServer as a service
    Start AcuConnect | Start AcuConnect as a service
    Note: Starting either AcuServer or AcuConnect as a service will only occur if you have run the .exe or .msi version of the installer with administrator privileges (see note above). If a previous version of either product is already running on its default port, an additional prompt is displayed, asking you if you want to shut down that service; you must answer Y if the new version of AcuServer or AcuConnect is to start - see Notes on AcuConnect and AcuServer Installation for more details.

    If you selected Launch License Activator on the Installation Settings page, the Activator Wizard appears.

  8. Type your first product code and key in the appropriate fields.

    The License Activator is case-insensitive and displays only uppercase characters. It also ignores embedded spaces and separating characters. Product codes and keys do not contain the letters "O" or "I".

    CAUTION:
    If you have a license for both the Windows runtime (wrun32.exe) and an Alternate Terminal Manager (ATM) runtime (run32.exe) for the same machine, be aware that the Activator Utility creates a license file named wrun32.alc for each of them. To avoid a situation in which the Activator Utility overwrites the license file for the second runtime:
    • Make a backup copy of the Windows runtime license file prior to creating (and renaming) the ATM runtime license.
    • Create the ATM runtime license and rename it to match the executable (change wrun32.alc to run32.alc) before creating the Windows runtime license.
  9. If you have more than one code and key pair to enter, select More after typing the first code/key pair. Repeat this process until you have entered all code and key pairs, then click Finish.

    Each time you press More, the License Activator creates a separate license file for the product code and key you entered and returns you to the code and key entry screen.

  10. Click Finish on the Installation Complete page to complete the installation.
Note: If license activation was successful, but you get a message during product startup indicating that the license file cannot be found, the license file may not be in the correct directory. The License Activator determines where to place the license file based on entries in the Windows registry. If no registry entry is found, the license file is placed in the same directory as the License Activator executable file, which is the \AcuGT\bin sub-directory of the default installation directory. If this is not the location of the product's executable file, move the license file to the directory containing the corresponding executable file; for example, move wrun32.alc to the directory containing wrun32.exe.
Parent topic: Installation on Windows Platforms
Related reference
Getting Started
License Management
The Activator Utility
Notes on AcuConnect and AcuServer Installation
Related information
Supported Windows Platforms
Silent Installation
Windows 64-bit Installations
Notes on AcuConnect and AcuServer Installation
BIN-REDIST and REDIST Installation Directories
Uninstalling or Modifying Your Installation


Silent Installation

On Windows platforms, you can perform a silent installation of the extend Interoperability Suite using the msiexec command, which requires that you use the .msi install package that is shipped with your product.

The syntax required is:

msiexec /i <msi-file> INSTALLDIR=<install-directory> [INSTALLDIR64=<64-bit-install-directory>] ADDLOCAL=<product1,product2,...> [WINDOWSVERSION=<Win-version>] /qn [/L*v <log-file>]

where:

<msi-file>
The .msi installation file. This could be a 32-bit or a 64-bit version.
<install-directory>
The directory in which the product will be installed.
Restriction: If you specify a mapped drive, it must map to a local directory; remote mapped drives are not supported.
<64-bit-install-directory>
The directory in which the 64-bit products will be installed. This is mandatory if you are using the 64-bit installer, because it installs both 32-bit and 64-bit versions of some products, using <install-directory> for the 32-bit versions and <64-bit-install-directory> for the 64-bit versions.
Restriction: If you specify a mapped drive, it must map to a local directory; remote mapped drives are not supported.
<product1,product2,...>
A list of products and services to be installed; see Product Variables for Silent Installation for the comprehensive list of options.
<Win-version>
This is required for Windows versions 8 and later, in order to create the Extend Start menu. The only permissible value for <Win-version> is PostWindows7.
<log-file>
The path and file name of a log file in which to log the installation details.

Examples

32-bit installation:

For example, the following command silently installs the ACUCOBOL-GT runtime, Acu4GL for MSSQL, and the AcuSQL runtime to the C:\AcuInstallDir directory, and (on Windows 8 and later) also creates the extend start menu in the Windows program list:

msiexec /i "extend(R) Version 10.2.0 x86.msi" INSTALLDIR=C:\AcuInstallDir ADDLOCAL=Runtime,Acu4GLMSSQL,AcuSQLRuntime WINDOWSVERSION=PostWindows7 /qn

64-bit installation:

For example, the following command silently installs the ACUCOBOL-GT runtime, Acu4GL for MSSQL, and the AcuSQL runtime to the C:\AcuInstallDir directory, and the 64-bit runtime, Acu4GL for MSSQL, and AcuSQL runtime to the C:\AcuInstallDir64 directory:

msiexec /i "extend(R) Version 10.2.0 x64.msi" INSTALLDIR=C:\AcuInstallDir INSTALLDIR64=C:\AcuInstallDir64 ADDLOCAL=Runtime,Runtime64,Acu4GLMSSQL,Acu4GLMSSQL64,AcuSQLRuntime,AcuSQLRuntime64  /qn

Comments

You can also use the msiexec command to run the installation with a user interface: omit the ADDLOCAL parameter and substitute /qn for /qf.

You can also use the msiexec command to install the thin client .msi file that is supplied with your product: omit the ADDLOCAL parameter.

  • Product Variables for Silent Installation
Parent topic: Installation on Windows Platforms
Related information
Supported Windows Platforms
Installation Steps
Windows 64-bit Installations
Notes on AcuConnect and AcuServer Installation
BIN-REDIST and REDIST Installation Directories
Uninstalling or Modifying Your Installation


Product Variables for Silent Installation

The following table contains a list of possible arguments that you can use with ADDLOCAL when running a silent installation. Most argument names are self-explanatory; the Notes column explains those that are not.
Argument name | Notes
Acu4GLDB2 |
Acu4GLMSSQL |
Acu4GLMSSQL64 |
Acu4GLODBC |
Acu4GLODBC64 |
Acu4GLOracle |
Acu4GLOracle64 |
AcuBench |
AcuConnect |
AcuConnect64 |
AcuConnectDistributedProcessing |
AcuConnectThinClient |
AcuServer |
AcuServer64 |
AcuSQLPrecompiler |
AcuSQLPrecompiler64 |
AcuSQLRuntime |
AcuSQLRuntime64 |
AcuToWeb |
AcuXDBC |
AcuXDBC64 |
AcuXDBCEnterpriseEdition | The 32-bit and the 64-bit versions of AcuXDBCEnterpriseEdition are mutually exclusive; you may only specify one of these versions during the installation.
AcuXDBCEnterpriseEdition64 |
AcuxdbcsBat |
AcuxdbcsBat64 |
AcuXDBCServer | The 32-bit and the 64-bit versions of AcuXDBCServer are mutually exclusive; you may only specify one of these versions during the installation.
AcuXDBCServer64 |
BIS |
Compiler |
DevSys | The ACUCOBOL-GT Development System, which includes the following: Compiler, Runtime, WebRuntime, ThinClient, and WebThinClient.
ExtendStartMenu | The entry shown on the Windows program menu for Windows versions 8 and later. The 32-bit and the 64-bit versions of ExtendStartMenu are mutually exclusive; you may only specify one of these versions during the installation.
ExtendStartMenu64 |
LicenseActivator |
LicenseActivator64 |
OnlineDocumentationCHM |
Runtime |
Runtime64 |
ThinClient |
VCRedist | Installs the Microsoft redistributable files, required by the extend products, if they are not already installed.
VortexJar | Required for AcuXDBCEE. The enterprise edition of AcuXDBC needs the vortex.jar file, which enables a Java client application to connect to your Vision database.
VortexJar64 |
WebRuntime |
WebThinClient |

Examples

32-bit installation:

For example, the following command silently installs the ACUCOBOL-GT runtime, Acu4GL for MSSQL, and the AcuSQL runtime to the C:\AcuInstallDir directory, and (on Windows 8 and later) also creates the extend start menu in the Windows program list:

msiexec /i "extend(R) Version 10.2.0 x86.msi" INSTALLDIR=C:\AcuInstallDir ADDLOCAL=Runtime,Acu4GLMSSQL,AcuSQLRuntime WINDOWSVERSION=PostWindows7 /qn

64-bit installation:

For example, the following command silently installs the ACUCOBOL-GT runtime, Acu4GL for MSSQL, and the AcuSQL runtime to the C:\AcuInstallDir directory, and the 64-bit runtime, Acu4GL for MSSQL, and AcuSQL runtime to the C:\AcuInstallDir64 directory:

msiexec /i "extend(R) Version 10.2.0 x64.msi" INSTALLDIR=C:\AcuInstallDir INSTALLDIR64=C:\AcuInstallDir64 ADDLOCAL=Runtime,Runtime64,Acu4GLMSSQL,Acu4GLMSSQL64,AcuSQLRuntime,AcuSQLRuntime64  /qn
Parent topic: Silent Installation


Windows 64-bit Installations

There are 64-bit versions of most extend products. These 64-bit versions are installed using a separate 64-bit version of the installer. The installation process follows the same steps as described in Installation on Windows Platforms, with the following notable exceptions.

When running the 64-bit installer, if no 64-bit version exists for a selected product (for example, AcuBench), the 32-bit version is installed.

Products such as AcuConnect and AcuServer have 32-bit and 64-bit versions, and both are installed if you select these products during installation. You can also decide which version of the product to start on completion of the installation.

The AcuXDBC product is broken down into three installations: for the Data Interface, you can install both the 32-bit and 64-bit versions; and for the AcuXDBC Server and Enterprise Edition, you must chose which version to install.

By default, all 64-bit product versions are installed in the Program Files directory, and 32-bit product versions (and any supporting non-64-bit tools) are installed in the Program Files (x86) directory; although, you can change these locations during the installation. All the 32-bit versions are fully supported and functional in a 64-bit environment.

Remember: When running the license activator after the installation, the 64-bit version of the Activator utility is run, which installs license files into both the 32-bit and 64-bit directories. When running the Activator utility from the command prompt, make sure you are using the 64-bit command prompt to ensure the correct licenses are generated and placed in the correct locations; otherwise, if the 32-bit Activator utility is run, only license files for 32-bit products will be generated.
Parent topic: Installation on Windows Platforms
Related information
Supported Windows Platforms
Installation Steps
Silent Installation
Notes on AcuConnect and AcuServer Installation
BIN-REDIST and REDIST Installation Directories
Uninstalling or Modifying Your Installation


Notes on AcuConnect and AcuServer Installation

During the installation process, if you are installing AcuConnect or AcuServer, you can choose to automatically start those services as part of the installation process.

Those services can only be started if certain conditions are met. For example, the services will attempt to start on a default port (AcuConnect 5632, AcuServer 6523). If an existing installation is already using that port, that service must be stopped if the installation is to create and run the new service. If you do not stop the existing service, the installation can only create the new service; it cannot run it.

If there is no previous installation, a default AcuAccess file is only created (in its default location of C:\etc) when the service starts. If you configure the installation to not start the service, no AcuAccess file will exist until you start the products from their respective control panels (or command line equivalents). If a previous installation exists, the AcuAccess file already located in C:\etc is used.

Note: This file and directory are not removed when you uninstall a previous product.
Parent topic: Installation on Windows Platforms
Related tasks
Installation Steps
Related information
Supported Windows Platforms
Installation Steps
Silent Installation
Windows 64-bit Installations
BIN-REDIST and REDIST Installation Directories
Uninstalling or Modifying Your Installation


BIN-REDIST and REDIST Installation Directories

The extend Windows distribution contains two directories: BIN-REDIST and REDIST.

REDIST contains thin client files that should be distributed along with the thin client.

BIN-REDIST contains Microsoft Redistributable files. These files are required in cases where the ACUCOBOL-GT bin directory and runtime are placed on a shared drive and users then map to that drive. The BIN-REDIST directory should be placed inside the shared bin directory.

Parent topic: Installation on Windows Platforms
Related information
Supported Windows Platforms
Installation Steps
Silent Installation
Windows 64-bit Installations
Notes on AcuConnect and AcuServer Installation
Uninstalling or Modifying Your Installation


Uninstalling or Modifying Your Installation

You can uninstall or amend your current installation in one of two ways: you can run the installer again, or use the Programs and Features section in Windows. Both enable you to run the Installation Wizard, where you can perform the following program maintenance:

Change
Enables you to add or remove products to and from your current installation. Any products that were already checked that you uncheck are uninstalled. Any additions are installed using the default installation path (C:\Program Files\Micro Focus\extend x.x.x - where x.x.x is the version number). There is no option to change to a non-default location, but you can overcome this with some products by copying the installed files from the default location to your preferred location. Note that this method will not work for AcuXDBC, AcuBench, and any server products that are registered as services.
Repair
Enables you to reinstall the currently installed products.
Remove
Enables you to remove all products of your installation.

Parent topic: Installation on Windows Platforms
Related information
Supported Windows Platforms
Installation Steps
Silent Installation
Windows 64-bit Installations
Notes on AcuConnect and AcuServer Installation
BIN-REDIST and REDIST Installation Directories


Launching extend Products on Windows 8 or Later

Since the introduction of Windows 8, the Windows program menu does not display programs in a hierarchical way. For the extend Interoperability Suite, this would mean that all the programs relating to AcuBench, ACUCOBOL-GT, AcuConnect, etc... would be displayed as a flat list, and it would be difficult to distinguish which programs were related to which products.

In order to show the programs grouped within the products they belong to, the extend Start Menu has been introduced. After installation of the extend Interoperability Suite, there will be one entry in the Windows programs menu - extend x.x.x Start Menu (where x.x.x is the version number of the installed product):

Launch this application to display a hierarchy that looks similar to the Windows program menus prior to Windows 8. Simply navigate the folders displayed in the left-hand pane to display shortcuts to the related programs in the right-hand pane. Select the required shortcut: at which point, the extend Start Menu closes and the program is launched.

Parent topic: Windows Installation


Compiling Your Programs

The ACUCOBOL-GT compiler is most easily used via AcuBench. However, it is also possible to compile from the command prompt or the Windows Start menu, to establish an association between your source files and the compiler executable, or to set up one or more icons to compile individual files. For information regarding creating file associations and setting up icons, see your Windows documentation.

When you compile, if the system returns "Bad command or file name," you did not add the location of the compiler to the PATH environment variable, or you have not rebooted since installing the software.

You can check the current definition of PATH by typing path and pressing Enter at the command prompt. The default path is C:\Program Files\Micro Focus\extend x.x.x\AcuGT\bin (or c:\Program Files (x86)\... for 64-bit installations). If you do not update PATH with this entry, you must type the full path and program name to the compiler each time you compile; alternatively, you can create a .bat file.

Once you have verified that the compiler is in your PATH (or you have decided that you will specify the full path every time you compile), you are ready to compile your programs. Refer to ACUCOBOL-GT User's Guide > Compiler and Runtime > Using the Compiler for a complete list of compile options. You can also display a complete list of options by running the compiler command:

ccbl32 -help

One commonly used option is -o. This option is used to specify the name of the output object file. Note that ACUCOBOL-GT uses the naming convention .acu to indicate an ACUCOBOL-GT object file. If -o is not used, the compiler will name the file source-name.acu. If your source includes COPY files, you can copy the COPY files to your current working directory, specify their location with the -Sp option followed by the complete path of one or more directories, or set the COPYPATH environment variable. A typical compilation command might look like:

ccbl32 -Sp c:\work\lib -o sample.cbx sample.cbl
Parent topic: Windows Installation


Running Your Programs

After a successful compilation, the resultant object file is ready for immediate execution (no link step is required). To run your program, make a note of the full path to your object file and return to the Windows desktop.

There are a variety of ways to run your program under Windows. The basic methods are:

  • Running a command from the Start menu.
  • Placing an icon for each program in a Program Group or folder, and then starting the program by double-clicking its icon.
  • Naming your COBOL object files with a common file extension and then associating the extension with the runtime. After the association is established, you can run a program by double-clicking on the name of the file as it appears in Windows.
  • Using the wrun32 (or crun32 if you are using the console runtime) command at the command prompt.

This document describes how to run a program from the Start menu only (although, the command line option is almost identical). The advantage of this method is that it requires no special setup. However, it is more time-consuming (than other methods) because you must type the command line options every time you execute the program. For greater convenience, it is best to set up a program icon: to do this, or to create a file association to the runtime, please refer to your Windows documentation.

  1. Click the Start button.
  2. On the Start menu, in the entry field, type the name of your ACUCOBOL-GT Windows runtime.

    The default name is wrun32.exe. If you changed the name of the runtime executable, enter that name.

  3. Following the name of the runtime, enter any runtime options required, followed by the path and name of the COBOL executable program you want to run.
  4. After you have entered the complete command line, press Enter to execute the program.
Note: If you did not add the \bin directory path to the PATH system environment variable (typically, that is: c:\Program Files\Micro Focus\extend xxx\AcuGT\bin), you will need to specify the full path to the runtime (c:\Program Files\Micro Focus\extend xxx\AcuGT\bin\wrun32.exe) each time in the command (and not simply wrun32.exe).

You can use the COBOL configuration variable DEFAULT_PROGRAM to specify the name of the program to execute when no program is specified on the command line. See Appendix H in the ACUCOBOL-GT documentation set for more configuration information.

Parent topic: Windows Installation


Printing and Spooler Issues

ACUCOBOL-GT includes extended support for printing under Windows. In addition to the basic print spooler access procedures described below, the WIN$PRINTER runtime library routine provides easy access to extended Windows print spooler capabilities. See the entry for "WIN$PRINTER" in ACUCOBOL-GT Appendices Guide > Appendix I. Rules for printer handling are illustrated in the ACUCOBOL-GT User's Guide > Compiler and Runtime > Filename Interpretation > Assigning Files to Printers.

Under Windows, you may print directly to the printer by defining PRINTER in the configuration file as "-D PRN". Be aware that this does not prevent other programs from printing at the same time and as a result you may get intermixed pages.

You may also print using the Windows spooler, even if your reports have embedded control codes. The spooler allows many programs to create print files at the same time, and also allows the user to do other tasks while the report is being printed.

Note: The configuration variable WIN_SPOOLER_PORT allows you to divert printer output to a file or port through the Windows print spooler. For more information, see ACUCOBOL-GT Appendices Guide > Appendix H of the ACUCOBOL-GT manual set.

Before you assign your print file to the Windows spooler, you must decide whether you want to control the format of each page directly (with embedded control codes) or whether you want the print spooler to format the pages.

  • Spooler Formatting
  • Direct Control
  • Printing Multiple Jobs Simultaneously
Parent topic: Windows Installation


Spooler Formatting

There are two ways to use the Windows spooler to format your print file: "-P SPOOLER" and "-Q <printername>". See Direct Control for information on controlling the formatting yourself.

  • -P SPOOLER
  • -Q <printername>
Parent topic: Printing and Spooler Issues


-P SPOOLER

If you want to use the default printer and font, simply assign your print file to "-P SPOOLER". For example, to assign "PRINTER1" to the spooler, enter the following line in your COBOL configuration file ("CBLCONFI"):

PRINTER1  -P  SPOOLER

By default, the runtime system assigns the "PRINTER" device to the spooler. You may change this in the configuration file by assigning "PRINTER" to some other name.

When the runtime opens a file assigned to "-P SPOOLER", it automatically initiates a job with the Windows spooler and constructs print pages in accordance with your program. The runtime uses the default printer and font. If the user looks for the job in the spooler, it is named with the current title of the ACUCOBOL-GT window.

Note:

The Windows spooler operates by drawing your report on each page. It constructs its own control codes to handle formatting. If you assign your print file to "-P SPOOLER" and your file contains device-dependent control sequences (such as those used to shift to a condensed font, or to print a form and then fill it in), the codes will be passed to the spooler as data and thus will not be interpreted correctly. If you have reports that depend on embedded control codes, you should print those directly to the device, or assign the print file to "-P SPOOLER-DIRECT," as described below.

Parent topic: Spooler Formatting


-Q <printername>

If you want the Windows spooler to format the pages of your report, but you want to use a particular printer, assign your print file to:

PRINTER1 -Q \\printername

in the configuration file (CBLCONFI). Printername is the printer designation as given in the Devices and Printers screen. The name may be up to 80 characters long and contain embedded spaces. The name may not include the semicolon character (;) or be surrounded by single or double quotes. The pages are printed in the manner described in "-P SPOOLER", above. The sample programs graphprn.cbl and prndemox.cbl contain examples of these functions.

To determine a valid printer name, use the WIN$PRINTER library routine to obtain the name of the desired printer. (This is described in Appendix I under the WINPRINT-SET-PRINTER operation code in "Specifying a Printer".) Then add the following line to your code:

MOVE "-Q \\printername" TO WS-PRINTER-NAME.

When the runtime opens a file assigned to "-Q <printername>", it sets the Windows print spooler to use this printer. The printer driver must be installed on the computer from which you print. If printername is not recognized by the runtime, a dialog box allows you to choose a printer manually.

Note:

If you want to access a printer using a UNC path, you have to print directly to the printer by defining PRINTER as "-D PRN". If you use the UNC path, Windows formatting is not supported.

Parent topic: Spooler Formatting


Direct Control

If you want to control the format of the printout yourself using embedded control codes, simply assign your print file to -P SPOOLER-DIRECT or to -Q <printername> using the DIRECT=ON option. For example, to assign the print job "PRINTER1" to the spooler and retain direct control over formatting, enter the following line in your COBOL configuration file (CBLCONFI):

PRINTER1  -P  SPOOLER-DIRECT

Or, use the following command to assign PRINTER1 to the spooler for printing to a specific printer while retaining direct formatting control:

PRINTER1 -Q printername;DIRECT=ON

Both of these methods cause the print job to be sent to the printer via the Windows spooler, but the program does not use the spooler to format the pages. You must use embedded control codes to handle formatting (much as you would under UNIX if you used the UNIX spooler).

When using the -P SPOOLER-DIRECT option, you may use the WIN$PRINTER library routine to choose a printer, but because you completely control the printer, the various options provided by WIN$PRINTER are ignored. For example, WIN$PRINTER does not set the page size, page orientation, or font. Information returned from WIN$PRINTER, such as number of lines and columns on the page, may not be accurate and should not be used. This subject is discussed in detail in Appendix I "Library Routines" of the ACUCOBOL-GT manual set.

Because some print drivers do not flush the last page, be sure to end your last page with a form-feed (for example, WRITE ... BEFORE ADVANCING PAGE). This ensures that all pages are printed. The ACUCOBOL-GT runtime ensures that no extra blank pages are printed at the end.

If you code WRITE...AFTER ADVANCING PAGE instead of WRITE...BEFORE ADVANCING PAGE, you might receive a blank last page. This is because a blank line written on the new page causes the Windows subsystem to flush the page for some print drivers. ACUCOBOL-GT ensures that entirely empty lines are not sent to the device (only the form-feed will be sent). But it is essential that:

  • You have specified trailing space removal in your COBOL code (the default for print files).
  • You have set the configuration option MIN-REC-SIZE to "0".

Your other option is to specify WRITE... BEFORE ADVANCING PAGE to avoid this potential problem.

If the user looks for the job in the spooler, it is named with the current title of the ACUCOBOL-GT window.

Parent topic: Printing and Spooler Issues


Printing Multiple Jobs Simultaneously

If you need to print multiple jobs at the same time, you must open multiple File Descriptors that point to "-P SPOOLER" or "-P SPOOLER-DIRECT" simultaneously. For example, you may have two simultaneous print jobs:

SELECT FIRST-FILE
       ASSIGN TO PRINTER "-P SPOOLER".

SELECT SECOND-FILE
       ASSIGN TO PRINTER "-P SPOOLER".

..PROCEDURE DIVISION.

..

       OPEN OUTPUT FIRST-FILE.
       OPEN OUTPUT SECOND-FILE.

and both will print to the default Windows printer without interfering with each other. You can call WIN$PRINTER USING WINPRINT-SETUP before one or both of the OPEN statements. Each file may have individual file status variables or may refer to a common file status variable.

This does not mean that you can open a single File Descriptor multiple times. For example, the following will return file status indicating that the file is already opened:

SELECT FIRST-FILE
       ASSIGN TO PRINTER "-P SPOOLER".

..

PROCEDURE DIVISION.

..

       OPEN OUTPUT FIRST-FILE.
       OPEN OUTPUT FIRST-FILE.

This is normal behavior and is consistent with the way file handling is implemented in COBOL and in other programming languages.

If you are using only the verbs OPEN, CLOSE, and WRITE, no further changes to your code are needed. If you are using WIN$PRINTER functionality (other than WINPRINT-SETUP) you will need to specify which print job is affected. This can be done in two ways:

  1. The simplest way is to execute the WIN$PRINT operation immediately after an OPEN or WRITE statement on the intended job. Every execution of OPEN and WRITE sets the current job as the default so that subsequent activity using WIN$PRINTER is automatically directed to the job that was last accessed with an OPEN or WRITE statement.

    In this situation, if you have multiple jobs running, and you close one of them, the runtime switches to the next job in the list. For example, if you are printing jobs 1, 2, and 3, and you close job 2, the close command sets the current job to 3. If there is no job 3, the runtime attempts to set to the job that preceded the closed job (which in this case is job 1). If there are no jobs, the current job is initialized.

  2. The other method is to use the WINPRINT-SET-JOB operation of the WIN$PRINTER library routine. This operation is described in Appendix I of the ACUCOBOL-GT manual set.
Parent topic: Printing and Spooler Issues


UNIX Installation

  • License Files for UNIX
  • Installation Under UNIX
Parent topic: Product Information


License Files for UNIX

UNIX users may request a license file for one or more users.

When you receive your product(s), the package includes product codes and product keys for every product you ordered. You require theses product codes and product keys to create license files.

  • The Activator Utility
  • Changing or Updating Your UNIX License Files
Parent topic: UNIX Installation


The Activator Utility

The Activator utility automates the process of creating a license file. On UNIX platforms, the Activator utility operates through a command-line interface.

By default, the Activator utility program (activator) is placed in the same directory as the runtime and other binary executable files.

If you did not install the Activator utility with your other products, simply copy the file onto your computer and run it as you would any other executable.

Parent topic: License Files for UNIX


Changing or Updating Your UNIX License Files

If you need to alter a license file, contact your Micro Focus extend representative for updated product codes and product keys. When you receive them, launch the Activator utility and enter the new product codes and product keys as prompted.

Parent topic: License Files for UNIX


Installation Under UNIX

To install extend products on UNIX or Linux systems, you must have the product media, and the product codes and product keys for the products you intend to install. Your products are delivered via FTP.

  • Installation Process
  • SHARED_LIBRARY_PREFIX Configuration Variable
Parent topic: UNIX Installation


Installation Process

  1. Download the product from the Micro Focus SupportLine site.
    Note: Before running the installer, ensure that the tar utility in on your PATH.
  2. Enter the following:
    /path/to/installer/installer-name [options]

    where installer-name will be something similar to setup_acucob1010pmk59shACU.

    The following options can be included:

    Option | Description
    -d installation-path Specifies a new default install location offered during the installation. If not specified, the default location is the current working directory (.). Any specified directory must already exist.

    This option can be combined with the -EULA option, but if it is, it will specify the location of the extracted EULA, and not the location of the installed product.

    -EULA | Extracts the EULA, in .htm format, to a location of your choosing. The product installation will not continue when using this option.
    -help | Displays the available options that can be appended to the installation command.
    Note: If you install ACUCOBOL-GT as a shared object library and you don't install to the default location, you need to set an appropriate library path variable specifying the location of the shared objects. For example, on an AIX system, you would need to set the LIBPATH environment variable. Note that if you log in as root or a superuser, this variable must also be set in root's environment for ACUCOBOL-GT to start. Additionally, see SHARED_LIBRARY_PREFIX configuration variable.

    After installation, you must use the Activator utility to license the products installed.

  3. From the installation directory, enter the following command to run the Activator utility:
    ./bin/activator
  4. At the prompt, type the product code and product key pairs that came with your product package, pressing Enter after each pair: this updates the license file. Repeat this cycle until the code/key pairs for each product you have ordered are entered.
    Note: Each product searches for its license file in the same directory in which its executable resides. If you move the product's executable to a new directory, you must move its license file to the same location.
  5. To start the acushare license manager service, enter the following:
    acushare -start
  6. Navigate to the sample sub-directory of your installation directory and try compiling and running the tour program, using the following commands:
    ccbl tour.cbl
runcbl tour.acu
  7. If you get the message Can't find entry for 'terminal' in 'term-lib", you need to configure your terminal for ACUCOBOL-GT. See Configuring Your Terminals.
  8. Once you have the sample program running, we recommend that you edit the cblconfig file supplied with ACUCOBOL-GT to meet the needs of your site. In particular, you should configure it to support the printers you have attached to your system.
  9. If you are using shared memory, see the instructions for configuring acushare in ACUCOBOL-GT User's Guide > Runtime Manual > Shared Memory > Acushare Utility Program.
Parent topic: Installation Under UNIX


SHARED_LIBRARY_PREFIX Configuration Variable

If you install ACUCOBOL-GT as a shared object library and you don't install to the default location, you need to set an appropriate library path variable (LIBPATH or LD_LIBRARY_PATH) specifying the location of the shared objects. The SHARED_LIBRARY_PREFIX variable helps the runtime find libaclnt.so (or libaclnt.sl) in case the LIBPATH (or LD_LIBRARY_PATH) variable is not set. libclnt.so (or .sl) is needed for AcuServer and AcuConnect support.

If a shared library name is specified without any directory information and the system call fails to load the shared library, the runtime will try to load the shared library from each of the directories specified in the SHARED_LIBRARY_PREFIX configuration variable.

The default value for SHARED_LIBRARY_PREFIX is /opt/acucorp/xxx/lib: /opt/acu/lib. The format of the value of SHARED_LIBRARY_PREFIX is the same as FILE_PREFIX. You can set SHARED_LIBRARY_PREFIX in the configuration file or environment, or programatically with the SET verb. Note that the runtime searches for and loads libaclnt.so (or libaclnt.sl) using the default value of SHARED_LIBRARY_PREFIX. This happens before reading the configuration file, environment, or running any COBOL code.

You can set SHARED_LIBRARY_PREFIX to an empty value if you do not want to use it.

Also, if the license is for AcuTSL, in a transactional server environment such as CICS, the runtime will add /opt/acucorp/xxx/bin/runcbl.1lc and /opt/acu/bin/runcbl.1lc to its list of license files to check. First the runtime checks $ACUCOBOL/etc/license.acu, then /etc/license.acu. If neither exists, the runtime will check /opt/acucorp/xxx/bin/runcbl.1lc and finally /opt/acu/bin/runcbl.1lc.

For cases in which users install ACUCOBOL-GT in the default location, /opt/acucorp/xxx or /opt/acu, and they have a license file, runcbl.1lc in their bin directory, they will not need to copy the license to /etc/license.acu.

Parent topic: Installation Under UNIX


VMS and OpenVMS Installation

  • Before You Begin
  • License Files for VMS
  • Installation Steps
Parent topic: Product Information


Before You Begin

Products are shipped for OpenVMS on VAX machines in Saveset format (*.BCK). The software does not have to be installed on the system disk. However, to use it within an OpenVMS-Cluster, it is advisable to install it on a disk that is accessible from all nodes in the cluster.

We recommend creating a separate directory for each version similar to the structure shown below:

Recommended directory structure

Parent topic: VMS and OpenVMS Installation


License Files for VMS

You may request a license file for one or more users. Note that this is different from an OpenVMS License-PAK.

When you receive your products the package includes product codes and product keys for every product you have ordered. You must have the product codes and product keys to create the license file using the Activator utility.

  • The Activator Utility
  • Changing or Updating Your License File
Parent topic: VMS and OpenVMS Installation


The Activator Utility

The Activator utility operates as a command-line interface for adding new or updated product codes and product keys.

On VMS platforms, the Activator (activator.exe) is installed in the same directory as the runtime and other binary executable files by default.

Parent topic: License Files for VMS


Changing or Updating Your License File

If you need to alter your license file information, contact your Micro Focus extend representative for updated product codes and product keys. When you receive them, launch the Activator and enter the new information as prompted.

Parent topic: License Files for VMS


Installation Steps

You need product codes, product keys, and the product media available to perform the installation. The installation process involves three main steps: create directories, extract the files from the Saveset onto your machine, and then copy certain files to specific directories.

Perform these installation steps using the SYSTEM account:

  1. Create the directories in which you want your files to reside.

    These instructions use the directory structure shown in Before You Begin, and is referred to as "path".

  2. If the product files reside on a CD-ROM or tape, first make the media accessible for the system.

    For example, to extract the files from a CD-ROM in device DQA0:, insert the CD-ROM into drive DQA0:, then type the following commands:

    ALLOCATE DQA0:
MOUNT/NOASSIST/OVERRIDE=IDENTIFICATION DQA0:

    These commands reserve the device so that no other process can access it. If you misspelled the device specification, or if the device is already in use, you will get a corresponding message after a short while.

  3. Identify the directory in which the Saveset resides by entering the following command.

    You will need this information to extract the product files in the next step.

    DIRECTORY DQA0:[000000...]*.BCK

    The Saveset is called "COBOL.BCK" and typically resides in a directory called "[ACUCOBOL]". If you find more than one Saveset and you don't know which one to use, contact Micro Focus.

  4. Extract the files from the Saveset to the directory in which the files should be installed.

    For example:

    SET DEFAULT DKA100:[ACUCOBOL.800]

    Then enter the command:

    BACKUP/LOG DQA0:[ACUCOBOL]COBOL.BCK/SAVE_SET DKA100:[ACUCOBOL.800...]*

    Note that the two lines above are one command, and that the qualifier "/SAVE_SET" is always required when accessing Savesets on disks.

    After extracting the release files from the product media, read the "RELEASE" file if present. The RELEASE file contains changes to the compiler not covered in the documentation.

    If you copied the Saveset via FTP to your system, use the BACKUP command above, replacing the source specification with the name and path of your Saveset.

  5. Define symbols so that users can access the executables.

    Define one symbol each for the compiler, the runtime system, the object file utility, and the Vision file utility for every user who will use ACUCOBOL-GT. You also need to define a symbol for the Activator utility for the system administrator. If you are installing AcuConnect, define a symbol for that product as well. If you want to allow everyone to have access to an executable, you can place the command in the "SYS$MANAGER:SYLOGIN.COM". Otherwise, place it in the "LOGIN.COM" file for each user who requires access.

    Use the following commands to define these symbols:

    CCBL == "$disk:[directory]CCBL.EXE"
RUNCBL == "$disk:[directory]RUNCBL.EXE"
CBLUTIL == "$disk:[directory]CBLUTIL.EXE"
VIO == "$disk:[directory]VIO.EXE"
ACTIVATOR == "$disk:[directory]ACTIVATOR.EXE"
ACURCL == "$disk:[directory]ACURCL.EXE"

    Using the directory structure shown in Before You Begin, the first command would look like this:

    CCBL == "$DKA100:[ACUCOBOL.800.ACUROOT.BIN]CCBL.EXE"

    Log out and back in to get the ACUCOBOL symbols defined for you.

    Note: The use of the dollar sign indicates to VMS that these symbols represent executable programs.
  6. Copy the file "A_TERMS.DAT" to the SYS$LIBRARY directory.

    Make sure it has read and execute permission for everyone by using the following command:

    SET SECURITY/PROTECTION=(W:RE) SYS$LIBRARY:A_TERMS.DAT
  7. Copy the file "CBLHELP.DAT" to the SYS$HELP directory.

    Make sure it too has read and execute permission for everyone by using the following command:

    SET SECURITY/PROTECTION=(W:RE) SYS$HELP:CBLHELP.DAT
  8. Copy the file "A_CONFIG.DAT" to the SYS$LIBRARY directory.

    You may need to edit this file. In particular, you should configure it to support the printers you have attached to your system. The ACUCOBOL-GT User's Guide contains details about the configuration file.

  9. Change to the directory where your executables reside and start the License Activator by issuing the command:
    ACTIVATOR
  10. At the prompt, type the product code and product key that came with your product package. When you press Enter after typing in each code and key pair, the license file is created. Repeat this cycle until the code/key pairs for each product you have ordered are entered.
  11. Change your DEFAULT to the directory that contains the ACUCOBOL-GT sample programs. (For example: SET DEFAULT DKA100:[ACUCOBOL.800.ACUROOT.SAMPLE]).

    Then try compiling and running the "tour" demonstration program with the following commands:

    CCBL TOUR.CBL
RUNCBL TOUR
    Note: The compiler and runtime make use of the VAX shared library "vaxcrtl.exe". This file must be in the SYS$SHARE directory. Install this file as a shared image for multi-user performance.

    If you have a VT100-compatible terminal, you should be able to run this program. To make use of some of the more advanced features of your particular terminal (or if you do not have a VT100 compatible), configure your terminal as outlined in the ACUCOBOL-GT User's Guide > Terminal Manager.

  12. For AcuConnect, create a server access file and set user account quotas to define each user's capabilities.

    Refer to, AcuConnect User's Guide > The AcuConnect Server > Installing AcuConnect on an OpenVMS Server for information about these settings.

Parent topic: VMS and OpenVMS Installation


Known Errors and Restrictions

The known errors and restrictions covered here are those not covered elsewhere in the documentation, or are of a temporary nature and may be resolved in a later release.

  • An Entry-field border color property does not show up inside AcuBench when using the Screen Painter.
  • When using AcuBench to compile the custmrsql.cbl sample program, a memory access violation (MAV) occurs. The custmrsql.cbl sample has a hard coded path to a 9.0.0 copybook. Changing that path to your install path allows the program to compile correctly.
  • An underline appears on the first tab of a tab control when the color is set.
  • When the title position is set to bottom on a push button control with bitmaps, the push button appears trimmed in upper right corner. When the title position is set to bottom on a push button control with a bitmap, the top upper right portion of the bitmap appears white.
  • After a successful START TRANSACTION, the transaction-status is reported as 99, indicating that transaction management is not supported. Recent extend runtime installations include the RM/COBOL file handler (RMFM), which does not support transactions. If your program does not rely on the RM/COBOL file handler, you can safely remove it from the runtime by setting the RMFM-DETACH 1 configuration variable. Either with or without the inclusion of the RM/COBOL file handler, the Vision file handler will continue to process transactions as expected, but by removing RMFM, you will not receive the transaction-status 99.
Parent topic: Product Information
Related information
filesystem_DETACH


Micro Focus Services and Solutions

  • Contacting Micro Focus
  • Training
  • Consulting Services
Parent topic: Product Information


Contacting Micro Focus

Our Web site gives up-to-date details of contact numbers and addresses.

  • Further Information and Product Support
  • Information We Need
  • Contact information
  1. Handling Compilation Problems
  2. Handling Program Execution Problems
Parent topic: Micro Focus Services and Solutions
Parent topic: Introduction


Further Information and Product Support

Additional technical information or advice is available from several sources.

The product support pages contain a considerable amount of additional information, such as:

  • The Product Updates section of the Micro Focus SupportLine Web site, where you can download fixes and documentation updates.
  • The Examples and Utilities section of the Micro Focus SupportLine Web site, including demos and additional product documentation.
  • The Support Resources section of the Micro Focus SupportLine Web site, that includes troubleshooting guides and information about how to raise an incident.

To connect, enter http://www.microfocus.com in your browser to go to the Micro Focus home page, then click Support & Services > Support Resources > All Support Resources. In the Browse by Product field, click the product you require support for. Click Log into SupportLine.

Note: Some information may be available only to customers who have maintenance agreements.

If you obtained this product directly from Micro Focus, contact us as described on the Micro Focus Web site, www.microfocus.com. If you obtained the product from another source, such as an authorized distributor, contact them for help first. If they are unable to help, contact us.

Also, visit:

  • The Micro Focus Community Web site, where you can browse the Knowledge Base, read articles and blogs, find demonstration programs and examples, and discuss this product with other users and Micro Focus specialists.
  • The Micro Focus YouTube channel for videos related to your product.
Parent topic: Contacting Micro Focus
Related information
Micro Focus SupportLine
Examples and Utilities
Support Resources
Micro Focus Community
White Papers and Webcasts
Micro Focus YouTube Channel


Information We Need

However you contact us, please try to include the information below, if you have it. The more information you can give, the better Micro Focus SupportLine can help you. But if you don't know all the answers, or you think some are irrelevant to your problem, please give whatever information you have.

  • The name and version number of all products that you think might be causing a problem.
  • Your computer make and model.
  • Your operating system version number and details of any networking software you are using.
  • The amount of memory in your computer.
  • The relevant page reference or section in the documentation.
Parent topic: Contacting Micro Focus


Contact information

Our Web site gives up-to-date details of contact numbers and addresses.

Additional technical information or advice is available from several sources.

The product support pages contain considerable additional information, including the Product Updates section of the Micro Focus SupportLine Web site, where you can download fixes and documentation updates.

To connect, enter http://www.microfocus.com in your browser to go to the Micro Focus home page, then click Support & Services > Support Resources > All Support Resources. In the Browse by Product field, click the product you require support for. Click either Log into SupportLine or Contact Support.

If you are a Micro Focus SupportLine customer, please see the Welcome to Customer Care document that includes information about downloading and licensing your product, contacting Customer Care, and about reporting an incident. You can download it from our Web site. Support from Micro Focus may be available only to customers who have maintenance agreements.

Parent topic: Contacting Micro Focus
Related information
Micro Focus SupportLine
Welcome to Customer Care


Training

Micro Focus's Training Department offers hands-on training classes that teach COBOL programmers how to use the business solutions provided by the extend product line. Classes cover nearly all products including the ACUCOBOL-GT Development System and related deployment and data access products. These classes are offered in an instructor-led environment or as online training units. They are designed to give guided practice using extend solutions. Contact your Micro Focus extend representative to register for any of our training opportunities.

Parent topic: Micro Focus Services and Solutions


Consulting Services

Micro Focus offers consulting services led by experienced professionals at Micro Focus's worldwide offices. These professionals provide a wide variety of consulting and training assistance as part of our business solutions. COBOL specialists with expertise in analysis, development, and project management are available to provide any level of support your business requires. We can help you:

  • Add a Graphical User Interface (GUI) to your character-based COBOL programs.
  • Deploy your COBOL applications on the Internet.
  • Migrate your COBOL application to a client/server and distributed processing environment.
  • Partner with your IT department for joint application development.
  • Migrate COBOL applications written for older platforms to an open systems environment.
  • Interface your COBOL application to a Relational Database Management System (RDBMS).
  • And more...

For more information, contact your Micro Focus extend representative.

Parent topic: Micro Focus Services and Solutions


Getting Started

  • Installation and License File Basics
  • Sample, Definition, and DLL Files
  • Configuring Your Terminals
Parent topic: ACUCOBOL-GT Version 10.2.0 Getting Started Guide


Installation and License File Basics

The following steps must be performed to install your products on any platform:

  1. Choose a directory for your products. (You may select the defaults.)
  2. Insert the media containing your products into the appropriate drive.
  3. Run the setup or install program or unload the media.

    This process varies depending on your operating system. Refer to the appropriate help in this guide for specific instructions.

  4. Create your software license file using the Activator utility described Windows Installation. Follow the setup or install program prompts.
  5. Configure the product for use according to the directions given in the product's online help file.
  • Requirements
  • License Files for extend Products
Parent topic: Getting Started


Requirements

Unless otherwise indicated, the references to specific operating systems in this documentation refer to the supported operating systems as indicated in the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx.

See the extend Release Notes for additional specifications and requirements.

Parent topic: Installation and License File Basics


License Files for extend Products

All extend products require a license file in order to operate. You may request a license file for a single user, or one that allows a number of users to execute a particular product concurrently.

When you receive your product(s) the package includes one or more letters containing product codes and product keys for every product you ordered. (These are alphanumeric strings containing information about your product, such as the version number, serial number, and user count.) The letter is titled "Important Licensing Information." If you do not receive this letter, contact your Micro Focus extend representative. You must have the product code(s) and product key(s) to install your software. A utility called the Activator converts the pair of strings into a license file.

Note:

Use the version of the Activator that corresponds with the version of the product you are installing.

The product code and product key make it easy to update or change your license file. If you order a new product or add users, you simply enter a new product code and key into the Activator utility. The resulting license file is required. If the license file is missing or damaged, your access to the software may be interrupted.

  • License file names
Parent topic: Installation and License File Basics


License file names

The name of each license file is based on the name of the product's executable file, with a special extension. For example, if your runtime executable is named "runcbl," the runtime license file is named "runcbl.alc," and the Acu4GL for Sybase license file is named "runcbl.ylc." Each product has its own license file. The following chart lists the UNIX and Windows license file name for each extend product.

Product | License ext. | UNIX | Windows
Acu4GL DB2 | .klc | runcbl.klc | wrun32.klc
Acu4GL Informix | .ilc | runcbl.ilc | N/A
Acu4GL MSSQL | .mlc | N/A | wrun32.mlc
Acu4GL ODBC | .dlc | N/A | wrun32.dlc
Acu4GL Oracle | .olc | runcbl.olc | wrun32.olc
Acu4GL Sybase | .ylc | runcbl.ylc | wrun32.ylc
AcuBench | .alc | N/A | acubench.alc
ACUCOBOL-GT compiler | .alc | ccbl.alc | ccbl32.alc
ACUCOBOL-GT runtime | .alc | runcbl.alc | wrun32.alc
ACUCOBOL-GT runtime CGI | .clc | runcbl.clc | wrun32.clc
AcuConnect distributed processing | .clc | acurcl.clc | acurcl.clc
AcuConnect Thin Client | .alc | acurcl.alc | acurcl.alc
AcuServer | .alc | acuserve.alc | acuserve.alc
AcuSQL precompiler | .alc | acusql.alc | acusql.alc
AcuSQL runtime | .2lc | runcbl.2lc | wrun32.2lc
AcuXDBC | .alc | xvision.alc | xvision.alc
AcuXDBC Server | .slc | xvision.slc | xvision.slc
AcuXDBC Enterprise | .elc | xvision.elc | xvision.elc
Transaction Server | .1lc | runcbl.1lc | wrun32.1lc
Note: If you rename the product's executable file, you must change the base name of the license file to match it, and leave the license file extension unchanged. For example, if you rename your compiler from "ccbl" to "mycomp," you must rename the license file from "ccbl.alc" to "mycomp.alc."

License files with an extension ending in an exclamation point (!), are back-up copies of old license files. See License Files for Windows for more information.

Parent topic: License Files for extend Products


Sample, Definition, and DLL Files

This section describes some of the sample programs included with the release materials and introduces the standard definition (".def") and dynamic link library (".dll") files that are included in the ACUCOBOL-GT compiler and runtime system in the release materials.

  • Sample Programs
  • Definition Files
  • DLL Files
Parent topic: Getting Started


Sample Programs

ACUCOBOL-GT includes many sample programs in the standard release materials. These programs demonstrate general and specific features of the system and measure some aspects of system performance. Many of these programs can serve as generic templates for developing similar functionality in your programs.

Some of the sample programs provided with ACUCOBOL-GT are stand-alone programs, designed to be run at the command line. Examples include:

  • TOUR.CBL (demonstrates features of the Development System)
  • GENMENU.CBL (creates COBOL code for menu bars)

Some of the sample programs can either be called from another program or run from the command line:

  • CALC3.CBL (provides a pop-up calculator)
  • NOTEPAD.CBL (offers a pop-up notepad for notes and reminders)

Many of the sample programs are subroutines that must be called from another program. You can call them from "tour.cbl" or from your own application:

  • MESSAGE.CBL (shows how to send up to three lines of text to the user and receive a standard numeric response code)
  • MENUBAR.CBL (demonstrates pop-up and static menu bars)
  • MENUBAR2.CBL (demonstrates pop-up and static menu bars for graphical environments)
  • PRNTSCRN.CBL (for character-based applications, shows how to print screens using the ACCEPT FROM SCREEN verb)

Many other valuable sample programs are available in the Examples and Utilities area of the Micro Focus Web site.

http://supportline.microfocus.com/examplesandutilities/index.asp

Parent topic: Sample, Definition, and DLL Files


Definition Files

ACUCOBOL-GT includes a number of definition files. These files make it easier to use some of ACUCOBOL-GT's special features, such as graphical controls, color configuration, and Windows HELP. Many of the definition files contain predefined data structures for use with ACUCOBOL-GT runtime routines. You can include these structures easily in your program by COPYing the definition file into your program. All of the definition files have the three-character .def extension in their name. Most reside in the sample\def directory: in Windows, this is %PUBLIC%\Documents\Micro Focus\extend x.x.x\sample\def, and copies are also placed the sample\def subdirectory of your ACUCOBOL-GT directory. In UNIX, they reside in the sample/def subdirectory of your ACUCOBOL-GT directory. How and when to use these files is documented with the feature or function that the file supports (such as with a runtime library routine or in the Special Names reference documentation).

Note: Always use the same .def file version with the corresponding version of the development system. For example, do NOT use a Version 9.0 .def file with a Version 10.0 development system.
Parent topic: Sample, Definition, and DLL Files


DLL Files

On Windows systems, ACUCOBOL-GT includes a number of dynamic link library files (extension ".DLL"). Those files are part of the product and contain various utility functions used by the executable files. They may also contain data. The .DLL files that are part of the ACUCOBOL-GT compiler and runtime are installed automatically in the same directories as the main executable files for those programs, CCBL32.EXE and WRUN32.EXE, respectively.

One of the main components of the Windows versions of ACUCOBOL-GT is a utility file called ACME.DLL. All of the .EXE and .DLL components of ACUCOBOL-GT link to this file, including their initialization and shutdown functions. ACME.DLL offers the benefit of providing a common set of utility functions for all executables to share, as well as allowing you easy and consistent access to all our libraries through a single DLL. ACME.DLL is installed automatically in the same default subdirectory on your machine as the executable files.

Note:

Those users who change directories after the installation of the product, or those who ship the compiler or runtime separately as part of their own product, should make sure that all the .DLL files are placed in the same directory as the .EXE files. Therefore, if you move CCBL32.EXE or WRUN32.EXE, you must move all of the .DLLs along with them. If you delete any .DLL files that have been installed, your products will not run.

Parent topic: Sample, Definition, and DLL Files


Configuring Your Terminals

ACUCOBOL-GT requires data about the video environment it is running in. On Windows machines, it directly examines the hardware and configures itself appropriately. On UNIX and VMS machines, you must provide a description of the terminal you are using. This section describes briefly how to provide that information. Additional details are provided in the Terminal Manager section of the ACUCOBOL-GT User's Guide.

On systems that do not configure themselves automatically, describing the terminal to ACUCOBOL-GT involves two steps:

  1. First, identify the terminal by setting the "TERM" variable.
  2. Second, ensure that the terminal's characteristics are accurately described in the terminal database file.
  • TERM Variable
  • Terminal Database
Parent topic: Getting Started


TERM Variable

ACUCOBOL-GT determines the type of terminal you are using by looking at the setting of the "TERM" variable. On UNIX and Linux machines, TERM is an environment variable; on VMS machines, it's a symbol. Samples for both UNIX and VMS are presented below.

TERM should be set to the name of one of the entries in the terminal database. You can examine the database file for valid names. The first field of each entry consists of a list of accepted names. Some common names are "vt100", "tv925", and "wy50" for VT100, Televideo 925, and Wyse 50 terminals, respectively.

Note that on most UNIX systems, the TERM environment variable is initialized as part of the login procedure. You will need to change this only if the name used is not one listed in the terminal database. On VMS systems, the TERM symbol defaults to "vt100" if it is not defined. Thus, you need to define the TERM symbol only if you want to use a terminal that is not VT100 compatible or if you want to use some advanced features of your terminal.

As an example, suppose you want to use a VT220 terminal. In the database, "vt220" is one of the accepted names for this type of terminal. On a VMS system, you would use the following command

TERM == "vt220"

On UNIX systems with the Bourne or Korn shell, the command would be:

TERM=vt200; export TERM

Using the C shell, the equivalent command is:

setenv TERM vt220

You may want to leave the TERM variable at its current setting to maintain compatibility with other software. If the setting is not correct for ACUCOBOL-GT, you can set the "A_TERM" variable instead. If both the A_TERM and TERM variables are set, ACUCOBOL-GT uses the definition of A_TERM. This allows you to have different settings for ACUCOBOL-GT and your other software.

Parent topic: Configuring Your Terminals


Terminal Database

ACUCOBOL-GT comes with a database of terminal descriptions. On UNIX machines, this is called "a_termcap". On VMS machines it is called "A_TERMS.DAT". This database contains encoded descriptions of many types of terminals. You need to select the terminal type in the database that most closely matches the terminal you are using. If you need to, you can add your own entries in the database.

By default, the terminal database should reside in a pre-selected directory on your machine. On UNIX machines, this is the "/etc" directory; on VMS machines, it is the "SYS$LIBRARY" directory. If you want to place your terminal database somewhere else, then you must define the variable "A_TERMCAP" to be the full name of the database file. For example, on a VMS system, you could place the database in the "SYS$LOCAL" directory with the following command:

A_TERMCAP == SYS$LOCAL:A_TERMS.DAT

On UNIX systems (using the Bourne shell), you might use the command:

A_TERMCAP=/usr/local/etc/a_termcap; export A_TERMCAP

The ACUCOBOL-GT User's Guide contains more information about setting up terminals and making full use of their capabilities, and selecting terminal types.

Parent topic: Configuring Your Terminals


License Management

  • Using Multiple Versions of ACUCOBOL-GT
  • Evaluation License Files
  • License Management for ISVs
  • License Management with CGI on the Internet
  • Multiple-User License File Management
  • Acushare License File Management for UNIX and Linux
Parent topic: ACUCOBOL-GT Version 10.2.0 Getting Started Guide


Using Multiple Versions of ACUCOBOL-GT

Version 9.x license files work only with the Version 9.x series of products. However, you may easily run Version 8.x or earlier versions of extend products alongside Version 9.x products. To do this, simply install the products and license files in a separate directory for each version.

For example, if you place the Version 8.1.0 compiler and license file in the C:\Program Files\Micro Focus\Acucbl810\AcuGT directory, and place the Version 9.x compiler and license file in the C:\Program Files\Micro Focus\Acucbl8xx\AcuGT directory, either version of the compiler will execute properly.

Parent topic: License Management


Evaluation License Files

Evaluation license files are time-limited. The steps performed to install extend products with a product code and key for an evaluation license file are the same as for installing a permanent license file. If you have an evaluation product code and key, follow the instaructions in the help provided for your platform.

Parent topic: License Management


License Management for ISVs

This section is intended for Independent Software Vendors (ISVs) who have used extend products to develop applications and are ready to distribute them to end-user customers. The following information outlines what you must include in your product distribution so that the licensing mechanism will work properly for your customers.

  • Licensing Requirements
  • Distributing License Files to your Customers
Parent topic: License Management


Licensing Requirements

Your customers will require the appropriate license file (single-use versus multiple-use). A license file is created from the product code and product key by the Activator utility. To obtain the product code and product key pair for your end user, you need to provide Micro Focus with the following information:

  1. Host operating system

    We need information about the target machine, such as the name of the operating system (OS), the release version of the OS, and the type of processor (such as Intel or SPARC). For example:

    • Windows 8 Pro (Intel)
    • IBM AIX V7.2 32-bit
    • HP-UX 11.31 RISC 64-bit
    • SCO UNIX OpenServer 10
    • Linux (glibc 2.5) (Intel)
    • Solaris 11.3 (SPARC) 64-bit
  2. Number of users

    You also need to specify how many users will be accessing the application at the same time (concurrent users). For example, if a site needs access to an application from a number of machines, but only by one user at a time, this would require a different license file than a site where multiple users access the same application concurrently.

  3. extend products

    You need to specify which products will be run with your application. Remember to specify the version number of the product using three digits, such as 8.1.0.

Once we have this information, the product code and product key pair(s) will be shipped in accordance with your License Agreement.

  • The Activator Utility
Parent topic: License Management for ISVs


The Activator Utility

In addition to the product code and product key, you will be given the following files, based on the target platform for the license file:

Target Platform | Required Files
Windows | activator.exe
UNIX/Linux | activator acushare*
VMS | activator.exe

*After all necessary license files are installed and the applications are ready to run, UNIX and Linux platforms use a utility called acushare to act as the license manager. The acushare utility must be distributed with all UNIX/Linux products. For more information on acushare, see Acushare License File Management for UNIX and Linux.

Parent topic: Licensing Requirements


Distributing License Files to your Customers

There are two methods of providing the license file with your application:

  1. Create the license file and package it with your application in the same directory as the corresponding extend executable.
  2. Distribute the extend executable files, the product code and product key pair, and the Activator utility to your customers and allow them to create the license file on site.
  • Including the License File in Your Distribution
  • Distributing extend Products and License Files
Parent topic: License Management for ISVs


Including the License File in Your Distribution

If you choose to create the license file using your customer's product code and key and incorporate it into your product installation before sending it to the customer, create the license file as needed for your operating systems and place the resulting file in the same folder as the runtime (or other corresponding executable).

Parent topic: Distributing License Files to your Customers


Distributing extend Products and License Files

If you choose to allow your end-user customer to create the license file directly on the target machine, your application must be accompanied by all of the files necessary to install extend products on the end user's machine. This includes the ACUCOBOL-GT product executable(s), DLLs, other relevant files, and the licensing files described above. Your customers will also need to receive their product codes and keys. The installation instructions for all major host systems are in Lets Get Started.

Note: If using the ACUCOBOL-GT Web runtime, see Obtaining and Distributing the Web Runtime in A Programmer's Guide to the Internet for special licensing considerations that may affect your product distribution.

The Activator utility should be launched at the end of your product installation.

You can distribute the product code and product key via fax, e-mail, or as a text file on your distribution media. When you send the product codes and keys to your customers, use a font that clearly distinguishes the different letters from each other. Product codes and keys do not contain the letters "o O" or "I I." In the Activator, all product codes and keys display in upper case. Also, the Activator removes spaces and hyphens.

Parent topic: Distributing License Files to your Customers


License Management with CGI on the Internet

If you order a CGI license file, you will receive a product code and key that will cause the Activator utility to create this type of license file. However, for the runtime to recognize this special license file, your COBOL application should be compiled with the "-Ca" compiler switch. You must also use "-f" as a runtime parameter, or set the A_CGI environment variable to a non-zero value. See Configuring the Web Server in A Programmer's Guide to the Internet for a description of the A_CGI variable.

When these conditions are detected by the runtime, it will run exclusively in CGI mode. In CGI mode, the runtime looks for a CGI license file. If a CGI license file is not found, the runtime looks for a standard runtime license file which, if found, causes the runtime to execute in its normal mode. End users should not detect any difference in runtime operation between CGI mode and normal mode.

Parent topic: License Management


Multiple-User License File Management

Micro Focus offers multiple-user license files for extend products. This enables end-user sites to plan for network growth and make arrangements to accommodate peaks in application use.

The first step in creating a multiple-user license file is to determine how many end users might need to execute the product simultaneously.

To determine this maximum on UNIX machines, you count the number of unique terminal names that might need to execute the product at the same time. On Windows systems, each connected machine is counted. Request a license file for the maximum number of simultaneous users. This number is the user limit. The user limit is encoded in the product code and key that create the license file. The product is also assigned a unique serial number in its license file.

Note:

On systems using Alternate Terminal Manager (ATM), the system cannot recognize which user is running a particular process. In that environment, one process equals one user.

For example, suppose the Adams Corporation has 50 end users, not all of whom use the system at the same time. Adams' managers predict that, with planned expansion, up to 30 of these users may need to execute the runtime at the same time.

Adams Corporation arranges for a 30-user license file, which gives all 50 of their end users access to the runtime system, with up to 30 having simultaneous access.

If Adams has a Windows network, up to 30 connected machines may execute the runtime system at the same time. The number of processes is not monitored.

If Adams has a UNIX network, the 30-user license file allows up to 30 terminals to execute at the same time. Because users often run background processes, each terminal is allowed to run more than one runtime process at a time. This ensures that background processes such as reports can be processed while interactive work continues. This is managed by the acushare utility, described in Acushare License File Management for UNIX and Linux.

To establish a multiple-user license file on other operating systems, such as VMS, please contact your local Micro Focus extend representative.

  • Updating the User Limit
Parent topic: License Management


Updating the User Limit

If you need to change the user limit, you update the license file. Contact your Micro Focus extend representative for new product codes and product keys. These should be entered with the Activator utility, as described in the help that is applicable to your operating system.

Parent topic: Multiple-User License File Management


Acushare License File Management for UNIX and Linux

License file management in UNIX and Linux environments is handled by the acushare utility program. Acushare provides three key services to extend products:

  • AcuServer license management
  • ACUCOBOL-GT runtime license management
  • ACUCOBOL-GT runtime shared memory management

The acushare utility program is described in detail in ACUCOBOL-GT User's Guide > Compiler and Runtime > acushare Utility Program. This section describes Acushare's role in extend license management and includes basic instructions for starting and stopping acushare.

Note: Multiple versions of acushare can run concurrently on the same system, but you must use matching acushare and product versions. For example you cannot use a version 9 acushare with a version 8 runtime.
  • AcuServer License Management
  • How Acushare License Management Works
  • Starting and Stopping acushare
Parent topic: License Management


AcuServer License Management

The acushare utility is required with the AcuServer product. AcuServer enables remote access of Vision indexed files. AcuServer can be requested for single-server situations (one instance of AcuServer per server machine) and for multiple-server situations (multiple instances of the product executing simultaneously on the same server machine). The acushare utility is required for both configurations.

Parent topic: Acushare License File Management for UNIX and Linux


How Acushare License Management Works

The acushare utility program is an important component of any UNIX or Linux system running AcuServer or the ACUCOBOL-GT runtime. Acushare monitors the number of simultaneous users of extend products, where a "user" is defined as a unique terminal name.

Note: For programs called via AcuConnect and CGI processes started by a Web server, each process on the server is counted as a separate user. Likewise, if a terminal allows users to log in with more than one Telnet (tty) session under a single user name, each Telnet session is counted as a separate user by the license manager.

Acushare keeps a list of active users (terminals) and ensures that the number of users executing the runtime simultaneously does not exceed the limits of the site's license.

Acushare keeps track of users for each product's distinct serial number. For example, if you have a runtime for 10 users, and a second runtime for 20 users, a total of 30 users could be executing applications on the system simultaneously, if both runtimes are executing. This ensures that distinct software applications are monitored separately.

When the ACUCOBOL-GT runtime or AcuServer run, they perform the following actions related to license management:

Check acushare

When the ACUCOBOL-GT runtime or AcuServer starts up, each checks to make sure that acushare is running on the system. If it's not running, the product attempts to start it. For this automatic startup to be successful, acushare must be located in the product's search path.

If the product cannot start acushare, it exits with the following message:

"Shared memory and license manager (acushare) is not running"

Register each terminal name

If acushare is running on the system, the ACUCOBOL-GT runtime or AcuServer attempts to register itself with acushare. If the user limit has not already been reached, the registration occurs. acushare places the user's (terminal) name on the list of active product users (unless it's already there).

If the user limit specified in the site's license file would be exceeded by the addition of this user, the product checks the product's configuration file (and then checks the environment), to determine if it should retry the registration process in a few seconds.

A runtime configuration variable can be used to specify the number of retries allowed when you are executing the runtime. If this variable is set to a positive integer value, the runtime waits n seconds and tries again to register itself. The value n (the number of seconds to wait between retries) is set in the variable A_RETRY_DELAY. If no retries are desired, or if all retries have been performed and the limit is still exceeded, the product exits with a message.

Recheck acushare

Each active product checks periodically to determine if acushare is still running. If the product detects that acushare has stopped and has not been restarted, it tries to restart it itself. If unsuccessful, it issues the following warning message:

"License manager (acushare) is not running"

This warning message appears at the line specified in the runtime configuration variable SCREEN ERROR-LINE. Or, if that's not set, at the bottom of the screen.

If acushare has not been restarted by the time the product makes another periodic check, the product exits.

End a session

When the user ends a session on the terminal, the product receives a signal to terminate. If the product was executed with "-h" or "-sb", it ignores the signal and continues to run. When a product is executing without a controlling terminal, acushare displays the terminal name as (none). The terminal is removed from acushare's list of active users only when the product terminates.

Parent topic: Acushare License File Management for UNIX and Linux


Starting and Stopping acushare

Acushare manages both the license file and any shared code segments used by the ACUCOBOL-GT runtime system. On UNIX and Linux systems, acushare runs as a background server process that responds to requests from various client products (a "daemon" in UNIX terminology).

Acushare has several command-line formats. They include:

acushare -start [-f] [ -p portnumber ] [ -e errorfile [ -g ] ]
acushare –kill
acushare –clean
acushare –version
acushare
  • -start
  • -kill
Parent topic: Acushare License File Management for UNIX and Linux


-start

To start acushare, you simply enter the following on the command line:

acushare -start

A successful start creates a background process that handles license management and shared code. You can specify:

acushare -start -f

to have acushare run in the foreground.

If you want acushare to start automatically each time your system boots, you can add a small amount of code to the system boot file. The name of the boot file varies from system to system. Typical names are /etc/rc.local, /etc/brc, or /etc/rc. Identify the proper startup file and add lines similar to the following:

if [ -f /usr/etc/acushare ]; then
   echo Starting ACUCOBOL-GT shared-code and license daemon> \
        /dev/console
   /usr/etc/acushare -start > /dev/console
fi

The above example assumes that you've placed acushare in /usr/etc. You may need to adjust the sample code to match the conventions used in your environment.

For more information about starting acushare, see ACUCOBOL-GT User's Guide Compiler and Runtime > acushare Utility Program.

Parent topic: Starting and Stopping acushare


-kill

To stop acushare, you simply enter the following on the command line:

acushare -kill

For complete information on all of acushare's options and information on licensing and memory sharing error messages, see ACUCOBOL-GT User's Guide Compiler and Runtime > acushare Utility Program.

Parent topic: Starting and Stopping acushare


Troubleshooting

  • Debugging an Invalid License Host Error
  • Questions & Answers
Parent topic: ACUCOBOL-GT Version 10.2.0 Getting Started Guide


Debugging an Invalid License Host Error

If you receive an "Invalid License For This Host" error, the likely cause is that the wrong port for your operating system was selected during installation. This can result in a mismatch between the runtime and the runtime license file. You can determine which port was actually installed and whether it matches your operating system by comparing the machine key numbers that appear in the Makefile to the runtime license file (runcbl.alc). Mismatched numbers between these two places indicates that the incorrect port for your machine is installed and can can lead to other errors or unexpecteed behaviors.

Note:

The machine key corresponds to a specific port and is embedded within the runtime. This same machine key must be in the license file runcbl.alc. The runtime searches for the runcbl.alc file attempting to match the machine keys. If no match is found, an "Invalid License Host" error is displayed. The runtime does not check to verify if the port you installed matches the operating sysem.

  • Identifying a Machine Key Mismatch
  • Tracing a License File
Parent topic: Troubleshooting


Identifying a Machine Key Mismatch

Check for a machine key mismatch by opening the Makefile (located in the "lib" directory) and locating the line containing "PMK". Make note of the machine key number that appears here. The Makefile content looks like this:

# Makefile to create new version of "runcbl" or "acusql"
# based on changes to "sub.c"
# To relink the runtime, run: make runcbl
# To relink the ESQL pre-compiler, run: make acusql
# Distributed with ACUCOBOL-GT version 8.0.0
# PMK: 120

Now, open the runtime license file, and check the machine key number. This number should be the same number that appears in the PMK number of the Makefile. The license file content looks like this:

# ACUCOBOL license file
# BLOCK_START_runtime_120_7.0.0
# Product code: LQASC3ABANS6S7XX7A2S
# Product key.: HTY9SVJBAMX3
# Product........: runtime
# Version........: 8.0.0
# Machine-key....: 120

If the numbers don't match, refer to the packing slip and the product code and key labels that were sent with the distribution. Note that the UNIX CD contains several choices, but only one port will match the generated license files. After reviewing these documents, delete the installed files and reinstall, choosing the port from the UNIX CD that matches the description on the license labels including whether it is 32- or 64-bit.

Parent topic: Debugging an Invalid License Host Error


Tracing a License File

You can also perform the following file tracing steps to determine where the runtime is searching for a license file, and if found, which directory it is in. the trace output also displays information abou the license file itself, including the machine key number.

  1. In the OS environment, set the following environment variable:
    A_TRACE_LICENSE=1
  2. From the "bin" directory of acucobolxx, execute the following command:
    runcbl -vv
  3. Examine the output from the trace to determine if the two entries that follow "Testing port key" match. The following example shows what the trace output would look like in the event of a mismatch:
    ACUCOBOL license: Trace 'runtime 8.0.0'
ACUCOBOL license: Trace './runcbl.alc'
ACUCOBOL license: Trace 'Comment'
ACUCOBOL license: Trace 'Blank line'
ACUCOBOL license: Trace 'Blank line'
ACUCOBOL license: Trace 'Comment'
ACUCOBOL license: Trace 'Comment'
ACUCOBOL license: Trace 'Comment'
ACUCOBOL license: Trace 'Blank line'
ACUCOBOL license: Trace 'Testing port key'
ACUCOBOL license: Trace '120'
ACUCOBOL license: Trace '135'

If you still are unable to resolve the error, contact Micro Focus Customer Care and include the trace output.

Parent topic: Debugging an Invalid License Host Error


Questions & Answers

Question

I have two servers on my network. One server contains ACUCOBOL-GT for two users, and the other has ACUCOBOL-GT for three users. If the server with a two-user license file fails, can all five users use the license file on the other server?

Answer

No. The license manager does not add up users from multiple servers. In order to have five users on either server, you would need to request the full user limit for each server.

Question

I am experiencing an error when I try to read the media on UNIX. For example, CPIO, generates the error, "not in cpio format" and TAR formatted archives generate the error, "I/O error on device name." What should I do?

Answer

In either case, use the following command to do an ASCII dump of the first part of the data:

od -c device | more

If you see the word "AMEK" in the dump, this indicates that some bytes may be swapped. You may be able to correct the problem with the "dd" utility.

For CPIO archives, use the following command:

dd if=device bs=10b conv=swab | cpio -icvBd

For TAR formatted archives, use the following command:

dd if=device bs=20b conv=swab | tar -xvf -

These commands cause each pair of incoming bytes to be swapped big-endian to little-endian conversion or vice versa). This may solve the problem.

Parent topic: Troubleshooting


ACUCOBOL-GT Version 10.2.0 Documentation Set

  • Copyright Statement
  • ACUCOBOL-GT User's Guide
  • ACUCOBOL-GT User Interface Programming
  • ACUCOBOL-GT Reference Manual
  • Appendices
Parent topic: extend Interoperability Suite


ACUCOBOL-GT User's Guide

  • Introduction
  • Compiler and Runtime
  • Debugger and Utilities
  • Terminal Manager
  • File Processing
  • Programmer's Guide
Parent topic: ACUCOBOL-GT Version 10.2.0 Documentation Set


Introduction

  • ACUCOBOL-GT Documentation
  • Product Overview
  • Document Overview
  • Supported Hardware
  • Environment Variables
  • Notation
  • Contacting Micro Focus
Parent topic: ACUCOBOL-GT User's Guide


ACUCOBOL-GT Documentation

This is the first part of the documentation set that describes the features of ACUCOBOL-GT®.

The other parts in this set include:

  • ACUCOBOL-GT User Interface Programming
  • ACUCOBOL-GT Reference Manual
  • ACUCOBOL-GT Appendices

This set is augmented by these additional volumes:

  • Getting Started
  • ACUCOBOL-GT Run-Time Manual
  • extend Product Guides
  • Transitioning to ACUCOBOL-GT
  • A Guide to Interoperating with ACUCOBOL-GT
  • A Programmer's Guide to the Internet

See Document Overview for a brief introduction to all of these volumes.

Parent topic: Introduction


Product Overview

ACUCOBOL-GT is part of the extend® family of Micro Focus solutions. ACUCOBOL-GT is an ANSI® 1985 COBOL compiler that also includes components of the ANSI X3.23a-1989 supplement. It is a powerful development environment for a wide range of computers.

Fast compile speed, clear error messages, and a multi-window source level debugger work together to provide a high-performance, easy-to-use COBOL development platform.

Portable object code, a generic interface to a variety of file systems, and a device-independent terminal interface help to simplify the distribution of applications developed with ACUCOBOL-GT.

In addition to portable object code, ACUCOBOL-GT can generate and execute object files that contain native instructions for specific types of processors. This enables you to optimize the use of CPU resources on the host machine while maintaining full portability within the same family of processors.

Installation instructions for all computer types are provided in Getting Started. The compiler, the run time, and some utility programs have different names, depending on the host system. Basically, the compiler is ccbl, the run time is runcbl, and the utilities are vutil, vio, logutil and cblutil.

Note: References to Windows in this manual denote any of the supported Windows platforms, which are listed in the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx. Where it is necessary to make a distinction, the specific version name/number is specified.

ACUCOBOL-GT is a single-pass compiler that produces an object file.

The object file is ready for immediate execution by the ACUCOBOL-GT run time. No linking step is required.

  1. Portability and Compatibility
  2. Native Instructions
  3. The ACUCOBOL-GT Runtime
  4. Run-Time Configuration
  5. Graphical Technology
  6. File System Flexibility
  7. Complementary Technologies
Parent topic: Introduction


Portability and Compatibility

One of the primary focuses of the product is program portability. ACUCOBOL-GT offers source code compatibility modes for five popular compilers:

  • Ryan McFarland's RM/COBOL™
  • ICOBOL (originally Data General Interactive COBOL)
  • VAX™ COBOL
  • IBM® COBOL
  • HP COBOL

Although not provided as a mode that is turned on with a compiler switch, there is extensive built-in compatibility for Micro Focus COBOL. These facilities allow programs to be moved to or from these environments with minimum effort.

ACUCOBOL-GT also offers fully portable object code. Any program compiled on one machine using ACUCOBOL-GT will run unmodified on any other machine that supports ACUCOBOL-GT — recompiling is not required. This allows the developer access to a diverse user base with a minimum investment in hardware.

Parent topic: Product Overview
Next topic: Native Instructions


Native Instructions

ACUCOBOL-GT can also generate and execute object files that contain native instructions for selected families of processors. This results in generally faster code at the cost of reduced portability and larger object files.

Generally speaking, a native-code module will be a much more efficient user of the CPU. However, a native-code module will typically be several times larger than a portable object code module. You must weigh the benefits of better CPU utilization versus the cost of more memory used. For systems in which memory is tight, one solution is to use native code only for those modules that are CPU-intensive, while leaving the rest of the system in portable object code.

When you compile using native instructions, the resulting object file may be run only on a machine containing the appropriate processor. Note, however, that within this class of machines, the object file is still portable. For example, you could run an Intel object file on a Windows machine or on a Linux machine. There is no need (or benefit) to compile directly on the target machine.

See Supported Hardware for the complete list of platforms supported by ACUCOBOL-GT, and Native Code Supported Processors for the complete list of processors supported by its native-code functionality.

Object files that contain native-code instructions are similar to normal COBOL object files. The only difference is the internal instruction set used. Native-code object files are run in the same fashion as normal (portable) objects: by using the runtime. The runtime acts as the memory manager and support libraries for the native-code module. You may mix native and non-native modules in a single run freely.

Parent topic: Product Overview
Previous topic: Portability and Compatibility
Next topic: The ACUCOBOL-GT Runtime


The ACUCOBOL-GT Runtime

After a program is successfully compiled it is ready for immediate execution with the ACUCOBOL-GT runtime. There is no link step. See Using the Runtime System for details on using the runtime.

On UNIX, Linux, and OpenVMS systems, the runtime executable file is named runcbl or runcbl.exe. On some UNIX systems the runtime is provided as a shared object library named libruncbl.so or libruncbl.a.

Several distinct runtimes are available for Windows systems. Each is licensed separately.

  • The standard Windows runtime is named wrun32.exe. It is used with all standard deployments
  • Thin client deployments use a special runtime named acuthin.exe. acuthin is used in conjunction with AcuConnect and a standard runtime, both of which are installed on the application host. See Thin Client, in the AcuConnect User's Guide for more information about Thin Client technology.
  • The Windows console runtime crun32.exe supports applications originally developed for Extended DOS and other character-based applications. The console runtime uses the Windows Console API and runs in a virtual DOS window. See Windows Console Runtime for more information.
  • The Alternate Terminal Manager (ATM) runtime, named run32.exe, lets you use a 32-bit Windows server in much the same way that some UNIX servers are used. With the ATM runtime, the user can telnet to the Windows server (with a third-party telnet service) to execute character-based ACUCOBOL-GT programs in the telnet window. See Alternate Terminal Manager (ATM) for more information.
  • A special CGI runtime supports Windows-based deployment of applications accessed via the World Wide Web. For more information on these options, see A Programmer's Guide to the Internet.
  • Windows Console Runtime
Parent topic: Product Overview
Previous topic: Native Instructions
Next topic: Run-Time Configuration


Windows Console Runtime

The Windows console runtime (crun32.exe) is a 32-bit Windows runtime that provides support for applications originally developed for Extended DOS and other character-based systems. The console runtime uses the Windows Console API and runs in a virtual DOS window. The Windows console runtime is sold and licensed separately.

The console runtime includes support for:

  • calling Windows DLLs
  • using Acu4GL modules without having to relink the runtime

Although the console runtime is designed to run ACUCOBOL-GT applications developed for Extended DOS, your applications may require some modifications. For example, the console runtime supports printing capabilities based on the Windows model. Programs that rely on DOS printing functions must be changed. You should examine your applications for the use of DOS functions that are not supported in the Windows environment.

Two runtime configuration variables allow you to tune the execution environment: DOS_SYS_EMULATE and DOS_BOX_CHARS. For details, see their respective entries in Appendix H.

Note: Should you need to relink the console runtime, see Relinking the Runtime System in A Guide to Interoperating with ACUCOBOL-GT.
Parent topic: The ACUCOBOL-GT Runtime


Run-Time Configuration

Users of ACUCOBOL-GT can modify many aspects of the run-time environment on a site-by-site or user-by-user basis without recompiling. This is accomplished in a text file known as a COBOL configuration file, and by environment variables.

For example, the location of data files, names of devices, color, text of error messages, file buffering, and screen editing functionality can all be maintained outside of the compiled programs. See Configuration Variables for configuration variables that may be useful to your site.

If machine-specific behavior is required, a program can directly inquire what type of machine it is running on. All of these features work together to allow the developer to support a wide range of machines with a minimum amount of resources.

Parent topic: Product Overview
Previous topic: The ACUCOBOL-GT Runtime
Next topic: Graphical Technology


Graphical Technology

ACUCOBOL-GT includes broad programming and run-time support for adding a native Graphical User Interface (GUI). In addition, many graphical elements, such as floating windows, labels, entry fields, push buttons, radio buttons, check boxes, list boxes, combo boxes, and others, are emulated with character-based components when run on text-mode systems. Some graphical elements are not emulated in text-mode environments and are simply ignored by the runtime. See User Interface Programming for more information.

ACUCOBOL-GT GUI syntax extensions make it easy to implement specialized user interfaces that are well suited to both graphical and character-based systems, and which remain fully portable. See Creating Portable User Interfaces for information on user interface development approaches, .

The graphical capabilities supported in ACUCOBOL-GT include the following:

  • syntax extensions for creating floating windows, toolbars, and controls (such as buttons, entry fields, and labels)
  • support for creating and managing menu bars with pull-down submenus
  • configuration variables for customizing windows, importing icons, and mapping colors
  • library support for host-specific features, such as file open and save-as dialog boxes, message boxes, font selections, print spoolers, and context-sensitive help
Parent topic: Product Overview
Previous topic: Run-Time Configuration
Next topic: File System Flexibility


File System Flexibility

ACUCOBOL-GT also includes a generic architecture for connecting to file systems. This means that developers can choose from a variety of file systems and database management systems, as shown in the following diagram:

On all platforms except VMS and OpenVMS, ACUCOBOL-GT is shipped with the powerful, performance optimized Vision indexed file system. On VMS and OpenVMS systems, ACUCOBOL-GT uses the native RMS file system. On HP e3000 emulators, in addition to Vision, ACUCOBOL-GT interfaces with KSAM files.

extend's interfaces to other file systems are licensed separately.

Parent topic: Product Overview
Previous topic: Graphical Technology
Next topic: Complementary Technologies


Complementary Technologies

  1. Acu4GL
  2. AcuBench
  3. AcuSQL
  4. AcuXDBC
  5. AcuConnect
  6. AcuServer
Parent topic: Product Overview
Previous topic: File System Flexibility


Acu4GL

ACUCOBOL-GT uses Acu4GL® libraries to access information stored in relational database management systems (RDBMSs). Data dictionaries generated by the compiler guide the libraries in mapping the field names and data types that are passed between COBOL and the database engine.

The essence of Acu4GL libraries is that standard COBOL I/O statements are used to access databases.

Acu4GL dynamically generates industry-standard SQL from the COBOL I/O statements. As the ACUCOBOL-GT runtime module is executing your COBOL application, Acu4GL is running behind the scenes to match up the requirements and rules of both COBOL and the RDBMS to accomplish the task set by your application.

Parent topic: Complementary Technologies
Next topic: AcuBench


AcuBench

AcuBench® is an integrated development environment for COBOL. AcuBench extends and enhances the ACUCOBOL-GT compiler and runtime system with a powerful suite of GUI-based development tools for COBOL. With AcuBench you can develop and maintain your COBOL applications in an integrated, developer friendly Microsoft Windows environment and deploy your applications on any of the more than 600 platforms supported by Micro Focus.
Parent topic: Complementary Technologies
Previous topic: Acu4GL
Next topic: AcuSQL


AcuSQL

AcuSQL® is an add-on tool that supports embedded SQL (ESQL) COBOL programs. It gives COBOL applications access to Microsoft SQL, IBM DB2, MySQL, and ISO/ANSI SQL92 compliant data sources.
Parent topic: Complementary Technologies
Previous topic: AcuBench
Next topic: AcuXDBC


AcuXDBC

AcuXDBC™ is a data management system, designed to integrate ACUCOBOL-GT data files into a relational database-like environment. AcuXDBC enables you to apply SQL and relational database concepts to your COBOL data files, resulting in data that is accessed and managed in much the same way as many of today's popular relational database management systems.

AcuXDBC is the next generation of AcuODBC and is engineered to provide broader flexibility in the way your COBOL data is accessed and maintained. Like previous versions of AcuODBC, AcuXDBC lets you retrieve and update ACUCOBOL-GT's Vision indexed files, relative files, and sequential files from Windows-based applications, including Microsoft Word, Excel, and Access. Business Intelligence tools such as Crystal Reports® Professional, and custom applications developed in ODBC-supported environments such as Visual Basic® are supported as well. With the enterprise edition, new functionality lets you retrieve data through Java applications that use JDBC standards. Direct SQL access to your ACUCOBOL-GT data is now available in both the Windows and UNIX environments.

Parent topic: Complementary Technologies
Previous topic: AcuSQL
Next topic: AcuConnect


AcuConnect

AcuConnect® is a client/server technology that is an integral part of extend's distributed computing solution. AcuConnect lets you implement a client/server system in which the client piece can be as thin or as fat as you need.

AcuConnect has two deployment environments. With AcuConnect's distributed processing deployment, users can distribute application logic between client and server machines in a way that best suits their needs. AcuConnect users can also take advantage of Micro Focus's Thin Client technology, which lets them run the user interface (UI) portion of an application on a graphical display host while the rest of the application and data reside on the server.

Parent topic: Complementary Technologies
Previous topic: AcuXDBC
Next topic: AcuServer


AcuServer

AcuServer® is an add-on module that provides remote file access services to ACUCOBOL-GT applications. AcuServer is available for applications running on UNIX, Linux, and Windows TCP/IP based networks and executing with ACUCOBOL-GT runtime Version 5.0 or higher.

With AcuServer, your applications gain:

  • The ability to create and store data files on any UNIX or Windows NT/Windows 2000 server equipped with AcuServer .
  • Full function remote access from UNIX, Linux, and Windows clients to all Vision, relative, sequential and object files stored on an AcuServer server.
  • Full record locking support of all Vision and relative files.
  • Transparent access of remote and local files

AcuServer is described briefly in File Processing. A seperate AcuServer User's Guide is included with the server software and provides additional details.

Parent topic: Complementary Technologies
Previous topic: AcuConnect


Document Overview

ACUCOBOL-GT's features and how to use them are documented in the first four sections in this list. This set is supplemented by the other guides in this list:

  • User's Guide
  • User Interface Programming
  • Reference Manual
  • Appendices
  • Getting Started
  • ACUCOBOL-GT Run-Time Manual
  • extend Product Guides
  • Transitioning to ACUCOBOL-GT
  • A Guide to Interoperating with ACUCOBOL-GT
  • A Programmer's Guide to the Internet
  • Related Documents
Parent topic: Introduction


User's Guide

The ACUCOBOL-GT User's Guide part of the documentation set includes the following.

Introduction | Gives an overview of this User's Guide with information on supported hardware, environment variables, and command notation.
Compiler and Run Time | Describes how to use the ACUCOBOL-GT compiler and its run time.
Debugger and Utilities | Discusses the source-level debugger and the file system maintenance utilities.
Terminal Manager | Gives a detailed description of the operational aspects of the ACUCOBOL-GT screen manager, along with instructions for creating new terminal definitions.
File Processing | Describes the transaction management and client/server features of the ACUCOBOL-GT language.
Programmer's Guide | Gives suggestions for taking advantage of the power and flexibility of ACUCOBOL-GT.
Parent topic: Document Overview


User Interface Programming

The User Interface Programming part of the ACUCOBOL-GT documentation set includes the following:

Introduction | Introduces floating windows and graphical controls, details interface programming issues and approaches, and describes basic windowing concepts.
Floating Windows | Introduces the properties of moveable, floating windows.
Graphical Controls | Introduces graphical control properties, details the use of bitmap buttons and paged list boxes.
Supporting Concepts and Related Issues | Discusses a variety of issues on using floating windows and graphical controls.
Control Types Reference | Describes control components, and the special properties of each control type.
Events Reference | Describes the events that the ACUCOBOL-GT run time can return to the program.
Using the Mouse | Describes how to use the automatic and programmable mouse functions available in ACUCOBOL-GT.
Menu Bars and Pop-Up Menus | Describes the process of creating, integrating, and managing program menu bars and pop-up menus.
Color Mapping | Describes program and environment configuration to take advantage of color display devices.
Help Automation | Describes how to use the syntax extensions and run time functions that support context-sensitive help.
Tips and Hints | Answers commonly asked interface programming questions, and questions about using floating windows and controls.
UI Terminology | Defines common user interface terms.
Parent topic: Document Overview


Reference Manual

The Reference Manualof the ACUCOBOL-GT documentation includes the following.

Introduction | An overview of the Reference Manual and information on the conventions used.
Program Structure | Describes the overall structure of a COBOL program and provides basic information about the format of user-defined words, literals, and source code.
Identification Division | Gives a detailed description of the COBOL Identification Division.
Environment Division | Describes the COBOL Environment Division.
Data Division | Describes the COBOL Data Division.
Procedure Division | Describes the COBOL Procedure Division. This also contains a complete discussion of all the verbs used by ACUCOBOL-GT.
Parent topic: Document Overview


Appendices

The Appendices part of the ACUCOBOL-GT documentation set includes the following.

Appendix A: Specifications | Compares ACUCOBOL-GT with the ANSI standard and describes internal limits set by the compiler.
Appendix B: Reserved Words | Lists ACUCOBOL-GT reserved words and notes which source dialect of each word.
Appendix C: Changes Affecting Earlier Versions | Describes features of ACUCOBOL-GT that have changed since earlier versions, and how to accommodate these differences.
Appendix D: Compiler Error Messages | Lists and describes the error messages that the compiler can generate.
Appendix E: File Status Codes | Lists file and transaction status values and their meanings.
Appendix F: Intrinsic Functions | Details the latest ANSI intrinsic function module standards for COBOL.
Appendix G: Reserved For Future Use | Is a placeholder that serves to preserve the historic placement of Appendices H and I.
Appendix H: Configuration Variables | Summarizes the entries that are available for use in the ACUCOBOL-GT runtime configuration file.
Appendix I: ACUCOBOL-GT Library Routines | Describes callable routines that are built into the runtime system. These routines may be called directly by your programs.
Parent topic: Document Overview


Getting Started

Getting Started contains information about how to install, configure, and rapidly become productive with ACUCOBOL-GT.

Parent topic: Document Overview


ACUCOBOL-GT Run-Time Manual

This Runtime Manual provides a summary of the options, variables, error codes, and utilities used with the ACUCOBOL-GT® runtime system, also known as the COBOL Virtual Machine(TM).

The ACUCOBOL-GT Run-Time Manual includes the following:

Introduction | Describes an overview of the available runtime systems.
Setting up your Terminals | A comprehensive guide to the terminal manager, the runtime module that handles keyboard input and display output for your applications.
Runtime Configuration File | Describes how to configure the runtime system using a runtime configuration file.
Runtime Options | Describes the syntax required to invoke the runtime system.
Runtime Debugger | A comprehensive guide to debugging your applications in the runtime system.
File Status Codes | Describes file status codes.
Utilities | Describes the number of utilities that are available for use with the runtime system.
Shared Memory | Describes the acushare utility for using shared memory on UNIX.
Parent topic: Document Overview


extend Product Guides

The extend Product Guides section contains a documentation set for each of the products that make up the extend Interoperability Suite:

Acu4GL | Describes how to use Acu4GL interfaces to access information stored in supported relational database management systems.
AcuBench | Describes the integrated development environment in which you can create your ACUCOBOL-GT applications.
AcuConnect | Describes how to implement a client/server environment for your applications.
AcuServer | Describes the client/server file server for your network.
AcuSQL | Describes how to use embedded SQL (ESQL) statements in COBOL programs to access SQL-conversant data sources.
AcuXDBC | Describes how to integrate COBOL data files into a relational database-like environment.
Xcentrisity Business Information Server for extend | Describes how to create a web server environment that manages application sessions and makes them available via any web browser or other web user agent.
Parent topic: Document Overview


Transitioning to ACUCOBOL-GT

Transitioning to ACUCOBOL-GT provides information on how to convert from several popular COBOL dialects to ACUCOBOL-GT. It includes sections on RM COBOL, ICOBOL, HP COBOL, and IBM DOS/VS COBOL.

Parent topic: Document Overview


A Guide to Interoperating with ACUCOBOL-GT

A Guide to Interoperating with ACUCOBOL-GT describes the capabilities and methods that enable your ACUCOBOL-GT applications to interoperate with other languages and other technologies. Topics include working with Java, working with Windows, working with C and C++, deploying on the Web, accessing mobile devices, working with OLTP systems, and working with non-COBOL data.

Parent topic: Document Overview


A Programmer's Guide to the Internet

A Programmer's Guide to the Internet is designed to teach ACUCOBOL-GT developers how to deploy applications on the Internet. It includes a description of alternative approaches to Internet deployment and specific instructions on implementing each approach.

Parent topic: Document Overview


Related Documents

Product documentation in the form of user's guides and technology supplements are included on the ACUCOBOL-GT product media and can be installed when the ACUCOBOL-GT software is installed, or installed at a later date, or accessed directly from the product media when the media is a CD-ROM. The set of documents includes information about: Acu4GL, AcuBench, AcuConnect, AcuXDBC, AcuServer, and AcuSQL. Product documentation is also available for viewing and downloading from Micro Focus's website, www.microfocus.com.

Parent topic: Document Overview


Supported Hardware

ACUCOBOL-GT is available on a wide range of machines. In this help, these machines are distinguished by their operating system. For detailed information on supported operating systems, see the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx.

  1. Native Code Supported Processors
Parent topic: Introduction


Native Code Supported Processors

The native code generation functionality of ACUCOBOL-GT currently extends to the following popular families of processors:

Intel: | Any processor matching the Intel IA-32 minimum specification such as the Pentium, Celeron or Core processor lines.
PA-RISC: | 32-bit and 64-bit PA-RISC processors under HP-UX.
PowerPC: | 32-bit and 64-bit IBM pSeries™ running under AIX®.
SPARC: | v7, v8, v9 (and compatible); 32-bit, and SPARC v9 64-bit mode.

Generated for one of these families, the native code object file is completely portable among all the supported members of that family.

Parent topic: Supported Hardware


Environment Variables

This manual often refers to the host machine's environment variables. These are values maintained by the host operating system that can be changed by the user. Exactly how an environment variable is set differs among various operating systems:

  1. With Windows NT/2000/2003/XP, environment variables are set using the System applet in the Control Panel. Windows must be restarted for the new values to take effect.
  2. With Windows 98/ME, environment variables can be defined in the autoexec.bat file (with the same syntax that's used with MS-DOS). Any changes made to the autoexec.bat file require restarting Windows to take effect. Environment variables can be defined temporarily by booting to MS-DOS mode, defining variables with the SET command and then starting Windows. Variables defined in this way persist until the system is rebooted.
  3. On Windows systems where the console runtime (crun32) is used, environment variables are inherited from the Windows environment. Temporary environment variables can be defined in the console window (DOS-box) with the SET command. For example, to set the environment variable SORT_DIR to C:\TEMP\, you would use the following line:
    SET  SORT_DIR=C:\TEMP\

    Variables defined in this way persist until the DOS-box is closed. Forward slashes (/) may be used in place of backslashes (\). Upper-case and lower-case letters are interchangeable.

  4. On UNIX and Linux systems, the environment is controlled in one of two fashions, depending on which command shell you are using. If you are using the Bourne shell (sh) or the Korn shell (ksh), then you set a shell variable to the desired value and then export that variable. For example:
    SORT_DIR=/tmp/;  export SORT_DIR

    If you are using the C-shell instead, then you use the setenv command. For example:

    setenv  SORT_DIR  /tmp/

    Upper-case and lower-case environment variables are distinct. If you are using a different shell, see the documentation for that shell, or ask your system administrator.

  5. On VAX/VMS systems, you set a symbol to the desired value. For example:
    SORT_DIR == "$DISK1:[TEMP]"

    Unlike UNIX, upper-case and lower-case variable names are treated the same on VMS.

  1. Environment Variables for Handling Temporary Files
Parent topic: Introduction


Environment Variables for Handling Temporary Files

Temporary files not placed in a specific directory via a configuration variable, such as SORT_DIR, can be directed to a specific directory by defining the A_TMPDIR or TMPDIR environment variables. The run time gives preference to A_TMPDIR. This allows users to specify an alternative temporary directory exclusively for ACUCOBOL-GT temporary files. On UNIX systems, TMPDIR is the traditional variable for specifying a location for temporary files. On Windows, the run time also checks the TEMP and TMP environment variables.

Parent topic: Environment Variables


Notation

When commands are described in this manual, the following conventions are used:

  • Plain text - any text appearing in the normal text font refers to a literal value that must be used exactly as shown.
  • Italics - any text appearing in italics refers to a generic item. These are explained in the text that follows the command.
  • Brackets - any text appearing in brackets ( [ ] ) refers to an optional item. The text following the command describes the action taken if these optional items are used.

For example, in this command:

vutil  -info  [-x]  [files]

the words vutil and -info must appear exactly as shown. The -x and files items are optional. If they are used, the -x must be typed literally while the files would be described in the text explaining the command.

Parent topic: Introduction


Handling Compilation Problems

When you compile, direct the error messages to a file, and save this file to examine. The compile command for capturing error output in a file is:

ccbl  -e  filename  program-name

From the information in this file, you will probably be able to determine the cause of the problem and make the necessary changes. If not, we would be pleased to assist you. Here's an overview of the information we need to know, most of which you can simply fax to us:

  • We need to know your hardware and operating system.
  • It's also helpful for us to know which version of the ACUCOBOL-GT compiler you are using. In case you've encountered a compiler anomaly, a later version of the compiler may solve your problem. To determine the version you are running, type: ccbl -v
  • We need a copy of the compile-time error file. If any message appears on your screen, we need the exact text of the message.
  • Finally, if you can isolate the section of the code that is causing the problem, please fax us a printed copy of this code.

Parent topic: Contacting Micro Focus
Next topic: Handling Program Execution Problems


Handling Program Execution Problems

The runtime system contains a built-in debugger that allows you to view the source code while you are debugging. To prepare to use source debugging, you must compile with one of the compiler options that include the source code in the compiled object file, such as -Ga.

For example:

ccbl  -Ga  -o  myprog  myprog.cbl

Where:

-Ga | includes the source code in the compiled object file and enables other helpful debugging features.
-o | allows you to specify the name of the output file for the object code
myprog | is the user-specified name of the output file
myprog.cbl | is the name of the file containing the COBOL source code
  1. Using the Debugger
  2. Using File Trace
  3. Using Screen Trace
  4. Working with your Technical Support Representative
Parent topic: Contacting Micro Focus
Previous topic: Handling Compilation Problems


Using the Debugger

Then, when you execute the program, specify -d to turn on the debugger. For example:

runcbl -dle errfile myprog

Where:

-d | turns on the debugger
-l | causes the contents of the runtime configuration file to be included in the error output
-e | causes the error output to be placed in the file named immediately after the option
errfile | is the user-specified name of the error file (Be sure to give a file name if you use the -e option.)
myprog | is the name of your object file

Use s to step through the program one step at a time, or use the other options described in Debugger Commands.

Parent topic: Handling Program Execution Problems
Next topic: Using File Trace


Using File Trace

Another tool that is helpful in dealing with program execution problems is the file trace feature of the debugger. It enables you to save information about all file OPENs, READs, and WRITEs. File trace can be used even if the program was compiled without the debugging option. File trace information is saved in the error file. The file trace feature is described in detail in File Tracing.

Parent topic: Handling Program Execution Problems
Previous topic: Using the Debugger
Next topic: Using Screen Trace


Using Screen Trace

Another tool that is helpful in dealing with program execution problems is the screen trace feature of the debugger. The screen trace feature enables you to save information about DISPLAYs of screen section items and CREATEs, DISPLAYs, MODIFYs, and INQUIREs of ActiveX objects. Screen trace can be used even if the program was compiled without the debugging option. The screen trace information is saved in the error file. The screen trace feature is described in greater detail in Screen Tracing.

Parent topic: Handling Program Execution Problems
Previous topic: Using File Trace
Next topic: Working with your Technical Support Representative


Working with your Technical Support Representative

We would be happy to assist you with the resolution of runtime problems. Questions that require extended research are entered into our Technical Support database and are assigned a tracking number. We use this tracking number when we phone to give you updates on our investigation.

Here's the information we'll need to start our research:

Parent topic: Handling Program Execution Problems
Previous topic: Using Screen Trace


Compiler and Runtime

  • Introduction
  • Using the Compiler
  • Using the Runtime System
  • Compatibility Modes
  • Source Formats
  • COPY Libraries
  • Source Code Control
  • Run-Time Configuration
  • File Name Interpretation
  • Calling Subprograms
  • Reducing the Size of the runtime
  • acushare Utility Program
  • General Preprocessor Interface
Parent topic: ACUCOBOL-GT User's Guide


Introduction

ACUCOBOL-GT is a single-pass ANSI X3.23-1985 COBOL compiler (ccbl). Errors encountered during compilation are displayed on the screen (or written to an error file if one is requested) referencing the line where the error was detected by source file and line number. A source listing, a symbol table listing, and general information can be created on request.

A successful compile produces an object-code file. This file is ready to be run by the ACUCOBOL-GT runtime system, runcbl. No linking is needed to run the program. Any programs that are called during execution are loaded dynamically at run time by runcbl. Subprograms written in C may be linked into the run time system directly, or loaded dynamically if packaged in a Windows DLL or UNIX/Linux shared object library, and then called by a COBOL program using the CALL verb.

Note: The compiler, the runtime, and some utility programs have different names, depending on the host system. For simplicity in this manual, we refer to the utilities by their base names (vutil, vio, logutil, and cblutil).

runcbl has a symbolic source-level debugger built into it. You can run any program under the debugger by specifying the debugger option (-d) at run time. The debugger runs in its own window, which overlays the running program. This prevents the debugger's output from interfering with the program's output.

Parent topic: Compiler and Runtime


Using the Compiler

The compiler is called ccbl. It can be run in one of three modes. These modes are:

Compile | Compiles COBOL programs
Help | Prints a command-line summary
Version | Prints the version and copyright

The compile mode is the default mode. The other modes are activated by command-line options.

To compile a program, enter the following:

ccbl [options] program

No options are required. When no options are specified, the compiler prints an error listing on the user's terminal and names the object file source-name.acu. The compiler runs in VAX COBOL compatibility mode by default.

Many options are available. These are all indicated by an initial hyphen (minus sign). These options are divided into different groups. Each group (except the first) has a distinguishing letter. For example, the options that control listings all start with the letter "L." Any set of options from the same group may be specified together. For example, the -Lo option and the -Ls option may be grouped together as -Los. See below for examples. Command-line options that begin with a hyphen are not case-sensitive. For example, -Lo and -lo are equivalent.

Options from the same group that require arguments may also be specified together, as long as the required arguments immediately follow the combined options, in the same order as the options. For example,

-o  file1  -e  file2

may also be specified as

-oe  file1  file2

The options used to compile a COBOL program are automatically embedded in the header of the resulting object file. Use the -x option of the cblutil info command to output these options.

The Compiler also supports several compiler directives. Compiler directives are directly embedded in the source code and cause the compiler to behave as specified by the directive. Support for compiler directives is likely to expand in future versions. See Conditional Compilation Options for more information.

  • Standard Options
  • Native Code Options
  • Listing Options
  • Internal Tables Options
  • Compatibility Options
  • Interoperability Options
  • Compiler File Options
  • Source Options
  • Reserved Word Options
  • Data Storage Options
  • Video Options
  • Warning and Error Options
  • Debugging Options
  • Mapping Options
  • Conditional Compilation Options
  • Miscellaneous Options
  • Upper and Lower Case
  • File Name Handling
  • Compiler Command-Line Examples
  • CBLFLAGS Environment Variable
  • Help, Version Information, and Communication With C Programs
  • The ">>IMP" Directive
Parent topic: Compiler and Runtime


Standard Options

The following table lists the standard options available to the Compiler and a brief description of each.

-e | This option must be followed by a file name (as the next separate argument). When specified, this option causes the error listing to be written to the specified file instead of the screen. This file is removed if no errors are found.The acurfap syntax can be used to specify a file located on a system being served by AcuConnect. See Remote File Name Handling for more information.
-o

This option must be followed by a file name (as the next separate argument), which becomes the name of the object file instead of source-name.int. This file is removed if the compiler detects errors in the source.

This option supports the use of acurfap syntax to create remote files and libraries. See Remote File Name Handling and Creating Remote Object Libraries for rules regarding the file name specifications for remote objects.

-v

This option has multiple applications:

  • If it is the first and only option on the command line, the compiler runs in Version mode. Using -v you can display version information, the copyright notice, and other information.
  • Otherwise, if it is used in combination with other options, it causes the compiler to be verbose about its progress.

Because -v is the lead-in sequence for the video options this option should be specified by itself.

-w | This option causes warning messages to be suppressed (a warning condition is never a fatal compilation error). Suppressing warning messages can be helpful when you are converting programs from another COBOL dialect that uses slightly different syntaxes.Note that -w negates the effect of -Wa and -Wl, which generate additional warning messages.
-x | This causes the CBLFLAGS environment variable to be ignored.See CBLFLAGS Environment Variable for more information.
Parent topic: Using the Compiler


Native Code Options

ACUCOBOL-GT supports several options that cause it to generate and execute object files that contain native instructions for select families of processors. These options can not be combined with other options into a single option. For example, it is an error to specify -nv; you must specify -n -v instead.

The compiler uses cblutil to produce the native-code object file. cblutil is installed in the same directory as the compiler by default. The compiler searches the execution path if it cannot find cblutil in its own directory.

You run a native-code object module just like a portable-code object module. You may mix native-code objects and portable-code objects in the same run. Native objects may be placed in libraries just like portable objects.

You can use the debugger with a native-code module in the same fashion as with a portable-code module. The only restriction is that you may not begin program execution at an arbitrary point in a native-code module (the @! command). Also, to prepare a native-code object for use with the debugger, you must compile the program with one of the debugging options, such as -Ga or -Gd.

To compile and run the tour.cbl program as a portable-code object, use the following commands:

ccbl tour.cbl
runcbl tour

To compile and run the same program as a native-code object, use the following:

ccbl -n tour.cbl
runcbl tour

These are the ACUCOBOL-GT Compiler native code options.

-n

This option causes the compiler to produce native code for the host machine (instead of processor-independent portable code). If native code generation is not supported for the host machine, the compiler generates an error.

The word-size of the native code generated with the -n option matches the internal word-size of the compiler, and not that of the host machine's processor. It does this because the word-size of the native code must match the internal word-size of the runtime to execute correctly. Therefore, on Windows, as the ACUCOBOL-GT compiler is 32-bit, even when running on a 64-bit machine, this option will only produce 32-bit native code. To produce 64-bit native code on Windows, use the x64_Win option listed below. On a 64-bit UNIX/Linux version of extend, you can compile native 64-bit code using either the -n option or the x64_Unix option

If you are running a program compiled with -n on either a UNIX or Windows machine that has executable memory protection enabled for all processes, ensure the runtime configuration variable USE_EXECUTABLE_MEMORY is set to TRUE (which is the default value).

--noinlineCall | This option turns off a feature that enhances the performance of called subroutines. By default, this feature is turned on, but in version 8.0 it is specified by the --inlineCall command. It is not recommended that you turn off this feature. It is useful if you have interest in testing the potential performance difference.
--intel

or

--ia-32

This option causes the compiler to produce 32-bit native code for Intel-class processors (486, Pentium, Pentium II, Pentium III, or compatible processors). You can use this option from any host machine. This is the same as specifying -n when the host machine is an Intel-class machine.
--pa_risc

or

--pa

This option causes the compiler to produce 32-bit code for PA-RISC Version 1.0 processors running the HP-UX operating system. The runtime must be a 32-bit runtime to match the code contained in the object file. The 32-bit runtime runs without modification on PA-RISC 2.0 platforms as well, providing a portable solution. You can use this option from any host machine. This is the same as specifying -n with a 32-bit compiler on an HP-UX machine.
--pa_risc_2.0

or

--pa2

This option causes the compiler to produce 64-bit code for PA-RISC Version 2.0 processors running the HP-UX operating system. Note that the runtime must be a 64-bit runtime to match the code contained in the object file. You can use this option from any host machine. This is the same as specifying -n with a 64-bit compiler on an HP-UX machine.
--power | This option produces code that is compatible with POWER and POWER2 processors, as well as PowerPC and later POWER series processors. This option allows you to use a wide range of machines, but it may affect performance.
--powerpc

or

--ppc

This option causes the compiler to produce 32-bit PowerPC native code for pSeries processors running AIX. You can use this option from any host machine. This is the same as specifying -n with a 32-bit compiler on a pSeries machine.

You can compile native code only for machines with a POWER3 or later chip, not with POWER2 or earlier.

-- powerpc_64

or

--ppc64

This option causes the compiler to produce 64-bit PowerPC native code for pSeries processors running AIX. You can use this option from any host machine. This is the same as specifying -n with a 64-bit compiler on a pSeries machine.
--sparc | This option causes the compiler to produce 32-bit native code for SPARC (v7 - v9) processors. You can use this option from any host machine. This is the same as specifying -n with a 32-bit compiler on a SPARC-based host machine.
--sparc_v9 | This option causes the compiler to produce 64-bit native code for SPARC version 9 processors. You can use this option from any host machine. This is the same as specifying -n with a 64-bit compiler on a SPARC v9-based host machine.
--x64_Win This option causes the compiler to produce x64 native code for Windows platforms. The resulting object code can only be run with a 64-bit enabled runtime.
Note: x64 object code is not portable between the Windows and UNIX/Linux platforms
--x64_Unix or --x64_Linux This option causes the compiler to produce x64 native code for UNIX/Linux platforms. The resulting object code can only be run with a 64-bit enabled runtime.
Note: x64 object code is not portable between the Windows and UNIX/Linux platforms
Parent topic: Using the Compiler


Listing Options

By default, ACUCOBOL-GT does not generate a listing. The options described below cause a listing to be created and control its contents. In addition to the items specified for these options, the listing file contains all the options given to the compiler. For example, a listing file could begin with

iobench.cbl Sat Sep 18 06:55:54 2005 ACUCOBOL-GT v7.3.0 Page: 0001
..\bin\ccbl32 -Lfo @.lst iobench.cbl
CBLFLAGS: -v -Za

Note that CBLFLAGS (or any other variable) is not included in the listing unless it is set.

-La | This option causes the compiler to create and display separate tallies for warnings and cautions. Without this switch, the compiler combines the tallies and reports the sum under the category of warnings.
-Lc

This option creates a cross-reference table at the end of the listing. The cross-reference first lists all Working-Storage data items in alphabetical order, then all section names and paragraph names. Included for each item are: the line on which the item is declared, the name of the item, and the lines on which it is referenced. A small example is shown below.

CROSS-REFERENCE

Line   Name                    Referenced on line(s)

32     ACOMMA
30     DISPLAY-FILE-STATUS     54*    62
36     ERROR-WINDOW            59*    65*
26     FILE-STATUS             44     83
35     FLD1                    44*
34     FLD1-LITERAL            43
27     FULL-FILE-STATUS        53     54*
42     MAIN-SCREEN             Unreferenced
31     PRIMARY-FILE-STATUS     Owning group referenced
28     PRIMARY-FILE-STATUS     Owning group referenced
23     RST-REC                 Owning group referenced
33     SECONDARY-FILE-STATUS   Owning group referenced
29     SECONDARY-FILE-STATUS   Owning group referenced
21     TEST-RECORD75           77     79
37     WHITE-ON-BLUE           57

testit.cbl  Thu Sep 04 10:05:42 1998 ACUCOBOL-GT v4.0 Page:0002

CROSS-REFERENCE SECTIONS/PARAGRAPHS

Line   Name                    Referenced on line(s)

69     MAIN-LOGIC
51     TESTFIL-ERR-HANDLING
49     TESTFIL-ERROR-HANDLING  50

If an item is not referenced directly, the listing indicates if the item's owning group is referenced, or if a subordinate item is referenced, or both (owning group & subordinate item).

If the compiler detects that a Working Storage data item may be removed without affecting program functionality, it prints the word Unreferenced to the right of the name of the data item. This happens only if the data item is not a group item with subordinates that are referenced, and the data item is not subordinate to a group item that is referenced.

A line number followed by an asterisk (*) indicates that the contents of the data item were modified at that line. Parameters passed in a CALL statement BY REFERENCE are always marked as modified in the listing, because it is possible that they were changed. An item that is not directly referenced but belongs to a referenced group, or is subordinate to an item that is referenced, is so indicated. When a full listing is requested with a cross-reference (-Lfc), line numbers are placed in columns 3 through 9 of the listing.

The first three columns of the listing indicate the copy files. Each line of a copy file is indicated, with the nest level number followed by a greater than symbol (>). The nest level number is 1 for a copy file included directly in the main source file, 2 for a copy file that is included in a level 1 copy file, 3 for a copy file included in a level 2 copy file, and so on. An example of a copy file listing is shown under the -Lw option.

-Lf | This options creates a full listing of the source program including the text of the COPY libraries.
-Li | This option creates summary information about the program compiled. This is automatically set by any of the -L options.
-Ll | This option sets the page length of the listing. This option must be followed by the number of lines per page (as the next separate argument). Specifying a negative number or zero (0) for the argument produces a continuous listing without page headers or form feeds (a blank line separates different sections of the listing).
-Lo | This option must be followed (as the next separate argument) by the name of the file to hold the listing. If this option is not specified, the listing is written to the standard output. This may be redirected to a file or a printer using the normal operating system commands. The acurfap syntax can be used to specify a file located on a system being served by AcuServer or AcuConnect. See Remote File Name Handling.
-Lp

This option directs the compiler to produce a preprocessed output file that can later be compiled to produce the same object code as the original source. The output includes the content of all COPY files and the results of all COPY REPLACING and REPLACE logic; the output does not include any comments or formatting from the original source. The output is sent to the standard output stream unless -Lo is used to specify a file. -Lp overrides all other listing options except -Lo.

This option is especially useful if your COPY files contain statements that other preprocessors don't allow in COPY files, such as embedded SQL or CICS statements. To compile such a program, you first create the preprocessed file and then compile it. For example:

ccbl -Lpo finalsrc.cbl -sp copybooks origsrc.cbl
   ccbl -Ga -o myprogram.acu finalsrc.cbl
Note: If the preprocessed code is subsequently compiled to include debugging symbols, the code displayed in the debugger is, of course, the preprocessed code, which does not include comments or formatting.
-Ls | This option creates a symbol table at the end of the listing.
-Lw

This option specifies a wide listing format and implies a full listing (thus -Lw is equivalent to -Lfw). The listing uses 101 characters to display copy book indicators, line numbers, relative line numbers, program addresses, sequence numbers, and the rest of each source line.

For multiple-line sentences, the address of the first verb of each line is shown.

The first three columns indicate copy files. Each line of a copy file is indicated, with the nest level number followed by a greater than symbol (>). The nest level number is 1 for a copy file included directly in the main source file, 2 for a copy file that is included in a level 1 copy file, 3 for a copy file included in a level 2 copy file, and so on. Following is a portion of a listing that shows a copy file:

   50                main-logic.
   51    000002         copy "copyfile".
1> 52               *
1> 53                   display "COPY file".
1> 54               *
   55    00000E         display window
   56                      size 40 lines 10
   57                      line 10 col 10 boxed
   58                      pop-up area is error-window.
-Lx | This option creates extended statistics at the end of the listing.
Parent topic: Using the Compiler


Internal Tables Options

The ACUCOBOL-GT compiler makes use of several internal tables for storing information about the COBOL program it is compiling. Most of these tables are dynamically resized as needed during compilation. A few of them are allocated a fixed amount of space. The amount of space allocated to the fixed size tables is enough for the vast majority of programs, but occasionally a program will require more space than is allocated by default. When this occurs, the compilation fails and a *** %s overflow *** error message is output. (See Appendix D, ACUCOBOL-GT Appendices manual for a more detailed explanation of the error.) In such cases, the user can increase the amount of space allocated to that table by including the appropriate -T compilation switch on the compiler command line.

The switches are:

-Td #### | Identifier and statement table — sets the maximum number of items in each statement. The default value is 4096.
-Te ### | Subscript statement table — sets the maximum size for OCCURS statements. The default value is 256.
Note: The compiler error message always suggests that you double the size of the default value. However, doubling the size is not always the best approach. Ideally, the size of the table should not be substantially larger than what is needed to compile the program.
Parent topic: Using the Compiler


Compatibility Options

ACUCOBOL-GT has several options that aid in converting programs written for other COBOL environments. By default, ACUCOBOL-GT runs in the VAX COBOL compatibility mode. See Compatibility Modes for more information.

-Ca       This option causes simple ACCEPT and DISPLAY statements to be treated in accordance with ANSI semantics. Specifying this option is the same as specifying FROM CONSOLE for all simple ACCEPT statements and UPON CONSOLE for all simple DISPLAY statements. You can control this behavior for individual ACCEPT or DISPLAY statements by specifying an explicit FROM/UPON phrase.See ANSI ACCEPT and DISPLAY Verbs for more information.

Prior to Version 2.1, -Ca was a synonym for the compile-time option -Va. If you have an obsolete reference to -Ca in any of your compile scripts, or in your CBLFLAGS environment setting, make sure that you change this to -Va.

-Cb | This option causes all sequential files that are not explicitly specified as LINE or BINARY sequential to be treated as BINARY sequential. Normally the file type is determined by a long sequence of rules. Files specified as print files are treated as LINE sequential even when this option is selected.
-Ce

This option allows you to specify a default source name extension that is used for both the main source file and its COPY files. When it is specified, any source or COPY file name that does not explicitly specify an extension has the default extension appended to it. When the option is specified in RM/COBOL compatibility mode, the default extension is .CBL. Otherwise, the default is .COB.

You may specify an alternate default by naming it after an = sign in the -Ce option. For example, the option -Ce=CPY would cause the default extension to be .CPY.

ACUCOBOL-GT automatically adjusts the extension for upper or lower case to match the case of the name it is being appended to, then searches for the COPY file. If this first search fails, ACUCOBOL-GT matches the case of the extension specified in the -Ce compiler option to perform a second search for the COPY file.

-Cf | This option forces all indexed, relative, and binary sequential files to be given fixed-length records. Normally the record type is determined by a sequence of rules. This flag is supplied to enhance compatibility with pre-85 compilers and earlier versions of ACUCOBOL-GT.
-Cg | Turns off the conditional compiling features. In version 8.1.0 (ECN 3607) conditional compilation was added to ACUCOBOL-GT. Conditional compiling statements begin with the $ sign. In prior versions, lines of code that began with the $ sign were treated as comments. Unfortunately, some COBOL programs use a type of conditional compilation, which now fail to compile. Turning off conditional compiling should rectify these situations. See Conditional Compilation Options for information on conditional compiling.
-Ci | This option causes the compiler to be compatible with ICOBOL for certain COBOL constructs. References in this manual to VAX COBOL compatibility also apply to ICOBOL compatibility mode unless otherwise stated.
-Ck

This option causes the compiler to generate key numbers for indexed file alternate keys in a different order. Key numbers are used internally by the compiler and runtime to identify a key. Normally, you don't need to know the key number for a particular key, or care about the order in which they are generated. By default, the compiler sorts the alternate keys in record order before assigning key numbers. This ensures that the keys are given the same number regardless of the ordering in the file's SELECT. Specifying -Ck causes the compiler to assign key numbers in the SELECT order.

For most applications, the order in which key numbers are assigned is irrelevant. This option provides compatibility with some other COBOL compilers. This could be helpful when you are sharing data files between ACUCOBOL-GT-based programs and programs compiled with these other systems.

-Cm

This option causes the compiler to be compatible with IBM/COBOL for the ASSIGN phrase of a SELECT statement. The syntax for the IBM/COBOL ASSIGN phrase is:

ASSIGN TO <filename-1> [<filename-2>
                <filename-3> ...]

where <filename-1>, <filename-2>, and <filename-3> are file identifiers.

Compiling with the -Cm option allows the IBM/COBOL ASSIGN phrase to ignore <filename-2> and <filename-3>. If <filename-1> contains any "-" characters, only the characters following the last "-" will constitute the file name assignment for the particular SELECT command. For example:

SELECT TESTFILE ASSIGN TO SYS000-AS-TEST1

results in a file called TEST1.

All of the existing ACUCOBOL-GT SELECT phrases and options can be used with the IBM/COBOL ASSIGN phrase.

-Cp | This option sets the compiler to its HP COBOL compatibility mode. In this mode, it accepts features of HP COBOL that are not otherwise accepted.
-Cr | This option sets the compiler to its RM COBOL compatibility mode. In this mode, it accepts features of RM COBOL that are not otherwise accepted.
-Cv This option sets the compiler to its IBM DOS/VS compatibility mode. In this mode, it accepts features of IBM DOS/VS COBOL that are not otherwise accepted.

Since there are slight differences between IBM COBOL versions, -Cv also takes the following optional arguments:

-Cv=OSVS specifies OSVS compatibility.

-Cv=VSC2 specifies VSC2 compatibility.

-Cv by itself defaults to OSVS mode. The two modes are very similar, except that in VSC2 compatibility mode, the following words are not reserved:
  • CURRENT-DATE
  • EXAMINE
  • TIME-OF-DAY
  • TRANSFORM

Note that CURRENT-DATE is a valid function in any compatibility mode.

-C3 This option causes ACUCOBOL-GT to abide by the rules used by Version 1.3. Later versions changed the way ACUCOBOL-GT treats a few special cases. If you use this flag, ACUCOBOL-GT will treat these cases in the same way it did under Version 1.3. This is useful if you are compiling programs written for Version 1.3 and you do not want to modify the programs. See Appendix C. Changes Affecting Previous Versions for details of which features are affected by this option.

Specifying this option does not prohibit the use of later features, but merely ensures that the changed features behave in the original fashion. Compare with the -Z3 option below.

-C4 | Similar to -C3, this option causes the compiler to generate code according to the rules used by Version 1.4.
-C5 | This option causes the compiler to maintain source compatibility with the Version 1.5 compiler.
-C20 | This option causes the compiler to maintain source compatibility with the Version 2.0 compiler. Chart verbs are allowed.
-Cnn This option causes the compiler to maintain source compatibility with the Version nn compiler.

nn is the version number of product; for example, -C21 for version 2.1, -C60 for version 6.0, and so on. From version 10.0 onwards, 3 digits are used to represent the version number; for example -C100 for version 10.0, -C101 for version 10.1, and so on.

Parent topic: Using the Compiler


Interoperability Options

--javaclass     | Generates a .java file in addition to an .acu file. The .java file has the same prefix as the .acu file and is placed in the same directory. This .java file is a Java class that calls the COBOL program being compiled. See Calling COBOL from Java for more information.
--javamain     | Generates a .java file in addition to an .acu file. The .java file has the same prefix as the .acu file and is placed in the same directory. This .java file is a Java class with a main method added. This class calls the COBOL program that is being compiled. See Calling COBOL from Java for more information.
--netexe

Generates a .NET executable file for command-line execution. The name of the executable file is the name of the program followed by .exe. All valid ACUCOBOL-GT command-line options can be specified with the executable file, as well as any of the following Linkage Section parameters:

  • -int:
  • -string:
  • -uint:
  • -short:
  • -ushort:
  • -float:
  • -double:
  • -long:
  • -ulong:
  • -byte:

See Calling COBOL from Java for more information.

Note: On Windows 7, compiling with this option may fail due a missing al.exe, which is not included as a utility with Windows 7. To fix this, download and install the Microsoft .Net framework SDK and then try compiling with this option.
--netdll Generates a .NET dynamic link library (DLL) that gives .NET assemblies — both executables and DLLs — a programmatic interface to your COBOL program. All COBOL entry points are exposed as .NET methods along with ACUCOBOL-GT runtime properties and methods. This allows .NET programmers to set ACUCOBOL-GT command options and call runtime interfaces from their .NET assembly.
Note: On Windows 7, compiling with this option may fail due a missing al.exe, which is not included as a utility with Windows 7. To fix this, download and install the Microsoft .Net framework SDK and then try compiling with this option.
Parent topic: Using the Compiler


Compiler File Options

Some file options (-Fa, -Fe, -Fx, and -F4) are used to generate XFD files (data dictionaries) that are used with Acu4GL, AcuXML, the alfred record editor, and with international character mapping for AcuXDBC and AcuServer. Other file options (-Fl, -Fs, -Ft) can simplify the addition of transaction management facilities to existing programs that use the Vision file system.

For more details regarding transaction management, see Transaction Management. For more details about international character mapping, see International Character Handling.

-Fa This option tells the compiler to build data dictionaries (XFD files) for every indexed, relative, and sequential data file in the FDs of the program. It is the only option that builds XFDs for relative and sequential files. This option is also used for AcuXML file translation and for international character mapping. See also the -Fo compile-time option, which specifies the directory in which the data dictionaries are placed.

The -Fa option generates the most current format for the XFD files (Version 6). (XFD versioning is distinct from Vision versioning.) Any version of Vision will work with any version of XFD, as long as the XFD version can store all the necessary precision of the Vision file. (For example, if you are using Vision Version 5 and you want to use a larger record size than what can be stored in 5 digits, then you will need to use Version 5 XFDs.)

An attempt to use the -Fa option with a backwards-compatibility switch results in a warning and the XFDs for RELATIVE and SEQUENTIAL files are not created. An attempt to use this option for records containing duplicate element names also results in a warning; however, if you are creating XFDs for AcuXML, you may disregard this warning. XFDs will be generated, and XML supports duplicate names.
-Fc | This option causes the field names in generated XFD files to match exactly the source of the COBOL program that generated them.
-Fe | This option causes XFD files to be generated in standard flat text format rather than XML format. Acu4GL, AcuXDBC, and alfred can all read XFD files in XML format. This option must be used in conjunction with the -Fx or -Fa options. The C$XML library routine can be used to parse the XML files if desired. This option will not work in combination with -F4 or -F3. Version 4 and 3 XFD files cannot be generated in XML format.
-Fl | This option enables single locking rules rather than multiple locking rules as the lock mode default. Normally, WITH ROLLBACK causes multiple locking rules to be in effect for a file. When -Fl is used, the WITH ROLLBACK clause does not affect whether single or multiple record locking rules are followed. Single locking becomes the default. You may enable multiple locking either by specifying WITH LOCK ON MULTIPLE RECORDS in a file's SELECT statement or by using APPLY LOCK-HOLDING ON file in the I-O CONTROL paragraph.
-Fm | This option causes LOCK MODE IS MANUAL to be applied when the LOCK clause is omitted from the SELECT statement in the FILE-CONTROL paragraph.
-Fn

This option specifies file locking as the default behavior for files that do not have locking or sharing already specified or implied from within the program. This option can improve batch processing times and make file access more restrictive for programs that do not specify any form of file locking.

This option implies a lock on any OPEN statement contained in the program. The implied lock is based on the OPEN format as follows:

  • OPEN INPUT - ALLOWING READERS
  • OPEN OUTPUT - ALLOWING NO OTHERS
  • OPEN EXTEND - ALLOWING NO OTHERS
  • OPEN-I-O ALLOWING NO OTHERS

If the following file locking or sharing methods are applied to a file, the -Fn has no effect:

  • SELECT contains a LOCK phrase. The specified or implied behavior of the LOCK phrase is used
  • The OPEN statement contains the EXCLUSIVE, LOCK, MASS-UPDATE, BULK-ADDITION, or ALLOWING phrases. The sharing attributes that these phrases set are used

See OPEN Statement for details on applying file locks and sharing.

-Fo

This option must be followed (as the next separate argument) by the directory that will hold the data dictionary files generated by the compiler with you use the -Fx option.

Type a space after the option and then give the name of the chosen directory. If this option is not used, the XFDs are placed into the current directory.

For example, to cause the data dictionaries to be stored in the directory /usr/inventory/dictionaries you would enter:

-Fo /usr/inventory/dictionaries

The acurfap syntax can be used to specify a location on a system being served by AcuServer or AcuConnect. For information about acurfap syntax, see Remote File Name Handling.
-Fp | This option causes all files, except sort files, to be treated as if the OPTIONAL phrase is specified in the SELECT statement.
-Fs | This option causes an implied START TRANSACTION verb before the first OPEN, CLOSE, WRITE, REWRITE, or DELETE and after each COMMIT or ROLLBACK. In effect, every file operation is part of a transaction. If this option is enabled, and the compiler encounters a START TRANSACTION verb, it reports a warning and does not generate any code for the START TRANSACTION. The -Fs option provides an alternate way to program transactions and is often useful when you are converting from other COBOL or SQL implementations. Transaction management is discussed in detail in Transaction Management.
-Ft | This option causes implied transactions for every OPEN, CLOSE, WRITE, REWRITE, or DELETE that is not part of an explicit transaction. Single file operations that are not part of a transaction are preceded by an implied START TRANSACTION and followed by an implied COMMIT. This option makes converting existing applications to a transaction system easier. Note that unlike most COMMITs, which unlock all of the file's currently locked records, the implied COMMIT does not unlock any records. See Extended Locking Rules for details regarding file locking and the handling of implied transactions.
-Fx This option directs the compiler to build Version 6 data dictionaries (XFD files) for every indexed data file in the FDs of the program. If you need an older version of XFD files, specify the -F3, -F4 or -F5 option instead of -Fx. If you use relative, sequential, or XML data files, use the -Fa option instead. Use the -Fo option to specify the directory in which the data dictionaries should be placed.
Note: XFDs are required if you plan to use any Acu4GL interface, AcuXDBC, or AcuXML; these interfaces cannot operate without data dictionaries. XFDs are also required for international character mapping with AcuServer and they provide useful information to the alfred record editor. XFD files have tthree different formats: Version 4, Version 5 and Version 6. Database technologies in the extend6 Interoperability Series, including AcuXML, require Version 5 XFDs. Version 4 XFDs are required for previous versions of Acu4GL, alfred, and AcuODBC (Version 5.x and earlier).
-F4 | This option tells the compiler to build Version 4 data dictionaries (XFD files) for every indexed data file in the FDs of the program. This older version of the XFD files is compatible with Acu4GL, AcuODBC, and Version 5.x and earlier. To build Version 4 XFDs for every indexed, relative, and sequential data file in your FDs, combine -F4 with -Fa, as in ccbl -F4 -Fa.
-Fxa | Supported but obsolete. It produces the same result as -Fa.
--fileAssign=

This option allows you to specify how to assign a filename when neither DYNAMIC or EXTERNAL is part of the ASSIGN clause of the SELECT statement. The "=" must be followed by the keyword DYNAMIC or EXTERNAL. For example,

--fileAssign=external

causes the compiler to treat SELECT statements that do not specify DYNAMIC or EXTERNAL in the ASSIGN clause, as if EXTERNAL were specified.

--fileIdSize=#        | Specifies the size, in bytes, of file handles passed to COBOL programs. # is replaced by the value , 4, or 8 to specify the number of bytes in the passed integer. A four-byte native integer is passed by default. A two-byte native integer is used in HP COBOL compatibility mode (-Cp).
Parent topic: Using the Compiler
Parent topic: Compiler and Runtime Options


Source Options

The source options modify the way the compiler treats the physical source files.

-S#       | Specifying a digit with -S causes ACUCOBOL-GT to use alternate tab stops for its source files. By default, ACUCOBOL-GT sets tabs every eight columns. When this option is used, tabs will be set every # columns apart, where # is the number specified. For example, -S4 will set tab stops at every fourth column. Tab stops always start in column 1.
-Sa | This causes the compiler to assume that the input source is in the standard ANSI source format. See Source Formats for more information. This option can be specified in a compiler directive. See Conditional Compilation Options for more information.
-Sc

This option must be followed by one of the following encoding scheme identifiers: BIG5, DBC, EUC, GB, KSC, or SJC. When used, this option causes the compiler to assume that the input source is encoded using the specified encoding scheme. This allows the compiler to recognize double-byte characters used in string literals and comments. The table below shows the encoding scheme identifiers, the code system to which each setting refers, and some examples of operating systems to which the particular encoding scheme applies:

Setting  Code System            Op. System Example
BIG5     Big Five (Taiwan)      Chinese DOS, Windows
DBC      ACUCOBOL-GT            other double-byte machines
         Generic
         Double-byte
         Coding Scheme
EUC      Extended UNIX          Most UNIX machines
GB       Code of Chinese        Chinese DOS, Windows
         Graphic Character
         Set (Peoples's
         Republic of China)
KSC      Korean Character       Korean DOS
         Standard
SJC      Shift JIS Code         DOS/V, Windows, some UNIX
         (Japanese Industrial   machines
         Standard)
-Sd | Setting this option causes debugging lines marked with D in the indicator area to be treated as normal source lines instead of comment lines. This is equivalent to supplying the phrase WITH DEBUGGING MODE in the SOURCE-COMPUTER paragraph.
-Si | This option causes the compiler to include source lines according to a pattern in the Identification Area of the source line. The next (separate) command-line argument is treated as this pattern. (The pattern is case-sensitive; enclose it in double quotes on systems such as VMS where you need to preserve its case.) See Source Code Control for details on source code control and the use of this option.
-sl | This option allows AREA B to extend to the end of the line, regardless of line length. Alternatively, you can obtain this behavior by setting the >>IMP MARGIN-R IS AFTER END OF RECORD source file directive.
-Sp With this option you can specify a series of directories to be searched when the compiler is looking for COPY libraries. This option is followed (as the next separate argument) by the set of directories to search.

See COPY Libraries for more information.

The acurfap syntax can be used to specify a location on a system being served by AcuServer or AcuConnect.

-Sr | This option causes ACUCOBOL-GT to use RM/COBOL-style tab stops. These tabs are set four columns apart starting in column 8 and ending at column 72.
-St | This option forces the compiler to use the terminal source format. See Source Formats for more information. This option can be specified in a compiler directive.
-Sx | This option is similar to the -Si option, except that the next argument is treated as a pattern to use to exclude source lines.
Parent topic: Using the Compiler


Reserved Word Options

ACUCOBOL-GT provides the ability to suppress certain sets of reserved words. When suppressed, these words are treated as user-defined words instead. This ability is provided to aid in converting programs written for other COBOL environments. Reserved words that have been added to the 1974 standard are divided into the groups identified below. By specifying the corresponding option, you cause that group of words to be treated as user-defined words.

Reserved Word List in the ACUCOBOL-GT Appendices, includes a list of reserved words and shows which group each word belongs to. Some words belong to more than one group. Every group a word belongs to must be suppressed for the word to be treated as a user-defined word.

-R2 | Suppresses words reserved by the 2002 COBOL standard.
-R8 | Suppresses words reserved by the 1985 COBOL standard.
-Ra | Suppresses words reserved by ACUCOBOL-GT that are required for its unique extensions.
-Rc
Allows you to change a reserved word. This option must be followed by two separate arguments: The first is the reserved word you want to change. The second is the word that you want to use instead. For example,
-Rc TITLE NAME
will allow you to use "TITLE" as a user-defined word and will cause the word NAME to be treated as the reserved word TITLE. You may not specify a word that is already reserved as the new reserved word. This option may be repeated to transform multiple reserved words.
-Ri | Suppresses words reserved by ICOBOL that are not in the 1985 standard.
-Rn
Allows you to make a reserved word a synonym for another reserved word. This option must be followed by two separate arguments: The first is the reserved word for which you want a synonym. The second is the word that functions as the synonym. For example,
-Rn COMP COMP-5
causes COMP-5 to be treated the same as the reserved word COMP. This option may be repeated to make multiple synonyms.
-Rr | Suppresses words reserved by RM/COBOL that are not in the 1985 standard.
-Rs | Suppresses words added to ACUCOBOL-GT in order to support the Screen Section.
-Rv | Suppresses words reserved by VAX COBOL that are not in the 1985 standard.
-Rw

This option allows you to suppress a particular reserved word. The option must be followed (as the next separate argument) by the reserved word you want to suppress. This option may be repeated to suppress multiple reserved words.

This option also allows you to suppress some non-reserved words, such as control names (for example, entry-field and label) or property names (for example, max-text and bitmap-number). If you tell the compiler to suppress a non-reserved word, it issues the following warning:
Unknown reserved word: non-reserved word
-Rx | This option tells the compiler to ignore a particular word. The option must be followed (as the next separate argument) by the word you want the compiler to ignore. This option may be repeated to ignore multiple words.
Parent topic: Using the Compiler


Data Storage Options

See USAGE Clause for more information about the format of a data item in memory.

-Da

This allows you to specify the data alignment modulus for level 01 and level 77 data items. Normally, level 01 and level 77 data items are aligned on a 4-byte boundary (modulus 4). This is optimal for 32-bit architectures. You can specify an alternate alignment boundary by following this option with the desired modulus. This should be specified as a single digit that immediately follows the -Da as part of the same argument. For example, -Da8 specifies that data should be aligned on 8-byte boundaries, which can provide improved performance on a 64-bit machine.

-Db | This causes COMPUTATIONAL data items to be treated as if they were declared as BINARY data items. This is the default when you are using VAX COBOL compatibility mode.
-De | This causes the compiler to generate MOVE code for all LINKAGE data items that works regardless of the alignment of the data item. The move is, however, less efficient. Please note that this option should be used only if the linkage is given values using the SET ADDRESS OF verb.
-Dca     | This selects the ACUCOBOL-GT storage convention. It is the default setting. This convention is also compatible with data produced by RM/COBOL (not RM/COBOL-85) and previous versions of ACUCOBOL-GT. It also produces slightly faster code.
-Dcb

This selects the MBP COBOL sign storage convention.See the topic USAGE Clause for the specifics of sign storage.

Note that the MBP COBOL sign storage convention for USAGE DISPLAY directly conflicts with that used by IBM COBOL and some other COBOLs. As a result, signed USAGE DISPLAY items in the MBP format are correctly understood only when the program is compiled with -Dcb. This is unlike the other sign conventions in which the runtime can usually extract the correct value even when a mismatched sign convention is specified at compile time.

Also note that MBP COBOL does not have the COMP-2 storage type. The convention that ACUCOBOL-GT implements (Positive: X"0C"; Negative: X"0D") was chosen because MBP COBOL most closely matches the sign storage of other COBOLs that use that convention.

-Dci | This selects the IBM storage convention. It is compatible with IBM COBOL, as well as with several others including RM/COBOL-85. It is also compatible with the X/Open COBOL standard.
-Dcm | This selects the Micro Focus storage convention. It is compatible with Micro Focus COBOL when the Micro Focus ASCII sign-storage option is used (this is the Micro Focus default).
-Dcn | This causes a different numeric format to be used. The format is the same as the one used when the -Dci option is used, except that positive COMP-3 items use X"0B" as the positive sign value instead of X"0C". This option is compatible with NCR COBOL.
-Dcr | This selects the Realia sign storage convention. Sign information for S9(n) variables is stored using the conventions for Realia COBOL, and their conversion to binary decimal is the same as that performed by the Realia compiler.
-Dcv

This creates numeric sign formats that are compatible with VAX COBOL. These are identical to the IBM formats, except that unsigned COMP-3 fields place X"0C" in the sign position, instead of X"0F".

The ANSI definition of COBOL does not state how signs should be stored in numeric fields (except for the case of SIGN IS SEPARATE). As a result, different COBOL vendors use different conventions. By using the options -Dca, -Dci, -Dcm, -Dcn, or -Dcv, you may select alternate sign-storage conventions. Doing so is useful in the following cases:

  • If you need to export data to another COBOL system and need to match its sign-storage convention.
  • If you are importing data from another COBOL system, and that data contains key fields with signed data. Keys are treated alphanumerically, so if you use the incorrect sign-storage convention, ACUCOBOL-GT will not find a matching key when it is doing a READ.
The storage-convention affects how data appears in USAGE DISPLAY, COMP-2, and COMP-3 data types.

For additional information and tables, see USAGE Clause.

-Dd31 | This option supports data items with up to 31-digits or 16 bytes. When this option is in effect, you may use as many as 31 X or 9 symbols in a PIC, instead of the usual 18. The maximum number of bytes in a COMP-X or COMP-N data item, whose picture contains only "X" symbols, is 16, instead of the usual 8. Intermediate results are calculated to 33 digits instead of the usual 20.
-Df

This option changes the way the compiler treats data items declared as COMP-1 and COMP-2. Some compilers use COMP-1 and COMP-2 to specify single- and double-precision floating-point data items. ACUCOBOL-GT, however, assigns a different meaning to COMP-1 and COMP-2 and uses FLOAT and DOUBLE to specify floating-point data items.When the -Df option is used, the compiler treats data items declared as COMP-1 as if they were declared FLOAT and data items declared as COMP-2 as if they were declared DOUBLE. With the -Df option, you have the following correspondence:

COMP-1   FLOAT    single precision
COMP-2   DOUBLE   double precision

The -Df option makes it easier to compile code originally written for another compiler — one that used COMP-1 and COMP-2 to specify floating point data items. The -Df option lets you compile such code without having to change COMP-1 and COMP-2 to FLOAT and DOUBLE.

-Di

This option causes the compiler to initialize Working-Storage. Normally, the compiler will initialize all data items to spaces or the value specified with the -Dv option, except for those items given a VALUE clause. If this option is specified, data items are initialized according to their type:

  • Alphabetic, alphanumeric, alphanumeric edited, and numeric edited items are initialized to spaces.
  • Numeric items are initialized to zero.
  • Pointer items are initialized to null.
  • Index items are initialized to 1.

Automatic initialization applies only to Working-Storage and does not apply to any item that (a) is given a VALUE clause, (b) is EXTERNAL, or (c) is subordinate to a REDEFINES phrase.

-Dl | This option allows you to limit the maximum alignment modulus that will be used for SYNCHRONIZED data items. Normally, a synchronized data item is aligned on a 2-, 4-, or 8-byte boundary depending on its type. This option allows you to specify an upper bound to the modulus used. This is specified as a single digit that immediately follows the -Dl as part of the same argument. For example, -Dl4 specifies that the maximum synchronization boundary is a 4-byte boundary. If you want to make programs that are compliant with the 88/Open COBOL specification, you should specify -Dl4. This option can be specified in a compiler directive. See Conditional Compilation Options for more information.
-Dm | This option causes any data item whose underlying type is binary to be stored in the minimum number of bytes needed to hold it. Normally, binary types are stored in two, four, or eight bytes. This option allows storage in any number of bytes ranging from one to eight. The exact number of bytes used for a particular data item is described under the USAGE clause in the ACUCOBOL-GT Reference Manual.
-Dq | Causes the QUOTE literal to be treated as an apostrophe, or single quotation mark, rather than as a double quotation mark ("). One exception to this is the HP COBOL TRANSFORM verb, in which QUOTE is always treated as a double quotation mark.
-Ds | This causes USAGE DISPLAY numeric items with no SIGN clause to be treated as if they were described with the SIGN IS TRAILING SEPARATE clause. Several versions of RM/COBOL behave this way (all versions before 2.0, and some versions afterward).
-Dv This option allows you to specify the default byte (initial value) used to initialize any data item not otherwise initialized when the program is loaded. The option must be followed by an equals sign (=) and the decimal value of the byte to use (for all current platforms, this is the ASCII value of the desired character). For example, to fill memory with the NULL character, use -Dv=0. To fill memory with the ASCII space character, use -Dv=32.

The default value is the space character.

-Dw

This option lets you modify the definition of certain data types. These data types are generally dependent on the host machine's native word size. You may use this option to:

  1. Maintain compatibility with COBOL source code written specifically for 32-bit machines (for example, to set the size of USAGE POINTER data items to 4 bytes).
  2. Make it easier to match a C structure for a particular machine.
  3. Optimize your data storage for a particular class of machines.

-Dw selects the maximum word size of the set of machines that you expect to run on. You follow this option with the maximum word size you desire, expressed as the number of bits per word. Currently, the legal forms are -Dw32 and -Dw64.

This option determines the maximum word size, not the exact word size.

The -Dw option affects the size of the following data types:

  • SIGNED-SHORT
  • SIGNED-INT
  • SIGNED-LONG
  • POINTER
  • UNSIGNED-SHORT
  • UNSIGNED-INT
  • UNSIGNED-LONG

It also affects the size of the RETURN-CODE special register.

Selecting a maximum word size does not inhibit the portability of your code. Instead, it limits the size of certain data items. If you attempt to use a data item that is too small for a particular machine, you may lose precision. For example, USAGE POINTER data items are stored in 4 bytes if you use -Dw32. If you attempt to run a program that stores an address in 4 bytes on a 64-bit machine, you may lose some of the address. While the program will technically run, the results may not be useful.

For maximum portability, you should use -Dw64. This will allow your code to run on all machines that run ACUCOBOL-GT. However, if your program will call Windows DLLs, you should use -Dw32. For strict compatibility with ACUCOBOL-85 Version 2.2 or earlier, you should use -Dw32. For programs prior to Version 2.3, the only real affect of shifting from -Dw32 to -Dw64 is the USAGE POINTER data types expand from 4 bytes to 8 bytes. If your program does not depend on the size of POINTER data items, then you should be able to use -Dw64 with no harm.

If you use any of the -C compile options that establish source compatibility with ACUCOBOL-85 Version 2.2 or earlier (for example, -C21, then the default setting is Dw32 If you do not use these options, then the default setting is -Dw64. You may override the default by using the -Dw option. For example, to compile for source compatibility with Version 2.1, but to set the target architecture to 64 bits, you would use -C21 -Dw64. In order to use -Dw64, you must use a Version 2.3 or later runtime.

See USAGE Clause for more information.

-Dy | This option specifies that all data items whose underlying representation is binary should be treated as if they were described as SYNCHRONIZED. This option is not recommended unless you have a particular need for it. ACUCOBOL-GT is optimized for non-synchronized handling of binary data, so synchronization will usually not have beneficial results. Note, however, that you must specify this option if you want to make programs that are compliant with the 88/Open COBOL specification.
-Dz

This option causes the compiler to modify its size checking rules for numeric items. Instead of computing size error by examining the number of 9's in an item's picture, the compiler computes size error by examining the actual storage for that item. For example, normally a PIC 99 BINARY data item cannot hold a number larger than 99, although the storage for the item can hold a value up to 255. When -Dz is used, ACUCOBOL-GT will not cause a size error until a value greater than 255 is moved to this item. This option also affects truncation in MOVE statements and implied moves.

There are four truncation options in all. See Truncation Options for description and comparison information on these options.

-D1 | This option causes any data item whose underlying type is binary to be stored in one byte if that data item has only one or two digits. Normally, such a data item would be stored in two bytes.
-D2 | This option causes COMPUTATIONAL data items to be treated as if they were declared as COMPUTATIONAL-2. This is the default when you are using RM/COBOL compatibility mode.
-D5 | This option causes data items declared as BINARY to be treated as if they were declared as COMPUTATIONAL-5. This causes the values to be stored in the host machine's native byte-ordering instead of the machine-independent byte-ordering normally used. This option should be used with caution, because it can lead to programs that are not portable.
-D6 | This option causes unsigned data items declared as PACKED-DECIMAL to be treated as if they were declared as COMPUTATIONAL-6. This saves one-half of a byte because the compiler will not generate any storage for the sign.
-D7 This option allows you to match one of the binary storage conventions used by Micro Focus COBOL. That convention is identical to the ACUCOBOL-GT -Dm convention, except that a PIC 9(7) data item (unsigned) is stored in 3 bytes instead of 4 and a PIC 9(12) data item (unsigned) is stored in 5 bytes instead of 6. When you use this option, the size of a binary item is determined as follows (the value in the table is the number of bytes occupied by the data item):
Number of          Signed             Unsigned
9's in PIC         Storage            Storage
1 - 2              1                  1
3 - 4              2                  2
5 - 6              3                  3
7                  4                  3
8 - 9              4                  4
10 - 11            5                  5
12                 6                  5
13 - 14            6                  6
15 - 16            7                  7
17 - 18            8                  8
--FpRounding

Simulates the behavior of other COBOL systems with regard to implied rounding when floating point is used in a math statement.

This case-insensitive option is followed by an equals sign (=) and one of the following:

  • OSVS means that any math statement that contains a floating-point data item as a sending item has ROUNDED implied for every receiving item.
  • VSC2 means that any math statement that contains a floating-point data item as either a sending item or a receiving item has ROUNDED implied for every receiving item.

If --FpRounding is not specified, rounding is not automatically implied.

For example, consider the following program fragment:

77 INT-1 PIC 99.
77 FLOAT-1 USAGE FLOAT.
MOVE 1.6 TO FLOAT-1
COMPUTE INT-1 = 3 * FLOAT-1.

Without this compiler option, the value moved to INT-1 is 4 (4.8 truncated). If either --FpRounding=OSVS or --FpRounding=VSC2 is specified, the value moved would be 5 instead (4.8 rounded up).

Alternatively, the following example:

77 INT-1 PIC 99.
77 DEC-1 PIC 99V99.
77 FLOAT-1 USAGE FLOAT.
MOVE 1.6 TO DEC-1
COMPUTE FLOAT-1, INT-1 = 3 * DEC-1

would move 5 to INT-1 only if --FpRounding=VSC2 is used (because the only floating item is a receiving item).

--lastWSDataSeg=# "#" is an integer between 1 and 32, inclusive.

This option sets the data segment number that will be the last one used by data items contained in Working-Storage. Note that this option applies only to Version 7.2 and earlier.

The compiler allocates up to 32 data segments per program, each of which can be up to 64 KB in size. Data outside of Working-Storage must fit within these segments. Data contained in Working-Storage need not, but it can be slightly more efficient to place Working-Storage data within these segments until it places some in the segment identified by --lastWSDataSeg=#. After that point, the compiler places all Working-Storage data into a separate address space (identified by addresses larger than x"40000000" in the symbol table listing). This reserves space for other data items that follow Working-Storage, such as the Screen Section or literals found in the Procedure Division.

The default setting is 24. This reserves 8 segments (512 KB) for use by the Screen Section and literals. This is normally much more than needed. If it is not enough, then setting --lastWSDataSeg=# to a lower value reserves more space.

When compiling for Version 6.0 or an earlier object format, the default setting is 32. This causes all of Working-Storage to be allocated in data segments. This sets an absolute limit of about two MB on the amount of small data that a program can allocate. The term small in this sense means data elements are individually smaller than 64 KB.

We recommend leaving this option at its default value unless you receive the error message Program exceeds 32 segments. Should this occur, try setting --lastWSDataSeg=# to a value smaller than the default of "24."

--noAlignLit | This option inhibits use of the default algorithm for aligning literals in memory. Use the -Da option to specify an alignment modulus other than the default of 4.
--truncANSI | There are four truncation options in all. See Truncation Options for description and comparison information on these options.
--noTrunc | There are four truncation options in all. See Truncation Options for description and comparison information on these options.
--fastRefMod | Directs the compiler to use an optimized method for handling code that performs reference modification. The result is faster runtime execution. Note that this option may not work with certain programs, resulting in unexpected results or compiler failure. If using this option, be sure to verify runtime results. When this option is not specified, the compiler uses the standard method for reference modification code handling.
  • Truncation Options
Parent topic: Using the Compiler


Truncation Options

In addition to the compiler's default truncation behavior, the compiler also supports the ability to use a data item's storage capacity instead of its PICTURE phrase to determine the largest numeric value it could hold. This is the -Dz compile option. However, other COBOL systems have similar concepts that differ in some details from -Dz. To give you the greatest amount of flexibility and compatibility with other COBOLs, there are four truncation options for numeric values. Only one of these options may be used for any individual compile. The following chart describes and compares these options:

Option | Behavior
<default> | Full ANSI COBOL rules are in place. Each numeric data item stores values up to its PICTURE in size. A small number of USAGE types provide exceptions (such as COMP-X). These are documented under the USAGE phrase. Values larger than allowed by the PICTURE are truncated using the standard size rules when the data item is the target of a MOVE statement. The results of an arithmetic overflow (without the SIZE phrase) are undefined.
--truncANSI | Similar to the default, but COMP-5 is added to the list of data types that ignore their PICTURE when determining the largest value they can hold. However, COMP-5 items do use their PICTURE when moving a value to a nonnumeric data item. The name of this option is similar to the name used by some other COBOL systems that behave this way.
--noTrunc | All binary data types ignore their PICTURE when determining the largest value they can hold. However, the PICTURE is used when moving data from a binary number to a nonnumeric data item. The name of this option is similar to the name used by some other COBOL systems that behave this way.
-Dz | All binary and packed-decimal data types ignore their PICTURE when determining the largest value they can hold. The PICTURE is not used when moving to a nonnumeric destination (the largest possible value determines the number of digits moved instead).
Parent topic: Data Storage Options


Video Options

-Va | This option must be used with either the -Vh or -Vl option. When used, the default intensity specified by the -Vh or -Vl option will be used only for ACCEPT statements. DISPLAY statements will use the opposite intensity. Thus -Vha will cause the default intensity for ACCEPT statements to be high while the default for DISPLAY statements will be low. When Screen Section items are used, then input and update fields will use the ACCEPT intensity, while output and literal fields will use the DISPLAY intensity.
-Vb | This option causes the phrase BLANK LINE, when used in a Screen Section entry, to be treated as if it were written BLANK EOL. Most other COBOL compilers work this way, but the X/Open COBOL standard requires the syntax supported by ACUCOBOL-GT.
-Vc | This option causes any ACCEPT statement that contains a numeric or numeric edited receiving field to be treated as if the CONVERT phrase were also specified. This is the default for RM/COBOL-85 but not for RM/COBOL version 2 or VAX COBOL.
-Vd | This option causes non-USAGE DISPLAY numeric items to be converted to USAGE DISPLAY before the screen display occurs. This option is used in conjunction with the -Ca switch for Micro Focus and HP COBOL compatibility.
-Ve This option alters the rules that determine which conditions cause an ON EXCEPTION phrase to receive control in a Format 1 ACCEPT statement. Normally, entering an exception key will cause the ON EXCEPTION phrase to receive control. If you specify this option, then you must follow the -Ve with a digit (as part of the same argument) taken from the following list:
  • 1 - Exception keys cause the ON EXCEPTION phrase to execute (default handling).
  • 2 - Conversion error causes the ON EXCEPTION phrase to execute. When a numeric item is being entered and the CONVERT phrase is specified, then entering an illegal number will cause the exception.
  • 3 - Combines the effects of both 1 and 2.

By default, the runtime system handles conversion errors by displaying an error message and forcing the user to re-enter the data. If you specify -Ve2 or -Ve3, then conversion errors are returned to your program instead. For strict compatibility with VAX COBOL, you should specify -Ve2, while for strict compatibility with RM/COBOL, you should specify -Ve3. The default setting is recommended, however, because it provides a meaning for ON EXCEPTION that is more consistent with the rest of the ACUCOBOL-GT language.

-Vg This option specifies which controls get COLOR information from their containing group item. Note that COLOR information includes BACKGROUND-COLOR, FOREGROUND-COLOR, COLOR, FOREGROUND-RGB, and BACKGROUND-RGB. Specify the -Vgcompiler option to not propagate color information. This can be optionally followed by a number, which is the bitwise OR of the control types to not propagate color for.

For a specific control type, the bit to use is 1 shifted left the control type number bits. So for the LABEL control, use 2 (1 shifted left 1), for PUSH-BUTTON, use 8 (1 shifted left 3), etc. Note that sample/def/controls.def file defines each control type, where you see entries such as CTL-LABEL is 1, and CTL-PUSH-BUTTON.

There should be no spaces between the -Vg and the following number.

Without any argument, PUSH-BUTTONS, CHECK-BOXES, and RADIO-BUTTONS do not get propagated color info. So -Vg is equivalent to -Vg56. Note that 56 = 32 + 16 + 8, which is (1 shifted left 5) + (1 shifted left 4) + (1 shifted left 3), and CTL-RADIO-BUTTON = 5, CTL-CHECK-BOX = 4, and CTL-PUSH-BUTTON = 3.

-Vg0 is equivalent to not using this option at all. Because the controls are 1-based and not 0-based, -Vg1 is the same as using the -Vg option at all.

-Vh | This option forces the default video intensity for ACCEPT and DISPLAY statements to be set to high intensity. The default for ACUCOBOL-GT is to use the normal operating intensity for the terminal being used.
-Vi This option changes the behavior of a Screen Section ERASE (and BLANK) phrase with respect to color handling. If the screen item containing the ERASE phrase has either BACKGROUND-COLOR or COLOR specified, then the -Vi option causes the erased area to be painted with that color instead of the subwindow's background color.

Keep in mind that background color can be specified using a background color number with the COLOR phrase.

If the screen item has no background color specification, or if the background color portion of a COLOR phrase is zero, then the subwindow's background color is used.

The default behavior is to use the current subwindow's background color when executing an ERASE phrase.

-Vl | This option forces the default video intensity for ACCEPT and DISPLAY statement to be set to low intensity.
-Vq | This option causes ACUCOBOL-GT to produce quiet programs by inhibiting the default bell produced by ACCEPT statements compiled in RM/COBOL compatibility mode. However, this does not override explicit BELL or BEEP phrases.
-Vu | This option allows you to imply the UPDATE phrase for all Format 1 ACCEPT statements that do not have an explicit UPDATE or DEFAULT phrase specified for them.
-Vx | This option allows exception keys to be entered by the user for any ACCEPT statement. Normally, ACUCOBOL-GT inhibits the use of exception keys on ACCEPT statements that do not have a CONTROL KEY clause or an ON EXCEPTION clause.
Parent topic: Using the Compiler


Warning and Error Options

Note: The -w is an existing compiler option to turn warnings off. The -w option will negate the effects of -Wa and -Wl. To use the previous -w option, it must be specified alone (as the -v option is).
-a | This flag is now obsolete and should not be used.
-Wl This option generates the following 01-level item warning:
USING parameter <name> is not an 01-level item

The ANSI COBOL standard requires that parameters passed to subprograms be 01-level items. ACUCOBOL-GT does not restrict them as such; however, there are valid reasons for restricting their use. For example, starting in version 7.0.0, the compiler can generate better code for certain moves and comparisons, based on the alignment of the underlying data types. When those data types are in LINKAGE, the alignment rules that the compiler assumes may not be valid. Making all of the passed parameters be 01-level items ensures that the compiler's assumptions about alignment of the data items are valid. Note that the compiler can generate incorrect code when the assumptions are invalid. In such situations, it is possible to get a MAV at run time.

-Wa Ths option generates the following alignment warning:
USING parameter <name> not aligned and may cause problems in the called subprogram

To be less restrictive, the compiler also includes an alignment warning. This is generated whenever a passed parameter is a group or is binary, and whose alignment is not an even multiple of the alignment specified by the -Da# option.

-Wr | This option displays warning messages for 01 level redefined zones if they are smaller than the redefiner.
-Wu This option displays a warning if any of the following verbs are missing an explicit scope terminator: ACCEPT, ADD, CALL, COMPUTE, DELETE, DISPLAY, DIVIDE, EVALUATE, IF, MODIFY, MOVE, MULTIPLY, PERFORM, READ, RECEIVE, RETURN, REWRITE, SEARCH, START, STRING, SUBTRACT, UNSTRING, USE, WAIT, WRITE, and XML GENERATE and PARSE.
Note: Only complex constructs are reported; simple constructs, such as MOVE a TO b, are ignored if the terminator is missing.
-Qm | This option specifies the number of errors the compiler reports before it exits. The option must be followed by a positive numeric argument, which is the maximum number of errors the compiler reports before it exits. The default value is 100.
-Qp | This option allows the compiler to skip entire sections of code when it finds an error. In particular, when this option is used, the compiler skips to the next period (.) when an error is detected.
Parent topic: Using the Compiler


Debugging Options

All the information obtained when you use the Debugging Options listed below is coded and stored in the COBOL object file. The runtime retrieves, decodes, and sends it to the debuggers (runtime and AcuBench integrated) when requested.

-Ga | This is a shortcut for turning ON all the debugging options.
-Gd This option includes the source code in the compiled object file. It also generates a single-byte no operation (NOP) instruction for each CONTINUE statement to make it easier to break at such statements when debugging.

See Runtime Debugger for more information.

-Gl This option includes line numbers in the object file. It does not include source code in the object file. Only a mapping between addresses and line numbers is included. This allows the runtime to output line number information along with an address when a program terminates abnormally. This information also enables AcuBench to find and indicate the line of source on which the debugger is currently stopped.

If line number mapping is needed in an object to be placed in production, -Gl is the best switch to use because it results in an object file that is much smaller than those produced with -Ga.

-Gs | This option includes extra symbol information. It does not include source code in the compiled object. This information is accessible only from AcuBench. The extra symbol information can be used by AcuBench to get all the children and siblings of any particular data item. It allows AcuBench to traverse the symbol table of the COBOL program and to have a tree-type control for viewing group data items.
-Gy | This option includes minimal symbol information. It does not include source code in the compiled object. Instead, minimal information about names and locations is stored in the object. Using this switch, you can accept and display variables from within the debuggers.
-Gz This option restricts a program from stopping in the debugger in nearly all cases. The only time the runtime will stop and enter the debugger when executing a COBOL program compiled with -Gz is when the runtime encounters a format 2 STOP statement (STOP literal), which is meant to break into the debugger.

This option is useful if you distribute COBOL objects and allow your users to create their own COBOL programs, but you don't want them to be able to debug your programs.

This option is not compatible with any other debugger option. If other debug options are used on the command line, the last debugger option will take precedence. For example, specifying -Ga -Gz will result in an object that will never stop in the debugger, while specifying -Gz -Ga will result in an object with full debugging symbols.

This option is available only if targeting an 8.1 runtime or later. Note that specifying -Znn for any nn <= 80 will turn off a special flag that is required in order for the -Gz option to work.

Note: To debug a program in AcuBench, you need only the -Gl and -Gs options. This combination allows AcuBench to display the correct line of the correct source file when the debugger is stopped at a breakpoint and to display any data items that you want to see. It does not include the source code in the compiled object, so the object can be safely distributed without fear of unauthorized access to source code.

To perform source-level debugging with the runtime debugger, you need only the -Gd and -Gy options.

The -Ga option is helpful when you expect to use both debuggers.

See Runtime Debugger for differences between symbolic debugging and source-level debugging.

Parent topic: Using the Compiler


Mapping Options

Each mapping option causes the compiler to produce a simple report about the program that is being compiled. Mapping options that produce reports prevent the compiler from generating an object file or XFD file. In this situation, errors in the source program are usually not reported. Only one report may be produced at a time, so several of the mapping options are mutually exclusive.

Specification of any mapping option causes the compiler to ignore all text positioned between EXEC and END-EXEC keywords.

Mapping options are frequently used internally by the workbench to implement some of the editor features.

-Mc | Lists all of the special style and property names associated with graphical controls. You can combine this with the -Mr option to get a listing of both reserved words and property names. You might use this to produce word lists for the AcuBench Code Editor, to specify the words to be colored as reserved words.
-Ml | Causes the -Mp (paragraphs) and -Mv (variables) reports to be printed in lowercase. The default is uppercase. See Miscellaneous Options.
-Mm | Causes the -Mp (paragraphs) and -Mv (variables) reports to be printed in mixed upper and lowercase. In this mode, the beginning of each word is capitalized, and the rest of the word is made lowercase. See Miscellaneous Options.
-Mo | Names the output file for a map report. This option must be followed (as the next argument) with the name of a file. If this option is not used, then map reports are sent to the compiler's standard output.
-Mp | Causes the compiler to produce a report on the Procedure Division sections and paragraphs contained in the program. If you select this option, the program is not compiled into an object file.
-Mr | Causes the compiler to produce a report of the reserved words known to the compiler. The exact list depends on the other compile time options. You can use this option to produce a word list that can by used by the workbench's editor to color reserved words. The workbench comes with the full reserved word set pre-programmed. If you modify the set of reserved words with any of the -R compiler options, you can use this option to produce a custom list that matches the reserved words you use. Selecting this option prevents the compiler from producing an object file.
-Ms | Causes the compiler to produce a report of the COBOL source files used in the program. This includes the program itself and any COPY libraries. This list can be useful for generating dependencies if you use a make utility, and can help you determine which files to send to Technical Support staff when you need help resolving compiler issues. This option prevents the compiler from producing an object file.
-Mss Similar to -Ms, this option lists all the COBOL source files needed to compile a program. If you specify -Mss instead of -Ms you get an enhanced listing with the following format:
path base-filename "C" or "R" source-file line-number

where:

  • path is the pathname processed by the compiler. This path may be relative to the current directory. For Win32 compilers, path is the full pathname leading up to the COPY file.
  • base-filename is the base file name of the COPY library.
  • C is listed if the file is a standard COPY library or the original source file.
  • R is listed if the file corresponds to a COPY RESOURCE statement.
  • source-file is the name of the file containing the COPY statement
  • line-number is the line number of the COPY statement. The compiler lists a 0 if the file is the original source file.

AcuBench uses this format when you import programs to the workbench.

-Mu | Causes the -Mp (paragraphs) and -Mv (variables) reports to be printed in uppercase. This is the default. See the -Zw compiler option (Miscellaneous Options).
-Mv | Produces a report of the data items (variables) declared in the program. This option prevents the compiler from producing an object file.
Parent topic: Using the Compiler


Conditional Compilation Options

The compiler supports conditional compilation through the use of special constructs in the COBOL source file and by accepting command-line arguments that turn on compiler directives and set constants to values. See Conditional Compilation for a description of the COBOL constructs.

The / compiler option is used to turn on directives and specify constants.

The two forms to this option are:

  1. Directive setting mode
    /[NO]directive

    This option is equivalent to having the following line in your COBOL source from the very beginning of the compilation:

    $SET [NO]directive

    By adding this compile switch, you turn on the directive (or off, if the directive is preceded by NO). This directive can now be tested with a Format 3 $IF statement, which can signal the compiler to either compile or skip the next lines of code.

    See Conditional Compilation for details on the $IF and $SET statements.

    If compiling for HP compatibility (-Cp) the -$IF and -$SET directives are supported.

  2. Value setting mode
    /CONSTANT name=value

    This option is equivalent to having a level-78 item defined in your COBOL source. If value is composed solely of numeric digits, the constant is considered numeric; otherwise, it is considered a string literal. Name can now be tested with a Format 1 $IF statement.

Note: The -Cg compiler option turns off the conditional compiling features. Conditional compiling statements begin with the $ sign. In prior versions, lines of code that began with the $ sign were treated as comments. Some COBOL programs use a type of conditional compilation which may fail to compile as a result. Turning off conditional compiling should rectify these situations.

Other Options

$SET ADDSYN "word1" = "word2"

Make the user-defined word word2 a synonym for reserved word word1.

$SET MAKESYN "word1" = "word2"

Make the reserved word word2 a synonym for reserved word word1. This is equivalent to the compiler option -Rn word1 word2

$SET DEFAULTBYTE "num"

num must be a numeric value between 0 and 255. The default fill byte is set to the value given. This is equivalent to the -Dv=num compiler option.

$SET SPZERO

Equivalent to the -Zz compiler option.

$SET INTLEVEL "nn"

Equivalent to the -Znn compiler option.

$SET CALLFH "program"

This currently does nothing, but is included for completeness.

$SET FCDREG

This currently does nothing, but is included for completeness.

$SET INITCALL "program"

This currently does nothing, but is included for completeness.

Parent topic: Using the Compiler
Related concepts
Conditional Compilation


Miscellaneous Options

--acceptrefresh | This option takes the most recent value of what was entered on the screen and then uses that value in subsequent ACCEPT statements. If you enter something in a screen section that goes to a variable, then MOVE something to that variable, the --acceptrefresh option will allow the subsequently MOVED value to be the basis of what is in the next ACCEPT statement.
--arithmeticVSC2 | Causes truncation of intermediate results in arithmetic statements to follow the rules of VS COBOL II and COBOL/370.
--binaryMath | Causes the compiler to use binary math operations to handle arithmetic as long as the target runtime supports these operations; this can be abbreviated --bin.
--brand serial# | Causes the compiler to embed the specified value into the object file. serial# is a separate argument of up to 20 characters. When you specify this option and a value, the COBOL object is associated with the value of serial# in such a way that it will execute only with a runtime that has the corresponding serial number. Attempts to execute the program with a runtime that has a different serial number (either as the initial program, or as a called subprogram) result in the runtime displaying the message Incorrect serial number and returning a call error of 28. To display a runtime's serial number, execute the runtime with the -v option.
--decimalMath | Causes the compiler to use decimal math operations to handle arithmetic, overriding other compiler flags; can be abbreviated --dec. This is the default behavior. You may wish to experiment with the --binaryMath options, which may improve performance; however, you should test precision and accuracy.
--defines | This option must be followed by the name of a file as the next separate argument. This option causes the compiler to find all level 78s in a COPY file and create equivalent C-language #define statements in the specified file. See Help, Version Information, and Communication With C Programs for more information.
--newARC With --newARC, the syntax rules for Abbreviated Combined Relation conditions become relaxed to allow for parenthesis to appear immediately after the relation.

For example:

IF A = (B OR C OR D)
would now be accepted by the compiler.
--oldARC | This option is the default behavior and specifies the standard syntax is to be used for Abbreviated Combined Relations. This syntax is described in Abbreviated Combined Relation Conditions.
--relaxRBUsing

ECN 2770 in version 6.2.0 corrected an issue where the compiler incorrectly allowed indexed data items as the USING data item for a Radio Button (contrary to the documentation). This error was discovered from a crash that occurred in a customer program. However, some customers were using the invalid syntax without error. This ECN allows those customers to continue to do so, though unsupported.

This option allows USING data items to be indexed data items, as was allowed prior to ECN 2770.

Note: The use of Indexed data items in the USING clause for Radio Buttons remains unsupported syntax. Additionally, this option is NOT included in AcuBench
-Za Causes the compiler to generate code to test array references at runtime. If an index is used which is out-of-bounds, the runtime system displays an error message showing the index value and the allowed bounds. (This causes some extra code to be generated and prevents certain table optimizations from occurring, so it should be turned off once a program is fully debugged.) With this option, the compiler does not re-use previously computed index values.

Because subscript overflow is the most common cause of memory access violation errors, adding this option is a good first step when you are looking for the cause of a memory access violation. (See Memory Access Violations for more details.)

This option also generates code that performs range checking on reference modification at runtime. Reference modification that creates a data item whose size or leftmost position parameter is out of range of the data item it references causes the runtime to display the error message Reference modifier range error.

This option also causes the runtime to test the LINKAGE items automatically. When an item defined in the Linkage Section is not referenced in the USING phrase of the Procedure Division statement and has not had an address assigned to it with the SET ADDRESS OF phrase, the run-time returns an error message.

The -Za option also specifies size testing of linkage items passed to sub-programs. when a LINKAGE SECTION parameter of a size larger than the caller passed is detected, an error to that effect is reported.

-Zc | This compact option causes ACUCOBOL-GT to optimize for smaller code instead of faster code.
-Zd | Although still supported, this option has been replaced by the -Gd option. Both options produce the same results.
-Ze

This option adds XML symbol table information to the COBOL object for use by XML Extensions.

Programs using XML Extensions must be compiled with the -Ze option. Add the -Ze compiler option to the compile command to include the XML symbol table information in the compiled COBOL object.

-Zg | Enables the use of segmentation (overlays) in the source. If this option is not used, section numbers will be ignored.This option applies only to Version 7.2 and earlier source files.
-Zi | Causes the program to be compiled as if it had the IS INITIAL PROGRAM phrase specified in its PROGRAM-ID paragraph. This can be useful, in some cases, when you are compiling programs that do not contain adequate memory management (no CANCEL verbs, for example). See PROGRAM-ID Paragraph for details on IS INITIAL PROGRAM.
-Zl | All data items may be larger than 64 KB. This option is obsolete. In versions prior to 6.0, this option caused the compiler to allow data items larger than 64 KB.
-Zm Causes the compiler to generate code that tells the runtime the size of a data item specified in a Format 7 SET Statement, as in:
SET pointer TO ADDRESS OF data-item.

This option supports thin client applications that pass pointers in calls to DLLs on the display host.

-Zn | This turns off ACUCOBOL-GT's local optimizer. This is useful primarily to see if the optimizer is introducing errors in the generated object code. This option also prevents the compiler from re-using previously computed index values.
-Zo | Although still supported, this option has been replaced by the -Fo option. Both options produce the same results.
-Zr Allows for a recursive PERFORM Statement. When this switch is used, the PERFORM verb is modified so that return addresses are stored on a stack. Only the most recent PERFORM statement has an active return address. When this option is used, a paragraph under the control of a PERFORM statement may (directly or indirectly) PERFORM itself. See PERFORM_STACK for more information>.

This behavior is the default. For backward compatibility, -Zr acts like -Zr1. If you compile for compatibility with Version 3.1 or earlier, recursive PERFORMs are turned off by default. This behavior may affect existing programs that do not compile for earlier compatibility. Event procedures require the ability to do recursive PERFORMs.

-Zr0 | This option tells the compiler not to allow recursive PERFORMs. Event procedures require the ability to do recursive PERFORMs.
-Zr1 | This option tells the compiler to allow recursive PERFORMs. Event procedures require the ability to do recursive PERFORMs.
-Zs | Although still supported, this option has been replaced by the -Gy option. Both options produce the same results.
-Zw This option prepares a program for import into the AcuBench Screen Designer. It causes the compiler to mark windows and screen controls with additional information that can be used by the graphical screen import utility or Character-to-GUI Wizard. Graphical windows imported into the Screen Designer will be more complete if the program is first compiled with this option, and character-based screens converted by the wizard are more likely to contain the proper control type for each field. Using this option makes your compiled program somewhat larger, so you should use it only when you are importing screens into the workbench. See -import and -- char2gui in Using the runtime System for related information.

You can also use the -Ml, -Mm, and -Mu options to affect the case of the additional information. This will affect how these items are seen in the Screen Designer, and in your subsequently generated code. Specifying -Zw -Ml will cause the data imported into the Screen Designer to be in lowercase. The default is uppercase (-Mu). To specify uppercase for the first letter of each word, and lower case for the rest of each word, use -Mm.

If you compile with -Zw, your screens may use only literal reference modifications, i.e., data-item(4:20), for any of their data items to be imported into workbench correctly. Data items that use more complicated variants of reference modification do not import correctly. For example, data-item(data-start:data-length) imports as data-item(:), and you need to insert the correct values into the workbench.

-Zx | Although still supported, this option has been replaced by the -Fx option. Both options produce the same results.
-Zy This option lets you treat ACCEPT FROM DATE as ACCEPT FROM CENTURY-DATE, and ACCEPT FROM DAY as ACCEPT FROM CENTURY-DAY. If you use this option, the 4-digit year format will be used for ACCEPT FROM DATE providing that:
  • The receiving field is numeric or numeric edited and contains eight or more integer digits; or
  • The receiving field is not numeric or numeric edited and contains eight or more character positions.
If neither of the above conditions applies, then ACCEPT FROM DATE will return its normal 6-digit format even if you use -Zy.ACCEPT FROM DAY works in the same fashion, except that the receiving field must have seven or more digits/positions in order to receive the new format.

Information on ACCEPT FROM DATE and ACCEPT FROM DAY is in Procedure Division Statements.

-Zz This option causes spaces in a USAGE DISPLAY numeric item to be treated as the value zero, and non-numeric data to be treated as numeric. It does this by treating the high-value half of each byte as 3 so as to bring all bytes in the variable within the range of 30 to 3F.

-Zz must be specified at compile time in order to prevent the optimizer from mis-constructing the program. Note that this option should be used only if you need it, because it causes less efficient programs to be produced.

-Z3 | Causes ACUCOBOL-GT to produce programs that can be run by the Version 1.3 runtime system. Specifying this will limit several features of later versions. If you use a restricted feature, you will receive an error message at compile time. This flag also implies the -C3 option to ensure compatible behavior of the compiled program (see above).
-Z4 | Similar to the -Z3 option, except that the produced object can be run by the Version 1.4 runtime system. Implies -C4.
-Z5 | Causes the compiler to produce object files that can be run by the Version 1.5 runtime system. This option implies -C5.
-Z20 | Creates object code that can be run with a Version 2.0 runtime (chart verbs are not supported). This option implies -C20.
-Znn Creates object code that can be run with a Version nn runtime.

nn is the version number of product; for example, -Z21 for version 2.1, -Z60 for version 6.0, and so on. From version 10.0 onwards, 3 digits are used to represent the version number; for example -Z100 for version 10.0, -Z101 for version 10.1, and so on.

Parent topic: Using the Compiler


Upper and Lower Case

Command-line arguments that begin with a hyphen are not case sensitive. For example, -LO and -Lo and -lo all mean the same thing. In this manual, group letters are shown in upper case, and the actual arguments are shown in lower case (for example, -Lo). This is done for consistency and clarity.

Other command-line arguments are case-sensitive if the host machine is case-sensitive, otherwise, they are not. For example, on UNIX machines, ccbl TEST and ccbl test are different commands because the file names TEST and test are different on UNIX systems. On VMS systems, these commands are the same because the two file names are treated as the same by the operating system.

Parent topic: Using the Compiler


File Name Handling

Several compiler options (such as -o) take a file name as an argument. As a special abbreviation, the character @ can be placed in these file names to stand for the base name of the source program. To form the base name, the compiler removes all directory information from the source file name, along with any characters following a period, and the period itself. The resulting base name is then inserted into the file name argument at the location of the @ character.

For example, if you want to compile a program called TEST.CBL, and you want the resulting object file to be named TEST.OBJ, and the error output to be placed in TEST.ERR, you can use the following command:

ccbl  -o  @.OBJ  -e  @.ERR  TEST.CBL

This is equivalent to the following:

ccbl  -o  TEST.OBJ  -e  TEST.ERR  TEST.CBL

and is also equivalent to:

ccbl  -oe  @.OBJ   @.ERR  TEST.CBL

In this example, the -o indicates that the next argument is the name of the object file. The @.OBJ argument is this name. The -e indicates that the next argument is the name of the error file. The @.ERR argument is this name. The @ character is replaced with the word TEST, which is derived from the name of the source file TEST.CBL.

As another example, on UNIX machines you can compile the program test.cbl and place the object code in the file /programs/test with the command

ccbl  -o  /programs/@  test.cbl

(Substitute \@ for @ if your UNIX machine uses @ as its default "line kill" character.) This can be particularly useful in compile scripts or in conjunction with the CBLFLAGS variable described below.

  • Remote File Name Handling
Parent topic: Using the Compiler


Remote File Name Handling

If AcuServer or AcuConnect is running on remote machines, the compiler can read remote source files from and write resulting files to those systems. The remote filename syntax that is used with the compiler is different from that used with the runtime and AcuServer. Because the compiler uses the at sign (@) as a placeholder for the base name of the source file, you cannot use that symbol as a tag in front of the name of the remote system (for example, -o @server:/objects/@.acu is ambiguous). Instead, the syntax is more like standard URL syntax. The remote filename specification must be of the form:

acurfap://server:[port]:filename

acurfap stands for Acucorp Remote File Access Protocol.

Remote file name notation can be used with any compiler option that takes a file name as an argument. The //server:port notation can be used with any configuration variable that allows remote name notation.

If AcuServer is listening on the default port of a server machine, you do not have to specify the port number because the compiler defaults to the number (6523). However, if you omit the port number, you must include two colons (::) before the file name. If AcuServer is listening on a port other than the default, the :: notation will not work.

Examples

If AcuServer is running on a UNIX machine named myserver and is listening on the default port, you can compile apmain.cbl straight to that machine with the following command.
ccbl -o acurfap://myserver::/myapp/obj/@.acu apmain.cbl
If apmain.cbl is located on the server, you can compile the remote file and write the resulting object file to the server with the following command.
ccbl -o acurfap://myserver::/myapp/obj/@.acu acurfap://myserver::/myapp/src/apmain.cbl
If AcuConnect is running on a Windows machine named myserver and is listening on port 5632, you can compile apmain.cbl straight to that machine with the following command. Notice that if specifying a Windows directory, you must also include a drive letter followed by a colon (the c: in this example) after the port number (or the optional ::).
ccbl -o acurfap://myserver:5632:c:/myapp/obj/@.acu apmain.cbl
Note: When specifying a remote file name for a Windows machine, you can use the backward slashes (\) used by Windows, the forward slashes (/) used by UNIX, or a combination of the two.
Parent topic: File Name Handling


Compiler Command-Line Examples

Here are some examples of common commands. The following command will simply compile the program test.cbl and produce the object file test.acu. The program will be compiled in VAX COBOL compatibility mode.

ccbl  test.cbl

This next command will compile the same program in RM/COBOL compatibility mode. It will treat signs in a manner consistent with early versions of RM/COBOL and suppress reserved words not used by that compiler. These options are particularly common when you are converting programs written for RM/COBOL.

ccbl  -Cr -Ds  -Rva8  test.cbl

The following Windows console-mode (DOS-box) command will compile the program TEST.CBL and produce an object code file named TEST in the c:\objects directory, and create a full listing called TEST.LST in the current directory.

ccbl32  -o  c:\objects\@  -Lfo  @.lst  test.cbl

Finally, this command will perform the same function on a UNIX machine except that the listing will be sent to the print spooler lp.

ccbl  -o  /objects/@  -Lf  test.cbl  |  lp
Parent topic: Using the Compiler


CBLFLAGS Environment Variable

To simplify the setting of compiler options, the environment variable CBLFLAGS may be set to a list of options. These options will be used each time the compiler is run. The CBLFLAGS variable is particularly useful for setting options that you use all the time.

If you have set the CBLFLAGS variable and need to unset it temporarily, you can use the -x command-line option to ignore it for any particular run of the compiler.

You may continue to use command-line options when you use the CBLFLAGS variable. All of the options from both places are used. Note that the environment variable CBLFLAGS is examined after the command-line options.

On UNIX machines, the CBLFLAGS variable is set in the environment. This can be done with the export command of the Bourne or Korn Shell or the setenv command of the C-Shell. Under VMS, the CBLFLAGS variable is set as a symbol. Under Windows NT/2000, the CBLFLAGS variable can be created in the Control Panel System applet or for Windows 98 systems, in the autoexec.bat file with the SET command. Windows must be restarted for the new values to take effect. For more information about setting environment variables, see Environment Variables.

The @ file name abbreviation is particularly useful in the CBLFLAGS variable. For example, if you set the variable to -o /programs/@, every program you compile will have its object file placed in the /programs directory with the same name as the source file.

Note: The number of acceptable arguments in the CBLFLAGS environment variable is limited to 50. The compiler accepts the first 50 arguments set and ignores all the rest in excess of that number. File specifications are counted as separate arguments, but combined options from the same group are counted as one argument.
Parent topic: Using the Compiler


Help, Version Information, and Communication With C Programs

You can get a summary of compiler options with the following command:

ccbl  -help

You can display the copyright notice and version information with this command:

ccbl  -v

You can get configuration information with the following command:

ccbl -vv

On UNIX systems, you can get additional port configuration information with:

ccbl -vvv

The information displayed with -vvv varies depending on the UNIX system and is subject to change from release to release.

You can find all of the level 78s in a COPY library and create equivalent C-language #define statements with the following command:

ccbl  -defines  filename

You can use the -defines option to simplify communication between COBOL and C programs.

One specific use of this option is to simplify the creation of Windows Help files when you are building context-sensitive help. Use this option to map context ID strings to context numbers for use with Windows Help files. First create a COPY library with level 78s that map the context IDs (strings) from your help file to unique context numbers (the Windows Help API function WinHelp requires a number as the context ID parameter). Then when you specify ccbl -defines, the compiler creates a file containing #defines that correspond to the level 78s in the COPY library you created.

The -defines option must be followed (as the next separate argument) by the name of the COPY library. acurfap syntax can be used to specify a file on a system being served by AcuServer or AcuConnect. See Remote File Name Handling for more information.

By default -defines creates a file having the same base name as the specified file and the extension .h. For example, if your COPY library is named PRHELP.DEF, you could use this command:

CCBL -DEFINES PRHELP.DEF

to create the file PRHELP.H that contains one #define for each level 78 in PRHELP.DEF.

Be aware that any hyphens in the level 78 names are converted to underscores in the corresponding #define. Although hyphens are allowed in COBOL and in the help file, hyphens are not allowed in C names. See The Help Processor in User Interface Programming, for more information about Windows Help files.

Parent topic: Using the Compiler


The ">>IMP" Directive

The >>IMP directive is an implementor defined directive, meaning that Micro Focus defines its specific uses (described below). The syntax is:

>>IMP (ACU-CBLFLAGS=CompilerOption)

CompilerOption can be:

  • -Dln, where n is the integer value 1, 2, 4, or 8
  • -Sa
  • -St

The directive must start in the indicator area: column 7 for ANSI format source; column 1 for terminal format source.

ACU-CBLFLAGS and its argument must be enclosed in parentheses. An equal sign (=) must immediately follow ACU-CBLFLAGS and immediately precede
     CompilerOption. Note that all three options require a leading hyphen.

The supported options allow you to work around two unusual compile time issues.
  • Specifying an Alternate Data Alignment
  • Forcing Compilation of ANSI or Terminal Format Files
Parent topic: Using the Compiler


Specifying an Alternate Data Alignment

You can use the -Dln argument to specify an alternate byte alignment for SYNCHRONIZED data itemsFor example, the RM COBOL compatibility switch (-Cr) implies two byte alignment (which is consistent with legacy RM COBOL). Some variables in your program may require a larger alignment. To apply the directive, in the source code immediately before the variable or set of variables (which may be contained in a COPY file), add the directive in the indicator area. For example, to specify four byte alignment add:

>>IMP(ACU-CBLFLAGS=-Dl4)

Immediately after the last variable that requires special alignment, set the alignment back to the original value:

>>IMP(ACU-CBLFLAGS=-Dl2)

See Data Storage Options for more information on the -Dl option.

Parent topic: The ">>IMP" Directive


Forcing Compilation of ANSI or Terminal Format Files

When specified with a compiler directive, the -Sa and -St options override the -Sa or -St option specified on the command line within the scope of the containing file.

In some instances, due to source origin issues, developers may choose to enforce compilation of a single source format by specifying either the -Sa (ANSI) or "-St" (terminal) compiler option in the command line. Without the use of a compiler directive, the Compiler will not compile source files of another format within the same compilation unit. (In prior releases this was particularly problematic for terminal format compilation (-St) when axdefgen had been used to create COPY files for ActiveX components, because axdefgen creates ANSI format COPY files. axdefgen now automatically inserts a compiler directive in the first line of all COPY files it creates.)

When the -Sa or -St option is specified in a compiler directive on the first line of the source file, the compiler compiles that source file regardless of the format option specified on the command line. Compilation of that format applies to only the file containing the directive.

For example, when the -St (terminal format) option is specified on the command line and you want to compile an ANSI format COBOL source file in the same compilation unit, place the following compiler directive in column 7 of the first line of the COBOL file:

>>IMP(ACU-CBLFLAGS=-Sa)
Parent topic: The ">>IMP" Directive


Using the Runtime System

The ACUCOBOL-GT runtime system (referred to in this manual as runcbl), runs the programs created by the compiler. Once compiled, programs are ready to run; no linking step is required. Programs compiled with ACUCOBOL-GT are machine transportable. runcbl accommodates the differences between machines.

To run an ACUCOBOL-GT program, enter the following command (substitute the name of your runtime for runcbl):

runcbl  [options]  [program]  [parameters]

program is the name of a compiled program. If omitted, its name defaults to cbl.out (or to the name you have set with the runtime configuration variable DEFAULT_PROGRAM). Remote name notation is allowed for the name of the compiled program, if your runtime is client-enabled. See Remote Name Notation for more information.

parameters are one or more arguments that can be passed to the program. These arguments can be accessed through the CHAINING phrase of the Procedure Division header in the compiled program. If parameters are specified, then program must also be specified. Under VMS, the parameters that are not in double quotes are converted to lower case. Parameters should be enclosed in double quotes to preserve case sensitivity. The maximum number of parameters allowed on the command line is 50. See CHAIN Statement in the ACUCOBOL-GT Reference Manual for more information.

options is a series of one or more of the following flags. These options must be preceded by a hyphen. You can specify more than one option by simply combining them. Option characters may be either upper or lower case.

Separately, or in addition to placing options on the command line, options can be specified in the ACUSW environment variable. ACUSW can contain any runtime options, which are specified with the same syntax used on the command line. ACUSW and command-line options can be used together. ACUSW is processed after the command line, however, the command line takes precedence with options that specify a filename. For example, you can specify a default error file in ACUSW (e.g., with the -e option) and then override it on the command line for a particular run. The --no-acusw option inhibits the processing of ACUSW. This is valuable for programs that directly invoke the runtime and require a fixed set of options that the user is not allowed to modify with ACUSW.

  • Runtime Options
Parent topic: Compiler and Runtime
Parent topic: Runtime Options


Runtime Options

The allowed runtime options include:

-# This option must be followed (as the next separate argument) by a series of letters that determine which SPECIAL-NAMES switches to turn on. There are 26 SPECIAL-NAMES switches. The letter a corresponds to switch 1, b to switch 2, and so forth. For example, to start the program with switches 1, 5 and 8 turned on, specify -# aeh.

For convenience, you can turn on any of the first 8 switches by simply specifying the switch number or numbers without the # argument. For example, -# aeh can also be specified as -158.

-a | This flag is now obsolete and should not be used.
--a2n | Indicates to use the AcuToNet.dll method of .NET support. For version 9 and earlier, this interface provides .NET support. By default, this interface is no longer needed in versions 9 or later of ACUCOBOL-GT. A new internal method of .NET support was added to version 9 that enables greater .NET support than what could be achieved with the previous AcuToNet.dll method. If you experience issues with the new method of .NET support, you can revert back to the previous method by using this runtime option. There are other steps you must also perform. See Using AcuToNetdll Interface for more information.
--analyze | This option turns on runtime tracing for the program being run. See Dynamic Runtime Tracing for full details.
-b | Inhibits terminal initialization done by runcbl. This can be useful if the program is run in background because terminal initialization can prevent normal use of the terminal by the operating system. This is particularly true on UNIX systems. If you specify this flag, the behavior of ACCEPT and DISPLAY statements is undefined; therefore use this flag with caution. A program can examine the ACU-NO-TERMINAL field after an ACCEPT FROM TERMINAL-INFO statement to determine whether it was started with -b. See ACCEPT Statement (Format 3) for more information.
-c This option must be followed (as the next separate argument) by the name of an alternate runtime configuration file. It causes runcbl to use this configuration file instead of the default file. See Runtime Configuration.

Remote name notation is allowed for this option if your runtime is client-enabled. See Remote Name Notation

--char2gui This option converts character-based screens into graphical equivalents for AcuBench Screen Designer use. When you run your program with this option, ACUCOBOL-GT's Character-to-GUI Wizard launches in the background.

After your program starts, navigate to the screen you want to convert and right-click on the window's background. A pop-up menu appears. Select Build Graphical Screen to continue with the conversion. The Character-to-GUI Wizard then creates a graphical version of the current screen and displays it together with a Properties dialog box. You can use the Properties dialog box to make some basic changes to the screen. Repeat this process for each screen you want to convert.

When you are done, exit the application. When the application exits, the run time writes an import.out file into your current working directory that contains information describing the converted screens. You can then start AcuBench and, using the Add Screen function, display the contents of the import.out file in a Screen Designer window. If you already have a file called import.out in your current working directory, the wizard overwrites it; therefore, if you intend to convert screens in stages, you should rename the file and save it in a separate directory.

If you execute the program in AcuBench, the workbench creates a new program in the workspace Structural View upon exit. The program's Screen node contains entries for each screen described in the import.out file. Those screens open in the workbench development area, where they can be modified. Screen node entries can be moved in the workspace as needed.

The purpose of the Character-to-GUI Wizard is to simplify the initial task of converting traditional text-based applications into ones that use a graphical user interface. Although the wizard greatly reduces the task of converting character-based screens, it is only a first step in the process. It is expected that after you use the wizard, you will spend time manipulating the screens to your liking using AcuBench Screen Designer. You will also need to integrate the newly generated screen section code back into your program. See the AcuBench User's Guide for more information on using the Character-to-GUI Wizard.

-d | This starts the program in debugging mode. See Runtime Debugger.
-e This option must be followed by the name of a file (as the next separate argument). This option causes the error output from the run time system to be placed in this file. This can be used to trap run time system error messages and trace output. -e creates a new file or overwrites an existing file. Use +e to cause error output to be appended to the file. The format of the output can be tailored with the TRACE_STYLE configuration variable.

When specifying a run time error file name you can use the following format specifiers:

  • %p - If the name contains the string %p, that string is replaced with the process ID (PID) of the run time.
  • %d - If the name contains the string %d, that string is replaced with the current date in the form YYYYMMDD where YYYY is the year, MM month, and DD day.
  • %t - If the name contains the string %t, that string is replaced with the current time in the form HHMMSSTTT where HH is the hour, MM minute, SS second, and TTT milliseconds.
  • %u - If the name contains the string %u, that string is replaced with the username.
  • %h - If the name contains the string %h, that string is replaced with the hostname.

Note that these specifiers may also be used in the file names configured with the ACU_MON_FILE and ACU_DUMP ACU_DUMP_FILE ACU_DUMP_WIDTH ACU_DUMP_TABLE_LIMIT configuration variables configuration variables.

Under UNIX systems, redirecting error output causes problems for more and vi. For this reason, we offer two options for redirecting error messages under UNIX:

  • -e - causes all of the runtime's tracing and error messages and DISPLAY UPON SYSERR output to go to "errorfile". It does not redirect stderr. This means that error output from programs called by CALL SYSTEM is not redirected. If you call more or vi from within COBOL, you can safely use -e to redirect error messages.
  • -ee - If you expect programs called by CALL SYSTEM to send their errors to the error file, use the option -ee instead of -e.

Remote name notation is allowed for this option if your runtime is client-enabled. See Remote Name Notation for more information.

--embedded-config-file This option causes the runtime to load and use a configuration file embedded in a COBOL object library. The name of the embedded configuration file can be specified with the runtime -c option. Otherwise, it must be named cblconfi or cblconfig.

The configuration file may be embedded either by using cblutil or the COPY RESOURCE statement.

The object library must be preloaded using the run time -y command-line option. This allows configuration file settings to be available before the primary module is loaded.

Certain configuration variables must be set before the object library is loaded. Therefore, these variables cannot be set in an embedded configuration file. The following is a list of variables that cannot be set in an embedded configuration file:

  • CGI
  • MESSAGE-QUEUE-SIZE
  • ICON
  • NO-CONSOLE
  • LOCKS-PER-FILE
  • TEST-CHAR
  • MAX-FILES
  • MAX-LOCKS
  • WINDOW-TITLE

The run time uses the following higher default values for the LOCKS-PER-FILE, MAX-FILES , and MAX-FILES variables when --embedded-config-file is specified:

  • 256 LOCKS-PER-FILE
  • 255 MAX-FILES
  • 512 MAX-LOCKS
-f | This option ensures that the run time does not perform user interface functions when the COBOL program is functioning as a Common Gateway Interface (CGI) program on the Internet. This option causes the run time to suppress warning messages that are normally displayed in a message box. If the run time shuts down due to an error that is not handled by the COBOL program, it constructs an HTML page containing the shutdown message and sends it to the standard output stream before terminating. This option performs the same function as the environment variable A_CGI but does not affect the entire environment.
-g | This option causes the error file (specified after the -e option) to be compressed with the gzip compression method. A compressed file must be decompressed with gzip before reading or editing. For clarity, give the error file a .gz extension. When appending to an existing file (with the +e option), you must use the same format (compressed or uncompressed) in which the file was originally created.
-h | This option causes the run time to explicitly ignore hang-up signals. You can also ignore hang-up signals by specifying both the -s and -b options. However, the -sb combination also inhibits terminal initialization and prevents the user from killing a program with an abort key such as Control-C or Delete. Unlike -sb, the -h option ignores only the hang-up signals.
-i This option must be followed (as the next separate argument) by a file name. This causes the keyboard input to be taken from this file. It can be used as an alternate to input redirection on UNIX systems. Remote name notation is not allowed for this option.

Examine your input files carefully, paying particular attention to the way the <enter> key is represented. On many systems, it is represented by a hex 0A (line feed). Note that the line feed does not, by default, terminate an ACCEPT.When using -i, add the following to your cblconfig file:

KEYSTROKE TERMINATE=10 ^J

This option has no effect on Windows platforms.

-import This option is available only on Windows and Windows NT systems. It requires the file WEXPRT32.DLL, which must be installed in the same directory as the run time executable. This option is used to import graphical screens created with ACUCOBOL-GT Version 3.x or AcuScreens so that these screens can be used with the AcuBench Screen Designer. If you are running with this option, simply right-click any window to have the opportunity to add it to the file import.out. See the AcuBench documentation for details.

The original purpose of the screen import utility was specifically to upgrade users from AcuScreens to AcuBench, and it was not intended as a permanent device to keep importing all the new screens you create either from scratch or from AcuBench. For that reason, when new control types are added, the screen import utility is not necessarily updated at all, or it may be updated with basic information about the new control type but not all the different properties and styles of the new control type. You should not rely on this utility to be able to import all new screens you create.

When the screen import utility tries to import an unrecognized type or property of a control, you will see the following message on your screen:

This screen contains at least one control type that the Screen Import Utility does not know about. You should add these controls manually.

-k This option causes the immediate playback of a keystroke file. It must be followed (as the next separate argument) by a file name. The filename argument is the name of a file containing recorded keystrokes. The run time internally calls W$KEYBUF using opcode 9 and this file name prior to executing the first COBOL program. The effect is that the keystrokes recorded in the file are treated as the runtime's first user input.

See W$KEYBUF, for more information. Remote name notation is not allowed for this option. Use this as an alternative to -i in Windows systems.

-l | Prints the run time configuration file on the error output. Prints the run time version number on the first line. Also prints the steps taken by runcbl when it is trying to load a program, along with any problems encountered. This is useful for debugging problems with the configuration file or program path resolution. See Run time Configuration for more information. This is best used with the -e option to capture the debugging information in a file.
-m value file | Turns on memory handling descriptions. These descriptions report detailed information about memory allocation, reallocation, and frees. See Memory Handling Descriptions for more information.
--no-acusw | Inhibits the processing of the ACUSW environment variable.
--no-save-debug This option prevents the debugger from:
  • Reading the .adb file, thus causing the debugger to start in its default state.
  • Writing out a new .adb file when it exits.

The debugger saves state information in a .adb file which is used when the debugger is executed in another run. This information includes window placement and breakpoint settings. There are some cases when you may find this inconvenient, and the --no-save-debug option provides a way to eliminate this behavior.

--no-signal-handlers | This switch allows you to initialize the run time without installing its signal handlers. This option is designed for use in environments like CICS that call the ACUCOBOL-GT run time from a C main program and want to install their own signal handlers. See acu_abend() for more information.
-o This option must be followed by the name of a file that will take the display output from the program. This is similar to output redirection on UNIX systems. If +o is used instead, then the output is appended to the named file. Remote name notation is not allowed for this option.

This option has no effect on Windows platforms.

-p | Activates a built-in execution profiling facility, prompting the run time to collect information about I/O operations and CALLs, and to install a timer to track the amount of time spent in different parts of the code. Information collected by the run time is placed into an output file called acumon.xml. Use the -p0 option to include zero execution count paragraphs in the report. See The Profiler for more information.
-p0 | Tells the profiler to include zero execution count paragraphs in the acumon.xml file. See The Profiler for more information.
-r | Starts the program in debugging mode (like -d). This option must be followed by the name of a file containing debugging commands. The debugger is run under control of this file. Remote name notation is not allowed for this option.
-s | Runs the program in safe mode. On non-UNIX systems, the -s option prevents the user from killing the program with the operating system's abort key (Control-C, Delete, etc.). However, any kill command interrupts the program run. On UNIX systems only, the -s option must be issued twice (runcbl -ss) to protect it from the system's abort key. This option allows only a kill -9 to stop the program run. Safe mode can help preserve the integrity of files used by the program. If the program is not in safe mode, then runcbl closes its files if the user kills the program. This keeps each file intact but does not keep separate files synchronized with each other, which may be required by the your application.
-t This option can be used to capture the runtime's terminal output to a disk file. This option must be directly followed by a filename of the output file.

The -t option can be used instead of piping the output to the tee command. Notice that piping runtime output to tee can cause the runtime to hang. This is because run time detects that the output is not a terminal and so it will not set terminal attributes for the terminal. In such state, the run time has a hard time accepting input, and the output may not be flushed to the screen in a timely manner.

When the -t filename flag is set, all the output to the terminal goes to this file, including cursor addressing This option can be used only with a version of the runtime which has an addressable terminal capability. It does not work with any of the graphical run times or the Windows console run time.

--time Causes the run time, to write the total real time spent executing to its error output file upon shutdown. Use this option to measure the time it takes to execute a stand alone batch program.

Note that such real time measurements are inexact, because they do not account for time spent on other tasks or waiting for external output.

-u | By default, the run time tests each use of a LINKAGE data item to check that the item passed by the calling program is at least as large as the item declared by the called program. This ensures that unallocated memory is not accidentally referenced. The -u option disables that test, as well as the test that verifies that all parameters of a subprogram were passed by the caller. (he same can be accomplished with the CHECK_USING configuration variable.
-v | Displays pertinent details about the runtime, including the current version number of runcbl, the Data Execution Prevention status, the serial number, and the maximum number of users licensed to use the run time simultaneously. No program is run.
-vv | (double v) Prints the current version number of runcbl, along with extended information. No program is run.
-vvv | (triple v) This option is valid on UNIX systems and causes runcbl to display additional configuration information about the UNIX port. The information varies depending on the UNIX system and is subject to change without notice. No program is run.
-w | This has the same effect as specifying WARNINGS 0 and MAKE-ZERO 0 in the run time configuration file. This option is provided for compatibility with previous versions of ACUCOBOL-GT. It is recommended that the corresponding configuration entries be used.
-x | When a file error 30 occurs, the root cause of this error is often not apparent. Specifying -x displays the operating system's corresponding error number on the error output. This information may help in determining the problem. You can use the -e option to direct the error output to a file.
--xreturn

Emits a status code if the run time fails to start properly. It may be used from the command line, but it is most useful with the acu_initv function. The code indicates the source of the failure. The possible status return values are:

  • 0 - Success
  • -1 - License has expired
  • -2 - License is not found
  • -3 - License user count exceeded
  • -4 - Library initialization failed
  • -5 - Library load failed
  • -6 - Configuration error
  • -7 - Debug initialization failed
  • -8 - File manager initialization failed
  • -9 - Memory allocation failure
  • -10 - Remote file manager initialization failed
  • -11 - Runtime initialization failed
  • -12 - Profile initialization failed
  • -13 - Mismatched version between runtime and support module
  • -14 - Exception encountered
-y Causes the run time to pre-load the -e specified ACUCOBOL-GT object library, UNIX/Linux shared object library, or Windows DLL. This option must be followed (as the next separate argument) by the name of the library to load. You can pre-load multiple libraries by specifying multiple -y options. If the library is a DLL, the C calling convention can be specified after the name. See Loading DLLs with Configuration Variables for more information.

The directory of the object module and ENTRY points contained in the library are loaded by the run time before it loads the main program. All of the object modules in the library are thus available to be called at any time. The main program may be contained in the library because the library is loaded first.

When specifying a shared object library, you can include the file suffix or use the SHARED_LIBRARY_EXTENSION configuration variable to specify the filename extension.

Note that shared libraries can also be loaded with the SHARED_LIBRARY_LIST configuration variable. You can also use the SHARED_LIBRARY_PREFIX configuration variable to specify a set of directories that the runtime will search when attempting to locate a shared library. For more information on these variables, see their entries in Configuration Variables.

Libraries loaded with the -y option remain in memory until the process exits. The CANCEL statement cannot be used to unload the library.

ACUCOBOL-GT object libraries are described in more detail in Object File Utility - cblutil Windows DLLs and UNIX shared libraries are described in Working with Windows Technologies and Working with C and C++ Programs.

Remote name notation is allowed. See Remote Name Notation.

Note: -y does not load client-side DLLs for thin client applications that make calls using the CALL verb @[DISPLAY]: syntax. These applications must explicitly load the DLL by calling it with the CALL verb before calling a function within the DLL.
-z | After an unexpected run time termination resulting from a memory access violation, this option causes the program to output the current contents of memory where the violation occurred.
Parent topic: Using the Runtime System
Parent topic: Runtime Options


Compatibility Modes

ACUCOBOL-GT is designed to make porting programs between different environments as easy as possible. To aid in this, the compiler runs under one of five compatibility modes. These five modes support source code portability to/from VAX COBOL, ICOBOL, RM COBOL (version 2), IBM DOS/VS COBOL, and HP COBOL programming environments. ACUCOBOL-GT supports a reasonable subset of these COBOL implementations. This is accomplished in two fashions. When these compilers have differing but distinct syntaxes for accomplishing the same thing, all syntaxes are supported. For example, in RM/COBOL, the word BLINK is used to turn on the blinking attribute. In VAX COBOL, the phrase used is WITH BLINKING. Because these phrases do not conflict with each other, both are supported.

In some cases, the compiler cannot simultaneously accept both methods of doing something because they conflict. For example, VAX COBOL and RM/COBOL have different rules for determining the default cursor position for a DISPLAY statement. In this case, ACUCOBOL-GT defaults to using the VAX COBOL interpretation unless the -Cr or -Ci flag is used at compile time. The use of these flags is detailed in Compatibility Options.

Many operational characteristics can be configured at runtime. See Runtime Configuration for more information.

See ANSI ACCEPT and DISPLAY Verbs for compatibility information concerning ANSI ACCEPT and DISPLAY verbs.

Parent topic: Compiler and Runtime


Source Formats

ACUCOBOL-GT supports two different source formats:

  • ANSI format
  • Terminal format

ANSI format has the following characteristics:

  • Columns 1 - 6 are used for sequence numbers. This area is ignored by the compiler.
  • Column 7 is the indicator area.
  • Columns 8 - 11 are area A.
  • Columns 12 - 72 are area B.
  • Columns 73 - 80 are the identification area. This area is ignored by the Compiler (but see Source Code Control below).
  • Lines are 80 characters long. Lines shorter than 80 characters are padded with spaces, and longer lines are truncated.

Terminal format is convenient for developing programs interactively. This format has the following characteristics:

  • The sequence number area is eliminated.
  • The indicator area is in column 1. All of the usual COBOL indicators are accepted here except for the conditional debugging line indicator D. This indicator must be preceded by a backslash (\) in column 1 (placing the D in column 2).
  • Area A also starts in column 1 unless an indicator is present, in which case it starts immediately after the indicator character.
  • Area B starts in column 5 and extends to the end of the line.
  • The identification area starts when a | or *> is encountered, provided it is not part of a literal. The Identification Area extends to the end of the line. This can be used to introduce in-line comments.
  • The line ends when a carriage-return or new-line is found. Lines may be longer or shorter than 80 characters.
    Note: Although the Compiler accepts lines longer than 80 characters, the runtime debugger does not display characters past the 80th column. If possible, use the AcuBench runtime debugger in such cases.

ACUCOBOL-GT Terminal format is compatible with the VAX COBOL terminal source format, except for the introduction of the identification area, which VAX COBOL does not support. ACUCOBOL-GT Terminal mode is also compatible with ICOBOL terminal source format except that area A must start in column 1 (in ICOBOL area A may start in column 2).

Both formats expand tab characters to every eight spaces. Both formats also translate lower-case characters to upper-case except in literals. Finally, both formats translate the underscore character to a hyphen when it is found in identifiers.

Normally, the Compiler determines the source format automatically by examining the first character of the first non-blank line. If this character is blank or a digit, the file is assumed to be an ANSI file; otherwise it is assumed to be in terminal format. This is done independently for the main source file and all COPY libraries. This allows mixing of formats among a source file and its COPY libraries. If desired, the format to use for the entire input source can be set to either mode via the -Sa or -St compile flags.

Parent topic: Compiler and Runtime


COPY Libraries

The COPY verb accepts the following forms:

COPY library-name [ OF path-name ] [ SUPPRESS ].
COPY RESOURCE resource-name [ OF path-name ].

where library-name and path-name are either user-defined words or alphanumeric literals. resource-name is an alphanumeric literal.

Environment variables may be used in path-name -- this is indicated by a $ sign before the name of the variable. For example:

COPY library-name OF "$COPYLIB".

You may also use multiple environment variables to define a path:

COPY library-name OF "$LIB/$COPYLIB/$SUBDIR".

library-name is the file name of the copy file to include in the object library. resource-name is a file (other than a COBOL object) that is to be included in a COBOL object library. If path-name is specified, then it is treated as a directory specification for library-name or resource-name.

The file name is derived by concatenating path-name with library-name or resource-name, using the appropriate syntax for the host operating system. For example, on a UNIX system,

COPY MYCOPY OF "/usr2/acctdir"

is translated to

COPY "/usr2/acctdir/MYCOPY".
Note: Note the use of quotation marks on path-name and on library-name and resource-name when they include lower case letters. This is a requirement on systems that are case sensitive, because the runtime would otherwise convert lower case to upper case.

The -Ce compatibility option can be used to specify an alternate default file extension. See Compatibility Options for more information.

A library name can be specified by a user-defined word which may include a period. This is a special extension to the meaning of user-defined word. This allows you to specify a file extension without putting the name in quotes. For example, the two statements:

COPY "MYFILE.CPY"

and

COPY MYFILE.CPY

are both allowed and mean exactly the same thing.

When a period is placed in a library name which is a user-defined word used without quotes, it must be preceded and followed by a (non-period) character normally allowed in an identifier (thus .MYFILE, MYFILE. and MYFILE..CPY are all disallowed).

In addition, the COPY RESOURCE statement allows the resource name to be a user-defined word just like in a Format 1 COPY statement (the resource name does not have to be an alphanumeric literal).

Note: User-defined words are always treated as uppercase on machines where file names are case-sensitive.

If the derived file name is a full path name or contains a drive designation, then that name is used unmodified. Otherwise, a series of directories is searched to find the COPY file. The default search path is just the current directory.

You can modify the search path by setting an operating system variable. On UNIX, Linux, and Windows systems, you do this by setting the environment variable COPYPATH to be the list of directories to search. For VMS systems, the symbol COPYPATH is set instead.

The COPYPATH variable consists of a series of prefixes to apply to the file name. Each prefix is terminated by a special character that depends on the host operating system.

System | Separator
Windows | Semicolon
UNIX/Linux | Colon
VMS | Comma

For example, to search the current directory, the directory /u/pr and the directory /u/ap on a UNIX system, the appropriate COPYPATH setting would be:

:/u/pr:/u/ap:

The initial colon indicates an empty prefix (i.e., the current directory). Note that the -Sp compiler option can also be used to specify the search path for COPY libraries. If used, it takes precedence over the COPYPATH setting.

You may use the word SUPPRESS to exclude the contents of a COPY file or any COPY files nested within from the program listing. For example:

COPY MYFILE OF "$MYLIB" SUPPRESS.

COPY statements may contain other COPY statements. This nesting is limited by the total number of files that the operating system will allow a program to open at once.

  • Resource Files
Parent topic: Compiler and Runtime


Resource Files

A resource is a piece of static data (such as a bitmap) that is required by the program and is embedded directly into the object file. Because a resource is not actually a separate file in the target environment, using resources reduces the number of physical files required on the target machine and thus can simplify the installation of your programs. Using resources is essential if you want to include bitmap images or sound files in an application that will be dynamically loaded over the World Wide Web. Bitmap files (BMP and JPEG), sound files (WAV), ActiveX resource files, and runtime configuration files are the only types of resources supported in the current version of ACUCOBOL-GT.

Note: In order to use JPEG files, you must have the file ajpg32.dll installed in the same directory as the runtime. Only 32-bit runtimes support JPEG format images. If you need JPEG support on 64-bit Windows, run the 32-bit runtime or the Thin Client. You can also run the Thin Client with the 64-bit runtime.
  • General Rules for Resources
Parent topic: COPY Libraries


General Rules for Resources

The following rules apply to resources in general.

  1. Resources are files (other than COBOL objects) that are included in a COBOL object library.
  2. Resources are named as if they were files, but without any directory information. A resource takes on the same base name as its source file (including suffix). For example, if you include the resource c:\mystuff\toolbar1.bmp, that resource would be called toolbar1.bmp in the COBOL object library.
  3. Resources preserve the case of their names in the object (as specified at the time they were included in the object). However, resource names are matched regardless of case. Thus, in the preceding example, a program could refer to the resource as toolbar1.bmp or ToolBar1.Bmp with identical results.
  4. A resource name with a hyphen (MY-FILE) is considered equivalent to the same resource name given with an underscore (MY_FILE).
  5. Resources are accessed by various specific COBOL subroutines or operations. Currently, there are five useful resource types. These are: bitmap, JPEG, WAV, ActiveX resource, and runtime configuration files. The library routines W$BITMAP, WIN$PLAYSOUND and C$RESOURCE can access resources. See Using the Runtime System for information about embedding a runtime configuration file in an object library.
  6. The presence of one or more resources in an object converts that object into a library. A library consists of a collection of COBOL objects and resources (either of which may be absent). COBOL objects are named in a library by their PROGRAM-IDs, while resources are named by their file names. The CALL verb ignores resources when trying to find a COBOL object, and resource processing routines (such as W$BITMAP) ignore COBOL objects when trying to find a resource.
  7. You can include a resource in an object file by using either the COPY RESOURCE statement or by using cblutil -lib.
Parent topic: Resource Files


Source Code Control

ACUCOBOL-GT provides a method for conditionally modifying the source program at compile time. This is accomplished by having lines in the source that can be excluded or included at compile time. This can be used to maintain different versions of the program, perhaps to support different machine environments.

The -Si (include) flag controls the actions of the source code control system. It must be followed by an argument that specifies a pattern that the compiler will search for in the Identification Area of each source line. If the pattern is found, then the line will be included in the source program, even if it is a comment line. However, if the pattern is immediately preceded by an exclamation point, then the line will be excluded from the source (i.e., commented out). The exclamation point here stands for the notion not. Note that the pattern is case sensitive; enclose it in double quotes on systems such as VMS where you need to preserve its case.

The -Sx (exclude) flag works in the same fashion except that its meaning is reversed (i.e., lines with the pattern will be commented out and lines with a preceding exclamation point will be included).

Here is an example. Suppose that a source program is being maintained for both the UNIX and VMS environments. The following piece of code is in the program:

   MOVE "SYS$HELP:HELPFILE" TO FILE-NAME.   VMS
*  MOVE "/etc/helpfile" TO FILE-NAME.       UNX
   OPEN INPUT HELP-FILE.

This program fragment is ready to be compiled for the VMS system. If a UNIX version is desired, then the following command line will correct the source during compilation:

ccbl  -Si  UNX  -Sx  VMS  source

The first -Si flag will cause lines marked with UNX to be included in the source. The second flag will cause lines marked with VMS to be excluded from the source. An alternate way of doing the same thing would be:

   MOVE "SYS$HELP:HELPFILE" TO FILE-NAME.   !UNX
*  MOVE "/etc/helpfile" TO FILE-NAME.        UNX
   OPEN INPUT HELP-FILE.

This would be compiled for UNIX systems with:

ccbl  -Si  UNX  source

The line marked with !UNX is commented out when this command is run because of the exclamation point. This alternate method is particularly appropriate if only two versions are being maintained.

This source code control system can be especially convenient if the source is being maintained for both ACUCOBOL-GT and non-ACUCOBOL-GT environments. The ACUCOBOL-GT extensions can be commented out and marked with a source-code control flag. When the program is compiled under ACUCOBOL-GT, these lines can be included.

Note: The patterns maintained in the Identification Area should be in upper case because some systems convert command lines into upper case. Also note that exclamation points usually need to be quoted on command lines. As a final note, the entire Identification Area is searched for the pattern; other information may be placed there too.
Parent topic: Compiler and Runtime


Run-Time Configuration

Many aspects of the run-time system can be controlled through configuration variables. Configuration variables can be modified by each runcbl site as well as directly by an ACUCOBOL-GT program. This allows a great deal of flexibility in adapting runcbl to a particular system.

Configuration variables are maintained in a configuration file. This is a standard text file that can be modified by the host system's text editor. See Configuration Variables for details on variable syntax and usage.

Topics in this section describe some of the most frequently used configuration variables.

  • File Name Assignments
  • Code and Data File Search Paths
  • File Status Codes
  • Terminal Handling Options
  • File Handling Options
Parent topic: Compiler and Runtime


File Name Assignments

File names referenced in an ASSIGN clause can be dynamically reassigned at runtime by configuration variables (this is sometimes referred to as name aliasing). Each file's ASSIGN name is searched for in the configuration environment and, if found, replaced by the value of the matching configuration variable. The exact meaning of this reassignment is detailed in File Name Interpretation.

For example, if your code contains a SELECT statement like:

INPUT-OUTPUT SECTION.
FILE-CONTROL.
       SELECT idx-file
       ASSIGN TO DISK "idx.dat"
       BINARY SEQUENTIAL
       STATUS IS idx-status.

you could define a name alias for idx.dat in your runtime configuration file by adding the line:

idx.dat  usr2/data/idx.dat

Whenever your application references idx.dat in a SELECT statement, the alias /usr2/data/idx.dat is substituted.

Remote name notation is allowed in file aliases if your runtime is client-enabled.

Likewise, Internet notation is allowed if you are using AcuXML. For example, to read the XML file bookfile.xml over the Internet, you could map the file to its URL in your runtime configuration file:

BOOKFILE http://myserver.mycomp.com/data/bookfile.xml

Note that the XFD files required by AcuXML must still be available locally in the named XFD_DIRECTORY, but the data stream will be read from the server myserver.mycomp.com via HTTP.

Note: Aliasing is strongly recommended for accessing physical devices such as printers. This allows a program to easily adapt to the device naming conventions used at each individual site.

For portability across applications, we recommend the following names for device files:

PRINTER | System spooler, default printer
PRINTER1-9 | System spooler, printers 1-9
FORM | Default special-form printer
FORM1-9 | Special-form printers 1-9
TAPE | Default tape/floppy transport
TAPE1-9 | Tape/floppy transports 1-9

For example, a COBOL program might assign a print file to the system spooler, printer number 2, with the following line:

ASSIGN TO PRINT "PRINTER2"

Although the assignment of these names to physical devices is arbitrary, the following conventions are recommended:

  • PRINTER devices should be assigned to the host operating system's spooler, if applicable. If the host operating system does not have a spooler, they should be assigned directly to the print devices.
  • FORM devices should not be assigned to a spooler. They should, instead, be assigned directly to the printer. These are intended to be used by programs that need to control the printer directly without intervention by another program.
  • TAPE devices can be assigned in any sensible manner.

No names are initially assigned. The process of assigning names is covered in File Name Interpretation.

For more selective aliasing, for example, changing the name of a single Vision segment, see the filename, filename_DATA_FMT, and filename_INDEX_FMT configuration variables described in Appendix H.

Parent topic: Run-Time Configuration


Code and Data File Search Paths

A series of directories can be specified that are used to locate program object files and data files. Object files are located via the CODE_PREFIX configuration variable. Data files are located by the FILE_PREFIX variable.

Each of these variables specifies a series of one or more directories to be searched for the desired code or data file. The search method is detailed in File Name Interpretation and Calling Subprograms.

The directories are specified as a sequence of space-delimited prefixes to be applied to the file name. All directories in the sequence must be valid names. The current directory can be indicated by a period (regardless of the host operating system). For example, the following line:

FILE_PREFIX    .  /usr/data

specifies that data files should first be searched for in the current directory and then in the /usr/data directory. For convenience, colons can be used along with spaces as a delimiter (except on Windows systems where semicolons are used, and VMS systems where commas are used). As an example of this, the following may be specified for a Windows system:

CODE_PREFIX    C:\;C:\OBJ

The "^" (carat) character can be specified in CODE_PREFIX to indicate the directory containing the calling program.

Note: Directory names with embedded spaces can be used as FILE_PREFIX and CODE_PREFIX configuration variables if the directory name is enclosed in quotes, for example:
FILE_PREFIX  C:\"Sales Data"

This example will cause the program to search for files first under the referenced directory name, and then in the current directory.

You can also specify a default file name extension for both code and data files. By default, ACUCOBOL-GT makes no assumptions about the file name extension used by files. A default name extension can be specified for code files by the configuration variable CODE_SUFFIX and for data files with the variable FILE_SUFFIX. These suffixes are automatically appended to any file name that does not explicitly contain an extension. A period is automatically placed between the file name and the extension, if needed.

For example, you can cause all of your object files to have the implicit extension of .COB by placing the following line in your configuration file:

CODE-SUFFIX  COB
Parent topic: Run-Time Configuration


File Status Codes

ACUCOBOL-GT supports five different sets of FILE STATUS code values. These five sets correspond with the values used by RM/COBOL-85, RM/COBOL version 2, Data General ICOBOL, VAX COBOL, and IBM DOS/VS COBOL. By default, ACUCOBOL-GT uses the RM/COBOL-85 values.

You can select another set of file status codes at runtime by setting the configuration variable FILE_STATUS_CODES to one of the following values:

"74" | -RM/COBOL version 2 codes
"85" | -RM/COBOL-85 codes (default)
"DG" | -ICOBOL codes
"VAX" | -VAX COBOL codes
"IBM" | -IBM DOS/VS codes
Note: The set of status codes used depends solely on the current setting of the FILE_STATUS_CODES variable and not on any compile-time settings. This is done to provide a consistent set of status codes to every program in a run unit. If you need to change the set of status codes during a run unit, you can do so with the SET ENVIRONMENT verb. Some programmers use this verb to ensure status code settings for a particular program, or in situations where programs that conform to the 1985 COBOL standard and programs that do not conform are both in use at a site.
Parent topic: Run-Time Configuration


Terminal Handling Options

Many aspects of the terminal I/O sub-system can be modified by configuration variables. These are described in detail in Getting Your Terminals Ready.

Parent topic: Run-Time Configuration


File Handling Options

Some COBOL systems do not abort when a file error occurs and there is no Declarative to handle it. If you desire this behavior, set the runtime configuration entry ERRORS_OK to one of the non-zero values described in the entry for ERRORS_OK in Appendix H. Configuration Variables.

CAUTION:
When ERROR_OK is enabled, file errors that would normally cause ACUCOBOL-GT to abort will instead allow processing to continue. This means that when ERRORS_OK is enabled, you will not get the usual error reporting. Under most circumstances this is undesirable.

Some compilers also automatically create files when they are opened for I/O or EXTEND, if the files are missing. You can simulate this behavior by setting EXTEND_CREATES to 1 if you want to create files opened for EXTEND and setting IO_CREATES to 1 to create files opened for I/O.

RM/COBOL version 2 automatically closes all files except print files when a program executes an EXIT PROGRAM statement. By default, ACUCOBOL-GT does not do this, because it is a violation of the ANSI standard. If the configuration variable CLOSE_ON_EXIT is set to 1, then this behavior is emulated by runcbl. You can also set this variable to 2 to cause all files (including print files) to be closed when a program exits. Setting the variable to zero resets this option.

RM/COBOL version 2 also automatically causes a page eject when a print file is closed unless the WITH NO REWIND option is used on the CLOSE statement. The configuration variable PAGE_EJECT_ON_CLOSE can be set to 1 to cause this behavior. Setting it to 0 causes the normal behavior of not ejecting a page.

You can improve the performance of indexed files that are opened WITH LOCK by setting the configuration variable MASS_UPDATE to 1. This causes ACUCOBOL-GT to treat these files as if they were opened with the MASS-UPDATE phrase specified. See Mass Update for details on this phrase.

  • Sort Files
  • Carriage Control
  • Device Locking
Parent topic: Run-Time Configuration


Sort Files

The SORT verb often makes use of temporary files. By default these files are stored in the current directory. You can specify an alternate directory to hold the sort files by setting the configuration variable SORT_DIR to the desired directory. This value is treated as a prefix, so any trailing directory syntax (such as /) is required. You can improve the performance of the SORT verb by placing the temporary files on a fast device. Care should be taken, however, that the device has enough free space to hold twice the size of the data to be sorted.

Parent topic: File Handling Options


Carriage Control

RM/COBOL handles carriage-control characters in a line sequential file differently on different systems. By default, both ACUCOBOL-GT and RM/COBOL-85 remove carriage-control characters from input records for line sequential files. This is the ANSI standard. RM/COBOL version 2, however, does not remove form-feed characters on MS-DOS machines and does not remove form-feed or carriage-return characters on UNIX systems. Some existing RM/COBOL version 2 programs depend on this behavior.

ACUCOBOL-GT can optionally retain any or all of these characters in the input record. If the configuration variable CARRIAGE_CONTROL_FILTER is set to 1, then form-feed characters will be retained in the input record. If it is set to 2, then carriage-return characters will be retained. If it is set to 4, then line feeds will be retained. You may specify combinations of characters to retain by adding their corresponding values together. For example, specifying 6 causes carriage-returns and line feeds (2 plus 4) to be retained. Setting the variable to zero causes the default action of removing all three characters. Note that on VMS systems, carriage control information is not placed directly into data records and is instead maintained separately. For this reason, the CARRIAGE_CONTROL_FILTER setting has no effect on VMS systems and should not be considered portable to those machines.

Parent topic: File Handling Options


Device Locking

Finally, users on UNIX systems who want to make use of runcbl's automatic device locking facility may set the variable LOCK_DIR to the desired lock directory. This process is covered in detail in Device Locking Under UNIX.

There are other configuration options that can affect file operations and performance. See Appendix H in Appendices for a complete listing of configuration options.

Parent topic: File Handling Options


File Name Interpretation

ACUCOBOL-GT employs a rich set of rules when translating a file name specified in an ASSIGN clause to an actual file name used on the host system. These rules provide a great deal of flexibility in placing files and dynamically reassigning them. These rules also allow for convenient handling of printers and other special devices. See Device Locking Under UNIX for examples that illustrate many of the rules listed below.

When interpreting a file name, runcbl performs the following steps in order:

  1. The initial name is taken from the ASSIGN clause of the file. If not specified in the ASSIGN clause, then the internal name specified by the SELECT clause is used instead.
  2. The name is examined to see if FILE_ALIAS_PREFIX should be applied.
    • The file name is constructed by prepending the first string listed in FILE_ALIAS_PREFIX to the file name. The runtime searches for that name in the environment or the configuration file.
    • If the name is not found, the runtime constructs a new name by prepending the second string in FILE_ALIAS_PREFIX and searches for that alias.
    • The process is repeated with each string in FILE_ALIAS_PREFIX until a file alias name is found or the end of the list is reached.

    If the file name includes a dollar sign ($) and EXPAND_ENV_VARS is set to one (1), the FILE_ALIAS_PREFIX logic is applied to the environment variable name. So, for example, $FILE1 and FILE1 are treated the same.

  3. If this name does not start with a hyphen, then it is searched for in the environment. First the runtime system's configuration variables are searched, followed by the host system's environment. The value of the variable found becomes the new name. This search is then repeated until either no new translation is found or the new name starts with a hyphen. Note that when the runtime system's configuration variables are initially loaded, any name found in both the runtime's configuration file and the user's environment is taken from the user's environment.

    For example, if the name PRINT-FILE is assigned to PRINTER1 in the ACUCOBOL-GT configuration file, and you have PRINTER1 assigned to /dev/lp in the host's environment, then opening a file called PRINT-FILE will actually open the file /dev/lp. PRINT-FILE is first translated to PRINTER1 and then "PRINTER1" is subsequently translated to /dev/lp.

  4. If the name starts with a hyphen, it is interpreted in a special fashion described below. If it does not start with a hyphen, then it is considered to be a normal file name. This name is further processed as follows.
  5. If the FILE_CASE configuration variable has been specified, the change to upper case or lower case is applied if appropriate.
  6. The name is examined to see if it has an extension (zero to three characters following a period). If it does not, and the FILE_SUFFIX configuration variable has been defined, then the value of the FILE_SUFFIX is added to the name, with an intervening period if necessary.
  7. The name is examined to see if FILE_PREFIX should be applied.
    • If the name contains a disk drive designation, or begins with a \ (back slash), processing continues at step 8.
    • If the name begins with a / (forward slash) and the configuration variable APPLY_FILE_PATH is set to off (0), processing continues at step 8.
    • If the name begins with a / (forward slash) and the configuration variable APPLY_FILE_PATH is set to on (1), the current FILE_PREFIX is applied to the name and processing continues at step 8.
    • If the name does not contain a full path or drive designation, the current FILE_PREFIX is applied to it and processing continues at step 8.

      FILE_PREFIX is a configuration variable that contains one or more strings that are prefixed to the filename. After each string is prefixed and the EXPAND_ENV_VARS variable is checked (see step 8), runcbl tries to find a file by that name. If it finds the file, processing of the name stops. If it does not, the next prefix is tried until no more prefixes are available. A prefix consisting of a single period (.) is treated as an empty prefix (i.e., the current directory is used).

  8. Before the runtime tries to find the file, if EXPAND_ENV_VARS is set to on (1), the runtime expands any environment variables found in the name. A file specification that includes a $ character will have all the characters from $ to the end of the name or to the next / or \ replaced with the value of the matching environment variable. The runtime now attempts to find the file. If the file is found, processing stops. If the file is not found and there is another FILE_PREFIX to apply, the prefix is applied and step 8 is repeated. If all the prefixes have been tried and the file has not been found, the first prefix is re-applied, and processing of the name stops. This means that files newly created by runcbl will reside, by default, in the first directory specified in the FILE_PREFIX configuration variable.

Upper or lower case in a file name is significant if it is significant to the host operating system. The same is true when the host environment is searched for a translation. Upper or lower case is not significant when runcbl's local environment is searched for a translation.

  • File Names Starting With a Hyphen
  • File Name Examples
  • Assigning Files to Local Printers
Parent topic: Compiler and Runtime


File Names Starting With a Hyphen

File names that start with a hyphen are treated specially. The hyphen and the following character are removed, as are any spaces following that character. The rest of the name is interpreted depending on the character after the hyphen as follows:

  1. If the character is an F, then the name is treated as a normal file name. This differs from the default handling only in that the name is not further translated (i.e., no further searching in the environment and no application of the FILE_PREFIX or FILE_SUFFIX). This is useful if you want to ensure that a file name is placed in the current directory or remains untranslated.
  2. If the character is a D, then the name is treated as the name of a device. This is treated no differently than the case for F above, except that file locking rules are slightly changed for devices. Devices may be assigned only to SEQUENTIAL files.
  3. If the character is a P, then the name is treated as the name of a program to run. On UNIX systems, a pipe is created between runcbl and the named program. This program will then either receive data written to the file or provide the data read from the file.

    On Windows and VMS systems this is handled somewhat differently. The translation of the name must contain at least two space-separated words. The first word is treated as the name of a file to write or read. This name is not further translated and is handled as a standard SEQUENTIAL file. The second and following words are treated as the program to run. If the file is being opened for input, the program is run first and then the named file is opened. If the file is being opened for output, then the named file is first opened normally; when this file is finally closed, the named program is run. Typically the program should either create or read the named file as is appropriate.

    On Windows and VMS systems you have the option of using the phrase %TMP% in place of a file name. In this case a unique name is created for you, and that same name is substituted for %TMP% every place on the line that the phrase is found. It is advisable to finish with (or rename) the file within 19 days, to avoid the possibility of name conflicts with names generated in the future. (See the examples below.)

    If you use the %TMP% option to assign a file to a simulated pipe (by using P in the assign name), you can specify where the temporary file will reside. This is done with the TEMP_DIR configuration entry. It acts just like the SORT_DIR entry, except that it applies only to %TMP% files.

    On Windows systems, if you append an ampersand (&) character to the command line, the program will run asynchronously. This should not be done for programs providing input files, but is often useful for programs processing output files. For example:

        assign to output "-P %TMP% cmd /c edit %TMP% &"

    Program files may be assigned only to SEQUENTIAL files and may not be opened for I/O or EXTEND.

Parent topic: File Name Interpretation


File Name Examples

Following are some examples of the file name translation rules. These examples point out some of the more useful aspects of the translation rules.

  • Example 1: Default Name Handling
  • Example 2: Accessing Printers
Parent topic: File Name Interpretation


Example 1: Default Name Handling

Suppose you wanted to place data files in the \DATA subdirectory on a Windows system. You could then make the following assignment in the configuration file:

FILE_PREFIX    C:\DATA  D:\DATA

In this case, a file being created by an OPEN OUTPUT statement will be searched for first in the C:\DATA and D:\DATA directories. If it is found in either of these directories, that file will be removed and the new file placed in the same directory. If it is not found, however, then the new file will be created in the C:\DATA directory because that is the first one in the list.

Notice that the current directory is not mentioned in the above FILE_PREFIX configuration entry. This means that the current directory will not be searched for files. If you want the current directory to be one of the directories that is searched, add . to the FILE_PREFIX configuration entry. If a particular file must be located in the current directory, use the -F flag. The -F can be specified in the ASSIGN name. For example, if you want to ensure that file DIRLIST is located in the current directory regardless of the value of FILE_PREFIX, place the following clause in your source code:

ASSIGN TO "-F DIRLIST"

The -F flag ensures that DIRLIST is not further translated or modified. Note that the -F flag also ensures that the name is not translated when it is used in a configuration variable. Thus, another way to accomplish the same result, is with these two steps:

  1. Set the file name in the ASSIGN statement as:
    ASSIGN TO "DIRLIST"
  2. To cause the file to be placed in the current directory, place the following line in your configuration variable file, or set it in the environment:
    DIRLIST  -F DIRLIST
    Note: In the above case, the file is placed in the current directory regardless of the contents of FILE_PREFIX.

Normally, you should avoid using the full directory path names or the -F flag in your source code. If you can, use FILE_PREFIX in the configuration file. This will provide the most flexibility in file management for each individual site.

Parent topic: File Name Examples


Example 2: Accessing Printers

ACUCOBOL-GT's name translation rules make it particularly easy to access a site's printers (and other devices) in a machine-independent fashion.

We recommend that you use some pre-designated names in your ASSIGN statements for files that are to be directed to a printer. Using these names will simplify the installation of runtime systems for sites using several ACUCOBOL-GT applications. The ASSIGN name for standard print files should be PRINTER, or one of its variants PRINTER1, PRINTER2, etc. By convention, PRINTER is associated with the default printer on the host system, while the alternate names are associated with additional printers. For print files where you need direct control over the printer (to align special forms, for example), you should use one of the names: FORM, FORM1, FORM2, etc. By convention, FORM devices are directly attached to the printer and PRINTER devices access printers through the system spooler (if available).

Each site can then place the appropriate definitions of these names in the configuration file. The installation of FORM devices is easy--simply name the device using the -D flag. See Runtime Configuration for more information.

For example, to associate the name FORM with the /dev/lp device on a UNIX system, place the following line in the configuration file:

FORM    -D  /dev/lp

It is important to ensure that the users have access permissions to the named devices. For more information about print spooler issues, see WIN$PRINTER WIN$PRINTER.

The installation of PRINTER devices is only slightly more complicated. Because these should be spooled (if possible), you will usually need to use the -P flag to specify a program to receive the print output. The following notes give examples for various operating systems:

  1. On UNIX systems, the name should be translated to the appropriate system spooler. This is usually either lp (for System V) or lpr (for Berkeley UNIX). You will usually need to specify additional flags to access devices other than the default one. If you are using the lp spooler, you should also specify the -s flag to prevent the request id is . . . message from appearing in the middle of your program.

    For example, suppose the site has two printers, a high-speed line printer (the default) and a laser printer. Furthermore, suppose System V UNIX is being used and the laser printer is accessed with the flag -dlaser.

    The following two lines should then be placed in the configuration file:

    PRINTER...   -P  lp  -s
PRINTER1     -P  lp  -s  -dlaser
  2. On VMS systems the usual way to print files is with the PRINT system command. One recommended way of doing this is to enter the following line in the configuration file:
    PRINTER  -P %TMP%  PRINT  /NOIDENT  /DELETE  %TMP%

    Be sure to use the options shown above (NOIDENT and DELETE), and feel free to add other options as desired.

Parent topic: File Name Examples


Assigning Files to Local Printers

For runtimes that use a_termcap, you may assign files to local printers. This makes it easy to switch between local and spooled printing in a single program--all you need to do is assign to a different device.

To assign a file to a local printer, assign the file to the filename LOCALPRINT. The file must be either a print file or a line sequential file, and it must be opened for OUTPUT or EXTEND.

If the terminal does not have enable-print/disable-print control sequences defined for it, you will receive an error 35 when you try to open the file. Otherwise, the open will succeed and you should be able to use WRITE statements normally. Note that the runtime has no way of knowing whether or not a printer is actually attached to the terminal.

The runtime sends an enable-print sequence prior to each line and a disable-print sequence after each line. If you prefer, you may assign to LOCALPRINT-C instead (the C stands for "continuous"). If you do this, then a single enable-print sequence is sent prior to printing the first line, and a disable-print sequence is sent when the file is closed. Note that this will cause any terminal output to be printed, so this should be used with care.

For runtimes that do not use a_termcap (such Windows), you should assign directly to the print device instead. This facility is not currently available under VMS.

Parent topic: File Name Interpretation


Calling Subprograms

ACUCOBOL-GT is not a linked language. Instead, when a subprogram is called it is loaded dynamically at runtime. ACUCOBOL-GT does not use the name specified in the PROGRAM-ID paragraph. Instead, the name specified in the CALL statement is treated as the filename of the object file to load. Actually, runcbl maintains two names for each called object file: its call name (the exact name specified in the CALL statement) and its filename (the name by which the object file is actually found).

An object module can be in one of three states:

  1. Active. This is the state of any program that has been called and has not yet exited. It also applies to the first (or main) program of a run unit. An active program is always memory resident.
  2. Loaded but inactive. A loaded program is one that is memory resident but not running. This is the state of a program that has been called and has also exited. It remains in memory until it is the object of a CANCEL verb. A program in this state keeps its files and data items in the same state that they were in when the program exited. Note that programs with the INITIAL PROGRAM attribute are never in this state because they are automatically canceled when they exit.
  3. Not loaded. This is the initial state of all object files. By default, not loaded indicates that the program is not in memory. However, if the logical cancel mechanism is enabled, the program may be cached in memory. See Memory Management for more information.

EXIT PROGRAM

ACUCOBOL-GT conforms to the 1985 COBOL standard, which specifies that a called program should execute an implicit EXIT PROGRAM if execution runs off the end of the Procedure Division. ACUCOBOL-GT versions prior to 9.1 executed an implicit STOP RUN in this case.

  • CALL
  • CANCEL
  • CHAIN
  • Alternate ENTRY Points
Parent topic: Compiler and Runtime


CALL

When a CALL occurs, runcbl performs the following steps. If during any step the call is resolved, call processing ends:

  1. runcbl searches the DYNAMIC_FUNCTION_CALLS configuration variable for a matching call name or call name prefix. If a match is found and the "dlopen(NULL)" feature is supported (true on most UNIX systems) the call name is searched for as a dynamic function in the current process. If it is not found, the call name is searched for as a dynamic function in each of the loaded shared libraries or DLLs specified with the -y option or with the SHARED_LIBRARY_LIST configuration variable.
  2. If the runtime is acting as an application host in a thin client environment, it checks for the @[DISPLAY]: prefix and, if found, passes the call to the thin client.
  3. The runtime next attempts to call any C subprograms that have been linked into the runtime system. Interfacing to C routines is detailed Calling C Programs From COBOL of A Guide to Interoperating with ACUCOBOL-GT.
  4. If the CODE_CASE configuration variable is defined, the change to upper case or lower case is applied as appropriate.
  5. Next, the list of loaded but inactive programs and their ENTRY points is searched for a matching call name. If a name is found, that program is made active, execution is initiated at the proper point in the program.
  6. Next, all loaded programs (both active and inactive) are searched to see if any are part of an object library. For each object library found, the call name is searched for in the list of modules contained in the library. If found, that module is loaded out of the library and made active. See Object File Utility - cblutil for more information.
  7. Next, on Windows systems the call name is searched for as the name of a routine in a loaded DLL.
  8. Next, any libraries specified with the -y runtime option are searched for a matching call name. Note that programs in a library are searched for by their PROGRAM-IDs.
  9. If the program has still not been found, the disk is searched for the object module.

    The name is examined to see if it is a full path name.

    • If the call name begins with a \ (back slash), the call name is treated as the filename, and the object file (if it exists) is loaded and made active.
    • If the call name begins with a / (forward slash) and the configuration variable APPLY_CODE_PATH is set to off (the default value), the call name is treated as the filename, and the object file (if it exists) is loaded and made active.
    • If the call name begins with a / (forward slash) and the configuration variable APPLY_CODE_PATH is set to on, the current CODE_PREFIX is applied to it. Or, if the call name is not a full path name, the current CODE_PREFIX is applied to it.

    The configuration variable CODE_PREFIXconsists of a series of prefixes to apply to the call name. These prefixes are applied, in order, until a matching file is found or all of the prefixes have been tried. See Code and Data File Search Paths for more information.

    For example, to search for object files in /usr/obj/ar, /usr/obj/ap, and the directory containing the calling program, you could set CODE_PREFIX to:

    CODE-PREFIX  /usr/obj/ar  /usr/obj/ap  ^

    When each file name is formed, the configuration variable CODE_SUFFIX is checked to see if it has been defined. If it has, and the call name does not have an explicit extension specified, the current value of CODE_SUFFIX is appended to the filename with an intervening period. An extension is zero to three characters following a period at the end of the name. If See the topic for CODE_SUFFIX in Appendix H. for more information. is not defined, .acu is appended to the filename. If the file is not found, the file is searched for again, this time without the .acu extension. See the topic for CODE_SUFFIX in Appendix H. for more information.

    Note: As with all filenames, upper and lower case are significant on UNIX machines but not on VMS and Windows systems.
  10. Next, on Windows, the call name is searched for as the name of a DLL. If the DLL is found it is loaded and the call name is searched for as the name of a routine in it or any other loaded DLL.
  11. Next, on UNIX, the call name is searched for as the name of a shared library.
  12. Finally, the call name is searched for as the name of a dynamic function in the current process, and then in each of the loaded shared libraries or DLLs specified with the -y runtime command-line option or the SHARED_LIBRARY_LIST configuration variable. Note that to match as a dynamic function in Step 1 of this process, the call name must match a name in the DYNAMIC_FUNCTION_CALLS configuration variable.
  • Recursive CALLs
Parent topic: Calling Subprograms


Recursive CALLs

A program may directly or indirectly call itself. A CALL statement that calls the active program (itself) is a recursive call. For more information, see RECURSION. For information on sharing data in recursively called programs (such as with HP COBOL), see the RECURSION_DATA_GLOBAL configuration variable.

Parent topic: CALL


CANCEL

When a CANCEL verb is executed, the following steps are performed:

  1. If a CANCEL ALL statement is executed, all loaded programs that are inactive are set to the not loaded state.
    Note: The CANCEL_ALL_DLLS configuration variable can be used to exclude DLLs and shared object libraries from the results of a CANCEL ALL statement. See Appendix H. Configuration Variables for more information.
  2. Otherwise, the list of active programs is searched for a matching call name. If found, an active program is being canceled and the CANCEL is ignored.
  3. Next the list of loaded but inactive programs is searched for a matching call name. If found, this program is set to the not loaded state.
  4. If no matching programs are found, the CANCEL verb has no effect. This is not considered an error.

By default, placing the canceled program in the not loaded state (initial state) includes removing the program from memory. However, if the logical cancel mechanism is enabled, the canceled program is cached in memory. For more information, see Memory Management.

Parent topic: Calling Subprograms


CHAIN

A CHAIN verb performs these steps:

  1. Any USING parameters are first copied to a safe place. These are made available to the chained program through the CHAINING phrase of the Procedure Division header.
  2. All active programs are made inactive.
  3. A CANCEL ALL is implicitly executed.
  4. A new program is loaded using the same rules that apply to the CALL verb. This becomes the main program of the new run unit.

See the entry for CHAIN Statement in Procedure Division Statements for more information.

Parent topic: Calling Subprograms


Alternate ENTRY Points

The ENTRY statement is used to establish an alternate entry point in a program. Such alternate points can occur many times in a single program. To activate a program at the ENTRY point, a CALL statement from a calling program is used. See CALL Statement in File Name Interpretation for details.

See Procedure Division Statements, for complete syntax diagrams and rules regarding the CALL Statement and the ENTRY Statement.

Parent topic: Calling Subprograms


Reducing the Size of the runtime

For a variety of reasons including limited system memory or concerns about runtime system overhead, it is sometimes necessary or desirable to reduce the size of the runtime by removing unused elements. This is accomplished by modifying the special file config85.c and relinking the runtime. Of course, any component removed from the runtime is no longer supported by the system. Programs that attempt to use those components may terminate in unexpected ways.

You can find the file config85.c in the lib subdirectory of your ACUCOBOL-GT installation.

config85.c supports the removal (or re-inclusion) of the following runtime components:

  • source debugger
  • SORT/MERGE support
  • extended exponent support
  • Screen Section support
  • charting support
  • AcuServer client support
  • AcuConnect client support
  • AcuSQL support

Comments in config85.c describe how to modify the file and indicate the approximate reduction in space that will result from the removal of each component.

Parent topic: Compiler and Runtime


acushare Utility Program

The acushare utility program is included on most UNIX and Linux systems. On those systems it provides three key services for deployments that use the ACUCOBOL-GT runtime system and/or AcuServer. These services include:

  • ACUCOBOL-GT runtime license management
  • ACUCOBOL-GT runtime shared memory management
  • AcuServer license management

acushare's role in the extend license management scheme is described in How Acushare License Management Works. acushare's role in shared memory management in UNIX/Linux environments is detailed in Using Shared Memory. Comprehensive instructions on the use of acushare are in Using acushare.

Note that versions of acushare are compatible as follows:

  • Versions of acushare shipped with extend8 products are compatible with all Version 8.x products but cannot be used with previous versions.
  • Versions of acushare shipped with pre-extend8 products can be used with all pre-extend8 products but not with any extend8 products.
  • You can run both extend8 and pre-extend8 versions of acushare on the same system concurrently.
  • Using Shared Memory
  • Using acushare
  • acushare Errors
Parent topic: Compiler and Runtime
Parent topic: Shared Memory


Using Shared Memory

In most UNIX and Linux environments, ACUCOBOL-GT supports the ability to have multiple users share the same copy of a COBOL program's object code in memory. This conserves memory and can lead to improved system performance by reducing the amount of memory paging that the system must do.

Note: Use of shared memory is recommended only in cases where there is a problem with excessive swapping due to too many users for the amount of memory in the machine. If you are not experiencing this problem, enabling shared memory will probably not improve performance. If you are having a problem with limited memory and excessive swapping, then the advantage of reduced swapping usually more than offsets the overhead added by using shared memory. Note that the overhead for using shared memory varies from machine to machine.

The UNIX code sharing facility is built on top of the UNIX System V shared memory facility. In order to use this code sharing, your machine must support shared memory in accordance with the UNIX System V Interface Definition (SVID) and must also have shared memory support enabled in its system kernel. Many UNIX and Linux vendors supply machines with shared memory already enabled, but others require that you reconfigure your kernel to use shared memory. Contact your UNIX vendor if you need additional information on this subject.

One easy way to tell if ACUCOBOL-GT supports code sharing on your machine is to check the files that are installed with the runtime system. If you receive a file called acushare, then that system has the ability to share code. If you do not receive this file, code sharing is not available on that machine (most likely because that machine does not adequately support shared memory).

To share program code under ACUCOBOL-GT, you must perform the following steps:

  1. Install acushare.
  2. Edit your COBOL configuration file to specify the programs you want to share. See Indicating Programs to Share for more information.
  3. Start the acushare program. After it's started, you can use the program to perform other tasks. See Using acushare for more information.
  • Indicating Programs to Share
Parent topic: acushare Utility Program


Indicating Programs to Share

Use your COBOL configuration file to indicate which programs you want to share code. By default, no programs share code. To use shared code for all of your programs, add the following line to the configuration file:

SHARED_CODE  1

This causes all programs to attempt to share code. Every code segment loaded into memory is placed into shared memory until the shared memory area becomes full. If the system runs out of shared memory and the shared code requests start failing, each runtime will have its own copy of the program in its own memory space. The UNIX default for SHARED_CODE is 0 (no programs share code).

Because shared memory is a limited resource under UNIX and Linux, you will probably want to restrict the use of shared code to those programs that render the most benefit. This ensures that other programs do not unnecessarily use up the available shared memory. To do this, specify in your runtime configuration file each program that you want to share as follows:

SHARED_CODE  Program1
SHARED_CODE  Program2
SHARED_CODE  Program3

(The program name may also be enclosed in single or double quotes, for example, Program1 or Program2.) When you are using this method, Program1, Program2, and so forth, specify the PROGRAM-IDs from the programs' Identification Division (note that a program's object file name is not used). If you use this method, setting SHARED_CODE to 1 has no effect.

To maximize the benefits of code sharing, begin by restricting the use of shared code to large programs that have many users. Later, if you find that you have enough shared memory in your system, you can extend its use to small programs that have many users. Use acushare's reporting facility to help you optimize the use of shared memory.

Parent topic: Using Shared Memory


Using acushare

On most UNIX and Linux systems, the acushare utility program is provided to handle ACUCOBOL-GT runtime and AcuServer license management, as well as shared code segments used by the ACUCOBOL-GT runtime. On these systems, acushare runs as a background server process that responds to requests from various client runtimes (a daemon in UNIX terminology). See the Getting Started Guide for a description of acushare's role in extend license management. See Using Shared Memory for a description of acushare's role shared memory management.

acushare has several command-line formats. They include:

acushare -start [ -p portnumber ] [ -e errorfile [ -g ] ]
acushare –kill
acushare –clean
acushare –version
acushare

These formats are described in the following sections.

  • acushare -start
  • acushare -kill
  • acushare -clean
  • acushare -version
  • acushare (with no options)
Parent topic: acushare Utility Program


acushare -start

The command for starting acushare is:

acushare -start [ -p portnumber ] [ -e errorfile [ -g ] ]

A successful start creates a background process that handles license management and shared code. You can specify:

acushare -start -f ...

to have acushare run in the foreground.

By default, acushare obtains a port number (for the listening port) from the operating system. If you want to direct acushare to listen on a specific port, you can include the -p option followed by the desired port number. For example:

acushare -start -p 12345

If the -e option is included, acushare error output is appended to the file named after -e. If -e is not used, error output is sent to /dev/console by default. If output is not allowed on /dev/console, acushare attempts to append to a file named acushare.err in the current directory. If that fails, acushare prints the message acushare: cannot open error output file to standard output and the process exits.

If -e is specified, you can optionally use -g to cause the error file to be compressed with the gzip compression method. Such files must be manually decompressed with gzip before reading or editing. For clarity and to reduce the risk of confusion or error, it is recommended that you specify a .gz extension in the filename. For example:

acushare -start -eg acushare_trc.gz
  • Automatic Startup at System Boot
Parent topic: Using acushare


Automatic Startup at System Boot

If you want acushare to start automatically when the system boots, you can add a small amount of code to the system boot file. The name of the boot file varies from system to system. Typical names are /etc/rc.local, /etc/brc or /etc/rc. Identify the proper startup file and add lines similar to the following:

if [ -f /usr/etc/acushare ]; then
   echo Starting ACUCOBOL-GT shared-code and license daemon > \
        /dev/console
   /usr/etc/acushare -start > /dev/console
fi

The preceding example assumes that you've placed acushare in /usr/etc. You will need to adjust the code to match the conventions used in your environment.

Parent topic: acushare -start


acushare -kill

To halt acushare, simply enter acushare -kill on the command line.

Should acushare terminate unexpectedly (for example, due to a SIGKILL signal), you should remove the stranded shared memory segment with the -clean option before restarting. See acushare -clean for more information.

Parent topic: Using acushare


acushare -clean

Should acushare terminate unexpectedly, its master shared memory segment may be left behind. Before restarting acushare, you should use the acushare -clean command to remove the stranded memory segment.

Parent topic: Using acushare


acushare -version

This option causes acushare to print its version number.

Parent topic: Using acushare


acushare (with no options)

If acushare is not running and you enter the acushare command without any options, the following message is displayed:

acushare: not running

If acushare is running and you enter the acushare command without any options, you will get a detailed report of acushare status and usage. The following is the output of the acushare server running with two shared programs:

ACUCOBOL-GT shared memory and license manager version 8.0.0 (2005-04-18)
Copyright (c) 1993-2008, Acucorp, Inc.

Server Statistics:
==================

server PID: 19134
IPC key: 0x01010101
shmid: 40370176
listening port: 44659
start date: Tue Apr 19 03:04:34 2005
clients: 2
client deaths: 0

message type        sent       received
--------------   ----------   ----------
HANDSHAKE                 8            8
ACK                       2            0
INFO                      0            2
KILL                      0            0
DATA                      1            0
LOAD                      0            2
ATTACH_FAILED             0            0
LOADED                    0            2
UNLOAD                    0            0
STATUS_PROGRAM            2            0
USER_ADD                  0            2
USER_SUBTRACT             0            0
STATUS_USER               2            0

Shared Program List:
====================

program-id       compilation date       code size   users      shmid
----------   ------------------------   ---------   -----   --------
PGM1         Thu Nov 18 10:51:22 2004          32       1   40435719
PGM2         Thu Nov 11 09:45:28 2004          32       1   40402950

shared programs in use: 2
total bytes shared: 64
total bytes saved: 0

Product/License List:
=====================

product: ACUCOBOL, SN: real, users: 2/50, processes: 2/4096
  terminal: pts/0, user: mark, processes: 1
      PID: 21188 (0x42650df9), refs: 2, added: Tue Apr 19 06:56:09 2005
  terminal: pts/1, user: mark, processes: 1
      PID: 21190 (0x42650e0e), refs: 2, added: Tue Apr 19 06:56:30 2005
Parent topic: Using acushare


acushare Errors

The runtime system gracefully handles errors relating to shared code and license management. If the runtime cannot use shared code for some reason (such as running out of shared memory), the runtime simply loads the program into conventional memory and execution continues.

If acushare stops running or is stopped while networked runtime processes are active, the runime issues a warning message, alerting the user to restart acushare. If the runtime later detects that acushare has not been restarted, the runtime exits.

By default certain errors cause a warning message to be displayed in a message box, which requires a response from the user. You can change this behavior by setting the LICENSE_ERROR_MESSAGE_BOX configuration variable to 0. This will send error messages to the error output (stderr, or an error file if specified). These messages include:

  • Error sending message to acushare

    The system has returned an error of an unknown nature when it tried to send a message to acushare. For shared memory, execution usually continues. If you kill acushare after some processes have attached to shared memory, those processes continue to use shared memory but new processes use conventional memory.

  • License manager (acushare) is not running

    This is a one-time message warning that the product will exit soon if acushare is not restarted immediately. It indicates that a multiple-user license file is in effect, and the product has detected that acushare has been stopped and not restarted.

  • Shared memory and license manager (acushare) is not running

    This indicates either: (1) code sharing has been requested (with the SHARED_CODE configuration entry), but cannot be implemented because acushare is not running, or (2) a multiple-user license file is in effect, and a runtime process cannot register itself with acushare because acushare is not running. After outputting the message, the runtime exits.

  • The license manager (acushare) has been killed and restarted. You have exceeded the licensed number of users for ACUCOBOL-GT. If you would like to add users, please contact your Customer Service representative.

    This message indicates that a process detected that acushare has been stopped and restarted, so the product attempted to re-register itself. However, it could not register itself, either because the maximum number of users has already been reached, or the maximum number of processes has already been reached.

  • You have exceeded the licensed number of users for ACUCOBOL-GT. If you would like to add users, please contact your customer service representative.

    A new process cannot be registered with acushare, either because the maximum number of users has already been reached, or because the maximum number of processes has been reached.

Note: If there are no shared memory identifiers, acushare aborts and prints the following error message:

acushare: cannot create shared memory

This message indicates that you do not have enough shared memory configured in your system. Either your UNIX kernel does not have the resource configured, or all of the resources are in use by other programs. In either case, you should regenerate your UNIX kernel for more shared memory. See your UNIX system documentation.

Parent topic: acushare Utility Program


General Preprocessor Interface

ACUCOBOL-GT includes a general preprocessor interface that allows you to connect preprocessors to the ACUCOBOL-GT compiler. A preprocessor is a program designed to take application source code and preprocess it before compilation into an executable object. In the case of ACUCOBOL-GT, the conforming preprocessors should be designed to translate source code written in a variety of COBOLs into ACUCOBOL-GT.

The preprocessor interface in ACUCOBOL-GT has two general functions: (1) To invoke a preprocessor from the Compiler and then have the compiler process the resultant expanded COBOL; and (2) to signal the compiler that there are fatal errors in the preprocessor and therefore the compiler should not be run.

The interface is designed to accommodate a wide variety of preprocessors and to work on every platform supported by ACUCOBOL-GT. It is designed to call preprocessors as chained programs (instead of linking them into the ACUCOBOL-GT compiler) for three reasons:

  1. You can develop and debug preprocessors without access to the ACUCOBOL-GT compiler.
  2. You can invoke preprocessors directly from the command line.
  3. The stand-alone design gives much better portability among platforms.

The general preprocessor interface can be used with any preprocessor that conforms to the requirements of the interface. Most preprocessors will be written in ACUCOBOL-GT or C/C++, but preprocessors can be written in any language that produces an executable object file that can read and write text files and accept command-line arguments.

The specific preprocessors that will be used with ACUCOBOL-GT will be written by you, the user. The ACUCOBOL-GT general preprocessor interface supports many features that you can build into your preprocessor to best handle the job at hand. They include:

  • a set of options that the compiler automatically forwards to each preprocessor
  • command-line preprocessor options that allow you to specify certain preprocessor parameters at the time of its invocation
  • a set of line and file directives that are used to pass special information to successive preprocessors, when two or more preprocessors are used in a chain
  • support for preprocessor-generated one-line error messages

The use of conforming preprocessors is described in Use of Preprocessors. Writing conforming preprocessors is discussed in Writing a Preprocessor. The use of the AcuSQL pre-compiler is discussed in AcuSQL Pre-compiler.

Source code for a sample preprocessor written in ACUCOBOL-GT is available for your reference on the Web at http://supportline.microfocus.com/examplesandutilities/index.asp. Select ACUCOBOL-GT® Samples > General Programming Techniques > ansi2term.zip .

  • Use of Preprocessors
  • AcuSQL Pre-compiler
  • Writing a Preprocessor
Parent topic: Compiler and Runtime


Use of Preprocessors

This section discusses various aspects of the use of preprocessors, including rules that apply to the command-line syntax for calling preprocessors. These aspects of use are presented in the context of two sample preprocessors, one written in ACUCOBOL-GT, the other written in C/C++. They include information on calling more than one preprocessor with the same command-line statement, command-line options forwarded to preprocessors by the compiler, and calling a preprocessor without the compiler.

  • Calling a Preprocessor
  • Calling Two or More Preprocessors
  • Compiler Options Forwarded to Preprocessors
  • Calling a Preprocessor Without the Compiler
Parent topic: General Preprocessor Interface


Calling a Preprocessor

The compiler option -Pg is used to call a preprocessor written in any language that produces a directly executable object file:

-Pg "preproc-1 [options]"

Here, preproc-1 is the name of the preprocessor's executable file. The compiler looks for this file first in the directory in which the compiler executable is located. We recommend that you place preprocessors in that directory. If you place them elsewhere, you need to provide a complete path specification. Under Windows, the compiler appends the extension .EXE automatically (if it is not already there).

The name of the preprocessor, and of any directories in its path, cannot contain spaces. Note that Windows creates a space-free alias for any name with embedded spaces. Every file and directory under Windows has an MS-DOS name and extension (maximum eight character name with a three character extension; the name can be viewed in the Properties dialog by right-clicking the file in the File Explorer). For example, the MS-DOS name and extension for acuodbcconfig.dll is ACUODB1.DLL. The MS-DOS name does not contain spaces, even if the original name does. The MS-DOS name and extension can be used by any Windows command or application in lieu of the original name and extension.

If the preprocessor requires or permits special options that are not specified by the ACUCOBOL-GT interface, they must follow the preprocessor executable file name and must be separated from it, and from each other, by spaces or tabs.

If a preprocessor option contains embedded spaces, it must be enclosed in delimiters so that it will be recognized as a single option. Standard double quotation marks (. . . ) cannot be used for this purpose because they are used to enclose the preprocessor executable filename and its associated options. Therefore, two apostrophes ('. . .') are used instead.

For example, the following option might be used to call a preprocessor:

-Pg "preproc -d ''x=:the quick brown fox'' "
  • Preprocessor Written in ACUCOBOL-GT
Parent topic: Use of Preprocessors


Preprocessor Written in ACUCOBOL-GT

Preprocessors written in ACUCOBOL-GT use extension .ACU by default and are not directly executable. In this case, options of a slightly different form are required:

-Pg "runtime preproc-2.ACU [options]"

runtime is the name of the ACUCOBOL-GT runtime executable file. By default, under Windows it is wrun32, and under UNIX it is runcbl. A path is usually not required because this file is normally installed in the same directory as the compiler's executable file.

preproc-2.ACU is the name and extension of the preprocessor, i.e., your ACUCOBOL-GT object file. The extension .ACU is required; it will not be added automatically. The runtime will look for this file in the current directory. If the file is elsewhere, it is necessary to include a complete path specification.

Rules regarding the use of options with this type of preprocessor are the same as for other preprocessors.

Parent topic: Calling a Preprocessor


Calling Two or More Preprocessors

If you want your program to call two or more preprocessors sequentially, you must separate them with vertical line (or pipe) characters (|):

-Pg "preproc1 [options] | preproc2 [options] ...  "

The preprocessors are called in the order in which they appear in this list. The first preprocessor accepts its input from the source file submitted to the compiler. Each subsequent preprocessor accepts as its input the output produced by the previous preprocessor. The output of the last preprocessor is then compiled by the compiler.

Although the pipe notation suggests the use of UNIX-type pipes, the compiler actually stores the output of each preprocessor in a temporary file for use as input to the next preprocessor. The temporary files are erased when the compiler is finished with them.

Note: The temporary file used by the nth preprocessor for its output is called acu_pp#.out, where "#" is a decimal representation of the number n. It is in the current directory.

This method of calling multiple preprocessors is incompatible with the standard method of calling the AcuSQL pre-compiler (with the -Pn or -Ps option). If the AcuSQL pre-compiler is to be called in conjunction with other preprocessors, it must be called with the -Pg option. See AcuSQL Pre-compiler for more information.

Parent topic: Use of Preprocessors


Compiler Options Forwarded to Preprocessors

The following compiler options are automatically forwarded to each preprocessor, including the AcuSQL pre-compiler:

-Sa | indicates that the input file is in ANSI format
-Sd | directs the preprocessor to include debugging lines
-Si | directs the preprocessor to include source lines according to a pattern in the Identification Area of the source code. The next separate argument is the pattern to match.
-Sl | enables support for long ANSI format source code
-St | indicates that the input file is in terminal format COBOL
-Sx | directs the preprocessor to exclude source lines according to a pattern in the Identification Area of the source code. The next separate argument is the pattern to match.
-efile | directs the preprocessor to write error messages to specified file (if not specified, error messages are directed to standard error output)
Note: Where some options are mutually exclusive (-Sa, -Sl, and -St), the compiler command line will include at most one of those options. That one will be forwarded to the preprocessor.

Every preprocessor (written to the standards of the ACUCOBOL-GT General Preprocessor Interface) honors the -e option. Every preprocessor accepts the other options, although it may not make use of them.

Note: A preprocessor honors an option if it does what the option requires. A preprocessor accepts an option if it tolerates its presence on its command line but does not necessarily honor it. An option that is not honored or accepted causes a preprocessor to generate an error message.

See Using the Compiler for a description of all compiler options.

Parent topic: Use of Preprocessors


Calling a Preprocessor Without the Compiler

Every preprocessor can be called as a separate application, without the ACUCOBOL-GT compiler, by a command line of one of the following forms (the second example is used with a preprocessor written in ACUCOBOL-GT):

preproc-1 -placePo output-file [options] input-file

run-time preproc-2.ACU -placePo output-file [options] input-file

These command lines are very similar to the one used with the -Pg option, but there are some important differences:

  • The preprocessor executable, or the ACUCOBOL-GT runtime if the preprocessor is an ACUCOBOL_GT program, will be located according to the procedures used by the operating system for locating executables.
  • The input and output files must be specified as shown.
  • The option list must include any compiler options that the compiler would normally pass through to the preprocessor. See Compiler Options Forwarded to Preprocessors for more information.
  • Options that might be passed to the compiler in combined form must be separated for the preprocessor. For example, the compiler accepts -Six for include/exclude, while a preprocessor requires: -Si for include and -Sx for exclude.

For diagnostic purposes, a preprocessor also accepts either of the following two options:

-help | do not preprocess; show command-line help on standard output device
-v | do not preprocess; show preprocessor version information on standard output device

When either of these options is used, the input and output files need not be specified.

Note: The -help and -v options are not acceptable when the preprocessor is called by the compiler.

Some preprocessors may allow other combinations of options and files when called without the compiler.

The input and output files should be files, not devices, because the preprocessor may not read or write them in strictly sequential order.

A preprocessor returns an exit value 0 (zero) if the preprocessing was successful and the value 1 (one) if there were errors.

Parent topic: Use of Preprocessors


AcuSQL Pre-compiler

The AcuSQL pre-compiler is a preprocessor for programs with embedded SQL. AcuSQL is offered by Micro Focus as a separately licensed product. You can invoke the AcuSQL pre-compiler from the ACUCOBOL-GT command line.

The AcuSQL pre-compiler is discussed in detail in the AcuSQL User's Guide. This section gives insight into the AcuSQL pre-compiler's compatibility with the ACUCOBOL-GT general preprocessor interface and other conforming preprocessors, and discusses calling the pre-compiler from the ACUCOBOL-GT compiler via the general preprocessor interface. This information is especially useful to those who want to use the AcuSQL pre-compiler in combination with another preprocessor.

  • Compatibility with ACUCOBOL-GT general preprocessor interface
  • Calling the AcuSQL pre-compiler
Parent topic: General Preprocessor Interface


Compatibility with ACUCOBOL-GT general preprocessor interface

The AcuSQL pre-compiler is compatible with the ACUCOBOL-GT general preprocessor interface. It can be used in its standard fashion if it is the only preprocessor being invoked, or it can be used with other preprocessors with some minor adjustments.

Parent topic: AcuSQL Pre-compiler


Calling the AcuSQL pre-compiler

You can start and use the AcuSQL pre-compiler from the compiler by using the -Ps compiler option. For example:

ccbl -Ps [options] input_filename

where options are AcuSQL commands and input_filename is the source file to be pre-compiled and compiled. For names and descriptions of the pre-compiler options, see Pre-compiler Function and Use of the AcuSQL User’s Guide. Note that the AcuSQL User’s Guide also discusses other ways to run AcuSQL and and the reasons for doing so.

Note: When the AcuSQL pre-compiler is called by the compiler along with other preprocessors, -P options other than those specified in the AcuSQL User's Guide are not recognized and should not be used.
Parent topic: AcuSQL Pre-compiler


Writing a Preprocessor

This section presents information on how to write a preprocessor that conforms to the ACUCOBOL-GT general preprocessor interface. You may choose to write a preprocessor in any of a number of languages and architectures, so we limit our discussion here to the general features, including syntax examples, that are relevant to any conforming preprocessor. This section contains subsections on using command-line options, line and file directives, and error messages in your preprocessors.

  • Command-line options
  • Line and File Directives
  • Error Messages
Parent topic: General Preprocessor Interface


Command-line options

A preprocessor is written as though it were always called without the compiler by a command line. In particular, every preprocessor must accept at least the following command-line options:

-e file | causes error messages to be written to the specified file. This option must be followed by the name of the error file.
-help | do not preprocess; show command-line help on standard output device
-Po file | causes preprocessor output to be written to the specified file. This option must be followed by the name of the output file.
-Sa | indicates that the input file is ANSI format COBOL
-Sd | instructs the preprocessor to include lines marked as debugging lines ("D") in the indicator area
-Si | instructs the preprocessor to include lines based on pattern. The next separate argument is the pattern to match.
-St | indicates that the input file is terminal format COBOL
-Sx | instructs the preprocessor to exclude lines based on patter. The next separate argument is the pattern to match.
-v | do not preprocess; show preprocessor version information on standard output device

A preprocessor should accept these options in any order. A preprocessor must honor the -e, -placePo, -help and -v options. Other options need not be honored but must be scanned if they appear on the command line.

Note: A preprocessor honors an option if it does what the option requires. A preprocessor accepts an option if it tolerates its presence on its command line but does not necessarily honor it. An option that is not honored or accepted causes a preprocessor to generate an error message.

Another command-line option is highly recommended:

-n      indicates to the preprocessor that no preprocessor directives should be included in output. A standard preprocessor output includes directives, which may make the output very difficult to read. If you want to examine the output of a preprocessor, this option lets you suppress the directives and receive clean output. See Line and File Directives for more information on directives.

The preprocessor should abort with an appropriate error message if a required option is missing.

Parent topic: Writing a Preprocessor


Line and File Directives

Line and file directives are comment strings that a preprocessor uses to pass information to the next preprocessor in the sequence. The information may include directory paths and filenames for the following preprocessor to access or specific instructions to be carried out. See Using Directives and Directive Syntax for more information on directives.

Every preprocessor that follows the first one invoked must scan its input for directives, and every preprocessor must put directives at the appropriate places in its output.

A directive always begins with an asterisk (*), which is placed in column 7 if the file is in ANSI format or in column 1 if the file is in Terminal format. The asterisk indicates a COBOL comment. A preprocessor should accept directives in either ANSI or Terminal format.

A directive of the following form indicates that subsequent input lines came from the specified source code file:

*(( PREPROC PPNAME FILE "<file specification>" ))

A preprocessor should replace the letters PPNAME in a directive with its own name (or any other name containing at most six alphanumeric characters). This field is used only for diagnostic purposes.

The file specification must be abbreviated if necessary, so that the directive will fit into a line of ANSI format without encroaching on the Identification Area.

Note:
  • In the ANSI format, code is limited to columns 1-72. Everything beyond this is part of the Identification Area and is not used, except for conditional compilation. If the directive is too long, it will extend into this area, possibly triggering spurious conditional compilation.
  • Examples in this section of the help show single spaces between items in directives. Actually, any reasonable number of spaces is acceptable.

The first preprocessor writes a directive of the preceding kind at the very beginning of its output file. Each subsequent preprocessor will read a directive of this kind at the very beginning of its input file and will write it at the beginning of its output file with only the preprocessor name changed.

Directives of this kind also appear whenever a preprocessor honors a COPY statement or its equivalent in other languages. There will usually be one such directive at the beginning of the copied code and another at its end.

Within each source file, the lines are numbered consecutively, beginning with line 1. If a preprocessor always produced one line of output for each line of input, it would need no other directives for line numbers. However, that is not usually the case and most preprocessors do need other directives.

A directive of the following form indicates that, until line numbering is changed by a subsequent directive, every line that follows came from the line whose number is embedded in the directive.

*(( PREPROC PPNAME LINE BEGIN <line number in decimal> ))

Normally, the embedded line number will be the number of the next line in the current source file. However, it might be larger if a previous preprocessor generated nothing from one or more lines in the source file.

When there are two or more lines following this directive, it is presumed that all of them were generated from the same line of source code. Although this is not always true, it is a necessary convention because preprocessors that do a lot of parsing and translation cannot always assign a specific source code line to each line of output.

A directive of the following form restores regular line numbering; that is, it indicates that the first line following the directive came from the line after the one whose number is embedded in the directive, and that until line numbering is changed by a subsequent directive for the same source file, every subsequent line came from the line after the previous line.

*(( PREPROC PPNAME LINE END <line number in decimal>))

These two directives normally come in matching pairs (although this is not required). For example, the source file may contain the following code (line number in parentheses):

(55)   display "Making connection".
(56)   EXEC SQL CONNECT TO :dsn-name as C1
(57)      END-EXEC.
(58)   display "Connection made".

The output may be as follows:

     display "Making Connection".
*(( PREPROC ACUSQL LINE BEGIN 56 ))
     PERFORM CALL "SQL$START" END-CALL CALL "SQL$CONNECT" USING
     dsn-name 'C1' END-CALL IF SQLCODE OF SQLCA < 0 THEN GO TO
     Error-Exit END-IF END-PERFORM
*(( PREPROC ACUSQL LINE END 57 ))
     display "Connection made".

Preprocessors that process COBOL code may also use two other directives to indicate places where the source code format (ANSI or Terminal) may change.

The following directive indicates that subsequent lines may be in a different format because they were taken from a COPY file (or its equivalent in modified COBOL):

*(( PREPROC PPNAME INCLUDE BEGIN "<file specification>" ))

The following directive indicates that the code in the new format has ended and the format reverts to the one that prevailed before the matching INCLUDE BEGIN directive.

*(( PREPROC PPNAME INCLUDE END "<file specification>" ))

The file specification must be abbreviated, if necessary, so each directive will fit into a single line of ANSI format without encroaching on the Identification Area.

In the above examples the INCLUDE directives are necessary to tell the compiler that the format may have changed, while the FILE directives are necessary to tell the compiler that a new file has begun and error messages should refer to it.

Note: In the ANSI format, code is limited to columns 1-72. Everything beyond this is part of the Identification Area and is not used, except for conditional compilation. If the directive is too long, it will extend into this area, possibly triggering spurious conditional compilation.

Preprocessors that do not distinguish between COBOL formats should pass such directives along.

Parent topic: Writing a Preprocessor


Error Messages

Each error message produced by a preprocessor must be one line long and must include the source file and line number, as in the following examples:

"myprogram.cbl, line 31: Include file not found at END-EXEC."
"myprogram.cbl, line 31: parse error at END-EXEC."

The comma following the source file name, the word line, and the colon following the line number are required. They are used by the compiler and other software to parse the error message.

Error messages produced by preprocessors other than the first one invoked must use special means to identify the original source file and line that contained the erroneous code. See Line and File Directives for more information.

You should abbreviate the source file specification if it is too long to be read easily.

Parent topic: Writing a Preprocessor


Debugger and Utilities

  • Run-Time Debugger
  • Object File Utility - cblutil
  • Vision File Utility - vutil
  • File Transfer Utility - vio
  • Indexed File Record Editor (alfred)
  • logutil
  • The Profiler
  • External Sort Utility AcuSort
  • Remote Preprocessing Utility Boomerang
Parent topic: ACUCOBOL-GT User's Guide


Run-Time Debugger

The run time, also referred to as runcbl, contains a built-in source-level debugger. This debugger runs in a window that overlays the screen so that the active program is not disturbed.

In all environments, the run-time debugger interface contains a menu bar and command window. To navigate through source code in character environments, use the Up and Down menu items. You can also use the arrow keys and Page Up and Page Down keys to move through the code.

The Runtime Debugger (UNIX)

In Microsoft Windows environments, the debugger also contains a toolbar. When you perform full source debugging in Windows, a scroll bar appears to the right of the source, offering an easy way to scroll through the code.

The Runtime Debugger (Windows)

You can run the debugger at any time, but in order to reference the program's symbols by name, or view the source code, you must have compiled the program with some special options.

The run-time debugger supports three modes of operation: source debugging, symbolic debugging, and low-level debugging.

  • General Debugging Information
  • Entering the Debugger
  • Cursor and Mouse Handling in Source-level Debugging
  • Debugger Commands
  • File Tracing
  • Screen Tracing
  • Macro Debugger
  • Specifying Addresses
  • Debugger Restrictions
  • Using the Abend Diagnostic Report (ADR)
  • Dynamic Runtime Tracing
Parent topic: Debugger and Utilities
Parent topic: Runtime Debugger


General Debugging Information

  • Source Debugging
  • Symbolic Debugging
  • Low-Level Debugging
  • Debugging in Background Mode
  • The Abend Diagnostic Report
Parent topic: Run-Time Debugger


Source Debugging

At the development stage, source debugging is the most useful, because it allows you to view the source code while you are debugging. To use source debugging, compile the program with the -Gd or -Ga option. Because these compiler options cause all of the source code to be bundled with the object code, you'll notice that the size of your object code grows considerably.

Note: Although the compiler accepts lines longer than 80 characters in TERMINAL format files, in source debugging mode the debugger does not display characters past the 80th column. If possible, use the AcuBench integrated debugger instead.
Parent topic: General Debugging Information


Symbolic Debugging

Symbolic debugging does not allow you to view the program source, but does allow you to reference paragraphs and variables by their COBOL identifiers. The advantage to using symbolic debugging rather than source debugging is that the compiled object module is much smaller. This may be useful if disk space is very tight. Some application developers compile their programs with symbolic debugging for delivery to clients in order to facilitate the resolution of client questions over the phone. You must compile the program with the -Gy or -Gs option to use symbolic debugging.

Parent topic: General Debugging Information


Low-Level Debugging

Low-level debugging is available at any time even if the program was not compiled with any debugging options, but you must use absolute addresses to access variables, so you'll need a listing of your program. Low-level debugging is convenient when you're debugging a data-dependent problem on a client's machine, if the client does not have a debug-version of your program. TheTrace Files command described in File Tracing operates in this mode. Trace Files is particularly useful for tracking data-specific problems in complex applications.

Parent topic: General Debugging Information


Debugging in Background Mode

If your ACUCOBOL-GT programs are called from programs written in other languages, or if you are running in an environment that includes an application server or OLTP software, you likely have programs running in background mode (executed with the -b flag). Complete instructions for debugging programs running in background mode is available in Working with Transaction Processing Systems in A Guide to Interoperating with ACUCOBOL-GT.

Parent topic: General Debugging Information


The Abend Diagnostic Report

When a program experiences an abnormal shutdown, running in debug may not reveal the source of the problem. In such cases, the ACUCOBOL-GT runtime can produce a report to show the state of the program at the moment of termination. This Abend Diagnostic Report, or ADR, can help you to analyze the cause of an abnormal shutdown.

More information about this report is included in Using the Abend Diagnostic Report (ADR).

Parent topic: General Debugging Information


Entering the Debugger

When a program is executed in debug mode, the debugging window pops up over the lower portion of the screen. Commands to the debugger and their results are displayed in this window. You can control the size of the command window from within the debugger by pulling down the Source menu and selecting Window Size.

If you are running the debugger under Windows, you can change the size of the entire debugger window. Point to a border or corner, and when the mouse pointer changes into a double arrow, hold the mouse button down and drag the border or corner to reach the size you want. Release the button when you are ready.

You can enter the debugger in several ways; the most common is to specify the -d option to runcbl. Here's a list of all the ways the debugger can be entered initially:

  • When you specify the -d option to runcbl. This causes the program to start in the debugger. For example:
    runcbl  -d  payroll
  • Whenever a STOP statement executes that is not a STOP RUN. In this case, the argument to STOP is displayed in the debugging window. This method functions even if runcbl is not run in debugging mode. Note, however, that symbols and source will not be available in this case. To do source level debugging, compile with the -Gd or -Ga option and run with the-d option.
  • When the program has been started in debugging mode, and the abort key (such as Ctrl + C) is pressed. On Windows systems, the same effect is achieved by selecting the Enter Debugger menu option. In either case, when the command is received, the program finishes execution of the current instruction and enters debugging mode. Note that if the current instruction is an ACCEPT statement, the program will not enter debugging mode until the ACCEPT statement is satisfied by having something entered. Using the abort command to enter the debugger does not work on all machines.
Note: If you receive the following message when entering debug mode, it is indicating that the program has somehow started multiple OS threads, which is currently not supported. You must figure out how the multiple OS threads have been spawned, and prevent them before you can debug the program:

Multiple OS threads detected

If you have already entered the debugger, you may reenter it in one of the following ways:

  • When a breakpoint is reached. Breakpoints are set by the user through the debugger.
  • When the program is being stepped through by the debugger and the step count has been reached.
  • When a variable that is being monitored changes. In this case an automatic breakpoint is generated at the beginning of the next statement.
  • When you've compiled with -Za along with -Gd, and an array violation occurs. In this case, you automatically break to the debugger and see the line on which the array violation occurred.

Each of the situations described above causes the debugging window to pop up over the lower portion of the screen. If source-level debugging is being used, then the upper half of the screen displays the source at the location currently being executed. When the debugger exits, these windows are removed and the application screen is restored. The application screen is not restored, however, until an ACCEPT or DISPLAY verb is executed. This allows you to debug a section of code without the distraction of having the screen being constantly repainted.

Parent topic: Run-Time Debugger


Cursor and Mouse Handling in Source-level Debugging

In source-level debugging, the entire source code is available for viewing. An @ sign is displayed in column one of the current line (the line of code that's being executed). The line containing the cursor shows a > sign in column one. (If the cursor is on the current line, then the cursor is hidden by the @ sign.) For terminals that support reverse video, the cursor line is highlighted. Use the arrow keys to move the cursor. Press F10 to access the menu bar and to toggle back to source code from the menu bar.

If your runtime offers mouse support, then you may use a mouse in the area of the screen that displays the source code. The mouse allows you to perform the following common actions:

Move the cursor line | To move the cursor to a different line, simply click anywhere on the line you want.
Scroll the source | To scroll the source up or down, hold the mouse button down and move the mouse off the top or bottom edge of the source window. The source will scroll to track the mouse. The source scrolls slowly, to make it easy to adjust the current display by a small amount.
Highlight a variable or procedure Point the mouse at a variable or a procedure name and click on it to highlight the name and enable the Selection entry on the menu bar (discussed below). Several operations are available under Selection that act on the highlighted item. The highlighted item will also become the default value used by many menu options.

Using variables, you may specify data names that require arguments, such as tables that require indexes. You cannot specify literals.

You can use the mouse, F7 (display variable on current line), or the Tab key (highlight variable on current line) to view qualified and indexed data items in the source. As long as a variable and all of its qualifiers and indexes are on one line, the entire expression is evaluated by these keys. If a variable and all of its qualifiers and indexes span multiple source lines, the entire expression is ignored, but component items are still found.

Display a variable | To view the value of a variable, double-click that variable.
View procedure | To scroll quickly to a paragraph or section, double-click its name.
Run to desired line | To set a temporary breakpoint, double-click a verb. This establishes a temporary breakpoint at the line containing the verb. The program runs to that line (unless it encounters another breakpoint before it reaches the line). When it reaches a breakpoint, the runtime returns to the debugger prompt and awaits your next command.
Parent topic: Run-Time Debugger


Debugger Commands

Debugger commands are displayed in a menu bar with pull-down submenus, and on the debugger's toolbar. Commands can be selected either from the menus or from the keyboard. A menu item that is followed by three dots (such as Accept...) requires a value. You are prompted for the value unless you highlight it within the source code before you choose the option. Some, but not all, commands may be selected from the toolbar. You can determine toolbar functions by placing the mouse over a button and holding it there for a brief period.

If you do not have a mouse, use F10 to access the debugger menu bar. Then use the arrow keys to move within the menu system. Press Return or the Space bar to make your selection. Typing the key letter is another way to make a selection, if key letters are available on your system. From the menu bar, press F10 to toggle back to the debugger command line.

On systems such as Windows that include a System Menu in the Debugger window, you can activate the System Menu by pressing F9. F9 also activates the System Menu of any window displayed over the Debugger window.

The debugger displays the first ten characters of the name of the current program, followed by the current address (in hexadecimal). This name is derived from the PROGRAM-ID in the Identification Division of the source code.

The commands described on the following pages may be used in all debugging modes, unless marked with one or two asterisks.

  • One asterisk (*) indicates that the option is available in source-level debugging only (-Gd compiler option).
  • Two asterisks (**) indicate that the option is available in either source-level or symbolic-level debugging (-Gd or -Gy compiler option), but not in low-level debugging.

Keep in mind that you must compile with -Gd or -Gy in order to reference variables by name. If the program was not compiled with one of these options, refer to each variable by its absolute address as shown in a program listing.

The tables below list all debugger commands available through the keyboard, with their menu equivalents given in parentheses. The same listing is accessible through the H (Help) debugger command.

  • Source-level Commands
  • Other Commands
  • Multithreading Issues
  • Getting Help
  • File Menu
  • View Menu
  • Run Menu
  • Source Menu
  • Data Menu
  • Breakpoints Menu
  • Selection Menu
  • Help Menu
Parent topic: Run-Time Debugger


Source-level Commands

Command | Menu Option | Description
<F1> or <Page Up> |  | Scrolls source up one page
<F2> or <Page Down> |  | Scrolls source down one page.
<F3> | Run/Go to Cursor Line | Sets a temporary breakpoint at the current cursor line and continues execution of your program.
<F4> | Breakpoints/Toggle at Cursor Line | Sets or removes a breakpoint at the source line containing the cursor.
<F5> or <Up Arrow> |  | Moves the source cursor up one line.
<F6> or <Down Arrow> |  | Moves the source cursor down one line.
<F7> |  | Causes the cursor line to be searched for program variables. If one is found, its name and current contents are displayed.
Tab |  | Search the current line for selectable text. If selectable text is found, select it.
@! | Run/Skip to Cursor Line | Moves the current program location to the line containing the cursor.
F | Source/Repeat Find | Repeats the last Find command, starting at the current cursor line.
FB text | Source/Find Backwards | Locates text in the program's source code. The debugger searches backwards from the current cursor line.
FF text | Source/Find Forward | Locates text in the program's source code. The debugger searches forward from the current cursor line.
FT text | Source/Find from Top | Locates text in the program's source code. The debugger starts at the top of the current program source.
VP | View/Perform Stack | Lists all of the nested paragraphs leading up to the current statement, starting from the beginning of the program.
W procedure | Source/Paragraph | Positions the cursor at the procedure you name. The procedure must be located in the current program.
W@ | Source/Current Line | Positions the cursor at the current line in your program.
WB | Source/Last Line | Positions the cursor at the last line (bottom) in your program.
WT | Source/Line 1 | Positions the cursor at the first line (top) of your program.
Parent topic: Debugger Commands


Other Commands

Command | Menu Option | Description
! | File/Shell | Invokes the operating system's command processor, allowing you to enter commands.
!! |  | Returns the process ID (PID) for the current runtime execution.
<script-file | File/Run Script | Runs a script file. Causes all input (debugger and program) to be read from the script. Control returns to the keyboard when the script is finished.
> | File/Stop Recorder | Ends your recording. If you do not end your recording, the script is saved and closed when the debugger closes.
>script-file | File/Record Script | Turns on a recorder that saves all of your keyboard input and menu selections to a file of your choice.
A variable | Data/Accept | Lets you modify the contents of a variable.
B | View/Breakpoints Breakpoints/View | Displays a dialog box with all existing breakpoints. You can add/modify breakpoints from this dialog box.
B address, [skip #] | Breakpoints/Set | Sets a breakpoint with a skip count. The breakpoint will not be activated until it has been hit skip# times.
B address, [skip #], [WHEN cond] | Breakpoints/Set | Sets a breakpoint with a skip count and/or condition. The breakpoint will not be activated unless cond is true # times.
C address | Breakpoints/Clear | Removes a breakpoint. You can enter either the breakpoint's paragraph name or hexadecimal address.
CA | Breakpoints/Clear All | Removes all breakpoints.
CM number | Data/Monitor/Clear | Clears variable monitor number.
CMA | Data/Monitor/Clear All | Clears all variable monitors.
CWA |  | Clears all variable watches.
D variable [, X] | Data/Display | Shows the contents of a variable. The value is shown in the debugger command window. If X is appended to the display command, the variable is displayed in hexadecimal. If the variable is specified by its absolute address from a program listing, it must be preceded by . (a period)
D variable(x:y) |  | Display a reference modified variable. The command d my-var(2:5), for example, displays five characters, starting with the second character of the variable string.
E | File/Exit Debugger | Turns off the debugger while continuing the execution of your program.
G | Run/Continue | Resumes execution of your program from its current location.
G address |  | Sets a temporary breakpoint at address, and continues execution.
GE | Run/Go until Program Exits | Runs your program until the current program exits to its calling program.
GP | Run/Go until Paragraph Returns | Runs your program until the current paragraph returns to the point from which it was performed.
H |  | Displays the online help files.
L |  | Displays the name of source paragraph or section which is being executed.
M | View/Monitors Data/Monitor/List | Shows all monitored variables and their values. This also displays a sequence number for each monitor, which is used to clear the monitor.
M variable | Data/Monitor/Set | Causes the program to stop whenever the named variable changes its value. The variable is shown in the Watch Window.
P [#] | Step Over | Steps over the next statement. With a count, the program will step count times. Use this command if you want to step through a program following only the original thread.
Q! | File/Quit | Halts your application and exits the debugger.
R script |  | Run a debugging script. The debugger reads commands from a script (but user-input is gathered normally).
RA [#] | Run/Run all Threads | Toggles or sets the Run All Threads setting. If # is 0, only the current thread will run. If # is non-0, all threads will run.
S [#] | Step Into | Executes one statement of your program and then returns control to the debugger. You may follow the command with the number of steps to take. This command will follow a new thread if one is created. If you want to follow the original thread, use the step over command (P) described above.
SA | Run/Auto Step | Causes your program to execute step commands repeatedly until it reaches the end of the program., or until you stop auto-step by pressing the spacebar while the debugger is active. Like the step into command (S), this follows a new thread if one is created.
ST [#] | Run/Thread | Switches to the thread identified by the given number (or the next thread, if no number is given). The Run menu displays the number assigned to each threads.
T flush |  | Causes the error file to be flushed to disk after each write, if you are writing to an error file.
TF [#] | File/Trace Files | Turns on file tracing. The # indicates the level of tracing, from 1 to 9, where 1 is the lowest and 9 is the highest.
TP | File/Trace Paragraphs | Toggles paragraph tracing, which is a listing of all paragraphs and sections entered at runtime.
U | View/Memory Usage | Displays the amount of dynamically allocated memory currently used by the runtime system.
V | View/Screen | Displays your application's current screen. Press any key or click the left mouse button to return to the debugger.
WA | Data/Monitor/Set | Places a variable in the Watch Window. The difference between a watched variable and a monitored variable is that watched variables do not cause program execution to halt when they change.
WS number | Source/Window Size | Specifies the number of lines to show in the command window.
WW number | Source/Watch Size | Specifies the number of lines to display in the Watch Window. The number cannot exceed the number of watched/monitored items.
F8 |  | Recalls the last command entered for editing.
Ctrl + N |  | Shows the next line in the Watch Window.
Ctrl + P |  | Shows the previous line in the Watch Window.
Parent topic: Debugger Commands


Multithreading Issues

When a program is running under the debugger, by default the run all threads (RA) mode is turned on. In this mode, you step through only one thread at a time, but the background threads run normally. If a background thread reaches a breakpoint, it returns control to the debugger and becomes the current thread. The last debugging mode you select is saved into your .ADB file, so the default mode applies only when you do not have a .ADB file.

You can choose to execute one thread at a time in the debugger. This allows you to trace a thread without interference from other threads. When a new thread starts, the debugger informs you, but continues tracing the parent thread. Use the ST (Switch Threads) command to switch between threads.

You can find a list of the current threads under the Run menu item. This list shows you the current program and address where each thread is executing. You can select the appropriate menu item to switch to that thread as an alternative to the ST command.

A list of all current threads appears at the bottom of the Run menu. The list shows both the name of the program associated with the thread and the address where each thread is executing. To switch between threads, you can select a thread from the list as an alternative to the ST command.

The debugger can manage up to ten threads simultaneously.

Parent topic: Debugger Commands


Getting Help

Under Windows, you can access the online debugger documentation from the Help menu at the far right of the debugger menu bar.

In other environments, access help by typing the letter H at the debugger prompt and then pressing Enter.

Parent topic: Debugger Commands


File Menu

The File menu contains commands relating to the overall operation of the debugger.

The File Menu (Windows)

Menu Option Description
Trace Files Toggles file tracing on or off.

A file trace is a listing of all file operations performed at runtime. Trace output can be tailored with the TRACE_STYLE configuration variable.>.

Trace output is sent to the same place that error output is sent. So, to prevent the trace from overwriting your application's screen, be sure to use the runtime's -e command-line option (followed by a file name) to direct error output to a file. See the runtime configuration variable MAX_ERROR_LINES in Appendix H to limit the size of the error file.

Some file systems can print extra information if a higher level of tracing is enabled. This extra information is mostly useful to the Technical Support department at Acucorp, and they may ask you to execute a tf n for some integer n.

File trace example:

runcbl  -de  trace.fil  program1

Make sure that the error file you designate (trace.fil in the example above) does not exist in the current directory. If it does, it will be emptied.

The keyboard form of this command is TF [#].

**Trace Paragraphs Toggles paragraph tracing on or off.

Paragraph tracing is a listing of all paragraphs and sections entered at runtime.

A paragraph trace is sent to the same place that error output is sent. So, to prevent the trace from overwriting your application's screen, be sure to use the runtime's -e command-line option (followed by a file name) to direct error output to a file.

The keyboard form of this command is TP.

Shell Pulls up the operating system's command processor, allowing you to enter commands. Shell is not supported for programs running in thin client mode. Attempts to use the Shell command with programs running in thin client mode will result in the error message: Unable to start shell in thin-client mode.
Note: Under the default Windows setup, the command processor will run as a full screen application.

The keyboard form of this command is !.

Record Script Turns on a recorder that saves all of your keyboard input and menu selections to a file of your choice. Debugger commands and input to the program being debugged are both saved.

Play back the recording with the Run Script command.

See also the description of the W$KEYBUF routine in Appendix I.

Stop Recorder When the recorder is running, the Record Script menu option is replaced by a Stop Recorder option. Use this to end your recording. If you do not end your recording manually, the script information is saved when the debugger closes.

While the recorder is active, you will not be able to use the mouse for anything except selecting menu items. Mouse actions are very position-dependent and are often difficult to replay.

The recorder can save up to 4096 characters of information. Normal keystrokes use one character. Special keys such as function keys and menu selections typically use up to four characters.

The keyboard form of this command is >script-file. The runtime does not process the filename. To turn off the recorder, use > by itself.

Run Script Runs a debugger script file. Control returns to the keyboard when the script is finished.

The keyboard form of this command is < script-file.

Exit Debugger Turns off the debugger but continues execution of your program.

The keyboard form of this command is E.

Quit Halts your application and exits the debugger.

The keyboard form of this command is Q!.

Parent topic: Debugger Commands


View Menu

The View menu contains commands related to viewing and monitoring your program.

The View Menu (Windows)

Menu Option Description
Screen Displays your application's current screen. Press any key or click the left mouse button to return to the debugger.

The keyboard form of this command is V.

Perform Stack Lists all of the nested paragraphs leading up to the current statement, starting from the beginning of the program (or the beginning of the thread, if a new thread was started). Double-clicking one of the names in the list takes you to that paragraph and highlights the current statement in that paragraph. The trace also accounts for embedded procedures and declaratives.

In order to use this command, you must have compiled for source-level debugging (-Gd), and your program must allow for recursive performs (-Zrl). Recursive performs are the default.

The keyboard form of this command is VP.

Breakpoints Displays a dialog box that lists all of your breakpoints and allows you to modify them, add new ones, view the next line of code containing a breakpoint, disable a breakpoint, and clear a breakpoint. It shows the location and skip count for each breakpoint. For breakpoints that are located in the current program, the paragraph they are contained in is also listed.

The keyboard form of this command is B.

Monitors Shows all monitored variables and their values. It also displays a sequence number for each monitor. You need the sequence number to clear an individual monitor. See Data/Monitor/Clear menu option in Other Commands.

The keyboard form of this command is M.

Memory Usage Displays the amount of dynamically allocated memory currently used by the runtime system. There are five types:
  • Program memory

    is the memory directly used by your programs' Data and Procedure Divisions. This includes all programs in memory–not just the current program.

  • File memory

    is memory used by your open files, including the indexed file cache.

  • Window memory

    is memory used by your pop-up windows. This includes the debugger's own pop-up window.

  • Overhead memory

    is memory used directly by the runtime system that is not controlled by your program.

  • Dynamic memory

    is memory allocated by the program via the M$ALLOC library routine.

The keyboard form of this command is U.

Parent topic: Debugger Commands


Run Menu

The Run menu contains commands related to executing your program.

The Run Menu (Windows)

Menu Option | Description
Continue Resumes execution of your program from its current location. The program returns to the debugger when it reaches the next breakpoint.

The keyboard form of this command is G.

*Go to Cursor Line | Sets a temporary breakpoint at the current cursor line and continues execution of your program. Press the F3 key to use this command from the keyboard. The F3 key works on lines that do not contain verbs. The closest previous line with a verb is the location used to set the breakpoint.
Go until Paragraph Returns Runs your program until the current paragraph returns to the point from which it was performed.

The keyboard form of this command is GP.

Go until Program Exits Runs your program until the current program exits to its calling program. If used from inside your main program, this command runs the program until it finishes.

The keyboard form of this command is GE.

Auto Step Causes your program to execute step commands repeatedly until it reaches the end of the program. When you select this mode, the debugger immediately begins stepping through your program. The debugger will follow new threads as they are created. (If you want to continue to follow the original thread, use the Step Over command) You can change the speed at which it is stepping by typing a digit from "1" (slowest; approximately three seconds per step) to "9" (fastest; several steps per second). Press the spacebar to leave Auto Step mode and return to the debugger prompt.

The keyboard form of this command is SA.

Step and P-Step Are not shown on the menu, but are available from the keyboard. Windows users can find equivalent commands, and others, on the toolbar provided with the debugger.

Step executes one statement of your program and then returns control to the debugger. New threads are followed as they are created. (If you want to continue to follow the original thread, use the Step Over command.)

The keyboard command is S. You may follow the keyboard command with a number of steps to take.

P-Step executes a "perform step." This is the same as a normal Step command, except that it includes the entire range of a PERFORM statement as a single statement. The effect is to step to the end of the performed paragraph. Use this command if you want to step through a program following only the original thread.

The keyboard command is P. You may follow the keyboard command with the number of perform steps to take. The toolbar is explained in Debugger Commands.
*Skip to Cursor Line Moves the current program location to the line containing the cursor. Further execution of your program will proceed from this line. The cursor line must contain a verb; otherwise the current program location does not change.

Use this command with care, because the skipped lines are not executed. You may skip important sections of code and experience unexpected results.

The keyboard form of this command is @!.

Note: The @! command is not available for debugging a native-code module.
Run all Threads Toggles or sets the "Run All Threads" setting. Once it is set, all threads run simultaneously under the debugger. Though all threads run simultaneously, only the debugger's current thread is traced when you are stepping through a program. However, breakpoints in other threads are active and can transfer control to the debugger, as can a trapped error (such as a table boundary violation). When a thread other than the current thread returns control to the debugger, that thread becomes the current thread.

The keyboard form of this command is RA [#].

Thread | Shows the threads contained in the program, and places a check mark next to the current thread.
Parent topic: Debugger Commands


Source Menu

The Source menu contains commands related to viewing your source code. These commands are available with source-level debugging.

The Source Menu (Windows)

Menu Option Description
*Line 1 Positions the cursor at the first line of your program.

The keyboard form of this command is WT.

*Last Line Positions the cursor at the last line in your program.

The keyboard form of this command is WB.

*Current Line Positions the cursor at the current line in your program.

The keyboard form of this command is W@.

*Paragraph Prompts you for a procedure name and positions the cursor there. The procedure must be located in the current program.

The keyboard form of this command is W procedure.

*Find Forwards Prompts you for text to locate in the program's source code. The debugger searches forward, starting at the cursor line. Case is not considered, so you do not have to match the capitalization of the text you want to locate.

The default text for the search is shown in a dialog box. This is the current selection (the currently highlighted variable or procedure name). If nothing is selected, the default is the last search string. If you do not want the default, simply type over it.

Before you choose Find Forwards, you can highlight a variable or procedure name by clicking on it. If you do not have a mouse, use the arrow keys to move to the desired line and then press the Tab key to highlight the desired name.

The keyboard form of this command is FF text.

*Find Backwards Prompts you for text to locate in the program's source code. The debugger searches backwards, starting at the cursor line. Case is not considered, so you do not have to match the capitalization of the text you want to locate.

The default text for the search is shown in a dialog box. This is the current selection (the currently highlighted variable or procedure name). If nothing is selected, the default is the last search string. If you do not want the default, simply type over it.

Before you choose Find Backwards, you can highlight a variable or procedure name by clicking on it. If you do not have a mouse, use the arrow keys to move to the desired line and then press the Tab key to highlight the desired name.

The keyboard form of this command is FB text.

*Find from Top Prompts you for text to locate in the program's source code. The debugger searches for the text, starting at the top of the current program source. Case is not considered, so you do not have to match the capitalization of the text you want to locate. This is usually a convenient way to find the definition of a COBOL data item.

The keyboard form of this command is FT text.

*Repeat Find Repeats the last Find command, starting at the cursor line.

The keyboard form of this command is F.

Window Size Sets the number of lines to show in the command window. This may be any integer from 2 to 14, inclusive.

The keyboard form of this command is WS number.

*Watch Size Displays a dialog box that allows you to specify the number of lines to display in the Watch Window. The number cannot exceed the total number of items being monitored and watched. Specifying a larger number results in no change.

The keyboard form of this command is WW number.

The Watch Window size dialog (actually titled Window Size) looks like this:

Parent topic: Debugger Commands


Data Menu

The Data menu contains commands relating to your program's variables.

The Data Menu (Windows)

You may use name qualification with the Display, Accept, and Monitor commands. For example, you can use the syntax FIELD-1 IN GROUP-1 to refer to a field called FIELD-1 that belongs to group item GROUP-1. Name qualification is not supported for on-screen commands (such as F7) or for situations in which you double-click on the data name.

Menu Option | Description
Display Shows the contents of a variable. With source-level debugging, you can either click on the variable name in the code before you select Display, or wait to be prompted.) Numeric variables are converted to show their value. Other variables are shown as text. The value is shown in the debugger command window. The keyboard form of this command is D variable.

Table elements cannot be highlighted with a mouse click. Instead, use this keyboard command:

   d  variable (index)

The variable's name is followed by the desired index in parentheses. The index must be a numeric literal. To display a reference modified variable (that is, to view some portion or substring of the data item), use the syntax:

   d  variable(x:y)

This shows y characters of variable, starting from character x. When you display a variable, and multiple fields with the same name are defined in the program, the debugger lists all instances of the field. For example, if the following two group items were defined in Working-Storage:

   01 start-date.
      05 ws-day     PIC XX.
      05 ws-month   PIC XX.
      05 ws-year    PIC X(4).
   01 end-date.
      05 ws-day     PIC XX.
      05 ws-month   PIC XX.
      05 ws-year    PIC X(4).

and you entered the command d ws-day, you would see the value for the field in both the start-date and end-date group items.

Reference modification and indexing are valid with duplicate names. For example, all of the following are valid:

   d field-1(1:1)
   d field-1(1)
   d field-1(1)(1:1)

If your display command contains multiple field names, only the first name specified may be a duplicate. Using the group definitions shown in a previous example, the Shows the contents of a variable in hexadecimal. (With source-level debugging, either click on the variable name in the code before you select Display in Hex, or wait to be prompted for the name.) command d ws-day(1:ws-month) would fail, because there is more than one ws-month defined.

Keep in mind that you must compile with -Gd or -Gy in order to reference variables by name. If the program was not compiled with one of these options, you must refer to each variable by its absolute address from a program listing, preceded by . (a period). For example:

   d  .213.5
Display in Hex This option allows you to determine the data stored in each byte of the variable. The value is shown in the command window below the source code.

The keyboard form of this command is D variable, X.

Accept Allows you to modify the contents of a variable. (With source-level debugging, either click on the variable name in the code before you select Accept, or wait to be prompted for the name.) For numeric variables, the value entered is converted to the internal storage format of the variable.

The keyboard form of this command is A variable.

When you accept a variable in the debugger, the current value of the variable is shown as the default. To leave the current value in place, press Enter.

Table elements cannot be highlighted with a mouse click. To modify a table element, follow the variable's name with the desired index in parentheses, as shown here:

   a  variable (index)

The index must be a numeric literal.

Keep in mind that you must compile with -Gd or -Gy in order to reference variables by name. If the program was not compiled with one of these options, you must refer to each variable by its absolute address from a program listing.

Accept in Hex Allows you to modify the contents of a variable in hexadecimal format. You can enter or display up to 2048 hex characters (1024 bytes of data).

To accept a variable in hexadecimal format from the command line, use the command:

   a  variable  x
Monitor | This submenu contains commands that relate to monitored variables.
Set Displays a dialog that prompts you for the name of a variable to be included in the Watch Window. (For source-level debugging, either click on the variable name in the code before you select Monitor, or wait to be prompted for the name.)

The keyboard form of this command is M variable.

The Monitor dialog looks like this

The Monitor dialog box includes a check box labeled Break when changed. When this box is checked, the selected variable becomes monitored, and if it is unchecked, the variable is only watched. The default value of this check box is On (checked).

If the Break when changed box is checked in the Monitor dialog box, monitoring a variable suspends the program run. Any time a monitored variable changes, the program stops executing and control returns to the debugger, where the new value of the variable is displayed in the command area of the debugger window and in the Watch Window.

If the Break when changed box is unchecked in the Monitor dialog box, the item is watched. Though changes to a watched variable's value are indicated in the Watch Window like those of a monitored variable, these changes do not cause the program to stop executing.

You can tell which variables in the Watch Window are monitored by the phrase (break) following the variable name (for example, those variables for which the Break when changed check box was clicked on). The watched variables do not have this phrase displayed after their names.

When any variables are set for monitor/watch, a new window is created as a sub-window of the main debugger canvas, located at the top of the screen. This window, called the Watch Window, shows all the monitored/watched variables and their values, one name/value per line (values that exceed the size of the window are truncated). By default, the Watch Window contains as many lines as there are variables being monitored, up to a maximum of three. If you set more than 3 variables, you can scroll through the Watch Windowto view them all, or you can make the Watch Window larger with the Window Size option on the Source menu. If your system does not use the mouse, you can scroll the Watch Window using Ctrl + P (for previous item) and Ctrl + N (for next item) keys on your keyboard. The maximum number of variables you can set is limited only by system memory. The Watch Window looks like this:

To monitor a table element, follow the variable's name with the desired index in parentheses, as shown here (table elements cannot be highlighted with a mouse click):

   m  variable  (index)

The index must be a numeric literal.

Keep in mind that you must compile with -Gd or -Gy in order to reference variables by name. If the program was not compiled with one of these options, you must refer to each variable by its absolute address from a program listing.

Menu Option (continued) | Description
List | Shows all monitored variables and their values. Also displays a sequence number for each monitor. You need the sequence number to clear an individual monitor. See Clear, below. The keyboard form of this command is M.
Clear | Clears a monitor from one variable. You will be prompted to identify the variable by number. Use the List option to display all monitors and their numbers. The keyboard form of this command is CM number.
Clear All | Clears all monitors. The keyboard form of this command is CMA.
Parent topic: Debugger Commands


Breakpoints Menu

The Breakpoints menu contains commands for managing a program's breakpoints.

The Breakpoints Menu

A breakpoint is a location in your program's code that you designate. It causes control to return to the debugger. Control is returned before the code at the breakpoint location is executed.

Breakpoints are displayed in the source. An enabled breakpoint shows as B in column 1, a disabled breakpoint as b (lowercase) instead. The @ sign (showing the program's current location) displays over the B if the current line is also a breakpoint.

Breakpoints are saved between sessions. The breakpoints are stored in a file that is named username.adb, where username is your login name, as known by the runtime. This file is placed in the directory named by the ACUCOBOL environment variable, or the current directory, if that variable is not set. In addition to your breakpoints, the run-all-threads state is recorded, as well as the last size of the debugger's window. Keep in mind that although breakpoints are saved between sessions, they are not saved between compiles.

Menu Option | Description
 | Allows you to set a breakpoint at a paragraph. Selecting Set displays the Set Breakpoint dialog.

The Set Breakpoint dialog prompts you for a breakpoint Location, Condition, and Skip count.

Set Breakpoint Field | Description
Location This field prompts you for a hexadecimal address and a program name, although the current cursor location is supplied as the default breakpoint address location. Hexadecimal addresses are specified with a . (period) as the first character, as described in Program Addresses. A breakpoint is set at that address in the program. If you omit the program name, the current program is used. To obtain the hexadecimal address of a line of code, use the compiler's program listing.

Suppose you want to set a breakpoint in a called program in the run unit, but you do not know the exact address. First, make sure you've compiled the called program with source-level debugging. Then, from the current program, set the breakpoint at address 0, called-program-name. The debugger breaks as soon as the called program is entered. You see the called program's source code on the screen, and the called program's name on the command line. The called program is now the current program, and you can use Set or Toggle at Cursor to set the desired breakpoint.

If you have compiled with line numbers, you can use an alternate notation to set a breakpoint within a called program. Instead of specifying an exact address, provide the file name for the ACUCOBOL-GT source file or COPY file, followed by a colon (":") and the line number. The syntax is:

   b [path/]filename.cbl:line

For example, in the command window, you could type:

   b invoice.cbl:559

or

   b /usr/copylib/mtrec.cpy:312

Note that when you use this method to set a breakpoint in a COPY file, the line number should be relative to the specific file, not to the main program. Also, if you set a breakpoint in an object module that has not yet been loaded, you will see a warning message, Breakpoint saved for future COBOL module. When the object is loaded, the breakpoint is set without further user intervention.

Condition | Breakpoints can have a condition, known as the When Condition, specified for them. The condition is entered into the Condition field. The breakpoint is activated only when the condition is true. For breakpoints with a skip count (see below), the skip count is decreased only when the condition is true. Conditions are simple comparisons between two numeric or alphanumeric data items or literals, including figurative constants (exception: the ALL literal is not supported). The allowed comparisons are =, <, >, <= and >=. You may place the word NOT before any of these operators. The comparisons are done according to the rules for COBOL. Any data items referenced must exist in the program containing the breakpoint. If the condition is not meaningful or is illegal (including table boundary violations), then the breakpoint is immediately activated when it is reached and an error message follows.
Skip count In the Skip count field, enter the number of times to skip the breakpoint. The breakpoint does not activate until the skip count reaches zero. The keyboard form of this command is
b address, counter

This command can also be set from the command line with:

b address [,program] [,SKIP count] [,WHEN condition]

A second command that is also supported but does not allow conditions to be set is:

b address [,program] [,count]
*Toggle at Cursor Line Sets or removes a breakpoint at the source line containing the cursor.

To use this command from the keyboard, press F4. The F4 key works on lines that do not contain verbs. The closest previous line with a verb is the location used.

*Disable/enable at Cursor Line | Allows you to keep a breakpoint location while turning off the breakpoint. You can disable/enable breakpoints from the menu or from the Breakpoint dialog box.
View | Is the same as the list breakpoints command (B). It displays a dialog box that lists all of your breakpoints and allows you to modify them, add new ones, view the next line of code containing a breakpoint, disable a breakpoint, and clear a breakpoint. It shows the location and skip count for each breakpoint. For breakpoints that are located in the current program, the paragraph they are contained in is also listed.
Clear Removes a breakpoint. At the prompt, you can enter either the breakpoint's paragraph name or hexadecimal address. Hexadecimal addresses are specified with a . (period) as the first character, as described in Program Addresses. Exact addresses are given in the View command described above.

To use this command from the keyboard, type C address.

Clear All Removes all breakpoints.

To use this command from the keyboard, type CA.

Parent topic: Debugger Commands


Selection Menu

The Selection menu lists actions you can take on the current selection.

A selection is a variable or procedure name that you have highlighted in the source window. If you do not have a mouse, use the arrow keys to move to the desired line and then press the Tab key to highlight the desired name.

Menu Option | Description
*Display Shows the contents of the selected variable. Numeric variables are converted from their internal formats to show their values. Other variables are shown as text.

You can also perform this by double-clicking the desired variable.

*Display in Hex | Shows the contents of the selected variable in hexadecimal notation. This allows you to view the internal storage of every byte in the variable.
*Monitor Sets a monitor on the selected variable. Changes to a monitored variable cause control to return to the debugger. This feature gives you the option to have the COBOL program stop executing, and the debugger to activate, when the value of a monitored variable changes. When this happens, the debugger window becomes the active window, and the variable and its value are displayed in the command area of the debugger.

When any variables are monitored (or watched), a new window is created as a sub-window of the main debugger canvas, located at the top of the screen. This window, called the Watch Window, shows all the monitored and watched variables and their values, one name/value per line (values which exceed the size of the window are truncated). By default, the Watch Window contains as many lines as there are variables being monitored, up to a maximum of three. If you select more than three variables for monitoring, you can scroll through the Watch Window to view them, or you can make the Watch Window larger with the Window Size option on the Source menu. The size of the Watch Window cannot exceed the total number of monitored and watched items. Attempting to make the window larger than that results in no change.

This is what a Watch Window looks like.

*Watch | Sets a watch on the selected variable. Changes to a watched variable do not cause control to return to the debugger. See also *Monitor, above.
*Accept | Accepts a new value for the selected variable. For numeric variables, the value you enter is converted to the variable's internal storage format.
*Accept in Hex | Accepts a new value for the selected variable in hexadecimal format. Up to 1024 bytes of data (2048 hex characters) can be entered or displayed.
*View Procedure Scrolls the source window to the start of the selected procedure.

You can also perform this by double-clicking the left mouse button on the desired procedure name.

*Run to Procedure | Sets a temporary breakpoint at the selected procedure and continues program execution. The program runs until it reaches the selected procedure (or another breakpoint).
*Set Procedure Breakpoint | Sets a permanent breakpoint at the selected procedure.
Up and Down Are available only for non-Windows environments. Windows users can perform the same tasks by using the scroll bar to the right of the debugger screen.
  • *Up scrolls up towards the top of the source code by one-half screen.
  • *Down scrolls down towards the bottom of the source code by one-half screen.

Help for Windows users is discussed in the topics in this section. In other environments, you can get help by typing the letter H and pressing Enter at the debugger prompt.

The following debugger commands are available but are not shown on the debugger menus:

Debugger Command | Description
*F1, Page Up | Scrolls source up one page.
*F2, Page Down | Scrolls source down one page.
*F5 (or the Up arrow) | Moves the source cursor up one line.
*F6 (or the Down arrow) | Moves the source cursor down one line.
*F7 | Causes the cursor line to be searched for program variables. If one is found, its name and current contents are displayed. Press F7 multiple times to cycle through all of the variables on the line. F7 (display variable on current line) and the Tab key (highlight variable on current line), as well as the mouse, also pay attention to qualified and indexed data items in the source. As long as a variable and all of its qualifiers and indexes are on one line, the entire expression is evaluated by these keys. If a variable and all of its qualifiers and indexes span multiple source lines, the entire expression is ignored, but component items are still found.
*F8, Edit Command | Causes the last command entered to be recalled for editing. Useful for correcting typographical errors.
*H, Help Key | Displays a screen of summary help information.
Parent topic: Debugger Commands


Help Menu

The Help menu is available only for Windows users. It provides access to a Windows-style Help facility for the debugger.

The Help Menu (Windows)

Menu Option | Description
Contents | Shows you the Debugger Help table of contents.
Search | Allows you to search for specific words, as you would in a book index.
Help on Help | Opens the native Windows help file that explains how help files can be used.
About the Runtime | Gives you information regarding the runtime, such as the runtime version number, serial number, copyright information, and license number.
  • The Toolbar
Parent topic: Debugger Commands


The Toolbar

Windows users can use the debugger's toolbar for a variety of operations. To display a description of any button on the toolbar, place the mouse pointer over the button and hold it there for a few seconds. Depending on the state of the debugger, some of the icons may be disabled.

The Debugger Toolbar (Windows)

Toolbar Button | Description
Step Into | Executes one statement of the program and then returns control to the debugger. It is the equivalent of the keyboard command S. The debugger will follow new threads as they are created. If you want to continue to follow the original thread, use the Step Over command.
Step Over | Allows you to step over a performed paragraph. It is the same as Step Into except that it includes the entire range of a PERFORM statement as a single statement. It is the equivalent of the P-step command. Use this command if you want to step through a program following only the original thread.
Step Out | Lets you run to a performed paragraph's exit.
Run to Cursor (F3) | Sets a temporary breakpoint at the current cursor line and continues execution of your program.
Auto Step | Causes your program to execute step commands repeatedly until it reaches the end of the program. As with the Step Into command, the debugger will follow new threads as they are created. If you want to continue to follow the original thread, use the Step Over command.
Find | Brings up a dialog for entering a word or phrase you want to locate.
Find from Top | Locates the next occurrence of the last found word or phrase.
Find Next | Locates the next occurrence of the last found word or phrase.
Find Previous | Locates a previous occurrence of the last found word or phrase.
Find Current Line | Sets the source view to the current program location.
Go | Runs the program to the next breakpoint.
Toggle Breakpoint (F4) | Sets or removes a breakpoint at the source line containing the cursor.
Disable Breakpoint | Allows you to keep a breakpoint location while turning off the breakpoint.
Remove All Breakpoints | Clears all breakpoints from the program.
Perform Stack | Displays the current Perform stack, listing all of the nested paragraphs leading up to the current statement.
Parent topic: Help Menu


File Tracing

File tracing is always available. Programs don't need to be compiled with the debug options to use file tracing. File tracing can be especially helpful in assessing the cause of a problem. File tracing provides valuable information about file OPENs, READs, and WRITEs. File status codes for unsuccessful I/O operations are also shown, and configuration variable settings can be examined. For relative files, file trace includes record numbers.

To enable file tracing, type:
runcbl -dlxe errfile myprog

where:

-d | turns on the debugger.
-l | (optional) causes the contents of the runtime configuration file to be included in the error output.
-x | causes the runtime system to display the operating system's corresponding error number for file error 30 on the error output. This information may help in determining the problem.
-e | causes the error output to be placed in the file named immediately after the option.
errfile | is the user-specified name of the error file. This file is opened as an empty file when the runtime is initiated. Do not forget to specify the error file name -- if you run with -e, immediately followed by your program name instead of an error file name, our object code file will be deleted and opened as a n empty file.
myprog | is the name of your object code file.
After you press Enter you are at the debugger screen. To turn on file tracing, type:
tf [#]

File trace is echoed on the screen.

Some file systems can print extra information if a higher level of tracing is enabled. This extra information is useful primarily to Product Support, and they may ask you to execute a tf # for some integer.

File tracing can also be enabled with the FILE_TRACE runtime configuration variable. Some attributes of trace output can be tailored with the TRACE_STYLE configuration variable. For more information about both of these variables, see Appendix H. Configuration Variables.

If you are writing to an error file, you can execute this debugger command:

   t  flush

to cause the error file to be flushed to disk after each write. This can be useful if your program terminates unexpectedly. It allows the error file to contain everything that the runtime sent to it. Without this command, the error file could be empty following an unexpected program termination, even though a great deal of information had been written to it. Note that this option slows down the processing but ensures that the error file is complete.

To start the program, enter:

   g

Proceed until you encounter the error condition and then exit. Your error file contains the error information, all COBOL configuration file variables that you have set, and a record of every file operation.

  • File Trace Timestamps
Parent topic: Run-Time Debugger


File Trace Timestamps

If you are directing file trace output to an error file, you can elect to include timestamp information. When this option is enabled, a timestamp is placed at the beginning of every line in the trace file. (When you are debugging a problem, it is sometime helpful to know the exact time of each file operation.) The format of the timestamp is: HH:MM:SS.mmmmmm, where mmmmmm is the finest resolution that the runtime can obtain from the system.

There are three ways to enable timestamps in the trace file.

  1. In the debugger, before you start the program with the g command, enter:
    t timestamp
  2. Before you start the program, in the runtime configuration file set the FILE_TRACE_TIMESTAMP variable to 1 (on, true, yes). This variable is set to 0 (off, false, no), by default.

    When set in the appropriate server configuration file, FILE_TRACE_TIMESTAMP can also be used with AcuServer and AcuConnect (see the associated product documentation for more information).

  3. Before you start the program, set the TRACE_STYLE variable to TIMESTAMP in the configuration file .

Timestamp information is included only when file trace information is directed to a file.

Timestamp output can add significant file I/O overhead and may have a noticeable impact on performance.

Parent topic: File Tracing


Screen Tracing

The screen trace feature enables you to save information about DISPLAYs of screen section items and CREATEs, DISPLAYs, MODIFYs, and INQUIREs of ActiveX objects. You can use screen trace even if the program was compiled without the debugging option.

To perform a screen trace, type:

runcbl  -dle  errfile  myprog

Because you specified -d (for debugger) on your command line, you will be at the debugger screen after you press Enter.

To turn on screen tracing, type:

ts

Screen trace ON is echoed on the screen.

The information output is useful primarily to Product Supprt.

If you are writing to an error file, you can execute this debugger command:

t  flush

to cause the error file to be flushed to disk after each write. This can be useful if your program terminates unexpectedly. Note that this option slows down the processing but ensures that the error file is complete.

Type:

g

You will now be running your program normally. Proceed until you encounter the error condition, and then exit. Your error file will contain the error information, all COBOL configuration file variables that you have set, and a record of every file operation.

This can be especially helpful as you assess the cause of the problem.

Parent topic: Run-Time Debugger


Macro Debugger

The debugger supports a simple macro processor. Twenty-six variables, named A through Z, are available to be assigned to arbitrary strings. You do this with the command:

variable = string

where the = must appear in column two. After a variable is assigned, you may use it in any command by specifying the variable name with a $ in front of it. This provides a convenient way to assign a long symbol name to a shorter string.

For example, if the symbol EMPLOYEE-NAME is often referenced in a debugging session, the following commands will assign this to the variable " and display the contents of the name:

   x=employee-name
   d $x

Macros may not be nested.

Parent topic: Run-Time Debugger


Specifying Addresses

Program addresses and variables can be specified directly or with program symbols. In order for a symbol to be used, the program containing the symbol must be currently executing and must have been compiled with either the -Gy or -Gd options.

  • Variables
  • Program Addresses
Parent topic: Run-Time Debugger


Variables

Variables can be specified by their symbolic name or by their address. If they are specified by address, both the starting address (in hexadecimal, preceded by a . (period)) and the variable's size (in decimal) must be specified, in that order. These values can be found in the symbol table listing produced when you compile with the -Ls compiler option. Any variable specified directly by address is treated as if it were an alphanumeric variable. Variables specified by name are treated as their correct type, except for edited fields, which are treated as alphanumeric.

Either form of addressing may have an index specified for it. This index is a number in parentheses following the address. Only constant values may be used as table subscripts.

You may use name qualification with the Display, Accept, and Monitor commands. For example, you may type FIELD-1 IN GROUP-1 to refer to FIELD-1 of GROUP-1. Name qualification is not supported for on-screen commands (such as F7) and for situations in which you double-click the data name.

Data items may be qualified by a group name. Table indexes may be specified with variables.

Note: For data items of variable size, the debugger always treats the data item as if it were currently defined to be its maximum size.

Examples:

VAR-1 | Variable name
3A4, 5 | Address 3A4 for 5 bytes
ARRAY-1 (2,4) | Indexed variable
  • Configuration Variables
Parent topic: Specifying Addresses


Configuration Variables

You can display and accept configuration variables within the debugger. To display a particular variable use the following command:

d %var-name

where var-name is the name of the variable you want to display. Up to 300 characters of the value are displayed. (This is equivalent to executing the ACCEPT FROM ENVIRONMENT command, and can show the same types of configuration variables.)

To accept a configuration variable, execute the command:

a %var-name

where var-name is the name of the variable you want to modify. In this case, the debugger responds with a prompt. Enter the new value of the variable, ACCEPT that variable within the COBOL program, and the runtime will use the new value.

Parent topic: Variables


Program Addresses

Program addresses may be specified by paragraph name. They can also be specified by a hexadecimal address, specified by a . (period) as the first character. This allows the debugger to distinguish between the hex address ABC and the paragraph name ABC. You can omit the period when there is no ambiguity. Optionally, . (period) can be followed by the six-character program name. The numeric form is the only way to specify an address that is not at a paragraph, and the only way to specify an address in a program other than the one that is currently running. The listing produced by the compiler has the address of the start of each sentence along the left-hand side. Usually it is more convenient to use the F3 and F4 commands of the source debugger.

Note: Every program always starts at address zero. If you want to debug a subprogram, you can always set a breakpoint at address zero of the subprogram and run it until this point is reached. Then the subprogram will be active and its symbols will be available (if it was compiled with -Gd or -Gy). When specifying an address in a different program, use the name contained in its PROGRAM-ID paragraph.

Examples:

MAIN-LOGIC | Paragraph name
3A7F | Numeric address
0, PROG2 | Start of program PROG2
Parent topic: Specifying Addresses


Debugger Restrictions

Note the following restrictions on the debugger:

  • If you have a paragraph (or section) and a data item with the same name, that name will refer to the paragraph (section). If more than one paragraph (or section) has that name, the last one will be the one used. Other data items and paragraphs (sections) with that name can be referenced only by their addresses.

    There is one exception to this rule. If a variable has the same name as a paragraph, you can still display (d ambiguousname) and accept (a ambiguousname) that variable in the debugger if you compile with at least -Gs and -Gd.

  • Although the compiler allows for up to 15 dimensions in a table, the debugger will let you access only the first three dimensions.
  • Although ACUCOBOL-GT object files are portable across all machines, an object file that contains debugging symbols or source may not be. These files can be run on other machines, but may cause errors if run with the debugger on the foreign machine.
  • You can use the debugger on a native-code module in the same fashion as you do for a portable-code module. The only restriction is that you may not begin execution at an arbitrary point in a native-code module (the @! command).
  • The debugger identifies a program name by a match on the first 30 bytes. This limitation derives from the compiler behavior, which reserves 30 bytes for the program name in the program object.
Parent topic: Run-Time Debugger


Using the Abend Diagnostic Report (ADR)

When you create an Abend Diagnostic Report to analyze the cause of an abnormal program shutdown, the report is divided into three sections:

  1. The first contains general information about the program, such as command-line parameters, the reason for the shutdown, and the line number of the operation that caused the shutdown.

    This section of the report appears as follows:

    Dump created: Tue Dec 28 15:00:32 2006

Reason for dump:
Index out of bounds, upper bound = 10, index = 11
COBOL error at 000014 in TwoTables.acu
("TwoTables.cbl", line 42)

Runtime version: 8.0.0 (2006-12-23)
Command line arguments: -c Cfg.txt TwoTables.acu
  2. The second section contains a call stack summary for each thread being run, including information about inactive programs. Inactive programs are those programs which have been loaded into memory but which are not currently executing.
    Process ID: 1128

1 thread(s) active

** Thread 487 **
Call stack:
000014 TwoTables.acu

Inactive programs:
(none)
  3. The third and largest section contains detailed information about each program, including the value of all data items. Programs are listed in CALL order, starting with the program executing at the time of shutdown and working backward to the start of the thread (usually the main program).
    • All data items and their values are listed in the order they are declared in the program.
    • Group items are named, but have the phrase (group) listed as their value to avoid duplicate information in the report.
    • Individual elements in a group are listed with their values.
    • Table items are expanded to show each element of the table.
    • Data is shown in both the appropriate numeric/non-numeric format and as raw hexadecimal data.
    • The compile options used to generate the object file.
      *** DETAIL FOR THREAD 487 ***

*** PROGRAMS IN THE CALL STACK ***

*** PROGRAM "TwoTables.acu" ***

Current address: 000014

01 ONE-TOO-MANY                   = 11             h30303031 31

01 MY-TABLE                       = (group)
05 FILLER                         = "    1"        h20202020 31
05 FILLER                         = "    2"        h20202020 32
.
.
.
00 SPECIAL REGISTERS              = ""             h

*** END OF PROGRAM "TwoTables.acu" ***

*** END OF THREAD 487 ***

*** END OF DUMP ***
  • Generating a Report
  • ADR Restrictions
Parent topic: Run-Time Debugger


Generating a Report

To generate an Abend Diagnostic Report, you must set the ACU_DUMP configuration variable to 1 (on, true, yes). The default value for the configuration variable is 0 (off, false, no). This variable also takes name format specifiers that you can use to add additional identifier information to the report name.

In order to add detailed information to the report, programs must be compiled with line number (-Gl) and symbol table (-Gs) option. The -Ga compiler option may also be used, but since this includes full source information in the compiled object, it results in a much larger object file on disk.

  • Configuration Variables
Parent topic: Using the Abend Diagnostic Report (ADR)


Configuration Variables

In addition to ACU_DUMP, there are three other configuration variables that affect creation of an ADR.

ACU_DUMP_FILE This configuration variable determines the name of the report file. It allows two special parameters:
  • If the file name starts with a plus sign (+), the report is appended to the specified file. By default, a new report overwrites the specified file. Note that the + character does not actually appear in the file name.
  • If the name contains the string %p, when the report is generated, that string is replaced with the process ID (PID) of the runtime from which the report originates.

The default value for ACU_DUMP_FILE is acudump.#, where # is an integer, starting at one and incrementing by one each time a new ADR is created in the current directory (acudump.1, acudump.2, and so on). Note that the first available filename is used, so if a directory contains files called acudump.1 and acudump.5, the next ADR file created in that directory is automatically called acudump.2.

Because the runtime performs a linear search to determine the next available filename to use, if a directory contains a large number of ADR files, the search can take some time. For this reason, it is a good idea to remove unneeded ADR files regularly.

ACU_DUMP_WIDTH

Determines the width of the report (in characters). Note that because the report uses dynamically computed columns for its hexadecimal data, making the report very wide can reduce readability by introducing excessive white space.

Permissible values: a numeric ranging from 79 to 2048 - Default value: 80.

ACU_DUMP_TABLE_LIMIT

Limits how many elements of each table item to list. Note that if you increase this value substantially, and if you have tables that allow for large numbers of elements, you may get very large reports.

In the following example, ACU_DUMP_TABLE_LIMIT is set to 5:

01 MY-TABLE-R                     = (group)
05 TABLE-ENTRY(1)                 =     1          h20202020 31
05 TABLE-ENTRY(2)                 =     2          h20202020 32
05 TABLE-ENTRY(3)                 =     3          h20202020 33
05 TABLE-ENTRY(4)                 =     4          h20202020 34
05 TABLE-ENTRY(5)                 =     5          h20202020 35
Remaining table items suppressed due to ACU-DUMP-TABLE-LIMIT setting

Default value: 1000

Parent topic: Generating a Report


ADR Restrictions

You should note the following restrictions in the use of the ADR:

  • Tables are expanded up to only four dimensions. If you have a table with more dimensions, then only the first element of the higher dimensions is seen. This limitation comes from a limit in the object's internal symbol table.
  • Level 77 data items are listed as level 01 items. This is caused by the way the compiler internally stores the symbol table.
  • Level 88 data items are listed, but show the actual data instead of the true/false evaluation of the data.
  • The report does not show line numbers for programs in the call stack, only for the aborting program. Addresses for calling programs are shown, and these can be found in a listing of the program.
  • Programs must be compiled with line number information (-Gl) in order to show line numbers, and symbol information (-Gs) to see data items in detail.
Parent topic: Using the Abend Diagnostic Report (ADR)


Object File Utility - cblutil

ACUCOBOL-GT's COBOL library utility, cblutil, works with ACUCOBOL-GT object files to provide several valuable capabilities. cblutil allows you to:

  • place object files together to create object libraries
  • output information about an object file or object library
  • create native-code object files from machine-independent ACUCOBOL-GT portable object files
  • Object Libraries
  • Creating Object Libraries
  • Getting Object Information
  • Generating Native Code
Parent topic: Debugger and Utilities
Parent topic: Utilities


Object Libraries

An object library is a file that contains one or more compiled ACUCOBOL-GT programs. Object libraries can simplify the distribution of an application by reducing the number of files involved. They can also help improve performance by reducing the number of directory operations performed by runcbl when it is loading object modules. The advantages are particularly noticeable if the number of object files in a directory is large.

Each object library contains a primary module. The primary module is the first (or only) module in the library. When the library is loaded by a CALL statement (or is the first program of a run unit), the primary module is the program that is loaded and run. Other modules in an object library can be loaded by subsequent CALL statements.

In order for the runtime system to access other object modules in a library, the primary module must be loaded. It may either be active or inactive, but it must be physically present in memory. A program is loaded whenever it is called; it is unloaded whenever it is canceled (or when it exits, if it has the INITIAL attribute). See Memory Management for a more complete description of runtime memory management.

Assuming that the primary module is loaded, then the other modules in the object library can be called if their name matches the name specified in a CALL verb. Modules in an object library are identified by PROGRAM-ID. If a matching name is found in an object library, that object module is then loaded and executed. See Calling Subprograms for more information.

As suggested by these rules, you should place related object files together. Usually this is done by specifying the main program of a run unit as the primary module and then adding in some or all of the subprograms it calls.

Object libraries may also be pre-loaded. This is done with the -y option of runcbl. When a library is pre-loaded, all of its modules are always available. Note that pre-loading does not mean that the component object modules and contained ENTRY points are physically loaded into memory. It just means that the directory of the contained modules is loaded. More than one library may be pre-loaded, and pre-loaded libraries may be used with dynamically loaded libraries with no restrictions.

Parent topic: Object File Utility - cblutil


Creating Object Libraries

You can create object libraries with the cblutil program provided with the ACUCOBOL-GT runtime system. This command line has the following format:

cblutil  -lib  [options]  modules

When you create a new object library, the first module specified becomes the primary module. All other modules are simply added to the library. If no options are specified, then the first module specified is converted from an object file or resource into an object library, and the remaining modules are added to it.

The first module may also be an object library. In this case, the remaining modules are added to the library. Any module that has the same name as one already contained in the library automatically replaces the one in the library.

The modules may be any type of file. If an input file is a COBOL object, then cblutil includes it in the resulting library as a COBOL object. Any other type of file is included as a resource. If an input file is another library, then each component of that library is individually added to the resulting library. The resulting library may consist entirely of COBOL objects, entirely of resources, or a mixture of the two.

A total of 1024 modules can be placed in a single library.

Options can be one or more of the following:

-c | Used to embed a comment in the object library. This flag must be followed by the comment. Comments with embedded spaces must either be between quotation marks, or include the shell's escape character before each space.
-o | This option must be followed (as the next separate argument) by a file name. This file becomes the new object library. If a file exists by that name, it will be deleted first.
-v | Causes cblutil to be verbose about its progress.
-r | Causes the separate modules to be deleted after they have been added to the object library. If -o has not been specified, then the first module (which becomes the new library) is not deleted.
  • Examples
  • Creating Remote Object Libraries
Parent topic: Object File Utility - cblutil


Examples

The following sample command line creates a library called mylib that consists of two ACUCOBOL-GT objects named prog1.acu and prog2.acu:

cblutil -lib -v -o mylib prog1.acu prog2.acu

You can add a comment to the object library. The comment is visible when you use the -info command to retrieve information about the object library:

cblutil -lib -o mylib -c "My comment" prog1.acu prog2.acu

Alternatively, you can add a comment using an escape character instead of quotation marks as follows:

cblutil -lib -o mylib -c My\ new\ comment prog1.acu prog2.acu

Wild cards are permitted:

cblutil -lib -v -o mylib prog1.acu otherdir/*.*

To add modules to an existing library, do not use the -o argument. For example, to add prog3.acu and prog4.acu to mylib, do this:

cblutil -lib -v mylib prog3.acu prog4.acu
Note: There is no way to remove an object module from a library. For this reason, we recommend that you create object libraries after all of the programs involved have been fully debugged.
Parent topic: Creating Object Libraries


Creating Remote Object Libraries

If AcuServer or AcuConnect is running on a remote machine, cblutil can read remote objects and write a remote library. The syntax rules that apply to specifying remote object libraries with cblutil are the same as those for compiling to remote object libraries with the compiler. See Remote File Name Handling for details.

This capability allows you to create a remote library from local object files or to create a local or remote library from remote object files.

With cblutil, you can also use the regular AcuServer syntax for referring to the remote files. This syntax is not allowed with the compiler because the @ symbol is reserved for another purpose. See Accessing Remote Files for more information.

Note: You cannot use wildcard characters to create a library from a collection of remote object files.

In the process of creating a remote library, cblutil overwrites the named library at the beginning of the operation. Then if something fails during the process, the library is removed. For that reason, you may consider creating a backup copy of the named library before executing the build library command. (Incidentally, when creating a local library, cblutil creates a temporary library first. Only after the new library has been successfully compiled is the (existing) named library removed and replaced by the new library.)

  • Examples
Parent topic: Creating Object Libraries


Examples

The following command creates a library in /myapp/obj on the UNIX server myserver called myapp.lib from all the .acu files in the current directory.

cblutil -lib -o acurfap://myserver::/myapp/obj/myapp.lib *.acu

acurfap stands for Acucorp Remote File Access Protocol.

The following command creates a library in /myapp/obj on the Windows server myserver where AcuServer is listening on port 6543. The library is named myapp.lib. The files used to create the library are all in /myapp/obj on myserver. Because you cannot use wildcard characters, you need to list each file.

cblutil -lib -o
   acurfap://myserver:6543:c:/myapp/obj/myapp.lib \
      acurfap://myserver:6543:/myapp/obj/test1.acu \
      acurfap://myserver:6543:/myapp/obj/test2.acu \
      acurfap://myserver:6543:/myapp/obj/test3.acu \
      acurfap://myserver:6543:/myapp/obj/test4.acu
Note: The use of the backslash character (\) as line continuation delimiter works only on UNIX systems. If you are entering a command for Windows, you must type the entire command as a continuous string.
Parent topic: Creating Remote Object Libraries


Getting Object Information

The cblutil program can output useful information stored in the header of an object file or object library. The format of the command is:

cblutil  -info  [-x]  files

The options used to compile a COBOL program are automatically embedded in the program's object file. The -x option to the -info command causes cblutil to output all the options used to compile the object file.

Each file named on the command line is examined to determine if it is an object module or object library. If it is an object module, its size and other information is output. If the file is an object library, information is output for each module the library holds.

In each report, cblutil includes information that indicates whether the module is in debug-mode. Because programs compiled for source-level debugging can be quite large, it can be helpful to run reports on a regular basis to see if you have accidentally left any programs in debug-mode.

For example, the following could be run on a UNIX system every night:

cblutil  -info  /objects/* | grep  "debug"  >  /tmp/debug

This command creates a file called /tmp/debug that lists every program in the /objects directory that is in debug-mode.

The cblutil program also reports whether or not table-boundary checking is enabled in an object file, and, if the object contains an embedded comment, lists the comment.

Parent topic: Object File Utility - cblutil


Generating Native Code

The -native option of cblutil allows you to translate ACUCOBOL-GT portable object modules into native-code object modules. The -native option has the following format:

cblutil -native [options] object-files ...

options can be any of the following:

--intel or --ia-32 | produces 32-bit native code for Intel-class processors (386, 486, Pentium, Pentium II, Pentium III or compatible processors).
--pa_risc or --pa | produces 32-bit native code for PA-RISC version 1.0 running the HP-UX operating system
--pa_risc_2.0 or --pa2 | produces 64-bit native code for PA-RISC version 2.0 running the HP-UX operating system
--power | produces code that is compatible with POWER and POWER2 processors, as well as PowerPC and later POWER series processors. This option allows you to use a wide range of machines, but it may affect performance.
--powerpc or --ppc | produces 32-bit native code for IBM pSeries processors running AIX operating system Note that you can compile native code only for machines with a POWER3 or later chip, not with POWER2 or earlier.
--powerpc_64 or --ppc64 | produces 64-bit native code for IBM pSeries processors running AIX
--sparc | produces 32-bit native code for SPARC (v7 - v9) processors.
--sparc_v9 | produces 64-bit native code for SPARC version 9 processors.
--x64_Win | produces 64-bit native code for x64 processors on Windows platforms.
--x64_Unix or --x64_Linux | produces 64-bit native code for x64 processors on UNIX/Linux platforms.
-o | names the output file. This option must be followed (as a separate argument) by the name of the file to produce. You may use @ in this name to stand for the base name of the input object file. If you specify -o and multiple object files, then you must use @ in the name. If you omit -o, then the output file replaces the input file.
-v | causes cblutil to print the name of each object file as it is being processed.
-Zc | produces code that is more compact and somewhat slower.
-Zn | turns off the more involved optimizations.

If you specify multiple object files, then each one is translated in turn. If object file refers to an object library, then each module contained in the library is translated. If an object file contains debugging information, that information is retained.

If you do not specify a target processor, then cblutil translates for the processor of the host machine, if native code for that processor is supported. Once an object file has been translated to native code, it cannot be translated again for a different instruction set.

If the object module does not contain ACUCOBOL-GT's portable instruction set, the cblutil -info command includes in its outputs the name of the native instruction set used.

Parent topic: Object File Utility - cblutil


Vision File Utility - vutil

On Windows, UNIX, and Linux systems, ACUCOBOL-GT uses the Vision indexed file system to manage its indexed data files. For these systems, ACUCOBOL-GT comes with an indexed file utility program called vutil that contains several useful functions. The full name of this 32-bit utility is vutil32, but is referred to as vutil.

Note: Other file system interfaces have their own file utility packages. On VMS systems, for example, ACUCOBOL-GT uses the RMS file system that is native to VMS, and the vutil utility is not supplied. VMS-specific programs such as ANALYZE/RMS and CONVERT can be used to accomplish the same functions that vutil provides.

vutil provides several functions in one package. It can be used to:

  • display file information (-info, -size, -tree)
  • test file integrity (-check)
  • modify keys within an existing file (-key)
  • rebuild and repair files (-rebuild)
  • reset the user count (-zero)
  • reset the internal revision number (-fixvers)
  • extract data records (-extract)
  • create empty files (-gen)
  • unload data to binary or line sequential files (-unload)
  • load data from binary or line sequential files (-load)
  • convert other index files to Vision (-convert)
  • change the maximum record size (-augment)
  • recover deleted records (-deleted)
  • place text in the comment field of the header (-note)
  • test the atomicity of a file system (-wtest)

Each of these functions is indicated by an initial keyword on the command line (preceded by a hyphen). This keyword may be abbreviated to its first letter. The functions are designed to allow you to specify all possible task parameters up front, so that the utility can run unattended or with a minimum of user interaction. Each function is discussed below.

  • Examining File Information
  • Testing File Integrity
  • Modifying Keys in an Existing File
  • Rebuilding Files
  • Resetting User Counts
  • Resetting Internal Revision Number
  • Extracting Records From a File
  • Recovering Deleted Records
  • Creating Empty Files
  • Unloading to Binary and Line Sequential Format
  • Loading a File
  • File Size Summary Report
  • Converting RMCOBOL-85 Indexed Files
  • Converting C-ISAM Files
  • Converting Micro Focus Files
  • Changing Record Size
  • Setting the Comment Field
  • Testing for Vision File Locking Compatibility
  • Miscellaneous Commands
  • Default Settings of vutil
Parent topic: Debugger and Utilities
Parent topic: Utilities


Examining File Information

The info function of vutil returns some basic information about Vision indexed files. The command syntax is:

vutil  -info  [ -kpxqd ]  [ files ]

If no files are specified on the command line, then vutil reads file names from the standard input. Several options can be specified with -info:

-p | This option causes vutil to pause between files and prompt the user for a return key. Otherwise, all the reports are run together.
-k | This option prints full details about each key, including the exact layout of a multi-segment or split key.
-q | This option causes vutil to exit (with status 99) if user interaction is required.
-x | This option causes vutil to report additional (extended) information.
-d | This option displays the key descriptors for the specified file. This option may not be specified alongside options -k or -x.

The basic information provided by the info function consists of:

  • text in the comment field (frequently empty)
  • Vision file format (Version 3, 4, 5, or 6)
  • total number of records
  • total number of deleted records
  • file size of each segment (Version 4 and later)
  • total size of all segments combined (Version 4 and later)
  • segment size (maximum possible; Version 4 and later)
  • record size (min/max)
  • number of keys
  • user count

If you request extended information with the -x option, the following additional information is output:

  • for each key: key size (total size and number of segments, if split); key offsets; whether duplicates are allowed
  • block size
  • blocks per granule
  • tree height (max/min/avg)
  • number of nodes
  • number of deleted nodes
  • total node space
  • node space used
  • unique counter (count and progress towards the limit)

The tree height is the number of levels in the B-tree and is directly related to how efficient the file is. If the maximum number exceeds four or five, then the file may benefit from rebuilding with a larger block factor. See Rebuilding Files for more information.

An important piece of information is the user count. The user count is initially set to zero, and is incremented each time the file is opened for I/O. The number is decremented when the file is subsequently closed. Under normal circumstances, the user count indicates the number of users who are currently updating the file. Should runcbl terminate abnormally, the user count may not be decremented. Therefore, if the user count is a non-zero value when there are no active users, it indicates that there may have been a sudden runtime failure and that corrective action may be required. At the very least, the file should be checked for integrity, but depending on the program that died, more significant action may need to be taken. A non-zero user count indicates that someone knowledgeable about the system should intervene and ensure that everything is okay. By monitoring the user count, the user count can be used as an early warning system to head off some types of file problems before they surface in a more serious form. Note that because runcbl usually closes all files when it detects an error, it is very unusual that a COBOL coding error will cause a non-zero user count condition. See Testing File Integrity for more information.

Note: Unlike RM/COBOL, a non-zero user count is not automatically an indication of a corrupt file. It merely means that a program has died while it had files open.

The unique counter displayed in the extended file information gives a running count and percentage towards the maximum number of records that can be written to a Vision file. The percentage should give you an indication of when to switch to a new file, as when the limit is reached, the file is marked as broken.

Parent topic: Vision File Utility - vutil


Testing File Integrity

The -check option of vutil tests a file for internal consistency. The command is:

vutil  -check  [ -afkqx ]  [ files ]

With no options, vutil reads a list of files from the standard input and tests each one for a non-zero user count and other quickly tested errors. Files with errors or a non-zero user count are listed. You may place the list of files to check on the command line instead of using the standard input.

-a | (for automatic) This option causes vutil to do a thorough test of each file that has a non-zero user count. It will read every record in an attempt to see if the file is broken. Any problems that are detected are printed. You can use this option to test a large number of files for errors without exhaustively reading every record from every file. Only those files that appear to have potential problems (because of the non-zero user count) are tested.
-f | (full) This option forces a file to be checked (including files with a user count of zero). When both -a and -f are specified, -f takes precedence.
-k | (key number) This option is used to specify the key to be used to read the file. All the keys in the file are read sequentially by the specified key during the check of the file. This option must be used in combination with the -a or -f option. This option has no effect when used with the -x option. -k must be followed (as the next separate argument) by the number of the key you want to use. Zero (0) indicates the primary key, 1 indicates the first alternate, and so forth.
-q | This option causes vutil to exit (with status 99) if user interaction is required.
-x | (extended tests) This option causes vutil to run extended tests in place of those that are normally run by the -a or -f options. The extended tests include: reading every record with every key, reading the records in their physical order in the file, and checking the deleted records list. The filename is displayed along with a message that indicates which test vutil is currently working on. This option causes a write lock to be placed on the file to ensure exclusive access during the tests. You must specify the -x option with either -a or -f on the same command line; used by itself, it does nothing. The -x option disables the -k option when the two are specified on the same command line.
Note: Although the -check option tests the file thoroughly, it is possible for a file to be corrupt and still pass the test. If you're processing an indexed file outside of vutil and you receive a file error 98, that file is corrupt even if it passed the vutil -check test.

For convenience in building scripts, the -check option will not complain if given a non-Vision file. This allows -check to be run on an entire directory without generating spurious errors from relative and sequential files.

When you perform vutil -check, one of the following status values is returned to the host operating system when vutil quits:

0 | file passed all checks
1 | checks not fully performed because the file was in use
2 | non-zero user count found
3 | file is corrupt
99 | user interaction was required, and the -q switch was set
255 | vutil fatal error or incorrect command line

If more than one file is checked, the highest status value that applies is returned.

Parent topic: Vision File Utility - vutil


Modifying Keys in an Existing File

Restriction: You can only modify keys in Vision files of version 6 or later, and that are not encrypted.

The -key option enables you to add, delete, or modify keys in a Vision file. The command is:

vutil -key [-q] ([ -a # kdesc] | [-d #] | [-m # kdesc]) file-name
The arguments are:
-q | This optional argument suppresses the warning message that is generated informing you that the file is modified in place.
-a # kdesc This argument adds a key at the position indicated by #. (Keys range from 0 (the primary key) to 120.) If keys already exist at and beyond the specified number, they are incremented to accommodate the new key.

kdesc is the key description, and must take the following format:

A,B,C,D[,C,D]...

where:

A is the number of segments in the key. A key may have from 1 to 16 segments. Each segment must be described with a size, offset pair (see C and D).

B indicates whether the key allows duplicates or not. 0 indicates that it does not allow duplicates; 1 indicates that it does.

C and D indicate the size and offset of a key segment. One such pair must occur for each key segment indicated in A.

This option is mutually exclusive of options -d and -m.

-d # This argument deletes the key indicated by #. If any keys follow the deleted key, they are decremented to fill the gap left by the deleted key.

This option is mutually exclusive of options -a and -m.

Note: When a key is deleted, the index blocks that made up the deleted key are marked as free for future use, but the space is not reclaimed from the file. The file will size will not shrink unless you then rebuild the Vision file, which removes any extra space in the file.
-m # kdesc This argument modifies the key at the position indicated by #.

kdesc is the new description for the key, and takes the same format as for the -a argument.

This option is mutually exclusive of options -a and -d.

file-name | This argument is the name of the Vision data file to be modified in place.

Comments:

Due to the nature of these operations, you should not perform them on a Vision file without backing it up beforehand. Any failure during the modification of the key structure could leave the file in an unrecoverable state, and requiring you to revert to a backup.

Before performing any of the modification operations, the Vision file is marked as broken, with a 97 sub-code (98,97 file status). Upon successful completion of the operation, this code is removed.

If a new or modified key is specified to not allow duplicate key values, and duplicate key values are found when the key is indexed, the setting will be overridden and the key will allow duplicate key values.

When altering the key structure of a file to allow duplicate key values, be aware that data may not be retrieved in the order that you expect when using that key. To distinguish duplicate key values, a unique value is assigned to each record containing the duplicate data. Usually, this happens as the record is written to the file, and so records can be retrieved using this data, in chronological order. By introducing duplicate keys on an existing file, the unique values must be assigned en masse, in the order that the records currently sit in the file; therefore, retrieving records using the key will not necessarily return them in the order in which they were written.

Parent topic: Vision File Utility - vutil


Rebuilding Files

The -rebuild option is used to rebuild or recreate an indexed file. You should rebuild a file that has become corrupt, or one that contains a large number of deleted records that you want to remove from the file. The command is:

vutil -rebuild  [ --slow ]  [ -l ]  [ -t tmpfile ]  [ -b # ]
  [ -3456 ]  [ -ac ]  [ +ce ]  [ -k keynum ]  [ -d dir ]
  [ -f factor ]  [ -s spoolfile [ -r ] [-m size] ]
  [ -p pre_factor ]  [ -g ext_factor ]  [ -q ]  [ -j #threads] [ files ]

Each file listed on the command line will be rebuilt. If no files are listed, then the standard input is read for the list. If, under UNIX, the named file is a symbolic link, the link is removed and the restored file is put in its place.

This option by default applies a read lock to the file that is rebuilt. The -l option applies a write lock instead.

When a file is rebuilt, a temporary file is created and each record from the original file is written to it. The -t option allows you to specify the name of the temporary file used during the rebuild. (You may not specify a directory, just a file name.) When -t is not specified, the temporary file's name begins with VTMP, followed by a six-character system-generated sequence. On Windows systems, the file's name begins with V. The rebuilding process reports the number of records found and the number of deleted records that were skipped. After the rebuild is complete, you are given the option of replacing the original file with the new one. If you do not replace it, you can examine the temporary file for correctness and replace it manually later. This is recommended if you suspect any difficulties.

When doing a rebuild, vutil places records that are rejected due to illegal duplicate keys into a file. Should this happen, vutil will report the name of the file that contains the rejected records. The format of this file is the same as a COBOL binary sequential file with variable-size records.

-a     This option may be used to specify automatic replacement of the original file by the newly created one. This is useful when you are calling vutil from a program or a script.

When used once, this option causes automatic replacement only if no records are skipped. If any records are skipped, you are prompted before file replacement takes place. When used more than once, this option causes automatic replacement of the file even if records were lost in the process.

The multiple specification of option -a may be given in the following syntax formats:

-aa

-a -a

-a (other options) -a

-b # This option sets a new blocking factor for the file. The blocking factor specifies the size of the blocks to be used by the file. Blocks are sized in 512 byte increments. Vision 5 and Vision 6 files support blocking factors from 1 to 16 (16 = 8192 bytes). Vision 3 and 4 files support blocking factors from 1 to 2.

When you rebuild a file, if the file is very large, or has a tree height of more than five, or key lengths in excess of 40 bytes, you may want to experiment with larger blocking factors. You will need to perform some benchmarking to determine if a larger block size improves performance. For more about how block size can affect performance, see Other Vision Features.

If you specify a blocking factor greater than 2 for a Vision 3 or 4 file, the factor is automatically and silently reduced to the maximum of 2.

-c | This option removes record compression from the file.
+c | This option adds record compression to the file.
-d dir | This option specifies an alternate directory for placing the rebuilt file. Dir should be the name of a directory on the host machine other than the directory containing the files to be rebuilt. When this option is used, the original files are not modified or destroyed. The rebuilt files are placed in dir with the same base name as the original files. This option can be useful if you do not have enough disk space on the device holding the files to rebuild them, but you do have space on another disk. This option implies the -a option because you are not prompted before the rebuild completes.
+e This option adds record encryption. It is not possible to remove record encryption (this would make encryption pointless).

Record compression and encryption may be added to a file, and compression may be removed from a file, regardless of the presence or absence of the WITH COMPRESSION and WITH ENCRYPTION phrases in the file's SELECT.

-f factor This option allows you to specify a compression factor. The factor must be an integer that specifies how much of the space saved by compression is actually to be removed from the record. Zero means no compression. A value of 1 means use the default factor (70).

For factors from 2 through 100, the factor is considered to be a percentage. It specifies how much of the space saved by compression is actually to be removed from each record. For example, suppose an 80-byte record is compressed to 30 bytes. Then the compression factor is used to determine how much of the 50 bytes of saved space is actually to be removed from the record. A compression factor of 70 would mean that 70% of the 50 bytes (35 bytes total) will be removed. This leaves 15 bytes for future expansion, and results in a compressed record size of 45 bytes (30 compressed size plus 15 extra for growth). The larger the compression factor, the more of the saved space is removed. A compression factor of 100 removes all saved space and allows no room for expansion.

-g ext_factor | This option sets a new extension factor for the file. This is the number of blocks that are added to a file's size when the file needs to be expanded. The default is one block. Specifying more than one enables you to take advantage of contiguous disk space, and thus may help to prevent fragmentation of the file as it grows.
-j #threads This option enables you to use multiple threads when rebuilding multi-keyed, Vision 6-formatted (or later) Vision files, which can improve the performance of the rebuild.

#threads must be a number between 2 and 120, and specifies the number of threads to be used in the rebuild process. Each thread is used to rebuild a key in the file; a new thread being spawned when a previous one completes rebuilding a key, until all keys are rebuilt.

The optimum number of threads that gives the best performance will vary depending on your system, and so trial and error in specifying different numbers of threads may be required. As a general guideline, specify a similar number of threads as your system has CPUs.

An important consideration when specifying the number of threads is that each thread is allocated memory as if it were its own version of vutil; therefore, the memory you have allocated for the V_BULK_MEMORY, V_BUFFERS, MAX_FILES, etc... variables is multiplied by the number of threads.

Another consideration is that rebuilding using multiple threads also uses additional temporary disk space, to hold the intermediate results of each key rebuild. This could be up to double the amount of space that a non-threaded rebuild would use.

-k keynum This option specifies that you want to rebuild the file in key order. The -k must be followed (as the next separate argument) by the number of the key that you want to use, with zero indicating the primary key, one indicating the first alternate key, and so forth. For example, to rebuild file1 in primary key order, you would specify:
vutil -rebuild -k 0 file1

There are two situations in which the -k option is particularly valuable. If you are repeatedly processing a file along a particular key, then you can improve performance by rebuilding the file in key order. This is particularly true if you do a great deal of sequential processing (common in reports). When you rebuild in key order, records that are logically adjacent (according to their key values) are placed next to each other on the disk. This maximizes the runtime's ability to improve performance with its read caching capabilities. It also minimizes the distance that the disk must seek when you are reading records sequentially by that key. Write performance also improves in applications that write large numbers of records in keyed sequence.

A second situation in which the -k option is valuable is when the default rebuild method fails to recover a file fully. This can occur if the chain of data records has been corrupted. When -k is specified, vutil will use the index you provide to try to locate the records, and will often find more records this way.

-p pre_factor | This option allows you to specify the number of blocks that vutil is to preallocate to the file. pre_factor must be a numeric value between one and 2,097,152. The maximum pre-allocation factor varies with Vision version. Vision 5 and Vision 6 files accept the upper limit of 2,097,152 blocks. Vision 3, and 4 files are restricted to a maximum of 65,535 blocks. If a larger pre-allocation factor is specified than the Vision version allows, the factor is automatically and silently reduced to the allowable limit.
-q | This option causes vutil to exit (with status 99) if user interaction is required.
-s spoolfile This option indicates that you want to use the spooling form of rebuild. This is especially helpful if you do not have adequate disk space to hold the new file. This option spools the records to removable media and then rebuilds the file over the existing file. This keeps only one copy of the file on disk and thus allows you to rebuild even when free disk space is limited. Note that the spooled file is not compressed.

The -s option must be followed by the name of the file to which you want to spool records. This can be any file but is usually the name of a tape or diskette device. For example, you might specify

vutil -rebuild -s /dev/rmt0 badfile

to rebuild the file badfile by spooling records to the tape device /dev/rmt0.

When -s is specified, vutil writes all the records it can recover from the corrupt file to the spool file, and then rebuilds the file using these records. You will be prompted to change media if the spool file gets full.

There are two additional options that can be used with the -s option:

  • -- allows you to recover an interrupted rebuild. When -r is specified, vutil skips the step of writing records to the spool device. Instead, it prompts you to mount the first volume of the spool file before it begins the rebuilding process.
  • -m size -- allows you to specify the size of the spool media. It is followed by the number of 1024-byte records that can fit on the media. This is useful when the spool device driver does not handle the end-of-media condition correctly. For example, if you were spooling to a 1.2 MB floppy disk, you could specify:
    -m 1200
--slow | This option causes vutil to open the file for mass update instead of for bulk addition. This usually causes vutil to run slower. The only reason for using this option is as a possible work-around to some difficulty with using bulk addition.
-# This option causes vutil to rebuild the file in the Vision file format specified by the integer. Valid values include 3, 4, 5 and 6. If the -# option is not included, the file is rebuilt in the same format as the original file.

When you perform vutil -rebuild, one of the following status values is returned to the host operating system when vutil quits:

0 | file successfully rebuilt
1 | rebuild not performed because the file is locked
2 | rebuild not fully performed because some records were not recovered
99 | user interaction was required, and the -q switch was set
255 | other errors
Parent topic: Vision File Utility - vutil


Resetting User Counts

This option resets the user count of each named file to zero. It is much faster than rebuilding when you are certain there are no other problems with the file. The command is:

vutil  -zero  [ -q ]  [ files ]

The files may be listed on the command line, or may be read from the standard input. For convenience in building scripts, non-Vision files are ignored.

-q This option causes vutil to exit (with status 99) if user interaction is required.
Parent topic: Vision File Utility - vutil


Resetting Internal Revision Number

This option resets the internal revision number of all segments in the specified Vision file to the revision number of the first data segment. It does this without rebuilding the entire file. To use this option, you must have exclusive access to the file. The command is:

vutil  -fixvers  [ -q ]  [ file ]

The files can be listed on the command line, or can be read from the standard input. For convenience in building scripts, non-Vision files are ignored.

This option can be used to repair 98, 89 and 98, 90 conditions that can result from improper shutdowns of a runtime or improper closure of a file. Before using this option, you should be certain that the file is otherwise internally correct, meaning that the data is not corrupted. Improper use may lead to loss of data. After using the fixvers option, you should run vutil -check -f file to verify internal consistency of the file. See Testing File Integrity for more information.

-q This option causes vutil to exit (with status 99) if user interaction is required.
Parent topic: Vision File Utility - vutil


Extracting Records From a File

The -extract option prints selected records on the standard output. The command syntax is:

vutil  -extract  [ -x ]  [ -k# ]  [ -n# ]
   [ -v value ]  [ -q ]  file

When using the "-extract option, you may use command-line options to specify the primary key, starting value, and the number of records. If you do that, vutil does not interrupt the -extract later (after printing a synopsis of the file) to prompt for those parameters. vutil does a START NOT LESS THAN on the desired key and proceeds to print records on the standard output. Each record is printed on its own line.

Note: If the file contains binary or COMP-3 data, that data may contain carriage returns (binary 0Ds). Each binary 0D is interpreted as a carriage return, and that is reflected in the display of the extracted record.

These options can be used with -extract:

-k# | This option specifies the key number to extract from.
-n# | This option specifies the number of records to extract.
-v value | This option specifies the key value from which to start the extract.
-q | When you use this option, the key number defaults to "0" (zero), the number of records defaults to all, and the keyval defaults to low-values, unless you specify these values with the -k, -n, and -v options.
-x | This option allows record extraction to continue if an error occurs. Records that generate errors are not included in the output file.

vutil will not let you extract records from an encrypted file.

Parent topic: Vision File Utility - vutil


Recovering Deleted Records

The deleted function recovers records that have been marked as deleted, but which have not yet been overwritten by a new record. This function can be used only with Vision 5 and Vision 6 files.

The -deleted option looks for records marked as deleted and writes their contents to a sequential file. For example:

vutil -deleted -vb infile.vis outfile.seq

reads through the list of deleted record areas in infile.vis and writes the data to outfile.seq in the form of a sequential file with variable length records and a portable record header that indicates the size of the record.

The file containing the deleted records may be loaded back into the Vision file with vutil -load, or opened by the runtime like any other sequential file.

Note: The deleted function works only with Vision 5 or Vision 6 files.

The command syntax is:

vutil -deleted [-v] [-b] [-t] [-q] source destination

-v | creates a file that contains variable-length records.
-b | creates a binary sequential file that is compatible with the ACUCOBOL-GT runtime. If the -v option is also specified, variable length records are written. Otherwise, fixed-length records are written.
-t | creates a line sequential file. This option always writes variable length records.
-q | tells vutil to perform all actions without prompting the user for input. This is useful when running vutil -deleted as a batch job.
source | is the name of an existing Vision 5 or Vision 6 file.
destination | is the name of the file to be filled with the recovered data.

By default, recovered records are written in a machine dependent binary sequential file format that is not compatible with the runtime. To create a file that is compatibility with the ACUCOBOL-GT runtime, include either the -b or -t option.

Parent topic: Vision File Utility - vutil


Creating Empty Files

The -gen option creates empty Vision files. This is equivalent to doing an OPEN OUTPUT on the files from COBOL and is supplied as an alternative to writing a program explicitly to create empty data files. The command syntax is:

vutil  -gen  [ -3456 ]

or

vutil  -gen  [ -3456 ]  [ -q ]  list  directory

The first command format invokes a prompting program that asks you for the name of the new file and each file attribute. The second command format allows you to specify all of the file attributes in advance, and store them in a file.

Whether you store the attributes in a file or respond to prompts at the keyboard, the file attributes you provide are the same.

-6 | creates a file in Vision Version 6 format. This is the default.
-5 | creates a file in Vision Version 5 format.
-4 | creates a file in Vision Version 4 format.
-3 | creates a file in Vision Version 3 format.
-q | This option causes vutil to exit (with status 99) if user interaction is required.

When you perform vutil -gen, one of the following status values is returned to the host operating system when vutil quits:

0 | file successfully rebuilt
255 | unsuccessful
  • Responding to vutil Generated Prompts
  • Specifying File Attributes in Advance
Parent topic: Vision File Utility - vutil


Responding to vutil Generated Prompts

If you use the interactive version of the gen option, you are immediately given the opportunity to store the session in a file, so that your responses can be used again. (In fact, you can use the session file as the list file with the non-interactive version of gen.) If you indicate that you do want to save the session, you are prompted for a session file name.

Next you are prompted for the name of the new file, and for its attributes. The exact prompts are shown here, and are described in Specifying File Attributes in Advance. Default values are enclosed in brackets.

Save this session [Y]?
          Enter session filename:
          Enter filename:
          Enter the blocking factor [1]:
          Enter the number of blocks to pre-allocate [1]:
          Enter the # of blocks for extension [0]:
          Enter the compression factor (0-100) [0]:
          Enable record encryption [N]?
          Enter the maximum record size:
          Enter the minimum record size (1-maximum) [maximum]:
          Enter the # of keys [1]:
          -- Primary key --
          Enter number of segments (1-6): (For generating Version 3
             files)
          Enter number of segments (1-16): (For generating Version 4 or 5
             files)
          Enter segment size:
          Enter segment offset:(Segment size and offset repeat as a pair for
             each segment)
          Duplicates allowed [N]?
          -- Alternate key n -- (repeats for each alternate key)
          Enter number of segments:
          Duplicates allowed [N]?
          Enter segment size:
          Enter segment offset:(Segment size and offset repeat
          as a pair for each segment)
          Enter translation table filename:
          Enter file comment (30 char max):
          Generate another file?
  • Collating Sequence
Parent topic: Creating Empty Files


Collating Sequence

One of the attributes you may specify is the name of a file containing a translation table. This enables you to create a custom collating sequence for the new file, instead of using the standard ASCII collating sequence. The exact format for the translation table is given here.

All white-space characters (space, tab, new line, etc.) are ignored, so the table can have as many lines and spaces as you desire.

The sequence of the characters in the table determines the collating sequence for keys. For example, a file which looks like this:

Z Y X W V U T S R Q P O N M L K J I H G F E D C B A

would sort keys reverse alphabetically, for the values in the range A to Z.

You may enter special characters by typing a backslash (\) and then the decimal value of the character desired. Thus, \032 would be used to specify the SPACE character.

Ranges can be specified with a dash (-). The sequence of the starting and ending characters in the range is significant. The reverse-alphabetical table shown above could be specified more concisely as:

Z - A

Finally, you can give two or more characters the same sort value by using an ampersand (&) between them. For example, the file will not distinguish case if you use a translation table with the following format:

a & A b & B c & C d & D e & E f & F g & G h & H i & I j & J
k & K l & L m & M n & N o & O p & P q & Q r & R s & S
t & T u & U v & V w & W x & X y & Y z & Z

Any characters in the native collating sequence that are not explicitly named in the table assume a position greater than any of the explicitly named characters. The relative order of these unnamed characters remains the same as in the native collating sequence. In the last example, all digits, punctuation, and control characters would be in their usual order, but after all alphabetic characters.

Parent topic: Responding to vutil Generated Prompts


Specifying File Attributes in Advance

vutil  -gen  [ -3456 ]  [ -q ]  list  directory

The non-interactive version of gen allows you to specify a file (list) that contains the attributes for one or more new files. The format of list is described below.

The directory parameter names the directory in which the new files are to be created. Each file is tested to see if it exists before it is created. If it does exist, and it is a Vision file, then it is left untouched. Thus, you can use the "gen" function to generate missing files from a directory without having to first save the ones that are there.

The file list consists of one or more file entries, one per line. Each entry pertains to exactly one file and consists of a series of fields.

The list file can have one of two formats: a format for creating relative and sequential files, and a format for creating Vision Version 3 or later files (documented below).

For indexed files, the fields are divided into five groups, separated with semicolons. Fields within each group are separated with commas.

For relative and sequential files, the fields are all separated with commas.

  • Indexed Format
  • Sequential and Relative Files
Parent topic: Creating Empty Files


Indexed Format

The fields for the indexed format are listed here and then described below.

filename,
blocking factor,
number of blocks to pre-allocate,
number of blocks for extension,
compression factor,
Enable record encryption?;
maximum record size,
minimum record size,
number of keys;
For primary key:
    number of segments,
    Duplicates allowed?, (always zero)
    segment size,
    segment offset, (repeat the segment size and offset
                   pair for each segment)
For each alternate key:
    number of segments,
    Duplicates allowed?,
    segment size,
    segment offset, (repeat the segment size and offset
                   pair for each segment);
translation table filename;
file comment

In the indexed format, the first field is the (physical) file name. The second field is the blocking factor. For Vision 5 and Vision 6 files, the value can range from one to 16. For Vision 3 and 4 files, the value must be one or two (if a larger value is specified, it is automatically reduced to two). All I/O to the disk is done in blocks of one or two sectors. Depending on the file and the underlying disk architecture, performance can be affected by this. Although performance is difficult to predict, files that have very large keys may benefit from a larger blocking factor. See Other Vision Features for a more complete discussion.

The third field is the number of blocks to allocate to the file initially. This is usually set to one. If you want to pre-allocate some disk to the file, then this can be set to a higher number. Pre-allocation in no way limits the file, but may help performance by reducing disk fragmentation.

The fourth field is the number of blocks for extension. This determines how many blocks are allocated each time space needs to be added to the file. This helps keep fragmentation to a minimum.

The fifth field is the compression factor. A compression factor of zero (0) means no compression. A compression factor of one (1) is equivalent to the default compression (70). For factors from 2 through 100, the factor is considered to be a percentage. It specifies how much of the space saved by compression is actually removed from the record. For example, suppose an 80-byte record is compressed to 30 bytes. Then the compression factor is used to determine how much of the 50 bytes of saved space is actually removed from the record. A compression factor of 70 means that 70% of the 50 bytes (35 bytes total) is removed. This leaves 15 bytes for future expansion, and results in a compressed record size of 45 bytes (30 compressed size plus 15 extra for growth). The larger the compression factor, the more of the saved space is removed. A compression factor of 100 removes all saved space and is advisable only if the file is rarely updated.

The sixth field is a flag that determines whether record encryption is enabled. A value of one (1) enables encryption. A value of zero (0) disables encryption. A semicolon should follow the encryption flag.

The next two fields specify maximum and minimum record size. If the two numbers are identical, the records are fixed-length. If the two numbers are not identical, records are variable-length. The maximum record size allowed in Vision 5 or Vision 6 files is 67,108,864 bytes. The maximum record size allowed in Vision 3 and 4 files is 32,767 bytes.

The ninth field is the number of keys in the file, to a maximum of 120. A semicolon should follow the number of keys.

Next, you describe the primary key by at least four entries. The first entry is the number of segments in the key. The second entry is always zero (0). For each segment, you must then specify the segment size in bytes, and the segment offset from the start of the record, in bytes. If there are no alternate keys, a semicolon should follow the final segment offset. Otherwise, a comma should be used.

If there are any alternate keys, describe each one by a series of at least four entries. The first entry is the number of segments in the key. The second entry should be one (1) if duplicate values are allowed, or zero (0) if they are not. For each segment, you must then specify the segment size in bytes, and the segment offset from the start of the record, in bytes. A semicolon should follow the final segment entry of the last alternate key.

After the keys have been specified, enter the name of a file containing the translation table (collating sequence), if you want anything other than standard ASCII sorting. If the name is empty, ASCII sorting is assumed. A semicolon should follow the name of the translation file.

Finally, you may provide up to 30 bytes of comment. This comment is printed by vutil when the info option is used.

Here's a sample file entry. Suppose a file containing G/L account descriptions has a record size of 80 and two keys. The primary key is at the start of the record and is 15 bytes long. The alternate key has two segments; the first is at record offset 40 and is 30 bytes long. The second segment of the alternate key is at record offset 20 and is 5 bytes long (duplicates allowed). A compression factor of 30 and ASCII sorting are desired. The corresponding entry is:

glactfil,1,1,0,30,0;80,80,2;1,0,15,0,2,1,30,40,5,20; ;G/L account
             master
Parent topic: Specifying File Attributes in Advance


Sequential and Relative Files

For convenience, the non-interactive gen option can also create empty sequential and relative files if they are missing. The entry contains only three fields. The first field is the file name. The second field is the record size, and the final field is an S for a sequential file or an R for a relative file. The record size field is only comment, so it can be set to any numeric value.

Whether to use gen or a COBOL program to create the data files for an application depends on which is more convenient. Creating the file list can be painstaking, but the symbol table listing of the compiler can help to compute the size information. Once the files are created, however, it is easier to replace missing files this way than with a program that must explicitly test for a file's existence before creating it.

Parent topic: Specifying File Attributes in Advance


Unloading to Binary and Line Sequential Format

The -unload option creates a binary sequential file or a line sequential file from a Vision file. The command is:

vutil  -unload  [ -v ]  [ -b | -t ] [-l] [ -q ] [ -r ] [ -k #]  source  destination

The source file is the Vision file to unload; the destination is the name of the file to create. If a file with the name destination already exists, it is deleted first. The records in the destination file are ordered by the primary key of the source file. This can be used to export data to other applications. vutil will not let you unload records from an encrypted file.

The source file is buffered according to the value in the A_SEQ_DEFAULT_BLOCK_SIZE variable. The variable must be set in the environment for vutil to use it. If the variable is not set, the default buffer block size is 4096 bytes. If the variable is set to "0", vutil -unload into a sequential file will perform record-based I/O. If the variable is set to a positive value, that value will be rounded up to the power of two equal to, or greater than the value. This will be the buffer size in bytes. The maximum buffer size is 1GB.

By default, the destination file is assumed to be a binary sequential file with an alternate format that is not compatible with the ACUCOBOL-GT runtime.

These are the destination file format options:

-v This option produces a file that has variable-length records. Variable-length records occupy only as much disk space as necessary. Two or four bytes indicating record size are placed in front of each variable-length record when it is written to disk. (Different machines generate different prefixes. Thus, files produced with vutil -unload -v can be loaded with vutil -load -v on the source machine but are not necessarily portable to other machines.) The two- or four-byte field that is added to the record is not specified in your COBOL program, but some programs that access the records need to be aware of the extra bytes.

If -v is not present, fixed-length records are written.

-b This tells vutil -unload to produce a binary sequential file that is compatible with the ACUCOBOL-GT runtime.

If -v is not present, fixed-length records are produced.

The -v option causes vutil to produce variable-length records. The record length is stored in a two-byte record header.

-l | This option places a read lock on the input Vision file. This improves performance, because the records can be read without needing to place and release locks on the individual records.
-t This tells vutil -unload to produce a file that has line sequential format. This means that the destination file is a simple text file, with records separated by line feeds.

This option implies -v (variable-length records), so the -v option is not necessary, although it is allowed.

If a record within the source file contains a newline character, a warning is displayed. Newline characters are used to signal the end of a record in line sequential files, and so continuing would result in partial/incomplete records. If you encounter the warning, you should unload to a binary sequential file (option -b) instead.

-q | This option causes vutil to exit (with status 99) if user interaction is required.
-r This option reads the records from the source file in the order that they occur in the data file, without using the index; the order of the records in the destination file is undefined.

Without this option, records are read in order according to the primary key or the key specified by the -k # option (if specified) as they are unloaded to the destination file. In a large file, reading all the records by the primary key can be slow if the actual record data is not generally ordered by the primary key.

If this option and the -k # option are both specified, the one that occurs on the command line last is the one in effect.

Note: This option is not effective when unloading Vision 3 files.
-k # This option specifies the key to be used to read the records as they are unloaded to the destination file. Substitute # for the actual key number.

Without this option, records are read in order according to the primary key, or the order that they occur in the data file if -r is specified.

If this option and the -r option are both specified, the one that occurs on the command line last is the one in effect.

Parent topic: Vision File Utility - vutil


Loading a File

The -load option creates an indexed file from a binary sequential file, a relative file, or a line sequential file. The command is:

vutil -load [-b|d|t] [-lnv(r|s)x] [-q] source destination

The source file is the name of the binary, relative, or line sequential file to read. The destination file is the name of the Vision file to add to. This file must already exist; it is used to determine the record size and key information.

By default, records from the source file are added to the destination file. If the -n flag (new file) is used, then any data in the destination file is eliminated before the records are loaded from the source file.

When doing a load, vutil places records that are rejected due to illegal duplicate keys into a file. Should this happen, vutil will report the name of the file that contains the rejected records. The format of this file is the same as a COBOL binary sequential file with variable-size records.

The input file is buffered according to the value in the A_SEQ_DEFAULT_BLOCK_SIZE variable. The variable must be set in the environment for vutil to use it. If the variable is not set, the default buffer block size is 4096 bytes. If the variable is set to "0", vutil -load into a sequential file will perform record-based I/O. If the variable is set to a positive value, that value will be rounded up to the power of two equal to, or greater than the value. This will be the buffer size in bytes. The maximum buffer size is 1GB.

By default, the source file is assumed to be a binary sequential file with an alternate format.

These are the source file format options:

-b | This loads a binary sequential file that is compatible with the ACUCOBOL-GT runtime into a Vision file. If -v is not present, fixed-length records are read. The -v option causes vutil to read variable-length records. The record length is stored in a two-byte record header.
-d | Records marked as deleted in the relative file are discarded. The -v option is not allowed for relative files.
-l | You can use the -l flag to prevent vutil from locking the file if you need to allow simultaneous access to the destination file while vutil is operating. Normally, vutil locks the destination file to improve the performance of the load operation. When -l is not used, vutil adds records to the file using "bulk addition" mode, which generally runs faster.
-n | If the -n flag (new file) is used, then any data in the destination file is eliminated before the records are loaded from the source file.
-q | This option causes vutil to exit (with status 99) if user interaction is required.
-r | This option causes any duplicate key write errors to be retried as rewrites to the file. This option should be used with caution, because duplicate key write errors often indicate that an error exists in the target file description. Warnings about this problem are not seen when you use the -r option. This option is incompatible with the -load -s option.
-s | This option indicates that duplicate records should be skipped rather than written to a file. When this option is used, any duplicate records found while loading the indexed file will be discarded. This option is incompatible with the -load -r option.
-t | This loads a file that has line sequential format into a Vision file. This means that the source file is a simple text file, with records separated by line feeds. The source file may not contain any line feeds within the data fields, because a line feed denotes the end of a record. This option implies -v (variable-length records), so the -v option is not necessary, although it is allowed. Line sequential files are assumed to contain variable length records. As such, they can only be loaded into Vision files that have been generated to accommodate the needed range of record sizes. If, however, the file contains records that are uniformly fixed length, the Vision file can be generated to accommodate only that fixed length. Should vutil attempt to load variable length records into a fixed record-size Vision file, an invalid record size error will occur. The error is reported as a generic parameter error.
-v | This option causes vutil to treat the source file as a file with variable-length records. The record length is stored in the record's header. The length of the header is either two or four bytes, depending on your machine type. If -v is not present, fixed-length records are read.
-x | The -x option is required when you are working with binary sequential and relative files that contain variable-length records larger than 65,535 bytes. (These files store the record length in two additional bytes in the record header. For "vutil -load" to read these files, it is necessary to indicate that these extra header bytes exist.)

If you are creating this file for the first time, you can either use the "gen" option of vutil or write a COBOL program to create the empty Vision file. The -load function can be used to import data from another application.

If an error occurs, an exit status of 255 is returned.

Parent topic: Vision File Utility - vutil


File Size Summary Report

The -size option of vutil gives summary disk usage information for a set of Vision files. This option is useful for quickly determining which files are occupying the most disk space and for spotting files that contain a large amount of unused space. The command is:

vutil  -size  [ -n ]  [ -q ]  [ files ]

If no files are requested, then the standard input is read for the list of files. The printed information includes the total size of the file, the number of records, and the number of deleted records the file contains. Also given is the percentage of records in the file that are not deleted records. This information is useful when you are trying to find candidates to rebuild when disk space gets tight. Non-Vision files are ignored by this command.

-n

This option shows all files, including non-Vision files. Although the vutil -size option normally ignores non-Vision files, sometimes it may be useful to see which files are being ignored. This option provides that capability.

Non-Vision files display as:

junkfile: not a vision file
-q This option causes vutil to exit (with status 99) if user interaction is required.
Parent topic: Vision File Utility - vutil


Converting RMCOBOL-85 Indexed Files

vutil can convert an indexed file created by RM/COBOL-85 into a Vision file. See Converting indexed files for more information.

Parent topic: Vision File Utility - vutil


Converting C-ISAM Files

vutil can convert a C-ISAM® file into a Vision file. This is useful when you are moving C-ISAM data to an ACUCOBOL-GT application. The command is:

vutil  -convert  [ -a ]  [ +c ]  [ -3456 ]  [ -d dir ]
                 [ -f # ]  [ -q ]  [ files ]

You need not specify that the file is C-ISAM; vutil makes that determination.

The -convert option starts with the same letter as the -check option. You must use at least two letters of the word "convert" in order to specify this option. If you just use -c, vutil will assume that you are specifying the -check option.

The -convert function will take each named file and convert it from a C-ISAM file to a corresponding Vision file. If no files are specified, then the standard input is read for a list of files to convert.

Each C-ISAM file actually occupies two files: an index file with the extension .idx and a data file with the extension .dat. Specify only the base name in the list of files (do not include any extension).

Specifying +c causes the resulting records to be compressed.

Normally vutil warns the user about the impending conversion and asks if the user wants to continue. The -a (for "automatic") option suppresses this warning. This can be useful when you are calling vutil from another program.

The -6 option specifies that you want the resulting file to be in Vision Version 6. The -5 option specifies that you want the resulting file to be in Vision Version 5. The -4 option specifies a Vision Version 4 file. A -3 means a Version 3 file.

The -d option specifies that you want the converted files to be placed in a new directory. dir should be the name of a directory on the machine other than the directory containing the files to be converted. The -d option implies the -a option.

The -f # option sets the compression factor to be used when the file is converted. This option does not force the use of compression, it merely sets the compression factor if compression is used. The compression factor, a numeric literal, specifies how much of the space saved by compression is actually to be removed from the record.

The -q option causes vutil to exit (with status 99) if user interaction is required.

There are a few types of files that cannot be converted due to restrictions in Vision. Any of the following properties will cause vutil to print a message and leave the file alone:

  • A record size or block size greater than 32 KB.
  • More than 120 keys.
  • An individual key with more than 250 bytes in it.
  • A single key with more than sixteen segments (Vision Version 4) or more than six segments (Vision Version 3).
  • A primary key that allows duplicates.

vutil makes a copy of the file while it is converting it. You must have adequate disk space for vutil to complete its conversion. Also, C-ISAM files and Vision files differ in the amount of disk space that they use. This difference is fairly unpredictable and can vary quite widely. Sometimes the Vision files are smaller, and sometimes the C-ISAM files are smaller. You should have some spare disk space when you start converting files to accommodate the potential difference.

Parent topic: Vision File Utility - vutil


Converting Micro Focus Files

Restriction: The conversion process is only supported for earlier Micro Focus indexed file formats (IDXFORMAT"4" and earlier).

vutil can convert a Micro Focus file into a Vision file. This is useful when you are moving Micro Focus data to an ACUCOBOL-GT application. The command is:

vutil  -convert  [ -a ]  [ +c ]  [ -3456 ]  [ -d dir ]
                 [ -f # ]  [ -q ]  [ mf-files ]

You need not specify that the file is a Micro Focus file; vutil makes that determination.

The -convert option starts with the same letter as the -check option. You must use at least two letters of the word convert in order to specify this option. If you just use -c, vutil will assume that you are specifying the -check option.

The -convert function will take each named mf-file and convert it from a Micro Focus file to a corresponding Vision file. If no mf-files are specified, then the standard input is read for a list of files to convert.

Each Micro Focus file actually occupies two files: an index file with the extension .idx and a data file. The resulting Vision file has the same name as the data file with the extension .vis. Specify only the base name in the list of files (do not include any extension).

Normally vutil warns the user about the impending conversion and asks if the user wants to continue. The -a (for automatic) option suppresses this warning. This can be useful when you are calling vutil from another program.

Specifying the -c option causes the resulting file to have uncompressed records regardless of the original file; using +c causes the resulting records to be compressed.

The -f option sets the compression factor used when the file is converted. This option does not force the use of compression; it merely sets the compression factor if compression is used. The compression factor, a numeric literal, specifies how much of the space saved by compression is actually to be removed from the record.

The -6 option specifies that you want the resulting file to be in Vision Version 6. The -5 option specifies that you want the resulting file to be in Vision Version 5. The -4 option specifies a Vision Version 4 file. A -3 means a Version 3 file.

The -d option specifies that you want the converted files to be placed in a new directory. dir should be the name of a directory on the machine other than the directory containing the files to be converted. The -d option implies the -a option.

The -q option causes vutil to exit (with status 99) if user interaction is required.

vutil makes a copy of the file while it is converting it. You must have adequate disk space for vutil to complete its conversion. Also, Micro Focus files and Vision files differ in the amount of disk space that they use. This difference is fairly unpredictable and can vary quite widely. Sometimes the Vision files are smaller, and sometimes the Micro Focus files are smaller. You should have some spare disk space when you start converting files to accommodate the potential difference.

Parent topic: Vision File Utility - vutil


Changing Record Size

The -augment option makes it possible to increase the maximum record size of a Vision file. This is useful for adding fields to a record without having to rebuild the entire data file. The new maximum record size and the file name is specified as shown in the examples below. This command format is:

vutil -augment [ -q ] new_max_rec_size filename

For example:

vutil -augment -q 50 myfile.dat

or

cat vision_filelist | vutil -augment -q 100

If the Vision file originally had a fixed-length record size, and if the new maximum record size is larger than the old maximum record size, the file effectively has a variable-length record size after running this command.

You may specify a new maximum record size that is smaller than the current maximum record size, but not smaller than the current minimum record size. This enables you to correct for the case that the maximum was too large. Be careful, however, because if any records were added while the maximum was at the higher level, the file is marked as broken when those records are next read. Vision detects that a record exists that is larger than the current (reduced) maximum record size and raises an error. When you use vutil -augment to reduce the maximum record size, vutil issues a warning.

Anytime you change the file record size with the -augment option, you should consider the need to modify existing FDs to reflect the new maximum record size. Changing the characteristics of a file without making changes to existing FDs will cause a mismatch to be detected at runtime when the file is opened, resulting in a file-status error 39 (Existing file conflicts with the COBOL description of the file).

Because this operation changes the logical structure of the file, exclusive file access is required. vutil reports File locked if any other process has the file open.

The -q option causes vutil to exit (with status 99) if user interaction is required.

Parent topic: Vision File Utility - vutil


Setting the Comment Field

The -note option allows you to set the comment field in the Vision file header.

The usage is:

vutil -note [-q] "comment" [file ...]

-q | causes vutil to exit (with status 99) if user interaction is required
"comment" | is limited to 30 characters and is truncated if longer

vutil -note sets the comment field in the specified Vision file to comment. If no file is listed on the command line, the filenames are read from standard input (one per line).

A Vision file's comment field can be viewed with the vutil -info command. If the field is not empty, the comment is displayed, enclosed in parenthesis, on the line immediately following the filename.

Parent topic: Vision File Utility - vutil


Testing for Vision File Locking Compatibility

The V_LOCK_METHOD configuration variable specifies the locking method for Vision files. When V_LOCK_METHOD 2 is set, the 'asynchronous reads' method is in effect, which can improve performance by reducing the number of locks required.

However, in order to use this setting, your file system must be able to perform atomic file operations. Not all environments are capable of this, and so if you want to set V_LOCK_METHOD 2, you should run the following test to ascertain if your file system is compatible with this setting.

CAUTION:
If you set V_LOCK_METHOD 2 on a system that cannot process file operations atomically, this will more than likely result in spurious file errors or file corruption.

The command syntax is:

vutil -wtest /path/to/file test-duration

Specify an existing directory on your file system, in which a temporary Vision file is created for the duration of the test. The test-duration is the length in seconds that the test will run; if you omit this argument or specify less than 30, the test will run for the default 30 seconds.

During the test, blocks of characters are written to the temporary file and read back in a separate thread until either the indicated time elapses or an inconsistent read is encountered. A message will then be displayed showing the results of the test.

If the test passes, this indicates that the system did not allow the thread reading the data to see the data in an intermediate state, and thus V_LOCK_METHOD 2 can work reliably in this environment.

If a block is read that contains inconsistent data, this indicates that the file system does not ensure that data written in a single system call can always be read back consistently, and intermediate results may be seen. In this case, V_LOCK_METHOD 2 cannot operate reliably, and must not be used.

Note: The file system type and its mount options may affect the results of this test: different file systems on the same system may produce different results. Ensure that you run this test on the file systems that will hold the Vision files that are to be accessed using the V_LOCK_METHOD 2 configuration.
Parent topic: Vision File Utility - vutil
Related reference
V_LOCK_METHOD


Miscellaneous Commands

The -tree option produces a listing of the internal B-tree in a file called v_tree. The command is:

vutil  -tree  [ -q ]  file

This is primarily used by Micro Focus staff to help debug suspected problems with Vision. Five columns of information are displayed, with these headings:

Left/Rec Uniq Size Pre Key

The Left/Rec column displays the pointer from the entry to the next tree level or to the actual record itself. The Uniq value is used to distinguish duplicated keys. The Size field is the number of bytes in the key (as stored after key compression). The Pre field is the number of bytes this key shares with the preceding key. The Key field is the actual key value.

The -version option of vutil tells you which version of the utility you are running. The command is:

vutil  [ -q ]  -version
-q This option causes vutil to exit (with status 99) if user interaction is required.
Parent topic: Vision File Utility - vutil


Default Settings of vutil

vutil uses the following default settings:

V_BUFFERS | 128 blocks (1 block = 512 bytes)
V_BULK_MEMORY | 1 megabyte

You can modify these settings if desired by placing the new settings in the operating system's environment.

Note: vutil does not use the runtime's configuration file. Settings made there have no effect on vutil.
Parent topic: Vision File Utility - vutil


File Transfer Utility - vio

vio is a file transfer utility similar to the UNIX program cpio. vio allows you to collect a group of files together into archives, and allows you to extract some or all of these files from these archives. Typically, an archive is some external media such as a tape or a diskette, but the archive may also be another disk file. vio is typically used to back up a set of files or to move files from one machine to another.

vio is particularly well suited for moving files to a different machine, because:

  1. vio is available on a wide-range of operating systems, including Windows, UNIX, Linux, and VMS.
  2. vio automatically adjusts for certain machine-dependent aspects such as byte-swapping.
  3. vio handles multiple volumes gracefully.
  4. On any system where Vision is supported, vio can automatically convert ACUCOBOL-GT indexed data files to the appropriate format for the target machine.

vio runs in two modes, the input mode (-i) and the output mode (-o). The syntax for each mode, with all possible options, is shown here:

vio -o [ -b ] [ -f file ] [ -u ] [ -g ] [ -h headerfile ]
       [ -k ][ -l listfile ] [ -pr ] [ -s  blocks ] [ -v ]

vio -i [ -cd ] [ -f file ] [ -g ] [ -h bytes ] [ -kmnstv23456 ]  [ files ]

The input mode reads vio archives to extract files. The output mode creates new vio archives.

In the output mode, vioreads its standard input for a list of files to place in the archive. The archive is written to its standard output.

In the input mode, vio reads the archive from its standard input and extracts all the files. The extracted files have the same names, permissions, and owners that they had when the archive was created.

If files are specified, then only the named files are extracted. Note that each file must exactly match the name of a file in the archive; no wild card characters are allowed.

When vio encounters an ACUCOBOL-GT indexed data file, it treats that file specially. When it's running in output mode, it extracts each data record from the file and writes that record to the archive along with some formatting information. When that file is later read in the input mode, a new indexed data file is created with the proper format, and each data record is loaded into the file using the host's indexed file system. Using this technique, vio is able to transfer an indexed file so that it is ready for use on the target machine.

When it's archiving files other than indexed files or ACUCOBOL-GT object files, vio assumes that the files are text files. It performs any conversions necessary to match the text file conventions on the host machine. For example, if a file is transferred from a UNIX system to a Windows system, new-line characters are translated into carriage-return, line-feed sequences. The -p option described below can cause these files to be treated as binary files instead, in which case no translation occurs. (If you are transferring multiple files at one time, some ASCII and some binary, do not use the -p option. Instead, add a space followed by a b or a B after the name of each binary file in the filename list. The <space> b prevents translation from occurring on an individual file.)

Note: ACUCOBOL-GT object files are automatically detected and written out to an archive as binary files, even if you fail to specify -p.
  • vio Options
  • Windows Considerations
  • vio Examples
  • Known Limitations
Parent topic: Debugger and Utilities
Parent topic: Utilities


vio Options

The following options can be used with the vio utility:

-b | Causes the archive to be blocked with 10 input records per output record. Each input record is normally 512 bytes. Blocking is specified only during output; vio automatically determines whether or not an archive is blocked when it is doing input.
-c | Forces all files read from the archive to be placed in the current directory. Any directory information in each file is removed and the file is placed in the current directory using just its base name. This is useful if someone sends you a file with a full directory specification that does not match your machine.
-d | Allows vio to create directories as needed to read a file.
-f | Allows you to specify the archive file directly. The next separate command-line argument is the name of the archive file. This is particularly useful when you are writing a multi-volume archive, because vio will not need to prompt you for the name of the archive when it has to change volumes.
-g | Rings the bell when a new volume is needed.
-h In the input mode, you may specify a number of bytes to skip from the beginning of each archive volume. This value is specified as the next separate argument. This is used to skip headers on media that some machines produce.

In the output mode, the next separate argument should specify the name of a file. This file is exactly copied to the beginning of each archive volume. This is used to simulate a media header required by a target machine.

For example, an AT&T 7300 diskette contains a header in the first 8 sectors. If you write a diskette on another type of machine, the 7300 will not recognize it. To get around this problem, take a diskette written on a 7300 and extract the header using this UNIX command: dd if=disk-device of=73header count=4096. You can then specify -h 73header as part of a vio command to have this header placed on each diskette of the archive. The 7300 will then be able to read these diskettes. If you are coming from a 7300, you can use -h 4096 to cause vio to skip the first 8 sectors of each diskette.

-k | Changes vio's notion of a record size from 512 bytes to 1024 bytes. All I/O is done using the record size, or a multiple of the record size. This option is occasionally useful on some machines that require 1KB transfers to devices. If you use this option on output, you must then also use it when reading the created archive. This option should be used only if required. You can improve performance better by using the -b option instead.
-l Allows you to specify a list of files to output as the next command-line argument. vio will then read this list instead of using its standard input. Note that this list must reside in a file, one line per entry.

An optional flag (<space> b or <space> B) may be placed after the filename. This specifies that the file should be written to the archive without translation (same as the -p option, except -p applies to all non-indexed files in the list).

For example, if the file list contains two lines file1 and file2 b, then specifying -l list will cause file1 and file2 to be written to the archive, with file2 written as a binary file. This option is useful on machines that do not allow standard input to be redirected.

-m | Causes vio to restore the file's modification time from the archive along with the other file attributes.
-n | Causes vio to assign a new owner (the current user) to extracted files. This is particularly useful when you are transferring files to another machine, because the original user ID is probably not meaningful in this case.
-p | Causes non-indexed files to be treated in a pure (binary) form. This prevents any text file conversion from occurring. vio stores its archives in a standardized format (similar to a UNIX text file). When it's creating archives, it converts any non-indexed file to this format unless this option is specified. (This option applies to all non-indexed files in the list and thus behaves as if you had specified "<space> b" for every non-indexed file in the list, even if you did not.)
-r | Causes indexed files to be treated as raw data files. No conversion is done when the file is written to the archive. This should be done only if the archive is going to be read by a binary-compatible indexed file system. Note that all Vision Version 6, 5, 4, and 3 files are binary-compatible, so you can use this option to move Vision 6, 5, 4, and 3 files. Specifying this option will speed up vio, so it is a reasonable option to use if you are doing backups.
-s In the output mode, this allows you to specify the size of the media. This is useful on a few machines that do not detect end-of-media correctly. The size is specified as the next command-line argument. This should be the number of blocks to place on the media. Normally, a block is 512 bytes, but the -k option causes blocks to be 1024 bytes in size. vio will not place more than this many blocks on the output media before changing volumes. For example: -s 2400 could be used to store 2400 blocks per diskette.

In the input mode, this option allows you to skip volumes. This is useful if vio dies due to a media error and you want to recover files on successive volumes. This option causes vio to start with whichever volume it finds physically mounted.

-t | Causes vio to print the titles of the files in the archive rather than extracting the files. If this is specified with the -v option, long information is printed about each file.
-u Causes vio not to do a translation of filename directory separators.

vio by default changes all filenames to use forward slashes as directory separators. This is done to avoid problems in cases when an archive is made on a Windows machine with filenames that use backslashes (\), and then extracted on a Unix machine. The files extracted would not be stored in directories, but would instead be created with the backslashes in the names, causing problems for the user who had to work with these files.

For example,

vio -ovbulf listfile archive.vio

causes vio to not translate any backslashes in filenames listed in listfile to forward slashes. Similarly,

vio -ivnduf archive.vio

causes vio to not translate any backslashes in filenames in the archive to forward slashes.

Windows versions of vio handle forward slashes just fine; you do not need to use the -u switch on those systems to have your filenames interpreted correctly. The main purpose of providing this switch is backwards compatibility.

-v | Causes vio to be verbose about its progress. Note that when it's extracting files from an archive, vio prints each name as it starts to work each file. If vio dies for some reason, the last name printed will not have been completely extracted.
-3 | Specify this option when you are reading an archive and want to produce an indexed file in Vision Version 3 format, rather than Version 6 file (the default).
-4 | Specify this option when you are reading an archive and want to produce a Vision Version 4 file.
-5 | Specify this option when you are reading an archive and want to produce an indexed file in Vision Version 5 format.
-6 | Specify this option when you are reading an archive and want to produce an indexed file in Vision Version 6 format (the default).

vio recognizes UNIX-style names on non-UNIX environments. For example, if you specify the name ../demo/compfile on a VAX system, vio will treat this name as [-.DEMO]COMPFILE.. For this reason, you should use UNIX-style names if you want to move directory structures between machines with different operating systems.

Parent topic: File Transfer Utility - vio


Windows Considerations

When you are using vio on an Windows machine, you can specify a diskette drive with the -f option. If you do this, you must specify the type of diskette you want to write. Specify one of the following letters immediately after the drive-name's colon:

H | 1.2 MB High-density 5.25"
3 | 1.44 MB High-density 3.5"
9 | 720 KB, 9-sector, low density 3.5"
8 | 320 KB, 8-sector, low density 5.25"

If you leave this letter off, vio will assume a low-density, 360 KB diskette (which can be either 3.5" or 5.25").

You may not specify a diskette drive with redirection. If you write directly to a drive, all pre-existing files on that drive are lost. In addition, all directory information is lost. In addition, the diskette will not be usable by Windows until it is reformatted.

Parent topic: File Transfer Utility - vio


vio Examples

Suppose that you have a list of files that you want to move to another machine using some compatible media. You could use the following vio command to create the media:

vio -ovblf listfile device

For each line inside the listfile there cannot be any spaces before or after the file name. The correct form for this file is:

filename(newline)
filename(newline)
filename(newline)

Do not include lines with spaces (initial or in the middle), such as:

filename  (newline)

or with leading spaces, such as:

   filename(newline)

On the target machine, you can read the archive you just created with:

vio -ivndf device

You could read this on a Windows machine with:

vio -ivndf a:h

Now let's assume that you want to move a set of Vision indexed files to another machine, but you do not have any common media. You plan to use a network or modem-transfer to get the files to the target machine, but you have a problem because the indexed file format on the two machines is different. You can use vio to help you in this case by writing the archive to a disk file with this command:

vio -ovblf listfile diskfile

The listfile must not have spaces before or after the file names.

Then you move diskfile to the target machine and use vio to create new indexed files in the correct format with this command:

vio -ivndf diskfile
Parent topic: File Transfer Utility - vio


Known Limitations

If you attempt to write to a write-protected diskette on a Windows system, vio incorrectly believes that 10 records are written to the diskette, and then it prompts for a new diskette. When this happens, the archive is incorrect and you must start over. Reading from write-protected diskettes works correctly.

vio will transfer indexed data files to/from VMS, but it will not convert them. If you must do this, you will have to unload and reload the records yourself.

On VMS, the -n option is always implied.

Be careful when using full path names. Some operating systems do not translate them in the way you might expect. You should always use relative path names when transferring files to a different operating system. Always make sure you have permissions to create files, and subdirectories if necessary, when you are transferring archives.

When using the -s option, you can suggest up to a maximum of 99999 blocks. This number corresponds to 50 MB if the block size is 512 bytes, and 100 MB if the block size is 1024 bytes.

Parent topic: File Transfer Utility - vio


Indexed File Record Editor (alfred)

As of Version 8.0, the Indexed File Record Editor (alfred) is provided as a sample program and is located in the sample folder under AcuGT. You can download detailed information on using alfred in PDF format from the Support > Examples and Utilities > ACUCOBOL-GT® Technical Articles and Tips page on the Micro Focus Web site (www.microfocus.com).

Parent topic: Debugger and Utilities
Parent topic: Utilities


logutil

You can use the utility program logutil to examine and edit an ACUCOBOL-GT transaction log file. This utility is used only with log files built for the Vision file system. You can run logutil from the operating system command line with the following usage:

  • Syntax and Options
  • logutil Report Headings
Parent topic: Debugger and Utilities
Parent topic: Utilities


Syntax and Options

Syntax

logutil  [ -filv ]  [ -d begin_date  [ end_date ] ]
  [ -t begin_time  [ end_time ] ]  [ -u user ]
  [ -r begin_location  [ end_location ] ]  [ -h num ]
  [ -e new_log_file_name ]  log_file_name

Options

-f | full listing, lists selection on standard output (implies -i).
-i | prints summary information at end of listing.
-l | report location information.
-v | verbose option, includes record images (implies -f).
-d | limits selection by date.
-t | limits selection by time. Uses 24-hour clock.
-u | selects transactions for a particular user only.
-r | selects transactions within the two locations you provide
-h | num is the frequency with which header lines will be printed.
-e | extracts selected section into a new log file.

If you do not specify any options on the command line, logutil acts as if -i were specified and prints only summary information.

Record Image:

0015  0001  2ce2  dffc  0000  55dd0000  646f  ...,.....U...do
7669  6400  6163  7563  6f62  6f6c      00    vid.acucobol.

logutil may be used to monitor transaction log activity. If you run it with only the -i option, or with no options, it sends a summary report to standard output. This report contains statistics, version information, and warning messages. One or both of the two warning messages below may appear, as shown in the following report:

logutil corruptlog
Log File                 :   corruptlog
WARNING: COMMIT BEGIN WITHOUT MATCHING COMMIT END IN LOG FILE
WARNING: START TRANSACTIONS WITHOUT MATCHING ROLLBACKS
   OR COMMITS
Total Size               :   2366 bytes
Number of Records        :   79
Mean Record Size         :   29 bytes
Number of Transactions   :   17
Mean Transaction Size    :   139 bytes
Record Version(s)        :   1

The warning COMMIT BEGIN WITHOUT MATCHING COMMIT END IN LOG FILE means that the last record in the log file is not a type CE (Commit End) record. This means that, during a commit:

  • the log file was being updated at the time logutil was run
  • or a process was killed with an uncatchable signal
  • or a system failure occurred

In the case of a killed process with an uncatchable signal, or a system failure, the next START TRANSACTION using the corrupted log file will return TRANSACTION-STATUS 12.

The warning 2 START TRANSACTIONS WITHOUT MATCHING ROLLBACKS OR COMMITS means that there are two transactions that have yet to be committed or rolled back. This could indicate a problem if there are no runtime processes currently using the log file.

The logutil utility date filter, -d command-line option, requires you to specify years in the 4-digit format. If you enter a year value less than 1900, logutil reports logutil: use 4 digit year specification.

Examples

To list all records for a user named randy that were written on November 11th between 4:50 P.M. and 5:00 P.M. to a log file called mylog, you would use the following command:
logutil -fu randy -d 11/11 -t 16:50 17:00 mylog

You will see something similar to the following report:

TY  PID     Term  Client    User   Date/Time       File ID   Filename
ST  21981   tty0  acucobol  randy  11/11 16:50:12
CB  21981   tty0  acucobol  randy  11/11 16:50:12
MA  21981   tty0  acucobol  randy  11/11 16:50:12            test.dat
OP  21981   tty0  acucobol  randy  11/11 16:50:12  07700001  test.dat
CE  21981   tty0  acucobol  randy  11/11 16:50:12
ST  21981   tty0  acucobol  randy  11/11 16:56:40
CB  21981   tty0  acucobol  randy  11/11 16:56:40
WR  21981   tty0  acucobol  randy  11/11 16:56:40  07700001
DE  21981   tty0  acucobol  randy  11/11 16:56:40  07700001
CE  21981   tty0  acucobol  randy  11/11 16:56:41
ST  21981   tty0  acucobol  randy  11/11 16:59:20
CB  21981   tty0  acucobol  randy  11/11 16:59:20
WR  21981   tty0  acucobol  randy  11/11 16:59:20  07700001
RE  21981   tty0  acucobol  randy  11/11 16:59:21  07700001
CE  21981   tty0  acucobol  randy  11/11 16:59:21
-
End of log.
Total Size               :   580 bytes
Number of Records        :   15
Mean Record Size         :   38 bytes
Number of Transactions   :   3
Mean Transaction Size    :   193 bytes
Record Version(s)        :   1

In a transaction log report, path and file names are limited to 17 characters without the -l option, or 21 characters with the -l option. Should the path and file name exceed that limit, the report will attempt to display all of the file name. If room permits, this will be followed by the file's parent directory, root directory, and subdirectories. Path name components that must be omitted are represented by an ellipsis (...).

To create a new log file called newlog that will contain the records reported above, use the -e option as follows:

logutil -u randy -d 11/11 -t 16:50 17:00 -e newlog mylog
Parent topic: logutil


logutil Report Headings

The first column of the standard report has the heading TY. Its value is the record type, taken from the following list:

ST | Start Transaction
CB | Commit Begin
CE | Commit End
RO | Rollback Transaction
DE | Delete (record)
RW | Rewrite
WR | Write
OP | Open (Opens an existing file)
MA | Make (Creates or Recreates a file during an OPEN operation)
CL | Close
CP | Copy
RN | Rename
RM | Remove (file)

The other columns are as follows:

PID | ID of process which wrote the record
Term | Name of terminal used by the runtime
User | User name of owner of the runtime
Client | Host name of machine running the runtime, the client machine when using AcuServer
Date/Time | Date and Time the event occurred
File ID | Unique identifier of the file
File Name | Name of file being opened, created, recreated, deleted, renamed, or copied

The PID is usually less than six characters on UNIX machines. On Windows, however, the PID can be a long negative number. In order for the output file to fit within 80 columns, all PID numbers are truncated to show only the right-most six characters.

If the -l option is used:

Location | Byte offset of the record in the log file
Length | Length of the log record
Parent topic: logutil


The Profiler

To help you tune application performance, the runtime includes an execution profiling facility. This built-in facility is activated when a properly prepared program is executed with the -p flag, prompting the runtime to collect information about I/O operations and CALLs, and to install a timer to track the amount of time spent in different parts of the code. All of this information is placed into an output file called acumon#.xml. (The # is an automatically incremented number, starting at 1, appended to the filename to ensure that the profile data is not accidentally overwritten by another execution of the profiler.)

Note: Because the runtime performs a linear search to determine the next available filename to use, if a directory contains a large number of profiler output files, the search can take some time. For this reason, it is a good idea to remove unneeded XML profiles regularly.

The raw data in acumon#.xml can be processed by the acuprof utility to create a text-based performance report, acumon.rpt. In all environments, the report summarizes the amount of processor time used by each program in an application and each paragraph in a program, as well as detailing the file I/O operations performed by each program. When the acumon#.xml file is created by a UNIX/Linux runtime, the final report also contains information about the amount of user time spent in each program and paragraph.

  • Using the Profiler
  • Configuring the Profiling Tools
  • Understanding the Report
  • Understanding the XML Data File
Parent topic: Debugger and Utilities
Parent topic: Utilities


Using the Profiler

The profiler is optimized for batch programs, and is especially useful with batch programs that run large numbers of transactions. It is more difficult to get good information from interactive programs. If user wait times are the issue you're trying to solve, trace files are more likely to return useful information than the profiler.

When you prepare to use the profiler, you should make an effort to run your application as cleanly as possible. This means making sure that your system isn't overloaded with large numbers of users, heavy system traffic, and so on. The cleaner the run, the more useful the information returned by the profiler.

The following steps describe how to perform profiling using default profiler and acuprof behavior.

  1. Compile your COBOL programs for debugging.

    You must compile with at least the -Gy option (to include at least minimal symbol information in the object file) for the profile to contain paragraph information. It is preferable to compile for full symbol information (-Gs) or for full source debugging (-Gd).

  2. Execute the program with the -p runtime option to create the acumon1.xml file.

    If a file called acumon1.xml already exists in the program directory, the profiler automatically changes the file name to create a file called acumon2.xml, acumon3.xml, and so on. This is intended to make it easier to compare multiple profiles of the same program.

    Note that the automatic naming scheme uses the first unused number when naming the file. This means that if a directory contains files called acumon1.xml, acumon2.xml, and acumon6.xml, the next profile created in that directory is called acumon3.xml.

  3. Use the command runcbl acuprof -a pathname (where pathname is the full path and file name of the XML file created by the profiler) to launch acuprof and process the profiler data.

    By default, acuprof creates a report file called acumon.rpt in the execution directory, then displays a message to indicate that the report was created successfully.

  4. Click OK to end acuprof execution, then open the newly created report file in the text editor of your choice.
Parent topic: The Profiler


Configuring the Profiling Tools

Using a combination of runtime flags, acuprof flags, and configuration variables, you can customize the behavior of both the profiler and the acuprof utility. This section describes the various configuration options.

  • PROFILE_TYPE Runtime Configuration Variable
  • Configuring Profiler Behavior
  • Configuring acuprof
Parent topic: The Profiler


PROFILE_TYPE Runtime Configuration Variable

This configuration variable provides an optional method of profiling ACUCOBOL-GT on Windows called COUNTER. The counter method uses the debugger to perform counting and appears to provide the most accurate results in Windows environments.

Set the PROFILE_TYPE configuration variable to either ASYNCH or COUNTER. When set to the default value of ASYNCH, the runtime performs profiling the way it historically has. When set to the value COUNTER, the runtime uses this method of profiling. Note that your COBOL programs must be compiled with -Gd as well as -Gs options to use the counter method.

The counter method is also available on UNIX and can be used if profiling your COBOL results in a message similar to profile timer expired. This method doesn't completely solve that problem, but does substantially mitigate it.

Parent topic: Configuring the Profiling Tools


Configuring Profiler Behavior

In order to reduce file size and processing time for the acumon#.xml file, the profiler does not create records for paragraphs that have a zero execution count and zero execution time. If you would like to have these zero count paragraphs recorded, use the -p0 option instead of -p.

To specify a name other than acumon#.xml for the XML output file, use the configuration variable ACU_MON_FILE. This variable also takes the following specifiers for adding additional information to the name:

%p | If the name contains the string %p, that string is replaced with the process ID (PID) of the runtime.
%d | If the name contains the string "%d", that string is replaced with the current date in the form YYYYMMDD where YYYY is the year, MM month and DD day.
%t | If the name contains the string %t, that string is replaced with the current time in the form HHMMSSTTT where HH is the hour, MM minute, SS second and TTT milliseconds.
%u | If the name contains the string %u, that string is replaced with the username.
%h | If the name contains the string %h, that string is replaced with the hostname.

For example:

ACU_MON_FILE profile%p.xml

would produce a file called something like profile314.xml, where 314 is the runtime process ID.

Parent topic: Configuring the Profiling Tools


Configuring acuprof

The acuprof utility takes the following flags:

Flag | Description
-a or --call-name | If you have specified a name other than acumon#.xml for the profiler output file, use this flag to pass the correct name to the acuprof utility.
-o or --output | To give the report file a name other than the default, acumon.rpt, use this flag.
-c or --sort-count | Sort data in the report file by the entry count for each program and paragraph. (By default, the report is sorted by time.)
-n or --sort-name | Sort data in the report file alphabetically by program and paragraph name. (By default, the report is sorted by time.)
-q or --quiet | This flag is used to suppress the report complete message used to indicate that acuprof has run successfully.

For example:

runcbl acuprof -a profile.114 -o report.114 -n

Here, acuprof parses a profiler output file called profile.114 and produces a report called report.114, sorted by program and paragraph name.

Parent topic: Configuring the Profiling Tools


Understanding the Report

The report is divided into three sections:

  1. The first section contains general information about when the program was run, which version of the runtime was used, and general system capabilities.
    Profile run on Fri Feb 06 10:05:15 2006, sorted by name
ACUCOBOL-GT version 8.0.0 (2006-05-10)
Timer interval = 10.029 milliseconds

    Note that the runtime uses the best timer that it can get from the system, which generally means an interval around ten milliseconds (100 ticks per second). As a result, it's best to run the application for at least ten seconds (not counting time waiting in an ACCEPT loop for user interaction) to get a useful number of data points.

  2. The second section contains information about the programs executed.
       Pct       Secs     Count      I/O   Program
========================================================
   36.7%      8.35    57927        0   PDM0425
   32.8%      7.47        1    38950   TRP140
   15.2%      3.46    41947        0   TRA050A
   14.2%      3.24    57927        0   TRS130B
    0.7%      0.15        2        8   PCM1800
    0.3%      0.07       14       15   TRZCG01B
    0.0%      0.00        1        0   PCM1520

    This condensed information gives you an easy way to see which programs to focus your attention on. In general, you will want to start by tuning the programs in which the most time is being spent. Because this example was generated on a Windows system, it doesn't show a comparison of system time (time spent performing I/O operations and doing memory management) and user time (time spent in the application, running PERFORMs, etc.). On UNIX systems, this additional information is included and can be used to help you figure out where to focus.

  3. The third section (which contains the bulk of the information in the report) has information about the paragraphs executed by each program.

    In this section, the paragraph totals are per program, not per application, so the total for all paragraphs in each program should add up to 100%.

    TRP140

    Opens:         1
    Reads:         38949

 Pct       Secs    Count    Total   Paragraph
======================================================
52.1%      3.89    41947     17.1%  Z70-CALL-TRA050A
40.5%      3.03    38949     13.3%  Z10-READ-FTR013A
 5.6%      0.42    38948      1.9%  B20-PROCESS-ECR
 0.5%      0.04     2996      0.2%  B20-PROCESS-EO
 0.4%      0.03       14      0.1%  Z40-CALL-TRZCG01B
 0.3%      0.02        1      0.1%  A00-MAINLINE
 0.3%      0.02        1      0.1%  A10-DEBUT-PROG
 0.3%      0.02        0      0.1%  Z99-END

    In most COBOL programs, one or two paragraphs use the lion's share of the time. There may be another paragraph or two that takes up a moderate amount of time, but most paragraphs use a very small percentage of the total program time.

    Note that you may find very small paragraphs (like the EXIT paragraph) getting a very large number of counts (CALLs). Because the time spent counting each CALL is added to the paragraph time, it may appear that such paragraphs are taking a large amount of time, when in fact the behavior of the timer is artificially inflating the paragraph time.

Parent topic: The Profiler


Understanding the XML Data File

The acuprof utility takes the raw data in acumon#.xml and combines the individual data points to create useful aggregates in the report file. acuprof is an ACUCOBOL-GT program that is located in the tools subdirectory.

Because acumon#.xml is a straightforward XML file, any tool that can parse XML can parse the raw report. This means that you can bring the report into recent versions of Microsoft Excel, for example, or create your own parsing tool using the C$XML routine to return the information most useful to you.

This section contains the basic information that you need to understand the data collected in acumon#.xml.

The "ticks" timer

In the final report, program time is reported in seconds, or fractions of a second. The raw XML file, however, counts user and processor time in ticks. The length of a tick is system-dependent, but usually equals about 10-milliseconds. The precise amount of time in each tick is reported at the beginning of the XML file (as described later). Each time the timer starts, the runtime examines the current program location and records a tick for the current program and current paragraph. By looking at how many ticks a program or paragraph accumulates, you get a real-time sampling of where the run spent its time.

If a program is running multiple threads and there is only one timer, when the timer expires, a tick is given to the current program and current paragraph, regardless of which thread is running.

The time runs in process time on machines that support the concept (UNIX). Process time is CPU time spent for the particular process and bears little relationship to real time. On older machines (Windows NT), a real-time timer is used instead. For these machines, it is important to run as few other tasks as possible while collecting profile data.

  • Structure of the Raw Report File
Parent topic: The Profiler


Structure of the Raw Report File

The structure of the XML file is similar to that of the final report. It contains general information about a specific execution of the application, followed by information about each program and each paragraph in the program. Because, however, the XML file contains raw data instead of aggregate information, it is more useful to think of the file as divided into levels rather than sections. The top level (outermost set of XML tags) contains general execution information. The next level (middle set of XML tags) contains program information. The last level (innermost set of XML tags) contains information about paragraphs in each program.

  • The Runtime Level
  • The Program Level
  • The Paragraph level
Parent topic: Understanding the XML Data File


The Runtime Level

The following table defines the HTML tags at the runtime level.

<Runtime-Version> | Shows the version number of the runtime used by this particular profiling run. The value is the full version number (including any information seen in runcbl -v such as build dates or patch numbers).
<Run-Date> | Marks the date and time of the run that produced the profile data.
<Has-Timer> | Is set to 1 if the runtime has support for profiling timers, 0 if not. If support is not available, the various ticks fields below will all be zero. Currently, timer support is available under Windows NT and UNIX machines that have setitimer and siginterrupt routines.
<Usecs-Per-Tick> | Contains the number of microseconds represented by each tick of the timer. The runtime normally asks for a 10-millisecond timer (a value of 10000 for this field).
<User-Time-Msecs> | When available, this tag shows the number of milliseconds of CPU time spent processing user code for this run.
<System-Time-Msecs> | When available, this tag shows the number of milliseconds of CPU time spent processing system code on behalf of the profiled process.
Parent topic: Structure of the Raw Report File


The Program Level

The <Program> tag marks the root of a subtree of information for each program used by the profiled run. Each time a program leaves memory, it produces one of these subtrees. Because of this architecture, a particular program can appear in the acumon#.xml file more than once.

If a particular program appears many times in a run, it may be getting canceled too often. This can present performance issues, because each cancel causes the program to be reloaded from disk the next time it is called.

Each program sub-tree contains the following tags:

<ProgramName> | Contains the program's ID.
<Call-Name> | Shows the name the program was called by. This is useful if more than one program has been given the same program ID.
<Object-Code> | Gives the name that describes the object code instruction set. The name AcuCode is used for machine-independent object files. If the object was compiled for native code, the name of the relevant CPU type is given.
<Call-Count> | Indicates the number of times this program was entered.
<Program-Ticks> | Shows the number of times the timer went off in this program. Time spent waiting for the user to respond is counted only on Windows NT systems.
<Has-Symbols> | Is set to 1 if the program was compiled for debugging and had section/paragraph symbols available. When this is 0, no paragraph data is included for this program.
<File-Opens> | Lists the number of times this program opened any file using the OPEN statement or I$IO. Note that this counts opens, not files (so if you open the same file ten times in the course of a run, that counts as 10 and not 1). Some machines open files much more slowly than others, so a large number here usually suggests a potential performance issue.
<File-Reads> | Lists the number of record read attempts. READ, READ NEXT, and READ PREVIOUS all count here and are not distinguished.
<File-Writes> | Indicates the number of records written.
<File-Rewrites> | Gives the number of records rewritten by the program.
<File-Deletes> | Shows the number of records deleted by the program.
<File-Starts> | Lists the number of file positions made using the START statement or the I$IO subroutine. Note: Note: Attempted reads, writes, rewrites, deletes, and starts that failed are counted along with the successful file operations
<File-Commits> and <File-Rollbacks> | Show the number of COMMIT and ROLLBACK statements performed by the program, regardless of outcome.
<Records-Sorted> | Gives the number of records sorted by this program via the SORT statement.
Parent topic: Structure of the Raw Report File


The Paragraph level

<Paragraph> indicates the root of a subtree of information about a paragraph contained in the program. If the program has been compiled with debugging, there will be one of these for each Procedure Division section or paragraph in the program.

Each paragraph sub-tree contains the following tags:

<Name> | Gives the name of the paragraph or section. This appears in uppercase, regardless of the case seen in the actual source code.
<Count> | Shows the number of times this paragraph was entered, by any means.
<Ticks> | Indicates the number of times the timer went off while in this paragraph. Time spent waiting for the user to respond is counted only on Windows NT systems. Time spent in between paragraphs or programs may count for either the caller or the called routine, depending on the timing.
Parent topic: Structure of the Raw Report File


External Sort Utility AcuSort

The AcuSort utility enables you to sort or merge Vision indexed, relative, binary sequential, and line sequential files. An alternative to using the SORT verb, this external sort function is invoked from the command line. AcuSort instructions may appear directly on the command line, or they may be included in a separate text file. See Procedure Division Statements for details on the SORT verb.

  • AcuSort Command Format
  • AcuSort Instructions
  • AcuSort Code Sample
  • AcuSort Environment Variables
Parent topic: Debugger and Utilities
Parent topic: Utilities


AcuSort Command Format

You can specify AcuSort instructions in one of two ways. You can include them on the AcuSort command line, as follows:

acusort parameters

where parameters are the various AcuSort utility options that control such operations as SORT and MERGE. This format is appropriate if you want to execute a simple sort with few parameters. Note that if you choose this method, you must ensure that the command line size and contents do not violate any operating system or shell limits.

If you need to execute a sort that is often repeated or one with a large number of options, you may find it easier to store and use sort instructions in a text, or take, file. In this case, the AcuSort command line format is

acusort take filename

where filename is the file that contains the options to use when AcuSort is executed.

The take file would contain all the instructions for your sort or merge process. The text file may also contain comments (indicated by an asterisk at the beginning of a line). An example of a take file appears in AcuSort Code Sample.

Specifying the -v option on the AcuSort command line as shown below causes the utility to display version and copyright information.

acusort -v
Parent topic: External Sort Utility AcuSort


AcuSort Instructions

Several options are available for use with the AcuSort utility, including various instructions to sort or merge files, specify the name of an input or output file, or define conditions under which certain records are included or excluded from a sort or merge process. An exit status of zero indicates success; non-zero indicates failure.

The following sections provide details on these functions. See AcuSort Code Sample, for AcuSort sample code.

  • CHAR-ASCII and SIGN-ASCII
  • CHAR-EBCDIC and SIGN-EBCDIC instructions
  • SORT/MERGE Instructions
  • USE/GIVE instructions
  • INCLUDE/OMIT Instructions
Parent topic: External Sort Utility AcuSort


CHAR-ASCII and SIGN-ASCII

The CHAR-ASCII instruction tells AcuSort that the data should be interpreted as ASCII characters. SIGN-ASCII instructs AcuSort to use the ASCII sign convention. These keywords mirror the operation of the CHAR-EBCDIC and SIGN-EBCDIC keywords and enable you to switch back and forth between the different modes. This means you can put multiple SORT/MERGE operations in a single take file, which use different character sets or sign modes. AcuSort's defaults are CHAR-ASCII and SIGN-ASCII mode.

Parent topic: AcuSort Instructions


CHAR-EBCDIC and SIGN-EBCDIC instructions

The CHAR-EBCDIC instruction tells AcuSort to expect data that is encoded in the EBCDIC character set rather than ASCII. SIGN-EBCDIC tells AcuSort that numeric DISPLAY types that include signs should be interpreted according to the EBCDIC convention. The use of CHAR-EBCDIC implies SIGN-EBCDIC.

For example, if your data is EBCDIC, you should use CHAR-EBCDIC. If you have ASCII data with EBCDIC sign encoding, you should use SIGN-EBCDIC. If you have ASCII data with ASCII sign encoding, you would not use either instruction.

CHAR-EBCDIC and SIGN-ASCII are incompatible options. If CHAR-EBCDIC is specified and AcuSort is in SIGN-ASCII mode, the sign mode will be forced to SIGN-EBCDIC. If SIGN-ASCII is specified and AcuSort is in CHAR-EBCDIC mode, the char mode will be forced to CHAR-ASCII.

Parent topic: AcuSort Instructions


SORT/MERGE Instructions

The SORT and MERGE instructions specify whether to perform a sort or merge operation. These two functions are mutually exclusive. A SORT or MERGE instruction must be followed by a FIELDS phrase that indicates the fields on which a file is to be sorted or merged. You specify the start position, the length, the type, and the order for each sort field. Use a comma to separate field attributes and a comma before starting to describe a new field. A merge operation combines records from files that are already sorted on the specified fields. The syntax for these functions follows:

acusort sort fields(start, length, type, order)

acusort merge fields(start, length, type, order)

where

start | is the offset of the field in the record (in bytes, starting at position 1).
length | is the size of the field in bytes.
type | is a two-letter code indicating the type of data in the field (see the data field type descriptions below).
order | is the order of output, either ascending (A) or descending (D).

The following data field types are supported in AcuSort:

BI | Unsigned numeric, USAGE COMP
C5 | Unsigned numeric, USAGE COMP-5
C6 | Unsigned numeric, USAGE COMP-6
CH | Alphanumeric
CX | Usage COMP-X
FL | Usage floating point
LI | Signed numeric, SIGN IS LEADING
LS | Signed numeric, SIGN IS LEADING SEPARATE
NU | Unsigned numeric
PD | Signed numeric, USAGE COMP-3
SB | Signed numeric, USAGE COMP
S5 | Signed numeric, USAGE COMP-5
TS | Signed numeric, SIGN IS TRAILING SEPARATE
TI | Signed numeric, SIGN IS TRAILING

In the following example:

acusort sort fields (1, 10, ch, a)

the sort operation begins at position 1 in a 10-byte sort field, and the alphanumeric data are sorted in ascending order. See AcuSort Code Sample for more sample code.

Note: When using LI or TI data types, you should be aware of the sign storage for your data. The AcuSort utility supports both IBM and Micro Focus sign storage. In ACUCOBOL-GT, use the Dci compile option to specify IBM sign storage, or the -Dcm option to specify Micro Focus sign storage. If you use IBM sign storage and your data is ASCII, use the SIGN-EBCDIC instruction in your take file of AcuSort options. See Data Storage Options in the ACUCOBOL-GT User's Guide for more information about data storage compile options. See USAGE Clause in the ACUCOBOL-GT Reference Manual for details on how signs are stored when the various compile options are used.
Parent topic: AcuSort Instructions


USE/GIVE instructions

The USE and GIVE instructions specify the name and characteristics of the input file and output file, respectively, of a sort or merge process. Note that you must specify all USE instructions before any GIVE instructions. The input and output file descriptions include ORG, RECORD, and KEY phrases, which define the file's characteristics. The syntax for these instructions is as follows:

use input-file
   org file-type
   record format, record-length [, max-length]
   key(key-structure)

give output-file
   org file-type
   record format, record-length [, max-length]
   key(key-structure)

where

input-file is the pathname of the input file. For file names containing spaces, surround the filename with double quotes (" "). If the filename contains double-quote characters, specify these by doubling the double-quote characters ("" "".

Examples:

  • filename: Work File
  • notation: "Work File"
  • filename: Embedded"Quote
  • notation: "Embedded""Quote"
output-file | is the pathname of the output file. the same rules regarding input-file names with spaces applies to output-file names.
file-type | specifies the type of input or output file: indexed (IX), relative (RL), line sequential (LS), or binary sequential (SQ).
format | indicates that the file contains fixed length records (F) or variable length records (V).
record-length | specifies the record length for a fixed length record or the minimum record length for a variable length record.
max-length | specifies the maximum record length for a variable length record.
key-structure | specifies the key structure for an indexed file.
Note: If the input and output files have the same organization and/or record information, you need not specify these options for each file. The AcuSort utility applies the most recent RECORD and ORG options to subsequent files when these options are not specified for the files.
  • KEY Structure
  • USE/GIVE Example
Parent topic: AcuSort Instructions


KEY Structure

For each key or key segment, you must specify the start position, the length, and the key type, as defined below. Use a comma to separate field attributes and a comma before starting the description of a new key or key segment.

The following command specifies the key structure for an indexed file:

key (start, length, key-type, ...)

where

start | is the offset of the record key (in bytes, starting at position 1).
length | is the size of the key in bytes.
key-type | is a code indicating the key type (see the list of key types below).

You can specify one of the following key types in the KEY statement:

P | Primary key
PD | Primary key with duplicates allowed
A | Alternate key
AD | Alternate key with duplicates allowed
C | Key segment belonging to the primary or alternate key previously described

The following sample describes the key structure for an indexed file with three keys:

key (502, 98, PD, 1, 18, A, 95, 18, AD, 337, 18, C)

In this example, the primary key allows duplicates. Its offset is 502 and its length is 98. The first alternate key has an offset of 1 and a length of 18. The second alternate key allows duplicates, and consists of two segments. The first segment starts at offset 95 and has a length of 18. The second segment starts at offset 337 and has a length of 18.

The AcuSort utility always sorts duplicate records in the order in which they are encountered in the input file, a process known as a stable sort.

Parent topic: USE/GIVE instructions


USE/GIVE Example

In the following sample code:

use c:\acuprod\data\ordrdetl org ix
   record f 143
   key (1, 36, p)
   give c:\acuprod\data\ordrdet_sorted

the input file is ordrdetl and the output file is ordrdet_sorted. They are both indexed files with a fixed record length of 143. The primary key is 36 bytes long, starting at position 1. Complete sample code can be found in AcuSort Code Sample.

Parent topic: USE/GIVE instructions


INCLUDE/OMIT Instructions

The INCLUDE and OMIT instructions specify conditions under which individual records may be included in or excluded from, respectively, a sort or merge process. As with SORT and MERGE, these instructions are mutually exclusive. Each SORT or MERGE instruction may have a single optional INCLUDE or OMIT conditional (COND) phrase. Syntax for these instructions is as follows:

omit cond (start, length, type, comparison expression)

include cond (start, length, type, comparison expression)

where start, length, and type are as defined for the SORT/MERGE instructions, and comparison expression sets the conditions for a specified comparison.

Conditional constants ALL and NONE match all or none of the records, respectively. As an example, each of the following statements would result in the inclusion of all records:

include cond = all

or

omit cond = none

To omit all records, you would use one of the following statements:

omit cond = all

or

include cond = none

A default record field type may be specified for an INCLUDE/OMIT instruction by setting FORMAT to the desired type. This assignment can appear either before or after the COND phrase. Record field specifications without the type inherit the default type specified by FORMAT. A warning is issued if the default format is specified but never used.

The INCLUDE or OMIT instruction comparison expression may compare a record field against another record field or against a constant. The size of an expression is not limited. Comparison operators are:

EQ | Equal to
GE | Greater than or equal to
GT | Greater than
LE | Less than or equal to
LT | Less than
NE | Not equal to
  • INCLUDE/OMIT Samples
Parent topic: AcuSort Instructions


INCLUDE/OMIT Samples

If you want to include records in which the first four bytes are greater than 1000 when interpreted as USAGE DISPLAY data, you could use one of the following code statements:

include cond = 1 4 nu gt 1000

or

omit cond (1 4 nu le 1000)

To include records in which the first four bytes are the same as the second four bytes when interpreted as characters, you could use one of the following statements:

include cond = 1 4 ch eq 5 4 ch

or

omit cond 1 4 ch ne 5 4 ch

As another example, if you want to omit any record in which the first four bytes (COMP-6) are greater than the second four bytes (COMP-4), you could use one of the following statements (note the use of the FORMAT phrase in this example):

omit format=c6 cond = (1 4 gt 5 4 bi)

or

include cond 1 4 c6 le 5 4 format bi

In addition to the data types already available with SORT/MERGE, the INCLUDE/OMIT instructions may have a substring search (SS) type, which indicates that a search should be performed for the specified character constant. Only the equal to (EQ) or not equal to (NE) operators may be used in conjunction with the SS type. The designated string is either found or not found with this comparison. As an example, each of the following code statements would result in the omission of records in which the first 10 characters contain the substring "data":

omit cond 1 10 ss eq c'data'

or

include cond = (1 10 ss ne c'data')

Constant types can be decimal, hexadecimal, or character. Decimal constants match the pattern

[+-]?[0-9]+

that is, an optional sign character followed by a number of digits. Decimal constants may be up to 76 digits long.

Hexadecimal constants match the pattern

x'([0-9A-F]{2})+'

that is, a leading x indicating a hex constant and then groups of two hexadecimal digits in single quotation marks. Hexadecimal constants are unsigned and may be up to 64 hexadecimal digits long (32 bytes). For example, either of the following statements results in the inclusion of records in which the first 10 characters (USAGE DISPLAY) equal 0xFFFF:

include cond = (1 10 nu eq x'FFFF')

or

omit cond 1 10 nu ne x'FFFF'

Character constants match the pattern

c'.+'

that is, a leading c indicating a character constant and then a number of characters in single quotation marks. Single quotation marks may be represented within the character constant by specifying two single quotation marks in a row.

In general, numeric types may be compared against each other or against a constant. Floating point data may only be compared against other floating point data. Strings may be compared against each other, a string, or a hexadecimal constant. Strings may also be used in substring searches.

Specifically, data types BI, C5, C6, CX, LI, LS, NU, PD, S5, SB, TI, and TS may be compared against each other, or against a hexadecimal or decimal constant. BI and CH may be compared against each other or a string constant. CH may be compared against a hexadecimal constant.

The AND and OR operators may be used to join comparison expressions. The AND operator takes precedence over OR. Note that the characters "&" and "|" may be used to represent AND and OR, respectively. As an example, either of the following statements results in the omission of any record in which the first character does not equal the second or the third character:

omit cond = (1 1 ne 2 1) & (1 1 ne 3 1) format ch

or

include format=ch cond ((1 1 eq 2 1) or (1 1 eq 3 1))

Parentheses may be used to determine the evaluation order of an expression. An expression is evaluated only as far as necessary to determine the inclusion or exclusion of the record. For example, if a conditional is a list of expressions joined by AND operators, and the first expression evaluates as false, the remainder of the expressions is not evaluated for this record.

Parent topic: INCLUDE/OMIT Instructions


AcuSort Code Sample

The following sample code describes the SELECT and FD for an orders-detail indexed file:

SELECT OPTIONAL Orders-Detail
           ASSIGN       TO DISK "ORDRDETL"
           ORGANIZATION IS INDEXED
           ACCESS MODE  IS DYNAMIC
           LOCK MODE    IS AUTOMATIC
           FILE STATUS  IS ORDERS-DETAIL-STATUS
           RECORD KEY   IS Prime = ORDERS-DETAIL-PRIMARY-KEY

       FD  ORDERS-DETAIL.
       01 ORDERS-DETAIL-RECORD.
           05 ORDERS-DETAIL-PRIMARY-KEY.
               10 ORDETL-CUSTOMER  PIC  X(10).
               10 ORDETL-DATE.
                   15 ORDETL-DT-YYYY   PIC  9(4).
                   15 ORDETL-DT-MM     PIC  99.
                   15 ORDETL-DT-DD     PIC  99.
               10 ORDETL-TIME.
                   15 ORDETL-HR        PIC  99.
                   15 ORDETL-MIN       PIC  99.
                   15 ORDETL-SEC       PIC  99.
                   15 ORDETL-TH-SEC    PIC  99.
               10 ORDETL-PROD-NO   PIC  X(10).
           05 ORDETL-DESCRIPTION           PIC  X(80).
           05 ORDETL-QTY       PIC  9(5).
           05 ORDETL-PRICE     PIC  9(9)v99.
           05 ORDETL-TOTAL-PRICE           PIC  9(9)v99.

In this sample, we illustrate the sort of the orders-detail file based on three fields: orderl-customer, ordetl-price, and ordetl-description. Each field is to be sorted in ascending order, and the resulting output file includes only records in which ordetl-date is equal to or greater than May 3, 2006.

The AcuSort take file paramfile1 contains the following options:

sort fields (1, 10, ch, a, 122, 11, nu, a, 37, 80, ch, a)
use c:\acuprod\data\ordrdetl org ix
   record f 143
   key (1, 36, P)
give c:\acuprod\data\ordrdet_sorted
   include cond = 11 8 nu ge 20060503

If we include our AcuSort instructions in a take file named paramfile1, our command line would be

acusort take paramfile1
Parent topic: External Sort Utility AcuSort


AcuSort Environment Variables

The following environment variables affect AcuSort behavior:

A_TMPDIR, TMPDIR | These variables control the location of any temporary AcuSort files. A_TMPDIR is checked first, and then TMPDIR. Temporary files created by AcuSort are placed in this directory. The default value is the current working directory.
ACUSORT_FILE_MEMORY This variable allows you to set the maximum amount of memory in megabytes to be used for buffering I/O data with the temporary file. The default value is "1".

The default value should be adequate for most situations. However, if very large records are in use, you may want to increase this value in order to hold several records. The higher setting allows the buffer layer to avoid doing I/O for record comparisons during a SORT/MERGE process.

Tip: The number of file buffer blocks is controlled by the ACUSORT_FILE_MEMORY environment variable. It is set in units of megabytes. The buffer block size is 4096 bytes; therefore, for each MB, you get 256 buffer blocks. One buffer block will be reserved for each sorted region in the temporary file. The number of sorted regions in the temporary file will depend on the size of the records being operated on and the amount of memory allocated for sorting with the ACUSORT_MEMORY environment variable. Buffers remaining after this reservation may be used for read-ahead. Up to eight buffers per region will be used for read ahead.
ACUSORT_MEMORY | This variable sets the number of megabytes of memory allowed for sorting records. Sort performance may improve as more memory is allocated for this purpose. The default value is "2".
ACUSORT_TRACE This variable controls the type of information written to the AcuSort log file. The following values determine which sets of log messages appear:
  • 1 -- general program
  • 2 -- record import/export
  • 4 -- numeric values comparison
  • 8 -- numeric values conversion
  • 16 -- temporary file buffer
  • 32 -- command structure
  • 64 -- modes
  • 128 -- parser
  • 256 -- lexer

Set ACUSORT_TRACE to the sum of the numbers corresponding to the sets of information you want written to the log file.

Please note that much of this information is intended only for diagnostic use. You should not rely on the content of the information written to the log file, as it is subject to change without notice.

Tip: For time-critical SORTs, examine the AcuSort trace output (specifically the buffer and import/export categories) to see various statistics about sorted region counts and buffer usage. Adjust the memory configuration variables as appropriate.
dd_SYSOUT | This configuration variable specifies the name of the AcuSort log file. Various information about AcuSort functions is written to this file. The default value is SYSOUT.
Parent topic: External Sort Utility AcuSort


Remote Preprocessing Utility Boomerang

The Boomerang utility program includes client and server technologies that enable you to automatically transfer files to a remote server, invoke and perform preprocessing on that server, then return the preprocessed files to your client machine where additional compiling can occur. Many proprietary or third party preprocessors have machine-specific functions that require preprocessing to occur in their native environments. Boomerang makes accessing these types of preprocessors easier and more efficient.

With Boomerang you can:

  • Send source files, COPY files, and user INCLUDE files from a Windows or UNIX/Linux client to a UNIX/Linux server.
  • Invoke and run popular third-party preprocessors such as those used with Oracle, DB2, UniKix, and IBM TXSeries CICS, or invoke custom-built preprocessors.
  • Have preprocessed output files, error files, and status returned to your client machine.
  • Use Boomerang with the ACUCOBOL-GT compiler's -Pg option to perform single or multiple preprocessing steps.
  • License Requirements and Installation
  • Server Setup and Configuration
  • Server Commands
  • Client-side Operation Remote Precompiling
  • Client Commands
  • Working with INCLUDE files
Parent topic: Debugger and Utilities
Parent topic: Utilities


License Requirements and Installation

To use Boomerang, the client machine must have an ACUCOBOL-GT development system and corresponding compiler license. On the server, a standard runtime license and server access file is required. You can use Boomerang to create an access file or you can use an existing access file. See the For AcuConnect or AcuServer User's Guide for information on setting up a server access file.

The Boomerang client and server program (boomerang.exe) requires no special installation steps, and is automatically installed in the same directory as the runtime.

Parent topic: Remote Preprocessing Utility Boomerang


Server Setup and Configuration

Boomerang server setup and configuration involves four main steps:

  • Step 1 Creating an Alias File that contains aliases for each preprocessor you wish to invoke from your client machine.
  • Step 2 Creating a Configuration File and setting configuration variables accordingly.
  • Step 3 Creating an Access File to establish system security and access.
  • Step 4 Starting the Server.
  • Step 1: Creating an Alias File
  • Step 2: Creating a Configuration File
  • Step 3: Creating an Access File
  • Step 4: Starting the Server
Parent topic: Remote Preprocessing Utility Boomerang


Step 1: Creating an Alias File

To accomplish its preprocessing tasks, Boomerang references an alias file that contains preprocessor-specific commands and instructions.

To create an alias file for a preprocessor, perform the following steps on the server:

  1. From a command line, navigate to where boomerang.exe is installed, type boomerang and press return.

    The following usage information appears:

    Server usage:
 boomerang -alias
 boomerang -access
 boomerang -kill [-n portnum]
 boomerang -start [-c config] [-e error] [t #] [-f] [-n portnum]

Client usage:
  boomerang -server server[:port]
            -alias alias
            -COPY
            -include pattern [pattern ...]
            [-placePo preprocessor-output-file]
            [-Pe preprocessor-error-file]
            -Sf source-file
  2. Access the alias menu by typing the following command:
     boomerang -alias

    The following alias menu options appear:

    Enter the name of the alias file: [/etc/boomerang_alias.ini] boomerang_alias.ini

Boomerang Alias file options
1 - Add an alias entry
2 - Remove an alias entry
3 - Modify an alias entry
4 - Display alias entries
5 - Exit

Enter choice [4]: 1
  3. Select option 1 create an alias file. The following menu appears:
    Add an alias
Enter the alias name:
Enter the name of the precompiler:
Enter precompiler options:
Enter precompiler directives:
Enter required precompiler extension if any:
Press <Return> to continue...

The alias creation fields are defined as follows:

Field | Description
Alias name | The name you wish to give your alias.
Name of precompiler | The precompiler that should be used by this alias. You can also specify the name of a shell script to run instead of the precompiler name. This is necessary for some precompilers like DB2 where certain setup instructions are required before precompiling can commence. See DB2 Alias Example for more information.
Precompiler options Instructions you wish to give to the preprocessor. Boomerang includes several keywords you can use to specify several basic files:
  • B_INPUT: Input to the preprocessor. This is replaced with the name specified by the -Sf option from the Boomerang client command. If you are executing Boomerang from the ACUCOBOL-GT compiler, the compiler automatically calls the Boomerang Client with the -Sf option and the name of the program to be preprocessed.
  • B_OUTPUT: Output from the preprocessor. This is replaced with the name specified by the -placePoBoomerang client command. By default, the ACUCOBOL-GT compiler expects the output from the preprocessor to be named acu_?_pp1.out with two underscores. If you do not specify the -placePo option, Boomerang will replace this keyword with the default name acu_?_pp1.out.
  • B_ERROR: Error output from the preprocessor. This is replaced with the name specified by the -PeBoomerang client command. If you do not specify the -Pe option, Boomerang will replace this keyword with the default name acu_?_pp1.std with two underscores. The ACUCOBOL-GT compiler automatically displays the contents of this file to the screen.
Precompiler directives | Used to specify any keywords that the preprocessor recognizes as directives. Boomerang will automatically insert ACUCOBOL-GT line directives before and after these keywords. In cases involving compilation errors, this makes it easier for you to identify the offending line of code in the source file.
Required precompiler extension | Your COBOL program can have any extension you want, but some precompilers require a specific extension. If your precompiler requires a specific extension on the source file, specify it here rather than changing the extension name of your source files. Boomerang creates a temporary file on the server with the extension you specify so that preprocessing can be performed. Boomerang will then remove this temporary file. If you do not specify an extension here, it will use the extension of the source file. There is a case where the extension of the source file is not used - when you are calling two or more preprocessors. In this case, the output of the first preprocessor is called acu_?_pp1.out and is used as input to the second preprocessor. If the second preprocessor requires a specific extension, you can specify the expected extension here. For example, if the precompiler requires a source file extension of .ccp, you would need to specify .ccp as the required precompiler extension. Otherwise, the precompile will fail. See Calling Two or More Preprocessors for more information on calling two or more preprocessors.
  • Pro*COBOL Alias Example
  • CICS Alias Example
  • UniKix Alias Example
  • DB2 Alias Example
Parent topic: Server Setup and Configuration


Pro*COBOL Alias Example

Add an alias
Enter the alias name: alias-procob
Enter the name of the precompiler: procob
Enter precompiler options: iname=B_INPUT oname=B_OUTPUT >B_ERROR 2>&1
Enter precompiler directives: EXEC SQL
Enter required precompiler extension if any:
Press <Return> to continue...

Since Pro*COBOL has the following options to specify the input and output files:

iname=
oname=

the name of the Pro*COBOL input file can be specified by the B_INPUT keyword and the name of the output file can be specified by the B_OUTPUT keyword. Since Pro*COBOL does not have an option to specify an error output file, the >B_ERROR 2>&1 redirects the output that normally would be displayed on the screen to the file associated with the B_ERROR keyword.

EXEC SQL is specified as the precompiler directive since Pro*COBOL uses this phrase to begin its Pro*COBOL statements.

Parent topic: Step 1: Creating an Alias File


CICS Alias Example

Add an alias
Enter the alias name: alias-cicstran
Enter the name of the precompiler: cicstran
Enter precompiler options: -l ACUCOB -O B_OUTPUT B_INPUT >B_ERROR 2>&1
Enter precompiler directives: EXEC CICS
Enter required precompiler extension if any: .ccp
Press <Return> to continue...

The -l ACUCOB option is required with CICS. This parameter tells cicstran to precompile the source file in a manner that is compatible with ACUCOBOL-GT.

Since CICS uses the -o option to specify the output file, it can be specified by the B_OUTPUT keyword. The name of the input file is specified by the B_INPUT keyword. CICS does not have an option to specify an error output file, the >B_ERROR 2>&1 redirects the error output from the screen to the file associated with the B_ERROR keyword.

EXEC SQL is specified as the precompiler directive since CICS uses this phrase to begin its CICS statements.

CICS requires that the source file have an extension of .ccp so it is specified as the required precompiler extension.

Parent topic: Step 1: Creating an Alias File


UniKix Alias Example

Add an alias
Enter the alias name: alias-unikix
Enter the name of the precompiler: kixclt
Enter precompiler options: -O B_OUTPUT B_INPUT >B_ERROR 2>&1
Enter precompiler directives: EXEC CICS
Enter required precompiler extension if any: .cl2
Press <Return> to continue...

Since UniKix uses the -o option to specify the output file, it can be specified by the B_OUTPUT keyword. The name of the input file is specified by the B_INPUT keyword. UniKix does not have an option to specify an error output file, the >B_ERROR 2>&1 redirects the error output from the screen to the file associated with the B_ERROR keyword.

EXEC SQL is specified as the precompiler directive since UniKix uses this phrase to begin its CICS statements.

UniKix requires that the source file have an extension of .cl2 so it is specified as the required precompiler extension.

If there are COBOL COPY statements in the source file UniKix requires these files to exist on the server where kixclt is run. You can use the Boomerang-COPY command on the client side to instruct Boomerang to copy the COPY files to the server and to use them in the preprocessing phase.

UniKix requires that you have the following environment variables set:

  • UNIKIX
  • PATH
  • COPYPATH

See your UniKix documentation for information on setting these variables. Boomerang requires setting these variables before starting the Boomerang server. If you use the -Sf or -COPY client commands to send COPY files from the client to the server, be sure you add the directory where the Boomerang server resides to the server COPYPATH environment variable so that these COPY files can be found by the preprocessor. The files specified by the -Sf or -COPY commands get copied into the directory where the Boomerang server resides.

Parent topic: Step 1: Creating an Alias File


DB2 Alias Example

Add an alias
Enter the alias name: alias-db2
Enter the name of the precompiler: db2prep.sh
Enter precompiler options: database B_INPUT B_OUTPUT B_ERROR
Enter precompiler directives: EXEC SQL
Enter required precompiler extension if any: .sqb
Press <Return> to continue...

DB2 requires some setup before running its precompiler. You can perform the necessary setup by specifying a shell script file (db2prep.sh in this example) to run instead of specifying the name of the precompiler. The shell script performs the necessary setup and then starts the precompiler. The Boomerang keywords beginning with B_ are passed to the shell script by specifying them at the precompiler options line. EXEC SQL is specified as the precompiler directive since DB2 users EXEC SQL to begin its DB2 statements. The DB2 precompiler requires that the input file have an extension of .sqb so this is specified at the required precompiler extension line.

Using the example above, when the Boomerang server runs the shell script it looks something like this:

db2prep.sh database ACCT01.sqb acu__pp1.out acu__pp1.std

Note that the precompiler options must be specified in the order that the shell script expects. The following is an example of a DB2 shell script used by the Boomerang server:

#!/bin/ksh

# db2prep.sh - This script is designed to be called from the
# Boomerang server. For this script the Boomerang server alias # file would need to have the following precompiler options     # using the Boomerang file keywords:
#
# Precompiler-Options: database B_INPUT B_OUTPUT B_ERROR
#
# In this script the Boomerang keywords get mapped to the       # following script variables:
#
# database = $1 the name of the database to connect to
# B_INPUT  = $2 the precompiler input file
# B_OUTPUT = $3 the precompiled output file
# B_ERROR  = $4 the precompiler error file

# Execute the DB2 configuration file
. /home/db2inst1/sqllib/db2profile

# DB2 precompile -- takes .sqb as input, outputs .cbl
echo ==================================================
echo  Begin output from \"db2 prep\" SQL precompiler:
echo ==================================================

# Connect to the database
db2 connect to $1 >$4 2>&1

# Execute the precompiler on $2 sending any error output to $4
# capture the return code in $returnCode
db2 prep $2 target ansi_cobol >>$4 2>&1
returnCode=$?

# Boomerang expects the precompiled output file to be the name
# specified by $3.  The precompiled output file created by DB2
# is the name as the source file but with an extension of .cbl.
# We need to remove the extension from the input file, $2, and
# add a .cbl extension so that we can copy it to $3.
# The following command removes the "." and everything past it # to create the prefix.
prefix=`echo $2 | sed -e "s/\..*$//"`

# Copy the precompiled output file to the name that Boomerang
# is expecting, $3.
cp $prefix.cbl $3

# the db2 CLP returns 2 for warnings; treat as if a 0 was returned
if [ $returnCode -eq 2 ]; then
    returnCode=0
fi
if [ $returnCode -eq 0 ]; then
    db2 connect reset  >>$4 2>&1
    db2 terminate      >>$4 2>&1
else
    echo \"db2 prep\" failed:  return code:  $returnCode >>$4 2>&1
fi
exit $returnCode
Parent topic: Step 1: Creating an Alias File


Step 2: Creating a Configuration File

Using a text editor, create a configuration file named boomerang.cfg and include the configuration variables that can be specified for the Boomerang server. (Note: you can specify your own filename if desired). A sample file showing these variables and their default settings appears below:

# boomerang.cfg

# This file should be owned by root and only writeable by root:
# chown root boomerang.cfg
# chmod 644 boomerang.cfg

# Default port is 7770
BOOMERANG_PORT 7770

# Default alias file is /etc/boomerang_alias.ini
BOOMERANG_ALIAS_FILE boomerang_alias.ini

#Default AcuAccess file is /etc/AcuAccess
ACCESS_FILE AcuAccess
Parent topic: Server Setup and Configuration


Step 3: Creating an Access File

The server access file for Boomerang is named and structured the same as the server access file for AcuServer and AcuConnect. If you are using either of these servers for UNIX, you can use your existing Access file in conjunction with Boomerang, or you can set up a separate file for Boomerang.

Parent topic: Server Setup and Configuration


Step 4: Starting the Server

To start the server, issue the following command:

boomerang -start -c boomerang.cfg -e boomerang.err
Parent topic: Server Setup and Configuration


Server Commands

The following table describes the Boomerang server commands.

-access | Used to create an access file. See Creating and Maintaining the Server Access File in the AcuServer User's Guide or Executing Non-COBOL Programs on the Client in the AcuConnect User's Guide for more information.
-alias | Used to create an alias. See Step 1 Creating an Alias File for details on this command.
-c configuration- filename | Specifies the configuration file that should be used by Boomerang. If the -c option is not specified, Boomerang will use the file specified by the environment variable, A_BOOMERANGCFG. If neither the -c or A_BOOMERANGCFG are specified, the default boomerang.cfg file is used.
-e error-filename | Specifies the error file for the Boomerang server.
-f | Runs the Boomerang server in the foreground.
-kill [-n port] | Stops the Boomerang server. You can optionally specify the port.
-start [-n port] | Starts the Boomerang server. You can optionally specify the port.
-t # Turns on the tracing function. When combined with the -e option, trace information is placed in the named error file. The # represents the type of tracing or logging to be performed.
  • 1 -- provides information about access file match attempts. The trace information buffer is flushed to the error file when the buffer is filled or Boomerang terminates.
  • 2 -- provides information about client requests. The buffer is flushed to the error file when the buffer is filled or Boomerang terminates.
  • 3 -- provides the information described for 1 and 2.
  • 5 -- is equivalent to 1, but the tracing buffer is flushed to the error file each time an access file match is requested. (File trace flushing can also be controlled with the FILE_TRACE_FLUSH server configuration variable.)
  • 6 -- is equivalent to 2, but the tracing buffer is flushed to the error file each time a client connection is requested.
  • 7 -- provides the information described for 5 and 6.
Parent topic: Remote Preprocessing Utility Boomerang


Client-side Operation Remote Precompiling

The Boomerang client does not require any special setup or configuration. Once you have set up and configured your Boomerang server, use the Boomerang client to enter and carry out your remote preprocessing commands. Boomerang sends the specified source file to the server and invokes the preprocessor using the alias file that you created on the server. The preprocessed output file and status are then returned to the ACUCOBOL-GT compiler. If the precompile was successful, normal compiling occurs. If the precompile was not successful, the compiler will display the status.

  • Remote Precompiling
Parent topic: Remote Preprocessing Utility Boomerang


Remote Precompiling

Boomerang operates as either a standalone program, or as a preprocessor to the ACUCOBOL-GT compiler. To perform remote preprocessing, invoke Boomerang from the ACUCOBOL-GT compiler using the -Pg option. For example:

ccbl32 -Pg boomerang -server myserver[:port] -alias alias-name source-filename

A list of all available commands appears below.

Note: Boomerang is also integrated with AcuBench (ACUCOBOL-GT's IDE product).
Parent topic: Client-side Operation Remote Precompiling


Client Commands

The following table describes the Boomerang client commands and arguments.

-alias alias-name | Tells Boomerang to pass this alias name to the server, which the server will then use to look up preprocessor-specific instructions.
-include pattern | Instructs Boomerang to copy INCLUDE files to the server and to use them in the preprocessing phase. See Working with INCLUDE files for details on using this command.
-Pe preprocessor- error-filename | Writes preprocessor error messages to the specified filename.
-placePo output- filename | Writes the preprocessed output to the specified filename.
-server myserver [:port] | Tells Boomerang which server to connect to, and if specified, which port.
-Sf source-filename | Instructs Boomerang to copy the specified file to the server if needed by the preprocessor on the server. If no pathname is specified the file is expected to be in the current directory. If you are using AcuBench, the current directory is the directory above the Copylib and Source directories. This is a way to move files to the server that would not normally get moved by the -include or -COPY options. For example, if the preprocessor expands an EXEC statement into a COBOL COPY statement and the COPY file is on the client but not on the server, you can use this option to move the file to the server so it can be found by the preprocessor. These files are copied into the directory where the Boomerang server resides and are removed after preprocessing. Some preprocessors require that you add the Boomerang server directory to a server environment variable like COPYPATH so that it can locate these COPY files.
-COPY | Some preprocessors require COBOL COPY files to reside on the server. This option instructs Boomerang to copy the COPY files specified by COBOL COPY statements to the server and to use them in the preprocessing phase. If you execute Boomerang from the ACUCOBOL-GT compiler, use the compiler -Sp option to tell Boomerang where to find the COPY files on the client. If the -Sp option is not specified, Boomerang will look for the COPY files in the current directory. If you are using AcuBench, the current directory is the directory above the Copylib and Source directories. These files are copied into the directory where the Boomerang server resides and are removed after preprocessing. Some preprocessors require that you add the Boomerang server directory to a server environment variable like COPYPATH so that it can locate the COPY file.
Parent topic: Remote Preprocessing Utility Boomerang


Working with INCLUDE files

With Boomerang, you can specify the -include option to tell Boomerang to send any preprocessor INCLUDE files that exist on the client to the server in case they are needed during the precompile. Do this by specifying the following command:

-include <pattern> <pattern...>

Since each preprocessor may have different syntax for specifying a preprocessor INCLUDE file, pattern is a sequence of case-insensitive strings that precede the name of the preprocessor INCLUDE file. The name of the INCLUDE file in the source file does not have to be enclosed in quotes, but if it is, it may be enclosed in single or double quotes.

For example, Pro*COBOL has the following syntax for a preprocessor INCLUDE file:

EXEC SQL
      INCLUDE SQLCA
END-EXEC.

You specify the following Boomerang option:

-include EXEC SQL INCLUDE
Parent topic: Remote Preprocessing Utility Boomerang


Terminal Manager

  • How the Terminal Manager Works
  • Getting Your Terminals Ready
  • The Keyboard Interface
  • The Display Interface
  • Restricted Attribute Handling
  • The Terminal Database File
Parent topic: ACUCOBOL-GT User's Guide


How the Terminal Manager Works

Terminal Manager is the name we give to the runtime system module that handles the input from the keyboard and the output to the screen. The Terminal Manager interprets the keys that the user presses, translating each keystroke into a function, such as a backspace. It also manages translation of attributes from your ACUCOBOL-GT application program to the screen.

The Terminal Manager provides a consistent interface between ACUCOBOL-GT programs and the particular machines on which they are running. The manager minimizes any differences among the various machines, operating systems, and terminals for which ACUCOBOL-GT is available.

The Terminal Manager also provides support for the emulation of graphical user interface components such as floating windows (modal and modeless) and controls on text-mode systems. For information regarding how to customize the characters used to emulate graphical components, see Graphical Window and Control Emulation.

This help section describes how the Terminal Manager handles your program's interaction with terminals, including both the screen display and the keyboard. It also explains how you can configure the Terminal Manager and how it interacts with end users.

For example, you'll see how to specify what terminal you have, and how to make choices like:

  • Designating a special action key
  • Changing the on-screen prompt character
  • Adding or changing colors
  • Controlling data display and entry format
  • Sounding error alarms

Sometimes features built into a COBOL program can override the effects of the values and variables described in this section. These situations can be important to application program developers and to end users, and are highlighted by notes at the appropriate places in this section.

  • Terminal Manager Functions
  • Alternate Terminal Manager
Parent topic: Terminal Manager
Parent topic: Setting up your Terminals


Terminal Manager Functions

This diagram depicts how the Terminal Manager relates to hardware and other software in your system:

Many Terminal Manager functions depend on the data in two files:

  • The terminal database file, a text file that maps screen and keyboard hardware signals of different terminals to common codes. The file contains signal-to-code sets for many popular terminals. In this section, the codes for screen and keyboard signals will generally be called terminal function codes. The term key codes will be used to refer to the subset of terminal function codes that deals with the keyboard.

    Terminal function codes enable the Terminal Manager to handle I/O between application programs and a variety of terminals without any program changes; you only need to tell the Terminal Manager what terminal you will be using. Some of the codes can also be used to customize terminal actions, as described throughout this section.

  • The runtime configuration file, a text file which includes variables that help define how the screen, the keyboard, and the user's keystrokes will be handled. Relevant runtime configuration variables are described in detail in this section. They are often used in conjunction with the key codes and terminal function codes mentioned above.
Parent topic: How the Terminal Manager Works


Alternate Terminal Manager

The Alternate Terminal Manager (ATM) runtime is a special 32-bit Windows runtime that allows you to use a 32-bit Windows server in much the same way that many UNIX servers are used. With the ATM runtime, you can telnet to the Windows server (with a third-party telnet service) to execute character-based ACUCOBOL-GT programs in the telnet window. However, the ATM runtime does not support program execution in the console window of the Windows server. The ATM runtime is licensed and installed separately from the standard ACUCOBOL-GT Windows (graphical) runtime.

All major runtime functionality, except graphical support, is available with the ATM runtime. Because it is for character-based programs, certain Windows-specific features, such as pop-up dialog boxes, are not supported. Note that the ATM runtime automatically detects and uses Acu4GL DLLs, if present, and it supports calls to other DLLs.

Note: See Relinking the Runtime System if you need to relink the ATM runtime.
Parent topic: How the Terminal Manager Works


Getting Your Terminals Ready

This help section describes your options as you prepare to use specific terminals with your application. Your computer's operating system and the ACUCOBOL-GT software will handle communication with most terminals without your doing anything. With some terminals, you will need or want to specify some choices.

Before running a program that uses the Terminal Manager, you may need to identify the type of terminal that will be used, and you may wish to customize the interface. The process of setting up a specific terminal involves these major steps:

  • Step One: Terminal Identification
  • Step Two: Terminal Definition
  • Step Three: Configuration Variables
Parent topic: Terminal Manager
Parent topic: Setting up your Terminals


Step One: Terminal Identification

The ACUCOBOL-GT runtime system opens the terminal database file. Each entry in the file consists of the name of a terminal, followed by its screen and keyboard attributes, definitions and codes. (Runtimes for some systems, such as Windows, typically do not use a terminal database file. Check with your Product Support representative if your terminal is non-standard, to determine if you require the terminal database file.)

The runtime system first looks for the system variable A_TERMCAP; if that variable is present, the runtime system opens the file named in it as the terminal database file. If the system variable A_TERMCAP is not present, the runtime system opens the file name shown in the table below. The file name varies with the operating system (note that file names on UNIX systems are case-sensitive):

System | Terminal database file
UNIX | /etc/a_termcap
VMS | SYS$LIBRARY:A_TERMS.DAT

You must tell the Terminal Manager what terminal database file to use with your ACUCOBOL-GT application. Either:

  • use the path and name specified in the table above, and do not set A_TERMCAP (this approach works fine in most cases)

    or

  • use a path and name of your choosing, and specify that path and name in A_TERMCAP.

After the terminal database file is opened, the Terminal Manager needs to know what terminal type is to be used, and where to locate the entry that describes it. One of the system variables A_TERM or TERM holds the name of the entry that is to be used.

The Terminal Manager looks first for the variable A_TERM. If it is present, the Terminal Manager searches the terminal database file for the terminal named in A_TERM. If A_TERM is not present, the Terminal Manager looks for the variable TERM and then searches the terminal database file for the terminal named in TERM. Setting TERM to the correct terminal name will handle most situations. If neither TERM nor A_TERM is present, the Terminal Manager terminates the runtime system with an error message. See Step 2 Creating a Configuration File for exceptions.

The various operating systems handle TERM and A_TERM in different ways:

  • On VMS systems, TERM and A_TERM are symbols.
  • On UNIX systems, they are environment variables; most UNIX systems set the TERM variable at login time.
  • The Windows console (character-mode) runtime does not use the terminal database file, and so does not need to know the value of TERM.
  • Graphical runtimes do not use the terminal database file, and so do not need to know the value of TERM.
  • The ATM runtime uses TERM and A_TERM as environment variables, just like UNIX.

The terminal database file shipped with the ACUCOBOL-GT runtime system contains definitions of the characteristics of most popular terminals; you will probably find yours listed. If the entry named in A_TERM or TERM describes the terminal you will use with your ACUCOBOL-GT application, then nothing more need be done.

Parent topic: Getting Your Terminals Ready


Step Two: Terminal Definition

If the terminal database file entry named in A_TERM or TERM does not describe the terminal you will use, you probably will not want to change the value of TERM, because other software may rely on that value. Instead, take these two steps:

  1. Locate the terminal database file entry that correctly describes your terminal, or create a new one and give it a new name. See The Terminal Database File for details.
  2. Set A_TERM to the name of that entry.
  • Windows Special Considerations for Terminal Manager
Parent topic: Getting Your Terminals Ready


Windows Special Considerations for Terminal Manager

Neither the ACUCOBOL-GT graphical or console runtimes for Windows use a terminal database file when a standard Windows monitor is used. If you choose to use a character-based terminal (such as the VT-100), you will need both the alternate terminal manager runtime and a terminal database file. These can be requested from your Product Support Representative at Micro Focus. Be aware that your programs will execute less efficiently with this combination than with the standard Windows runtime and a standard Windows monitor.

Parent topic: Step Two: Terminal Definition


Step Three: Configuration Variables

Some behaviors of the terminal can be controlled by entries (variables) in the runtime configuration file. The default name of this file, like that of the terminal database file, varies according to the host operating system:

System | Runtime Configuration File
Windows | \etc\cblconfi
UNIX and Linux | /etc/cblconfig
VMS | SYS$LIBRARY:A_CONFIG.DAT

Options on naming and accessing the runtime configuration file, and descriptions of many of the entries in it, are discussed in Compiler and Runtime. That section also discusses the relationship between the runtime configuration file and the host computer's environment. This section discusses entries in the terminal database file and the runtime configuration file which are of particular importance to the Terminal Manager.

Entries in both the terminal database file and the runtime configuration file are described throughout this section, grouped according to the functions that they control. These are the basic areas of functionality that you will need to consider in deciding what you need to modify or define:

Parent topic: Getting Your Terminals Ready


The Keyboard Interface

The Terminal Manager handles both the screen display and keyboard input. See The Display Interface for more information about the display interface.

  • Key Mapping
  • Redefining the Keyboard
Parent topic: Terminal Manager
Parent topic: Setting up your Terminals


Key Mapping

The mapping of keys to functions is one of the main activities of the Terminal Manager. If you understand what happens when a user presses a key, you'll have a good feel for how you can control the interaction between the keyboard and the COBOL application. The next diagram depicts the overall process, from keystroke to COBOL program.

  • Key Interpretation
  • Key Translation
  • Keyboard Configuration
Parent topic: The Keyboard Interface


Key Interpretation

When the user presses a key, the keyboard sends a signal to the computer. This signal needs to be interpreted and translated into a value, or functionality, that the COBOL program can understand. This process begins with the terminal database file.

The terminal database file equates hardware signals to logical values. Unless you are running on a system such as Windows, where the key interpretation is built into the runtime, your terminal needs to be listed in the terminal database file. Keystrokes at the terminal generate hardware signals, and each hardware signal must be equated to a logical value if the application program is to respond to the associated keystroke. These logical values, called key codes, are listed in the Table of Keys in Table of Keys.

We provide the definitions for many popular terminals in the terminal database file that we send you. If the name of your terminal is included, you will not need to change anything unless your particular terminal is different from the standard configuration for its type. If that is the case, you may need to change the entry.

Each entry in the terminal database file consists of the name of the terminal (including all names by which you might typically refer to this terminal type), followed by a series of character strings. Some of these strings are equations that assign hardware signals from the keyboard to key codes that we provide. Some of the strings consist of functional instructions to the terminal.

Terminal database file entries and the syntax rules that govern them are described in The Terminal Database File.

Parent topic: Key Mapping


Key Translation

After the hardware signal has been equated to a key code, the runtime system checks the runtime configuration file to determine if any special values or functions have been attached to the key code.

This is the point at which statements in a COBOL program can override what is specified in the runtime configuration file.

Parent topic: Key Mapping


Keyboard Configuration

Each terminal has several keys that are available to be used for special purposes. Some of these keys are used as field termination keys, others are used as editing keys. ACUCOBOL-GT supports a large number of special keys, but in the default configuration, only these are used:

Function Keys 1-20 | Help
Arrow Keys | Do
Page Up | Page Down
Backspace | Line-Kill
Home | End
Insert | Delete
Clear | Clear to End
Carriage Return | Control Keys

The Backspace and Line-Kill keys are whichever keys provide these functions for your operating system. The Backspace key is the one that erases individual characters from a command line; the Line-Kill key is the one that can cancel a command line. On most systems, the key that performs the Backspace function is the one labeled either backspace or delete.

The keyboard interface can be easily configured to meet a variety of needs. The default configuration has the following characteristics:

  1. The range of legal input characters is ASCII values 32 through 255. Other characters outside this range are ignored unless covered by one of the cases below.
  2. The range of exception characters is ASCII values 1 through 31. If any of these characters is typed, an exception condition exists and input to the field is terminated. The exception key value is identical to the ASCII value of the key. For example, if Control-E is typed, then the exception key value returned would be 5. This rule does not apply to characters specifically listed in rule 3.
  3. The following table outlines the actions of other keys. In this table, Action is the special action performed by the key. If a number is present here, then this key terminates the field and returns that number as its termination key value. If the number is starred (*), then this key also causes an exception condition. If there are both a number and an action, then the key acts as a termination key when the action cannot be applied.

    The Windows column names the keycap on the IBM-PC keyboard that is used for this key. The Termcap column names the terminal database file entry that corresponds to this key for UNIX and VMS systems.

Key | Action | Windows | Termcap
Carriage Return | 13 | Enter |
Tab | Next Field (9) | Tab |
Host's Backspace | Backspace | BkSp |
Host's Line-Kill | Erase Field |  |
Backtab | Previous Field | Shft-Tab | kB
Home | First Field | Home | kh
End | Last Field | End | KE
Insert | Auto-Insert Mode | Ins | KI
Delete | Delete Character | Del | KX
Clear | Erase Field | Ctl-Home | KC
Clear-to-End | Erase Remainder | Ctl-End | kE
Left Arrow | Left | Left | kl
Right Arrow | Right | Right | kr
Up Arrow | Previous-All (52*) | Up | ku
Down Arrow | Next-All (53*) | Down | kd
Page Up | Page-Up (67*) | PgUp | kP
Page Down | Page-Down (68*) | PgDn | kN
Do (Command) | 40* |  | KD
Help | 90* |  | K?
F1 - F10 | 1 - 10* | F1 - F10 | k1 - k0
F11 - F20 | 11 - 20* | Shft F1 - F10 | K1 - K0
Note: Keys that terminate input with an exception condition are ignored by ACUCOBOL-GT if the ACCEPT statement does not have an EXCEPTION clause or a CONTROL KEY clause. However, if you use the -Vx compile-time option, exception keys will be recognized even if the ACCEPT statement does not contain an EXCEPTION or CONTROL KEY clause.

When accepting data from the keyboard, the Terminal Manager runs in one of two modes: standard mode or auto mode. In standard mode, the only way to finish input is by typing one of the allowed termination keys; the cursor may not leave the field. In auto mode, the cursor can leave the field; when the user fills the field with data, it is immediately accepted and the cursor moves on. The setting of auto mode or standard mode is determined by the various clauses specified on the ACCEPT statement.

There are four methods for accepting a field (ACCEPT verb, Format 1), depending on the mode and the presence of either the CONTROL KEY clause or the ON EXCEPTION clause. These methods are:

  • Standard mode, no CONTROL KEY or ON EXCEPTION clause:

    the field can be accepted only by a termination key. In the default keyboard configuration, these are the Carriage Return and Tab keys.

  • Standard mode, with CONTROL KEY or ON EXCEPTION clause:

    the field can be accepted by a termination key or by one of the exception keys.

  • Auto mode, no CONTROL KEY or ON EXCEPTION clause:

    the field can be accepted by a termination key or by filling the field with data.

  • Auto mode, CONTROL KEY or ON EXCEPTION clause:

    the field can be accepted by filling it with data, or by a termination key or an exception key.

The Terminal Manager can control more than one field when the program is doing an ACCEPT that refers to a Screen Section item (ACCEPT verb, Format 2). In the course of this ACCEPT, the user can move between the fields by using the Tab, Backtab, Left, Right, Up, Down, Home and End keys; the Tab key acts as a terminate key only in the last field. A Format 2 ACCEPT statement does not support the use of the CONTROL KEY clause; the CRT STATUS phrase of the Special-Names paragraph may be substituted. Data entry for a Screen otherwise falls into four categories much like the above.

The termination and exception keys may be changed by runtime configuration options as described in Redefining the Keyboard.

  • Note to RMCOBOL-85 Users
Parent topic: Key Mapping


Note to RMCOBOL-85 Users

The ACUCOBOL-GT default keyboard layout is very similar to that used by RM/COBOL-85, but it is not identical. Consider these points:

  1. Under MS-DOS, RM/COBOL-85 defines the Command key to be Alt-C. When you are typing this key it is easy to accidentally type Control-C instead, which is the interrupt key in DOS. For this reason, ACUCOBOL-GT uses Alt-D (for "Do") instead.
  2. ACUCOBOL-GT defines more editing keys than RM/COBOL-85 does. In particular, the Home, End, Clear, Clear-to-End and Line-Kill keys return exception values under RM/COBOL-85, while under ACUCOBOL-GT they perform various field-editing functions.
  3. ACUCOBOL-GT defines Page Up, Page Down, and Help keys that are not defined under RM/COBOL-85. These keys are used by the ACUCOBOL-GT debugger.
  4. The default RM/COBOL-85 keyboard includes the following keys as exception keys: Attention, Home, New Line, Tab Left, Erase Right, Tab Right, Insert Line, Delete Line, and Send. Under ACUCOBOL-GT, these keys either act as editing keys or are ignored. Because these keys are generally not available on most keyboards (or, in the case of the Tab Right and New Line keys, are ambiguous with control keys), most applications do not use them. If you need to use any of these keys, you can alter the ACUCOBOL-GT keyboard configuration as described in Redefining the Keyboard.
  5. The RM/COBOL-85 layout varies from machine to machine. In the interest of portability, the default ACUCOBOL-GT keyboard interface is the same for all machines.
Parent topic: Keyboard Configuration


Redefining the Keyboard

The ACUCOBOL-GT keyboard interface may be modified via two variables in the runtime configuration file. The KEYBOARD variable defines global keyboard attributes. The KEYSTROKE variable defines the interpretation of a particular key or key combination. These two variables enable you to tailor the keyboard interface to your application.

  • The KEYBOARD Variable
  • The KEYSTROKE Variable
  • Table of Keys
  • Additional Windows Keys
  • Special Keys
  • Default Keyboard
  • Keyboard Modification Examples
Parent topic: The Keyboard Interface


The KEYBOARD Variable

You can specify one or more KEYBOARD variables. Attributes that you can set are identified by one or more sets of keywords and associated values, separated from each other by spaces or tabs. The syntax is:

KEYBOARD keyword=value [keyword=value]...

Keywords are:

  • AUTO-RETURN=value
  • CASE=value
  • CHECK-NUMBERS=value
  • CURSOR-PAST-END=value
  • DATA-RANGE=value
  • EXCEPTION-RANGE=value
  • IMPLIED-DECIMAL=value
  • RM-2-DEFAULT-HANDLING=value
  • SCREEN-DEFAULT=value
Parent topic: Redefining the Keyboard


AUTO-RETURN=value

Some ACCEPT statements terminate automatically when the input field is filled. When this occurs, the termination key value is the value (a decimal number) defined by the AUTO-RETURN keyword. This value is returned in the CONTROL KEY clause of the ACCEPT statement. The default value is zero. You may also specify this option with the configuration variable KBD_AUTO_RETURN.

Parent topic: The KEYBOARD Variable


CASE=value

The CASE option on the KEYBOARD configuration entry allows you to cause all entries to be automatically converted to upper or lowercase. value may be set to Upper, Lower or Both:

Upper: | all ACCEPT statements convert keystrokes to upper case.
Lower: | all ACCEPT statements convert keystrokes to lowercase.
Both: | (default) causes no translation.

CASE may be overridden with the settings of the UPPER and LOWER keywords on individual ACCEPT statements. See Common Screen Options for more information.

The configuration variable KBD_CASE is also supported.

Note: The value of KEYBOARD CASE does not affect controls. To effect the same result on controls, use the UPPER or LOWER phrase on the ACCEPT statement.
Parent topic: The KEYBOARD Variable


CHECK-NUMBERS=value

Normally, ACUCOBOL-GT requires that numeric data be entered for numeric and numeric-edited fields that have the CONVERT phrase specified for them. If value is No, then any data can be entered and the runtime system will remove the non-numeric data from the user's input prior to converting. If value is set to Yes (the default), then a non-numeric entry will cause an error message to print and will force the user to re-enter the field. If value is set to Validate, the runtime system also checks to make sure that the numbers entered are valid, as described by the PICTURE clause for that field. The configuration variable KBD_CHECK_NUMBERS can also be used to set this value.

Parent topic: The KEYBOARD Variable


CURSOR-PAST-END=value

By default, ACUCOBOL-GT does not let the cursor leave the field where data is being entered. When the final position is entered, the cursor remains there and further entry is inhibited except for editing keys. Setting value to Yes allows the cursor to move one character past the end of the field instead. Input is still inhibited. The difference between the two modes is essentially cosmetic and CURSOR-PAST-END can be set to suit the user's taste. The default value is No. This value may also be specified with KBD_CURSOR_PAST_END.

Parent topic: The KEYBOARD Variable


DATA-RANGE=value

DATA-RANGE=value

value defines the range of legal input values. The default range is 32,65536 - this range covers all Unicode characters. The maximum range is 1,65536.

This value may also be set using the configuration variables KBD-DATA-RANGE-HIGH and KBD-DATA-RANGE-LOW. These are both integer values.

Important: In previous versions of extend, the variables could be set to byte values. If you use a character to set these variables, you now need to change how they are set.
Parent topic: The KEYBOARD Variable


EXCEPTION-RANGE=value

This is similar to the DATA-RANGE keyword except that value defines the range of characters that generate default exception handling. A key whose ASCII value falls within that range will terminate input with an exception condition value which matches the ASCII value of the key. That value is returned in the EXCEPTION clause or the CONTROL KEY clause of the ACCEPT statement. The default range is 1,31. A character in this range that is also defined by a KEYSTROKE variable acts as defined by that KEYSTROKE variable, and may or may not terminate the input. The configuration variables KBD_EXCEPTION_RANGE_HIGH and KBD_EXCEPTION_RANGE_LOW may also be used to set this value.

Note: If the same number(s) is included in both the DATA-RANGE and EXCEPTION-RANGE, then DATA-RANGE takes precedence.
Parent topic: The KEYBOARD Variable


IMPLIED-DECIMAL=value

If value is Yes, an implied decimal point is inserted in certain fields when the user does not explicitly type a decimal point. The last n digits of the user's input will be to the right of the decimal point, where n is the number of decimal places specified in the receiving field. For example, if the program is accepting a field with two decimal places, and the user types 1535, the value accepted (and echoed to the screen) will be 15.35. This is only done for numeric or numeric-edited fields that are input with conversion, either explicit or implicit. It never occurs for floating-point items. The default value is No. The configuration variable KBD_IMPLIED_DECIMAL is also supported.

Parent topic: The KEYBOARD Variable


RM-2-DEFAULT-HANDLING=value

RM/COBOL versions 2.1 and 2.2 have a configuration option that allows for ACCEPT fields that do not receive any input (for example, the user just types Return) to leave the receiving field unchanged. Normally, the receiving field would be filled with spaces. If the RM-2-DEFAULT-HANDLING value is Yes, then ACUCOBOL-GT will behave in this alternate fashion. You may also set this value using the variable KBD_RM_2_DEFAULT_HANDLING.

Note: This option is recommended only if you are converting programs written using this feature of RM/COBOL. Note that RM/COBOL-85 does not contain this feature, so only programs written for RM/COBOL version 2 should need to use it.
Parent topic: The KEYBOARD Variable


SCREEN-DEFAULT=value

If value is Yes, default data is taken from the screen for any ACCEPT statement that does not have a default value specified for it (either explicitly or implicitly). This will also allow for updating of the current screen contents. The default value is No. This option can also be specified using the configuration variable KBD_SCREEN_DEFAULT.

Parent topic: The KEYBOARD Variable


The KEYSTROKE Variable

The KEYSTROKE variable defines the actions to be taken for a single keystroke. You need to add one KEYSTROKE line for each key that you wish to redefine. The maximum number of allowed KEYSTROKE entries is 170.

KEYSTROKE entries consist of keywords and associated values that describe the action to be taken, plus the key code (a two-character name) of the key, or key combination, being defined. All definable keys have such a name. The key code is case sensitive, although the rest of the KEYSTROKE line is not. The ASCII value of the key (decimal) may be used instead of the key code. Note that this is the only way to assign a value to the DEL key (ASCII value 127). The syntax of the KEYSTROKE line is:

KEYSTROKE keyword=value [keyword=value] key-code

The key-code argument is one of the two-character codes shown in Table of Keys. Keywords are separated from each other by spaces or tabs. For example:

KEYSTROKE     EDIT=Next    TERMINATE=13    ^M

The following keywords may be used:

  • AT-END=value
  • DATA=value
  • EDIT=value
  • EXCEPTION=value
  • HOT-KEY=value
  • INVALID=value
  • TERMINATE=value
Parent topic: Redefining the Keyboard


AT-END=value

If value is Yes, the key becomes a termination key that also causes the AT END condition. This keyword may not be specified along with either the TERMINATE or EXCEPTION keywords. The AT END condition always returns a termination value of -1 in the CONTROL KEY clause. AT-END keystrokes are always allowed, but will cause no action unless an AT END, EXCEPTION, or CONTROL KEY clause is present in the ACCEPT verb. The default keyboard defines no AT-END keys. See also the AT END phrase of the ACCEPT verb in the ACUCOBOL-GT Reference Manual, Procedure Division.

Parent topic: The KEYSTROKE Variable


DATA=value

This keyword is used to assign special characters to keys. DATA associates a decimal ASCII value with a key; the Terminal Manager will return this value to the COBOL program when the key is pressed. If the DATA keyword is used, no other keywords may be specified for this key.

Parent topic: The KEYSTROKE Variable


EDIT=value

EDIT is used to define an editing action for a key. It must be assigned one of the following values:

Alt | Left
Auto-Insert | Menu
Backspace | Next
Default-Entry | Next-All
Default-Next | Next-Line
Delete | Numeric-Default
Down | Numeric-Next
End | Page-Down
Erase-All | Page-Up
Erase-EOS | Previous
Erase Field | Previous-All
Erase-Next | Previous-Line
Erase-to-End | Right
First | Switch-Window
Home | System-Menu
Insert-Off | Toggle-Edit-Mode
Insert-On | Toggle-Insert
Insert-Space | Up
Last |

The EDIT keyword values specify various editing functions, described below. EDIT keys may also be designated as termination keys. When they are, the EDIT is applied and then the input is terminated. This rule is slightly changed for the actions that move the cursor. With these actions, the field terminates only if the cursor cannot be moved farther in the requested direction. This is detailed in the descriptions of each of the EDIT values.

In the following descriptions, the order of fields is the order in which they appear in the Screen Section. Thus, the next field may not necessarily be the next one on the physical display. This feature can be used to design special purpose screens.

EDIT keyword values can be:

Alt When edit=alt is defined, the user must press the Alt key and the key letter in order to activate the desired control.

The character-based version of the runtime supports the use of key letters for operating controls. By default, if the program has key letters defined for its controls and if the program is currently accepting a control that doesn't allow user input, such as a push-button, checkbox or radio button, the user can move to the control by simply pressing its key letter key. When this happens the accept will be terminated. This default behavior can be changed by setting the runtime configuration variable NO_BARE_KEY_LETTERS to TRUE.

Auto-Insert | Auto-Insert causes all following characters to be entered in insert mode. Auto insert mode is automatically reset when the input terminates, or when any other editing key is typed. This style of insertion is the RM/COBOL-85 default method.
Backspace | The Backspace function moves the cursor to the left one character and deletes the character found there. If the Backspace function occurs at the left-most field position, it is ignored unless a TERMINATE or EXCEPTION value has been assigned to the key, in which case it is treated as a termination key.
Default-Entry | The Default-Entry action erases the remainder of the field starting at the cursor position provided that the cursor is not in the first position of the field. If the cursor is in the first position, this action does nothing. This editing action is intended to be tied to a termination key (such as the "Return" key or the "Tab" key), and to be used as a reasonable method of handling fields that contain default values. If the default is correct, then this key is typed (which does nothing to the field). If the default is wrong, then the correct value is entered and this key is typed (erasing the part of the old field after the new input).
Default-Next | Default-Next combines the Default-Entry action and the Next (described below) action.
Delete | Deletes the character that the cursor is on (if any).
Down | If there are fields below the current cursor location, the cursor moves to the one on the closest lower line. If there is more than one field on this line, the cursor will move to the one closest to its current horizontal location. The cursor will try to stay in the same column. If there are no fields beneath the current line, then this action does nothing unless an EXCEPTION or TERMINATE value has been assigned to it, in which case it acts as a termination key.
End | The cursor is moved to the end of the current field, excluding any trailing prompt characters. If the cursor is already at the end of the field, then this key is ignored unless it has a TERMINATE or EXCEPTION value, in which case it is treated as a termination key.
Erase-All All fields controlled by the ACCEPT statement are erased and the cursor is moved to the home position of the first field. This key may not be assigned a TERMINATE or EXCEPTION value.

Under Windows, the field in which the cursor is currently positioned is erased, instead of all fields controlled by the ACCEPT statement being erased.

Erase-EOS The current field is erased from the cursor location to the end of the field, and all fields following the current one are erased. The definition of "following field" is based on the order of fields in the Screen Section. This action may not be assigned a TERMINATE or EXCEPTION value.

Under Windows, the current field is erased from the cursor location to the end of the field, but the fields following the current one are not erased.

Erase-Field | The field is erased, and the cursor is moved to the first position of the field.
Erase-Next | This action combines the functions of the Erase-to-End action and the Next (described below) action.
Erase-to-End | This function erases the field from the current cursor position to the end of the field.
First | The cursor is moved to the beginning of the first field controlled by the ACCEPT statement. If the cursor is already in the first field, and the key has been assigned a TERMINATE or EXCEPTION value, then the ACCEPT terminates.
Home | The cursor is moved to the beginning of the field. If the cursor is already at the beginning and this key has been assigned a TERMINATE or EXCEPTION value, the ACCEPT terminates.
Insert-Off | If insertion mode is currently in effect, it is turned off; otherwise does nothing.
Insert-On | This causes all following characters to be entered in insert mode. This causes any trailing characters to be moved one space to the right before the added character is printed. Insertion mode stays in effect until explicitly reset by an Insert-Off, an Auto-Insert, or a Toggle-Insert action. Note that insertion mode stays in effect across multiple ACCEPT statements.
Insert-Space | A space character is inserted at the cursor position, moving trailing characters over one position.
Last The cursor moves to the end of the last field controlled by the ACCEPT statement. Trailing prompt characters in the last field are ignored in determining the end of the field. If this key has been assigned a TERMINATE or EXCEPTION value and the cursor is already in the last field, the ACCEPT terminates.

Under Windows, with TERMINATE and EXCEPTION value, if the cursor is at the last field, the ACCEPT does not terminate and the cursor stays at the current field.

Left The cursor is moved one position to the left; if it is already in the left-most field position, it moves to the end of the previous field. If the cursor is in the left-most position of the first field, the key is ignored unless it also has been assigned a TERMINATE or EXCEPTION value, in which case the ACCEPT terminates.

In the case of Windows, the left and right arrow keys move the cursor inside a field but do not act as terminators. Without TERMINATE and EXCEPTION value, if the cursor is in the leftmost position of the first field, the key is not ignored and the cursor is moved to the last field.

Menu | The key is defined as a Menu key. Pressing this key will cause a program-defined menu to appear on the screen.
Next | Under Windows, without TERMINATE and EXCEPTION value, if the cursor is in the last field, it moves to the first field, instead of moving to the end of the field.
Next-All The cursor moves to the beginning of the next field regardless of whether or not the next field has a Tab-Stop. Thus a key with the Next action will skip controls with the NO-TAB style, while a key with the "Next-All" action will not.

By default, the Down key is assigned the Next-All action. This makes the Down key behave more like it does in a common Windows program. Assign the Down keyword (described above) for a more traditional, text-mode behavior.

Next-Line | Next-Line functions the same as the Down action, except that the cursor always moves to the beginning of the left-most field on the new line (instead of maintaining the current cursor column).
Numeric-Default If the field is numeric, then this key acts just like the Default-Entry key. Typing this key at the first character position of a numeric field leaves the field unchanged and accepts the default value. Typing this key when the cursor is not in the first position causes erasure of the field from the cursor position to the end. This key allows the user either to accept the default or type over it without having to worry about blanking out the trailing portion of the field.

If the field is alphanumeric, then this action does not affect the field. Numeric-Default is usually made a termination key, so that typing it causes the ACCEPT to finish.

Numeric-Next If the field is numeric, then this key acts just like the Default-Next key. Typing this key at the first character position of a numeric field leaves the field unchanged, accepts the default value, and advances to the beginning of the next field. Typing this key when the cursor is not in the first position causes erasure of the field from the cursor position to the end. The cursor is then advanced to the beginning of the next field. This key allows the user either to accept the default or type over it without having to worry about blanking out the trailing portion of the field.

If the field is alphanumeric, then this key acts just like the Next key. It advances the cursor to the beginning of the next field and does not affect the current field.

Page-Down | This keyword sets the key that pages down a multiline entry field, list box, and combo box.
Page-Left | This keyword sets the key that scrolls left one page.
Page-Right | This keyword sets the key that scrolls right one page.
Page-Up | This keyword sets the key that pages up a multiline entry field, list box, and combo box.
Previous | The cursor moves to the beginning of the previous field. If the cursor is in the first field, it moves to the beginning of the field unless the key has been assigned a TERMINATE or EXCEPTION value, in which case it acts as a termination key instead.
Previous-All The cursor moves to the beginning of the previous field regardless of whether or not the previous field has a Tab-Stop. Thus a key with the "Previous" action will skip controls with the NO-TAB style, while a key with the "Previous-All" action will not.

By default, the Up key is assigned the Previous-All action. This makes the Up key behave more like it does in a common Windows program. Assign the Up keyword (described below) for a more traditional, text-mode behavior.

Under Windows, without TERMINATE and EXCEPTION value, if the cursor is in the first field, it moves to the last field, instead of moving to the beginning of the field.

Previous-Line | The cursor moves to the beginning of the left-most field on the next higher line. If there are no fields above the current one, this action does nothing unless it has an EXCEPTION or TERMINATE value, in which case it acts as a termination key.
Right This function moves the cursor one position to the right. This will not move the cursor onto any trailing prompt characters (exception: if the prompt character is a space and the field is being updated, the cursor will move over the trailing spaces).

If the cursor is as far right as it is allowed to go, it will move to the beginning of the next field. If there is no following field, this key is ignored unless a TERMINATE or EXCEPTION value has been assigned, in which case the ACCEPT terminates.

In the case of Windows, the left and right arrow keys move the cursor inside a field but do not act as terminators. Without TERMINATE and EXCEPTION value, if the cursor is as far right as it is allowed to go, the key is not ignored and moves to the first field. See Regarding Configuration Variables for more information.

Scroll-Left | This keyword sets the key that scrolls left one column.
Scroll-Right | This keyword sets the key that scrolls right one column.
Switch-Window | This keyword defines the key that, when pressed, causes the system to enter switch window mode. In this mode, the user can press any key to cycle through the modeless windows, with each window border highlighted until the Return key is pressed. Window switching order is from top to bottom.
System-Menu | Use the System-Menu function to define the key used to activate a floating window's system menu on a text-mode system.
Toggle-Edit-Mode | This keyword defines the key that can be used to toggle the presence of the combo box's drop-down list and the paged list box's search box.
Toggle-Insert | If insertion mode is currently in effect, it is turned off. Otherwise, insertion mode is turned on.
Up | If there are fields above the current cursor location, the cursor moves to the one on the closest higher line. If there is more than one field on this line, the cursor moves to the field closest to its current location. The cursor will try to stay in its current column. If there are no lines above the current line with active fields, then this key is ignored unless it has a TERMINATE or EXCEPTION value, in which case it acts as a termination key.
Parent topic: The KEYSTROKE Variable


EXCEPTION=value

The purpose of this keyword is to create an exception key. EXCEPTION assigns a decimal ASCII value to a key; the key becomes a termination key that also causes an exception condition. The assigned value is returned in the EXCEPTION clause or the CONTROL KEY clause of the ACCEPT statement. See the TERMINATE keyword below if you want to terminate input without causing an exception condition. Note that ACUCOBOL-GT inhibits exception keys when no EXCEPTION or CONTROL KEY clause is present in the ACCEPT statement, unless the program was compiled with the -Vx option.

Parent topic: The KEYSTROKE Variable


HOT-KEY=value

ACUCOBOL-GT offers two methods for assigning hot keys: the KEYSTROKE keyword HOT-KEY described here, and the HOT-KEY runtime configuration variable described in Appendix H. Either or both may be used, but the results are undefined if you assign the same key using both formats. The total number of hot-key entries defined by both methods cannot exceed 16.

A hot key is a key that is associated with a program, so that when the key is pressed, the corresponding program is run. value is the program name, which must be specified in single or double quotes if it is lowercase. The full configuration file entry looks like this:

KEYSTROKE HOT-KEY=program-name key-code

Pressing the key specified in key-code initiates execution of the program just as if it were named in a CALL statement. The key-code argument is one of the two-character key codes shown in Table of Keys. For example, there is a screen printing sample program named PRNTSCRN provided with ACUCOBOL-GT. If you want to be able to initiate that program just by pressing the keyboard's F11 key, add the following line to your configuration file:

KEYSTROKE HOT-KEY=PRNTSCRN U1

Hot keys are active only during Format 1 and Format 2 ACCEPT statements (these are the forms of the ACCEPT verb that allow the user to enter data at the keyboard). When the user presses a hot key, the current program status is saved, and the program associated with the hot key is run. When the hot-key program exits (via the EXIT PROGRAM statement), control is returned to the program that was running when the hot key was pressed. The hot-key function does not save the original contents of the screen. You can accomplish this by popping up a window in your hot-key program, and then closing the window just before you exit the hot-key program.

A hot-key program is automatically passed two parameters. The first parameter is PIC X(200). It contains an image of the data in the field that was being entered at the time the hot key was pressed. The second parameter is a COMP-1 field that contains the length of the field being entered. You can define the first parameter as a table that depends on the second parameter like this:

LINKAGE SECTION.
01  CURRENT-FIELD.
    03  OCCURS 1 TO 200 TIMES
        DEPENDING ON FIELD-SIZE   PIC X.

01  FIELD-SIZE   PIC S9(4) COMP-1.

You are not required to declare or use either of these parameters in your hot-key program; they are provided for convenience.

The hot-key program may modify its first parameter. Any modifications made are reflected in the field that was being entered when the hot-key program was called. You might use this capability to perform a look-up function and then return the value found to the field being entered. If you want to pass additional data to the hot-key program, use EXTERNAL DATA ITEMS.

When a hot-key program is started, the value of the RETURN-CODE special register is saved and then set to zero. The hot-key program may alter this value. When the hot-key program exits, the value of RETURN-CODE is checked. The following table shows the possible values and the action that the calling program will take:

Value | Action
0 | continue ACCEPT
>0 | generate exception if allowed
-1 | activate next field logic

If the value of RETURN-CODE is zero, then the calling program continues to a normal completion of the ACCEPT statement that was active when the hot key was pressed.

If the value is greater than zero, then the calling program acts as if an exception key (with that value) was pressed. This will terminate the ACCEPT statement if it is of a format that allows exception keys.

If the value is -1, then the ACCEPT statement will act as if a next field key were pressed by the user. This will cause the ACCEPT statement to proceed to the next field. If there are no more fields (or if there is only one field), then the ACCEPT statement will terminate with a termination value of zero. The hot-key program should not set RETURN-CODE to any negative value other than -1. Other negative values are reserved for future use by ACUCOBOL-GT.

In any case, after the RETURN-CODE value established by the hot-key program has been acted upon by the calling program, RETURN-CODE is restored to the value it held before the hot-key program was called.

If a hot-key program cannot be executed, an error message is displayed to the user, and control returns to the ACCEPT statement.

Up to two hot-key programs per process may be active at once.

Parent topic: The KEYSTROKE Variable


INVALID=value

If value is Yes, the key is ignored when it is typed. This keyword may not be specified with any other keywords.

Parent topic: The KEYSTROKE Variable


TERMINATE=value

This keyword is used to create a termination key. TERMINATE assigns a decimal ASCII value to a key; when the key is pressed, the ACCEPT is terminated and the assigned value is returned in the CONTROL KEY clause of the ACCEPT statement. TERMINATE does not cause the key to generate an exception condition when pressed; to define an exception key, use the EXCEPTION keyword instead.

Parent topic: The KEYSTROKE Variable


Table of Keys

The following tables list all of the keys that can be redefined. The tables list the key's full name, its two-character name (called the key code), and the corresponding key used on a Windows keyboard (not all keys listed can be redefined under Windows; see Note below). The key code is used in the terminal database file on UNIX and VMS systems to identify the corresponding key-sequence.

Note: On Windows systems, the alt key sequences, PrtSrcn, and F10 keys are directly handled by Windows and cannot be referenced in COBOL. A list of additional keys that can be redefined in Windows environments follows the table below.
Key | Key Code (terminal db file) | Windows Keyboard
Host's Backspace | ZB | BkSp
Host's Line-Kill | ZK | -
Cntrl-A - Cntrl-Z | ^A - ^Z | Ctl A-Z
Escape | ^[ | Esc
Control-\ | ^\ | Ctl-\
Control-] | ^] | Ctl-]
Control-^ | ^^ | Ctl-^
Control-_ | ^_ | Ctl-_
DEL | 127 | Ctl-BkSp
F1 - F10 | k1 - k0 | F1 - F10
F11 - F20 | K1 - K0 | Shft F1 - F10
Down Arrow | kd | Down
Home | kh | Home
Left Arrow | kl | Left
Right Arrow | kr | Right
Up Arrow | ku | Up
Insert Line | kA | Ctl-Ins
Tab Left | kB | Shft-Tab
Clear-to-End | kE | Ctl-End
Delete Line | kL | Ctl-Del
Page Down | kN | PgDn
Page Up | kP | PgUp
Cancel | Kc | -
Next Paragraph | Kd | Ctl-Down
Word Left | Kl | Ctl-Left
Word Right | Kr | Ctl-Right
Previous Paragraph | Ku | Ctl-Up
Exit | Kx | -
Attention | KA | -
Bottom | KB | Ctl-PgDn
Clear | KC | Ctl-Home
Command (Do) | KD | -
End | KE | End
Find | KF | -
Insert Character | KI | Ins
Page Left | KL | -
Mark (Select) | KM | -
Print | KP | -
Page Right | KR | -
Send | KS | -
Top | KT | Ctl-PgUp
Save | KV | -
Delete Character | KX | StateStateDel
Help | K? | -
User-defined keys 1 - 10 (1-6 on Windows) | U1 - U0 (U1-6 on Windows) | F11-F12; Shft-F11-F12; Ctl-F11-F12
User-defined keys 11-20 | A1 - A0 | Ctl-1 - Ctl-0

The following table lists mouse-action keys that can be referenced by a KEYSTROKE entry; this table has meaning only for graphical systems such as Windows. The table lists the mouse action, the corresponding key code, and the default exception value returned. See Using the Mouse in User Interface Programming for details on mouse handling.

Action | Key Code | Exception Value
Mouse moved | Mv | 80
Left button pushed | Ml | 81
Left button released | ML | 82
Left button double-clicked | M1 | 83
Middle button pushed | Mm | 84
Middle button released | MM | 85
Middle button double-clicked | M2 | 86
Right button pushed | Mr | 87
Right button released | MR | 88
Right button double-clicked | M3 | 89

The Host's Backspace and Line-Kill keys are not identified in the terminal database file. They are defined, instead, at the operating system level. The Backspace key is the key used to back up while you are typing command lines (usually either backspace or delete). The Line-Kill key is the one that is used to cancel an entire command line.

Control keys (Control plus another key) are not defined in the terminal database file. They are directly mapped by the runtime system to the corresponding control-key ASCII value. They can be referred to by either their ASCII value or by the key code listed. The DEL key does not have a key code; it can be referred to only by its ASCII value (127).

Some keys may have more than one name. When this occurs, the names have the following precedence:

  1. Host name
  2. Terminal database file name
  3. Control-key name (if applicable)

For example, if a terminal whose left arrow key produces a Control-H is being used, and Control-H is the system's backspace key, that key would be treated as a Host's Backspace key (ZB). If the host's backspace were redefined (by operating system command) to be some other key, then this key would be considered a Left Arrow key (kl). It would be considered a Control-H (^H) only if the terminal database file were edited and the kl definition changed or removed.

Parent topic: Redefining the Keyboard


Additional Windows Keys

In addition to the keys listed in Table of Keys, these extra keys are available for 32-bit Windows systems:

Key | Key Code
Ctl-Ins (Insert Line) | kA
Ctl-Del (Delete Line) | kL
  • User-defined keys
  • Keys that Cannot be Defined
Parent topic: Redefining the Keyboard


User-defined keys

User-defined keys 1 - 6 (U1 - U6):

Key | Key code
F11 | U1
F12 | U2
Shft-F11 | U3
Shft-F12 | U4
Ctl-F11 | U5
Ctl-F12 | U6

User-defined keys 11 - 20 (A1 - A0):

Key | Key code
Ctl-1 | A1
Ctl-2 | A2
Ctl-3 | A3
Ctl-4 | A4
Ctl-5 | A5
Ctl-6 | A6
Ctl-7 | A7
Ctl-8 | A8
Ctl-9 | A9
Ctl-0 | A0

Several function key combinations can also be redefined. These keys have no specified default action and the key combinations are recognized by the Windows keyboard driver only after they are assigned a definition.

Key | Key code
Alt-F1 | a1
Alt-F2 | a2
Alt-F3 | a3
Alt-F5 | a5
Alt-F7 | a7
Alt-F8 | a8
Alt-F9 | a9
Alt-F10 | a0
Alt-F11 | U7
Alt-F12 | U8
Shift-Ctl-F1 | S1
Shift-Ctl-F2 | S2
Shift-Ctl-F3 | S3
Shift-Ctl-F4 | S4
Shift-Ctl-F5 | S5
Shift-Ctl-F6 | S6
Shift-Ctl-F7 | S7
Shift-Ctl-F8 | S8
Shift-Ctl-F9 | S9
Shift-Ctl-F10 | S0
Shift-Ctl-F11 | U9
Shift-Ctl-F12 | U0
Note: Alt-F4 and Alt-F6 are reserved for use by Windows and are not included in the table. Shift-Ctl-F10 may be used only if the configuration option F10_IS_MENU is set to false. When F10_IS_MENU is set to the default of true, then Shift-Ctl-F10 activates context menus (for example, a control's drop-down menu).
Parent topic: Additional Windows Keys


Keys that Cannot be Defined

Alt key sequences (except as noted in the preceding table), PrtSrcn, and F10 are directly handled by 32-bit Windows and cannot be referenced in COBOL. You can free the F10 key to act as a user defined key by using a configuration variable. Setting the F10_IS_MENU variable to 0 inhibits the standard menu activation capability for the F10 key. See Appendix H for more details.

Parent topic: Additional Windows Keys


Special Keys

The following keys deserve special attention.

  • Arrow Keys
  • Backspace vs. Left Arrow
  • Interrupt Key
Parent topic: Redefining the Keyboard


Arrow Keys

The left and right arrow keys can be configured to meet a variety of needs.

  1. As exception keys only. In this case, typing an arrow key will cause an ACCEPT to terminate immediately with the arrow-key exception value. The program can then take the appropriate action (such as moving a highlight in the requested direction). To configure an arrow in this manner, define an EXCEPTION value for it with the KEYSTROKE runtime configuration variable.
  2. As edit keys only. In this case, the arrows will move the cursor within the ACCEPT field, but will not move outside the boundaries of the field. In this mode, the arrow key will never terminate the ACCEPT. To configure an arrow in this manner, define the appropriate EDIT value for it with the KEYSTROKE runtime configuration variable.
  3. As both exception keys and edit keys. In this mode, the arrows will act as edit keys within the ACCEPT field, but will act as exception keys when the user tries to move outside the field. This can be useful if you are writing a fill-in-the-form style of application. To configure an arrow in this manner, define both an EXCEPTION and an EDIT value for it.

By default, the left and right arrows act as edit keys, and the up and down arrows act as both edit and exception keys. You can change the behavior of the arrows at run time to switch between different modes if you need to. You do this via the SET ENVIRONMENT verb and the appropriate KEYSTROKE settings. For example, to configure the left arrow to act as an editing key from within a program, use:

SET ENVIRONMENT "KEYSTROKE" TO "EDIT=Left kl"
Parent topic: Special Keys


Backspace vs. Left Arrow

On some terminals, the Backspace and Left Arrow keys send the same hardware signal. If so, ACUCOBOL-GT's key naming rules will treat both as a (destructive) Backspace, because the host name takes precedence. You can deal with this situation in one of several ways; some possibilities are:

  1. If you do not use the Left Arrow key as anything other than an edit key, you can probably just use the defaults. You will not have the Left Arrow capability, but most users prefer to have destructive Backspace instead. Alternatively, if you prefer to have Left Arrow instead of destructive Backspace you can, with a KEYSTROKE variable, define the Backspace key to have the "Left" edit action.
  2. If you use the Left Arrow as an exception key, then you can leave the destructive backspace action on the Backspace key and also give it an exception code value. This will cause the Backspace key to act as a destructive backspace while the cursor is in an ACCEPT field. The Left Arrow exception value will be returned when the user backspaces off the left edge of the field.
  3. Finally, you can use operating system commands to assign the host's Backspace key to another key. This will then cause the Backspace key to be recognized as a Left Arrow key while the other key will take on the characteristics of the Backspace key. If you wish to do this, a common key to use as the alternate Backspace key is the Rub Out (or DEL) key.

Other combinations exist, but this should give you a general idea of ways to address this issue.

Parent topic: Special Keys


Interrupt Key

ACUCOBOL-GT has no way of defining a key to be the asynchronous interrupt key. ACUCOBOL-GT makes use of the host's definition for this key. This has two effects:

  1. If you want to define a special asynchronous interrupt key, you must do so at the operating system level.
  2. Whichever key is used as the Interrupt key will be unavailable to you as a normal key. This is because the host operating system acts on this key prior to ACUCOBOL-GT's ever receiving it. ACUCOBOL-GT sees an interrupt when this key is typed; it never receives a character for it.
Parent topic: Special Keys


Default Keyboard

The default ACUCOBOL-GT keyboard is defined below in the language of the KEYBOARD and KEYSTROKE runtime configuration variables.

KEYBOARD | Data-range=32,255 |
KEYBOARD | Exception-range=1,31 |
KEYBOARD | Auto-Return=0 Screen-Default=No |
KEYBOARD | RM-2-Default-Handling=No |
KEYBOARD | Check-Numbers=Yes |
KEYBOARD | Cursor-Past-End=No |
KEYSTROKE | Terminate=13 | ^M
KEYSTROKE | Edit=Next Terminate=9 | ^I
KEYSTROKE | Edit=Previous | kB
KEYSTROKE | Edit=Backspace | ZB
KEYSTROKE | Edit=Erase-Field | ZK
KEYSTROKE | Edit=First | kh
KEYSTROKE | Edit=Last | KE
KEYSTROKE | Edit=Auto-Insert | KI
KEYSTROKE | Edit=Delete | KX
KEYSTROKE | Edit=Erase-Field | KC
KEYSTROKE | Edit=Erase-to-End | kE
KEYSTROKE | Edit=Left | kl
KEYSTROKE | Edit=Right | kr
KEYSTROKE | Edit=Up Exception=52 | ku
KEYSTROKE | Edit=Down Exception=53 | kd
KEYSTROKE | Exception=67 | kP
KEYSTROKE | Exception=68 | kN
KEYSTROKE | Exception=40 | KD
KEYSTROKE | Exception=90 | K?
KEYSTROKE | Exception=1 | k1
KEYSTROKE | Exception=2 | k2
KEYSTROKE | Exception=3 | k3
KEYSTROKE | Exception=4 | k4
KEYSTROKE | Exception=5 | k5
KEYSTROKE | Exception=6 | k6
KEYSTROKE | Exception=7 | k7
KEYSTROKE | Exception=8 | k8
KEYSTROKE | Exception=9 | k9
KEYSTROKE | Exception=10 | k0
KEYSTROKE | Exception=11 | K1
KEYSTROKE | Exception=12 | K2
KEYSTROKE | Exception=13 | K3
KEYSTROKE | Exception=14 | K4
KEYSTROKE | Exception=15 | K5
KEYSTROKE | Exception=16 | K6
KEYSTROKE | Exception=17 | K7
KEYSTROKE | Exception=18 | K8
KEYSTROKE | Exception=19 | K9
KEYSTROKE | Exception=20 | K0
Parent topic: Redefining the Keyboard


Keyboard Modification Examples

Following are examples of some common modifications to the default keyboard settings.

In the default keyboard, the Tab key is used to move from one field to the next. The Return key is used to terminate the ACCEPT. If you want the Return key to move the user to the next field instead of immediately terminating the ACCEPT, the following entry in the runtime configuration file will cause that to happen:

KEYSTROKE    EDIT=Next    TERMINATE=13    ^M

Alternately, you might want the Return key to clear the part of the field that follows the cursor. If you want to do this along with the previous modification, you can use either of these entries:

KEYSTROKE    EDIT=Erase-Next     TERMINATE=13    ^M
KEYSTROKE    EDIT=Default-Next   TERMINATE=13    ^M

These two lines have slightly different methods of handling how the field is cleared. The first version always erases the field from the current cursor location to the end. The second form does this only if the cursor is not in the home position of the field. You can also use the actions Erase-to-End or Default-Entry if you do not want the Return key to act as a next field key.

Parent topic: Redefining the Keyboard


The Display Interface

The Terminal Manager's keyboard interface has been discussed above. The display interface can also be configured. Its task is to implement, for a particular terminal, those program instructions that specify display attributes. You can accomplish most desired display options by defining, in the terminal database file, the actions that terminal function codes will take. You can specify some other display options by assigning values to special keywords in the ACUCOBOL-GT runtime configuration file.

The steps listed below describe, in a simplified way, the overall process from COBOL statement to screen display:

  • Function code generation
    • The COBOL program sends output to the screen. (For example, the COBOL statement might be: DISPLAY data-item HIGH.)
    • The runtime configuration file may specify an attribute for the DISPLAY keyword. (Continuing with the example, the configuration file might include this entry: COLOR-MAP High=Blue.)
    • The Terminal Manager maps the COBOL attributes to terminal function codes. (High=HI Blue=C2)
  • Function code interpretation
    • The terminal database file maps the function codes to a hardware signal. (HI=\E[0;1m C2=\E[34m)
    • The Terminal Manager sends a hardware signal to the screen. (\E[0;1m \E[34m)
  • Final result
    • The display function is executed. (The data item characters are displayed at high intensity in blue.)

Restricted Attribute Handling also describes the runtime configuration file options. The terminal database file function codes and values are described in The Terminal Database File.

  • Adding Color
  • The SCREEN Option
  • Additional Configuration Variables
  • Double-Byte Character Handling
Parent topic: Terminal Manager
Parent topic: Setting up your Terminals


Adding Color

ACUCOBOL-GT allows you to add color, without reprogramming, to programs that were originally written for black-and-white terminals. You accomplish this by assigning color values to the runtime configuration variable COLOR-MAP . The COLOR-MAP keyword is followed by one of the following single attributes:

High, Low, Reverse, Blink, Underline, Default, or Exit;

or by one of the following hyphenated combinations of attributes:

High-Reverse | Low-Reverse
High-Blink | Low-Blink
High-Reverse-Blink | Low-Reverse-Blink
High-Underline | Low-Underline
High-Reverse-Underline | Low-Reverse-Underline
Reverse-Blink | Reverse-Underline

The single attribute, or attribute combination, is then followed by an equals sign and one of the following color names:

Black, Blue, Green, Cyan, Red, Magenta, Brown, White

The named color becomes the foreground color that is displayed whenever the corresponding attribute is used in a DISPLAY statement. For example, if you want fields that are displayed as low-intensity to appear green, use the following configuration file entry:

COLOR-MAP   Low=Green

You can also assign a background color value. It follows the foreground color and is separated from it by a comma. For example, to assign white characters on a blue background for high-intensity fields, you would use the following:

COLOR-MAP   High=White,Blue
Note: No spaces should appear within the assignment.

You may specify more than one attribute in a single COLOR-MAP line. Simply separate the attributes from each other by spaces. For example:

COLOR-MAP  High=Green  Low=Red  Reverse=Blue

The following points should be noted:

  1. The named video attribute is still used by the ACCEPT or DISPLAY. For example, Reverse=Blue will result in a reverse-video blue field while High=Brown will use high-intensity brown (on some terminals, specifying High=Brown will cause yellow to be generated by any DISPLAY HIGH phrase).
  2. If a particular ACCEPT or DISPLAY statement has a COLOR phrase, that phrase will be used instead of the COLOR-MAP attributes in the runtime configuration file. Note, however, that the COLOR-MAP will apply to fields that use the FCOLOR or BCOLOR options of the CONTROL phrase.
  3. The attributes HIGH, LOW, and REVERSE are treated in a special manner. If a statement uses more than one of the three, then the attribute/color used will be in this order of preference:
    1. REVERSE
    2. HIGH
    3. LOW

    For example, a DISPLAY statement specifying both REVERSE and HIGH will use the color associated with REVERSE.

    Also, any one of these settings is used for all applicable cases, except where specifically overridden by another setting. For example:

    COLOR-MAP   REVERSE=Red  LOW-REVERSE=Blue

    will use red for all statements that specify REVERSE except for statements that explicitly specify REVERSE,LOW.

    In all other cases, the configuration variable must exactly match the COBOL statement. For example, a configuration file attribute HIGH-REVERSE would not apply to a program statement that included HIGH,REVERSE,UNDERLINE.

    Note that compiler options -Vl and -Vh cause LOW and HIGH respectively to be implied for program statements; create your COLOR-MAP as though LOW or HIGH were explicitly coded in the program.

  4. The DEFAULT attribute works a little differently. It is used to assign the initial default colors for the screen. Its effect is the same as having a DISPLAY WINDOW COLOR statement as the first statement of your program.
  5. The EXIT attribute determines which colors ACUCOBOL-GT will set when it terminates. These colors are also set when a call is made to the SYSTEM library routine. On some machines these colors are immediately changed by the operating system prompt and thus have no effect.
  6. You can assign values to the color map from within a COBOL program through use of the SET ENVIRONMENT verb. You can turn off the color map with the following statement:
    SET  ENVIRONMENT  "COLOR-MAP"  TO  "OFF"
  7. Note that on a XENIX console, if you use the XENIX command setcolor to establish a high-intensity background color, you may get unexpected results from ACUCOBOL-GT. This is because the implementation of high-intensity background colors causes XENIX to treat the blink bit as a background intensity bit instead. In addition, because ACUCOBOL-GT can select only 8 background colors, all of the background colors used will be high-intensity, including black (which shows up as a light gray).

    For these reasons, we recommend that you avoid using a high-intensity background color if you are using the XENIX console. As an alternative, you may create a shell script to run ACUCOBOL-GT. This script could set a low-intensity background color, run ACUCOBOL-GT, and then reset the desired high-intensity background color.

Parent topic: The Display Interface


The SCREEN Option

There is a runtime configuration variable called SCREEN that controls many features of the video sub-system. This option works in the same manner as the KEYBOARD variable. You can specify one or more SCREEN variables. Attributes that you can set are identified by one or more sets of keywords and associated values, separated from each other by spaces or tabs; the syntax is:

SCREEN keyword=value [keyword=value]...

The following keywords are supported:

ALPHA-UPDATES=value | CONVERT-OUTPUT=value
EDITED-UPDATES=value | ERROR-BELL=value
ERROR-BOX=value | ERROR-COLOR=value
ERROR-LINE=value | FORM-FEED=value
INPUT-DISPLAY=value | INPUT-MODE=value
JUSTIFY=value | NUMERIC-UPDATES=value
PROMPT=value | PROMPT-ALL=value
PROMPT-ATTR=value | REFRESH-LINES=value
REFRESH-MODE=value | SHADOW-STYLE=value
SIZE=value | WINDOW=value

These keywords are described in detail below.

  • ALPHA-UPDATES=value
  • CONVERT-OUTPUT=value
  • EDITED-UPDATES=value
  • ERROR-BELL=value
  • ERROR-BOX=value
  • ERROR-COLOR=value
  • ERROR-LINE=value
  • FORM-FEED=value
  • INPUT-DISPLAY=value
  • INPUT-MODE=value
  • JUSTIFY=value
  • NUMERIC-UPDATES=value
  • PROMPT=value
  • PROMPT-ALL=value
  • PROMPT-ATTR=value
  • REFRESH-LINES=value
  • REFRESH-MODE=value
  • SHADOW-STYLE=value
  • SIZE
  • WINDOW=value
  • SCREEN Examples
Parent topic: The Display Interface


ALPHA-UPDATES=value

This option affects how alphanumeric fields with a default value are displayed prior to entry. It works just like the EDITED-UPDATES option (described below) except that it applies to alphanumeric fields instead of numeric edited fields. The only acceptable value is Unchanged.

Placing Auto-Prompt immediately after this option, using a comma as a separator, allows the user to decide whether to change or replace the default value. When Auto-Prompt is specified, the default value will be displayed, and then the program will wait for the user to enter a character. If the character entered is a data character, ACUCOBOL-GT will fill the field with prompt characters (erasing what was there) and then accept data as if this were a new field. If the character entered is an editing character (such as an arrow key), then ACUCOBOL-GT allows the user to edit the data normally. Sample syntax is shown here:

SCREEN  ALPHA-UPDATES=Unchanged, Auto-Prompt

This option can also be specified as SCRN_ALPHA_UPDATES. The Auto-prompt value can be specified with SCRN_ALPHA_AUTO_PROMPT. For example, to set the above syntax using these variables, you would enter:

SCRN_ALPHA_UPDATES Unchanged
SCRN_ALPHA_AUTO_PROMPT on
Parent topic: The SCREEN Option


CONVERT-OUTPUT=value

This option affects only Screen Section DISPLAY statements. If this keyword is set to Yes, then all output fields will act as if the WITH CONVERSION phrase were specified for them. This has two effects. The first is that numeric fields will be converted from the internal storage format to a readable form (including suppression of leading zeros). The second is that the action of the JUSTIFY keyword (see below) takes effect. This option is normally set to No, but is provided as an alternate method of displaying numeric data in the Screen Section. The configuration variable SCRN_CONVERT_OUTPUT is synonymous with this option.

Parent topic: The SCREEN Option


EDITED-UPDATES=value

This option affects how numeric edited fields with a default value are displayed prior to the user making an entry. The four possible values are:Converted, Unchanged, Left-Adjust, and Formatted.

Converted | is the default setting. When this setting is used, the default value is displayed in a standardized format. This format has an optional leading minus sign, followed by the number, with no leading zeros and no internal formatting characters.
Unchanged | is an alternate setting. When this setting is used, the default value is displayed without any changes. All of the editing characters appear, and leading spaces are shown. Note that the LEFT, RIGHT, or CENTER phrase will affect the display. After the value has been displayed, the user can edit it normally.
Left-Adjust | is identical to Unchanged, except that any leading spaces are removed before the value is displayed.
Formatted | is fundamentally different from the other options in that it affects the way the number is entered, not just the format of the default value. When Formatted entry is selected, the number is continuously reformatted by the ACCEPT statement to match the editing specification of the item being entered. This means that the value will always appear to the user in its "final" form. This is similar to the way numbers are entered on most calculators. Selecting this option has many minor affects on the actions of various editing keys. These are not detailed here, but the actions of the editing keys are analogous to their actions on non-formatted fields.

There is one exception to the rule that the number will always be formatted just as described by the PICTURE clause. This is when Z or * characters are placed after the decimal point in the PICTURE. In this case, the entered characters will be treated like 9 characters instead. This is necessary in order to allow the user to enter values between zero and 1 when the default value is zero. If this rule did not exist, then when the user tried to enter the decimal point, the reformatter would keep removing it. The same applies to any zero digits between the decimal point and the first non-zero digit.

When the Formatted option is used with left justification, the entry action is also left justified. When it is used with the centering option, the entry occurs as if the field were right justified, and the final result is centered when the user leaves the field.

Place Auto-Prompt immediately after this option, using a comma as a separator, to allow the user to decide whether to change or replace the default value. When Auto-Prompt is specified, the default value will be displayed, and then the program will wait for the user to enter a character. If the character entered is a data character, ACUCOBOL-GT will fill the field with prompt characters (erasing what was there) and then accept data as if this were a new field. If the character entered is an editing character (such as an arrow key), then the program allows the user to edit the data normally. Sample syntax is shown here:

SCREEN EDITED-UPDATES=Converted, Auto-Prompt

This option can also be specified as SCRN_EDITED_UPDATES. The Auto-prompt value can be specified with SCRN_EDITED_AUTO_PROMPT.

Parent topic: The SCREEN Option


ERROR-BELL=value

This option determines when the error bell will be sounded. Possible values are:

Yes: | ring the bell on an entry error, but not on field-full. This is the default setting.
No: | do not ring the bell on entry error or field-full.
All: | ring the bell whenever the user makes an entry error or attempts to enter data into a full field.

For example, to use the All setting, add the following line to your runtime configuration file:

SCREEN  ERROR-BELL=All

You may also use the configuration variable SCRN_ERROR_BELL to set these values. The variable SCRN_WARN is synonymous with SCREEN ERROR-BELL=All.

Parent topic: The SCREEN Option


ERROR-BOX=value

This option affects whether an error box appears when an entry error has occurred. Examples of entry errors are entering a letter in a numeric field or entering a number in the wrong format. When value is set to yes (the default), the error message is displayed in a box. If value is set to no, the error is reported based on the entry in the SCREEN ERROR-LINE variable (below). The configuration variable SCRN_ERROR_BOX may also be specified.

Parent topic: The SCREEN Option


ERROR-COLOR=value

This keyword is given a numeric value that represents the colors used in error messages generated by the runtime system. Value is the arithmetic sum of the numbers representing the colors and other attributes used in error messages generated by the runtime system. The following color values are accepted:

Color | Foreground | Background
Black | 1 | 32
Blue | 2 | 64
Green | 3 | 96
Cyan | 4 | 128
Red | 5 | 160
Magenta | 6 | 192
Brown | 7 | 224
White | 8 | 256

You may specify other video attributes by adding the following values:

Reverse video | 1024
Low intensity | 2048
High intensity | 4096
Underline | 8192
Blink | 16384
Protected | 32768

Only one foreground color and one background color may be specified. If either is missing, the corresponding default for the current terminal window is used. High intensity and low intensity may not both be specified. If neither is specified, the default intensity is used.

For example, to get a blinking white foreground on a blue background, you would specify:

SCREEN   ERROR-COLOR=16456
(16456 = 8+64+16384)

The default value is 4096, which causes the error messages to use the current colors with a high-intensity foreground. The configuration variable SCRN_ERROR_COLOR is also supported.

Parent topic: The SCREEN Option


ERROR-LINE=value

Value is the line number you wish error messages to appear on. The runtime system pops up a one-line window on this line to display the message, and then removes it after the user responds. If this is set to a negative value, then the line used will be that many lines up from the bottom of the screen. For example, Error-Line=-2 implies that the next-to-last line should be used. The default value is -1. You may also specify the configuration variable SCRN_ERROR_LINE to set this value.

Parent topic: The SCREEN Option


FORM-FEED=value

This option lets you use Control-L for a form feed. Setting this variable to yes and putting Ctl-L in a DISPLAY statement allows a form feed to occur. In effect, this clears the screen and puts the cursor at screen position (0,0). Setting this variable to no disallows a form feed. The default value is no. This can also be specified as SCRN_FORM_FEED instead of SCREEN FORM-FEED.

Parent topic: The SCREEN Option


INPUT-DISPLAY=value

This option determines what happens when the DISPLAY verb operates on an input field described in a Screen Section entry. There are four choices: None, Value, Spaces, and Prompt.

None: | The field is not displayed.
Prompt: | The field is displayed with the field's prompt character (usually underscore).
Spaces: | The field is displayed as spaces. This is the default value.
Value: | The current value of the field is displayed. This will be zero for numeric and numeric-edited fields, and spaces for other fields.

The configuration variable SCRN_INPUT_DISPLAY is also supported.

Parent topic: The SCREEN Option


INPUT-MODE=value

This option affects pre-display of data in a Screen Section ACCEPT. The options are Predisplay, Update, and StateStateNormal.

Predisplay: | A Screen Section ACCEPT statement will cause the current value of each input and update field to be displayed. (Whatever is present in the Screen Section is displayed; this is not necessarily the same as the contents of Working-Storage). Each field is then entered as an update field (i.e., the value can be edited).
Update: | Each input field is treated as an update field. This causes the field's current value to echo on the screen when the field is visited.
Normal: | Causes no echoing of input-only fields.

You may also specify the configuration variable SCRN_INPUT_MODE.

Parent topic: The SCREEN Option


JUSTIFY=value

The JUSTIFY setting determines the default justification of converted numeric and numeric-edited fields. If Left is chosen, then leading spaces are removed from these fields when they are displayed. If Right is chosen, then the leading spaces are retained. Finally, if Auto is chosen (the default), then left justification is used if the program was compiled in RM/COBOL compatibility mode, otherwise right justification is used. Note that justification affects only fields that have the CONVERT phrase specified or implied for them. The configuration variable SCRN_JUSTIFY is also supported.

Parent topic: The SCREEN Option


NUMERIC-UPDATES=value

This option affects how numeric fields with a default value are displayed prior to entry. This option works just like the EDITED-UPDATES option described above except that it applies to numeric fields instead of numeric edited fields. The possible values are Converted and Unchanged.

Place the phrase Auto-Prompt immediately after this option, using a comma as a separator, to allow the user to decide whether to change or replace the default value. When Auto-Prompt is specified, the default value will be displayed, and then the program will wait for the user to enter a character. If the character entered is a data character, ACUCOBOL-GT will fill the field with prompt characters (erasing what was there) and then accept data as if this were a new field. If the first character entered is an editing character (such as an arrow key), then ACUCOBOL-GT allows the user to edit the data normally. Sample syntax is shown here:

SCREEN NUMERIC-UPDATES=Converted, Auto-Prompt

This option can also be specified as SCRN_NUMERIC_UPDATES. The Auto-prompt value can be specified with SCRN_NUMERIC_AUTO_PROMPT.

Parent topic: The SCREEN Option


PROMPT=value

The value of the PROMPT setting determines the default prompt character. The default value is underscore. To specify an alternate prompt, place the character immediately after the equals sign. To specify a space as the prompt character, leave the value empty (e.g., Prompt= ). You may also specify the configuration variable SCRN_PROMPT to set this value. The variable SCRN_PROMPT_DEFAULT is equivalent to setting SCREEN PROMPT to the default value.

Parent topic: The SCREEN Option


PROMPT-ALL=value

By default, a prompt character is shown only in the field containing the cursor. If value is Yes, then the prompt character is shown in every field managed by the ACCEPT statement. The prompt characters are removed when the ACCEPT is terminated. Prompts never appear in SECURE fields. Default is No. The configuration variable SCRN_PROMPT_ALL is synonymous with this option.

Note: Setting the SCREEN keyword PROMPT-ALL to the value Protected will have the same effect as setting PROMPT-ALL to Yes, except that prompt characters will not be displayed in protected fields.
Parent topic: The SCREEN Option


PROMPT-ATTR=value

You may specify a prompt attribute. This attribute is used whenever the PROMPT is specified or implied for a Screen Section ACCEPT statement. The PROMPT-ATTR keyword is followed by a single attribute: High, Low, or Reverse. For example:

SCREEN PROMPT-ATTR=HIGH

The configuration variable SCRN_PROMPT_ATTR is also supported. The usage is:

SCREEN_PROMPT_ATTR HIGH
Parent topic: The SCREEN Option


REFRESH-LINES=value

Value specifies the number of screen lines to redisplay after the user has finished entering data into a field. This option is useful when the terminal or terminal emulator can accept Asian phonetic characters and translate them into ideograms. The entered characters will often overflow the displayed input field, but after translation, the resultant ideogram(s) will not. This option will clean up the screen by redisplaying the affected lines with the ideograms in place. For example:

SCREEN   REFRESH-LINES=3

After accepting input data, the Terminal Manager will redisplay the contents of the input field, the remainder of the line, and the two lines below it. If the CODE_SYSTEM runtime configuration variable is non-zero, specifying an Asian double-byte character system, the default value of REFRESH-LINES is 1. See Double-Byte Character Handling for more information.

If the CODE_SYSTEM runtime configuration variable is set to 0, indicating a single-byte ASCII or EBCDIC character system, the default value of REFRESH-LINES is 0. You may also use the configuration variable SCRN_REFRESH_LINES to set these values.

Parent topic: The SCREEN Option


REFRESH-MODE=value

This option, like REFRESH-LINES, supports double-byte character sets. value specifies when lines should be refreshed after an ACCEPT. Setting this variable to a value of 0 means that the lines are never refreshed, 2 indicates that lines are always refreshed. The default value of 1 specifies that lines are refreshed only if double-byte characters are entered. For example:

SCREEN REFRESH-MODE=1

The configuration variable SCRN_REFRESH_MODE is synonymous with this option.

Parent topic: The SCREEN Option


SHADOW-STYLE=value

This option determines the way window shadows are displayed. It may have one of the following four values:

None: | When this setting is used, shadows are not displayed.
Dim: | This setting displays a one-character border around the right and bottom edges of the window. This border displays the underlying data in low-intensity with a white foreground and a black background; in effect, the border is translucent. This border looks best when the shadowed window and the window it overlays do not both have black backgrounds.
Black: | This setting displays a black border on the right and bottom edges of the window. On the right edge, this border is one character wide. On the bottom edge, the border is one-half character high. This gives a fairly uniform appearance to the border. The border depends on the existence of an "upper-half" block character on the display device. For machines that use a terminal database file, this character should be specified as the 12th character in the GM code in the terminal database file (GM defines the various graphics characters). Also, we recommend that you specify a "lower-half" character as the 13th GM character. If such characters do not exist, then the bottom border is a full character high. The Black setting is the default shadow style.
Lines: | This setting causes the right and bottom edges to be shown with a border made from the line drawing set. This setting is not as appealing as the Dim or Black settings when color or reverse-video backgrounds are being used. When the background is black, however, this setting is preferable to the other two.

The configuration variable SCRN_SHADOW_STYLE is also supported.

Parent topic: The SCREEN Option


SIZE

This keyword has meaning only on graphical systems such as Windows. It is used to change the default virtual screen size. Value is the desired number of rows and columns, separated by a comma.

For example, to set the initial virtual screen size to 30 rows by 80 columns, you would make the following entry:

SCREEN    SIZE=30,80

The comma is required.

The size of your virtual screen is independent of the size of the application window or the underlying hardware. In other words, the virtual screen can be larger than the physical screen. You may set any screen size up to a maximum of 100 rows and 200 columns. If you do not specify a size, the default is 25 rows and 80 columns. You may also use the configuration variables SCRN_SIZE_COLS and SCRN_SIZE_ROWS to set this option.

The SIZE option sets only the initial screen size. After the application begins, the screen size can be changed with the DISPLAY SCREEN SIZE verb.

If the virtual screen is too large to be fully displayed on the physical screen, the user will have to scroll to view all of the rows and columns.

Parent topic: The SCREEN Option


WINDOW=value

This keyword has meaning only on graphical systems such as Windows. Normally, the initial size of an application's window is determined by the host. You can change this initial size with the WINDOW keyword. Value is the desired number of rows and columns, separated by a comma.

For example, if you wanted your initial window to contain 10 rows and 70 columns, you would enter:

SCREEN   WINDOW=10,70

The WINDOW configuration option has several special values that it recognizes. If either the row or column is set to a negative number, then the initial window is minimized (turned into an icon). If either value is set to "999" or larger, then the initial window is maximized instead. Finally, if either value is zero, then the initial window size is determined by the host system (this is the default).

The application window size may never be bigger than the virtual screen size, nor may the window size be larger than what can be physically displayed on the user's screen. This physical limit will change depending on the resolution of the user's screen and the size of the font you are using. The ACUCOBOL-GT runtime system will automatically reduce the requested window size to meet these limits.

You may enter the SIZE and WINDOW options on the same line. For example, if you wanted your application to be able to use 30 lines by 80 columns, and you wanted to start with the window maximized (thus showing the entire virtual screen), you would enter:

SCREEN   SIZE=30,80   WINDOW=999,999
Note: The SIZE and WINDOW options set only the initial screen and window size. After the application begins, the user is free to change the window size with various system controls, and the application is free to change the screen size with the DISPLAY SCREEN SIZE verb.

The configuration variables SCRN_WINDOW_X and SCRN_WINDOW_Y are also supported for this option.

Parent topic: The SCREEN Option


SCREEN Examples

The following sample recaps the default settings and provides an example of how to specify SCREEN configuration entries.

SCREEN | Convert-Output=No
SCREEN | Edited-Updates=Converted, Auto-Prompt
SCREEN | Error-Bell=Yes
SCREEN | Error-Color=4096 Error-Line=-1
SCREEN | Input-Display=Spaces Input-Mode=Normal
SCREEN | Prompt=_ Justify=Auto
SCREEN | Numeric-Updates=Converted, Auto-Prompt
SCREEN | Alpha-Updates=Unchanged
SCREEN | Shadow-Style=Black
Parent topic: The SCREEN Option


Additional Configuration Variables

Several miscellaneous runtime configuration variables affect the Terminal Manager. These are described below.

Note that for the variables AUTO_PROMPT, BELL, MONOCHROME, SCROLL and WRAP, the settings 1, on, true, and yes are synonymous, as are the values 0, off, false and no.

  • AUTO_PROMPT
  • BELL
  • HOT_KEY
  • MONOCHROME
  • RESTRICTED_VIDEO_MODE
  • SCROLL
  • WRAP
Parent topic: The Display Interface


AUTO_PROMPT

When set to a non-zero value, the AUTO-PROMPT runtime configuration variable causes every ACCEPT statement without a PROMPT phrase to be treated as if PROMPT SPACES were specified. This has the effect of erasing the field where the data is about to be entered. This is provided primarily for compatibility with ACUCOBOL-85 version 1.1, which behaved this way. The default setting for this variable is zero.

Parent topic: Additional Configuration Variables


BELL

When set to a zero value, the BELL variable suppresses all bells generated by ACCEPT and DISPLAY statements. This will make ACUCOBOL-GT totally quiet even if WITH BELL phrases are used on DISPLAY statements. The default setting is one.

Parent topic: Additional Configuration Variables


HOT_KEY

This variable associates an exception value or values with a program. When a key with a specified exception value is pressed, the corresponding program is run. This variable is described in detail in Appendix H.

Parent topic: Additional Configuration Variables


MONOCHROME

When set to a non-zero value, this variable disables color output for Windows machines with graphics video cards.

ACUCOBOL-GT assumes that all Windows machines with graphics video cards have color monitors (because the card has color abilities). If you have a monochrome monitor attached to such a machine, the results can be difficult to see. You can tell ACUCOBOL-GT to disable color output for these monitors through the Monochrome option. When this is set to a non-zero value, ACUCOBOL-GT will use only black and white. The default value is zero. Note that you may change this in your program by using the SET ENVIRONMENT verb; ACUCOBOL-GT examines the MONOCHROME setting each time it does screen output.

Parent topic: Additional Configuration Variables


RESTRICTED_VIDEO_MODE

This variable controls the rules ACUCOBOL-GT uses when displaying data on a terminal with non-hidden attributes (sometimes called magic cookies). See Restricted Attribute Handling for more information.

Parent topic: Additional Configuration Variables


SCROLL

When set to zero, the SCROLL variable inhibits screen scrolling, except scrolling caused by explicit SCROLL phrases in ACCEPT and DISPLAY statements. If a line wraps on the bottom line of the screen, the screen will not be scrolled if SCROLL is set to zero, but the line wrapping will still occur; it will overwrite the bottom line. Normally, ACUCOBOL-GT will scroll the screen to bring a DISPLAY line onto the screen if its line number is past the bottom edge of the screen. When SCROLL is set to zero, this does not occur and the cursor location becomes undefined.

Parent topic: Additional Configuration Variables


WRAP

The WRAP variable controls whether line wrapping is allowed. Normally, a DISPLAY statement that does not fit onto one line will wrap around to the next line. When WRAP is set to zero, this does not occur and the DISPLAY statement is truncated at the end of the line. Also, ACUCOBOL-GT normally wraps around to bring the column position specified for an ACCEPT or DISPLAY statement onto the screen. If WRAP is set to zero, the cursor location becomes undefined.

Note: If WRAP or SCROLL is set to zero, the screen cursor location can be placed into an undefined state. This can occur, for example, if the WRAP setting causes a DISPLAY statement to truncate. This would leave the cursor conceptually just off the right edge of the screen. When this occurs, ACUCOBOL-GT inhibits further DISPLAY statements until the cursor is placed back on the screen via one of the normal positioning rules (ACUCOBOL-GT continues to track the cursor's logical location). Should an ACCEPT statement execute in an undefined location, ACUCOBOL-GT places the ACCEPT field in the home position of the current window.
Parent topic: Additional Configuration Variables


Double-Byte Character Handling

Asian character sets contain large numbers of ideographic characters that represent an entire or partial word or concept. They may also contain interspersed phonetic characters. They may therefore consist of tens of thousands of characters. Because one 8-bit byte can hold only 256 unique codes, these languages require at least two bytes to represent each character, in order to accommodate the full range.

Most double-byte characters occupy two full character screen positions (each byte corresponds to one screen position). Such data may be entered into and displayed from USAGE DISPLAY data items. Most COBOL applications can therefore accept and store double-byte data without modification.

Problems can arise when double-byte data is displayed on the screen. For example, during an ACCEPT, one byte of a double-byte character may be deleted or overwritten. When a window is displayed, the edge of the window might cover one byte of a double-byte character. In these circumstances, the pairing of bytes can change, and the resulting codes may represent entirely different characters. On most machines this confuses the operating system's display driver. To overcome these potential problems, the runtime system must follow two rules:

  1. Always display both bytes of a double-byte character together (never display only part of a double-byte character).
  2. Always overwrite, or change the attributes of, both bytes of a double-byte character together (never overwrite, or change the attributes of, only part of a double-byte character).

These rules must be obeyed when an ACCEPT handles cursor movement, cursor placement, text selection, delete, backspace, and character overtyping.

The rules must also be followed when the edges of windows are displayed, to avoid covering parts of double-byte characters.

To implement these rules, the runtime system needs to know which of several double-byte character encoding schemes is being used. It gets this information from the value of the configuration variable CODE-SYSTEM. See Appendix H for a detailed discussion of this variable.

Parent topic: The Display Interface


Restricted Attribute Handling

The ACUCOBOL-GT Terminal Manager assumes that video attributes can be applied individually to each character on the screen. This is the way most personal computers work with ANSI-conforming terminals. Several popular terminals, however, do not behave this way. The topics in this section describe how ACUCOBOL-GT treats these terminals and what restrictions they impose.

Note: The topics in this section does not apply to Windows implementations of ACUCOBOL-GT except those using the alternate runtime with a terminal database file. If you are a Windows user and plan to move your programs to UNIX or VMS systems, you may want to read this section to familiarize yourself with the restrictions these environments impose.

Some terminals implement video attributes by a method that conflicts with the assumptions of the Terminal Manager. These terminals have special characters that show on the screen as a space, but set a display attribute for succeeding characters. That attribute is applied until another attribute-setting character is found. If one of these special characters is overwritten, its attribute will not be set.

UNIX documentation calls these attribute characters magic cookies. They are also sometimes called non-hidden attributes. Two terminals that use this style of attribute handling are the Televideo 925 and the Wyse 50.

This type of terminal poses special problems. One issue is where to place the attribute character. If it is placed in the first location of the field, the data in the field will be moved over one character position, resulting in a different display than on other types of terminals or personal computers. If it is placed just before the field, it might overwrite some valid data. Combining attribute characters with windows is even more intricate.

  • Restricted Video Modes
Parent topic: Terminal Manager
Parent topic: Setting up your Terminals


Restricted Video Modes

The action of ACUCOBOL-GT on a terminal with non-hidden attributes is determined by the setting of the RESTRICTED_VIDEO_MODE runtime configuration variable. This variable can take several different settings to control the rules ACUCOBOL-GT uses for these terminals.

Note: The following rules do not apply to intensity. These terminals can apply intensity attributes individually to each screen position. The Terminal Manager treats high and low intensity in the normal manner for these types of terminals.

By default, the RESTRICTED-VIDEO-MODE value is zero, which causes the Terminal Manager to ignore attributes other than intensity; the application will run correctly, but without any video attributes. This is convenient when you are running a program that has not been written to conform to the following rules.

To use video attributes with these terminals, you must set RESTRICTED-VIDEO-MODE to a non-zero value; the syntax is:

RESTRICTED-VIDEO-MODE  value

Optional values are:

1 When the variable is set to 1, the Terminal Manager uses rules that tend to emphasize getting the fields in the right location over getting all the attributes correct. These rules are as follows:
  • Every ACCEPT and DISPLAY is preceded by the appropriate attribute-setting character.
  • This character is placed immediately to the left of the beginning of the field. Note that this may overwrite existing data.
  • If the field position is column 1 of the current window, and the attribute is normal white on black, then the attribute-setting character is not displayed.
  • If the field position is column 1 of the current window, and the attribute is other than white on black, the field is moved over to column 2 to allow space for the attribute character.
  • The field is then accepted or displayed using the normal rules.
  • If the screen location immediately after the end of the field does not contain an attribute-setting character, a normal white-on-black attribute character is placed there. If this statement is an ACCEPT statement, this is done before the ACCEPT occurs. The current cursor location is then set according to the normal ACUCOBOL-GT rules (this will cause the cursor location to be where this terminating attribute character is located).
3 | When RESTRICTED-VIDEO-MODE is set to 3, the Terminal Manager follows all the rules listed under value1 except for rule (c). This causes all ACCEPT and DISPLAY statements that reference column 1 to be placed in column 2. This setting prevents you from placing data in column 1, but causes all fields placed in column 1 to line up vertically regardless of which attributes they use.
5 | When RESTRICTED-VIDEO-MODE is set to 5, the Terminal Manager follows all the rules listed under 1 except for rule (b). The attribute character is placed in the first position of the field, and the field is moved to the right one character. This setting will cause all fields to shift to the right by one, but will not overwrite data if two fields are adjacent.
7 | When RESTRICTED-VIDEO-MODE is set to 7, the Terminal Manager follows all the rules listed for 1 except for rules (b) and (c). Thus, every ACCEPT and DISPLAY will always be preceded by an attribute character, and this character will always occupy the first field position. This value emphasizes getting the attributes correct over getting the fields in the correct screen location.

These rules give a certain amount of flexibility, but also have restrictions.

  • Restrictions
Parent topic: Restricted Attribute Handling


Restrictions

The following restrictions apply to programs that plan to use non-hidden attribute terminals. The restrictions are largely based on physical attributes of these terminals. In essence, by setting RESTRICTED-VIDEO-MODE to a non-zero value, you are declaring to ACUCOBOL-GT that you are willing to work with some restrictions beyond those imposed by other types of terminals. The end user should be aware that moving an application to this type of terminal from a normal type may result in unexpected effects.

The following restrictions apply:

  1. Under the current version of ACUCOBOL-GT, this style of attribute handling may be applied only at the field and Screen Section levels. If you are using one of these types of terminals, the REVERSED and COLOR phrases of the DISPLAY WINDOW, DISPLAY LINE, and DISPLAY BOX verbs will be ignored.
  2. The Terminal Manager makes no attempt to control the screen attributes present when a window is created. If you create a pop-up window over one-half of a reverse-video field, and then you clear that window, the reverse-video field will suddenly extend across the screen when the terminating attribute character is erased. You should keep fields either wholly contained in a window or wholly outside a window.
  3. The various RESTRICTED-VIDEO-MODE settings can interact with SCROLL and WRAP settings in unexpected ways. For example, if you have a field wrap-around, the video attribute used for that field will also wrap around for some terminals, but not for others. On the other hand, if you set WRAP to zero and cause a field to be truncated, then the terminating attribute character will not be placed on the screen, and the video attribute may wrap around to the next line on some terminals. Care should be taken with fields that wrap around or scroll the screen.
  4. If you position one field within another, you will affect the attributes of the characters that follow the contained field. Keep your fields separate from each other and supply enough space between fields to hold the attribute characters.

These restrictions are relatively easy to work with until you start working extensively with windows. When working with windows, try to keep the use of attributes to a minimum (particularly reverse-video) in order to avoid difficulties. You can use high and low intensity or boxes to organize your screen. Just use reverse-video for special highlighting.

If you intend to use video attributes on these types of terminals, then you should make sure that you fully test your programs on one of them.

Parent topic: Restricted Video Modes


The Terminal Database File

The terminal database file, which is similar to the termcap file supplied with many UNIX systems, may be edited to add new terminals to the ones it currently supports. Existing entries in the file may also be edited, if needed, to describe your terminal.

Each line of this file is either blank, a comment (marked by a "#" in column 1), or a definition of a terminal. You can continue a "line" on following lines by ending the line to be continued with a "\" (see below for an example). The "\" character must be the last character on the line.

A terminal definition consists of several fields, separated by colons. The end of the line marks the end of the definition. The first field is always the name of the terminal. Several names can be placed here, separated by a vertical bar ("|"). The rest of the fields consist of codes that describe various terminal functions. Most of these codes are followed by an equals sign and a coded string that describes how to operate that particular function.

Here is a generic representation of a terminal database file entry, where TNnis a terminal name, tf is a terminal function code, and cs is a coded string to accomplish the function (some terminal function codes are self-defining and do not need a coded string):

TN1|TN2|TN3:\
:tf[=cs]:tf[=cs]:tf[=cs]:\
:tf[=cs]:tf[=cs]:

The coded string that describes a function is just a representation of the control-sequence (or sequences) that the terminal uses to activate that function. These strings consist of the literal characters used in the control-sequence. Several special forms are recognized to aid in describing the control-sequence. The following abbreviations are supported:

\E | an escape character
\n | a newline (control-J)
\r | a carriage return (control-M)
\t | a tab (control-I)
\b | a backspace (control-H)
\f | a form-feed (control-L)
^X | X is any character, treated as control-X
\nnn | three digits treated as an octal value

The following is a list of all of the supported function codes.

AC | Attributes used by clear screen
AT | Special color for IBM 3164 terminal
B1 - B8 | Background color 1-8
BL | Blink
C1 - C8 | Foreground color 1-8
DI | De-initialization string
DL | Default intensity is low
DP | Disable print mode
EP | Enable print mode
GA | Graphics on and off are characters
GE | Graphic escape
GF | Graphics off
GM | Graphics map
GO | Graphics on
GX | Graphics movement glitch
HI | High-intensity, normal video
LO | Low-intensity, normal video
NM | Normal Video (only if ìsgî set)
NS | Screen does not scroll when corner is used
OC | One color can be displayed at a time
RA | Reverse video, alternate intensity
RB | Reverse video, blink
RU | Reverse video, underline
RV | Reverse video
UL | Underline
W3 | Set terminal width to 132 columns
W8 | Set terminal width to 80 columns
al | Insert (add) line
bc | Backspace cursor (defaults to ^H)
cd | Clear to end-of-screen
ce | Clear to end-of-line
cl | Clear screen
cm | Cursor positioning
co | Number of screen columns (default 80)
dl | Delete line
do | Down one line (defaults to ^J)
is | Initialization string
is1 | Additional initialization string
is2 | Additional initialization string
li | Number of screen lines (default 24)
nd | Non-destructive space
sg | Standout-mode glitch (uses magic cookies)
tc | Continue description with another entry
up | Cursor up one line
ve | Set cursor to normal
vi | Set cursor to invisible
vs | Set cursor to bright

The following codes are also available to represent various keys. Most terminals have only a subset of this full set.

K1 - K0 | Function keys 11 - 20
K? | Help
KA | Attention
KB | Bottom
KC | Clear
KD | Do (command)
KE | End
KF | Find
KI | Insert character
KL | Page left
KM | Mark (select)
KP | Print
KR | Page right
KS | Send
KT | Top
KV | Save
KX | Delete character
Kc | Cancel
Kl | Word left
Kr | Word right
Kx | Exit
k1 - k0 | Function keys 1 - 10
kA | Insert line
kB | Tab left
kE | Clear to end
kL | Delete line
kN | Page Down
kP | Page Up
kd | Down arrow
kh | Home
kl | Left arrow
kr | Right arrow
ku | Up arrow
U1 - U0 | User defined key 1 - 10
A1 - A0 | User defined key 11 - 20

All of the function codes described with lower-case characters are identical to ones found in the UNIX termcap file. These sequences can be taken verbatim from termcap and included in the ACUCOBOL-GT terminal database file when you are adding a new terminal entry.

To help with this discussion, an example of an entry for a DEC VT-100 will be developed. At each step of the example, the new portion of the entry will be in bold type. Initially, we need to assign a set of names that we want to use to refer to the terminal. For example:

vt100|vt-100|DEC VT-100:

This allows for any of the names vt100, vt-100 or DEC VT-100 to be used for the TERM or A_TERM variable. By convention, the last name in the list is a long, descriptive name.

  • Required Functions
  • Additional Screen Functions
  • Video Attributes
  • Color
  • Function Keys and Other Keys
  • Line Drawing
  • Graphical Window and Control Emulation
  • Mouse Support for X Terminals
  • Initialization
  • Print Functions
  • Continued Entries
Parent topic: Terminal Manager
Parent topic: Setting up your Terminals


Required Functions

In order for the Terminal Manager to run, four functions must be defined for the terminal; all of the remaining functions are optional. These required functions are Cursor-positioning (cm), Clear-screen (cl), Clear-to-end-of-line (ce), and Clear-to-end-of-screen (cd). If these functions are not present when the Terminal Manager tries to run, an error will be printed and the program halted.

The Clear-screen function should clear the entire screen and home the cursor. The clear-to-end-of-line function should clear from the cursor position to the end of the current line. The clear-to-end-of-screen function should clear from the cursor position to the end of the screen.

The Terminal Manager starts by establishing a window that is the size of the screen. By default, a screen size of 24 by 80 is assumed. If this is not correct, you can set the Lines (li) and Columns (co) fields to the correct size. These settings are made with a "#" instead of an "=". For example, if you have a 25-line terminal, the proper setting is li#25.

Continuing with our example, the DEC VT-100 clears the screen by sending an ESC[2J. Unfortunately, this does not home the cursor. This can be accomplished by sending ESC[;H. These can be sent in either order. Clearing to the end of line is done by sending ESC[K and clearing to the end of the screen by ESC[J. The terminal has the default screen dimensions, so we do not need to add the co or li options. Our entry now reads:

vt100|vt-100|DEC VT-100:\
:cl=\E[;H\E[2J:ce=\E[K:cd=\E[J:

Cursor positioning is accomplished by a special encoded form. The program must specify varying information in the control-sequence (the row and column numbers). Special abbreviations are allowed to encode this information. These abbreviations and their meanings are:

%d | Inserts the row or column number here in ASCII. For example, row 5 would be inserted here as "5".
%2 | Acts like "%d" except that it always prints as two digits. Row 5 is inserted as "05".
%3 | Acts like %2 except that three digits are used.
%. | Inserts the row or column number here literally. Row 5 would be inserted here as a decimal 5 (ASCII control-E). Note that if this type is used, then Cursor-up (up) and Backspace-cursor (bc) must also be defined.
%+x | Acts like "%." except that x is added to the row or column number first. If the sequence were "%+ " (note the trailing space), then row 5 would be inserted here as the sum of the space character and 5, "%" in ASCII. This form is quite common.
%>xy | This does not insert anything in the string. If the row or column number is greater then x, then y is added, otherwise this has no effect.
%r | Normally the row is inserted first, and then the column. This reverses the order.
%i | Normally the row and column numbers are relative to zero. Including this causes them to be relative to 1.
%% | Sends a literal "%".

For example, the ADM-3A terminal positions the cursor by sending an ESC= followed by the row and column offset by a space character. The code for this is \E=%+  %+   (note spaces).

The VT-100 positions the cursor by sending an ESC[ followed by the row, a semicolon, the column and then an "H". The row and column are sent as ASCII strings and the home position is row 1, column 1. The correct string is \E[%i%d;%dH.

vt100|vt-100|DEC VT-100 :\
:cl=\E[;H\E[2J:ce=\E[K:cd=\E[J:\
:cm=\E[%i%d;%dH:
Parent topic: The Terminal Database File


Additional Screen Functions

Several additional functions are available to manipulate the screen display. These should be included if the terminal supports these features. The functions are: insert-line (al), delete-line (dl), non-destructive-space (nd), backspace-cursor (bc), cursor-down (do), cursor-up (up), set-width-132 (W3) and set-width-80 (W8).

The four cursor movement commands are available to optimize cursor motion. The non-destructive-space function should move the cursor to the right one column; the backspace-cursor function should move the cursor left one column. Finally, the cursor-down function should move the cursor down one line and cursor-up should move it up one line. If omitted, cursor-down defaults to a line-feed character, and backspace-cursor defaults to a backspace character. There are no defaults for non-destructive-space and cursor-up.

The insert-line function should insert a blank line at the cursor line, moving the cursor line and all following lines downward. The delete-line function should delete the cursor line, moving all following lines up and inserting a blank line at the bottom of the screen.

NS should be added to the terminal database file entry for a terminal that does not scroll if the lower right corner of the screen is filled. This tells the ACUCOBOL-GT program that it is all right to use this position. NS is the complete sequence (... :NS: ...).

The set-width functions should change the display between 132-column mode and 80-column mode. Both must be specified to use this feature.

You can also specify when the cursor should be visible. These entries should handle cursor modification:

ve = set cursor to normal
vs = set cursor to bright
vi = set cursor to invisible

After vi has rendered the cursor invisible, ve is used to make it visible.

If your terminal does not have both a normal and a bright cursor, then set the ve entry to turn the cursor on and do not use the vs entry.

The VT-100 supports only one of these functions: Non-destructive-space. This is accomplished by sending ESC[C. Our current entry is now:

vt100|vt-100|DEC VT-100 :\
:cl=\E[;H\E[2J:ce=\E[K:cd=\E[J:\
:cm=\E[%i%d;%dH:\
:nd=\E[C:
Parent topic: The Terminal Database File


Video Attributes

To correctly configure attributes for a terminal, you must first determine which style of attribute setting (ANSI or magic cookie) it uses. You can do this most easily by typing the sequence to turn on reverse video at your terminal. If the cursor moves one character and a reverse-video bar appears, then you have a magic cookie style of terminal. If nothing happens, then type some characters. These should show up in reverse video. If they do, then you have an ANSI style terminal that allows for independent attributes for each screen position. If you do not get reverse-video at all, then you did something wrong.

If you include RV, UL, BL, RU, or RB in your terminal database file entry, then the HI and LO functions must be included. These two functions set the terminal to normal video/high intensity and normal video/low intensity, respectively. If intensity is not being used, then these should both just set normal video.

On all machines except Windows, the runtime system ignores the difference between high-intensity spaces and low-intensity spaces when the background color is black. If your terminal is set up to run with black-on-white characters (reverse video) as its default, you should add the entry VB (visible background) to the description of that terminal. This causes spaces to be handled consistently.

If a magic cookie style terminal is being used, then HI and LO should not set normal video, but should just set the appropriate intensity. The function NM should be added to set normal video instead. Also, the function sg must be included to tell the Terminal Manager that this is a "magic cookie" type terminal. The sg setting does not take a value, it just has to be present.

A few "magic cookie" terminals ignore HI and LO, so that reverse video fields appear the same regardless of which intensity is used. If you are experiencing this situation, add RA to the terminal's description. This sets the terminal into reverse video using the terminal's alternate intensity (usually low intensity). If RA is used, then RV sets reverse video in the terminal's default intensity.

The function DL should be included in a definition if the default intensity for the terminal is low-intensity. This function is not set to a value, it is just included in the terminal definition.

On some terminals, a clear screen operation uses the currently selected video attribute. For example, if reverse-video were the current attribute, then a clear screen would cause the entire screen to become reverse-video. If the terminal has this property, then AC should be included to indicate this. ACUCOBOL-GT will use this to optimize certain screen displays.

Continuing the example, the VT-100 allows the independent setting of each attribute. It cannot independently reset the attributes, but that is not required by the Terminal Manager. Low-intensity, normal-video can be set with ESC[m. High-intensity can be set with ESC[1m. Reverse video is initiated by sending ESC[7m, underline with ESC[4m and blink with ESC[5m. The terminal normally runs in low-intensity, so the DL flag is used. All of these modes can be combined by placing the appropriate attribute numbers together in one command string and separating them with semicolons. Our new entry becomes:

vt100|vt-100|DEC VT-100 :\
:cl=\E[;H\E[2J:ce=\E[K:cd=\E[J:\
:cm=\E[%i%d;%dH:nd=\E[C:\
 :LO=\E[m:HI=\E[0;1m:RV=\E[7m:\
 :UL=\E[4m:BL=\E[5m:RU=\E[4;7m:\
 :RB=\E[5;7m:DL:

Note the setting of \E[0;1m for HI. The initial zero ensures that the terminal is set to normal modes before the high-intensity mode is set.

Parent topic: The Terminal Database File


Color

The Terminal Manager can support terminals that support ANSI-style attribute handling. This style allows for independent setting of the background and foreground colors and does not interfere with the setting of other video attributes such as underlining. Color terminals that meet these criteria can enable color by adding entries to turn on the various foreground and background colors. Use the following table of attribute codes to set the correct color entries; if your terminal has fewer than eight colors, you should still make all eight entries for both foreground and background, repeating colors as necessary:

Foreground | Background | Color
C1 | B1 | Black
C2 | B2 | Blue
C3 | B3 | Green
C4 | B4 | Cyan
C5 | B5 | Red
C6 | B6 | Magenta
C7 | B7 | Brown
C8 | B8 | White

Terminal definitions for color terminals do not need the RV, RB, and RU entries, because the Terminal Manager sends the appropriate foreground and background color codes instead.

  • One-color terminals
Parent topic: The Terminal Database File


One-color terminals

Some terminals can display text in only one color at a time. On these terminals it is impossible to display text with separate foreground and background colors, unless one of the colors is black. The termcap code OC (one color) tells the runtime system to use special color handling to accommodate a terminal of this type.

If this code is present in the terminal's database entry, the runtime system displays text using the correct color combinations set from COBOL, so long as either the foreground or background color is set to black. If neither the foreground nor the background is set to black, the runtime system displays text using the foreground color (the background color is disregarded).

To use this code, add it to the terminal database entry preceded and followed by a colon (:OC:).

Parent topic: Color


Function Keys and Other Keys

Function keys and other special keys are simple to deal with. The various key entries are set to the values that those keys send when they are pressed. All of the key entries are optional.

As a minimum, you should define the arrow keys and some function keys. Most programs use these keys.

  • User-defined keys
Parent topic: The Terminal Database File


User-defined keys

The User-defined keys (U1 - U0) are available for any keys that are not defined in the table above. These can be used for special purposes.

The VT-100 has the four arrow keys and function keys 1 through 4. The function keys send ESCO followed by a distinguishing character, and the arrow keys send ESC[ and a distinguishing character. The new entry is:

vt100|vt-100|DEC VT-100 :\
:cl=\E[;H\E[2J:ce=\E[K:cd=\E[J:\
:cm=\E[%i%d;%dH:nd=\E[C:\
:LO=\E[m:HI=\E[0;1m:RV=\E[7m:\
:UL=\E[4m:BL=\E[5m:RU=\E[4;7m:\
:RB=\E[5;7m:DL:\
:k1=\EOP:k2=\EOQ:\
:k3=\EOR:k4=\EOS:ku=\E[A:\
:kd=\E[B:kr=\E[C:kl=\E[D:
Parent topic: Function Keys and Other Keys


Line Drawing

Some terminals support a line drawing set. This is used by the Terminal Manager when boxes are drawn around windows. The Terminal Manager turns on the graphics mode by sending the GO code, then sends normal characters that correspond to the lines, and then sets the terminal back to normal mode with GF.

The GM function lists the normal characters that draw the line segments. This is either a six- or eleven- or thirteen-character string. The characters listed in the GM function correspond, in order, with the following line segments:

  1. horizontal line
  2. vertical line
  3. upper left corner
  4. upper right corner
  5. lower left corner
  6. lower right corner

This is the six-character set. If the terminal has the following line segments, the characters that correspond to them should be included (in order) to make the eleven-character set:

four three-way intersections:

  1. missing bottom line
  2. missing left line
  3. missing top line
  4. missing right line
  5. the four-way intersection

This is the eleven-character set. If the terminal has the following block characters, the characters that correspond to them should be included (in order) to make the thirteen-character set:

  1. upper-half block
  2. lower-half block

On a few terminals, the graphics-on and graphics-off sequences are treated as character attributes. In particular, turning off graphics also sets the terminal to its default video attributes. If this is the case, then the code GA (graphics are attributes) should be included in the terminal description. A few terminals also cannot move the cursor while in graphics mode. If this is the case, the code GX (graphics movement glitch) should be included.

Some terminals do not need to send a graphics-on or a graphics-off sequence. For these terminals, the line-drawing characters are available in the default character set. If this applies to your terminal, then just give the GM setting without the GO or GF settings.

  • Multi-character Sequences for Graphics
Parent topic: The Terminal Database File


Multi-character Sequences for Graphics

Some terminals require more than one character in the escape sequence that draws a graphical line segment. For example, the two-character sequence \E\202 might be required to draw a single horizontal line character.

ACUCOBOL-GT permits up to three characters to be specified in an escape sequence that draws a single line segment. The three characters are stored separately and assembled into a single sequence by the Terminal Manager.

When these multiple-character sequences are used, the GO (graphics on) and GF (graphics off) codes serve special purposes. GO is used to store the first character in the sequence, and GF is used (if needed) to store the third character.

You tell the runtime system (by including the GE code) that GO should be sent to the terminal before each GM graphical character that is sent, and GF should be sent after each GM graphical character.

Also you must make sure that the GM character list contains the appropriate characters. To handle the example mentioned above, in which a horizontal line segment requires the two-character sequence \E\202, you would add two codes to the terminal database entry: :GE: and :GO=\E:, and also add \202 to the GM character list in position one (horizontal line character).

Some VT-100 emulators support line drawing by using alternate character sets. They turn on graphics by sending ESC(0 and turn it off by sending ESC(B. The entry is:

vt100|vt-100|DEC VT-100 :\
:cl=\E[;H\E[2J:ce=\E[K:cd=\E[J:\
:cm=\E[%i%d;%dH:nd=\E[C:\
:LO=\E[m:HI=\E[0;1m:RV=\E[7m:\
:UL=\E[4m:BL=\E[5m:RU=\E[4;7m:\
:RB=\E[5;7m:DL:k1=\EOP:k2=\EOQ:\
:k3=\EOR:k4=\EOS:ku=\E[A:\
:kd=\E[B:kr=\E[C:kl=\E[D:\
:GO=\E(0:GF=\E(B:GM=qxlkmjvtwun:
Parent topic: Line Drawing


Graphical Window and Control Emulation

The character-based version of the runtime system emulates graphical windows and controls by displaying characters with particular attributes that approximate the look and feel of a graphical system.

The following standard characters are used by default to represent various graphical components:

"-", "|", "+", "=", "*", ".",

"^", "v", "<", ">", " ", "#"

Terminals that support a line drawing set or a special extended character set, or both, can be configured to use these special characters. The configuration method is similar to the one used for line drawing, described in Line Drawing.

To support the substitution of line drawing characters and extended characters, there are two terminal database (a_termcap) functions: GO-GUI-MAP and GF-GUI-MAP.

The GO-GUI-MAP function uses a list of standard characters that correspond to line segments and other special characters when displayed in the terminal's graphics mode. This is similar to the GM function used for line drawing. The Terminal Manager turns the terminal's graphics mode on by sending the GO code. The GO code is followed by normal characters which are interpreted by the terminal into their corresponding special characters. When all of the special character elements have been displayed, the terminal is set back to normal mode with GF.

The GF-GUI-MAP function provides a method for specifying substitute standard characters for some or all of the graphical components. When these characters are used, they are displayed in normal (not graphics) mode. The Terminal Manager gives preference to the characters specified in GO-GUI-MAP. If a character in the list is preceded with \0 (backslash, zero), the Terminal Manager uses the corresponding character in the GF-GUI-MAP. If the character cannot be determined from the GO-GUI-MAP or GF-GUI-MAP functions (either list may be incomplete or there may be a \0 in the same position in both lists), the Terminal Manager uses the default character. For more information about defining the list of special characters, see the entry for GUI_CHARS in Appendix H. Configuration Variables.

The characters listed in the GO-GUI-MAP and GF-GUI-MAP correspond, in order, to the following graphical components. The character in parentheses is the default character:

1. | System menu button | (*)
2. | Floating window title left corner | (+)
3. | Floating window title right corner | (+)
4. | Floating window title fill character | (=)
5. | Minimizer | (.)
6. | Maximizer | (^)
7. | Scroll bar up button | (^)
8. | Scroll bar down button | (v)
9. | Scroll bar left button | (<)
10. | Scroll bar right button | (>)
11. | Scroll bar page area | ( )
12. | Scroll bar thumb | (#)
13. | Left entry field box and check box character | ([)
14. | Right entry field box and check box character | (])
Note: Some of these graphic components may not be used in the current version of ACUCOBOL-GT.

When a program executes, the runtime system evaluates the terminal's display capabilities and determines the special display attributes to apply to select control elements. These control elements include the control's key letter, push-button text, and a key letter that is part of the push-button text when the user presses the button with the mouse. The runtime system applies the first supported capability to each element as follows.

Key letter:

  1. Underline
  2. Intensity toggle (opposite intensity - for example, if the control is displayed in high intensity, the key letter is displayed in low intensity)
  3. Reverse video

Selected push-button text:

  1. Reverse video
  2. Underline
  3. Intensity toggle

Key letter in selected push-button text:

If the selected push-button text attribute is reverse video, apply to the key letter:

  1. Intensity toggle
  2. Underline
  3. Reverse video (the key letter is indistinguishable from the other text)

If the selected text attribute is underline, apply to the key letter:

  1. Intensity toggle
  2. Underline (the key letter is indistinguishable from the other text)

If the selected text attribute is intensity toggle, apply to the key letter:

Intensity toggle (key letter is indistinguishable from the other text)

  • Reconstructing the Screen
Parent topic: The Terminal Database File


Reconstructing the Screen

On a character-based system, during program execution when a control is resized, moved, hidden, or removed (destroyed), the runtime system applies the following procedure to reconstruct and display the screen:

  1. The screen is reconstructed in memory, in a virtual screen, before being displayed to the physical screen.
  2. The portion of the screen underneath the affected control is redrawn to the virtual screen with the attributes and colors of the owning window (this usually results in that area of the screen being filled with the owning window's background color).
  3. Any controls that overlap the affected area are redrawn in the order in which they were originally created.
  4. The changed portions of the screen (constructed in memory) are displayed to the physical screen.
Parent topic: Graphical Window and Control Emulation


Mouse Support for X Terminals

The Terminal Manager allows for limited mouse support for X terminals if you are using a curses-compatible mouse. To make mouse events available to your COBOL program, you need to do the following to your termcap file:

  • use an escape sequence in the is termcap entry to enable mouse events
  • use an escape sequence in the DI termcap entry to disable mouse events at exit, and
  • create a new entry, km, which is the lead-in sequence for a mouse event. When the escape sequence for km is detected, the next three characters are the event and character position of the mouse at the time of the event.

Currently, the support is limited. In particular, the termcap file will return information about which button was pressed, and where the mouse was at the time the button was pressed. Though it will return information when a button was released, it cannot tell which button was released. The runtime system assumes that the button last pressed is the button released. This assumption may, of course, be incorrect. Double-clicks and information about motion are never returned.

The a_termcap entry for xterm-mouse is:

xterm-mouse|xterm emulator with mouse support (X window system):\
:cr=^M:do=^J:nl=^J:bl=^G:le=^H:ho=\E[H:\
:co#80:li#56:cl=\E[H\E[2J:bs:am:cm=\E[%i%d;%dH:nd=\E[C:up=\E[A:\
:ce=\E[K:cd=\E[J:UL=\E[4m:DL:\
:HI=\E[1m:RV=\E[7m:LO=\E[m:\
:ku=\EOA:kd=\EOB:kr=\EOC:kl=\EOD:kb=^H:\
:k1=\E[11:k2=\E[12:k3=\E[13:k4=\E[14:\
:k5=\E[15:k6=\E[17:k7=\E[18:k8=\E[19:\
:k9=\E[20:k0=\E[21:ta=^I:pt:sf=\n:sr=\EM:\
:al=\E[L:dl=\E[M:ic=\E[@:dc=\E[P:\
:kh=\EO\000:kN=\E[6:kP=\E[5:\
:km=\E[M:\
:w8=\E[?3l:w3=\E[?3h: \
:ks=\E[?1h\E=:ke=\E[?1l\E>:\
:is=\E7\E[?47h\E[r\E[m\E[2J\E[H\E[?7h\E[?1;3;4;6l\E[?1h\E=\E[?1000h:\
:DI=\E[2J\E[?47l\E8\E[?1000l:\
:DI=\E[2J\E[?47l\E8:NS:\
:KX=\177:KI=\E[2:\
:GO=\E(0:GF=\E(B:GM=qxlkmjvtwun:\
:W8=\E[?3l:W3=\E[?3h:\
:hs:ts=\E[?E\E[?%i%dT:fs=\E[?F:es:ds=\E[?E:
Parent topic: The Terminal Database File


Initialization

Initialization strings can be sent at the beginning of the session to ensure that the terminal is in the proper state, or to program special function keys. This is primarily used to program function keys and function key labels with application specific information. The codes is, is1, and is2 are always sent at the beginning of each session. You can specify a sequence to send at the end of the session with DI.

  • Numeric Mode
Parent topic: The Terminal Database File


Numeric Mode

With the VT-100, it is useful to set the numeric keypad to numeric mode (as opposed to application mode). This is done by sending ESC>. The new entry is then:

vt100|vt-100|DEC VT-100:\
:cl=\E[;H\E[2J:ce=\E[K:cd=\E[J:\
:cm=\E[%i%d;%dH:nd=\E[C:\
:LO=\E[m:HI=\E[0;1m:RV=\E[7m:\
:UL=\E[4m:BL=\E[5m:RU=\E[4;7m:\
:RB=\E[5;7m:DL:k1=\EOP:k2=\EOQ:\
:k3=\EOR:k4=\EOS:ku=\E[A:\
:kd=\E[B:kr=\E[C:kl=\E[D:\
:GO=\E(0:GF=\E(B:GM=qxlkmjvtwun:\
:is=\E>:
Parent topic: Initialization


Print Functions

The Terminal Manager also allows for limited support of a printer attached directly to the terminal. You must ensure that communications between the printer and terminal meet all the restrictions that the devices require (some terminals, for example, require that the printer and the terminal run at the same baud rate). The Terminal Manager supports two printer functions. The Enable-print function (EP) causes data sent to the terminal to be also sent to the printer; EP mode remains in effect until turned off by the Disable-print function (DP).

  • Pass Through Mode
Parent topic: The Terminal Database File


Pass Through Mode

The VT-100 supports an attached printer. It has several print modes, but the only one that the Terminal Manager supports is the pass through mode where data sent to the terminal is passed through to the printer. This is enabled by sending ESC[5i and disabled by sending ESC[4i. The completed VT-100 entry is:

vt100|vt-100|DEC VT-100:\
:cl=\E[;H\E[2J:\
:ce=\E[K:cm=\E[%i%d;%dH:cd=E[J:\
:nd=\E[C:LO=\E[m:HI=\E[0;1m:RV=\E[7m:\
:UL=\E[4m:BL=\E[5m:RU=\E[4;7m:\
:RB=\E[5;7m:DL:k1=\EOP:k2=\EOQ:\
:k3=\EOR:k4=\EOS:ku=\E[A:\
:kd=\E[B:kr=\E[C:kl=\E[D:GO=\E(0:\
:GF=\E(B:GM=qxlkmjvtwun:is=\E>:\
:EP=\E[5i:DP=\E[4i:
Parent topic: Print Functions


Continued Entries

The tc function allows you to include, by reference, all the functions from another terminal database file entry. The syntax is tc=entry, where entry is the name of the database file entry whose functions are to be included.

For purposes of explanation, let us say the terminal database file entry you are working on is called entryA and the one you wish to reference is called entryB. Then, as the last function in entryA, you would write tc=entryB. This will include all the functions from entryB in entryA. If there are conflicts between the functions specified by entryA and entryB, the entryA functions take precedence.

Also, any function in entryB can be turned off by naming it, followed by an @ sign, in entryA. For example, if there is an AL function in entryB and you wish to turn it off, simply say :AL@: in entryA.

For example, some VT-100s come with an Advanced Editing option that includes, among other things, an add-line and delete-line function. The complete entry for this might be:

vt100a|DEC VT-100 w/Advanced Editing:\
           :al=\E[L:dl=\E[M:tc=vt100:
Parent topic: The Terminal Database File


File Processing

This section describes these special file processing topics:

  • transaction management
  • client/server implementation with remote file access services
  • generation of data dictionaries (also known as extended file descriptors or XFDs)
  • translation of international character sets between machines that use different codes for the same characters.

General file handling capabilities are covered in Handling Files.

  • Transaction Management
  • AcuServer
  • XFD Files
  • International Character Handling
Parent topic: ACUCOBOL-GT User's Guide


Transaction Management

ACUCOBOL-GT extends standard COBOL to provide a complete transaction management system. A transaction is a group of related file operations that are treated as an indivisible unit. The purpose of defining such transactions is to ensure that related files can be restored to a consistent state when errors occur.

The transaction management requirements of business applications vary widely and can be quite complex. ACUCOBOL-GT provides a basic transaction management facility. Specialized transaction management middleware frequently offers sophisticated capabilities not included in ACUCOBOL-GT, such as multi phase commit, nested, concurrent and distributed transactions, transaction queuing, automatic rollback on startup, and dynamic load balancing, to name a few. Before selecting a transaction management facility, you should carefully assess the needs of your business systems.

ACUCOBOL-GT's transaction management facility can sometimes interfere with programs that use a separate transaction management facility, such as an online transaction processing (OLTP) facility. To disable ACUCOBOL-GT's transaction management, set the NO_TRANSACTIONS configuration variable. For information about using ACUCOBOL-GT with OLTP systems, see Working with Transaction Processing Systems in A Guide to Interoperating with ACUCOBOL-GT.

  1. Overview of Transaction Management
  2. The Transaction Logging Process
  3. Transaction Management Verbs
  4. Extended Locking Rules
  5. Logging and Rollback of File Update Operations
  6. Multiple Log Files
  7. Configuration Variables
  8. Transaction Error Handling
  9. Compiler File Options
  10. Recovery
Parent topic: File Processing


Overview of Transaction Management

Standard COBOL contains a weakness in its handling of file operations in that it does not provide a method of defining transactions. This section describes the special features of ACUCOBOL-GT that allow the security of transaction management.

The benefits of a transaction management system are best illustrated by an example. A COBOL application that handles order entry might perform these steps to accept an order:

  1. Write an invoice record.
  2. Update a customer record.
  3. Write a payroll record for sales commissions.
  4. Update an inventory record.

This series of four file operations is a logical unit. If the program were interrupted, and completed only some of the four file operations, then the files would be in an inconsistent state. For example, if the program died after it updated the customer record, but before it updated the inventory record, then a subsequent run might access non-existent inventory.

The solution to this problem is to provide a method where the programmer can define a set of operations that should either all occur or all not occur. Then, if the program encounters an error or dies, the files are left in a consistent state.

Sites using transaction management should ensure that all users are referring to the same files by the same names. For example, all users should map the same network directory to the same drive letter.

  • Transaction logging
  • File types
  • Features
Parent topic: Transaction Management
Next topic: The Transaction Logging Process


Transaction logging

ACUCOBOL-GT solves this problem by providing a transaction logging facility. All file operations that are part of a transaction are logged. Once logged, they can either be committed or rolled back (undone) by the program.

If a program dies, or the system fails, the log file can be used to reconstruct complete transactions, thus returning all files to a consistent state.

Transaction logging thus offers these two facilities:

  • It provides the programmer with the ability to define transactions, and the ability to commit them or undo them (usually in response to an error condition). This undo facility is called a rollback.
  • It provides the ability to reconstruct files into a consistent state after a program dies or system failure occurs. This operation is called recovery.
Parent topic: Overview of Transaction Management


File types

In general, transactions apply to relative and indexed files. Transaction operations apply for indexed Vision, C-ISAM, and BTRIEVE files, as well as for Acu4GL database files (which are treated as indexed files).

Each transaction operation is executed on the file systems linked with the ACUCOBOL-GT runtime. Each file system uses its own mechanism to handle the transaction operations, and some have their own log files. The general rules for the Vision file system and for relative files are listed in the ACUCOBOL-GT Reference Manual under the COBOL verbs that are used with transaction management. If you use an alternate file system that does not support transaction management, the facility is not available for programs that access those files.

Parent topic: Overview of Transaction Management


Features

Transaction logging provides the following:

  • A method of indicating that transaction logging is wanted and identifying which log files to use.
  • A means of deciding which file operations to log and which files have rollback capability.
  • The ability to start, commit, and rollback transactions in COBOL.
  • A utility routine to perform the recovery function.
  • A utility program to examine and edit log files.
Parent topic: Overview of Transaction Management


The Transaction Logging Process

Transaction logging provides the programmer with a COBOL verb that can roll back or undo file operations performed during a transaction. A rollback is typically invoked when the program detects a file error or other error condition.

Outside of the application, transaction log files can be used for another purpose: to recover files after a program failure or system crash. The recovery process is performed by an ACUCOBOL-GT library routine that accesses the latest backup and the log files. It is the site's responsibility to clear the log files when a backup is made, so that the logs always contain precisely those transactions that have occurred since the last backup. The logs and the backup can then be used to reconstruct files into a consistent state after a crash.

To make rollback and recovery operations possible, the runtime records information about how to redo and undo each file update that occurs within a transaction. After the transaction starts, each Vision or relative file update operation is recorded until the transaction is committed or rolled back. At that point:

  • If the transaction is committed, the commit operation writes the redo information to the log file. The undo information is not recorded in the log file.
  • If the transaction is rolled back, the rollback operation scans the record of changes in reverse order and performs the operations needed to undo the file updates done during the transaction.

All programs that operate on the same set of data files must also use the same set of transaction log files.

In transaction management, the log files must be synchronized to the backup procedure for the files being managed. When the files are backed up, the log files must be cleared (or deleted). The next time a transaction occurs, the runtime creates new log files (or begins writing to the cleared files). Thus, the logs contain precisely those transactions that have occurred since the last backup.

If the log files and backups are synchronized, when a program dies in mid-transaction, you can reconstruct the files into a consistent state. To do this, you restore the backup, then run a program that calls the C$RECOVER utility routine. This routine reads a log file and performs each update operation that was part of a completed transaction. Operations that were not part of a completed transaction are not performed.

By using transaction logging, you ensure logically consistent files. In addition, you never need to do a rebuild operation on a broken data file, because you can always recover files by restoring the backup and running a program that calls C$RECOVER.

You can use the utility program logutil to examine and edit an ACUCOBOL-GT transaction log file. The logutil utility supports large (>2GB) transaction log files. The host operating system must allow such large files. See logutil for more information.

Though a transaction logging system provides a high degree of file security, it does impose extra overhead. Backups are essential, and there is increased disk I/O, more memory use, and more record locks.

Going to your backups and using the recovery procedure usually takes more time than just checking the data files and restarting the program. On the other hand, if the system dies, you do not need to worry about examining the files for problems.

Parent topic: Transaction Management
Previous topic: Overview of Transaction Management
Next topic: Transaction Management Verbs


Transaction Management Verbs

There are three verbs used in ACUCOBOL-GT transaction management. These are:

  • START TRANSACTION
  • COMMIT TRANSACTION
  • ROLLBACK TRANSACTION

TRANSACTION, ROLLBACK, START, and COMMIT are reserved words.

START TRANSACTION identifies the beginning of a transaction. The COMMIT TRANSACTION statement indicates the end of a transaction and commits the changes made. The ROLLBACK verb causes the transaction to be rolled back or canceled.

There is an implicit COMMIT before a STOP RUN or before the end of the program. However, the runtime performs an implicit ROLLBACK before a STOP RUN if the STOP-RUN-ROLLBACK configuration variable is set. If the runtime system is killed by the user or encounters a fatal error prior to completing a transaction, then an automatic rollback occurs. For more information, see START Statement or COMMIT Statement in the ACUCOBOL-GT Reference Manual.

Parent topic: Transaction Management
Previous topic: The Transaction Logging Process
Next topic: Extended Locking Rules


Extended Locking Rules

In order to prevent another process from updating the records in a way that might make it impossible to do a rollback, the system locks any records modified during a transaction. This is done only for files that allow rollbacks. ACUCOBOL-GT offers some flexibility in record locking procedures in its transaction management system. You can enable multiple locking rules or single locking rules as the default locking mode for files that allow rollbacks.

To indicate which files will have record locks held, use the following syntax in the LOCK MODE phrase of the FILE-CONTROL entry for each affected file:

WITH  ROLLBACK

When rollback is enabled, record and file locking rules are extended. Every record updated as part of a transaction is locked until that transaction is committed or rolled back. The COMMIT and ROLLBACK verbs remove these locks. Record locks that are applied when the file is read are also kept until the end of the transaction. Multiple record locking rules are in effect by default.

Use of the compiler option, -Fl, enables single locking rules rather than multiple locking rules as the lock mode default. Normally, WITH ROLLBACK causes multiple locking rules to be in effect for a file. When -Fl is used, the WITH ROLLBACK clause does not affect whether single or multiple record locking rules are followed. Single locking becomes the default. You may enable multiple locking either by specifying WITH LOCK ON MULTIPLE RECORDS in a file's SELECT statement or by using APPLY LOCK-HOLDING ON file in the I-O CONTROL paragraph.

Record locks are held during a transaction in order to prevent another process from updating the records in a way which might make rollback impossible. Note, however, that a record may be deleted during a transaction, and another process is allowed to write a record with the same record key to the file. If this happens, the ROLLBACK will fail with a duplicate key error. See Logging and Rollback of File Update Operations for more information.

Note: During a transaction, the UNLOCK statement affects only files for which rollback is not enabled. In the case where the UNLOCK statement is ineffective because rollback was enabled for the file, the file status will be set to 00 (success).

During a transaction with a Vision or relative file, a CLOSE is postponed if any updates (WRITE, REWRITE, or DELETE) are performed on the file during the transaction, regardless of whether any records are locked. This function permits the file to remain open for ROLLBACK.

If the same physical file is OPENed again within the same transaction, even if the program is using a different logical file (different SELECT), the postponed CLOSE is canceled. Note that the mode of the original OPEN is retained. (For example, if the file were originally OPEN OUTPUT, and if the CLOSE were canceled, then an OPEN I-O on the same file within the same transaction would not enable the program to read the file.) When the second OPEN is encountered, the file position is reset to the beginning so that a READ NEXT would read the first file in the record.

CAUTION:
While a CLOSE action is delayed until the transaction is committed, a DELETE FILE action is performed immediately. If the DELETE FILE statement is contained within a transaction (before the COMMIT) following its associated CLOSE statement, the result will not be what is expected. Because the CLOSE is delayed but the DELETE FILE is executed right away, the program will attempt to delete the open file. The result of the attempted DELETE FILE action is host system dependent (for example, under Microsoft Windows, attempting to delete an open file will cause an error 37, 07 to be returned, while under UNIX, where there is no restriction on deleting an open file, the action will succeed). The safest programming practice is to not code a DELETE FILE action inside a transaction.
  1. Special handling of implicit transactions
Parent topic: Transaction Management
Previous topic: Transaction Management Verbs
Next topic: Logging and Rollback of File Update Operations


Special handling of implicit transactions

There are conditions in which transactions are automatically defined by the runtime to ensure that all file operations are logged, such as when the -Ft compiler flag is used or when an OPEN or CLOSE is performed outside of a defined transaction on a file that has rollback enabled. In these situations, the implicit COMMIT does not unlock any records associated with the file. This ensures that the runtime defined transaction is recorded without interfering with the existing program logic (or locking). See File Options for more information.

Parent topic: Extended Locking Rules


Logging and Rollback of File Update Operations

The record update operations WRITE, REWRITE, and DELETE can be rolled back. However, file operations which open, create, recreate, rename, delete, or close files cannot be rolled back. Therefore, OPEN, CLOSE, DELETE FILE, RENAME, and COPY operations cannot be rolled back.

When a transaction is committed, all of the file update operations are written to the default log file defined by the LOG-FILE configuration variable. However, if instead the transaction is rolled back, those file operations that cannot be rolled back are written to the default log file and then committed.

If a file that was opened during a transaction is closed outside of a transaction, the CLOSE will be treated as its own transaction and will be logged. If a file that has rollback enabled (using the WITH ROLLBACK syntax) is opened outside of a transaction, the OPEN is treated as its own transaction and will be logged. See Extended Locking Rules for more information.

If, during a transaction, a record is deleted from a file not allowing duplicates on a particular key, the delete may be rolled back only if the record key does not exist in the file at the time of the rollback.

This means that if another process writes a record with the same key to the file after the delete, then the delete will not be rolled back, and the rollback will fail with a duplicate key error. See Transaction Error Handling for more information.

Parent topic: Transaction Management
Previous topic: Extended Locking Rules
Next topic: Multiple Log Files


Multiple Log Files

The transaction management facility allows the program to use multiple log files. Different types of transactions can be logged in separate log files, giving you quicker access to a particular type of transaction. Each log file records the information that is necessary to recover a particular file or set of files.

The application administrator or programmer can specify an individual log file to use with any given set of data files. The specified log file is updated whenever a transaction is committed in its associated data files. Log file names are specified with configuration variables of the format:

filename-LOG logfilename

where filename is the base name of the data file, and logfilename is the name of the log file. filename should not include any directory names, nor should it include a file extension. logfilename can include the absolute or relative directory path ending with the name of the log file. If the log file is not found, a new file is created there with the specified name. Note that logfilename can have remote name notation. A configuration file entry for multiple log files might look like:

#transaction temporary file directory
LOG-DIR /usr/transaction-tmp/
#log file definitions
file1-LOG file1.log
file2-LOG file2.log
file3-LOG file3.log
#default log file definition
LOG-FILE  default.log

In the example above, during a commit, all of file1's updates are written to file1.log, all of file2's updates are written to file2.log, and so forth. If other data files are updated during a transaction, their updates are written to default.log. Operations performed with the RENAME or C$COPY library routines are also written to default.log.

A default log file must be specified in the LOG-FILE variable. The runtime creates that log file, or opens the existing one, as part of the first START TRANSACTION statement. Log files specified with filename-LOG variables are created or opened when the file whose base name is filename is opened OUTPUT or I/O for the first time in the program. Note that this means that any error that can be returned from a START TRANSACTION can also be returned as a secondary code of an error 9E on an OPEN statement. See Transaction Error Handling for more information.

Multiple log files can be used only with Vision indexed files and relative files. Transaction management for other file systems is dependent on the specific file system's transaction management facility.

Parent topic: Transaction Management
Previous topic: Logging and Rollback of File Update Operations
Next topic: Configuration Variables


Configuration Variables

There are seven configuration file variables used to configure the logging system. For details, see the configuration variable's listing in Appendix H:

  • filename_LOG — specify the name of a log file
  • LOGGING — enable or disable logging
  • LOG_FILE — specify the name of the default log file
  • LOG_BUFFER_SIZE — set the log file buffer size
  • LOCK_DIR — specify an alternate directory for temporary files
  • LOG_DEVICE — enable or disable special device handling for the log file
  • LOG_ENCRYPTION — enable or disable log encryption
Parent topic: Transaction Management
Previous topic: Multiple Log Files
Next topic: Transaction Error Handling


Transaction Error Handling

Error codes associated with transaction management are stored in a special register called TRANSACTION-STATUS. These codes tell you the status of the last transaction and are documented in Transaction Error Codes. Transaction management errors fall into two categories:

  • For errors that occur during a START TRANSACTION, COMMIT, ROLLBACK, or call to C$RECOVER, use TRANSACTION-STATUS to determine the type of error that occurred. See Recovery for more information.
  • After the execution of any file operation during a transaction, the file's FILE-STATUS variable will contain 9E if an error occurred in the transaction system. The exact nature of the error will be shown by the contents of TRANSACTION-STATUS.

    A subcategory of these errors are intermediate runtime errors that call installed error procedures. They are:

    • File error #
    • File error # on #
    • Transaction error #
    • Transaction error # on #

    where the # signs are replaced at run time by error names, numbers, or other information. See Appendix I. Library Routines for detailed discussion of the error and exit procedures.

The TRANSACTION-STATUS variable has the same format as a file's status variable. It is automatically created by the compiler, and is implicitly shared by all programs of a run unit. TRANSACTION-STATUS is a reserved word.

You can specify procedures for transaction error handling with the USE statement and the reserved word TRANSACTION. The syntax is:

USE AFTER STANDARD {EXCEPTION} PROCEDURE ON TRANSACTION
                   {ERROR    }

If TRANSACTION is specified, the procedure executes when an error occurs during a START TRANSACTION, COMMIT, ROLLBACK, or call to C$RECOVER.

A transaction error 10 is returned by a START TRANSACTION statement when the LOG-FILE configuration variable (that specifies the default log file) is undefined. The COBOL program may choose to ignore this error in the cases where the filename-LOG variables are used.

A transaction error 99 is returned by a START TRANSACTION statement when one of the host file systems in effect does not support transaction management. The runtime includes the RM/COBOL file handler (RMFM) as default, which does not support transactions. Even though you receive this warning message, the Vision file handler will continue to process transactions as expected. If your program does not rely on the RM/COBOL file handler, you can safely remove it from the runtime by setting the RMFM-DETACH 1 configuration variable, after which, you will not receive the warning.

Parent topic: Transaction Management
Previous topic: Configuration Variables
Next topic: Compiler File Options
Related reference
Transaction Error Codes
Related information
filesystem_DETACH


Compiler File Options

There are three compiler options that can simplify the addition of transaction management facilities to existing programs that use the Vision file system. The -Ft option causes implied transactions for every OPEN, CLOSE, WRITE, REWRITE, or DELETE operation that is not part of an explicit transaction. In other words, single file operations that are not part of a transaction are preceded by an implied START TRANSACTION and followed by an implied COMMIT. This makes it easier to convert existing applications to a transaction system.

The -Fs option causes an implied START TRANSACTION verb before the first OPEN, CLOSE, WRITE, REWRITE, or DELETE operation and after each COMMIT or ROLLBACK. This, in effect, makes every file operation part of a transaction. If this option is enabled, and the compiler encounters a START TRANSACTION verb, it reports a warning and does not generate any code for the START TRANSACTION. The -Fs option provides an alternate way to program transactions and is often useful when you are converting from other COBOL or SQL implementations.

A third compiler file option, -Fl, enables single locking rules rather than multiple locking rules as the lock mode default. Normally, WITH ROLLBACK causes multiple locking rules to be in effect for a file. When -Fl is used, the WITH ROLLBACK clause does not affect whether single or multiple record locking rules are followed. Single locking becomes the default. You may enable multiple locking either by specifying WITH LOCK ON MULTIPLE RECORDS in a file's SELECT statement or by using APPLY LOCK-HOLDING ON file in the I-O CONTROL paragraph.

Parent topic: Transaction Management
Previous topic: Transaction Error Handling
Next topic: Recovery


Recovery

If a program dies, or there is some other system failure, files may become corrupted, destroyed, or left in an inconsistent state. If this occurs, the files may be recovered with the built-in library routine, C$RECOVER.

For any Vision files or relative files, C$RECOVER can be successful only if every operation on the files, including file OPEN, was done within a transaction.

To use the recovery function, you need the most recent backup copy of all the files that record their transactions. You also need all of the log files that were started immediately after the backup was created. Here's one way to perform a recovery:

  1. Get everyone off the system.
  2. Restore backup files to original locations.
  3. Run a program that calls the C$RECOVER library routine (for example, CALL C$RECOVER). Use the same configuration file that the applications use. Note that the log files specified with the filename-LOG variables are not used.

The C$RECOVER library routine only recovers the updates recorded in the log file specified by the configuration variable LOG-FILE. To recover updates recorded in multiple log files, specify each log file in the LOG-FILE variable and call C$RECOVER for each one. For example:

    SET CONFIGURATION "LOG-FILE" TO "default.log".
    CALL "C$RECOVER".
    SET CONFIGURATION "LOG-FILE" TO "file1.log".
    CALL "C$RECOVER".
    SET CONFIGURATION "LOG-FILE" TO "file2.log".
    CALL "C$RECOVER".
    SET CONFIGURATION "LOG-FILE" TO "file3.log".
    CALL "C$RECOVER".

To ensure that your data can be recovered, you should:

  1. Make sure all transactions are committed before you do a backup.
  2. Clear or delete the log files only after your backup is complete.
  3. Make sure there is no file activity between the time the backup is made and the time you clear or delete the log files.
  4. In between backups, you can periodically archive log files, then clear or delete them.
  5. If you use archived log files, make sure you recover using the logs in the chronological order in which they were written.
  6. Make sure there is no other activity on the files during recovery.
  7. Make backups and start new log files immediately if any log file gets corrupted or destroyed.
  8. Make sure you have good log files.

The backup data files should have the same absolute or relative pathname as when the original programs were run. If there are any cases where relative pathnames are used for the log or data files, run the program that calls the C$RECOVER routine from the same directory as the original programs. For the program that calls the C$RECOVER routine, specify the log file in the configuration file or in the environment.

If the recovery process terminates prematurely due to an error, and files are left open, they are automatically closed before the call to C$RECOVER returns.

If a failure occurs during the recovery process, and no other copies of the backup files are available, then automatic recovery is not possible. This means that you should make sure to have an extra backup copy of your data files.

  1. Transaction logging and recovery with AcuServer
Parent topic: Transaction Management
Previous topic: Compiler File Options


Transaction logging and recovery with AcuServer

Transaction logging and recovery are possible on a network using AcuServer. Transaction logging and recovery of operations on remote files are also supported. See AcuServer) for more information.

Such recovery is possible only if each client runtime uses the same log file. To accomplish this, specify a host name, according to AcuServer rules, in each client's runtime configuration file. For example, to specify a single log file on a server with the host name sun, add the following line to each client runtime's configuration file:

LOG-FILE @sun:/usr2/users/cobol/mylogfile

Each client runtime with this configuration file entry will use the single server log file during its START TRANSACTION, ROLLBACK, and COMMIT processing. Temporary files used for rollback are created in the working directory, or in the directory specified by the LOG-DIR configuration variable of the client runtime.

Parent topic: Recovery


AcuServer

AcuServer is an add-on module that provides remote file access services to ACUCOBOL-GT applications. AcuServer is available for applications running on UNIX, Linux, and Windows TCP/IP based networks and executing with ACUCOBOL-GT runtime Version 5.0 or higher.

With AcuServer, your applications gain:

  • the ability to create and store data files on any UNIX or Windows NT/Windows 2000 server equipped with AcuServer
  • full function remote access from UNIX, Linux, and Windows clients to all Vision, relative, sequential and object files stored on an AcuServer server
  • full record locking support of all Vision and relative files
  • transparent access of remote and local files

AcuServer does not require any changes to your existing application code. (Some applications that contain hard coded paths to files must be modified to use the FILE_PREFIX environment variable, or to include the name of the file server in the path.)

AcuServer does not require that you recompile your existing programs. Programs compiled with any version of ACUCOBOL-GT can be executed ACUCOBOL-GT runtime version 5.0 or higher. Contact your Micro Focus extend Sales Professional for a current list of supported platforms.

The AcuServer User’s Guide contains installation instructions and a complete description of each AcuServer feature.

Above is an illustration of a simple AcuServer network. ACUCOBOL-GT applications running on UNIX and PC client systems access and store data files on a common UNIX or Windows NT/Windows 2000 file server running AcuServer. More complex networks might incorporate multiple AcuServer file servers supporting dozens of client machines running multiple applications.

  • Product Requirements
  • Remote Name Notation
Parent topic: File Processing


Product Requirements

See the extend Release Notes for information about AcuServer product requirements.

Parent topic: AcuServer


Remote Name Notation

Accessing remote files requires that your application refer to them with remote name notation. The ACUCOBOL-GT runtime looks for remote name notation to identify requests to AcuServer. Remote name notation has the following format:

@server-name:path-name

I/O requests to files prepended with @server-name:path-name are routed to AcuServer on the host specified by server-name. AcuServer looks for the named file in the directory specified by path-name, for example:

@condor:/usr/acct/inventory

To add a remote path to FILE_PREFIX or CODE-PREFIX, use the format:

FILE_PREFIX  @server-name:path-name
CODE_PREFIX  @server-name:path-name

As an alternative to FILE_PREFIX, you can define file name aliases in the runtime configuration file. A file name alias is a string that will replace the literal name in the ASSIGN TO clause of a SELECT statement. For example:

input-output section.
file-control.
    select idx-file
    assign to disk “IDXDAT”
    binary sequential
    status is idx-status.

To define an alias for IDXDAT you could add the following line to your runtime configuration file:

IDXDAT  @condor:/usr/data/index_data
Parent topic: AcuServer


XFD Files

The ACUCOBOL-GT compiler is capable of generating data dictionaries that store a map of COBOL record structures. These dictionaries are also called extended file descriptors (XFDs) because they're based on the standard COBOL file descriptors (FDs).

XFDs are used by Acu4GL to interface to database management systems and by AcuXML to interact with data in XML files. They are also used by alfred, Acucorp's record editor, and by AcuXDBC, Acucorp's database management system for Vision. In addition, they are used to help guide the mapping of international character sets between machines that use different underlying character codes.

The compiler creates an XFD for each indexed file in the compiled program when you specify the -Fx compile-time option. The -Fa option generates XFD files for all indexed, relative, and sequential files in the compiled program. Ordinarily, XFDs are generated in flat text file format. Use the -Fe option to generate XFD files in XML format instead. See File Options for details on these compiler options.

Acu4GL, AcuXDBC, and alfred can all read the XFD files in either format. XFDs are fully portable, and thus no recompilation is necessary if you change hardware.

The effects of all compile-time options, COPY REPLACING, and source-code control lines are reflected correctly in the XFDs.

  • Understanding how the XFD File is Formed
  • Defaults Used in XFD Files
  • Using Directives
  • Directive Syntax
  • XFD Format
Parent topic: File Processing


Understanding how the XFD File is Formed

Micro Focus's data dictionaries (XFDs) enable the Acu4GL and AcuXML interfaces to create a table (or access an existing one) in a database for each indexed, relative, or sequential file. Each column in the table contains the values for one field. The column names are essentially the field names.

XFDs also allow the alfred record editor to display and accept data in an indexed file at the field level, instead of character-by-character. If an XFD is available to alfred, it has enough information to display fields on the screen, instead of just groups of characters. This makes the screen easier to read, and helps make editing more efficient.

Each XFD file is based on the largest record in the COBOL file, and contains the fields from that record, plus any key fields (key fields are those which are named in KEY IS phrases of SELECT verbs in the File-Control section). This ensures that data from all COBOL records will fit within database tables, and simplifies the storage and retrieval process. If you were to examine the XFD file, only the fields from the largest record, and the key fields, would appear.

Note: If the field named in the KEY IS phrase is a group item, it will not be named as a field in the XFD file. This means it will not be used as a column in a database table, if you are using an Acu4GL interface, and it will not appear on the screen if you use the alfred editor. Instead, all elementary items subordinate to the named group item will be named in the XFD. You can force the group item to be a named field by using the USE GROUP directive.

With multiple record formats (level 01), not all COBOL fields are named in the XFD file, but all fields are storable and retrievable. The data dictionary maps fields from all records of a file to the corresponding locations in the master (largest) record of the file. Since Acu4GL and alfred have access to the data dictionary, they know where the data from a given COBOL record fits. This activity is invisible to the COBOL application.

For example, if your program has one file with the three records shown below, the underlined fields will be included as fields in the XFD file by default (this example assumes that ar-codes-key is named in a KEY IS phrase). Some fields will not appear by name in the file, but will be mapped to the master field names. The interface thus will eliminate redundancies and give you optimum performance.

01  ar-codes-record.
  03  ar-codes-key.
    05  ar-code-type      pic x.
    05  ar-code-num       pic 999.

01  ship-code-record.
  03  filler              pic x(4).
  03  ship-weight         pic s999v9.
  03  ship-instruct       pic x(15).

01  terms-code-record.
  03  filler              pic x(4).
  03  terms-rate-1        pic s9v999.
  03  terms-days-1        pic 9(3).
  03  terms-rate-2        pic s9v999.
  03  terms-descript      pic x(15).

The following diagram shows how Acu4GL creates database columns for some of the fields in the COBOL record, while other fields are mapped to those columns by the data dictionary; this means that all the fields are accessible to the COBOL program.

Parent topic: XFD Files


Defaults Used in XFD Files

There are several elements of COBOL that require special handling when data dictionaries are built. These include multiple record definitions, REDEFINES, FILLER, and OCCURS.

Note: In many instances you can override the default behavior described below by placing special comment lines in the FDs of your COBOL code. These comments are called directives. For example, the WHEN directive allows you to use multiple definitions for a single set of data by specifying when each definition should be used. See Using Directives for more information.

Databases generally do not support the notion of multiple definitions for the same column. (In a similar sense, when you are editing a data file, it makes sense to see and change only one view of the data, rather than multiple views.) As the following paragraphs explain, whenever a COBOL program gives more than one definition for the same data, the compiler makes a choice about which definition to use in the data dictionary. Then it disregards the rest.

  • KEY IS phrase
  • RENAMES clause
  • REDEFINES clause
  • Multiple record definitions
  • Group items
  • FILLER data items
  • OCCURS clauses
  • Summary of dictionary fields
  • Identical field names
  • Long field names
  • Naming the XFD
  • Examples of XFD names
Parent topic: XFD Files


KEY IS phrase

Fields named in KEY IS phrases of SELECT statements are included as fields in the XFD. Other fields that occupy the same areas as the key fields (by either explicit or implicit redefinition) are not included by name, but are mapped to the key field column names by the data dictionary.

Remember, if the field named in the KEY IS phrase is a group item, it will not become a named field in the XFD unless a USE GROUP directive is used (see "Understanding how the XFD file is formed").

Parent topic: Defaults Used in XFD Files


RENAMES clause

You may not use the RENAMES clause when creating data dictionaries. If you do, a file error results and the XFD is not created for that file. Instead of using the RENAMES clause, we recommend that you name the data segments in the usual ACUCOBOL-GT manner. For example:

ALTERNATE RECORD KEY K1-CUSTOMER =
     company-name,
     company-address2,
     company-zipcode2
ALTERNATE RECORD KEY K2-CUSTOMER
ALTERNATE RECORD KEY K3-CUSTOMER WITH DUPLICATES
ALTERNATE RECORD KEY K4-CUSTOMER =
     company-contact,
     k-customer
ALTERNATE RECORD KEY K5-CUSTOMER WITH DUPLICATES
ALTERNATE RECORD KEY K6-CUSTOMER =
     company-address3,
     company-zipcode3,
     company-country
     WITH DUPLICATES
Parent topic: Defaults Used in XFD Files


REDEFINES clause

Fields contained in a redefining item occupy the same positions as the fields being redefined. The compiler needs to select only one of the field definitions to use. The default rule that it follows is to use the fields in the item being redefined as column names; fields that appear subordinate to a REDEFINES clause are mapped to column names by the data dictionary.

Parent topic: Defaults Used in XFD Files


Multiple record definitions

This same rule extends to multiple record definitions. In COBOL, multiple record definitions are essentially redefinitions of the entire record area. This leads to the same complication that is encountered with REDEFINES: multiple definitions for the same data. So the compiler needs to select one definition to use.

Because the multiple record types can be different sizes, the compiler needs to use the largest one, so that it can cover all of the fields adequately. Thus, the compiler's rule is to use the fields in the largest record defined for the file. If more than one record is of the largest size, the compiler uses the first one.

Parent topic: Defaults Used in XFD Files


Group items

Group items are, by default, never included in a data dictionary for the same reason that REDEFINES are excluded: they result in multiple names for the same data items. You can, however, choose to combine grouped fields into one data item by specifying the USE GROUP directive, described in USE GROUP Directive.

Parent topic: Defaults Used in XFD Files


FILLER data items

In a COBOL FD, FILLER data items are essentially place holders. FILLER items are not uniquely named and thus cannot be uniquely referenced. For this reason, they are not placed into the Acucorp data dictionary. The dictionary maintains the correct mapping of the other fields, and no COBOL record positional information is lost.

Sometimes you need to include a FILLER data item, such as when it occurs as part of a key. In such a case, you could include it under a USE GROUP directive or give it a name of its own with the NAME directive. See NAME Directive for more information.

Parent topic: Defaults Used in XFD Files


OCCURS clauses

An OCCURS clause requires special handling, because the Acu4GL runtime system must assign a unique name to each database column. The runtime accomplishes this by appending sequential index numbers to the item named in the OCCURS.

For example, if the following were part of a file's description:

03  employee-table occurs 20 times.
    05  employee-number pic 9(3)

then these column names would be created in the database table:

employee_number_1
employee_number_2
.
.
.
employee_number_10
employee_number_11
.
.
employee_number_20
Note: The hyphens in the COBOL code are translated to underscores in database field names, and the index number is preceded by an extra underscore.

AcuXDBC users can make use of the SUBTABLE directive to modify how OCCURS clauses are handled. The alfred record editor shows only the names of the fields, without subscripts or indexes. See SUBTABLE Directive (AcuXDBC use only) for more information.

Parent topic: Defaults Used in XFD Files


Summary of dictionary fields

Fields defined with an OCCURS clause are assigned unique sequential names. Fields without names are disregarded.

When multiple fields occupy the same area, the compiler chooses only one of them unless you have a WHEN directive to distinguish them. To choose:

  • The compiler preserves fields mentioned in KEY IS phrases.
  • It discards group items unless USE GROUP is specified.
  • It discards REDEFINES.
  • It uses the largest record if there are multiple record definitions.
Parent topic: Defaults Used in XFD Files


Identical field names

In COBOL you distinguish fields with identical names by qualification. For example, there are two fields named RATE in the following code, but they can be qualified by their group items. Thus, you would reference RATE OF TERMS-CODE and RATE OF AR-CODE in your program:

01  record-area.
  03  terms-code.
    05  rate       pic s9v999.
    05  days       pic 9(3).
    05  descript   pic x(15).
  03  ar-code.
    05  rate       pic s9v999.
    05  days       pic 9(3).
    05  descript   pic x(15).

However, database systems consider duplicate names an error. Thus, if more than one field in a particular file has the same name, the data dictionary will not be generated for that file.

The solution to this situation is to add a NAME directive that associates an alternate name with one or both of the conflicting fields. See NAME Directive for more information.

Parent topic: Defaults Used in XFD Files


Long field names

The compiler determines whether field names are unique within the first 18 characters. This is because some RDBMSs truncate longer field names to 18 characters. (In the case of the OCCURS clause described above, the truncation is to the original name, not the appended index numbers.) If the field names are not unique within 18 characters, the XFD file is generated, but a warning message is issued.

You can, instead of allowing default truncation, use the NAME directive to give a shorter alias to a field with a long name. Note that within the COBOL application you will continue to use the original name. The NAME directive affects only the data dictionary.

Parent topic: Defaults Used in XFD Files


Naming the XFD

The compiler needs to give a name to each XFD file (data dictionary) that is built. It attempts to build the name from your COBOL code, although there are some instances where the name in the code is nonspecific, and you must provide a name.

Each XFD name is built from a starting name that is derived (if possible) from the SELECT statement in your COBOL code. The following paragraphs explain how that occurs.

ASSIGN name is a variable

If the SELECT for the file has a variable ASSIGN name (ASSIGN TO filename), then you must specify a starting name for the XFD file via a FILE directive in your code. This process is described inp topics FILE Directive.

ASSIGN name is a constant

If the SELECT for the file has a constant ASSIGN name (such as ASSIGN TO "COMPFILE"), then that name is used as the starting name for the XFD name.

ASSIGN name is generic

If the ASSIGN phrase refers to a generic device (such as ASSIGN TO "DISK"), then the compiler uses the SELECT name as the starting name.

Forming the final XFD name

From the starting name, the final name is formed as follows:

  1. The compiler removes any extensions from the starting name.
  2. It constructs a universal base name by stripping out directory information that fits any of the formats used by the operating systems that run ACUCOBOL-GT.
  3. It converts the base name to lower case.
  4. It appends the letters .xfd to the base name.
Note: The FD can specify the file name using the VALUE OF FILE_ID IS xxx clause. This phrase has a similar effect to the ASSIGN phrase of the SELECT statement, but when this phrase is used it overrides the ASSIGN phrase. So all of the above rules that relate to the ASSIGN phrase also relate to the FILE_ID phrase, when that phrase is used. Technically, the ASSIGN phrase and the FILE_ID phrase are supposed to be identical, but the compiler silently overrrides the ASSIGN with the FILE_ID phrase. See VALUE OF FILE-ID Clausefor more information.
Parent topic: Defaults Used in XFD Files


Examples of XFD names

COBOL code | File name
ASSIGN TO "usr/ar/customer.dat" | customer.xfd
SELECT TESTFILE, ASSIGN TO DISK | testfile.xfd
ASSIGN TO "-D SYS$LIB:HELP" | help.xfd
ASSIGN TO FILENAME | (you specify)
Parent topic: Defaults Used in XFD Files


Using Directives

Directives are optional comments that you can use in your FDs to control how things look in the XFD file. Many applications will not use directives at all. They're most commonly used when a site intends to do a lot of work with a database management system outside of the COBOL application, and wants to control how the database table is built. They are also used to customize how fields are displayed by the record editor, alfred.

Directives are special comments placed into an FD in your COBOL source code. They guide the building of the data dictionaries, which in turn guide the building of the database table (and the display of data in the record editor).

Each directive includes the letters XFD. These three letters indicate to the compiler that the comment is to be used in data dictionary generation.

Directives offer you a great deal of control over how the XFD file is built. Among other things, they enable you to:

  • specify a field name to be used in the XFD, in place of a COBOL field name
  • map elementary items of a group item together into a single field
  • cause numeric COBOL data to be treated as a text string in the XFD
  • cause the fields from a specific record in a file to appear in the XFD (rather than just the fields from the largest record)
  • mark specific fields as candidates for a secondary database table, if all of the data will not fit into a single table
  • cause a fixed-length field to be designated as variable-length
  • assign a column the DATE type, so that it will have the built-in functionality that dates have in an RDBMS
  • give a name to the data dictionary file itself
  • include comments in XFD files

Directives are always placed within a COBOL FD. They do not affect Procedure Division I/O statements, and they do not change your COBOL fields in any way. Rather, they guide the building of the data dictionaries, giving you a measure of control over the way COBOL data is mapped to XFD fields.

  • Important for Acu4GL and AcuXML sites
Parent topic: XFD Files


Important for Acu4GL and AcuXML sites

Each data item in your COBOL FD must correspond to a field in the database. You may have columns in a table for which no data item exists in the COBOL FD, but not vice versa. You may not have data items in your FD with no counterpart in the database.

This correspondence happens automatically when the database is newly generated by the Acu4GL or AcuXML interface. If the database is pre-existing, you should check for the correspondence, and use directives if necessary to make it complete.

Data dictionaries may be built directly from your source code with no directives if the default mapping rules described earlier are sufficient for your situation. If you would like to override the default mapping behavior, or map a field to a different name, then you would add directives to your COBOL code.

Parent topic: Using Directives


Directive Syntax

When you create XFD directives, there is a particular syntax you must follow.

  • Place each directive on a line by itself, immediately before the COBOL line to which it pertains.
  • Introduce each directive with a "$" in the Indicator Area (column 7 in standard ANSI source format), followed immediately by the letters "XFD", then the directive itself. There should be no space between the $ and the XFD. Spaces are permitted elsewhere on the line as separators. For example, the NAME directive looks like this:
    $XFD  NAME = EMP-NUMBER
  • An alternate ANSI-compliant way to introduce a directive is with an asterisk (*) in the Indicator Area. In this case, you begin the directive with the letters "XFD" and enclose the entire comment in double parentheses. For example:
    *(( XFD  NAME = EMP-NUMBER ))

    There should be no space between the asterisk and the double left parentheses. Spaces are permitted elsewhere on the line as separators.

    You may use either form of the directive syntax (or both) in your applications.

  • Two or more directives that pertain to the same line of COBOL code may be combined on one comment line. The directives should be separated by a space or a comma. For example, to specify both USE GROUP and NUMERIC at the same time, you would add this line:
    $XFD  USE GROUP, NUMERIC

    or

    *(( XFD  USE GROUP, NUMERIC ))
  • ALPHA Directive
  • BINARY Directive
  • COBOL-TRIGGER Directive
  • COMMENT Directive
  • DATE Directive
  • FILE Directive
  • NAME Directive
  • NUMERIC Directive
  • SECONDARY-TABLE Directive
  • SUBTABLE Directive (AcuXDBC use only)
  • USE GROUP Directive
  • VAR-LENGTH Directive
  • WHEN Directive
  • XSL Directive
Parent topic: XFD Files


ALPHA Directive

The ALPHA directive allows you to treat a data item as alphanumeric text in the database, when it is declared as numeric in the COBOL program. Also, ALPHA causes the alfred record editor to edit the field as alphanumeric instead of as numeric.

Syntax

$XFD ALPHA

or

*(( XFD ALPHA ))

This is especially useful when you have numeric keys in which you occasionally store non-numeric data, such as LOW-VALUES or special codes. In this situation, treating the field as alphanumeric allows you to move any kind of data to it.

Example

Suppose you have specified KEY IS code-key. Then assume the following record definition:

01  code-record.
  03  code-key.
    05  code-num   pic 9(5).

In a database, group items are disregarded, so CODE-NUM is the actual key field. Suppose you needed to move a non-numeric value to the key:

MOVE "C0531" TO CODE-KEY.
WRITE CODE-RECORD.

In this case, the results are not well-defined, because a non-numeric value has been moved into a numeric field. The database might very well reject the record.

One way to solve this problem is to use the ALPHA directive. This causes the corresponding database field to accept alphanumeric data:

01  code-record.
   03  code-key.
$XFD ALPHA
     05  code-num   pic 9(5).

As an alternative, you could specify the USE GROUP directive on the line before code-key. The USE GROUP directive implies that the field is alphanumeric. See USE GROUP Directive for more information.

Parent topic: Directive Syntax


BINARY Directive

The BINARY directive is used to specify that the data in the field could be alphanumeric data of any classification. Absolutely any data is allowed.

The method of storing fields declared as binary is database-specific.

Syntax

$XFD BINARY

or

*(( XFD BINARY ))

Example

You might use this directive when you need to store a key that contains LOW-VALUES; COBOL allows a numeric field to contain LOW or HIGH values, but these are invalid for a numeric field in the RDBMS:

01  code-record.
  03  code-key.
    05  code-indic    pic x.
*(( XFD BINARY ))
    05  code-num      pic 9(5).
    05  code-suffix   pic x(3).
      .
      .
      .
move low-values to code-num.
Parent topic: Directive Syntax


COBOL-TRIGGER Directive

Use this directive to indicate that a COBOL trigger is to be executed.

Syntax

$XFD COBOL-TRIGGER=program name

or

*(( XFD COBOL-TRIGGER=program-name ))

This XFD must be located immediately before the FD of the file for which the trigger is defined.

Three parameters are passed to the COBL program:

01  OPCODE.
    88  READ-BEFORE         VALUE "r".
    88  READ-AFTER          VALUE "R".
    88  WRITE-BEFORE        VALUE "w".
    88  WRITE-AFTER         VALUE "W".
    88  REWRITE-BEFORE      VALUE "u".
    88  REWRITE-AFTER       VALUE "U".
    88  DELETE-BEFORE       VALUE "d".
    88  DELETE-AFTER        VALUE "D".

01  FILE-RECORD             PIC X(MAX-RECORD-SIZE).

01  ERROR-CODE              PIC 99.

You can use the C$PARAMSIZE library routine to determine the size of the record passed, in case you have variable-length records. See Appendix I. Library Routines for more information on C$PARAMSIZE.

  • In cases where the record size is known, the actual record is passed (READ-AFTER (all), WRITE-BEFORE, WRITE-AFTER, REWRITE-BEFORE, REWRITE-AFTER)
  • In cases where the record size is not known, the maximum record size is passed (READ-BEFORE (all), DELETE-BEFORE, DELETE-AFTER

The contents of this field will be identical to the record area given to the file operation. The BEFORE images will have the value before the file operation, and the AFTER images will have the value after the file operation.

Use the ERROR-CODE parameter to signal to Acu4GL that an error occurred.

  • Setting this in a BEFORE trigger causes the actual file operation to not execute
  • Setting this in an AFTER trigger causes the runtime to treat the file operation as an error, though in fact the file operation did execute

This means that, for sequential access (next or previous), the file position has changed and a subsequent next or previous will act as if the prior file operation succeeded. Also, setting an error in the REWRITE-AFTER or DELETE-AFTER will not actually return the record to its prior state — the record will be modified or deleted in the database. We suggest using transactions if this behavior is not acceptable.

If the COBOL program can not be called (for any reason), it is treated as having succeeded.

Parent topic: Directive Syntax


COMMENT Directive

The COMMENT directive allows you to include comments in an XFD file. Comments enable you to embed information in the XFD file that might be useful to other applications that access the data dictionary. Because the information is embedded in a comment, it does not interfere with processing by the Acu4GL database interfaces. A comment is any line in the XFD file that starts with "#" in column 1.

Syntax

$XFD COMMENT comment

or

*(( XFD COMMENT comment ))

The text following the directive is copied into the XFD file as a comment. For example:

$XFD COMMENT This is a comment
Parent topic: Directive Syntax


DATE Directive

The DATE directive instructs the runtime to store a field in the database as a date or a time. Because there's no COBOL syntax that identifies a field as a date or time, you may want to add this directive to differentiate dates or times from other numbers, so that they enjoy the properties associated with dates or times in the RDBMS.

Syntax

$XFD DATE=date-format-string

or

*(( XFD DATE=date-format-string ))

The date-format-string is a description of the desired date or time format in the COBOL program, composed of characters from the following list:

M | month (01 – 12)
Y | year (2 or 4-digit)
D | day of month (01 – 31)
J | Julian day (00000000 – 99999999)
E | day of year (001 – 366)
H | hour (00 – 23)
N | minute
S | second
T | hundredths of a second

Any other characters cause the date-format-string to be invalid and result in a corrupt XFD error or a compile-time warning.

Each character in a date-format-string can be considered a place holder that represents the type of information stored at that location. The characters also determine how many digits will be used for each type of data.

For example, although you would typically represent the month with two digits, if you specify MMM as part of your date format, the resulting date will use three digits for the month, left-zero-filling the value. If the month is given as M, the resulting date will use a single digit and will truncate on the left.

If you do not specify a date-format-string, the default is YYMMDD if the field has six digits, or YYYYMMDD if the field has eight digits.

Julian dates

Because the definition of Julian day varies, the DATE directive offers a great deal of flexibility for representing Julian dates. Many source books define the Julian day as the day of the year, with January 1st being 001, January 2nd being 002, and so forth. If you want to use this definition for Julian day, simply use EEE (day of year) in your date formats.

Other reference books define the Julian day as the number of days since some specific "base date" in the past. This definition is represented in the DATE directive with the letter "J" (for example, a six-digit date field would be preceded with the directive "$XFD DATE=JJJJJJ"). The default "base date" for this form of Julian date is 12/31/4714 BC.

You may define your own base date for Julian date calculations by setting the runtime configuration variable 4GL-JULIAN-BASE-DATE. The value of this variable must have the format YYYYMMDD. For more information, see the Acu4GL User's Guide.

Using group items

You may place the DATE directive in front of a group item, as long as you also use the USE GROUP directive (see Example 2, below).

Example 1

$xfd date
    03 date-hired     pic 9(8).
    03 pay-scale      pic x(3).

The column date-hired will have eight digits and will be type DATE in the database, with a format of YYYYMMDD.

Example 2

*(( XFD DATE, USE GROUP ))
    03  date-hired.
      05   yyyy    pic 9(4).
      05   mm      pic 9(2).
      05   dd      pic 9(2).

This also will produce a column named date-hired with eight digits and type DATE in the database, format YYYYMMDD.

Example 3

*(( XFD DATE=EEEYYYY))
    03  date-sold      pic 9(7).
    03  sales-rep      pic x(30).

This will produce a column named date-sold with seven digits and type DATE in the database. The date will contain the day of the year (for example, February 1st would be 032), followed by the four-digit year, such as 1999.

Example 4

Note: This format and data type is only applicable with SQL Server, and only when using the SQL Server Native Client 11.0 (or later) ODBC driver.
$XFD DATE=HHNNSSTTT
   03 trans-time pic 9(9).

This produces a column named trans-time containing data items of type TIME. The time is represented down to the hundredths of a second (for example, 123030030 represents a time of 12:30:30.03).

FY and RY date formats

The FH and RY date format characters have very precise requirements and are used to handle a specific case in which eight-digit dates are expressed in six characters.

Instead of YYYY or YY, you can specify FY to mean that the first character of the year specifies the decade instead of the "tens" year. The decade can be a character between space (" ") and "I" (inclusive). For the characters "0" through "9" to be treated as decades in the 20th century, the decade characters have the following meaning:

 | 00 | 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90
1700 |  |  |  |  | spc | ! | " | # | $ | %
1800 | & | ' | ( | ) | * | + | , | - | . | /
1900 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
2000 | : | ; | < | = | > | ? | @ | A | B | C
2010 | D | E | F | G | H | I |  |  |  |

This means that a date of ?70210 is converted to 20570210, or February 10, 2057. The range of valid dates is 00101 (Jan 1, 1740) through I91231 (Dec 31, 2159).

Instead of YYYY or YY, you can also specify RY to mean that the first character of the year specifies the decade and that the entire date is to be 9s complement (to be able to sort dates in reverse order). Note that the entire date and time is treated as a 9s complement number in this case. The decade characters have the following meaning:

 | 00 | 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90
1700 |  |  |  |  | I | H | G | F | E | D
1800 | C | B | A | @ | ? | > | = | < | ; | :
1900 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
2000 | / | . | - | , | + | * | ) | ( | ' | &
2010 | % | $ | # | " | ! | spc |  |  |  |

The date 20570210 is now specified with *29789. The range of valid dates is I99898 (Jan 1, 1740) through 08768 (Dec 31, 2159), the same valid range as when using F instead of R.

While using F and R before month, day, hour, or any other format specifier does not generate a compile error for the XFD, the results are undefined at run time.

Note that if you use these format specifiers with Acu4GL, the actual date is written to the database, not the encoded date. This means that the R specifier is not very useful in this scenario (you won't be able to read forward through a file in reverse date order). This format specifier is more useful with AcuXDBC, where the data is in indexed file format.

Parent topic: Directive Syntax


FILE Directive

The FILE directive supplies a starting name from which the XFD file name is formed. This directive is required only when the file name in the COBOL code is nonspecific. For example, you would use this directive when the SELECT for the file has a variable ASSIGN name (ASSIGN TO variable_name). In this situation, the interface cannot form a file name automatically, and you must provide a name.

A starting name is simply a short file name that serves as the basis for the XFD name.

Syntax

$XFD FILE=name

or

*(( XFD FILE=name ))

This directive must appear on the line immediately preceding the file's FD.

Special characters (such as $) can be included within the filename if the name is surrounded by either single or double quotes. For example:

$XFD FILE="f$test"

No quotes are required if the filename does not include special characters.

Example

Suppose your SELECT statement has a variable ASSIGN name such as the one shown here:

select my-file
  assign to my-variable.

You would need to add the FILE directive as shown here:

 select my-file
   assign to my-variable.
   .
   .
   .
$xfd  file=payroll
 fd my-file
Parent topic: Directive Syntax


NAME Directive

The NAME directive assigns a field name to the field defined on the next line.

Syntax

$XFD NAME=fieldname

or

*(( XFD NAME=fieldname ))

This directive has several uses, as shown in the following examples.

Example 1

Within a database file, all field names must be unique. (Multiple database tables may include the same field name, but duplicates may not exist within a single table.) Unique field names are not required in COBOL, because names can be qualified by group items. For example, in COBOL this is done:

01  employee-record.
  03  date-hired.
    05  yy   pic 99.
    05  mm   pic 99.
    05  dd   pic 99.
  03  date-last-paid.
    05  yy   pic 99.
    05  mm   pic 99.
    05  dd   pic 99.

You need not change the field names in your COBOL program to access a database. Instead, you use the NAME directive to provide unique database names for the fields. For example:

 01  employee-record.
   03  date-hired.
     05  yy   pic 99.
     05  mm   pic 99.
     05  dd   pic 99.
   03  date-last-paid.
*(( xfd  name=year-paid ))
     05  yy   pic 99.
$xfd  name=month-paid
     05  mm   pic 99.
$xfd  name=day-paid
     05  dd   pic 99.

The dates portion of the resulting database table will look like:

yy | mm | dd | year_paid | month_paid | day_paid
88 | 02 | 15 | 94 | 04 | 30

Example 2

Some SQL-based databases require that names be no more than 18 characters long. For those systems, the Acu4GL run-time will automatically truncate longer COBOL names after the eighteenth character.

If you have names that are identical within the first 18 characters, or that would not be meaningful to you if shortened to the first 18 characters, you can use the NAME directive to assign them different database field names.

For example, a portion of your database might contain:

01  acme-employee-record.
  03  acme-employee-record-date-hired
      pic x(6).
  03  acme-employee-record-date-last-paid
      pic x(6).

You could add two NAME directives to differentiate the two item names by making them meaningful within 18 characters:

 01  acme-employee-record.
$xfd  name=date-hired
   03  acme-employee-record-date-hired
       pic x(6).
$xfd  name=date-last-paid
   03  acme-employee-record-date-last-paid
       pic x(6).
Note:

Your COBOL names have not changed. The new names are used only for the XFD fields.

Each time you compile your program and specify the CREATEXFD configuration variable to create XFDs, any field names longer than 18 characters will be checked for uniqueness within the first 18. If any field names are identical for the first 18 characters, a compiler warning message will be issued. A warning of this type does not prevent the program from compiling and does not prevent the XFD from being generated.

Example 3

You may want to use the NAME directive to assign shorter names than those used in your COBOL programs. This makes the formation of interactive SQL queries easier and quicker. For example:

*(( XFD  NAME=EMPNO ))
  03  employee-number  pic x(8).

This directive causes the XFD to map EMPLOYEE-NUMBER to EMPNO in the database.

Example 4

If your database already exists, and a field name in the database does not match the name used in your COBOL FD, you can use a NAME directive to associate the two names. For example:

$xfd  name=employee-no
  03  employee-number  pic x(8).

This directive causes the XFD to map EMPLOYEE-NUMBER in the COBOL program to EMPLOYEE-NO in the database.

Example 5

If your COBOL program uses field names that begin with a numeric character, use the NAME directive to assign a different name for use with your database. SQL will typically generate a syntax error when it encounters a column name that begins with a numeric character. For example:

  03  12-months-sales   pic 9(5)V99.

could be renamed this way:

$xfd  name=twelve-months-sales
  03  12-months-sales   pic 9(5)V99.
Parent topic: Directive Syntax


NUMERIC Directive

The NUMERIC directive allows you to treat a data item as an unsigned integer when it is declared as alphanumeric. You might use this when the data stored in the item is always numeric.

Syntax

$XFD NUMERIC

or

*(( XFD NUMERIC ))

Example

$xfd numeric
 01   student-code   pic x(7).
Parent topic: Directive Syntax


SECONDARY-TABLE Directive

Some RDBMSs permit subordinate tables. When this is the case, you can use the SECONDARY-TABLE directive to indicate that the next data item may be placed into a subordinate table, if more than one table is necessary to accommodate the data.

Up to 16 subordinate tables can be created from a single record description. Each table name is based on the original table name, with a letter from "A" to "P" appended. For example, if the original table were named "my-table," subsequent subordinate tables would be given these names:

  • my-tableA
  • my-tableB
  • my-tableC
  • my-tableD

When the runtime accesses the XFD, it makes an initial pass through the data, taking all eligible data items for which the SECONDARY-TABLE directive is not specified.

SECONDARY-TABLE is ignored for certain data items. These include:

  • Any field that is part of a key
  • Any field that is referenced in a WHEN directive

If the table size is not exceeded in the first pass, then in a second pass, the runtime appends to the original table all items marked SECONDARY-TABLE that can be accommodated.

When the first table reaches a limit (either in total number of columns or total number of characters), that table is created, and a new table is begun. Items that did not fit into the previous table are placed into a subordinate table, in the order in which they are encountered.

The process repeats until all items have been accommodated.

It's permissible to place the SECONDARY-TABLE directive just before a level 01 record definition. In this case, it applies to all fields underneath the level 01.

Syntax

$XFD SECONDARY-TABLE

or

*(( XFD SECONDARY-TABLE ))

Example

$xfd secondary-table
 01  description   pic x(80).
Parent topic: Directive Syntax


SUBTABLE Directive (AcuXDBC use only)

This directive modifies the way fields that appear in an OCCURS clause are processed resulting in the creation of subtables. This directive instructs the XFD parsing routines not to append the occurrence number to the field name, as would normally take place with OCCURS clauses, but instead store just the base name along with the name of the subtable as written in the XFD file. See OCCURS clauses in the ACUCOBOL-GT User's Guide for more information.

Syntax

$XFD SUBTABLE=name

or

*(( XFD SUBTABLE=name ))

Example

*((XFD SUBTABLE=subtab1))
    03 employee-table occurs 10 times.
        05 employee-number    pic 9(3).
Note: AcuXDBC is the only product that currently makes use of this directive. Using this directive with other products such as Acu4GL will result in errors.
Parent topic: Directive Syntax


USE GROUP Directive

The USE GROUP directive allows you to enter a group item into the XFD as a single field, instead of using the elements contained in the group. This is necessary if the item is stored in a pre-existing database as a group, rather than as individual fields.

Combining fields of data into meaningful groups for database storage also improves I/O efficiency.

Syntax

$XFD USE GROUP

or

*(( XFD USE GROUP ))

By default, the USE GROUP directive implies that the consolidated field is alphanumeric. If you want a numeric field, simply add the word NUMERIC at the end of the directive.

Example 1

For example, the directive in the following code combines the functions of the USE GROUP and DATE directives, and indicates that the date should be entered into the XFD as a single date-formatted data item instead of three distinct fields:

*(( XFD  USE GROUP, DATE ))
  03  date-entered.
    05  yy   pic 99.
    05  mm   pic 99.
    05  dd   pic 99.

Either a comma or a space (or both) may separate the word DATE from the words USE GROUP.

Example 2

Other fields with which you might use this directive include multi-part account numbers or department numbers, or keys that are referenced as a unit but not by their individual pieces. Here's an example of an item that might be grouped:

$xfd  use group
 01  gl-acct-no.
   03  main-acct     pic 9(4).
   03  sub-acct      pic 9(3).
   03  dept-no       pic 9(3).

If you are using a pre-existing database in which certain fields are grouped, they must also be grouped in your COBOL FD.

If the database does not yet exist, keep in mind that combining fields into groups typically improves execution speed. Whether to group fields or not also depends on how you want to process them. Do you always store and use the fields together? Someone who really knows how the data is being used might help to identify groups of fields that can be combined to speed processing.

Parent topic: Directive Syntax


VAR-LENGTH Directive

By default, the compiler generates fixed-length fields in the XFD. The VAR-LENGTH directive requests that the data item that immediately follows the directive be assigned a type that implies variable length, if possible. This can save considerable space in your database.

The precise variable type that is assigned to the data item depends on which DBMS is in use.

Possible variable types that might be assigned are VARCHAR and VARBINARY.

Syntax

$XFD VAR-LENGTH

or

*(( XFD VAR-LENGTH ))

Example

For example, the directive in the following code indicates that the employee-name field should be entered into a database as a VARCHAR data item.

*(( XFD  VAR-LENGTH ))
  03  employee-name   pic x(45).
Parent topic: Directive Syntax


WHEN Directive

The WHEN directive is used when you want to include multiple record definitions or REDEFINES in the XFD file. It’s typically used when you want to force certain database columns to be built that would not be built by default (because you want to use them from the RDBMS side). It can also force certain fields to be displayed in the alfred record editor.

Note: You cannot use the WHEN directive in an OCCURS clause.

Recall that the key fields and the fields from the largest record are automatically included as explicit fields in the XFD file. All fields are stored and retrieved, whether they appear as explicit fields or not. So you do not need to use WHEN unless you want to ensure that some additional fields are explicitly listed by name in the XFD.

WHEN declares that the field (or subordinate fields, if it is a group item) that immediately follows the directive must appear as a field (or fields) in the XFD. It also states one condition under which the fields are to be used. WHEN thus guarantees you that the fields will be explicitly included in the XFD (as long as they are not FILLER and do not occupy the same area as key fields).

A WHEN directive may also be assigned an optional tablename. If you assign a tablename, then the data that immediately follows the WHEN directive and meets the specified condition will be considered as a separate table.

Syntax

$XFD WHEN field=value [TABLENAME=name] (equals)
$XFD WHEN field=OTHER [TABLENAME=name] (equals)
$XFD WHEN field<=value [TABLENAME=name] (is less than or equal)
$XFD WHEN field<value [TABLENAME=name] (is less than)
$XFD WHEN field>=value [TABLENAME=name] (is greater than or equal)
$XFD WHEN field>value [TABLENAME=name] (is greater than)
$XFD WHEN field!=value [TABLENAME=name] (is not equal to)

or

*((XFD WHEN field=value [TABLENAME=name])) (also <, <=, >, >=, !=)

The value may be an explicit data value (in quotes). The word OTHER, which can be used only with “=”, means “use the field(s) that are subject to the WHEN OTHER condition only if none of the other WHEN conditions listed for this field is met.”

Note: Keep in mind the distinction between a field subject to a condition and a field in a WHEN condition (i.e., the field for which a condition is listed). A field subject to a WHEN condition is one that immediately follows the WHEN directive or is subordinate to a group item that immediately follows the WHEN directive. The field in a WHEN condition is the field before the arithmetic operator and is a part of the directive itself.

In other words, a WHEN OTHER condition is true if all other WHEN conditions with the same field in them are false. If a WHEN condition is false, the fields subject to it are not written.

For example:

 01 ar-code-type.
*(( xfd when ar-code-type = "s" ))
  03 ship-code-record pic x(4).
*(( xfd when ar-code-type = "b" ))
  03 backorder-code-record redefines
    ship-code-record.
*(( xfd when ar-code-type = other ))
  03 obsolete-code-record redefines
    ship-code-record.

OTHER may be used before one record definition, and may be used once at each nesting level within each record definition.

Note: A WHEN directive with condition OTHER must be used if there is a possibility that the data in the field will not meet any of the explicit equality conditions specified in the other WHEN directives; if this is not done, results are undefined.

Example1

If the following code were compiled without directives, the underlined fields would appear explicitly in the XFD file. Note that the key fields, and the fields from the longest record, would be included automatically. FILLER would be ignored:

01 ar-codes-record.
  03 ar-codes-key.
    05 ar-code-type    pic x.
    05 ar-code-num     pic 999.
01 ship-code-record.
  03 filler            pic x(4).
  03 ship-instruct     pic x(15).
01 terms-code-record.
  03 filler            pic x(4).
  03 terms-rate-1      pic s9v999.
  03 terms-days-1      pic 9(3).
  03 terms-rate-2      pic s9v999.
  03 terms-descript    pic x(15).

If you added the WHEN directive as shown below, it would cause the fields from the SHIP-CODE-RECORD to be included in the XFD file, and would determine when specific fields would be used. The underlined fields would appear as columns in a database table if you were using Acu4GL:

 01 ar-codes-record.
   03 ar-codes-key.
     05 ar-code-type      pic x.
     05 ar-code-num       pic 999.
$xfd when ar-code-type = "s"
 01 ship-code-record.
   03 filler              pic x(4).
   03 ship-instruct       pic x(15).
$xfd when ar-code-type = "t"
 01 terms-code-record.
   03 filler              pic x(4).
   03 terms-rate-1        pic s9v999.
   03 terms-days-1        pic 9(3)
   03 terms-rate-2        pic s9v999.
   03 terms-descript      pic x(15).

FILLER data items do not have unique names and are thus not used to form field names in the XFD. You could use the NAME directive to give them a name if you really need to have them in the XFD. However, in this example the FILLER data items implicitly redefine key fields. Thus, they would be disregarded even if you provided a name for them.

Example 2

In the following code, in which no WHEN directives are used, the underlined fields will be explicitly named in the XFD. (Key fields have the suffix key in their names in this example.)

Note: REDEFINES records simply re-map the same data area and are not explicitly included in the XFD by default.
01 archive-record.
  03 filler               pic x(33).
  03 archive-code         pic 9(6).
  03 archive-location     pic 9(2).
  03 filler               pic x(10).
01 master-record.
  03 animal-id-key.
    05 patient-id         pic 9(6).
    05 species-code-type  pic 9(5).
    05 species-name       pic x(6).
  03 service-code-key.
    05 service-code-type  pic 9(6).
    05 service-name       pic x(10).
  03 billing-code.
    05 billing-code-type  pic 9(4).
    05 plan-name          pic x(8).
  03 office-info.
    05 date-in-office     pic 9(8).
    05 served-by-name     pic x(10).
  03 remote-info redefines office-info.
    05 van-id             pic 9(4).
    05 proc-code          pic 9(8).
    05 vet-name           pic x(6).

If you added the WHEN directives shown below, you would add several fields to the XFD. The fields that would appear are underlined:

*(( xfd when animal-id-key = "00000000000000000" ))
 01 archive-record.
   03 filler              pic x(33).
   03 archive-code        pic 9(6).
   03 archive-location    pic 9(2).
   03 filler              pic x(10).
*(( xfd when animal-id-key = other ))
 01 master-record.
*(( xfd use group ))
   03 animal-id-key.
     05 patient-id        pic 9(6).
     05 species-code-type pic 9(5).
     05 species-name      pic x(6).
   03 service-code-key.
     05 service-code-type pic 9(6).
     05 service-name      pic x(10).
   03 billing-code.
     05 billing-code-type pic 9(4).
     05 plan-name         pic x(8).
*(( xfd when billing-code-type = "1440" ))
   03 office-info.
     05 date-in-office    pic 9(8).
     05 served-by-name    pic x(10).
*(( xfd when billing-code-type = other ))
   03 remote-info redefines office-info.
     05 van-id            pic 9(4).
     05 proc-code         pic 9(8).
     05 vet-name          pic x(6).

Example 3

If your application has a REDEFINES whose field names are more meaningful than the fields they redefine, you might consider switching the order of your code, rather than using a WHEN directive. Use the less significant field names in the REDEFINES. For example, you might change this:

   03 code-info.
     05 filler        pic 9(8).
     05 code-1        pic x(10).
   03 patient-info redefines code-info.
     05 patient-id    pic 9(4).
     05 service-code  pic 9(8).
     05 server-name   pic x(6).

to this:

   03 patient-info.
     05 patient-id    pic 9(4).
     05 service-code  pic 9(8).
     05 server-name   pic x(6).
   03 code-info redefines patient-info.
     05 filler        pic 9(8).
     05 code-1        pic x(10).

The fields that would appear in the XFD by default are underlined above. This shows how the XFD field names might become more meaningful when the order is reversed. Your application operates the same either way.

Note: When a WHEN directive condition is met, COBOL record definitions or REDEFINES records that are subordinate to other WHEN directives are not used. Database columns in rows which correspond to those records are set to the special database value “NULL”. This means that there is no value provided for those columns. “NULL” is not equivalent to zero, and it has special properties in the RDBMS. For example, you can select all rows for which a given column is NULL.

Example 4

This COBOL code:

 01 example4-record.
   03 col-type            pic x.
$xfd when col-type = "a"
   03 def1                pic x(2).
$xfd when col-type = "b"
   03 def2 redefines def1 pic 9(2).

will result in this database table:

col_type | def1 | def2
a | xx | null
b | null | xx
a | yy | null
Parent topic: Directive Syntax


XSL Directive

If you are using the -Fe compiler option to generate XML-style XFD files, the XSL directive allows you to include a stylesheet reference in the XML header.

Syntax

$XFD XSL=stylesheet

or

*(( XFD XSL="stylesheet" ))

where stylesheet is an alphanumeric literal indicating the appropriate stylesheet. The compiler includes the following line in all generated XML-style XFD files:

<?xml-stylesheet type="text/xsl" href="stylesheet"?>

For example:

*(( XFD XSL="myxsl.xsl" ))

generates this line:

<?xml-stylesheet type="text/xsl" href="myxsl.xsl"?>
Parent topic: Directive Syntax


XFD Format

An XFD file may be created either as a simple text file or as an XML file. In either case, the XFD contains a description of a COBOL indexed, sequential, or relative file based on its fields.

  • Identification Section
  • Key Section
  • Condition Section
  • Field Section
Parent topic: XFD Files


Identification Section

The identification section describes the data file described by the XFD. It contains information about the version of XFD created and the data file type (indexed, relative, or sequential). It also lists the data file's SELECT and base file name, as well as basic record information (such as minimum and maximum record size and number of keys).

Consider the following SELECT statement:

SELECT clients ASSIGN TO DISK "clients.dat"
ORGANIZATION IS INDEXED
...
RECORD KEY IS cl-client-id
ALTERNATE RECORD KEY IS key01 = cl-first-name, cl-last-name
  WITH DUPLICATES.

In a simple text XFD, the identification section appears similar to the following:

# [Identification Section]
XFD,06,CLIENTS,CLIENTS,12
0000000197,0000000197,002
000,18,046,044,00

Here, XFD,06 specifies that the XFD file was created in version 6 format. The SELECT and base file name are both CLIENTS, and the data file is in indexed format (12). The other available file formats are relative (08), and sequential (04).

The minimum and maximum record length for the file described in the XFD are the same (0000000197), and there are 002 keys.

The next line of digits are derived from various compile options and program settings that may be used when creating the XFD. The first three-digit sequence (000) indicates sign compatibility. The possible values are:

  • FLG_ACU_SIGNS = 000
  • FLG_IBM_SIGNS = 004
  • FLG_MF_SIGNS = 008
  • FLG_NCR_SIGNS = 020
  • FLG_VAX_SIGNS = 036
  • FLG_MBP_SIGNS = 072
  • FLG_REA_SIGNS = 128

The above values are set by the -Dc compiler options. See Data Storage Options for details on using these options.

The next two-digit sequence (18) indicates the maximum numeric digits. The possible values are 18 and 31. This is set by the -Dd31 compiler option.

The next three-digit sequence (046) indicates the decimal value of the character used as the program period.

The next three-digit sequence (044) indicates the decimal value of the character used as the program comma.

The last two-digit sequence (00) is a UNICODE indicator.

In XML format, the same information is presented as follows:

<xfd:identification xfd:version="6">
  <xfd:select-name>CLIENTS</xfd:select-name>
  <xfd:table-name>CLIENTS</xfd:table-name>
  <xfd:file-organization>Indexed</xfd:file-organization>
  <xfd:maximum-record-size>197</xfd:maximum-record-size>
  <xfd:minimum-record-size>197</xfd:minimum-record-size>
  <xfd:number-of-keys>2</xfd:number-of-keys>
  <xfd:sign-compatibility>0</xfd:sign-compatibility>
  <xfd:maximum-numeric-digits>18</xfd:maximum-numeric-digits>
  <xfd:period-character>.</xfd:period-character>
  <xfd:comma-character>,</xfd:comma-character>
  <xfd:alphabet>ASCII</xfd:alphabet>
</xfd:identification>
Parent topic: XFD Format


Key Section

The key section contains an entry for each key in the file. The following example refers to the SELECT cited in the previous section, and shows the key information in a simple text format:

# [Key Section]
01,0,005,0000000000
01
CL-CLIENT-ID
02,1,015,0000000005,015,0000000020
02
CL-FIRST-NAME
CL-LAST-NAME

For each key, there is a line describing the number of segments in the key, whether or not the key allows duplicates, and the size and offset for each segment in the key. Segment size and offset are repeated as necessary to describe each segment in the key.

In the example given, the primary key (CL-CLIENT-ID), is defined as having one segment and being a unique key (01,0). The size of the segment is 5 (005), and the offset is 0.

The alternate key is defined as having two segments and allowing alternates (02,1). The first segment is described as having a size of 15 and an offset of 5; the second segment also has a size of 15, but its offset is 20.

The next line in each key description contains the number of elementary field definitions defined in the key. For the primary key in the example, there is one elementary field. In the alternate key, there are two.

The remaining lines in the key section give the name of each elementary field contained in the key.

In XML format, the key section appears as follows:

<xfd:keys>
  <xfd:key xfd:segment-count="1" xfd:duplicates-allowed="false">
    <xfd:segments>
      <xfd:segment xfd:segment-size="5" xfd:segment-offset="0"/>
    </xfd:segments>
    <xfd:key-columns xfd:key-column-count="1">
      <xfd:key-column xfd:key-column-name="CL-CLIENT-ID"/>
    </xfd:key-columns>
  </xfd:key>
  <xfd:key xfd:segment-count="2" xfd:duplicates-allowed="true">
    <xfd:segments>
      <xfd:segment xfd:segment-size="15" xfd:segment-offset="5"/>
      <xfd:segment xfd:segment-size="15" xfd:segment-offset="20"/>
    </xfd:segments>
    <xfd:key-columns xfd:key-column-count="2">
      <xfd:key-column xfd:key-column-name="CL-FIRST-NAME"/>
      <xfd:key-column xfd:key-column-name="CL-LAST-NAME"/>
    </xfd:key-columns>
  </xfd:key>
</xfd:keys>
Parent topic: XFD Format


Condition Section

Condition definitions identify fields that are not present in every record. This section of the XFD specifies the number of condition definitions set, followed by the actual definitions. Each definition appears on its own line, and contains the condition number and type. A table of condition types appears at the end of this section.

In a simple text XFD, the condition section appears as follows:

# [Condition Section]
001
001,4,CL-CLIENT-ID,200

Here, there is one condition (001). Condition number 001 is a type 4 (greater than, ">") condition specifying that the field CL-CLIENT-ID is greater than 200.

In XML format, the same condition section would appear as follows:

<xfd:conditions xfd:condition-count="1" >
  <xfd:condition xfd:condition-number="1">
    <xfd:condition-comparison>gt</xfd:condition-comparison>
    <xfd:condition-variable>CL-CLIENT-ID</xfd:condition-variable>
    <xfd:condition-value>200</xfd:condition-value>
  </xfd:condition>
</xfd:conditions>

The recognized condition types are:

Type | Description
1 | Equal to (=)
2 | And
3 | Other
4 | Greater than (>)
5 | Greater than or equal to (>=)
6 | Less than (<)
7 | Less than or equal to (<=)
8 | Not equal to (!=)
9 | Or
Parent topic: XFD Format


Field Section

The final section of the XFD is the field section. This is the longest section of the file, because it describes all of the fields contained in the data file.

The file begins with a line describing the number of elementary fields defined for inclusion in the XFD (four digits), the total number of elementary fields in the file (five digits), the number of group and elementary fields listed in the FD (five digits), and the total number of group and elementary fields listed in the FD (five digits).

These last two items — the number and total number of group and elementary fields — may be different if the FD contains an OCCURS clause. Although the total number is increased by the number of times the item OCCURS, the item still has only one listing in the field section of the XFD. Total number is also affected by redefines, group items, and multiple FD descriptions, but it excludes filler fields.

Following the summary line, the field section contains a line for each field definition, listing:

  • The field offset, in bytes (10 digits)
  • The field size, in bytes (10 digits)
  • The field type, as described in the following table:
    Type Values | Description
    0 | Numeric edited
    1 | Unsigned numeric
    2 | Signed numeric (trailing separate)
    3 | Signed numeric (training combined)
    4 | Signed numeric (leading separate)
    5 | Signed numeric (leading combined)
    6 | Signed computational
    7 | Unsigned computational
    8 | Positive packed-decimal
    9 | Signed packed-decimal
    10 | Computational-6
    11 | Signed binary
    12 | Unsigned binary
    13 | Signed native-order binary
    14 | Unsigned native-order binary
    16 | Alphanumeric
    17 | Alphanumeric (justified)
    18 | Alphabetic
    19 | Alphabetic (justified)
    20 | Alphanumeric edited
    22 | Group
    23 | Float or double
    24 | National
    25 | National (justified)
    26 | National edited
    27 | Wide
    28 | Wide (justified)
    29 | Wide edited
  • For numeric fields, this holds the number of digits in the field. For non-numeric fields, the number shown is the same as the size of the field (10 digits).
  • The scale of the field (+ or - and a two-digit number), expressed as a power of 10. The scale for non-numeric fields is "0".
  • The field's "user type":
    "000" | no user type
    "001" | date fields
    "002" | binary fields
    "003" | variable-length character
    If "secondary table" is used, 16 is added to the value. So "017" would be the entry for a date in the secondary table.
  • The condition number to apply to this field. This is "000" if the field appears in every record, or "999" if the field is a group item.
  • The field level number (2 digits)
  • The field name (30 characters)
  • An optional date format if the field is a date (only included if you put a date_format_string in your COBOL program)

When a field uses the OCCURS phrase, two special entries appear in the list of field definitions. These entries are designated by offsets of 90001 and 90002. The START-OCCURS entry is defined as follows:

90001,num-occurs,size,START-OCCURS

The END-OCCURS entry is defined as follows:

90002,END-OCCURS

The fields contained in the OCCURS clause are listed between these markers using normal field notation.

Fields that are not defined for actual use but that occur in the FD are indicated by the special condition marker 999.

A simple text field section would appear as follows:

# [Field Section]
0010,00010,00011,00011
0000000000,0000000197,16,0000000197,+00,000,999,01,CLIENT-RECORD
0000000000,0000000005,01,0000000005,+00,000,000,05,CL-CLIENT-ID
0000000005,0000000015,16,0000000015,+00,000,000,05,CL-FIRST-NAME
0000000020,0000000015,16,0000000015,+00,000,000,05,CL-LAST-NAME
0000000035,0000000040,16,0000000040,+00,000,000,05,CL-STREET-ADDR
0000000075,0000000030,16,0000000030,+00,000,000,05,CL-CITY
0000000105,0000000020,16,0000000020,+00,000,000,05,CL-STATE-PROV
0000000125,0000000006,16,0000000006,+00,000,000,05,CL-POST-CODE
0000000131,0000000013,16,0000000013,+00,000,000,05,CL-COUNTRY
0000000144,0000000013,16,0000000013,+00,000,000,05,CL-TEL
0000000157,0000000040,16,0000000040,+00,000,000,05,CL-EMAIL

In an XML-format XFD, the field section description appears as follows:

  <xfd:fields
    xfd:elementary-items="10"
    xfd:elementary-items-with-occurs="10"
    xfd:total-items="11"
    xfd:total-items-with-occurs="11">
    <xfd:field
      xfd:field-offset="0"
      xfd:field-bytes="197"
      xfd:field-type="16"
      xfd:field-length="197"
      xfd:field-scale="0"
      xfd:field-user-flags="0"
      xfd:field-condition="999"
      xfd:field-level="1"
      xfd:field-name="CLIENT-RECORD"
    />
    <xfd:field
      xfd:field-offset="0"
      xfd:field-bytes="5"
      xfd:field-type="1"
      xfd:field-length="5"
      xfd:field-scale="0"
      xfd:field-user-flags="0"
      xfd:field-condition="0"
      xfd:field-level="5"
      xfd:field-name="CL-CLIENT-ID"
    />
   .
   .
   .
  </xfd:fields>
Parent topic: XFD Format


International Character Handling

This section explains how to exchange data between different types of hardware that use different character code sets. Not all machines use the same codes for the characters that are outside of the standard ASCII character set (those whose underlying decimal values are 128 or larger). But you can overcome these differences by setting up a simple character map file and then pointing to your map file with a runtime configuration variable. Character mapping is triggered by the presence (on the client machine) of a configuration variable that points to the map file. Only single-byte alphanumeric characters are mapped.

Mapping might be essential for sites using the AcuServer product to retrieve and store data on a remote server. Sites that use AcuConnect to launch programs on a remote server might need character mapping to ensure that parameter values returned for their CALL statements are correctly translated. Sites using AcuODBC to access Vision data files on a remote machine may need to provide a map file for the client.

The map file is a simple text file that you create with any text editor. You can choose any name for it that you like. It should contain two values on each line. The first value on the line indicates the decimal or hexadecimal value of the character on the client machine. The second value on the line indicates the decimal or hexadecimal value of the corresponding character on the server machine. Hexadecimal values use the standard "0x" notation. For example:

0x90  0xC9

maps "E" (acute) in the IBM PC character set to "E" (acute) in the ISO8859-1 character set.

Only those character codes that differ between the two machines need to be included in the map file. This might include characters with a grave accent, acute accent, circumflex, tilde, umlaut, and so forth.

You can check the values of specific characters by using the Windows Character Map accessory in the PC environment, or by referring to your UNIX man pages in the UNIX environment.

As data moves from the client machine to the server, each alphanumeric character that appears in the first position of a map file entry is mapped to the corresponding second character in that entry. A character coming from the server to the client is mapped in reverse: from the second value listed to the first value listed. Each line in the map file thus sets up a one-to-one mapping.

The map is used to translate only single-byte alphanumeric fields. All group items are treated as alphanumeric, so you may want to restructure them to eliminate numeric fields within the group. Data items that are subject to a REDEFINES clause need to be examined with care. For example, if the data looks like this:

03  customer-info          pic x(150).
03  customer-detail redefines customer-info.
      05 customer-name     pic x(30).
      05 customer-code     pic 9(20).
      05 customer-address1 pic x(25).
      05 customer-address2 pic x(25).
      05 customer-address3 pic x(25).
      05 customer-address4 pic x(25).

then you might need to reorganize or restructure the data definition to ensure that numeric fields are not translated.

  • Files Required for Translation
Parent topic: File Processing


Files Required for Translation

International character mapping makes use of three files: your map file of corresponding character codes (explained above), an XFD file that the compiler creates to describe the structure of data files, and a runtime configuration file that points to the location of both the map file and the XFD file. This section provides more details about each of these files. Note that file names are not translated, so remote files should use only standard ASCII characters in their file names.

Map File:Your map file of corresponding character codes may be stored on either the client or the server machine. One advantage of storing it on a server is that many clients can access the same map file. If it needs to be changed, a single update benefits all clients. To make a remote map file accessible to a client, you need to run the AcuServer remote file access product on the server.

XFD File: In order to determine whether a data item is alphanumeric, the mapping process for AcuServer and AcuODBC makes use of a data dictionary (also known as an XFD file). (AcuConnect does not require this file.) The XFD file stores the structure of the COBOL records in a format that the runtime can access. An XFD file must be created at compile-time for each program that will use the mapping process. It is created with the -Fx or -Fa compile-time option. The XFD files may be stored on either the client machine or the server machine. If they are located on the server, you must have the AcuServer product on that server, to enable client access. If an XFD file cannot be found, no error message is generated, but no character translation occurs.

Runtime Configuration File: The runtime configuration file on the client machine must identify the location of the character map file and the XFD files. Remote name notation can be used to specify remote locations.

Set XFD_DIRECTORY to specify the directory for the XFD files (the default is the current directory). AcuConnect does not require XFD files.

Set DEFAULT_MAP_FILE to specify the name and location of the character map file.

If you have more than one map file (because you have different types of servers), you can associate a map file with a particular server by using the configuration variable server_MAP_FILE to point to a map file on a particular server machine. For example, if you are using AcuServer to access remote files on a machine named sun3, you would use remote name notation to specify the directory that contains the data files. It might look like this:

@sun3:/user/acct/inventory

Then, use this configuration variable to point to the map file:

sun3-map-file  @sun3:/user/acct/inventory/map.txt

If the map file is local, your value might look like this:

sun3-map-file  C:\user\utility\map.txt
Note: The server specified in the configuration variable name must match the server specified in the remote file name. The map file may be stored on either the client machine or the server machine. If it is located on the server, you must have the AcuServer product on that server, to enable client access.

The runtime looks first for server-MAP-FILE. If that variable is not set, the runtime looks for DEFAULT-MAP-FILE. If that variable is also not set, no translation is done.

Parent topic: International Character Handling


Programmer's Guide

  • Handling Files
  • Terminal IO
  • Memory Management
  • Memory Testing and Error Handling
  • Screen Section
  • Data Validation
  • Exiting From ACUCOBOL-GT Programs
  • Multiple Execution Threads
  • Working with External Sort Modules on UNIX
Parent topic: ACUCOBOL-GT User's Guide


Handling Files

Managing files forms the central focus of most COBOL applications. This section discusses the implementation and special features of the three types of files: sequential, relative, and indexed.

ACUCOBOL-GT supports variable-length records in accordance with ANSI standards for all file types. A file's records are variable-length whenever any one of these conditions is true:

  • The RECORD CONTAINS clause contains the VARYING phrase.
  • The RECORD CONTAINS clause contains both a minimum and maximum size.
  • There is no RECORD CONTAINS clause but the file's FD specifies more than one record, and those records have different sizes.

A file's records are fixed-length whenever:

  • The RECORD CONTAINS clause specifies only a maximum record size.
  • There is no RECORD CONTAINS clause, and the file's FD does not specify multiple records having different sizes.
Note: ACUCOBOL-GT automatically closes all of its files if it is killed by the user. However, a power failure, turning off the computer, or issuing a kill -9 from the console are catastrophic exits. In these cases, ACUCOBOL-GT cannot close its files.
  • Sequential Files
  • Relative Files
  • Indexed Files - Vision
  • Record Locking
  • Device Locking Under UNIX
  • Indexed File Considerations
  • Performance Considerations
  • Limits on Open Files
Parent topic: Programmer's Guide


Sequential Files

ACUCOBOL-GT treats sequential files in one of two ways. One form is called binary sequential; the other form is called line sequential. Note that RECORD SEQUENTIAL is synonymous with BINARY SEQUENTIAL.

Binary sequential files are designed to contain non-ASCII information and are easy to move to foreign systems. A binary sequential file consists of either fixed-length or variable-length records grouped together into blocks.

Variable-length binary sequential records occupy only as much disk space as necessary. If the maximum record size is equal to or less than 65,535 bytes, two bytes indicating record size (VLI) are placed in front of each variable-length record when it is written to disk. If the record size is larger than 65,535 bytes, four bytes are placed in front of each variable-length record. This two- or four-byte field is not specified in your COBOL program, and non-COBOL programs that access the records need to be aware of the extra bytes.

All I/O on the physical device is done using the block size, except for the last block. Only that portion of the last block that contains records is read. The default block size is one record. You can change block size with the BLOCK CONTAINS clause.

On VMS systems, binary sequential files are sequential RMS files with fixed-length or variable-length records.

Line sequential files contain variable-sized records. These files are designed to be printed and to be used with other programs, such as editors. The exact form of these files depends on the host system, and thus they should not generally be treated as portable files. On many machines, these files consist of variable-length lines delimited by carriage-control characters. These files should contain only USAGE DISPLAY data so as not to inadvertently introduce stray carriage-control characters.

On Windows systems, a line sequential file contains each data record followed by a carriage-return/line-feed pair. On UNIX systems, these files use just a line feed as the delimiter. On VMS systems, a line sequential file is a sequential RMS file with variable-length records.

ACUCOBOL-GT performs all of its I/O on line sequential files according to the following rules. If the file is blocked (i.e., it has a BLOCK CONTAINS clause), then all I/O is done by blocks. Otherwise, all output is done one record at a time. Input, on the other hand, is internally blocked by runcbl. This provides an efficient interface while still providing line-by-line control over a print device (which may be needed to do form alignment, for example).

Line sequential files further break into two types, print files and variable-length files. Print files are similar to variable-length files except that different line-delimiting characters are used. These characters are chosen so that the resulting file will print correctly. Print files may not be opened for INPUT or I-O. Print files are designed to be efficiently printed.

When a line sequential file is read, the default behavior is that any carriage-return, line-feed, or form-feed characters in the record are removed before the record is made available to the program. See Runtime Configuration for information on changing this default behavior.

Some line sequential files have automatic blank stripping. This causes records written to the file to have any trailing spaces in the record removed before it is written to the file. All print files have automatic blank stripping. You can specify blank stripping for other line sequential files by choosing one of the following device types in the file's ASSIGN phrase: CARD-PUNCH, CARD-READER, CASSETTE, INPUT, INPUT-OUTPUT, MAGNETIC-TAPE or OUTPUT. See the ACUCOBOL-GT Reference Manual for details on the ASSIGN phrase.

When reading from a variable-length sequential file, runcbl treats short records in one of two ways. If blank-stripping is specified for the file, then the short records are padded with spaces to fill out to the maximum record size. If blank-stripping is not specified, then the trailing portion of the record is left unchanged (from the most recent contents of the record area).

The runtime system allows a sequential file to be opened for input when the user does not have write-access to the file.

Parent topic: Handling Files


Relative Files

Relative files are generally used to store data where low overhead is required. Records are available by record number. On machines that directly support relative files (such as VMS), relative files are used.

On other machines (Windows and UNIX systems), relative files are treated the same as binary sequential files. Each record is physically located at its record number, and writing record 1 and record 1000 causes 999 blank records to be written. Block sizes are ignored, and each I/O uses the record size to determine how many bytes to transfer.

Records may be either fixed-length or variable-length. With variable-length records, if the maximum record size is equal to or less than 65,535 bytes, two bytes indicating record size (VLI) are placed in front of each variable-length record when it is written to disk. If the record size is larger than 65,535 bytes, four bytes are placed in front of each variable-length record. This two- or four-byte field is not specified in your COBOL program, but other non-COBOL programs that access the records need to be aware of the extra bytes. Each record is padded to the maximum size so that records can be retrieved randomly in an efficient fashion.

When a record is deleted, the physical record is filled with up to 256 null characters (LOW-VALUES in ACUCOBOL-GT). This deleted record marker can be changed through the use of the REL_DELETED_VALUE configuration variable. Note that ACUCOBOL-GT checks only the first 256 characters of the record to determine if it is deleted.

Relative files may be assigned only to disk files.

On many (but not all) systems, the runtime system allows a relative file to be opened for input when the user does not have write-access to the file.

Parent topic: Handling Files


Indexed Files - Vision

Vision is ACUCOBOL-GT's native indexed sequential file system. It provides fast, flexible, and reliable data storage to ACUCOBOL-GT applications in all environments except VMS where ACUCOBOL-GT uses the native RMS file system. Vision handles small or large amounts of data with equal efficiency and provides rapid access to data using optimized indexes, sequential reading, or a combination of indexed START and sequential READ statements. Vision handles all ANSI standard COBOL data types. The Vision file system is described here.

Vision Version 6

Vision 6 is similar to Vision 5, except that it uses a 64-bit offset file I/O. Where available, Vision 6 is the default, but for systems that do not have 64-bit offset file I/O, Vision 6 is unavailable, and Vision 5 is the default.

With Vision 6, maintaining multiple 2GB file segments for very large files is not required, which reduces the potential for file breakage due to mishandled file segments. It also reduces the number of OS file handles required to open a very large Vision file. This is because Vision 6 files only have one data and one index segment; each of which may grow to nearly 128TB, due to the use of 48-bit file offsets.

Previous Vision versions (version 3-5) are still supported. Vision 2 support has ceased as of extend version 10.2.0, due to the architecture-dependent nature of the file format; to continue to use these files, update them to at least Vision 3.

No special action is required to start using Vision 6. To create indexed files with an earlier file format, set the V_VERSION environment variable to the appropriate value.

Vision Version 5 and 4

Vision Version 5 and 4 use a dual file format. One file, or segment, holds the data records and another segment holds the key information. When a segment approaches the file size limit (configurable up to nearly 2 GB), Vision creates a new data or index segment in which to store more information. The dual file format provides several key benefits:

  1. The maximum size of Vision 5 and 4 files is virtually unlimited. Individual data and index segments can be up to 2 GB in size.
  2. Separating data and key information provides a higher degree of reliability when files must be rebuilt.
  3. Permanent data loss due to memory-related problems is less likely to impact two files.

Vision Version 5 is a superset of Version 4. The rules that apply to Version 4 segment file naming also apply to Version 5.

ACUCOBOL-GT uses Vision Version 5 by default. Vision Version 5 is the most recent and advanced Vision version. Version 5 supports the following capabilities that Version 4 does not:

  • records up to 64 megabytes in size
  • block sizes up to 8192 bytes
  • very large pre-allocate and extension factors
  • the ability to recover deleted records (that have not yet been overwritten by subsequent writes)

Vision Version 3

Vision Version 3 files are generated in a single file that contains both the data records and the key information. A separate linked list is maintained and used to rebuild corrupted files. A linked list of deleted records is also maintained so that new records first reuse space held by deleted records before new space is consumed. The single file format supports a maximum file size of two gigabytes.

On many (but not all) systems, the run time system allows an indexed file to be opened for input when the user does not have write-access to the file.

Indexed files may be assigned only to disk files.

  • Segment Naming of Vision 6 Files
  • Segment Naming of Vision 4 and 5 Files
  • Method One: The Format Method
  • Method Two: The Default Method
  • Overriding Individual Segment Names
  • Selecting the Vision Version
  • Keys
  • Other Vision Features
Parent topic: Handling Files


Segment Naming of Vision 6 Files

Vision 6 files only have one data and one index segment, each of which may grow to nearly 128TB due to the use of 48-bit file offsets.

New indexed files are created as Vision 6 files unless the V_VERSION configuration variable specifies otherwise. If Vision 6 is not available for a particular system, Vision 5 is the default.

The UNIX configuration variable LARGE_FILE_LIMIT_1TB default setting is ON for HP-UX ports only. It is common for HP-UX systems to be configured with file systems that only support large files up to 1TB. Trying to use file offsets larger than that generate I/O errors even though large file access is available. Set this configuration variable to OFF for HP-UX systems that support file access larger than 1TB when a Vision file larger than 1TB is needed.

The i_info() Vision API function and the I$IO standard library function now return a result with larger fields when called with mode -8 to obtain the file name and size. See the sample/def/filesys.def FILE-SEGMENT-INFO data items for the exact details of the new result structure returned.

Parent topic: Indexed Files - Vision


Segment Naming of Vision 4 and 5 Files

File segments generated for Vision Version 5 and 4 files can be given customized extensions.

The naming rules described below do not apply to the first data segment. The name of the first segment is set in the same way that the name of any other data file is set. In this discussion, the name of the first segment is referred to as the regular name.

Note: Turning on level 3 or higher file tracing in the debugger ("tf 3") causes the output of file diagnostics that show the names used for active segments of a Vision Version 5 or 4 file. Also, "vutil -info" displays the names of all segments of a Vision Version 5 or 4 file.

Vision Versions 5 and 4 use two methods to determine the file names of additional index and data segments (after the first segment).

  • The first method allows the user to specify a "format" from which Vision generates the names of additional segments.
  • The second method (the default) automatically generates the names of additional segments using the base name as a template.

Both methods allow specific generated file names to be overridden.

The first method takes precedence over the second. That is, if circumstances allow Vision to use the first method, it is used. If not, the second method is used.

In both methods, environment variables are used to indicate how Vision is to determine the names of additional segments. You form the names of these environment variables by taking the regular name of the file, converting all the alphabetic characters to upper case, leaving numeric characters alone, and converting all other characters to underscores ("_"). Thus, gl42.dat becomes GL42_DAT. This name is typically suffixed with another string, depending upon which method you are using, as described below. The runtime looks for these variables in the runtime configuration file. Utilities such as vio and vutil look for them in the operating system's environment.

Parent topic: Indexed Files - Vision


Method One: The Format Method

This method lets you specify a format that Vision uses to determine the file names of additional segments. Two formats must be specified: a format for data file extensions and a format for index file extensions. The resulting variables have this general look: filename_DATA_FMT and filename_INDEX_FMT. Each of these variables must be equated with a format code that includes an escape sequence. The valid escape sequences are defined below.

Example for Method One

Suppose the regular name of your COBOL file is /usr1/gl.dat. The variables you would use to set the segment naming formats for this file are GL_DAT_DATA_FMT and GL_DAT_INDEX_FMT.

Each of these variables must be set equal to a pattern that shows how to create the segment names. The pattern shows how to form the base name and how to form the extension for each segment. Part of this pattern is a special character (such as %d) that specifies how the segment number should be represented. Choices include %d (decimal segment numbers), %x (lower case hexadecimal numbers), %X (uppercase hexadecimal numbers), and %o (octal numbers).

For example, setting environment variables GL_DAT_DATA_FMT=gl%d.dat and GL_DAT_INDEX_FMT=gl%d.idx would result in data segments named /usr1/gl.dat (remember that the first data segment is not affected), /usr1/gl1.dat, /usr1/gl2.dat, and so forth. The index segments would be named /usr1/gl0.idx, /usr1/gl1.idx, /usr1/gl2.idx, and so forth.

Escape Sequence Definitions

The %d in the values of the filename-DATA-FMT and filename-INDEX-FMT variables above is a printf-style escape sequence. Most reference books on the C language contain an in-depth explanation of these escape sequences, and UNIX systems typically have a man page (man printf) that explains them in detail. Here are the basics:

  • "%d" expands into the decimal representation of the segment number.
  • "%x" expands into the hexadecimal representation (with lower case a-f) of the segment number.
  • "%X" expands into the hexadecimal representation (with upper case A-F) of the segment number.
  • "%o" expands into the octal representation of the segment number.
  • You can add leading zeros to the number (to keep all the file names the same length) by placing a zero and a length digit between the percent sign and the following character. "%02d" would result in 00, 01, 02, and so forth when expanded.
  • To embed a literal "%" in the file name, use "%%".
The escape sequence can be positioned anywhere in the file name, including the extension.
Note: The run time checks for these segment naming variables in the run-time configuration file. Utilities such as vutil and vio check in the operating system's environment.
Parent topic: Indexed Files - Vision


Method Two: The Default Method

The default method uses the regular file name to determine the file names of additional segments. This method stores the segment number in the extension of the file name. If you use the extension of the file name to distinguish files that are otherwise named the same, you should not use this method.

This method takes the regular file name and removes the extension (if any) from that name. It then adds .vix to generate the name for the first index segment. Subsequent index segments are named with .v01 through .vff (hexadecimal representation) for the first 255, and .v0100 through .vffff for segments 256 through 65536. The data segments are named using a similar numbering scheme, but use d instead of v before the segment number.

You should avoid using file name extensions that can be considered as d or v followed by a hexadecimal number. For example, the extension .dae is not safe, because that is the name of the 175th data segment. The common extension .dat is safe because t is not a hexadecimal digit.

Parent topic: Indexed Files - Vision


Overriding Individual Segment Names

You can override an individual generated segment file name by setting an environment variable named by the generated file name of the segment (converted as described above) to the full path of the desired file name. As an example, suppose the regular name of your file is /usr1/gl.dat, and you have GL_DAT_DATA_FMT=gl%d.dat set, but you want to place the second data segment on /usr2. Setting GL1_DAT=/usr2/gl1.dat will override the originally determined name. This feature works with both methods. Using the file names generated by the default method as environment variables (converted as described above) works, too.

Parent topic: Indexed Files - Vision


Selecting the Vision Version

You can control what Vision file format is applied to new Vision files through the V_VERSION and filename_VERSION configuration variables. The value of V_VERSION specifies the default format for new Vision files. The filename_VERSION variable allows you to set the file format on a file-by-file basis. Filename is replaced by the base name of the file (the filename minus directory and extension). These variables take an integer value that corresponds to the Vision Version that you want applied (6, 5, 4, 3, 2). For more information about these configuration variables, see Appendix H. Configuration Variables.

Parent topic: Indexed Files - Vision


Keys

Vision files allow up to 120 keys for sorting. One key is the primary key, all others are alternates. In a record, a key may not occupy physical space that exceeds the minimum record length. Thus, a 10-byte key cannot occupy positions 20-29 in a record with a minimum record length of 28.

You can specify whether duplicates are allowed for the primary key and for each alternate key. If duplicates are allowed for a particular key, it is possible to write a record whose key fields contain exactly the same data as the key fields of an existing record. In this case, the records are stored in chronological order.

Note: It is generally recommended that you not allow duplicate primary keys unless the file is processed only in ACCESS SEQUENTIAL mode. Allowing duplicate primary keys in files that are processed in DYNAMIC and RANDOM access modes, could generate unanticipated results. The rules that govern the treatment of duplicate primary key values are presented in File-Control Paragraph.

Every alternate key causes significant additional overhead. (Keys have the least amount of overhead when duplicates are allowed to occur.) The keys for a data file are automatically stored in a compressed form.

A key may be a contiguous part of the records, or it may be split into as many as 16 segments. If you are compiling for compatibility with versions earlier than Vision Version 4, you can have no more than six segments. You must use Vision Version 4, or later, if you want more than six segments.

Suppose you have the following record structure in a file called AJAX-SUPPLIES:

01  CUSTOMER-RECORD.
    03  CUSTOMER-NO           PIC 9(6).
    03  CUSTOMER-BALANCE      PIC S9(9)V99.
    03  CUSTOMER-NAME         PIC X(30).
    03  CUSTOMER-CONTACT      PIC X(30).

To use CUSTOMER-NAME as the primary key, you would use the syntax shown in the last line below:

FILE-CONTROL.
     SELECT AJAX-SUPPLIES
     ASSIGN TO DISK "INDEX.DAT"
     RECORD KEY IS CUSTOMER-NAME.

If data elements are contiguous and defined in the order that would be used for sorting, they may be grouped and defined together as a key. For example, suppose you wanted to use CUSTOMER-BALANCE, CUSTOMER-NAME as an alternate key. Because these two fields are contiguous and are defined in the same sequence they will be used for sorting, the most efficient way to define the alternate key is to establish a group item that includes both fields. For example:

01  CUSTOMER RECORD
    03  CUSTOMER-NO               PIC 9(6).
    03  CUSTOMER-BALNAME.
        05  CUSTOMER-BALANCE      PIC S9(9)V99.
        05  CUSTOMER-NAME         PIC X(30).
    03  CUSTOMER-CONTACT          PIC X(30).

Then, to define CUSTOMER-BALNAME as an alternate key, you would use the syntax shown in the last line below:

FILE-CONTROL.
     SELECT AJAX-SUPPLIES
     ASSIGN TO DISK "INDEX.DAT"
     RECORD KEY IS CUSTOMER-NAME
     ALTERNATE KEY IS CUSTOMER-BALNAME.

Suppose now that you want to define a sort sequence that uses fields that are not contiguous, or are defined in a different order from the sorting order. In this case, you could either:

  • move the fields around, or duplicate them, so that they are contiguous and are in the same sequence in which they will be used for sorting
  • define a split key

Split keys allow you to specify up to 16 segments of data elements as the components of a key. (Note that if you compile for compatibility with versions earlier than Vision Version 4, you can have no more than six segments.) The data segments need not be contiguous and need not be listed in the order they appear within the record. The composite length of a split key cannot exceed 250 bytes, and no key can be defined beyond the minimum record length.

For example, to define an alternate key consisting of CUSTOMER-BALANCE, CUSTOMER-NAME, and CUSTOMER-NO, use the syntax shown in the last two lines below:

FILE-CONTROL.
    SELECT AJAX-SUPPLIES
    ASSIGN TO DISK "INDEX.DAT"
    RECORD KEY IS CUSTOMER-NAME
    ALTERNATE RECORD KEY IS CUSTOMER-BALNAME
    ALTERNATE RECORD KEY IS BAL2-KEY =
      CUSTOMER-BALANCE, CUSTOMER-NAME, CUSTOMER-NO.

In this example, BAL2-KEY is a user-defined word and is the name you would use in your READ and START statements. Note that BAL2-KEY is not defined in Working-Storage. This is the only definition of the key.

Parent topic: Indexed Files - Vision


Other Vision Features

Block Size

Vision files have a block size (physical record size) of between 512 and 8192 bytes (in 512 byte increments). The block size specifies how large a node is in the Vision index tree. The block size of Vision Version 3 or 4 files is restricted to 1024 bytes. The block size is specified by the BLOCK CONTAINS clause. If the BLOCK CONTAINS clause is omitted, the file contains 512 byte blocks. See BLOCK CONTAINS Clause for more information.

Each index node holds a number of key entries and pointers to other nodes or record data. The larger the block size, the more key entries each node can store. Also, larger block sizes produce shorter index trees. However, larger index nodes can cause Vision to spend more time performing linear searches of each node to find the desired key entry. Therefore, it is important to determine the optimal block size for your particular key and data structure. If you have very large keys, a larger block size can help keep the tree height manageable. If you have smaller keys, a large block size will produce a short tree, but performance may be lost in the time it takes Vision to scan each of the large nodes.

Some experimentation will help you determine the optimal block size for your application and hardware. In the past, Vision has used 512 and 1024 byte block sizes. Users have reported good results with these values. If your keys are small- or medium-size, try using the 512 or 1024 block sizes. If you have a file with large keys and you are using Vision 5 or Vision 6 files, you might want to experiment a larger block size.

Compression and Encryption

Vision can optionally compress and/or encrypt records. Record compression uses a simple run-length compression algorithm. Encryption uses a byte transformation algorithm that is unique to every byte in the file. Encrypted files may not have records extracted by the Vision utility program vutil. Records are stored internally in the least amount of space required. Furthermore, they are packed together and span block boundaries, so no disk space is wasted. Compression is discussed in more detail in Compression.

User Count

Vision maintains a user count for each file. This count is normally zero. When a file is opened for update, the user count is incremented; when the file is closed, the user count is decremented. The user count is thus the number of currently updating processes for the file. If a program dies catastrophically, however, the user count will not get decremented. This results in the count never reaching zero. Thus, if the value is non-zero when there are no active users, it indicates a catastrophic program failure and suggests that corrective action may need to be taken. At the very least, the file should be checked for integrity, but depending on the program that died, perhaps more significant action should be taken. Basically a non-zero user count indicates that someone knowledgeable about the system should intervene and ensure that everything is okay. This can be used as an early warning system to head off some problems. Note that a non-zero user count is not a fatal error to Vision. It is used only as an indicator of potential problems. See Exiting From ACUCOBOL-GT Programs for a definition of catastrophic.

Parent topic: Indexed Files - Vision


Record Locking

Record locking for indexed and relative files is used for all machines. Currently, record locking is not supported for sequential files. Only files opened in the I/O mode will actually lock records; input-only files will not lock records they read. Record locking occurs in one of two modes: automatic (the default) and manual. In automatic mode, a record is locked when it is read (unless the WITH NO LOCK or ALLOWING UPDATES phrase of the READ statement is used). In manual mode, records are locked only when WITH LOCK is specified on the read statement. Both modes support single and multiple record locks. When single record locks are used (the default), the currently locked record is released whenever any I/O statement is executed for the file. When multiple record locks are used, records become unlocked only when an UNLOCK or CLOSE statement is executed for the file (or a COMMIT is executed for a transaction file).

It is possible to get a record locked condition when you are doing a READ, REWRITE, or DELETE on a file.

On most machines, a READ performed without locking will not get a record-locked condition even if another process has the record locked. This allows report programs to run without hindrance. Note, however, that on some older UNIX machines, non-locking READs will receive the record-locked condition if another process has the record locked. This is because on these machines, UNIX enforces the record locks. Most UNIX systems do not enforce record locks (the current system V standard does not allow for it) so this should not continue to be a problem for long. PC-based environments (i.e., LANs, Windows) also enforce record locks, introducing a portability issue. For unenforced locks in a PC-based environment, you should use indexed files rather than relative files.

runcbl behaves in one of two fashions when a locked record is encountered. Normally, the return is immediate and the file status variable is set to the locked condition. When this happens, the I/O fails. Unlike most errors, the current record pointer is not changed by a locked condition. This allows multiple READ NEXTs to be performed in a loop until the lock condition disappears, without losing track of the current record position.

In RM/COBOL compatibility mode, however, this rule changes if the file does not have a Declarative associated with it. In this case, locked records on REWRITE and DELETE statements are handled as described above. On READ statements, however, runcbl automatically waits until the record becomes unlocked. This is identical to the behavior of RM/COBOL version 2. The programmer should beware when using this technique, however. Deadlocks can occur if two programs end up waiting for each other to unlock a desired record. For this reason, we recommend against using this technique.

When ROLLBACK is enabled in a file's FILE-CONTROL entry, record and file locking rules are extended for that file. Every record updated as part of a transaction is locked until that transaction is committed or rolled back. The COMMIT and ROLLBACK verbs remove these locks. For more information see Extended Locking Rules.

Parent topic: Handling Files


Device Locking Under UNIX

On UNIX machines, handling devices poses a special problem. The difficulty is that UNIX does not in any way limit access to a device, so that it is possible for two programs to intermix reports on the same printer. This is usually not a problem with printers because the output is usually directed to the UNIX spooler. However, for special-form printing, or writing to other types of devices, it is necessary to write directly to the device.

On UNIX systems, runcbl can control concurrent access to a device by automatically performing file locking for all files identified as devices. You must enable this feature if you want to use it. When it is enabled, runcbl will create a lock file whenever a device file is opened. If the lock file exists when the open is made, then the open will fail and a file-locked condition will be returned to the program. When an open device file is closed, its lock file will be removed.

You identify a device to runcbl by using the -D flag in its name. The lock file will be called LOCK.name where name is the base file name of the UNIX device (for example, lp or mt0). See File Name Interpretation for more information.

You enable automatic device locking by specifying a lock directory. Set the configuration variable LOCK_DIR to the desired directory.

For example, if you wanted to enable device locking and place the lock files in the directory /usr/locks, you could use the following configuration variable:

LOCK-DIR  /usr/locks
Note: If a program that has established a device lock dies in a catastrophic fashion (for example, a power failure), the lock file will be left around and should be removed manually.

Also note that enabling device locking will not prevent the UNIX spooler from printing to the device. When you are using a printer as a special-form printer, the spooler should first be disabled (see the disable UNIX command) and then the program should be run that will print the special forms. It will prevent other special-form printing programs from using that printer. Programs that print through the spooler, meanwhile, will continue to run, because the UNIX spooler accepts queued reports when disabled. After the special forms are printed, the spooler can be enabled and the queued reports will start printing.

Parent topic: Handling Files


Indexed File Considerations

This section describes the impact of ACUCOBOL-GT's special indexed file features. It covers how they work and when they should (and should not) be used.

  • Compression
  • Mass Update
  • Bulk Addition Mode for Vision
Parent topic: Handling Files


Compression

File compression can be used on indexed files to save disk space. The Vision file system supports compression, but not all file systems do. Compression is enabled by specifying the WITH COMPRESSION phrase in the ASSIGN clause of a file's SELECT statement. Compression must be specified when the file is initially created to have any effect. However, the vutil-rebuild option allows you to apply or remove compression during the file rebuilding process. See Rebuilding Files for more information.

File compression uses a simple run-length compression scheme. This replaces runs of identical bytes with a shorter sequence. Files using compression may contain any type of data.

Some files will compress better than others. Generally speaking, files that contain text compress the best due to repeated space characters. Results can vary significantly, however. Experimentation is the best way to tell how much space may be saved.

Each compressed record usually retains some extra, unused space for future expansion. This is advisable especially if the records are frequently changed. You can specify via a compression factor how much of the space saved by compression should be retained to allow for future growth. When no compression factor is specified, WITH COMPRESSION uses the default compression factor (70). The following paragraphs explain how the factor is used.

A compression factor other than the default may be specified via the COMPRESSION CONTROL VALUE IS clause in the SELECT statement. The factor must be a numeric literal within the range zero (no compression) to 100 (maximum compression). A factor of one (1) causes Vision to examine the COMPRESS_FACTOR configuration variable. If COMPRESS_FACTOR is not set, the default compression factor is used (70).

For factors from two through 100, the factor is considered to be a percentage. It specifies how much of the space saved by compression is actually removed from the record. For example, suppose an 80-byte record is compressed to 30 bytes. Then the compression factor is used to determine how much of the 50 bytes of saved space is to be removed from the record. A compression factor of 70 would mean that 70% of the 50 bytes (35 bytes total) will be removed. This leaves 15 bytes for future expansion, and results in a compressed record size of 45 bytes (30 compressed size plus 15 extra for growth). The larger the compression factor, the more of the saved space is removed. A compression factor of 100 removes all saved space and is advisable only if the file is rarely updated.

An alternate way to specify the compression factor is to set the COMPRESS_FACTOR configuration variable. COMPRESS_FACTOR is used when the COMPRESSION CONTROL VALUE IS clause is either omitted or set to a value of one. See the entry for COMPRESS_FACTOR for more informaqtion. As noted earlier, the compression factor for a file is established when the file is created. Subsequent changes to COMPRESS_FACTOR do not affect existing files.

The selection of the compression factor should be based on the amount of updating that the file undergoes. If rewrites and deletes are rarely or never done on the file, then a high compression factor is most efficient. We recommend 100 for files that are rarely updated, 70 for average files, and 50 (or less) for files that are frequently updated.

Parent topic: Indexed File Considerations


Mass Update

The MASS-UPDATE option of the OPEN verb can provide significant performance benefits under some circumstances. Several issues come into play, however, when you are deciding whether or not to use MASS-UPDATE. Currently, the MASS-UPDATE clause affects only the systems that use Vision.

Normally, when Vision updates a file, it immediately writes all of the changed information to disk. This is done for two reasons: to allow current information to be accessed by other concurrent processes, and to ensure that the file will be accurate should the program die suddenly without closing the file (e.g., when a machine's power goes out or the operating system crashes). Note that a Vision file is really only at risk of being damaged during an update to the file.

The MASS-UPDATE option changes this strategy. It allows Vision to retain information in memory until the file is closed. This allows Vision to be much more efficient, particularly on Windows systems. However, using this option means that the file is at risk from the time the first update is made until the time the file is closed. Should the machine die during this period, the file will almost certainly be corrupt. To mitigate this issue, Vision writes enough information to disk to ensure that the file can be rebuilt using vutil.

The MASS-UPDATE option also requires that the entire physical file be locked against other updaters because the disk version of the file is not always accurate. This somewhat limits the opportunities in which MASS-UPDATE can be used.

Generally, programs might use MASS-UPDATE if they heavily update a file. For many such programs, the fact that the file is at greater risk is not really an issue. For example, many posting programs cannot recover from an incomplete run. This is because the program cannot tell where it left off in the process. This is particularly true for programs that update several files at once, because it is usually not clear which file got updated last. For these programs, it is usually necessary to go to a backup of the affected files when the program dies. These programs are obvious candidates for MASS-UPDATE because it does not matter if the files are corrupt after a program failure, since they are just going to be restored from backup. Furthermore, these programs benefit the most from MASS-UPDATE because they do a lot of updating.

Interactive programs, however, make poor candidates for MASS-UPDATE. Usually the volume of updates is low (at least for the time frame the program runs in). Furthermore, interactive programs are often killed or left running overnight by their operators, thus increasing both the risk to the file and the inconvenience of the file lock that MASS-UPDATE implies.

To summarize, MASS-UPDATE is appropriate for programs where the implied file lock is useful, the volume of updates is large, and where a system failure would usually require special attention for recovery (either restoring from backup or rebuilding the files).

Note: For convenience when you are converting programs written with other COBOL compilers, ACUCOBOL-GT can treat files opened WITH LOCK as if they were opened with MASS-UPDATE . This is controlled by the MASS_UPDATE runtime configuration variable. Configuration variables are described in Appendix H.
Parent topic: Indexed File Considerations


Bulk Addition Mode for Vision

This section includes the following:

When Vision writes a record to a file, its normal algorithm is to first add the record, then add the primary key, then add the first alternate key and so on until all the keys have been added. This is the algorithm one expects and is generally required to correctly support the WRITE verb.

Vision also has another technique that it can use to add records to a file. This technique does not write the keys to the file when it adds the record. Instead, it adds many records to the file first, then it gathers all the primary keys for those records and adds them, then it gathers all the first alternate keys and adds them and so on. By adding many keys at once, Vision can be much more efficient in its handling. This has two benefits:

  1. The time it takes to add a large number of records using this technique is generally much smaller than using the normal technique; and
  2. The resulting file is more efficiently organized, with all of the blocks associated with a particular key near each other on disk.

This technique of adding records to a file is called bulk addition mode. It is available only for Vision files. It may be used with any format Vision file.

You can use bulk addition mode in your programs. This is most useful in programs that add a large number of records to a file at once. It is less useful in programs that do operations other than WRITE on a file, or programs that do not write many records. Some typical applications for bulk addition mode are:

  • Programs that load externally supplied data into a file. For example, a program that adds to an indexed file from the data contained in a sequential file.
  • File conversion programs, such as programs that change a record format. These programs read from one file and write to a new one.
  • Archiving programs.
  • Programs that post transactions to permanent log files.

While bulk addition mode has fairly specialized uses, its benefits are high in these cases.

Bulk addition mode can provide substantial performance improvements over other techniques, including MASS-UPDATE mode. These improvements become more noticeable as the file grows and in files with a large number of alternate keys. For files with few records, bulk addition mode can be slightly less efficient than the normal WRITE technique.

Using bulk addition affects some of the standard COBOL file handling rules. These are described separately.

  • Using Bulk Addition
  • Effect on COBOL Rules
  • Duplicate Key Handling
  • Progress Reporting
  • Bulk Addition and AcuServer
  • Using Bulk Addition with Transactions
  • Performance Tips
  • Summary
Parent topic: Indexed File Considerations


Using Bulk Addition

To use bulk addition on a file, open that file with the BULK-ADDITION phrase. For example:

OPEN OUTPUT MY-FILE FOR BULK-ADDITION

A file opened for bulk addition is locked for exclusive use by the program. This is necessary because the file becomes internally inconsistent when the first WRITE occurs and does not become consistent again until the file is closed.

You may use BULK-ADDITION with the OUTPUT, EXTEND and I-O open modes.

If you specify BULK-ADDITION for a file other than a Vision file, the effect is the same as if you had specified MASS-UPDATE instead.

Vision allocates a memory buffer for each file opened for bulk addition. The size of this buffer is controlled by the V_BULK_MEMORY configuration variable. The default size of this buffer is 1 MB. The default size is fairly large because it is assumed that only a few files will be open for bulk addition on a system at any one time. If this buffer cannot be allocated, the OPEN fails with a status indicating inadequate memory.

When a WRITE occurs for a file opened for bulk addition, only the record is actually written to the file. The keys for the record are not written out until later. When an operation occurs on the file other than a WRITE, that operation is suspended and all of the records with missing keys have their keys added. After this completes, the suspended file operation resumes.

The process of adding keys uses the memory buffer allocated when the file was opened. The algorithm is to fill the buffer with keys, sort them, and then add them to the file. This is repeated until all the missing keys have been added. The larger the memory buffer, the more efficient this process is.

When adding records to the file, Vision always places the records at the end of the file when using bulk addition. It does not re-used deleted record areas in this case. It does this to make the process of gathering the missing keys efficient. If you need to recover the deleted record disk space, you can rebuild the file with vutil to do this.

Note: Any operation on the file other than WRITE will trigger the addition of the keys. Ideally, this operation will be the final CLOSE of the file. In this case, all of the newly added records are keyed at once and efficiency is maximized. In the worst case, each WRITE is followed by some other operation (such as a READ). In this case, each record is keyed individually. This is less efficient than just updating the file normally.

This process of delaying the keying of the records has several effects besides improving performance. It affects the rules of COBOL, especially the handling of duplicate keys. In addition, it makes it harder to report the program's progress to the user, since much of the program's time may be spent in a single COBOL statement (the file's CLOSE, for example, may take the majority of the program's running time as it adds all the missing keys).

Parent topic: Bulk Addition Mode for Vision


Effect on COBOL Rules

When you open a file for bulk addition, the regular rules of COBOL file handling are changed for that file, until that file is closed. The following changes apply:

  1. File status 02 (record written contains an allowed duplicate key value) is never returned by WRITE.
  2. File status 22 (record not written because it contained a disallowed duplicate key value) is not returned by WRITE. See the next section for a discussion of how illegal duplicate keys are handled.
  3. File status 24 (disk full) may occur on file verbs that normally cannot produce this status. This occurs because the verb (for example, READ) triggered writing of the keys to the file and the disk became full while doing this.
  4. Records may be rejected as having illegal duplicate keys that would not normally be rejected. The circumstance under which this occurs is described in the next section.
Parent topic: Bulk Addition Mode for Vision


Duplicate Key Handling

Because keys are not written at the time a new record is written, the WRITE statement never gets a duplicate key error status (status 22). When you are using bulk addition, illegal duplicate keys are handled in a different manner.

When the keys are added to the file, any illegal duplicates are detected then. Should a record be found that contains an illegal duplicate key value, that record is deleted. Your program is informed of this only if it contains a valid declarative for the file. If there is no declarative available, the record is quietly deleted. Otherwise, the file status data item is set to 22, the file's record area is filled with the contents of the rejected record, and the declarative executes. When the declarative finishes, the file record area is restored to its previous contents so that it contains the correct data when the suspended file operation resumes.

When the file's declarative executes in this way, the program may not perform any file operations in the declarative. This is because the program is in the middle of doing a file operation already, the one that triggered the addition of the keys. In addition, the declarative may not start or stop any run units (including chaining), nor may it do an EXIT PROGRAM from the program that contains the declarative. Finally, note that the declarative runs as a locked thread - no other threads execute while the declarative runs.

You can configure Vision to write any rejected records to a file. This gives you a way to log the rejected records even though you may not perform a file operation from within your declarative. To create this log, set the DUPLICATES_LOG configuration variable to the name of the file in which you want to store the records. Vision will erase this file first if it already exists. You must use a separate log file for each file opened with bulk addition. You can do this by changing the setting of DUPLICATES_LOG between OPEN statements. For example:

SET ENVIRONMENT "DUPLICATES-LOG" TO "file1.rej"
    OPEN OUTPUT FILE-1 FOR BULK-ADDITION

SET ENVIRONMENT "DUPLICATES-LOG" TO "file2.rej"
    OPEN EXTEND FILE-2 FOR BULK-ADDITION

If DUPLICATES_LOG has not been set or is set to spaces, then no log file is created.

In addition, the duplicate-key log file may not be placed on a remote machine using AcuServer. The log file must be directly accessible by the machine that is running the program.

Any record that Vision rejects due to an illegal duplicate key value is written to the log file. The format of the file is a binary sequential file with variable-size records. You can read this file with a COBOL file that has the following layout:

FILE-CONTROL.
     SELECT OPTIONAL LOG-FILE
     ASSIGN TO DISK file-name
     BINARY SEQUENTIAL.

FILE SECTION.
FD    LOG-FILE
      RECORD IS VARYING IN SIZE DEPENDING ON REC-SIZE.
01    LOG-RECORD.
      <<indexed record layout goes here>>

WORKING-STORAGE SECTION.
77    REC-SIZE                PIC 9(5).

If no duplicate records are found, the log file is removed when the Vision file is closed.

There is an unusual circumstance that can cause a file opened for bulk addition to reject a record that would not have been rejected if the file had been opened normally. This occurs only when the file has at least one alternate key that does not allow duplicates. This happens due to the changed order in which the keys are written to the file.

Consider a case where a file has two numeric keys, the primary key and one alternate that does not allow duplicates. Now suppose the following three records were written to this newly created file:

Primary key | Alternate key
1 | 1
2 | 1
2 | 2

In a file opened normally, the first record would be written to the file, the second record would be rejected because of an illegal duplicate on the alternate key, then the last record would be written. The result would be a two-record file, the records (1,1) and (2,2).

If the file is opened for bulk addition, the three records are added, then the primary keys are added, then the alternate keys are added. First the three records are added. Then the first and second record's primary keys are added. The third record's primary key is rejected because it duplicates the second record's key. The third record is removed as a result of this. Then the alternate keys are processed. The first record's key adds fine. The second record's key is rejected because it is a duplicate, and the second record is removed. The third record's alternate key is not processed because that record has already been removed. The result is a one record file, the record (1,1).

To summarize, as a result of bulk addition, you may end up with records rejected because of the duplicate key conflict with other (eventually) rejected records and not necessarily with any accepted records.

This difference would not occur if the keys were added row-wise instead of column-wise, but doing so would sacrifice much of the efficiency gained by bulk addition mode.

In most practical applications, this scenario is not very likely. If need be, you can adjust for this difference by logging the rejected records and then trying to add them to the file normally after leaving bulk-addition mode. The second attempt at writing out the records will still reject the records with illegal duplicates, but take any records that conflict only with other rejected records.

Because of the various issues surrounding illegal duplicate key values, it is best to use bulk addition in cases where illegal duplicates are rare. Processing records with a great many illegal keys significantly reduces the performance benefits of using bulk addition.

Parent topic: Bulk Addition Mode for Vision


Progress Reporting

Programs that use bulk addition are frequently the types of programs where it is desirable to report the program's progress to the user. For example, a program that reformats a file would typically display its percentage complete while running. However, a single COBOL statement may represent the majority of the running time, so progress reporting is difficult to do. The file reformatting program, for example, could spend 20% of its time writing out the reformatted records and 80% of its time in the CLOSE statement while the records are having their keys written.

You can use a special declarative section to do progress reporting. This section is called directly by Vision in a periodic fashion while the keys are being added to the file. To create the declarative, use the following form of the USE statement:

USE FOR REPORTING ON file-name.

Vision executes this section at regular intervals. This reporting period is approximately once for each percentage point completed per key.

Because the declarative is called from within a file operation, the declarative section's code may not execute any file operations. In addition, the declarative may not start or stop any run units (including chaining), nor may it do an EXIT PROGRAM from the program that contains the declarative. Finally, note that the declarative runs as a locked thread - no other threads execute while the declarative runs.

To determine how far along Vision is in adding the keys, you can call the library routine C$KEYPROGRESS . You pass this routine a single parameter which has the following layout:

01  KEYPROGRESS-DATA, SYNC.
    03  KEYPROG-CUR-KEY   PIC XX COMP-N.
    03  KEYPROG-NUM-KEYS  PIC XX COMP-N.
    03  KEYPROG-CUR-REC   PIC X(4) COMP-N.
    03  KEYPROG-NUM-RECS  PIC X(4) COMP-N.

A copy of this group item can be found in the COPY library keyprog.def.

When C$KEYPROGRESS returns, the group item is filled with current data. The individual items contain the following:

  • KEYPROG-CUR-KEY - this is the current key being worked on by Vision. The primary key is key 1, the first alternate is key 2, and so on.
  • KEYPROG-NUM-KEYS - this is the total number of keys in the file.
  • KEYPROG-CUR-REC - this is the number of the last record written for the current key, ranging from 1 to the total number of records to write.
  • KEYPROG-NUM-RECS - this is the total number of records to be keyed.

You may report this information in any fashion. If you want to report the actual percentage complete, the formula is the following:

total-operations = keyprog-num-recs * keyprog-num-keys

operations-complete =
  (keyprog-cur-key - 1) * keyprog-num-recs + keyprog-cur-rec

pct-complete =
  (operations-complete / total-operations) * 100

That formula computes the percentage complete for just adding the keys. If you want to treat the original record writes and the adding of the keys in a single percentage scale, the formula is slightly different:

total-operations = keyprog-num-recs * (keyprog-num-keys + 1)

operations-complete =
  keyprog-cur-key * keyprog-num-recs + keyprog-cur-rec

pct-complete =
  (operations-complete / total-operations) * 100

Here is an example of a typical reporting declarative:

77  PROGRESS-BAR-1      HANDLE OF FRAME.

DECLARATIVES.
MYFILE-REPORTING SECTION.
   USE FOR REPORTING ON MYFILE.
MYFILE-REPORT.
   CALL "C$KEYPROGRESS" USING KEYPROGRESS-DATA
   MODIFY PROGRESS-BAR-1, FILL-PERCENT =
          ((((KEYPROG-CUR-KEY - 1) * KEYPROG-NUM-RECS
          + KEYPROG-CUR-REC) / (KEYPROG-NUM-RECS
          * KEYPROG-NUM-KEYS)) * 100).
END DECLARATIVES.
Note: As mentioned above, the progress reporting code in the Declaratives Section tracks only the bulk addition of keys to the file. To also indicate the time spent writing records, similar code should be added to the corresponding WRITE statements in the Procedure Division.
Parent topic: Bulk Addition Mode for Vision


Bulk Addition and AcuServer

You may not use bulk addition mode with files that you are accessing via AcuServer. If you attempt to do so, AcuServer will open the file in MASS-UPDATE mode instead.

Programs that are appropriate targets for bulk addition mode are generally much more efficient when run directly on the server. You can arrange to do this directly by manually starting the job on the server, or you can use AcuConnect from a workstation to remotely start the job on the server.

In addition, the duplicate-key log file may not be placed on a remote machine using AcuServer. The log file must be directly accessible by the machine that is running the program.

Parent topic: Bulk Addition Mode for Vision


Using Bulk Addition with Transactions

You may use bulk addition for files that use transaction management. No transaction management rules are affected by bulk addition.

The START TRANSACTION, COMMIT and ROLLBACK verbs are not treated as operations that trigger the bulk addition of keys. However, a ROLLBACK can cause the bulk addition of keys if it has to delete or rewrite a record as part of its operation. Note that a file's declaratives will not execute as part of a ROLLBACK process. This applies to both the error handling declarative and the progress reporting declarative.

Parent topic: Bulk Addition Mode for Vision


Performance Tips

Using bulk addition can provide very substantial performance gains in appropriate cases. Generally, it is best used when you are adding a large number of records to a file and has a more noticeable effect on files with a large number of records.

The following chart shows one set of execution times for creating a new file with eight 10-byte keys generated in random order and a 130-byte record size. These were run on a Windows 98 machine.

Note that the times will vary widely from machine to machine and between different file organizations; use these number just as a comparison between techniques:

Notice how the run times for MASS-UPDATE mode rise at a much steeper rate than those for bulk addition mode as the number of records grows.

You get best performance from bulk addition when you maximize the number of records being keyed at once. This means that you want to WRITE as many records as possible to the file without performing any other intervening operations on the file.

There are two configuration variables that have an important effect on the bulk addition performance. The first of these is V_BUFFERS , which determines the number of 512-byte blocks in the Vision cache. Besides having its usual caching effect, the Vision cache is especially important when you are doing bulk addition because the cache is used to gather file blocks together into larger groups that are written out in a single call to the operating system. While the cache always does this, the bulk addition algorithm tends to produce very large sets of adjacent modified blocks, which can all be written out at once. By increasing the cache size, you can increase the number of blocks written out at once.

For this reason, you should use a cache size of at least 64 blocks. Note that this is the default cache size for most systems. If memory is plentiful, then a cache size of 128 or 256 blocks is recommended. You can go higher if you want; however, there is usually little benefit seen after about 512 blocks (256K of memory).

The other important factor is the memory buffer used to hold the keys ( V_BULK_MEMORY ). Unlike V_BUFFERS, this is most useful when it is large. The default size is 1 MB. Larger settings will improve performance when you are adding many records to a file. Essentially, this buffer is used to hold record keys. The more keys that it can hold, the better the overall performance. For runs that will write out between 250,000 and 500,000 records, a setting of 4 MB generally works well. For more than 500,000 records, we recommend at least an 8 MB setting. Be careful that you do not set this too large, however. If you set it so large that the operating system must do significantly more memory paging to disk, you could lose more performance than you gain. You will need to experiment to see which setting works best for your system.

Finally, the process of removing records due to illegal duplicate keys is expensive. You should try to arrange it so that bulk addition is used in cases where illegal duplicate keys are rare.

Parent topic: Bulk Addition Mode for Vision


Summary

Using bulk addition can provide very significant performance gains in certain cases. These cases involve writing a very large number of records to a file. In order to optimize performance, certain rules of COBOL are changed and some other restrictions apply. Here are the key points to remember:

  1. Files open for bulk addition are locked for exclusive use.
  2. WRITE does not add keys to the file. The keys are added when some other file operation occurs.
  3. Duplicate record errors (status 22) are not returned by WRITE. Instead, they are reported to the file's declarative procedure only during some other file operation.
  4. The declarative must not perform any file operations or start or stop any run units when processing status 22.
  5. You may log records rejected due to illegal duplicated keys by setting the option DUPLICATES_LOG to the name of the desired log file.
  6. Disk space occupied by deleted records is not re-used when you are adding records with bulk addition.
  7. You can report on the progress of adding the keys in a USE FOR REPORTING declarative. This declarative may not perform any file operations or start or stop any run units.
  8. You may not use bulk addition on files you are accessing via AcuServer. Use AcuConnect or some other technique to start the job directly on the machine with the files.

Avoid doing an abnormal shutdown on a job running with bulk addition. If the job aborts without completing its "close" operation, the file will almost certainly have keys missing and need to be rebuilt.

Parent topic: Bulk Addition Mode for Vision


Performance Considerations

File performance varies considerably from machine to machine and from program to program. This topic discusses general measures that can be taken to improve file handling performance for most situations.

Generally speaking, sequential files are fastest and indexed files are slowest. Relative files are usually in between in performance, but are generally close to sequential files in speed.

When designing indexed files, you should try to keep the size and number of keys to a minimum. Each key added to a file significantly increases the processing time required. The key size is important because it affects how many keys can be stored in one disk block. If you are faced with a decision that trades off making a new key or making an old key larger, it usually is better to make the old key larger.

One important and often overlooked aspect of file performance is file locking. Generally speaking, the more restrictive the access to a file, the more efficiently that file can be processed. On some machines, the difference can be quite dramatic. For example, under RMS, writes to a sequential file are usually at least five times faster if that file is locked for exclusive use. If this is a report file, there is no reason not to lock the file, and the report program will run much faster if you do so.

As a general rule of thumb, you should lock files as restrictively as you can, given the needs of your application. Note that if you have a file that is read by many programs, but rarely or never written to, you can open the file for INPUT ALLOWING READERS. This allows many users to access the file, but also tells the runtime system that it is not being updated by anyone. The runtime system can use this knowledge to buffer the file more effectively. One common form of file where this technique can be used is a file that contains menu options or screen layouts.

On the other hand, you should lock records only when you need to. While locking a record is generally fairly fast, the time to do so increases proportionally to the number of locks you are holding. Also, on networked file systems, locking records can be fairly slow because the networked machines must all be informed of the lock. Note that this is another reason to lock files when possible: when the file is locked, the runtime does not need to establish locks on individual records.

If you have enough memory, you can also increase your indexed file performance by increasing the V-BUFFERS configuration option described in Appendix H. This will increase the number of disk buffers used by the runtime system to hold key information.

Finally, you should read the information on the MASS-UPDATE option described in Mass Update, as well as the Bulk Addition option described in Bulk Addition Mode for Vision. Using these options can significantly improve performance on some machines.

Parent topic: Handling Files


Limits on Open Files

Because Vision Versions 4, 5, or 6 generate files in a dual file format, a COBOL application registers at least two open files for each Vision file. (Version 3 use a single file format.) For large files with data extensions, the number of open files per Vision file (versions 4 and 5) can be greater than two. Various techniques exist for controlling the number of files that can be open at one time.

  1. The COBOL configuration variable MAX_FILES sets the maximum number of files that can be opened by the runtime system. The default value is 32. You can set this to any value up to 32767. Keeping this value small conserves memory.
  2. Many operating systems limit the number of files that can be opened by a single process, so you may need to make some adjustments. On UNIX systems, file limits are controlled by kernel parameters. On VMS, file limits are controlled by process parameters.
  3. If you are using an external file system or database instead of (or in conjunction with) Vision, limits may be imposed by the external file system or by the interface. See the ACUCOBOL-GT document for the specific interface that you are using.
Parent topic: Handling Files


Terminal IO

ACUCOBOL-GT uses a sophisticated Terminal Manager that can provide many screen functions and improve terminal performance. To get the most out of the Terminal Manager, it helps to understand how it works. See Terminal Manager for more information.

  • Performance Considerations
  • Terminal Manager Restrictions
Parent topic: Programmer's Guide


Performance Considerations

ACUCOBOL-GT comes with a built-in window-oriented Terminal Manager. Efficient use of windows partially depends on the hardware characteristics of the host machine and terminal. Machines with memory-mapped screens (such as most personal computers) will run efficiently in any case. Machines with attached terminals, however, can significantly benefit from careful use of the windows.

As an example of an unwise choice of a window, consider trying to scroll a window that is almost the size of the screen. Without any hardware support, the Terminal Manager might have to move 1000 characters or so. On a memory-mapped machine, this will happen quickly, but on a machine with a terminal that is running at 9600 baud, this will take about one second. If several lines are being scrolled onto the screen, the entire operation will take several seconds to complete. This might be acceptable on occasion, but is very tedious if used regularly.

The Terminal Manager attempts to minimize screen I/O by keeping track of every character on the screen. Characters that do not need to be displayed (because they are already on the screen) are not sent to the terminal. Because much of a screen is often empty, substantial savings are achieved when you are clearing a window. Other general optimizations are done which result in generally faster screen I/O.

Special hardware characteristics of most terminals are used for time-consuming operations. The following guidelines will help you use windows efficiently on most machines by taking advantage of these characteristics.

  • Large windows that will be cleared regularly should extend to the right edge of the screen. This allows the use of the terminal's clear to end-of-line function.
  • Large windows that will be scrolled regularly should be the width of the screen and extend to the bottom edge. This case will use the insert-line and delete-line functions of most terminals.
  • Reverse-video windows should be kept small. Creating a large reverse-video window is time-consuming because each location of the window must be initially written to. If you want a large window to stand out, consider making it boxed instead.
Parent topic: Terminal IO


Terminal Manager Restrictions

Because of the windowing capabilities of the Terminal Manager, the programmer must abide by certain restrictions. This topic describes these restrictions and how to work with them.

The primary restriction is that the Terminal Manager must retain control of the terminal. It needs to do this in order to implement the windowing functions. Also, by doing this, it can significantly improve screen performance over a dumb screen interface.

The main effect of this restriction is that you may not send arbitrary escape sequences to the terminal. Sending "escape" sequences that command the terminal in a hardware-specific fashion will confuse the Terminal Manager because it will not know what effect the "escape" sequence had on the screen. This will result in the Terminal Manager's making incorrect assumptions about the screen and, eventually, will cause it to display incorrect data.

This restriction is not too serious, however, because the Terminal Manager can perform most functions that are normally accomplished through these escape sequences. Using the Terminal Manager to perform these functions has the added benefit of making them terminal-independent. This allows you to run the same application on any kind of terminal without having to keep a database of terminal capabilities maintained by the program.

The following points outline the Terminal Manager's solution to various functions that are usually implemented via "escape" sequences.

Line Drawing | Many programs draw special-forms on the user's screen using the terminal's line drawing characters. This works fine if the line drawing characters are part of the terminal's default character set (such as on a PC), but does not work if you need to send an "escape" sequence to switch character sets. With ACUCOBOL-GT, you can use DISPLAY BAR, DISPLAY LINE, and DISPLAY BOX to perform line drawing. These verbs have the advantage that you can simply draw the form using screen coordinates without having to worry about different character sets on different terminals or using special characters to handle the intersections.
132-Column Handling | Some programs send escape sequences to switch between 80-column and 132-column mode on the terminal. This can be accomplished with the DISPLAY SCREEN verb in ACUCOBOL-GT.
Attached Devices | ACUCOBOL-GT can send data to a device attached to the terminal. For example, a printer or a cash register might be attached. The built-in library routine C$LOCALPRINT can send data to the attached device with a variety of line spacing options. This routine is described in Appendix I. Library Routines.
Scrolling | ACUCOBOL-GT directly supports scrolling with the SCROLL option of the DISPLAY verb.
Function Key Labels | you can program function key labels by providing the appropriate command string in the is entry in a_termcap. See Initialization for more information. Currently, ACUCOBOL-GT does not provide a way to program function key labels at run time.
Parent topic: Terminal IO


Memory Management

This help section discusses how ACUCOBOL-GT manages runtime memory, the tools available to you to help manage program memory, and the facilities available to help find and correct memory management problems.

When runcbl initiates, it loads the main program into memory and begins execution. As other programs are called they are also loaded into memory. Once loaded, a program remains in memory until it is canceled (typically with the CANCEL statement). Canceling a program:

  • places the program in its initial state
  • closes its open files
  • ensures that any VALUE clauses are in effect when the program is called again
  • removes the program from memory, by default

This handling allows for a full ANSI implementation of subprograms (variables retain their previous values when a subprogram is re-entered, files can be left open in a subprogram, and so forth).

If subprograms are never canceled, a large system can eventually occupy very substantial amounts of memory. This is a common problem with large menu driven applications where the master menu calls programs for the various menu selections.

There are several mechanisms for managing runtime memory, including the CANCEL verb and the INITIAL and RESIDENT clauses of the PROGRAM-ID paragraph. To provide more flexibility, you can also enable a caching system in which canceled programs are not removed from memory until a specified memory limit is reached (see CANCEL below).

  • CANCEL
  • CANCEL ALL
  • INITIAL Clause
  • RESIDENT Clause
  • Other Memory Management Tools
  • External Data Items
Parent topic: Programmer's Guide


CANCEL

The CANCEL statement places the specified program in its initial state (see above). By default, the program is removed from memory. Subsequent calls to the program cause it to be reloaded from disk. This type of cancel, in which the program is removed from memory, is called a physical cancel. Alternatively, as an aid to tuning system performance, you can set up a system in which canceled programs are placed in their initial state but are left in memory until a specified memory limit is reached. Such cancels are called logical cancels. Subsequent calls to these programs start very quickly because the programs are already in memory. When the memory limit is reached, all logically canceled programs are removed from memory. Two runtime configuration variables are used to set up this system. See DYNAMIC_MEMORY_LIMIT and LOGICAL_CANCELS for more information.

When using logical cancels, replacing an object file on disk does not necessarily mean that subsequent calls to the program will use the new object. To force a subsequent call to load the new object file from disk, you must configure ACUCOBOL-GT to perform a physical cancel on that program.

Also, the use of logical cancels has some implications on debugging. The ACUCOBOL-GT debugger periodically reads source code from the object file on disk. When program code is cached by a logical cancel, the object file is closed and could be replaced or deleted. For the debugger to function correctly, it needs to keep the object file open and ensure that the object code in the disk file is identical to the code in memory. If the program is cached, the debugger accomplishes this by unloading the program from the cache, reopening the object file, and reloading the object code into memory. Because this effectively turns off logical cancels and the code caching feature when the debugger is active, the runtime configuration variable DEBUG_NEWCOPY can be used to control the runtime's behavior.

Parent topic: Memory Management


CANCEL ALL

Because it can be inconvenient to individually CANCEL every subprogram, ACUCOBOL-GT includes an extension to the CANCEL verb: CANCEL ALL. When executed, CANCEL ALL cancels every subprogram that is not active. (A program is active if it is either the main program or it has been called, but not yet exited.) Executing a CANCEL ALL after a menu selection completes is an easy way to free the memory used by that program.

Parent topic: Memory Management


INITIAL Clause

The INITIAL clause in the PROGRAM-ID paragraph causes a subprogram to be automatically canceled whenever it exits. The program is removed from memory, regardless of whether the logical cancel feature is enabled. This can be used to help manage memory or to ensure that VALUE clauses are set whenever a subprogram is called. Note that the compiler will automatically apply this clause to a program compiled with the -Zi option. This can be particularly useful when you are converting programs from RM/COBOL version 2.

In RM/COBOL, the status of a program that exits is not precisely defined. Subprograms remain in memory until either their caller exits or until inadequate memory remains to load another subprogram. This occurs at fairly unpredictable times. Because their fate in memory is unclear, most RM/COBOL subprograms are treated as if they have been canceled when they exit. By applying the -Zi option at compile time, the ACUCOBOL-GT programmer can simulate this behavior. Note, however, that utility subprograms that are called repeatedly should not be compiled with -Zi, because this introduces extra overhead each time they are called. Also, any subprogram that depends on retaining variables between calls should not be compiled with -Zi.

Note: RM/COBOL treats spooled print files specially in that they are not closed when a subprogram exits (all other files are closed). ACUCOBOL-GT does not treat spooled files specially, so if this feature of RM/COBOL is used, the subprogram that does this should not be compiled with -Zi.

Parent topic: Memory Management


RESIDENT Clause

The RESIDENT clause in the PROGRAM-ID paragraph causes the program to remain resident in memory after its first execution. A program with the RESIDENT clause is not affected by a CANCEL or CANCEL ALL statement. Should the condition occur where there isn't enough system memory available to load a program, the CALL will fail with a Inadequate memory available error.

Parent topic: Memory Management


Other Memory Management Tools

The CHAIN Statement can be used to replace the running program with another program. This can conserve substantial amounts of memory. Segmentation (overlays) can be used to reduce the size of a single program. This is described in Procedure Division Format. Finally, you can adjust the size of ACUCOBOL-GT's runtime buffers with the V_BUFFERS and SORT_MEMORY configuration options.

Parent topic: Memory Management


External Data Items

ACUCOBOL-GT manages external data items by allocating them in pools. The minimum size of each pool is set by the EXTERNAL_SIZE configuration option.

When a new external data item is needed, it is allocated from an existing pool. If it does not fit in any of the allocated pools, a new pool is allocated. The size of this pool is the same as the size of the data item, but never smaller than the value specified by the EXTERNAL_SIZE option. This reduces memory fragmentation. There are 32 pools available altogether.

Because external data items remain allocated after programs are canceled, it is best to allocate the external data items together so they do not break up the memory space. The default value for EXTERNAL_SIZE is 8192.

Parent topic: Memory Management


Memory Testing and Error Handling

This help section discusses techniques for recovering from common runtime errors. It also describes several mechanisms for tracking, testing, and debugging memory in the runtime, including linked C programs.

(Compiler error messages are listed alphabetically in Appendix D, List of Errors.)

  • Memory Access Violations
  • Logging Errors to the Runtime's Error File
  • Run-Time Memory Tracking and Testing
Parent topic: Programmer's Guide


Memory Access Violations

If your program tries to access a portion of memory that is protected by the operating system, ACUCOBOL-GT generates a memory access violation message and shuts down.

The most common cause of this violation is indexing beyond the legal range of a table. Often this sort of error is difficult to detect, because it can be data-dependent, as shown in this example:

PERFORM UNTIL IDX > NO-OF-EMPLOYEES
   DISPLAY "EMPLOYEE NAME:   ", EMP-TABLE(IDX)
   ADD 1 TO IDX
END PERFORM.

If NO-OF-EMPLOYEES ever exceeds the size of EMP-TABLE, or if IDX is ever set to zero, you could get a memory access violation when the program is run.

To uncover this type of memory access violation, use the -Za compile-time option while you are debugging your program. When you run a program that has been compiled with -Za, ACUCOBOL-GT prints a subscript out of bounds error message, detailing the legal range of indexes for any table-indexing error that it encounters. (Note that the subscript out of bounds error appears when you run the program, not when you compile it.) You can then correct the program as necessary.

A memory access violation can also occur if there is a bug in any C routine linked into the runtime. Because of the nature of C, the violation can occur long after the called C function executes.

Parent topic: Memory Testing and Error Handling


Logging Errors to the Runtime's Error File

The code fragment below shows how to log permanent file errors into the runtime's error file. Normally, you would also use the +e runtime flag to name the error file and cause new messages to be appended to the end of the file.

Example

ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    SYSERR IS ERROR-LOG.

PROCEDURE DIVISION.
DECLARATIVES.
CUSTOMER-ERROR-PROCEDURE.
    USE AFTER STANDARD ERROR PROCEDURE ON CUSTOMER-FILE.
CUSTOMER-ERROR.
    IF CUSTOMER-FILE-STATUS = "30" OR "98"
        CALL "C$RERR" USING EXTENDED-STATUS
        DISPLAY "CUSTOMER FILE ERROR", EXTENDED-STATUS
           UPON ERROR-LOG.
Parent topic: Memory Testing and Error Handling


Run-Time Memory Tracking and Testing

There are several mechanisms available for tracking, testing, and debugging memory in Acucorp products and linked C programs. See Tracking Monitoring and Debugging Memory for more information about using these facilities from a C program.

All Acucorp products can monitor, test, and debug memory allocations. They can:

  • Track memory boundaries, so that if the boundaries are corrupted a report is generated. This facility is called memory bounds checking.
  • Track how much memory is allocated in each of six subsystems. This facility is called memory tracking.
  • Output a description of each memory allocation, reallocation, and free by file and line, including a text message. This facility is called memory handling descriptions.
  • Memory Handling Descriptions
  • Memory Tracking
  • Memory Bounds Checking
Parent topic: Memory Testing and Error Handling


Memory Handling Descriptions

Memory handling descriptions report detailed information about memory allocation, reallocation, and frees. To turn on memory handling descriptions in the ACUCOBOL-GT runtime, simply specify the -m valuefile command-line option. When -m valuefile is specified, description and tracking information is written to the file named by the file argument. Exactly what information is included in the report is determined by the value argument as follows:

If value is odd, a final memory dump, showing all blocks still allocated, is performed.

If (value / 2) is odd, each allocation, reallocation, and free is written to the file.

If (value / 4) is odd, a full memory dump is written for each allocation, reallocation, and free.

For example, if value equals 3, each allocation, reallocation, and free is reported and a final memory dump is performed when the runtime shuts down. This is because value is odd and value / 2 is also odd.

You can also enable memory handling descriptions for any extend product by setting two environment variables prior to product startup: A_MEM_DESC and A_MEM_DESC_FILE.

A_MEM_DESC must be set to value.

A_MEM_DESC_FILE specifies the name of the output file.

Both environment variables must be set to enable memory handling descriptions. Note that these are environment variables, not configuration variables. Also note that when memory descriptions are enabled with environment variables, the output does not (and for technical reasons cannot) include a final memory dump.

Parent topic: Run-Time Memory Tracking and Testing


Memory Tracking

The memory tracking feature is similar to the debugger "U" command, which displays the amount of dynamically allocated memory currently used by the runtime system. You can turn on memory tracking by setting the environment variables TRACE or A_DEBUG to positive numeric values. Apart from writing some C code (see 6.7.4 in A Guide to Interoperating with ACUCOBOL-GT), or running in the debugger (which turns this feature on automatically), there is no way to get the values stored for memory tracking.

Parent topic: Run-Time Memory Tracking and Testing


Memory Bounds Checking

Memory bounds checking in COBOL programs is easily performed by compiling with the -Za option. See Memory Access Violations and the entry for -Za in Miscellaneous Options for more information.

A second method can be helpful when the problem may be in a linked C routine.

There is a simple method of testing allocated memory bounds errors in any Acucorp product. On Windows systems, the method is turned on and off with a registry entry. On other systems, the method is turned on and off with an environment variable. When an array bounds error is detected, a message is written to the file dbgmalloc.log in the current working directory.

To enable memory bounds checking on Windows, you must create a registry value Test Allocated Memory Bounds in the HKEY_CURRENT_USER\Software\MicroFocus hive, with a type of DWORD and a value of non-zero. To turn memory bounds checking off, you must set the value to zero.

To enable memory bounds checking on UNIX, Linux, and other non-Windows platforms, you must set an environment variable named TEST_ALLOCATED_MEMORY_BOUNDS to a non-zero value. To turn memory bounds checking off, removed the environment variable or set its value to zero.

When memory bounds checking is enabled, messages are printed whenever the memory checking routines detect that allocated memory bounds have been overwritten.

Note: Application performance can be adversely impacted by memory bounds checking.
Parent topic: Run-Time Memory Tracking and Testing


Screen Section

The ACUCOBOL-GT Screen Section uses data structures that are similar to the record descriptions in Working-Storage. However, the Screen Section offers an alternate method for displaying information to the user's screen and accepting data from the keyboard. It lets you display and update data items in groups, rather than as individual fields.

The Screen Section enables a non-intelligent terminal to emulate an intelligent one by acting as if it were displaying and accepting an entire screen of data at one time.

Intelligent terminals can readily accept and transmit an entire terminal screen. The user moves around the screen and fills in a form consisting of several fields. The intelligent terminal stores all of the entries for the form in a buffer, and then transmits an entire screen full of information at one time.

Non-intelligent terminals are not designed to process data in this way. Instead, data is displayed and entered on a field-by-field basis. However, the ACUCOBOL-GT Screen Section lets non-intelligent terminals emulate intelligent terminals by acting as if they are displaying and accepting an entire screen of data at one time.

Although the data is actually handled behind the scenes on a field-by-field basis, the COBOL programmer can display or accept either individual fields or entire screens with one COBOL statement. Although it's common for a screen entry in the Screen Section to describe an entire screen, it need not do so. The language is so flexible that the programmer can decide whether to include one field, a few fields, or a screen full of fields in a Screen Section entry. See Screen Section for more information about the Screen Section.

  • Advantages
  • Structure
  • Syntax
  • Comparison to Field-level
  • Using Screen Section Embedded Procedures
Parent topic: Programmer's Guide


Advantages

The Screen Section lets you display or accept a screen full of items with only one COBOL statement. In addition, a significant amount of cursor handling is built in, so that end users move easily among the fields on the screen. Entry of tables of data becomes very simple, as shown in the table example in this section. End users gain the flexibility of entering and validating a screen full of related data at one time.

Parent topic: Screen Section


Structure

A screen description entry is similar to a data description entry. Just as a record's data description typically consists of:

  • a level number
  • a data-name
  • a Picture Clause

so a screen description entry typically consists of:

  • a level number
  • a screen-name
  • a Picture Clause

Because the programmer decides how many fields to group together, the screen-name may not actually refer to a full screen of data items. It might refer to a single field, a few fields, or an entire screen. In any case, each group or subgroup must be given a screen-name.

To place a screen or form on the terminal and receive data into that form, you need two different COBOL statements. The literals in a screen description entry are displayed by a DISPLAY Statement.

These are the prompting words that guide the end user. The information entered into the data items is accepted from the keyboard by an ACCEPT Statement. So, first you DISPLAY the screen, and then you ACCEPT the end user's entries for that screen.

Parent topic: Screen Section


Syntax

Each screen description entry must start with a level-number from level 01 through level 49. At the top level (01), the screen is given a name. For example:

01  employee-info-screen.

The other levels of a screen description entry (level 03 and so forth) can either name subscreens within the top-level screen, or:

  • provide literals that prompt the end user for entries
  • position the cursor
  • identify the data items that will store the information the end user types into each field

See Screen Description Entry in the ACUCOBOL-GT Reference Manual for a complete description of Screen Section screen description entry formats, their syntax and general rules.

When your program DISPLAYs a screen or ACCEPTs entries for a screen, the screen-name you reference in the DISPLAY or ACCEPT statement determines which fields are included. Everything subordinate to the screen-name is affected. For example, if you display a screen-name that's defined as a level 03 with two subscreens defined as level 05s below it, then all of the fields subordinate to the level 03 are displayed, and both of the subordinate level 05 screens and their attributes are also displayed.

Here are some examples.

This is an entry that names the screen and provides one literal:

01  employee-info-screen.
    03  emp-number-prompt value is "EMPLOYEE NUMBER: ".

This entry positions the cursor:

03  column plus 1
        line plus 2.

This entry identifies a data item to receive a typed entry:

03  PIC  9(9) to emp-number.

This defines a subscreen:

03  pay-period-dates.
        05  PIC 9(6) USING period-start.
        05  PIC 9(6) USING period-end.

Here's a complete program example for a table. It accepts a simple table on one line:

IDENTIFICATION DIVISION.
PROGRAM-ID. TABLE-SAMPLE-1.

DATA DIVISION.
WORKING-STORAGE SECTION.

01  TABLE-1.
    03  TABLE-ITEM OCCURS 5 TIMES     PIC X(5).

SCREEN SECTION.

01  SCREEN-1.
    03 "TABLE ITEMS:".
    03 OCCURS 5 TIMES USING TABLE-ITEM, COLUMN + 2.

PROCEDURE DIVISION.

MAIN-LOGIC.

    DISPLAY WINDOW ERASE.
    DISPLAY SCREEN-1.
    ACCEPT SCREEN-1.
    STOP RUN.

For additional examples that use tables, see OCCURS Clause.

The name that you give to a screen or subscreen in your Data Division must be referenced by the DISPLAY and ACCEPT statements that use the screen. Here's how that works.

First, you display the screen with a Format 2 DISPLAY statement. When this type of DISPLAY is executed, the screen-name in the DISPLAY statement tells which group of literals and data items should be displayed at the terminal. All of the literals in and subordinate to that screen-name definition are displayed in their appropriate positions. These typically serve as the prompts on the screen, guiding the end user. So the end user sees a form on the terminal, with multiple locations to enter data. That's why a Format 2 DISPLAY is said to be a form-level DISPLAY. Typical literals in a payroll program might be Employee Name: , Employee Number: , and Pay Period Ending Date: . The DISPLAY statement ignores the data items in the screen definition that are entry-only (TO) fields.

Second, you accept data into the screen with a Format 2 ACCEPT statement. When an ACCEPT statement of this type is executed, the screen-name that it references tells which screen of data items will be accepted. The ACCEPT statement ignores the literals in the screen definition as well as display-only (FROM) fields. The cursor moves to the position you've assigned to the first (non-literal) data item in the group, and waits for an entry. The end user can move around on the screen, from field to field and back again, with the tab and arrow keys (or other keys if you have customized the keyboard). When all items have been entered, the user presses a termination key to indicate that the screen is complete.

There are three types of screen description entries:

  • If a VALUE clause is specified, then the entry is a display literal. The word VALUE may or may not appear in a Screen Section VALUE clause.
  • If a PICTURE clause is specified, then the entry is a data field. The word PICTURE may or may not appear in a Screen Section PICTURE clause.
  • If neither a VALUE nor a PICTURE clause is specified, the entry is either a screen-name or an attribute.
Parent topic: Screen Section


Comparison to Field-level

The following paragraphs compare a field-level DISPLAY and ACCEPT to a form-level DISPLAY and ACCEPT for the same data. Both examples display a simple name and address form, and prompt the user to enter data.

  • Field-level ACCEPT & DISPLAY
  • Form-level DISPLAY and ACCEPT (Screen Section)
Parent topic: Screen Section


Field-level ACCEPT & DISPLAY

DISPLAY-AND-ACCEPT-ADDRESS.
  DISPLAY "Name:", ERASE SCREEN, LINE 1.
  DISPLAY "Address 1:", LINE 2.
  DISPLAY "Address 2:", LINE 3.
  DISPLAY "City:", LINE 4, "State:", COLUMN 25.
  ACCEPT NAME, LINE 1, COLUMN 12.
  ACCEPT ADDRESS-1, LINE 2, COLUMN 12.
  ACCEPT ADDRESS-2, LINE 3, COLUMN 12.
  ACCEPT CITY, LINE 4, COLUMN 12.
  ACCEPT STATE, LINE 4, COLUMN 32.
Parent topic: Comparison to Field-level


Form-level DISPLAY and ACCEPT (Screen Section)

SCREEN SECTION.
01  ADDRESS-SCREEN.
    03  ERASE SCREEN.
    03  "Name:".
    03  TO NAME, COLUMN 12.
    03  "Address 1:", LINE + 1.
    03  TO ADDRESS-1, COLUMN 12.
    03  "Address 2:", LINE + 1.
    03  TO ADDRESS-2, COLUMN 12.
    03  "City:", LINE + 1.
    03  TO CITY, COLUMN 12.
    03  "State:", COLUMN 25.
    03  TO STATE, COLUMN 32.
DISPLAY-AND-ACCEPT-ADDRESS.
    DISPLAY ADDRESS-SCREEN.
    ACCEPT ADDRESS-SCREEN.

There are three primary advantages of the Screen Section:

  • The centralized screen definition is easier to maintain, especially when screen processing occurs in more than one place in the program.
  • Automatic handling of arrow keys allows the user to move between fields without specialized programming.
  • Users gain improved automatic mouse handling on systems where the mouse is supported.
Parent topic: Comparison to Field-level


Using Screen Section Embedded Procedures

The following example shows how to use embedded procedures to provide an automatic look-up function plus field validation on a key field. In this example, an ellipsis in braces indicates omitted code.

IDENTIFICATION DIVISION.
PROGRAM-ID. SCREEN-EXAMPLE.
REMARKS.
This program shows how to use embedded procedures
in the Screen Section to:
(a) show a field-specific legend when the user
    arrives at that field,
(b) perform validation of a key field and,
(c) perform a look-up procedure when a special
    function key is pressed.
In this example, a customer-number field is included
in an order-entry screen.  When the user enters a
customer number, the program validates that it's an
existing customer and, if so, displays the customer's
name.  If it's not valid, the user must re-enter the
field.  If the user presses the F1 key, a look-up
procedure locates the desired customer.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
   CRT STATUS IS CRT-STATUS
   SCREEN CONTROL IS SCREEN-CONTROL.

INPUT-OUTPUT SECTION.
FILE-CONTROL.
   { . . . }

DATA DIVISION.
FILE SECTION.
   { . . . }

WORKING-STORAGE SECTION.
01  CRT-STATUS            PIC 9(3).
      88  F1-KEY            VALUE 1.

01  SCREEN-CONTROL.
    03  ACCEPT-CONTROL    PIC 9.
      88  GOTO-FIELD      VALUE 1.
    03  CONTROL-VALUE     PIC 999.
    03  CONTROL-HANDLE    HANDLE.
    03  CONTROL-ID        PIC XX COMP-X.

{ . . . }

SCREEN SECTION.
01  ORDER-SCREEN.
  { . . . }
  03  "Cust #: ".
  03  USING CUSTOMER-NO
      BEFORE PROCEDURE IS SHOW-CUST-LEGEND
      AFTER PROCEDURE IS TEST-CUSTOMER
      EXCEPTION PROCEDURE IS CHECK-FOR-LOOKUP.
  03  SHOW-CUSTOMER-NAME, PIC X(30) FROM
      CUSTOMER-NAME, COLUMN + 3.
  { . . . }

PROCEDURE DIVISION.
MAIN-LOGIC.
   { . . . }
   DISPLAY ORDER-SCREEN.
   ACCEPT ORDER-SCREEN
      ON EXCEPTION CONTINUE
      NOT ON EXCEPTION WRITE ORDER-RECORD
   END-ACCEPT.
   { . . . }
   STOP RUN.

* SHOW-CUST-LEGEND executes whenever the user
* arrives at the customer number field.  It
* displays a legend. This legend is removed by
* both the AFTER and EXCEPTION procedures
* associated with the customer-number field.

SHOW-CUST-LEGEND.
   DISPLAY "F1 = Customer Lookup", LINE 24,
   ERASE TO END OF LINE.

* TEST-CUSTOMER checks for a valid customer number
* entry by reading the customer file. If it finds a
* customer record, it displays the customer's name.
* If it does not find a record, it forces the user
* to re-enter the field by setting the SCREEN-
* CONTROL condition, GOTO-FIELD, to TRUE.  Since
* the ACCEPT statement initializes CONTROL-VALUE to
* the field number of the customer number field,
* setting GOTO-FIELD to TRUE will cause the ACCEPT
* statement to return to the customer-number field.

TEST-CUSTOMER.
   DISPLAY SPACES, LINE 24, ERASE TO END OF LINE.
   READ CUSTOMER-FILE RECORD
      INVALID KEY
         DISPLAY "CUSTOMER NOT ON FILE - PRESS RETURN",
         LINE 24, BOLD
         ACCEPT OMITTED
         SET GOTO-FIELD TO TRUE

      NOT INVALID KEY
         DISPLAY SHOW-CUSTOMER-NAME.

* CHECK-FOR-LOOKUP executes when the user types a
* function key when in the customer-number field.
* It erases the legend and then checks to see if
* Function Key 1 was pressed.  If it was, it
* executes a look-up procedure.  If the procedure
* returns with a valid customer selected, it
* displays the customer's name and causes control
* to pass to the next field. Otherwise, it forces
* the user to re-enter the customer-number field.
* It does this by setting GOTO-FIELD to TRUE while
* leaving CONTROL-VALUE unchanged.

CHECK-FOR-LOOKUP.
   DISPLAY SPACES, LINE 24, ERASE TO END OF LINE.
   IF F1-KEY
      PERFORM CUSTOMER-LOOKUP-PROCEDURE
      IF HAVE-CUSTOMER-NUMBER
         DISPLAY SHOW-CUSTOMER-NAME
         ADD 1 TO CONTROL-VALUE
   END-IF
   SET GOTO-FIELD TO TRUE.
Parent topic: Screen Section


Data Validation

ACUCOBOL-GT includes several mechanisms that instruct the runtime to perform specific types of validation on user supplied data. In instances where an input field is marked for validation, the runtime typically performs data validation when the user attempts to leave the data entry field. Data validation mechanisms include:

  • the REQUIRED (EMPTY-CHECK) and FULL (LENGTH-CHECK) phrases of the ACCEPT and Screen Section Screen Description Entry statements. See Common Screen Options for more information.
  • the SCREEN CHECK-NUMBERS=Validate option of the KEYBOARD variable. See The KEYBOARD Variable for more information.

Although validation is usually performed when the user attempts to leave the field, this is not always the case. Validation is not performed when the ACCEPT terminates as a result of the following:

  • an event, except CMD-GOTO and CMD-TABCHANGED
  • an exception key, except for keys that move the cursor from field to field in a Screen Section, such as the arrow keys
  • a message

The special exceptions noted above (CMD-GOTO, CMD-TABCHANGED, and the arrow keys) are treated as normal termination with regards to validation (they trigger validation), but they also generate their usual exception conditions.

Parent topic: Programmer's Guide


Exiting From ACUCOBOL-GT Programs

If an application written in ACUCOBOL-GT is aborted, the following exit techniques produce different results:

  • Catastrophic exit: A power failure, turning off the computer, or issuing a kill -9 from the console are all examples of catastrophic exits. The runtime cannot trap exits of this kind. Any files open at the time of a catastrophic exit may be corrupted.
  • Graceful abort: A kill (not a kill -9) from the console and a Control-C from the keyboard are forms of program abort that ACUCOBOL-GT tries to detect. If the abort signal is intercepted by the runtime system, the runtime will close any open files and set the user count back.
  • Safe mode exit: The runtime option -s instructs the runtime to trap graceful abort signals such as Control-C and prevent the abort from occurring. Only normally coded exit paths are allowed in safe mode.
    Note: Even in safe mode, the runtime cannot trap a catastrophic exit. So even if you run with -s, turning off the computer or issuing a kill -9 will risk corrupting the file.
Parent topic: Programmer's Guide


Multiple Execution Threads

ACUCOBOL-GT includes support for the specification and control of multiple execution paths in the program (multithreading). This means that you can define separately executing program threads and control their execution.

A thread is an execution path through a program. All programs have at least one thread, the thread (execution path) that starts when the program starts and ends when the program ends. In a program that has multiple threads, more than one thread may be active at a time.

When more than one thread is active, the runtime monitors and switches among threads, dividing processing time in accordance to program activity and thread priority (thread priorities are described below). In this way, threads can be thought of as running in parallel. Although conceptually they run in parallel, keep in mind that your program is still executing one statement at a time. The runtime controls the movement among active threads in response to a variety of conditions, such as computational activity, file I/O, user input, and programmatic controls, such as messages and locks (described below).

While most programs do not need multiple execution paths, there are some cases where threads can be helpful.

  1. Threads can be used to simplify modeless window handling. By tying threads to modeless windows you simplify the task of managing multiple windows. If each modeless window has its own thread, the runtime can automatically activate or suspend each window (via its associated thread). The code within each thread can then focus solely on managing its own window. This approach is much easier than the alternative, in which the program must be made to handle requests from any window at any time.
  2. Threads can improve system throughput. There are times when you can improve system throughput by performing tasks in one thread while waiting for user input in another thread. For example, you could do your program initialization while the user enters his or her password. Or, you could allow the user to edit the first item found by a complex search while your program continues searching for additional items.
  3. Threads can be used to control program actions. For example a program can present and accept a "cancel" dialog box in one thread while running a report in another. If the user clicks on the cancel button, that thread stops the report by terminating the report's thread.
  4. Threads can be used to perform periodic updates. Any periodic effect, such as updating an on-screen clock or performing animation, can easily be accomplished in a thread by placing that thread in a loop that sleeps for some period of time, wakes and performs the update, and then loops back to the sleep cycle. This allows the rest of your program to be written without concern about performing the periodic update.
  • Thread Fundamentals
  • Data Sharing Among Threads
  • Thread Communication
  • Thread Priorities
  • Threading Rules that Affect Windows and ACCEPT Statements
  • Thread Pausing
  • Multithreading and Multiprocessor Systems
  • Thread Interaction With Run Units
Parent topic: Programmer's Guide


Thread Fundamentals

Threads are created with either the PERFORM statement or the CALL statement. You simply add the word "THREAD" after the verb. The thread runs the target of the PERFORM or CALL statement. When the target completes, the thread is destroyed.

For example, to run the paragraph OPEN-FILES in a thread, you would code:

PERFORM THREAD OPEN-FILES

The main thread continues to execute at the statement following the PERFORM, while the OPEN-FILES code begins execution in a separate thread. When OPEN-FILES finishes, the thread is destroyed.

Threads are identified by thread handles. When you create a thread, you can optionally store its handle. Thread handles are used to communicate among threads. The next example demonstrates how this works.

There are times when you will want to ensure that a thread is complete before continuing in the program. For example, if one thread is used to open an application's files while another thread gets the user's password, you will not want to continue in the program until both tasks are complete, otherwise you might try to look up the password in a file that is closed. You can use the WAIT verb to make sure that both threads are complete before continuing. The WAIT verb causes the thread to wait for the specified thread to finish or send a message. The following example illustrates this process:

77  THREAD-1   USAGE HANDLE OF THREAD.

PERFORM THREAD OPEN-FILES, HANDLE IN THREAD-1
PERFORM GET-PASSWORD
WAIT FOR THREAD THREAD-1
PERFORM VALIDATE-PASSWORD

In this example, the paragraphs OPEN-FILES and GET-PASSWORD run in parallel. The WAIT statement ensures that OPEN-FILES is finished before the main thread goes on to validate the password.

  • LAST THREAD
Parent topic: Multiple Execution Threads


LAST THREAD

The need to synchronize threads is so common that there is an optional phrase, LAST THREAD, that can be used to simplify coding. Note that the thread that LAST THREAD refers to is dynamic, so some care must be taken in its use. LAST THREAD refers to:

  1. the last thread created by the current thread, or the last thread that the current thread communicated with, whichever was the last action
  2. or, if neither of the actions described in (1) has occurred, the parent thread (the thread that created the current thread)

You can use the LAST THREAD phrase to eliminate the need to store a thread handle. For example, the preceding example could also be written as:

PERFORM THREAD OPEN-FILES
PERFORM GET-PASSWORD
WAIT FOR LAST THREAD
PERFORM VALIDATE-PASSWORD

A thread normally ends when the PERFORM or CALL statement that created it completes. You can end a thread earlier in the execution path with the STOP THREAD statement. Used by itself, STOP THREAD terminates the current thread. You can also specify a thread handle to stop another thread. If there is only one thread running, stopping that thread is equivalent to doing a STOP RUN.

Parent topic: Thread Fundamentals


Data Sharing Among Threads

In the program that created it, a thread and its parent thread share the same data. This includes both working-storage and files (including the file's open state and record position). Thus any changes made in one thread will be seen by the other thread. The only data that are not shared are those items internally generated by the compiler that are related to the flow of control within a thread, such as a paragraph's return address or an internal counter associated with PERFORM N TIMES.

When a thread CALLs a program, any data local to that program are private to that thread (and its child threads). As a result, you can write utility routines that many threads can call, without having to worry about data sharing issues in the utility. Note that any data passed (BY REFERENCE) to the called program are shared if they are shared in the program passing the data.

External data items and external files are always shared by all threads.

ACUCOBOL-GT ensures that any one logical operation on a data item is fully completed before control switches between threads. Consider the following example:

77  DATA-1     PIC X(3).

PERFORM THREAD
    MOVE "ABC" TO DATA-1
END-PERFORM
MOVE "DEF" TO DATA-1
WAIT FOR LAST THREAD
DISPLAY DATA-1

The last DISPLAY will either print ABC or DEF depending on the order in which the threads execute. It will not, however, print something like AEF or DEC because each MOVE that affects DATA-1 is performed in its entirety before control switches between threads.

  • LOCK THREAD and UNLOCK THREAD
Parent topic: Multiple Execution Threads


LOCK THREAD and UNLOCK THREAD

There may be times when you want to be sure that a group of operations is performed without switching threads. For example, if you have a utility paragraph that does a series of math operations on a data item, you will not want to begin that paragraph and then switch to another thread if another thread uses that data item. In this case, you can use the LOCK THREAD statement to ensure that a series of operations are all accomplished together. For example:

PARA-1.
   LOCK THREAD
   ADD DATA-1 TO DATA-2
   IF DATA-2 > DATA-2-DIV-LIMIT
      MOVE DATA-2-DIV-LIMIT TO DATA-2
   COMPUTE DATA-2 = DATA-2 / DATA-3
   UNLOCK THREAD.

The LOCK THREAD statement ensures that no other thread executes. This condition remains in effect until the thread is unlocked (with UNLOCK THREAD) or the thread terminates. In the preceding example, if the LOCK THREAD was omitted, another thread referencing DATA-2 could see its value after the ADD but before the COMPUTE. This could be a value that is not meaningful.

A thread can have more than one lock. Each time a LOCK THREAD statement executes in the thread, the number of locks held by that thread increases by one. To allow other threads to run again, an equal number of UNLOCK THREAD statements must also execute. Each UNLOCK THREAD statement removes the last lock applied to the thread. This capability allows a thread to lock itself, call a subroutine that also locks itself, and remain locked after that subroutines unlocks itself.

The data sharing aspect of threads is very powerful. However, ensuring that the data are always consistent can be a difficult programming problem. When writing multithreaded programs, you should strive to share data in a well-defined manner to minimize this problem. The best way to do this is to share as little data as possible and to be clear when each thread is allowed to use that data.

Parent topic: Data Sharing Among Threads


Thread Communication

You can share data items among threads. This is the easiest form of communication among threads. The drawback to this form of data sharing is that you must carefully code the program so as to ensure that data is accessed and updated in a consistent manner. A second drawback is that there is no efficient way for one thread to wait for another to update a particular data item. You could arrange a set of data items to act as semaphores, but it is inefficient for a thread to loop until a data item reaches a particular value. It would be much better for the thread to sleep until the data item it needs is available.

To solve this problem, ACUCOBOL-GT provides a way for threads to send messages to each other. A message can be any data item. You decide in your program how you want to format messages.

  • SEND and RECEIVE
Parent topic: Multiple Execution Threads


SEND and RECEIVE

A thread sends a message to another thread with the SEND statement. A thread receives a message from another thread with the RECEIVE statement. Messages can either be broadcast, in which case they are sent to all threads, or directed, in which case the message is sent to a particular thread or set of threads.

For example, suppose you have a thread that updates a complicated display in response to a message. Another thread receives user input and sends messages to the update thread. The code might look like this:

77  H-DISPLAY-THREAD    HANDLE OF THREAD.
77  RECORD-NUMBER       PIC 9(5).
77  UPDATE-RECORD-NO    PIC 9(5).

MAIN-LOGIC.
    PERFORM INITIALIZE
    PERFORM CREATE-MAIN-SCREEN
    PERFORM THREAD DISPLAY-THREAD,
            HANDLE IN H-DISPLAY-THREAD
    PERFORM UNTIL DONE
        PERFORM ENTER-MAIN-SCREEN
        IF NOT DONE
            SEND RECORD-NUMBER TO
                 THREAD H-DISPLAY-THREAD
        END-IF
    END-PERFORM
    PERFORM SHUT-DOWN
    STOP RUN.

DISPLAY-THREAD.
    PERFORM CREATE-STATUS-SCREEN
    PERFORM UNTIL 1 = 0
        RECEIVE UPDATE-RECORD-NO FROM ANY THREAD
        PERFORM UPDATE-STATUS-SCREEN
    END-PERFORM.

The thread that updates the screen sits in an infinite loop waiting for messages. It will terminate when the runtime shuts down. Because it uses the RECEIVE statement, this thread is very efficient even though it contains an infinite loop. Note that the program includes two copies of the "record number": one sent by the main thread, and one to hold the value received by the update thread. This isolates the data sharing to the SEND and RECEIVE statements. If the main thread goes on to change RECORD-NUMBER while the update thread is performing its screen updates, the action will not affect the update thread because it has its own copy in STATUS-RECORD-NO.

The following example expands on the previous one to make the code more robust. In particular, the new code handles the case where other threads may be sending different types of messages, as well the case where all the sending threads die for some reason. Note that some of the code from the first example has been omitted for brevity:

77  H-DISPLAY-THREAD        HANDLE OF THREAD.
77  RECORD-NUMBER           PIC 9(5).

78  UPDATE-MSG-TYPE         VALUE 1.

01  SENDING-RECORD.
    03  SENDING-MSG-TYPE    PIC 99.
    03  SENDING-REC-NO      PIC 9(5).

01  UPDATE-RECORD.
    03  FILLER              PIC 99.
       88  IS-UPDATE-MSG    VALUE UPDATE-MSG-TYPE.
    03  UPDATE-RECORD-NO    PIC 9(5).

MAIN-LOGIC.
    PERFORM THREAD DISPLAY-THREAD,
            HANDLE IN H-DISPLAY-THREAD
    PERFORM UNTIL DONE
        PERFORM ENTER-MAIN-SCREEN
        IF NOT DONE
           MOVE UPDATE-MSG-TYPE TO SENDING-MSG-TYPE
           MOVE RECORD-NUMBER TO SENDING-REC-NO
           SEND SENDING-RECORD TO
                        THREAD H-DISPLAY-THREAD
           END-SEND
        END-IF
    END-PERFORM.

DISPLAY-THREAD.
    PERFORM CREATE-STATUS-SCREEN
    PERFORM UNTIL 1 = 0
        RECEIVE UPDATE-RECORD FROM ANY THREAD
           ON EXCEPTION
              PERFORM SENDING-THREADS-DIED-ERROR
        END-RECEIVE
        IF IS-UPDATE-MSG
            PERFORM UPDATE-STATUS-SCREEN
        END-IF
    END-PERFORM.

The preceding example assumes that all messages in the program will be formatted with a two-digit type code as the first element. The update thread checks the message received to see if it contains a type that it knows how to respond to. If it does not, it simply ignores the message. This check is a good idea because the update thread uses the ANY THREAD option in its RECEIVE statement. If some other thread broadcasts a message (SEND TO ALL THREADS), the update thread would receive the message even though it might not be an update message. Adding the message-type code resolves this issue. It also makes debugging easier if you have more than one message type in your program.

Messages can also interrupt a thread that is in an ACCEPT statement. However, to allow that you must declare that the ACCEPT statement may be interrupted. This is specified with the ALLOWING MESSAGES phrase in the ACCEPT statement.

Parent topic: Thread Communication


Thread Priorities

In a multithreaded program, it is likely that many threads will be active at the same time. To ensure that each active thread gets its proper share of CPU time, the runtime tracks certain types of operations, such as DISPLAY, file IO and basic computation operations, and periodically switches the executing thread. Each of these opportunities to change threads is called a switch point. The execution priority of each thread helps to determine which thread gets control at each switch point.

A thread's execution priority is an integer value. By default, all threads start with a priority value of 100. You use a Format 12 SET statement to change a thread's priority value.

Threads receive control in proportion to their priority. The higher the priority, the more often that thread gets control at a switch point. Thus, a thread with a priority of 50 gains control half as often as a thread with a priority of 100. Of course, if a thread is paused for any reason, such as waiting for input, the thread does not gain control. The minimum priority for a thread is one (1), the maximum is 32767.

Three runtime configuration variables, SWITCH_PERIOD , DISPLAY_SWITCH_PERIOD , and IO_SWITCH_PERIOD , can be used to affect how the runtime manages thread switching.

Parent topic: Multiple Execution Threads


Threading Rules that Affect Windows and ACCEPT Statements

There are a number of special rules that govern how and when threads can receive user input. In the following discussion, the phrase ACCEPT statement refers specifically to formats 1, 2, and 7 of the ACCEPT statement. These are the forms that retrieve the user's input.

When a thread attempts to execute an ACCEPT statement, two rules determine if that thread is allowed to proceed:

  1. The thread may proceed if no other thread is in an ACCEPT statement. This rule ensures that threads do not compete for a single piece of input. It prevents the possibility, for example, of alternate keystrokes going to different threads.
  2. The thread may proceed if the window in which the ACCEPT will occur is active, or if the active window is controlled by the current thread. A window is controlled by the thread that created it or the last thread that did an ACCEPT statement in it. A window can be controlled by only one thread at a time. This rule ensures that windows do not activate arbitrarily.

If an ACCEPT does not meet both of these conditions at the time that it would normally execute, its thread is suspended. The thread will remain suspended until both conditions are met (at which time the thread resumes and the ACCEPT executes).

Note: Even if the thread is suspended and the ACCEPT is not started, the ACCEPT may still be timed out with ACCEPT BEFORE TIME. It can also be terminated with a message, if ACCEPT ALLOWING MESSAGES is specified.

These rules apply only if there is more than one thread. If a suspended thread becomes the only remaining thread, then it automatically resumes execution.

If a thread suspends due to rule (2), it will suspend forever unless its window becomes active. This can happen in one of two ways: (a) another thread activates the window, or (b) the user activates the window. Arranging for the latter is much more common. It is the case where you want to give the user the ability to work in multiple windows at once, freely switching between them.

To create windows that the user can activate at will, you describe the windows as MODELESS when you create them. A modeless window allows the user to activate another window (the other type of window, called modal, does not allow the user to activate another window). When the user activates a modeless window, by clicking on it or using the host's method, the runtime generates a CMD-ACTIVATE event. In a single-threaded program, the program must detect this event and ACCEPT something in the appropriate window in order to activate that window. In a multithreaded program, there is a second option. To use this option you code your program in such a way that each modeless window runs in a separate thread, and you use the phrase LINK TO THREAD or BIND TO THREAD when you create each window. This phrase instructs the runtime to handle the CMD-ACTIVATE events on its own. In this arrangement, when a CMD-ACTIVATE event occurs, the runtime suspends the current thread and activates the new window. The thread controlling the newly active window then resumes execution. Technically speaking, the thread running the ACCEPT in the newly active window can leave the suspended state because it meets rules (1) and (2) described above.

This automatic runtime handling allows you to easily manage multiple windows. Each window is contained in a thread that need only manage that one window. The threads do not need to be aware of each other or know which window is active. If the threads have some need to communicate among themselves, they can do so with messages. See Thread Communication for more information.

Here is an example. The following program presents a maintenance screen for a data file. It also pops-up a window that has a list of all the records in the file. The user can update a record on the maintenance screen, and can select records from the list. When the user selects a record, the maintenance screen is updated with the selected record.

MAIN-LOGIC.
   PERFORM INITIALIZE
   DISPLAY STANDARD GRAPHICAL WINDOW,
      LINK TO THREAD
   PERFORM THREAD SEARCH-THREAD,
   PERFORM UNTIL DONE
      PERFORM DISPLAY-RECORD
      ACCEPT MAINTENANCE-SCREEN
         ALLOWING MESSAGES FROM LAST THREAD
         ON EXCEPTION
            IF KEY-STATUS = W-MESSAGE
                PERFORM SAVE-CURRENT-RECORD
                RECEIVE RECORD-NUMBER
                        FROM LAST THREAD
            END-IF
      END-ACCEPT
   END-PERFORM
   PERFORM SHUT-DOWN
   STOP RUN.

SEARCH-THREAD.
   DISPLAY FLOATING GRAPHICAL WINDOW,
      MODELESS, LINK TO THREAD
      HANDLE IN H-SEARCH-WINDOW
   PERFORM DISPLAY-SEARCH-LIST
   PERFORM UNTIL 1 = 0
      PERFORM ACCEPT-SEARCH-LIST
      SEND RECORD-NUMBER-SELECTED TO LAST THREAD
   END-PERFORM.

This example shows how using threads can simplify managing multiple windows. In it, one thread manages the main window, and one manages the search window. The search window is very simple, its thread sits in an infinite loop fetching a list item from the user and sending it to the main thread. The main thread sits in a loop accepting the main screen. If a message arrives from the search thread, it saves the current record and retrieves the record sent from the search window. By using multiple threads, each piece of your window-handling code stands alone. If it were written as a single-threaded program, the two loops accepting the windows would have to be combined into a single loop, with a state variable tracking which window is currently active.

Tip: The use of modeless windows and threads to provide the ability to switch between screens by pressing Taskbar buttons is demonstrated in an AcuBench sample project located in the Support area of the Acucorp Web site. To download the project, open your Web browser and navigate to: http://supportline.microfocus.com/examplesandutilities/index.asp. Select the ACUCOBOL-GT® Samples > Graphical User Interface (GUI) Sample Programs and click Threadds.zip.
Parent topic: Multiple Execution Threads


Thread Pausing

There are some conditions in which all of the threads in your program will pause. One reason this occurs is when some event in the system causes the entire runtime to suspend. The pause ends when the runtime regains control. The main cases where this occurs are:

  1. when moving any of the application's windows with the mouse. The host system manages this task.
  2. when a message box is displayed (by calling the MESSAGE utility program or DISPLAY MESSAGE BOX). The message box is managed by the host system. You can use this to your advantage by using message boxes to report critical errors. The message box requires that the user respond to the box before any part of the application will resume.

Although the host system does not handle these tasks in character-based versions of the runtime, architectural similarities between the character and graphical versions cause these tasks to produce the same effect on character systems.

Another reason for all threads in your multithread program to pause is waiting for locked records. You can configure the runtime to automatically wait for locked records by either setting the WAIT-FOR-LOCKS configuration option, or by compiling with the RM/COBOL compatibility (-cr option) and omitting a declarative for this particular file. When you do this in a multi-threaded program, all threads are frozen while waiting for a locked record to unlock. This occurs because the runtime employs a very tight wait loop that does not allow other threads to continue running.

Note: You can avoid this by writing your own wait loop. Simply turn off the runtime option and perform the affected file operations in a loop until the file status is not 99. For efficiency, we recommend calling C$SLEEP for at least one second between file operations when waiting for a lock.
Parent topic: Multiple Execution Threads


Multithreading and Multiprocessor Systems

ACUCOBOL-GT implements multithreading in a machine-independent fashion. It neither needs nor uses any multithreading capabilities of the host system. This has several advantages:

  1. You can run multithreaded programs in environments that do not otherwise support multithreading.
  2. Multithreaded programs run the same way under different environments.
  3. ACUCOBOL-GT can provide features not universally available in multithreaded systems, such as the link between windows and threads.

There are, however, a few disadvantages to this implementation. Chief among these is that the operating system is not aware that there are multiple threads running in the runtime's process. This is primarily an issue on systems that have multiple processors. Some of these systems can allocate additional processors to a task if they know that the task contains more than one thread - up to one processor per thread. But because these systems do not see the runtime as a multithreaded entity, multiprocessor allocation does not happen.

Typically, multiprocessor systems are used to provide support for more users. By having more processors in the system, the system can run more processes at once, and in this way increase the number of users the machine can effectively support. But the system will not increase performance for a single process (assuming that the process gets 100% of the CPU's time - an unrealistic assumption in a production environment). In practice, a multiprocessor machine will usually not benchmark any better than a single processor machine for single-task benchmarks, but they will provide much better total throughput in a multi-user production environment.

In summary, multithreading an ACUCOBOL-GT program will not affect its performance in any special way on a multiprocessor machine. Any gain, or loss, will be the same as for a single processor system.

Parent topic: Multiple Execution Threads


Thread Interaction With Run Units

The following rules apply to the interaction of threads with run units:

  1. The CHAIN and CALL PROGRAM statements normally act as if the program does a STOP RUN followed by the beginning of a new run unit. The implied STOP RUN destroys all threads other than the one executing the CHAIN or CALL PROGRAM statement.
  2. If you have more than one thread running, you may not start a nested run unit (accomplished with the CALL RUN statement).
Parent topic: Multiple Execution Threads


Working with External Sort Modules on UNIX

The ACUCOBOL-GT runtime on UNIX platforms can call most third-party sort modules that support the EXTSM interface to perform SORT and MERGE operations. The EXTSM call interface allows you to substitute other sort modules that may enhance performance or offer more flexibility for sort features.

Sort modules can perform file handling using the EXTFH interface, which the ACUCOBOL-GT Runtime makes available to third-party sort modules. The sort module may also interface directly with the Vision library.

  • Before Using an External Sort Module
  • Linking in a Third-Party Sort Module
Parent topic: Programmer's Guide


Before Using an External Sort Module

Depending on the sort and merge results you want to achieve, you may need to recompile programs and set a new environment variable:

  • To use Micro Focus-style sign representation for data items, compile your programs with the -Dcm (Data Storage Options) switch.
  • To obtain the behavior of SORT...WITH DUPLICATES IN ORDER, set the following environment variable:
COBSW=+S
Note: You must set COBSW even if the COBOL program already specifies the WITH DUPLICATES IN ORDER phrase.
Parent topic: Working with External Sort Modules on UNIX


Linking in a Third-Party Sort Module

In order to use a third-party sort module with the ACUCOBOL-GT Runtime, you must relink the runtime using the following steps:

  1. Install the third-party sort software.
  2. Refer to the documentation for the EXTSM interface to understand its operation and use.
  3. Make a copy of the lib/Makefile file in your ACUCOBOL-GT installation. You can use this backup copy to ensure that the relink of the runtime works before you make the changes to support the EXTSM interface.
  4. Edit lib/Makefile to enable linking with the third-party sort library, as instructed in the Makefile section, EXTSM configuration.
  5. Execute the make command to relink the runtime..

After creating the new runtime, which includes the third-party sort module, set the USE_EXTSM configuration variable to 1 and then run programs as usual. For more information, refer to Appendix H, Configuration Variables.

You can then run programs with SORT and MERGE verbs run as they normally would. See Procedure Division Statements in the ACUCOBOL-GT Reference Manual for more information.

Parent topic: Working with External Sort Modules on UNIX


ACUCOBOL-GT User Interface Programming

  • Introduction
  • Floating Windows
  • Graphical Controls
  • Supporting Concepts and Related Issues
  • Control Types Reference
  • Events Reference
  • Using the Mouse
  • Menu Bars and Pop-up Menus
  • Color Mapping
  • Help Automation
  • Tips and Hints
  • UI Terminology
Parent topic: ACUCOBOL-GT Version 10.2.0 Documentation Set


Introduction

  • Overview of User Interface Features
  • Developing Programs for Graphical Systems
  • Windowing Concepts
  • ACUCOBOL-GT Window Types
  • Creating Portable User Interfaces
  • GUI Development Project Issues
  • Sample Programs
Parent topic: ACUCOBOL-GT User Interface Programming


Overview of User Interface Features

ACUCOBOL-GT® is part of the extend® family of Micro Focus solutions.

In addition to the standard display handling included in ANSI-85 COBOL, ACUCOBOL-GT offers a comprehensive set of extensions for programming and managing Graphical User Interfaces (GUIs). With these extensions, an ACUCOBOL-GT developer can add a full-featured, native GUI to an existing program entirely in COBOL. The purpose of these extensions is to:

  • allow developers to create a fully graphical program in COBOL for use on systems such as Microsoft Windows.
  • allow developers to use a mix of graphical and character-based interfaces in one program. Graphical features can be added to an existing program without the need to rewrite the entire user interface.
  • allow programmers to develop graphical interface specifications that are portable to a variety of host systems.
  • support graphical features in a way that is natural for COBOL.
  • mimic existing COBOL screen syntax as closely as possible to simplify the task of reworking a character-based program into a graphical program.
  • avoid the need to do event loop programming that is common for graphical systems, but foreign to most COBOL programs.
  • make it easy to add new graphical capabilities in the future.

ACUCOBOL-GT supports the emulation of graphical controls and windows on character-based systems. This emulation allows you to more easily write a single program that will run on both character and graphical systems. ACUCOBOL-GT supports the emulation of floating windows and the following control types: label, entry field, push button, radio button, frame, check box, list box (including infinite capacity list box), and combo box.

You can also use ACUCOBOL-GT's traditional text-oriented mechanisms for creating your user interface, such as the textual forms of the ACCEPT and DISPLAY verbs, and Format 1 of the Screen Section. In addition, you can use the Screen Section extensions to define and process both character-based and graphical user interface screens.

References to Windows in this manual denote any of the supported Windows platforms, which are listed in the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx. Where it is necessary to make a distinction, the specific version name/number is specified. .

Generally, ACUCOBOL-GT GUI supports include:

  • syntax extensions for creating native floating windows, toolbars, and controls (such as buttons, entry fields, and labels)
  • the ability to create and manage menu bars with pull-down submenus
  • configuration variables for customizing windows, importing icons, and mapping colors
  • many host specific features such as message boxes and context-sensitive help

Specifically, ACUCOBOL-GT's GUI programming supports include:

  • native floating (moveable) windows, including:
    • "modal" and "modeless" window types
    • default and custom window size and position
    • dynamically resizeable windows
    • configurable borders
    • programmable title bar
    • optional system menu
  • GUI controls, including:
    • labels
    • entry fields
    • standard and infinite capacity list boxes
    • combo boxes
    • push buttons
    • radio buttons
    • check boxes
    • frames
    • bars*
    • scroll bars*
    • tabs*
    • tree views
    • bitmaps*
    • grids*
    • status bars
    • Web browsers*
    • .NET, ActiveX, and COM elements*
  • menu bars and submenus
  • display of bitmaps and bitmap buttons*
  • toolbars*
  • access to the native message box facility
  • access to the native file open and file save-as dialog boxes*
  • access to the native help facility and support for context sensitive help
  • specialized mouse handling
  • font selection and handling
  • custom colors
  • the ability to play ".WAV" audio files on Microsoft Windows systems with sound capabilities
Note: Items marked with an "*" are not supported in text-mode environments

ACUCOBOL-GT run-time supports include:

  • full object code compatibility
  • the creation and run-time management of native floating windows and graphical controls on Microsoft Windows and Windows NT
  • automatic text-mode emulation of floating windows and most graphical controls, except bars, scroll bars, tabs, animated bitmaps, bitmap buttons, and toolbars
  • automatic mouse support
  • automatic menu bar handling
  • extensive color mapping facilities
  • access to the Windows print spooler
  • automatic multi-tasking support
  • network compatibility
  • access to all memory available under Windows
  • Floating Windows and Graphical Controls
  • Automatic GUI Runtime Support
Parent topic: Introduction


Floating Windows and Graphical Controls

ACUCOBOL-GT supports a class of windows called floating windows. When run under a graphical environment, floating windows correspond to the graphical windows that are native to the host environment. Floating windows pop up over their parent window and can be repositioned by the user with the mouse or system menu (if present).

ACUCOBOL-GT also supports the creation, display, and manipulation of graphical controls. Toolbars can also be created and attached to floating windows. A toolbar can host any type of control, but is usually populated with push buttons, check boxes, and radio buttons. To simplify the programming of graphical controls, ACUCOBOL-GT provides a consistent method for their specification and handling. For a complete description of graphical controls, see Graphical Controls.

Parent topic: Overview of User Interface Features


Automatic GUI Runtime Support

Many GUI capabilities are provided automatically by the runtime. To take advantage of these features, you don't have to change your COBOL code, and you don't have to recompile your program. You simply use the object code generated with your ACUCOBOL-GT Compiler, and execute it with a run-time for Windows. When you do this your program automatically gains:

  • a native, moveable, main application window.
  • basic mouse support. Users can point and click to move the cursor, and can highlight a string of characters and replace the string by typing a new one.
  • customizable colors, titles, window sizes, window placement, and program icons (tailored with runtime configuration variables).
  • access to the system's print spooler, so that several files may be queued for printing.
  • the ability to run more than one application at the same time.
Parent topic: Overview of User Interface Features


Developing Programs for Graphical Systems

The following sections discuss issues of importance to developers who are building systems for graphical environments.

  • Event-driven Environments
  • Configuration and Programming Support
  • Index to Related Topics
  • GUI Development with Third-party Kits and Tools
Parent topic: Introduction


Event-driven Environments

Most GUI environments are event-driven. Unlike traditional operating environments in which a program prompts for input and the user responds, the event-driven environment turns the relationship around. Actions are initiated by the user or system, and it's the job of the program to listen for and respond to events (events include such things as mouse movements, menu selections, and data entry).

To support this, event-driven programs have an event loop that waits for and handles events. Including an event loop in a COBOL program usually requires significant changes to existing code. However, in ACUCOBOL-GT the run-time implements the event loop and manages nearly all events for the application. There is no need for the COBOL program to include an event loop. This greatly simplifies programming for event-driven environments and preserves the traditional procedural structure of the application. Events which must be handled by the application are passed through to the program along with any necessary data. The application is typically programmed to handle these events in the same way that it handles the press of a function key. Events and event handling are described in Events and in Events Reference.

Parent topic: Developing Programs for Graphical Systems


Configuration and Programming Support

ACUCOBOL-GT provides many configuration variables and run-time library routines to tailor the environment and to help take advantage of host-specific capabilities. Configuration variables are documented in Appendix H. Configuration Variables. Library routines are documented in Appendix I. Library Routines. Windows-specific information is documented in A Guide to Interoperating with ACUCOBOL-GT as is information on working with transaction processing and message queueing systems on IBM and other hosts.

Following is a select list of configuration variables, runtime library functions, and host-specific capabilities pertinent to interface programming and configuration.

Parent topic: Developing Programs for Graphical Systems
Related reference
Appendix H. Configuration Variables
Appendix I. Library Routines
A Guide to Interoperating with ACUCOBOL-GT


Index to Related Topics

Following is a select index to related topics and topic sections in the ACUCOBOL-GT help.

Related Topics

ACCEPT verb | Procedure Division Statements in ACUCOBOL-GT Reference Guide
Configuration Variables | Appendix H. Configuration Variables in ACUCOBOL-GT Appendices
DISPLAY verb | Procedure Division Statements in ACUCOBOL-GT Reference Guide
Display interface | The Display Interface in ACUCOBOL-GT User's Guide
Library routines | AP Appendix I. Library Routines in ACUCOBOL-GT Appendices
Screen Section | Screen Section in ACUCOBOL-GT User's Guide and Screen Section in ACUCOBOL-GT Reference Manual
SPECIAL-NAMES paragraph | Special-Names Paragraph in ACUCOBOL-GT Reference Manual

Other major topics

ACUCOBOL-GT product overview | ACUCOBOL-GT Documentation in ACUCOBOL-GT User's Guide
Compiler, using | Compiler and Runtime in ACUCOBOL-GT User's Guide
Debugger, using | Runtime Debugger in ACUCOBOL-GT User's Guide
Multithreading | Exiting From ACUCOBOL-GT Programs in ACUCOBOL-GT User's Guide
Runtime, using | Using the Compiler in ACUCOBOL-GT User's Guide
Working-Storage Section | WORKING-STORAGE Section in ACUCOBOL-GT Reference Manual
Parent topic: Developing Programs for Graphical Systems


GUI Development with Third-party Kits and Tools

To add graphical features not currently supported by ACUCOBOL-GT, you can use one of the system development kits offered by operating system vendors. For example, the Windows Software Development Kit (SDK) from Microsoft supports extensions to applications running under Windows. Using the SDK, you can build C routines that provide extra features, and then call the C routines from your COBOL application. ACUCOBOL-GT is fully compatible with the Microsoft Windows SDK, so the two are readily integrated.

Parent topic: Developing Programs for Graphical Systems


Windowing Concepts

The following basic window concepts form the foundation for GUI programming and ACUCOBOL-GT window support.

The Screen

The screen is the physical display area of the monitor.

The Virtual Screen

The virtual screen is a non-physical display area allocated to the application by the operating system (or the ACUCOBOL-GT run-time). It is called virtual because not all of the allocated area need be displayed on the physical screen. A window (defined below) is used to frame the virtual screen, and scroll bars are provided, if necessary, to allow the user to navigate to any part of the virtual screen. The application behaves as if the entire virtual screen is always available.

Window

A window is a rectangular display area that provides a view of the virtual screen. It can be any size, including the entire screen. It is usually framed. Depending on the window type and the underlying system software, windows are displayed in either graphical or text-mode. Windows can include a number of other interface objects, such as a title bar, menu bar, and controls.

In GUI environments, windows are the fundamental construct used to display and accept commands and data from the user.

The Main Application Window

The main application window is the application's primary window. The main application window is typically the first window that the application creates. It usually includes a title bar displaying the application's name, and a menu bar for quick access to the application's basic functions. The main application window is usually movable and resizeable.

Modeless Windows

A modeless window is a window that allows the user to switch between windows — usually application windows — without having to close the current window. The current window application continues to run in the background even after you switch to another window. An application might also use several modeless windows to give the user access to different program functions and to provide separate views of program data. The user activates a modeless window using the host's method — usually by clicking on it. Modeless windows can contain most any type of control and are typically moveable and resizeable. An application's main application window is usually a modeless window.

Modal Windows

A modal window is a window that the user must respond to and close before the application will continue. Dialog boxes are typically modal windows. Modal windows may include buttons, entry boxes, and other controls that the user manipulates to provide input, and to confirm or cancel an action. Modal windows are usually moveable but not resizeable.

Controls

A control is a self-contained graphical object with a dedicated function, such as a push button, check box, entry field, or scroll bar. Controls are also known as widgets. Though they are technically windows, controls are not moveable or resizeable, nor do they have many of the other properties of a window.

Parent topic: Introduction


ACUCOBOL-GT Window Types

ACUCOBOL-GT includes two fundamental window types: floating windows and subwindows (sometimes referred to as pop-up windows). Each window type is discussed briefly below. Floating windows are discussed in detail in Floating Windows.

ACUCOBOL-GT also supports many types of controls (technically a type of window). Controls are discussed in detail in Graphical Controls.

Floating Windows

A floating window is the ACUCOBOL-GT window type that creates a host-based, pop-up window. When your application executes in a graphical environment, such as Microsoft Windows, floating windows are created as native pop-up windows, managed by the host operating system and the ACUCOBOL-GT run-time.

Floating windows must be used when you want to include graphical controls, such as buttons, entry boxes, and scroll bars. ACUCOBOL-GT supports two types of floating windows: modal and modeless.

Floating windows are positioned and displayed on the virtual screen. The virtual screen is intrinsic to all applications that use floating or subwindows. The virtual screen size can be set with the SCREEN SIZE run-time configuration variable and changed during program execution with the MODIFY Statement. The default virtual screen size is 25 rows by 80 columns. See Windowing Concepts for more information.

Independent Windows

An independent window is similar to a floating window, except that independent windows do not belong to parent windows; independent windows are controlled independently.

Subwindows

Subwindow is the name given to ACUCOBOL-GT text-mode windows created with the DISPLAY WINDOW or DISPLAY SUBWINDOW statement.

Subwindows are always text-mode windows and are not compatible with graphical controls. However, subwindows can be mixed with floating windows, so long as the subwindows do not display on top of graphical controls. When an overlay occurs, due to the workings of the underlying host system, control objects are improperly displayed on top of the text-mode subwindow. For a discussion of textual and graphical modes, see Graphical vs Textual Modes.

You can easily convert subwindows to floating windows by changing the DISPLAY WINDOW statement to a DISPLAY FLOATING WINDOW statement. However, subwindows that simply define a screen region, that are not bordered, or are not pop-up in nature, do not lend themselves to conversion to floating windows.

Parent topic: Introduction


Creating Portable User Interfaces

ACUCOBOL-GT allows you to run programs on a wide variety of host systems. Because of its machine-independent object code, many programmers use ACUCOBOL-GT to write programs that will run under several different host systems. However, it can be challenging to write a program that looks good and functions well under both character-based systems and graphical systems because of the vastly different nature of these systems. This is especially true if you include graphical controls in your programs.

You could take into consideration all of the differences between graphical and character-based systems and design your user interface accordingly. You could develop one interface, one set of source code to handle all situations; you could develop two interfaces, but maintain them in a single set of source code; or you could develop two separate programs altogether (one for graphical systems and one for character-based systems). Because many developers use ACUCOBOL-GT to convert existing character-based programs into graphical programs, these sections adopt the point of view that you are doing such a conversion. However, most of the comments apply to writing new programs as well.

  • Incompatibilities Between Graphical and Character Systems
  • Strategies for Supporting Multiple Systems
  • Tips for Solving Cross-Platform Interface Problems
Parent topic: Introduction


Incompatibilities Between Graphical and Character Systems

Ideally, you could simply modify your program to use graphical features, and that program would then run perfectly under both graphical and character systems. However, this is usually not the case. The key problems arise in the different physical traits associated with graphical and character systems. Let's examine some of the primary differences.

For character systems, you can generally assume that you have a screen area of 24 or 25 lines by 80 columns. While you can occasionally find larger screens (for example, many Xterm configurations), designing your programs for 24 by 80 will guarantee nearly universal compatibility. (Some programmers use 25 lines instead because this is the number of lines normally provided on IBM PC compatibles, as well as many common terminals. The discussion below uses 24 lines because it is traditionally the most portable value. If you use 25 lines instead, the discussion still applies, but the problems that arise during the conversion to a graphical system are more obvious.)

The display characteristics of graphical systems are harder to analyze. Looking at current Microsoft Windows systems, they are usually configured with one of these screen resolutions: 640 x 480, 800 x 600, or 1024 x 768. You can find other sizes too, but these account for the vast majority. Now, translate these values into character cells to see how they compare with character systems. The FIXED-FONT used by ACUCOBOL-GT is usually designed to be 8 pixels wide by 15 pixels high. On a 640 x 480 screen, this gives exactly 80 characters across (assuming the window borders are placed off of the screen) and 42 characters high (in practice, somewhat less because of space used by the window's title and menu). This size works fine with a 24 x 80 layout, and so simply running a character-based program under Windows works fine.

However, problems arise when you convert that character-based program to use graphical controls. Consider what happens when you convert text-based data entry fields into ENTRY-FIELD controls. Typically, entry fields are boxed (have a border around them) so that they match the normal look of a Windows application, and they usually display using the DEFAULT-FONT (a proportional font). The DEFAULT-FONT is normally 13 pixels high by 7 pixels wide. Making the entry fields boxed adds 50% to their height, with the result that they are 20 pixels high. This gives exactly 24 lines on a 640 x 480 screen, but only if you omit all of the window borders, the title and menu, and assuming that you do not include any spacing between the entry fields. If you want to add a 3-D look to the entry fields, you need at least another 3 pixels, making 24 lines approximately 552 pixels high (again, ignoring the window title and other features). In practice, you will usually want to be able to see the window's title, and its menu and toolbar (if any). This adds approximately 20 to 40 pixels depending on how many elements are present. As a result of these conditions, you cannot assume that you have 24 lines available on a 640 x 480 system when you include graphical controls.

Note: Switching to the DEFAULT-FONT actually gains horizontal space: it is only 7 pixels wide instead of the 8 used by the FIXED-FONT. In reality, even more space is gained because DEFAULT-FONT is a proportional font. Most strings of lower-case letters occupy much less space than 7 pixels per character (upper-case strings, on the other hand, occupy much more space).

Thus, the first major problem can be summarized as follows:

For a given screen resolution, a graphical screen is effectively shorter and wider than the equivalent character-based screen.

Differences in the physical dimensions of controls also cause problems in placing them. Consider entry fields again. On a character-based system, entry fields are one line tall. On a graphical system, they are 1.5 lines tall. ACUCOBOL-GT has a feature to account for this difference, but there are also problems in horizontal positioning that are harder to account for. For example, two radio buttons placed side-by-side might look great on a graphical screen, but they may overlap when displayed on a character screen. This happens because of the effects of shifting from a proportionally sized font to a fixed-size font.

Now consider a FRAME control. On a graphical system, the frame is drawn around the area that it occupies (except for the top line, which is adjusted to account for the frame's title). On a character system, the frame is drawn in the middle of the character cells forming the edge of the frame, because that is the best positioning that a character system can perform. A frame that is two lines high on a graphical system has enough space inside it to hold one line of text. On a character system, a two line high frame has no space inside it to hold anything.

Thus the second major problem is:

Controls occupy different amounts of space in character and graphical systems.

Help topics in this section discuss various approaches to managing these issues. While there is no single solution to all the cases, ACUCOBOL-GT offers a variety of ways to handle these problems.

Parent topic: Creating Portable User Interfaces


Strategies for Supporting Multiple Systems

Selecting the best approach to supporting both graphical and character systems is very important and well worth the time invested. In general terms, there are three possible approaches to this problem. You can use ACUCOBOL-GT with any of these approaches. These approaches can be summarized as follows:

  • Dual interface, dual code

    This approach uses separate programs for graphical and character systems.

  • Single interface, single code

    This approach uses one program with a single user interface that runs under both graphical and character systems.

  • Dual interface, single code

    This approach uses one program that includes two user interface implementations, one for graphical systems and one for character systems.

  • Dual Interface, Dual Code
  • Single Interface, Single Code
  • Dual Interface, Single Code
  • Selecting the Right Approach
  • Determining Which UI is Running
Parent topic: Creating Portable User Interfaces


Dual Interface, Dual Code

This approach is in many ways the most obvious and straightforward. It is also the approach used most often by other programming systems: simply write different programs for the graphical and character systems. The big advantage of this approach is that you can customize the code for the characteristics of the host system as much as you want. Additionally, you incur no overhead for having to include code that is not used for a particular system. Finally, when you are programming you don't have to think about two systems at the same time. Development time for any one system is shortened and testing is easier. These are all significant advantages.

Unfortunately, there are also many significant disadvantages. You have to write two programs instead of one. And, you must maintain two programs. Because there are two programs, you are likely to encounter twice as many bugs. Also, the time required to develop the set of programs is most likely greater than required by the other approaches.

Here are some cases where this approach offers significant advantages:

  1. If you are in the process of retiring or freezing a character-based application, then you can simply use that application as the starting point for its graphical incarnation and leave the character version in its original form in an archive for future maintenance. In this scenario, you do not expect to do much more work on the character version, so spending a lot of effort in maintaining a single piece of source code is probably not worth what you gain.
  2. If you intend to have sizable functional differences between a character-based application and its graphical sibling, then it might not make sense to try to have a single program cover both cases. In this case, you really do have two different programs, with some overlap in their functionality. The overlapping portions could be maintained as a separate library of source that is shared by both systems.

In general, if you view the character-based application as having a limited future, then this approach generally makes the most sense. The other two approaches are more attractive if you plan on maintaining and enhancing the character-based application in the future.

Parent topic: Strategies for Supporting Multiple Systems


Single Interface, Single Code

This approach relies on ACUCOBOL-GT's ability to run the same program on any machine. With this approach, you write a single program that has a single user interface that runs on all machines. The big advantage of this approach is that you need to write and maintain only one program. The disadvantages are that you will have to work harder to get a program that looks good on all systems, and you are limited to only those features that are available on both graphical and character-based systems. Generally, this means developing a simpler user interface for the graphical system than you might otherwise choose. If you presently have a character-based user interface and do not plan to add graphical controls, then this approach is straightforward to pursue and is the obvious choice.

The biggest challenge to this approach is developing code that works well under both systems. This generally means a lot of back-and-forth development under Windows and a character-based system to ensure that the results look good and work well. Fortunately, AcuBench® provides a built-in facility for testing both character and GUI interfaces under Windows. Alternatively, you can use Acucorp's Windows Console run-time to perform initial character-based testing.

This approach generally accommodates graphical single-line labels and entry fields. Getting labels and entry fields to look right on both types of systems is fairly easy. Incorporating other graphical elements tends to be harder and should be done sparingly.

ACUCOBOL-GT does not yet support all control types on character-based systems. In particular, bars, scroll bars, bitmaps, and tabs are not supported, so you need to avoid these when using this approach. Support for these controls may be included in a future version.

Parent topic: Strategies for Supporting Multiple Systems


Dual Interface, Single Code

With this approach, you write a single program that includes two user interfaces: one for character systems and one for graphical systems.The two user interfaces gather the same data, but in a fashion that is customized for the host system. After the data is collected, the remainder of the program is the same between the two systems.

This approach combines some of the advantages and disadvantages of the other two approaches. On the positive side, there is only one set of source to maintain. There is less programming than the dual code approach, but you aren't forced into the simplified user interface typically required by the single interface approach. You can customize the user interface to take advantage of features found on a graphical system without making the character-based version unmanageable.

The biggest disadvantage is that you must write two user interfaces. While this is less work than writing two separate programs, it is still a significant amount of work. In addition, you must test the user interface code more thoroughly than with the single interface approach, because only half of the interface code is exercised on any one type of system.

Parent topic: Strategies for Supporting Multiple Systems


Selecting the Right Approach

Each of these approaches has its merits. One thing to remember is that you can mix the approaches. Mixing approaches can be quite useful in a large project. Imagine a standard accounting package. In it, you might use the dual code method to handle the main menu of the package. For example, the graphical version might display a nice graphic and use the system's menu bar to initiate the subsidiary applications. The character version might instead display the menu as the main contents of the opening screen since it can't show a graphical image. Parts of the application that perform maintenance of minor files (such as shipping codes and user passwords) or entry of report parameters, might use the single interface approach because the screens are simple. Finally the key transaction entry screens (such as an order entry screen) might use the dual interface, single code approach to ensure that the screens work well for the respective systems while also ensuring that the entered data is handled the same way by both systems.

You can even mix approaches inside a single program, or even a single screen. You might have most of a screen use the single interface approach, while a small portion of it is customized by using the dual interface technique.

You do not need any special tools to use the dual interface, dual code approach (although a good source-code control system always helps). For the two single code approaches, ACUCOBOL-GT has special features to simplify use of the single interface and dual interface methods. The topics in this section discuss these features and when you might use them.

Parent topic: Strategies for Supporting Multiple Systems


Determining Which UI is Running

To determine whether the user interface to your program is running through the Windows run-time, or the thin client, you can add ACCEPT TERMINAL-ABILITIES FROM TERMINAL-INFO to your program. (TERMINAL-ABILITIES is defined in the sample/def/acucobol.def copybook.) The TERMINAL-NAME field that is returned contains a short descriptive name of the terminal type being used. If the Windows run-time or thin client is being used, the TERMINAL-NAME contains the string Windows.

If you are maintaining separate screen sections for these environments, this could be useful for determining which screen section or routine to use at any given moment. For example, you might include the following code in your program:

accept TERMINAL-ABILITIES from TERMINAL-INFO
     If terminal-name = Windows
     display screen1a

terminal-name is defined as an 03 data-item under the 01 TERMINAL-ABILITIES.

The IS-REMOTE field is set to true if the program is running with thin client. When IS-REMOTE is true, CLIENT-MACHINE-NAME is set to the name of the client that is running thin client, plus a hyphen (-) and the hex value of the client process ID. For example:

techxp-2ef1
Parent topic: Strategies for Supporting Multiple Systems


Tips for Solving Cross-Platform Interface Problems

This section of the help describes how to use selected features of ACUCOBOL-GT to solve common problems encountered when developing programs to run on both character and graphical systems.

  • Establishing the Initial Window
  • Tips for Building Single-interface Programs
  • Tips for Building Dual-interface Programs
Parent topic: Creating Portable User Interfaces


Establishing the Initial Window

One of the most important things that you can do when implementing a user interface that includes graphical controls is establish the program's main application window correctly. By default, ACUCOBOL-GT will construct a main application window for you. However, this window is designed to run traditional, text-based COBOL programs and not programs with graphical controls. The run-time does this so that it can run older ACUCOBOL programs unchanged. If you plan to use graphical controls, it is very important that you do not use the default window. Instead you should explicitly create your window. There are two reasons why this is so important:

  1. It gives you an opportunity to account for the height difference between character-based entry fields and graphical entry fields. How to do this is described below.
  2. It ensures that your program will look right when run under various Windows machines using different resolutions. If you use the default, you risk having your program look wrong when run under some Windows configurations. The reason for this is that the standard fonts used at higher resolutions are often not the ones supplied by Microsoft. Instead, they come from the video card manufacturer. Sometimes, the relative proportions of the standard fonts are changed from those seen in the Microsoft fonts.
  3. Since the run-time's default window uses the FIXED-FONT to measure lines and columns, but your controls usually use some other font (such as the DEFAULT-FONT) to determine their size, a change in proportion between these two fonts causes the screen to change. This can result in overlapping controls and other problems. This is not a bug, but an effect of the changing environment. By establishing your initial window correctly, you can use the same font to position controls as you use to size the controls. Then, regardless of the size of this font, your whole application will scale itself proportionally and look fine.

Format 12 of the DISPLAY verb is used to create the main application window. See DISPLAY Statement for the rules that govern its use. See Coordinates for a more detailed discussion of coordinate space issues. Here are a few suggestions for handling the most common situations for graphical programs:

  1. Use DISPLAY STANDARD GRAPHICAL WINDOW. The GRAPHICAL phrase ensures that the default font used for controls is also used to determine lines and columns in the window.
  2. If boxed entry fields are going to be a major element of the window, then use the following statement:
    DISPLAY STANDARD GRAPHICAL WINDOW,
    CELL SIZE = ENTRY-FIELD FONT, SEPARATE
  3. You can substitute OVERLAPPED for SEPARATE if you prefer. This statement also works well if vertically stacked push buttons are a major component of the screen (push buttons require about 1.5 lines each, just like boxed entry fields).
  4. If you plan to use a font other than DEFAULT-FONT as your primary font, name it as the CONTROL FONT. For example:
    77  LARGE-FONT  USAGE HANDLE OF FONT.
ACCEPT LARGE-FONT FROM
    STANDARD OBJECT "LARGE-FONT"
DISPLAY STANDARD GRAPHICAL WINDOW
    CONTROL FONT IS LARGE-FONT
    CELL SIZE = ENTRY-FIELD FONT, SEPARATE

There are many other options you can add to the DISPLAY STANDARD WINDOW statement, including the ability to set the window's size. The preceding suggestions just cover the basics of establishing the measuring font.

If you follow suggestion number two above, then you should find that you can place labels and entry fields on whole line numbers and have them show up nicely spaced under both character and graphical systems. Because the line height is determined by the height of a boxed entry field, each line is exactly big enough to hold one entire entry field. This solves the problem where entry fields are 50% taller on graphical systems than they are on character systems.

An alternative solution is to avoid using boxes with entry fields on graphical systems. You can do this very easily by using the FIELDS_UNBOXED configuration option. However, while this solution is very easy, it has two problems. One is that the results look a little out of place under Windows, where boxed fields are the norm. The other problem is that unboxed entry fields are used so infrequently under Windows that the underlying Windows code is not well exercised. Occasionally you will see slightly odd behavior with unboxed entry fields under Windows (for example, leaving a stray pixel turned on when it should be erased during editing).

Parent topic: Tips for Solving Cross-Platform Interface Problems


Tips for Building Single-interface Programs

Here are some ideas for simplifying the task of supporting a single user interface on both character and graphical systems:

  1. If you plan to use the bar, scroll bar, tab, or bitmap controls for your graphical programs, make sure you program alternatives for the character-based systems (in other words, build a dual-interface program for these elements).
  2. Make sure you establish a sensible cell size. This is the only way you can hope to have a single set of coordinates describe screens that look good under both character and graphical systems.
  3. Provide plenty of space between elements on the same line. Items that appear to be nicely separated on a graphical system may well overlap under a character-based system. This occurs because the labels and control titles are narrower on a graphical system due to the nature of the proportional font used.
  4. If you use frames, design them on the graphical system. The run-time automatically grows frames as needed on character-based systems to surround the contained controls.
  5. In general, try to keep the screens simple. The more complex they are, the harder it is to achieve a nice look under both types of systems.
  6. Try to use a single size font under the graphical system. The character system has only one size, so you can get more uniform results if you do the same under graphical systems.
  7. For cases where you cannot get a nice look under both systems using a single set of coordinates, use the CLINE, CCOL, CSIZE and CLINES options. These allow you to specify alternate coordinates and dimensions for character-based systems. This lets you customize the placement of screen elements for both graphical and character systems, giving you finer control. See The Character Coordinate Phrases for more information about these phrases.
Parent topic: Tips for Solving Cross-Platform Interface Problems


Tips for Building Dual-interface Programs

The key to building dual-interface programs is being able to determine which kind of system you are using. ACUCOBOL-GT provides two methods to accomplish this:

  1. You can determine whether you are running under a character or graphical system by using the ACCEPT FROM TERMINAL-INFO verb. The HAS-GRAPHICAL-INTERFACE field is true when the host system is graphical, otherwise it is false. You can also use the WIN$VERSION library routine to get more detailed information about the Windows host operating system.
  2. In the Screen Section, you can automate the detection of character and graphical systems with the CHARACTER and GRAPHICAL reserved word labels to indicate entries that apply to only one system. See Graphical vs Textual Modes for more information.

You have a great deal of flexibility in how you implement dual interface programs. On one extreme, you can have completely separate interfaces for character and graphical systems. On the other, you can have a uniform interface with only minor differences between them. Here are some ideas to consider:

  1. If you are happy with your existing character interface, you may want to leave it alone and simply develop a new graphical interface. You could either start from scratch, or use your existing character interface as a starting point. If you decide to have completely separate interfaces, then you should start by isolating your character interface into one branch of an IF statement that tests HAS-GRAPHICAL-INTERFACE. You then develop the graphical interface in the other branch. Exactly the best way to do this depends on the structure of your code.
  2. If your existing character interface does not use the Screen Section, consider using the Screen Section for the graphical interface. While using the Screen Section is not required, it is easier because it automates all of the mouse handling and transfer of control between screen fields.
  3. If you do use the Screen Section for your character interface, you can use the CHARACTER and GRAPHICAL reserved word labels to do customization. You could do this either globally, by creating separate level 01 screen items for each system, or individually on selected fields. Note that you may have two screen items with the same name, as long as one is a CHARACTER item and the other is a GRAPHICAL item. This allows you to have a single set of interface code in the Procedure Division while still coding different screens.
  4. Consider employing some of the tips from the single-interface model. The more similar your two interfaces are, the easier they are to maintain.
Parent topic: Tips for Solving Cross-Platform Interface Problems


GUI Development Project Issues

For many COBOL programmers, graphical user interfaces, GUI environments, and GUI programming are new territory. Enhancing or adding a graphical user interface to an existing COBOL program raises many questions and issues. Before you begin, we recommend that you thoroughly consider the following basic questions:

  1. To what extent will the program's interface change?
  2. How suitable is the current interface to conversion?
  3. What resources are needed for the project?
  • Extent of the Interface Changes
  • Suitability of the Current UI to Conversion
  • Recommendations
  • Conversion Wizard
Parent topic: Introduction


Extent of the Interface Changes

There is no simple formula for defining a good specification for a modernized user interface. The special needs of your application, the demands of your marketplace, and the resources of your business will combine to define a practical GUI specification. In this process we recommend that you explore the full range of options available to you, from the small, selective update, to a full reimplementation project.

We recommend that you consider a phased update approach to spread the cost and risk of changing the user interface (UI) over a longer period of time. Remember that ACUCOBOL-GT can support a mix of graphic and character-based screens. The phased approach gives you more time to learn GUI technology in general, and ACUCOBOL-GT GUI support in particular.

Don't forget to develop a test plan. Any significant changes to the UI will require careful testing. You may want some end users to help with testing and evaluation. Be sure to include your test plan in the project schedule and staffing estimates.

Parent topic: GUI Development Project Issues


Suitability of the Current UI to Conversion

A careful study of your application's existing user interface implementation can make a huge difference in ensuring the success of your project and holding down costs. When it comes to modernizing the user interface, some programs are better suited and less costly to update than others. Here are some qualities to consider:

  • The easiest applications to convert tend to be those that already use the Screen Section.
  • The most difficult programs to convert tend to be those in which the user interface code is dispersed throughout the program, that is, programs that do not use the Screen Section, or do not organize screen processing code into separate procedures. If your application fits that description and you are going to undertake a large GUI upgrade project, it is nearly certain that it will be more efficient to implement your new user interface with the Screen Section. Also consider that Screen Section code is much easier to maintain over the life of the application than is distributed UI DISPLAY and ACCEPT code. A large enhancement project presents a good opportunity to move to the Screen Section.
  • However, if you're doing a small enhancement project that is confined to a small portion of your code, using individual DISPLAY statements to create and process your screen elements might be reasonable.
  • Programs that already include a menu bar, the old-style character-based pop-up windows (subwindows), and support for the mouse, are well on their way to a modern user interface. These elements are easy to upgrade and enhance to take advantage of ACUCOBOL-GT GUI support. Note, however, that just because an application already includes this functionality does not mean that there won't be substantial work in adding floating windows and controls.
  • Evaluate your existing, character-based user interface screens for translatability into the graphical model. Many text-mode screens make dense use of the screen. In contrast, graphical screens tend to be more open, having more white space and fewer fields. Also, graphical objects tend to take up more space on the screen than their equivalent text-mode objects (mostly due to the boxes used to frame controls). It may require a lot of work to reformulate your character screens into attractive, functional graphical screens. This problem is just as challenging for applications that already make use of pop-up windows and menu-bars as for those that don't.
Parent topic: GUI Development Project Issues


Recommendations

  • Implement your GUI in the Screen Section.
  • To control the size and cost of your project, execute it in phases.
  • If suitable, allow a mix of character-based and GUI screens (that is, add new graphical screens and retain some of your existing text-mode screens).
  • Redesign your screens to make them less crowded and more consistent with the established look of the GUI environment.
  • Whenever possible, use the Acucorp workbench to design and prototype screens quickly.
  • Formulate a test plan and allocate time to execute it.
Parent topic: GUI Development Project Issues


Conversion Wizard

In an effort to reduce the amount of work required to convert a traditional text-based application into one that uses a graphical user interface, Acucorp has developed a screen conversion tool known as the Character-to-GUI Wizard. The tool works by watching a running character application and, at a specified point, constructing an equivalent graphical screen. This screen is then automatically imported into the AcuBench Screen Designer where you can make modifications to it as desired. AcuBench then produces a Screen Section description of the graphical screen that you can integrate back into your original program. Because it requires the AcuBench Screen Designer, the Character-to-GUI Wizard is only available on Windows platforms.

The Character-to-GUI Wizard is designed to work with any character screen that you have created using ACUCOBOL-GT syntax. This allows it to work with most existing character-based programs. Note that the wizard works with programs using either of ACUCOBOL-GT's two main screen handling techniques: the Screen Section and inline ACCEPT/DISPLAY statements. Although the wizard uses a variety of heuristics to decide how to convert the code, these do not always produce the desired result, and some rework in the Screen Designer should be expected. For usage information on the Character-to-GUI Wizard, please refer to the AcuBench User's Guide.

Parent topic: GUI Development Project Issues


Sample Programs

The ACUCOBOL-GT release materials include many sample programs and their source code. Many of these programs demonstrate ACUCOBOL-GT's GUI capabilities. We recommend that you study the source code for these programs to gain a better understanding of how ACUCOBOL-GT GUI objects are programmed. You can find these programs and their source code in the %PUBLIC%\Documents\Micro Focus\extend x.x.x\sample directory.

Included among the sample programs is a program called "message." This program provides basic message-box support on any host. The message program calls the host operating system's message box handler when one is available. Otherwise the run-time provides a simulated, character-based message box. See the comments in the program source for additional details.

Parent topic: Introduction


Floating Windows

  • Overview of Floating Windows
  • Relationship Between Floating Windows and Subwindows
  • Active and Current Windows
  • Parent and Child Windows
  • Creating, Inquiring, Modifying, and Destroying Windows
  • Menus and Floating Windows
Parent topic: ACUCOBOL-GT User Interface Programming


Overview of Floating Windows

ACUCOBOL-GT includes a class of graphical windows called floating windows. When run under a graphical environment, floating windows correspond to the graphical windows that are native to the host environment. On character-based systems, floating windows are emulated with text-mode elements and are managed directly by the ACUCOBOL-GT runtime system.

Note: Independent windows are similar to floating windows. The following characteristics also apply to independent windows unless otherwise noted.

The primary characteristics of a floating window are:

  1. It is either modal or modeless (see below)
  2. It pops up over its parent window (usually the main application window) and is always displayed over the parent window wherever they intersect
  3. It can be moved independently of the parent window and is able to leave the area described by the parent window. The user can move it directly with the mouse, without any program interaction
  4. It belongs to the parent window. If the parent window is minimized, it is too. (Independent windows do not belong to parent windows; independent windows are considered siblings of parent windows. They can be minimized or maximized without controlling the parent window.)
  5. It may have a system menu associated with it that allows the user to select some basic operations on the window, such as moving or closing it

The main application window is treated as a special-case floating window that has no parent window.

Floating windows may be either modal or modeless. A modal window is a window that the user cannot leave until it is dealt with and closed. When a modal window is active, all other windows are disabled.

A modeless window is one that allows the user to switch among windows while allowing each modeless window to remain open and available. When a modeless window is active, the user can activate another window using the host system's techniques for doing so (for example, by clicking on the window with the mouse).

The names modal and modeless are derived from the idea that a modal window enters a new mode in the program (for example, selecting a file to open), while a modeless window does not (since the user can continue working on tasks in other windows).

Floating windows are modal by default. The MODAL phrase may be included as commentary. Inclusion of the MODELESS phrase makes a window modeless.

Parent topic: Floating Windows


Relationship Between Floating Windows and Subwindows

In graphical environments, every floating window has an implicit subwindow (and can have more than one if you create pop-up subwindows). This implicit subwindow is a region of the floating window. It cannot exist outside of the floating window, cannot cross the border of the floating window, and cannot be moved independent of the floating window. In essence, it is a viewing region in the active floating window.

Therefore, under graphical systems, the application always has two active windows: its active floating window and its implicit subwindow. When you create a new floating window, it starts off with a default subwindow that covers its entire interior (client area). You do not display directly to the floating window, but instead to its subwindow. A subwindow's coordinates (and thus the program's coordinates) are always relative to the floating window to which it belongs.

If you close a floating window, any subwindows associated with it are also destroyed.

Parent topic: Floating Windows


Active and Current Windows

A floating window may be active. The active window is the window that the user's input goes to (also referred to as the window that has focus). This active window is usually highlighted in some way. For example, under Microsoft Windows NT, the active window is shown in the color scheme defined in the Appearance tab of the Display Properties dialog box.

A floating window may also be current. The current window is the window that the application uses whenever it does not explicitly refer to a window (essentially, it is the default window). The current window is the window to which output is directed. The current window is usually the same as the active window, but it need not be. For example, if the application wants to display some text in an inactive window, it would make that window the current window and display text to it. Note that changing the current window does not affect the input focus of the active window.

You can use the UPON phrase of the DISPLAY statement to temporarily change the current window. You can also use the SET verb to change the current window. For more information about the UPON Phrase, see Common Screen Options in the Reference Manual. For a complete description of the SET Statement, see Procedure Division Statements in the Reference Manual.

Any time you execute an ACCEPT verb that retrieves input from the user, the first thing that happens is that the run-time system makes the active window current. This ensures that the program is referring to the same window that the user is using to enter data.

When a floating window is first created, it is made both the active and current window. When a window is destroyed, the first applicable rule applies:

  1. If the destroyed window was active, its parent window is made both current and active.
  2. If the destroyed window was current, its parent window is made current.
  3. Otherwise, the current and active windows remain unchanged.

Except for the main application window, all windows have a parent window.

Parent topic: Floating Windows


Parent and Child Windows

Except for the main application window, each floating window has a parent window. The parent of a window is typically the current window at the time the new window is created. For example, if the application starts off by creating two floating windows in a row, the parent of the first window will be the main application window, while the parent of the second window will be the first window.

The converse of a parent window is a child window. If window A is window B's parent, then window B is window A's child.

Windows are considered siblings if they have the same parent.

A floating window always displays over its parent wherever they intersect on the screen. This is true even when the parent window is the current window. An active window will always display over any of its siblings.

If you destroy a floating window, all of its children are also destroyed.

Parent topic: Floating Windows


Creating, Inquiring, Modifying, and Destroying Windows

You create a floating window with the DISPLAY FLOATING WINDOW statement. This statement constructs the specified window and returns a handle to it. A window created with the above statement is modal by default (the MODAL phrase can be added as commentary). To create a modeless window, you can add the MODELESS phrase. Note that managing multiple modeless windows is greatly simplified by associating a separate thread with each modeless window. See Multiple Execution Threads for more informaqtion.

The program's initial window, or main application window, is created either automatically, via the run-time system, or programmatically via the DISPLAY INITIAL WINDOW statement. If the first DISPLAY statement is not a DISPLAY INITIAL WINDOW (or DISPLAY STANDARD WINDOW statement), the run-time system automatically creates the initial window. The main application window is always a modeless window.

Because floating windows can be moved and, optionally, resized, their position and size are dynamic. To retrieve the current position and size of a floating window, you use the INQUIRE verb. INQUIRE returns information for the current window or the window identified by the specified handle.

To programmatically reposition or change the size or title of a window, you use the MODIFY verb. The MODIFY statement applies the specified values to the window identified by the handle or, if omitted, the current floating window.

Windows have a property called ACTION that can be used in DISPLAY and MODIFY statements. The ACTION property allows you to programmatically maximize, minimize, or restore a window. To use ACTION, assign it one of the following values (these names are found in acugui.def):

  • ACTION-MAXIMIZE

    Maximizes the window. It has the same effect as if the user clicked the maximize button. Allowed only for windows that have RESIZABLE or AUTO-RESIZE specified or implied for them. In windows with RESIZABLE specified, when ACTION-MAXIMIZE causes the window to change size, an NTF-RESIZED event occurs. (This event does not occur, however, if AUTO-RESIZE is specified.)

  • ACTION-MINIMIZE

    Minimizes the window. It has the same effect as if the user clicked the minimize button. Allowed only for windows that have RESIZABLE or AUTO-RESIZE specified or implied for them.

  • ACTION-RESTORE

    If the window is currently maximized or minimized, restores the window to its previous size and position; otherwise, it has no effect. It has the same effect as if the user selected Restore from the menu. Allowed only for windows that can be maximized or minimized. In windows with RESIZABLE specified, and when ACTION-MAXIMIZE has caused the window to change size, an NTF-RESIZED event occurs when ACTION-RESTORE is used. (This event does not occur, however, if AUTO-RESIZE is specified.)

If you assign an ACTION value that is not allowed, there is no effect other than to trigger the ON EXCEPTION phrase of the MODIFY statement (if present). Note that you can use the ACTION phrase to create a window that is initially maximized or minimized.

You destroy a floating window with either the CLOSE WINDOW statement or DESTROY verb. You specify the handle of the window you want to destroy. Both verbs behave identically when acting on floating windows. You cannot destroy the main application window. It is closed automatically when the application terminates.

See Procedure Division Statements for a complete description of each of the above verbs. See Screen Description Entry for detailed information regarding creating and managing floating windows via the Screen Section.

Parent topic: Floating Windows
Parent topic: Graphical Controls


Menus and Floating Windows

You can create and attach a menu bar to any floating window. The menu bar is created and maintained with the methods described in Menus Overview. Note that when a floating window is created, its menu, if present, is the only menu available as long as that floating window is the active window. Menus in other windows are disabled.

The library routine W$MENU is used to create and control the menu bar. When you call W$MENU, and the routine has to resolve which window to apply its actions to, it assumes the current window. With the following operations, you can specify a particular window by passing the target window's handle as a parameter in the position noted below.

WMENU-SHOW           --3rd parameter
WMENU-GET-HANDLE     --2nd parameter

If you have a floating window displayed, and you want to update the menu in the main application window, you must specify the handle of the main application window in the call to WMENU-SHOW. For example:

DISPLAY INITIAL WINDOW, HANDLE MAIN-WINDOW
PERFORM BUILD-MAIN-MENU
CALL "W$MENU" USING WMENU-SHOW, MENU-HANDLE
  .
  .
DISPLAY FLOATING WINDOW ...
  .
  .
PERFORM CHANGE-MAIN-MENU
CALL "W$MENU"
      USING WMENU-SHOW, MENU-HANDLE, MAIN-WINDOW
Note: Microsoft Windows does not display menus correctly in floating windows that have thick borders (that is, BOXED floating windows). As a matter of style, Windows applications never display menus in windows with this border type (this style is normally used for dialog boxes). If you want to put a menu in a floating window, you must not use the BOXED style when you create the window. For an example of a floating window with a menu, see the ACUCOBOL-GT debugger screen.
Parent topic: Floating Windows


Graphical Controls

  • Overview of Graphical Controls
  • Control Types Handles and IDs
  • Interaction Between Controls and Windows
  • Creating, Inquiring, Modifying, and Destroying Windows
  • The Character Coordinate Phrases
  • Controls and the Mouse
  • Bitmap Buttons
  • Paged List Boxes
  • Paged Grids
Parent topic: ACUCOBOL-GT User Interface Programming


Overview of Graphical Controls

ACUCOBOL-GT allows you to create, display, and process graphical controls. Graphical controls are also commonly called graphical objects or widgets. Some examples of common graphical controls include push buttons, list boxes, radio buttons, check boxes, and entry fields (text entry boxes). ACUCOBOL-GT provides a consistent method for specifying and handling graphical controls. Several common control types are supported. Future versions of ACUCOBOL-GT may incorporate additional control types.

Graphical controls have several important components:

  1. Each control has an underlying type, such as push button or check box (this is also called the control's class). See Control Types Handles and IDs for a list of control types.
  2. Each control has a handle that uniquely distinguishes the control. Handles are also discussed in the Control Types Handles and IDs.
  3. Each control has a set of common properties defined for it. These common properties are described in Common Screen Options.

    Common properties that apply to virtually all controls include:

    location | Each control has a screen location. The location is given as row and column coordinates that specify the position of the upper left-hand corner of the control on the screen. The character coordinate phrases CLINE and CCOL can be used to specify an alternate control location for use on a non-graphical system.
    size | Controls have size information. The size information is given as width and height. The exact meaning of the width and height depends on the control type. Some control types have a predefined size (in one or both dimensions). The character coordinate phrases CSIZE and CLINES can be used to specify an alternate control size for use on a non-graphical system. Controls can also be given minimum and maximum size specifications. This is useful if you want to change the size of a control when the window changes size. Layout managers frequently use this information. See Layout Managers for more information.
    titles | Controls can have titles. This usually appears as a text label attached to the control. Examples include the text on a push button or the text beside a check box. Some controls, such as entry fields, do not use titles.
    value | A control also has a value. The value of a control is the user-modifiable portion of that control. For an entry field, this is the text entered into the box. For check boxes, the value is whether the box is checked or not. Some controls, such as push buttons, do not have values. The exact range of values allowed is determined by the control type.
    color | Controls have color. Both foreground and background colors apply. The exact meaning of the color information depends on the control type. Some controls or host systems may limit the choice of colors.
    font | Most controls have a font that is used when text is displayed in conjunction with the control.
    event lists | For any control that generates events, you can create an event list that specifies for that control the types of events that must be received or filtered out.
    styles | Controls also have style properties. Style properties typically affect the visual presentation of the control. For example, a push button may be assigned the DEFAULT style, which causes the push button to be drawn with a thick border to indicate that it is the default action.
    Note: Styles do not take a value. They are either applied (on), or not applied (off).

    Some styles apply to all controls. However, each control has its own additional styles. Each style is described in Control Types Reference.

    Certain Operating System styles or themes have an effect on the appearance of controls. For details on how ACUCOBOL-GT applications behave when certain styles are in effect, see Visual Styles and Differences Among Operating Systems.

    There are also common properties that determine whether a control is displayed (VISIBLE), whether a control will respond to the user (ENABLED), or whether a control has a key letter that the user can use to activate the control with the keyboard (KEY).

  4. In addition to the common properties, each control defines its own set of special properties. These special properties give the control a special attribute or capability. Special properties are specified with the PROPERTY and Property-Name phrases of the DISPLAY Control-Type statement. See Common Screen Options in the ACUCOBOL-GT Reference Manual for more informtion. For a list of each control's special properties, see Control Types Reference.
  5. ActiveX and .NET controls define their own set of methods. Methods (or object methods) specify the functions that the control provides. They are invoked using the MODIFY verb, and they can take any number of parameters or no parameters. ActiveX controls can also take optional parameters (that is, parameters that can be omitted). For more information, see Methods.

Rather than using a unique syntax to define each control type, ACUCOBOL-GT provides a generic method for specifying a control's characteristics. The programmer then selects the attributes that are applicable to each desired control.

  • Visual Styles and Differences Among Operating Systems
Parent topic: Graphical Controls


Visual Styles and Differences Among Operating Systems

Controls can have different visual styling or themes on certain Windows operating systems such as XP and Vista. By default ACUCOBOL-GT applications will automatically employ the latest styling that is set on the workstation (via the Windows Control Panel Display options). You can modify the various styling control through the run-time configuration variables WIN32_NATIVECTLS and WIN32_3D , which are described in the ACUCOBOL-GT Appendices Guide, Appendix H.

A control's internal behavior may be different with various operating systems. In Windows systems, some configuration variables have no effect on the control's behavior. On the other hand, in character-based systems, controls are defined using the run-time's configuration file and editing capabilities. For example, the following configuration file entry causes Function Key 7 to erase the contents of an entry field under UNIX, but not under Windows:

KEYSTROKE Edit=Erase-field k7
Parent topic: Overview of Graphical Controls


Control Types Handles and IDs

Each control belongs to a particular type. The compiler knows the following type names:

ACTIVE-X | BAR
BITMAP | CHECK-BOX
COMBO-BOX | DATE-ENTRY
ENTRY-FIELD | FRAME
GRID | LABEL
LIST-BOX | .NET
PUSH-BUTTON | RADIO-BUTTON
SCROLL-BAR | STATUS-BAR
TAB | TREE-VIEW
WEB-BROWSER |

Control type names are reserved by the compiler.

When you create a control, a handle to the control is also created. This handle is a COBOL data item that uniquely identifies the control to the system. The handle values are generated dynamically by the system at runtime and cannot be controlled by the programmer.

To provide a constant name for the control that is the same between runs, you can optionally assign an ID to the control. The ID is a programmer assigned number. Anytime the runtime returns information about a control, it includes both its handle and its ID. Since the handle can change from run to run, examining the ID can be more convenient. A control's ID is the only effective way to distinguish controls in a Screen Section because those controls' handles are hidden from the programmer.

Parent topic: Graphical Controls


Interaction Between Controls and Windows

A control always belongs to a particular floating window and cannot be displayed outside that window (however, some controls, such as combo boxes, can temporarily pop up information outside of the floating window). Like all screen elements, controls are positioned relative to the current subwindow. When you destroy a floating window, all controls that belong to that window are also destroyed.

Controls and pop-up subwindows do not interact well on some systems. The reason for this is that graphical controls are native elements of the host system, while subwindows are a text-only construct created by the ACUCOBOL-GT runtime system. Because the host graphical system is not aware of ACUCOBOL-GT subwindows, the system unwittingly displays controls over subwindows. Unfortunately, such host systems do not have support for a construct similar to ACUCOBOL-GT's subwindows, so the subwindows must be managed directly by the runtime system.

To avoid problems, you should not use controls in any location that may intersect with a subwindow. If you are updating an existing program to use controls, you should start by converting any subwindows to floating windows. Floating windows interact correctly with controls, and have the added benefit of having generally better functionality (for example, the user can move them with the mouse).

Windows that have the AUTO-RESIZE or RESIZABLE attribute may be dynamically resized by the user. Unless the program specifically handles it, the size and position of the controls in the window remain unchanged. If the window also has the CONTROLS-UNCROPPED attribute, controls that had been invisible or partially invisible because they were positioned on or outside the visible bounds of the windows, may become visible. If the user tabs to a control outside of the visible area, the run-time will scroll the window in order to make that control visible. To make it easier for programmers to resize and reposition controls in a resizeable window, ACUCOBOL-GT provides a layout manager facility. A layout manager is a piece of software that manages the size and placement of controls in a particular window. See Layout Managers for more information about layout managers.

Parent topic: Graphical Controls


The Character Coordinate Phrases

In contexts where you can specify LINE, COL, SIZE, or LINES for a control, you may additionally specify CLINE, CCOL, CSIZE, and CLINES (respectively). These phrases let you specify alternate coordinates and dimensions for controls when they are displayed on text-mode systems. The CLINE, CCOL, CSIZE, and CLINES phrases are collectively called the character coordinate phrases. They behave in all ways like their corresponding counterparts, except that they are applied only when the program executes in a text-mode environment.

Because of the physical differences between graphical and non-graphical systems, getting a single screen description to look good on both types of systems is challenging. Sometimes, the best way to account for these physical differences is to use alternate coordinates or dimensions for some screen elements. The CLINE, CCOL, CSIZE, and CLINES phrases allow you to do this easily.

You specify the character coordinate phrases in exactly the same fashion as their regular counterparts (that is, CLINE is similar to LINE, CCOL to COL, and so on). All of the syntax supported by one phrase works in the corresponding phrase. For example, a Screen Section item that has a twin set of column offsets is:

03 entry-field, col + 2, ccol + 1, ...

When run on a graphical host system, the character coordinate phrases have no effect (although in some contexts the values are evaluated, so any relevant table indexes should be set to legal values to prevent access violations). When run on a character-based host, the character coordinate phrases substitute for their graphical counterparts. For example, if you specify both LINE and CLINE for a control, the CLINE specification is used as the line number on a character-based system. Omitting a character coordinate phrase causes the regular counterpart to be used instead. This means that you need to specify character coordinate phrases only for those aspects of the control that must be different between graphical and character-based hosts.

If you specify the CELLS option in either the SIZE or CSIZE phrase, then you must use the CELLS option in both phrases. The same rule applies to the CELLS option of the LINES and CLINES phrases. This rule is necessary because the CELLS option asserts a particular style attribute for the control, and styles work the same under both graphical and character-based systems.

Parent topic: Graphical Controls


Controls and the Mouse

Controls are implemented as small child windows. These windows do not look like normal application windows. Instead, they define a rectangular region of the application window that holds the control. In this sense, they are similar to subwindows. The difference is that these child windows are maintained by the host graphical system.

In the general model for graphical user interfaces, the system directs events to the window where the event occurred. This window owns the event. The effect of this is most noticeable when you examine what happens when controls interact with the mouse. As the mouse moves across the application screen, the various windows that the pointer passes over each receive the appropriate events. If you look at an application screen that has several controls, the application window receives those mouse events that occur when the pointer is in the application window, but not over any of the controls. When the mouse pointer is over a control, that control receives the mouse events.

This means that the setting of the runtime configuration variable MOUSE_FLAGS affects the behavior of the mouse only when it is not over a control. When the mouse is over a control, that control does its own mouse processing.

If you need to process the mouse while it is over a control, there are two options:

  • You can capture the mouse using the CAPTURE-MOUSE option of the W$MOUSE library routine. When the mouse is captured, all mouse events are directed to the current application window, even those that occur outside of the window altogether. It is advisable to capture the mouse only for short periods of time, because capturing the mouse prevents all other applications from using the mouse. Normally you capture the mouse to handle a user-initiated action such as dragging a screen object from one location to another.
  • You can disable the control. Disabled controls cannot receive input, so any associated mouse actions are directed to the owning application instead. To disable a control, use the ENABLED phrase of the Screen Section, DISPLAY, or MODIFY statements. See Common Screen Options for more information about the ENABLED phrase.
Note: It is rare that your program would need to manage the mouse directly. In most cases, controls manage their own mouse messages without any intervention by the program.
Parent topic: Graphical Controls


Bitmap Buttons

This section describes how to create bitmap buttons. A bitmap button is a push button, check box, or radio button that looks like a push button, but with a picture on its face instead of the usual text. Bitmap buttons are frequently grouped together to form a toolbar. A bitmap button that is a check box or radio button appears to be depressed when it has a non-zero value (is selected, or on). It appears to be raised when its value is zero (is not selected, or off).

Creating a bitmap button is a multi-step process. It helps to be familiar with programming regular push buttons before you attempt to program a bitmap button. To create a bitmap button you must complete the following steps:

  1. Create the bitmap image with a paint application.
  2. Update your program to load the bitmap into memory.
  3. Update your program to create the button and specify the bitmap image to apply to the button.

These steps are detailed in the sections that follow.

  • Drawing the Image
  • Loading Bitmaps
  • Creating the Button
  • Pop-up Hints
  • Portability
Parent topic: Graphical Controls


Drawing the Image

You create the bitmap image with a paint tool. This tool is host-system dependent, as are the images it creates. Under Microsoft Windows, you can use the Paint program that is bundled with Windows. For most bitmap buttons, you will want to use the zoom mode of the paint program to make it easier to adjust the individual pixels.

You create your bitmap as a strip that contains one or more bitmap button faces. For example, the following bitmap image contains 15 button faces:

You can use more than one bitmap image strip in your program; however, the run-time is more efficient when it pulls multiple images from the same strip. In addition, it is usually more convenient to store multiple images in a single file rather than several small files. Note that all images in a particular strip must be the same size.

When you design the image, the first thing you need to do is to settle on the size of the image. The default size under Windows is 15 pixels high by 16 pixels wide. However, you can use any size you want. Note that the bitmap size is the size of the button's image. To accommodate the button's border, the actual button will be somewhat larger. Under Windows, eight pixels are added to the width and seven pixels are added to the height (so the default button size is 24 pixels wide by 22 pixels high). The first thing you should do in the bitmap editor is set the dimensions of the bitmap to the desired size. For example, a strip of six default-size buttons would have an image size 15 pixels high by 96 pixels wide (6 * 16 = 96).

When you draw a strip that contains multiple images, make sure that each image starts on a boundary that is a multiple of the image size. In the default case, your images should start at offset 0, 16, 32, and so on (that is, pixel numbers 1, 17, 33, and so on).

Under Windows, certain colors that you use in the bitmap will be mapped to colors chosen by the user in the Control Panel. This mapping allows you to create buttons that will have the same color scheme as the text-labeled buttons on the screen. The following table names the bitmap colors that are translated, as well as their RGB (red, green, blue) values and the system color that they are translated to.

Bitmap Color | RGB Values | System Color Used
Black | 0, 0, 0 | Button Text
Dark gray | 128, 128, 128 | Button Shadow
Light Gray | 192, 192, 192 | Button Face
White | 255, 255, 255 | Button Highlight
Blue | 0, 0, 255 | Selected Item Background
Magenta | 255, 0, 255 | Window Background

None of the other colors are translated.

It is best to use light gray as your primary background color. This color ensures that the button's edges (which are supplied by the run-time) blend in correctly.

Note: The color transformation described above occurs only for bitmaps stored in 16-color or 256-color format. Bitmaps stored in 24-bit format (true color) do not contain an internal palette. As a result, there is no efficient way of performing the transformation described above. Bitmaps in 24-bit format will be displayed with their colors unchanged.

Once you have finished creating the bitmap, save it as a file. Under Windows, you may use files in JPEG format as well as BMP. Once loaded, JPEG files can be used in any context that BMP files may be used with no code changes. The recognizable extensions for JPEG files are JPE, JPEG, and JPG. See Loading Bitmaps for important information related to JPEG support.

Parent topic: Bitmap Buttons


Loading Bitmaps

In your program, you must load bitmap images (BMP or JPG) from disk into memory before they can be displayed as buttons. To load a bitmap, you must use the WBITMAP-LOAD operation of the W$BITMAP library routine. The call looks like this:

CALL "W$BITMAP" USING WBITMAP-LOAD, filename
   GIVING bitmap-handle

where filename is a literal or data item that holds the name of the bitmap file to load, and bitmap-handle is a PIC 9(9) COMP-4 data item. This call opens the filename file, loads the bitmap into memory and closes the file. If the operation is successful, bitmap-handle will contain a positive value. If bitmap-handle is zero or negative, an error occurred. For a complete description of W$BITMAP W$BITMAP including all error values returned by it, see Appendix I. Library Routines.

Note: To use JPEG files, you must have the file ajpg32.dll installed in the same directory as the run-time. Only 32-bit run-times support JPEG format images. If you need JPEG support on 64-bit Windows, run the 32-bit run-time or the Thin Client. You can also run the Thin Client with the 64-bit run-time.

If you have multiple bitmap files, you need to load each before you can use the images they contain. Make certain to store the returned handles in different data items.

W$BITMAP searches for resources before it searches for disk files. For example, the tour.cbl sample program contains the following lines:

COPY RESOURCE "gtanima.bmp".

CALL "W$BITMAP" USING WBITMAP-LOAD,
"gtanima.bmp" GIVING GT-BITMAP

The bitmap loaded is the resource specified in the COPY RESOURCE statement because the referenced file name is the same as the resource name. Replacing the COPY RESOURCE statement with

COPY RESOURCE "mybmps/gtanima.bmp"

produces the same results (assuming mybmps/gtanima.bmp existed at compile time) because resource names are not stored with directory information. Note that

CALL "W$BITMAP" USING WBITMAP-LOAD,
"mybmps/gtanima.bmp"  . . .

also load the resource gtanima.bmp because W$BITMAP looks for a resource first, stripping directory information as part of the lookup. If no resource is found, W$BITMAP loads the file in the specified directory.

You can include JPEG files as a resource in your COBOL programs with the COPY RESOURCE statement or by using cblutil, in exactly the same manner as BMP files. cblutil -info will identify JPEG resources contained within an object library.

Note: A resource name with a hyphen (MY-FILE) is considered equivalent to the same resource name given with an underscore (MY_FILE).

When you are done with an image and have destroyed all the buttons that reference that image, you can remove it from memory with the WBITMAP-DESTROY operation. Do not destroy an image that is referenced by an existing button; the results are unpredictable.

Parent topic: Bitmap Buttons


Creating the Button

After you have loaded the bitmaps, you can create the buttons. Bitmap buttons are created in the same manner as regular push buttons. See the DISPLAY Control-Type statement in Procedure Division Statements for more information. You turn a push button, check box, or radio button into a bitmap button by using the following styles and special properties:

BITMAP (style, required) | This style informs the system that the button should be drawn as a bitmap button instead of a regular button. You must have this style set when the button is created, and you cannot change this style after the button is created.
BITMAP-NUMBER (numeric, special property, required) | This property identifies which image in the bitmap strip will be used for this button. The first image in the strip is number 1 , the second number 2, and so on. If this value is set to zero, a blank button is displayed. If this number is a negative value, or higher than the number of images in the strip, the results are unpredictable. If a bitmap strip contains only one image, you should specify the number 1. Note that you can change which bitmap appears on a button by changing this value.
BITMAP-HANDLE (numeric, special property, optional) | This property identifies which bitmap strip to use for the button. If you do not specify a bitmap handle, then the last bitmap loaded is used. If you specify a handle, the handle must hold a value returned by W$BITMAP when the bitmap was loaded. You can change bitmap strips after a button has been created by changing this value.

You may optionally use the following styles to affect the appearance of the buttons:

FRAMED (style, optional) | This style requests that a frame be drawn around the button. Typically the frame is a thin black line. Note that not all systems support frames, in which case the request is ignored. By default, buttons are framed under Windows NT/Windows 2000.
UNFRAMED (style, optional) | This style requests that the button be drawn without a frame. Not all systems support unframed buttons; on these systems the request is ignored. By default, buttons are not framed under Windows 98.
SQUARE (style, optional) | This style is used only with framed bitmap buttons. It forces the button to have square corners. Without this style, the button will have slightly rounded corners. Not all systems support square buttons; on these systems the request is ignored.

The following Screen Section entry describes two default size bitmap push buttons:

01  SCREEN-1.
  03  PUSH-BUTTON, ROW 1, placeStateCOL 2,
        BITMAP, BITMAP-NUMBER = 1.
  03  PUSH-BUTTON, OVERLAP-LEFT,
        BITMAP, BITMAP-NUMBER = 2.

Specifying the OVERLAP-LEFT style on the second button causes the two buttons to share a border if they are framed. See Global Styles for more information. Note that this example assumes that you want to pull images from the last bitmap loaded in your program.

Here is a more complete example that creates six bitmap buttons. The first two buttons are push buttons, the third is a check box, and the final three are radio buttons. The styles and properties used are appropriate for grouping the buttons into a toolbar. Note that the toolbar.cbl sample program does this.

* Screen Section
01  TOOLS-1.

  03  PUSH-BUTTON, placeStateCOL 2,
        BITMAP, BITMAP-NUMBER = 1,
        EXCEPTION-VALUE = 101.

  03  PUSH-BUTTON, OVERLAP-LEFT,
        BITMAP, BITMAP-NUMBER = 2,
        EXCEPTION-VALUE = 102.

  03  placeCityCHECK-BOX, StateCOL + 2, BITMAP,
        BITMAP-NUMBER = 3, NOTIFY,
        EXCEPTION-VALUE = 103.

  03  placeCityRADIO-BUTTON, StateCOL + 2, BITMAP,
        BITMAP-NUMBER = 4, NOTIFY,
        EXCEPTION-VALUE = 104.

  03  RADIO-BUTTON, OVERLAP-LEFT,
        BITMAP, BITMAP-NUMBER = 5,
        NOTIFY, EXCEPTION-VALUE = 105.

  03  RADIO-BUTTON, OVERLAP-LEFT,
        BITMAP, BITMAP-NUMBER = 6,
        NOTIFY, EXCEPTION-VALUE = 106.
Parent topic: Bitmap Buttons


Pop-up Hints

Bitmap buttons allow you to pack several controls into a small screen area. This makes them particularly useful in the construction of toolbars. However, a toolbar can be a problem for the novice or occasional application user because these users may not remember what functions the buttons perform. Because of their small size, these buttons do not always clearly indicate their purpose.

To aid these users, the run-time supports pop-up hints. A pop-up hint is a piece of text that pops up in its own window when the user places the mouse over a bitmap button for a predefined period of time. The text describes the function of the button. After some time has elapsed, the pop-up window disappears. Under Microsoft Windows, pop-up hints are also called tool tips.

To give a bitmap button a pop-up hint, simply assign the button a title. The title does not appear on the button. Instead, the run-time uses it as the pop-up hint. The hint will pop up automatically whenever the mouse is placed over the button and remains over the button for at least three-quarters of a second. The hint will automatically disappear after about four seconds. The hint will also disappear if you move the mouse away from the button, use the button, or start typing. Once a hint has been shown for a particular button, it will not be redisplayed as long as the mouse remains over that button. This prevents the hint from popping up annoyingly when the user uses the same button repeatedly.

Pop-up hints are displayed in a system-dependent color and font. Under Windows 98, the colors used are chosen by the user in the Control Panel for Tooltips. SMALL-FONT is used to display the hint.

You can control various aspects of how hints work with the HINTS_ON and HINTS_OFF runtime configuration variables.

Parent topic: Bitmap Buttons


Portability

Bitmap buttons cannot be supported on non-graphical systems. Under such systems, an attempt to create a bitmap button will fail, returning a handle with the value NULL. If you intend to run programs with bitmap buttons on character-based systems, you should arrange your program so that it can run effectively without the bitmap buttons, or substitute regular push buttons for the bitmap buttons when running on character-based systems.

Bitmaps are highly host-system dependent. You should be prepared to recreate or convert your bitmaps when moving to other graphical systems.

Parent topic: Bitmap Buttons


Paged List Boxes

The standard list box control provides a convenient way for a program to implement a look-up facility for a group of items. It is also tempting to extend this type of use into a method for locating records in a data file. Unfortunately, this doesn't work well when there are too many records in the file. The programmer runs into two main problems:

  1. The standard list box has a limited capacity (64K bytes), usually less than 2000 items.
  2. It takes too long to load the list box with the entire set of items.

Also, if the number of items is very large, the user may have a difficult time locating a particular item. There are two reasons for this:

  1. The resolution of the scroll bar's slider is too coarse.
  2. The search mechanism is too primitive (single-character match on the first byte of the record).

The paged list box is a variation of the standard list box that solves all of these problems. A paged list box works by managing only a limited number of records at a time. When it needs more records, it requests them from the controlling program. Paged list boxes are intended to be used in conjunction with a large, ordered data source, typically records stored in an indexed file.

Compared to a standard list box, a paged list box has the following advantages:

  • There are no capacity limitations. Since the paged list box stores only a small number of items at once, capacity is not an issue.
  • Load time is minimized. The list box displays as soon as it receives enough items to fill its visible portion.
  • There is an enhanced search facility. A paged list box can search for items based on full text strings instead of single characters. When the paged list box is active, the user can simply begin typing a string of text. A search box pops up, displaying the entered characters and the list box scrolls to the first entry that matches the string. You determine (with the SORT-ORDER property) whether the search is case-sensitive or not.
  • Memory requirements are minimal. Because it stores only a few items at once, a paged list box can be less of a drain on memory than a standard list box.

The primary disadvantage of a paged list box is that it's more complicated to program. Also, it's not well suited to handling unordered data.

  • Creating a Paged List Box
  • Adding Records to a Paged List Box
  • Other List Box Operations
  • Paged List Box Event Handling
  • Paged List Box Example
Parent topic: Graphical Controls


Creating a Paged List Box

To create a paged list box, you simply add the style word PAGED to the standard list box definition. Unlike some style attributes that can be applied to the list box after it's created, the paged property must be specified in the original definition that creates the list box. You cannot change this property after the list box is created. Other styles and properties associated with list boxes can be used normally. Note, however, that a paged list box will always be UNSORTED regardless of what you specify. Therefore, you must supply data to the paged list box in the sort-order that is needed.

The following Screen Section fragment shows how a typical paged list box might be declared. This declaration appears in the larger examples found in the help. This example illustrates the use of a paged list box to present records contained in a keywords file.

    78  lines-per-page   value 12.
    77  list-1-data      pic x(30).

01  list-1, list-box using list-1-data,
    line 3, column 10, size 30,
    lines lines-per-page,
    paged, 3-d,
    exception procedure is list-1-handler.

In the preceding example, the level 78 item lines-per-page defines the number of lines contained in the list box. The level 78 makes the examples that follow easier to read. Also, note the declaration of an EXCEPTION PROCEDURE for the list box. This is typical for paged list boxes that are defined in the Screen Section. The EXCEPTION PROCEDURE will handle requests from the list box when more data is needed.

Parent topic: Paged List Boxes


Adding Records to a Paged List Box

A record is added to a paged list box in the same way that a record is added to a standard list box: by assigning the record to the ITEM-TO-ADD property. Most of the time, you will add records to the end of the list box (exception: you will need to add to the top of the list when responding to scroll-up requests from the user). You can, however, add records anywhere in the list, by using the INSERTION-INDEX property. Remember that paged list boxes are always unsorted, so you must add records in a fashion that preserves the sort-order of the full set of records.

An important and unusual feature of the paged list box is that it never contains more items than are needed to display one page (that is, they contain only what is shown on the screen). Whenever you add a record that would cause the list to grow larger than one page, the list box automatically deletes a record. If you add a record to the beginning of the list, the last record in the list is deleted (causing the box to appear to scroll upward). Inserting an item into any other position in the list causes the first record to be deleted (causing the box to appear to scroll downward if you are adding to the end). This automatic deletion is a coding convenience that frees you from having to worry about the list box growing larger than a complete page of data.

The following example adds one item to the end of the current list's contents:

modify list-1, item-to-add = keyword-word

Alternatively, this example shows how to add an item to the top of the list:

modify list-1, insertion-index = 1,
   item-to-add = keyword-word

Remember that control properties are set in the order specified in the statement. In the preceding example, the INSERTION-INDEX phrase must appear before the ITEM-TO-ADD phrase in order to get the intended result.

Parent topic: Paged List Boxes


Other List Box Operations

Paged list boxes include a mechanism that allows the user to enter a search string. Any time a paged list box is active, the user can enter a sequence of characters (the search string). The list box automatically pops up a search box (entry field) displaying the search string. Each character entered generates an NTF-PL-SEARCH event. The program should be programmed to respond to the NTF-PL-SEARCH event, displaying the first entry in the data source that matches the search string. For an example of NTF-PL-SEARCH support, see the code example in Paged List Box Example.

Other aspects of a standard list box apply equally to a paged list box. For example, the currently selected item is the box's VALUE. You can specify the NOTIFY-DBLCLICK property to detect when the user double-clicks on an item. You can empty the list with the RESET-LIST property, or use the MASS-UPDATE property to speed changing the box's contents. For a complete description of list box properties and operations, see the List Box.

  • Scroll Bars in Text-mode Environments
Parent topic: Paged List Boxes


Scroll Bars in Text-mode Environments

A runtime variable called PAGED_LIST_SCROLL_BAR enables you to control the appearance of a scroll bar on paged list box controls in text-mode environments. Refer to the ACUCOBOL-GT Appendix manual, PAGED_LIST_SCROLL_BAR configuration variable, for details on this variable's settings.

Parent topic: Other List Box Operations


Paged List Box Event Handling

The largest and most demanding issue regarding paged list boxes is the additional required event handling. Whenever a paged list box needs more data, it generates an event. The program must detect these events and respond in a way that will update the box's contents appropriately. There are several such events. They are described in detail in Events Reference. In brief, they are:

NTF-PL-NEXT | Indicates the user wants to scroll the list box one record in the downward direction.
NTF-PL-PREV | Indicates the user wants to scroll the list box one record in the upward direction.
NTF-PL-NEXTPAGE | Indicates the user wants to scroll the list box one page in the downward direction.
NTF-PL-PREVPAGE | Indicates the user wants to scroll the list box one page in the upward direction.
NTF-PL-FIRST | Indicates the user wants to scroll to the top of the list.
NTF-PL-LAST | Indicates the user wants to scroll to the bottom of the list.
NTF-PL-SEARCH | Indicates the user wants to scroll to the page that contains the text he or she has entered.
NTF-PL-NEXT-WHEEL | Indicates the user wants to use a wheelmouse to scroll the list box in the downward direction.
NTF-PL-PREV-WHEEL | Indicates the user wants to use a wheelmouse to scroll the list box in the upward direction.

In each case, the program should locate the appropriate records and add them to the box. After adding the records, the program re-ACCEPTs the box to continue processing. Alternatively (and preferably), the program can use an EXCEPTION PROCEDURE to handle the events, thus never leaving the ACCEPT.

The program needs to track where it is in the overall list of items so that it can respond sensibly to the NEXT and PREVIOUS requests. Usually, the list of items consists of records contained in an indexed data file, and the ordering of those records is based on one of the file's keys. In this case, you can track the current location in the list by using the file's current record position. In this way you need only to remember if the last record you read from the file was placed at the beginning or end of the list box. If the record was placed at the beginning, then a single READ PREVIOUS will give you the previous record for the list. If the record was placed at the end, then a READ NEXT will give you the next record for the list. If you must get the next item from the opposite end of the list from your current position, then reading a page worth of records in the appropriate direction will get you to the proper record. The examples that follow explore this scheme in more detail.

Let's begin with a simple example. Suppose you are reading from an indexed file to get records for your list box. Also suppose that you always ensure that the last record you read from the file was the one at the end of the current page. In this situation, the following code fragment illustrates how you might handle the NTF-PL-NEXT event. This code builds on the code shown in the earlier example on constructing a paged list box.

list-1-handler.
   if key-status = w-event
      evaluate event-type
        when ntf-pl-next
          read keywords-file next record
             at end
                continue
             not at end
                modify list-1,
                       item-to-add = keywords-word
          end-read
      end-evaluate
   end-if.

In this example, you first determine if the exception that led you to this paragraph was an event. Then you evaluate the event type. In the case of an NTF-PL-NEXT event, you read the next record in the file and add it to the list box.

To this add the case of handling the NTF-PL-NEXTPAGE event. The code for this is very similar, except that you want to add a full page of records. Here is an augmented example that does that:

list-1-handler.
   if key-status = w-event
      evaluate event-type
         when ntf-pl-next
            perform add-next-record
         when ntf-pl-nextpage
            perform add-next-record
                    lines-per-page times
      end-evaluate
   end-if.

add-next-record.
   if not keywords-at-end
      read keywords-file next record
         at end      set keywords-at-end to true
         not at end  modify list-1,
                     item-to-add = keywords-word
      end-read
   end-if.

A problem with this approach is that you have to do a lot more work to implement NTF-PL-PREV and NTF-PL-PREVPAGE. Because the file's current position is at the end of the list, you have to read backward through the entire page to get to the records you want. Then, when you are done adding records, you have to read forward through the page to maintain the program's assumptions. A more efficient technique keeps track of which side of the list you have last read from, and adjusts the position accordingly. This technique is shown in the full example included in Paged List Box Example, or in pagebox.cbl sample program.

Before laying out the full paged list-box example, consider how you might handle the NTF-PL-SEARCH event. This event is unusual in that you have to reposition the file arbitrarily. To get the search text that the user entered, you must first INQUIRE on the list box's SEARCH-TEXT property. That information is then used to do the positioning. Typical code might look like:

list-1-handler.
   if key-status = w-event
     evaluate event-type
       when ntf-pl-next
          perform add-next-record
       when ntf-pl-nextpage
          perform add-next-record
                  lines-per-page times
       when ntf-pl-search
          inquire list-1,
                  search-text in keywords-word
          start keywords-file,
                key not less than keywords-word
            invalid key
               perform search-failure-handling
            not invalid key
               perform add-next-record
                       lines-per-page times
          end-start
     end-evaluate
   end-if.

The full example that follows explores the issue of handling a failed search.

Parent topic: Paged List Boxes


Paged List Box Example

The following partial program shows a full implementation of a paged list box. Code that is incidental to the handling of the list box is omitted in the interest of brevity.
Tip: In the AcuGT > Sample directory of your installation, there is also a sample program called wheelevent.cbl. This program demonstrates how to create a paged list box, a paged grid, and wheelmouse events for scrolling the control.
file-control.
     select keywords-file
         assign to "techword.dat"
         organization is indexed
         access mode is dynamic
         record key is keyword-word
         file status is keyword-status.

file section.
fd  keywords-file.
01  keyword-record.
    03  keyword-key.
        05  keyword-word         pic x(15).
        05  keyword-id           pic 9(7).

working-storage section.

78  list-box-lines               value 16.

copy "acucobol.def".
copy "acugui.def".

77  keyword-status               pic xx.
77  number-reads-needed          pic 99.

* STATE-FLAG tracks where you are in the file.
* READING-FORWARDS indicates that the last read was
* of the last record shown in the box.
* READING-BACKWARDS indicates that the last read
* was of the first record in the box (via READ
* PREVIOUS).  AT-START and AT-END handle special
* cases when you reach either end of the file.

77  state-flag                   pic x.
    88  reading-forwards         value "f".
    88  reading-backwards        value "b".
    88  at-start                 value "s".
    88  at-end                   value "e".

77  list-data                    pic x(15).

77  key-status
    is special-names crt status  pic 9(4).

* Note: although the program never directly
* references the Screen Control data item, you have
* to declare it anyway.  That is because "notify"
* style events will set it to the proper value when
* entering an EXCEPTION PROCEDURE.  The value
* generated causes the controlling ACCEPT statement
* to continue processing after the exception
* procedure finishes.  If you omit SCREEN-CONTROL,
* then the result is that you exit the ACCEPT after
* the exception procedure completes.

01  screen-control
    is special-names screen control.
    03  accept-control            pic 9.
    03  control-value             pic 999.

01  event-status
    is special-names event status.
    03  event-type                pic x(4) comp-x.
    03  event-window-handle       handle.
    03  event-control-handle      handle.
    03  event-control-id          pic x(2) comp-x.
    03  event-data-1              signed-short.
    03  event-data-2              signed-long
    03  event-action              pic x comp-x.

screen section.
01  screen-1.
    03  list-1, list-box using list-data,
        line 3, column 10, size 30,
        lines list-box-lines, 3-d,
        paged,
        exception procedure is list-1-handler.

* Other screen items typically found here

procedure division.
main-logic.
   open input keywords-file.
   set reading-forwards to true.

* Code to construct user's window omitted

   display screen-1.

* Load the first page of list box items

   modify list-1, mass-update = 1
   perform list-box-lines times
      read keywords-file next record
         at end     set at-end to true
                    exit perform
         end-read
      modify list-1,
             item-to-add = keyword-word
   end-perform
   modify list-1, mass-update = 0.

* Now activate the list box

   accept screen-1.

* Code to use the entered data omitted

   stop run.

* LIST-1-HANDLER handles all exceptions generated
* by the list box.  The only exceptions you care
* about are those that require a response in
* order to manage the list box properly.

list-1-handler.
   if key-status = w-event
      evaluate event-type
        when ntf-pl-next
          perform get-next-item

        when ntf-pl-prev
          perform get-prev-item

        when ntf-pl-nextpage
          modify list-1, mass-update = 1
          perform get-next-item list-box-lines times
          modify list-1, mass-update = 0

        when ntf-pl-prevpage
          modify list-1, mass-update = 1
          perform get-prev-item list-box-lines times
          modify list-1, mass-update = 0

        when ntf-pl-first
          move low-values to keyword-word
          start keywords-file,
                key not < keyword-word
             invalid key    exit paragraph
             end-start
          set reading-forwards to true
          modify list-1, mass-update = 1
          modify list-1, reset-list = 1
          perform get-next-item list-box-lines times
          modify list-1, mass-update = 0

        when ntf-pl-last
          move high-values to keyword-word
          start keywords-file,
                key not > keyword-word
             invalid key    exit paragraph
             end-start
          set reading-backwards to true
          modify list-1, mass-update = 1
          modify list-1, reset-list = 1
          perform get-prev-item list-box-lines times
          modify list-1, mass-update = 0

* In the search logic, if you get too close to the
* end of the file, you simply act as if you wanted to
* find the last full page.  Do this by setting the
* event type to NTF-PL-LAST and re-evaluating.

        when ntf-pl-search
          inquire list-1,
                  search-text in keyword-word
          start keywords-file,
                key not < keyword-word
            invalid key
                move ntf-pl-last to event-type
                go to list-1-handler
            end-start
          set reading-forwards to true
          modify list-1, mass-update = 1
          perform get-next-item list-box-lines times
          if at-end
            move ntf-pl-last to event-type
            go to list-1-handler
          end-if
          modify list-1, mass-update = 0
      end-evaluate
    end-if.

* GET-NEXT-ITEM handles all cases where you read
* forwards through the file.  It adjusts for the
* four possible states you could be in and then
* retrieves the next record.  This record is added
* to the end of the list box.  In some cases, you
* have to traverse over the page of records
* currently displayed (because you are switching
* direction).

get-next-item.
   evaluate true
     when at-start
        move low-values to keyword-word
        start keywords-file, key not < keyword-word
          invalid key    exit paragraph
          end-start
        add 1 to list-box-lines
            giving number-reads-needed
     when at-end
        exit paragraph
     when reading-backwards
        move list-box-lines to number-reads-needed
     when reading-forwards
        move 1 to number-reads-needed
     end-evaluate

     perform number-reads-needed times
        read keywords-file next record
          at end   set at-end to true
                   exit paragraph
          end-read
     end-perform

     modify list-1,
       item-to-add = keyword-word

     set reading-forwards to true.

* GET-PREV-ITEM is the converse of GET-NEXT-ITEM.
* It retrieves the previous record in the list and
* adds it to the top of the list box.  The code is
* structured identically to GET-NEXT-ITEM.

get-prev-item.
   evaluate true
     when at-end
        move high-values to keyword-word
        start keywords-file, key not > keyword-word
            invalid key  exit paragraph
            end-start
        add 1 to list-box-lines
            giving number-reads-needed
     when at-start
        exit paragraph
     when reading-forwards
        move list-box-lines to number-reads-needed
     when reading-backwards
        move 1 to number-reads-needed
   end-evaluate

perform number-reads-needed times
   read keywords-file previous record
     at end  set at-start to true
             exit paragraph
     end-read
end-perform

modify list-1
   insertion-index = 1
   item-to-add = keyword-word

set reading-backwards to true.
Parent topic: Paged List Boxes


Paged Grids

A grid is a matrix of data fields. Each element of this matrix, called a cell, can hold either text or a bitmap, or both. Grids are organized into rows, columns, and records. In a grid, a row is a grouping of cells that appear on one line in the control. A record is one or more rows that are treated as a logical unit. By default, a record occupies one row in a grid, but a record may also wrap around to the next row when it passes the right edge of the grid. A column identifies a particular cell in a record.

A grid's capacity is limited by available memory. Sometimes, however, you may want to view many records using a grid control. This could pose a problem when you are using normal grids. Just loading all the records into the grid could take an excessive amount of time. To remedy this problem, you may want to use a paged grid.

When you are using the PAGED style in a grid, the grid holds only as many records as can be viewed on the screen. This is called a page of data. The vertical scroll bar found in a normal grid is replaced by four buttons. These buttons respond to requests to get the next record, the previous record, the next page, or the previous page. (Note that you can also apply wheelmouse events to PAGED styled grids.) When the user clicks one of these buttons, the grid sends a message to the program asking for the appropriate data depending on which button was clicked. This data typically comes from an indexed file. The expected program logic is to do one or more READ NEXT or READ PREVIOUS statements to retrieve the data.

Note: By default, if a user switches focus by clicking any of the buttons used to scroll a paged grid, a CMD-GOTO event is not generated. To modify this behavior, set the GRID_BUTTONS_CAUSE_GOTO configuration variable to 1 (on, true, yes).

Paged grids are conceptually similar to paged list boxes. Programmers familiar with paged list boxes, however, may notice some differences in programming paged grids. These differences were designed to make programming the grid's paging logic easier. The noticeable differences are:

  • The program's structure is simplified because event procedures, instead of responses to various exception values, are coded into the paging logic.
  • Less coding is required, because there is no need to write any code for Next Page and Previous Page actions. You may still opt to write additional code if you want to define actions other than the response normally expected from Next Page and Previous Page operations.
  • Coding the response to the First Page and Last Page requests are simpler.
  • Satisfying Next Record and Previous Record requests are easier because the grid control can tell you how many records will have to be read (in the proper direction) in response to these requests.

Furthermore, paged grids communicate requests for more data through events such as:

  • MSG-PAGED-NEXT
  • MSG-PAGED-PREV
  • MSG-PAGED-NEXTPAGE
  • MSG-PAGED-PREVPAGE
  • MSG-PAGED-FIRST
  • MSG-PAGED-LAST
  • MSG-PAGED-NEXT-WHEEL
  • MSG-PAGED-PREV-WHEEL

Paged grids never hold more data than they can display on the screen. When you are adding a record at the end of a full page, the control deletes the topmost non-heading record. This causes the grid's contents to scroll upward. When you are adding a record to any other position, the last record in the grid is deleted. This causes all records after the one being added to scroll downward.

Note: The current cell is not changed when the grid is paged. In other words, if the grid's cursor is at row 2, column 3, it will be at row 2, column 3 after the user clicks the next record button. This will effectively move the cursor to a new record, even though its physical location has not changed. Unlike other forms of cursor movement, this does not generate any additional events. If you are performing special actions when the cursor enters a new cell (for example, displaying related information outside of the grid), then you should perform the appropriate actions in response to paging events as well as cursor-movement events.
Tip: The paged grid feature is demonstrated in two AcuBench sample project located in the Support > Examples and Utilities area of the Micro Focus Web site. To download these projects, go to: http:// supportline.microfocus.com/examplesandutilities/index.asp. Select Acucorp samples > Graphical User Interfaces > GridTXTViewer.zip and pagedgrid.zip.
Parent topic: Graphical Controls


Supporting Concepts and Related Issues

  • Handles
  • Events
  • Graphical vs Textual Modes
  • Styles and Special Properties
  • Methods
  • Coordinates
  • Fonts
  • Layout Managers
Parent topic: ACUCOBOL-GT User Interface Programming


Handles

Normally, when you create a graphical object, the run-time system generates a unique value to identify that object, and stores that value in the program's specified handle. You make future references to that object by naming its handle. Most of the graphically oriented features of ACUCOBOL-GT make use of handles. A handle is a COBOL data item. Internally, a handle is simply a number. The COBOL program uses handles to identify various graphical items.

Note: In addition to all the graphical controls and user-interface-type objects (for example, window or font), a handle can be applied to a thread within a program.

If you have worked with ACUCOBOL-GT's text-based subwindows (textual, pop-up windows), you are already familiar with the use of handles. The POP-UP AREA phrase of the DISPLAY WINDOW verb names a PIC X(10) data item that holds the handle of the created window. When you want to remove the window, you use that data item in the CLOSE WINDOW verb. The data item tells the system which window to close.

There is a data type, called USAGE IS HANDLE, that you use when you want to declare a handle for a data item. The syntax for it is as follows:

USAGE IS HANDLE OF type

You can use this data type with or without specifying a type of handle, but there are certain benefits if you do specify it. The primary benefit, for handles of controls, is that the proper style and property names are known by the Compiler and can be used. Consider the difference in this example:

77  h-1  handle.
77  h-2  handle of entry-field.

then,

modify h-2, max-text = 15.     ( legal )
modify h-1, max-text = 15.     ( compile error )

Another significant benefit to typed handles is that the Compiler can check that they are being used in proper contexts.

The run-time system can tell when a handle is no longer valid. If you make reference to an invalid handle (for example, a handle to an object you have destroyed), the requested operation is simply ignored.

When you make use of graphical objects in the Screen Section, the run-time system automatically creates and manages the associated handles for you. In this case you do not explicitly use handles when referring to graphical objects.

See USAGE Clause for more information about handles and the USAGE IS clause.

Parent topic: Supporting Concepts and Related Issues


Events

In graphical systems, events communicate actions taken by the user and various graphical objects. For example, if the user types a key, the system may generate several events to denote that fact: a key pressed event, a character typed event, and a key released event. A push button might generate a button pushed event when the user activates it. Much of graphical programming involves detecting and handling events.

Event programming is foreign to most COBOL programs. To simplify the programming of graphical systems, ACUCOBOL-GT handles most events internally. The run-time system either performs the appropriate action, or converts the event into a form more recognizable to a traditional COBOL program. For example, you can create your push buttons so that button pushed events are treated as if a particular function key was pressed.

Certain events must be handled by the program, however. In ACUCOBOL-GT, there are very few of these, but they are important. Events that must be acted upon by the COBOL program are called terminating events. The name comes from the fact that their occurrence causes any active ACCEPT statement to terminate, so that the COBOL program can handle the event.

When a terminating event occurs, any active ACCEPT statement terminates and returns an exception value of "96". In the file acugui.def, you will find a level 78 for this value, called W-EVENT. When you set up a situation in which a terminating event could occur, you must be ready to handle this exception value.

When a terminating event occurs, the run-time system fills in the new EVENT STATUS data item (event-status) with information about the event. The EVENT STATUS data item is declared in SPECIAL-NAMES. This data item identifies which event occurred, which window it occurred in, which control it applies to (if any), and any additional information your program might need. See Special-Names Paragraph for details on the EVENT STATUS data item.

If desired, for any control that generates events you can specify a list of event types that that control either must receive or not receive (filter out). To create such a list, you use the EVENT-LIST, AX-EVENT-LIST, and EXCLUDE-EVENT-LIST Common Properties. These are described in Common Screen Options.

For a description of the events that can be returned by the runtime system, see Events Reference.

Note: There is a special control style called SELF-ACT that can be assigned to push buttons, radio buttons, and check boxes. This style simplifies the handling of button events. If you also assign an exception value to the button, it will act just like the equivalent function key. See Push Button for more information about the SELF-ACT style.
Parent topic: Supporting Concepts and Related Issues


Graphical vs Textual Modes

As previously discussed, ACUCOBOL-GT marries two diverse technologies: text-only displays and graphical displays.

When we talk about an ACCEPT or DISPLAY statement, the term textual refers to the forms of these verbs that handle text-based elements. Specifically, textual refers to Format 1 of both verbs, plus any referenced Format 1 Screen Section items. The term graphical refers to the forms of these verbs that handle controls. Specifically, this includes Format 14 of the DISPLAY verb, Format 7 of the ACCEPT verb, and Format 2 of any referenced Screen Section items. Note that a LABEL control (which is a block of text) is considered a graphical element, not a textual display.

When thinking about the textual display, you may find that it helps to think of it as a rigid grid of character cells. Each cell in the grid holds one character, and the cell's size and location is fixed. This simulates the nature of text-only monitors. In this mode, you can display five characters starting at column 1 and expect the fifth character to be placed in column 5.

The graphical display is then layered on top of the textual display. The graphical display is not rigid. You can place elements anywhere on the screen, not just in the fixed character cells. In this mode, displaying a label of five characters starting at column 1 will not necessarily place the fifth character in column 5 (because the label's font may be variable-pitch). See Coordinates for more information on screen coordinates.

Two COBOL reserved words are available to mark Screen Section entries for use in the graphical or textual environment. These reserved words are: GRAPHICAL and CHARACTER. These markings have the effect of restricting the display of the elements nested within them. The elements contained in a GRAPHICAL Screen Section entry are displayed only when the program is run on a graphical system. The contents of a CHARACTER Screen Section entry are displayed only when the program is run on a character-based system. When the program attempts to execute a marked entry on a system of the opposite type, that entry is ignored (for an extended description of these labels and their use, see Screen Description Entry in the ACUCOBOL-GT Reference Manual).

Parent topic: Supporting Concepts and Related Issues


Styles and Special Properties

ACUCOBOL-GT uses a special type of COBOL identifier that is context-sensitive. These are the style and special property names of controls. Each type of control has a set of styles and special properties that apply to it. If these names were reserved words in COBOL, there would be many new reserved words, making it likely that existing programs would have to be changed to be compiled with ACUCOBOL-GT. Because more styles and special properties are expected in future versions, this proliferation of reserved words would create an ever-increasing problem.

To address this issue, ACUCOBOL-GT does not reserve the style and special property names in the usual manner. Instead, the Compiler reserves them only when in the context of acting on a control of the proper type. For example, when you are defining an entry-field control in the Screen Section, the style and special property names associated with entry fields are reserved. At other times, they are not. This allows you to declare variables and paragraphs with the same names as long as you do not try to refer to those items in a context where the reserved meaning would apply.

Style and special property names are reserved in the following four cases:

  1. When defining a Screen Section entry for a control
  2. In the scope of a DISPLAY statement that creates a control
  3. In the scope of a MODIFY statement that changes a control
  4. In the scope of an INQUIRE statement that references a control

At all other times, the style and special property names are not reserved.

Since the Compiler reserves only names that are appropriate for a particular type of control, it can recognize those names only when it knows what type of control is being acted on. If the control class is generic (variable), the Compiler cannot determine which set of names to reserve, so it does not reserve any of them. This leads to cases where the Compiler cannot resolve seemingly correct code.

For example, MAX-TEXT is a special property name associated with entry fields. The following code appears to be correct, but will not compile:

77  FIELD-1  USAGE HANDLE.
MODIFY FIELD-1, MAX-TEXT = 15.

In the above example, the Compiler does not recognize MAX-TEXT as a meaningful word because it does not know that FIELD-1 is an entry field. For this code to compile, you would have to change it to read:

77  FIELD-1  USAGE HANDLE OF ENTRY-FIELD.
MODIFY FIELD-1, MAX-TEXT = 15.

By declaring FIELD-1 as a handle to an entry field, you alert the Compiler to use the style and special property names associated with entry fields whenever it is referenced.

Note: Sometimes you might need to use generic handles in your code when you don't know at compile time what kind of control will be needed during program execution. In these cases, you can always use the alternative form of specifying styles and special properties. In this form, you include the word "STYLE" or "PROPERTY" followed by the numeric value associated with the style or special property (the value can be a literal or stored in a variable). Level 78 declarations for the style and special property names can be found in the file controls.def.

For example, the level 78 name that corresponds to MAX-TEXT is EFP-MAX-TEXT ("EFP" is short for Entry Field Property). The following code is another way of coding the preceding example:

77  FIELD-1  USAGE HANDLE.
MODIFY FIELD-1, PROPERTY EFP-MAX-TEXT = 15.

In most cases, you will probably use the style and special property names known by the compiler. However, the advantage of using the values provided in controls.def is that you can assign them to variables that need to be set dynamically (at run time).

Parent topic: Supporting Concepts and Related Issues


Methods

All ACUCOBOL-GT controls have properties and styles. In addition to properties and styles, ActiveX and .NET controls have a concept known as methods. In ActiveX and .NET, methods (also known as object methods) specify the functions that the control provides. To invoke (call) a method, you use the MODIFY verb in much the same way that you set a property or style.

Note: Unlike common properties and styles, you cannot use the DISPLAY statement to set a special property or invoke a method of an ActiveX or .NET control defined in the Screen Section. You must use the MODIFY verb.

Both ActiveX and .NET methods can take any number of parameters or no parameters. ActiveX controls can also take optional parameters (that is, parameters that can be omitted). You specify the parameters in COBOL by enclosing them in parentheses. With ActiveX controls, the optional parameters are always last. If a method takes only one parameter, the parentheses may be omitted. If a method takes no parameters, you must use empty parentheses (( )).

Note that ActiveX and .NET properties and methods should always be prepended with an @ character in case they clash with COBOL reserved words or ACUCOBOL-GT graphical control property and style names. @ identifies the relationship of the name to ActiveX or .NET.

  • ActiveX Example
  • .NET Example
Parent topic: Supporting Concepts and Related Issues


ActiveX Example

Consider the ActiveX control, Microsoft Rich Textbox Control 6.0. Here is an excerpt from its COPY file, created with the AXDEFGEN utility. See Using ActiveX Controls and COM Objects in A Guide to Interoperating with ACUCOBOL-GT for more information on AXDEFGEN.

...
      * LoadSave constants.

      * LoadSaveConstants
           CLASS @LoadSaveConstants
               CLSID, 9FAEAB20-894B-11CE-9576-0020AF039CA3
               NAME, "LoadSaveConstants"
      * long rtfRTF
               ENUMERATOR, @rtfRtf, 0
      * long rtfText
               ENUMERATOR, @rtfText, 1

...
      * Microsoft Rich Textbox Control 6.0

      *** Primary Interface ***

      * RichTextBox
           CLASS @RichTextBox
               CLSID, 3B7C8860-D78F-101B-B9B5-04021C009402
               NAME, "RichTextBox"
...
      * LoadFile
      * Loads an .RTF or text file into a RichTextBox control.
               METHOD, 37, @LoadFile,
                   "BSTR bstrFilename",
                   "VARIANT vFileType"
                       OPTIONAL 1
...

The LoadFile method takes two parameters: bstrFilename and vFileType. vFileType is an OPTIONAL parameter. bstrFileName is a BSTR type, and vFileType is a VARIANT type. To invoke this method from COBOL, you use the MODIFY verb:

  MODIFY RICH-TEXT-BOX-1 LoadFile ("myfile.rtf", rtfRtf).

The ACUCOBOL-GT run-time system automatically converts the parameters to the appropriate type and invokes the method. The LoadFile method does not have a return value. If the method had a return value that was not void, it would be converted and moved to the item specified in the GIVING clause of the MODIFY statement.

The syntax is as if LoadFile is a property whose value is its parameter list. For example, the following is also valid:

  MODIFY RICH-TEXT-BOX-1 PROPERTY 37 = ("myfile.rtf", rtfRtf).

Note that 37 is the property number of LoadFile. The equals sign is optional. Commas in the parameter list are optional. The parameters may be arithmetic expressions.

Parent topic: Methods


.NET Example

Consider the sample .NET control, AmortControl. Here is an excerpt from its COPY file, created with the NETDEFGEN utility. See Working with .NET Assemblies in A Guide to Interoperating with ACUCOBOL-GT for more information on using NETDEFGEN.

* .NET Copy Book - Generated On 3/5/2004 10:39:23 AM
     OBJECT @ASSEMBLY
     NAME "@AmortControl"
            VERSION "1.0.1266.13363"
            CULTURE "neutral"
            STRONG "null"
* AmortControl.UserControl1
     NAMESPACE "AmortControl"
     CLASS "UserControl1"
     MODULE "amortcontrol.dll"
         VISUAL
          CONSTRUCTOR,  0, @CONSTRUCTOR1
* System.String get_WhatIfMonths()
          METHOD,  0, "@get_WhatIfMonths"
                    RETURNING "BSTR", TYPE 8
* Void InitializeComponent()
          METHOD,  0, "@InitializeComponent"
* TotalInterest
          PROPERTY_GET, 0, @TotalInterest
                    RETURNING, "BSTR", TYPE 8
* FireCalc  ()
          EVENT, 520214344, @UserControl1_FireCalc

The get_WhatIfMonths method takes no parameters and returns a string of characters. To invoke this method from COBOL, you use the MODIFY verb:

MODIFY AmortControl-handle "get_WhatIfMonths" ( )
          GIVING MY-PICX-STRING.

The method has a return value that is converted and moved to the item specified in the GIVING clause of the MODIFY statement. To get the property TotalInterest:

INQUIRE ctl-handle TotalInterest IN TOT-INTEREST.
Parent topic: Methods


Coordinates

This section describes how display elements are located on the screen

  • Coordinate Handling
  • Coordinate Space Problems
  • Coordinate Space Solutions
Parent topic: Supporting Concepts and Related Issues


Coordinate Handling

ACUCOBOL-GT uses line and column positions to specify the location of graphical objects. There are two reasons for this:

  1. The line and column notation is already familiar to COBOL programmers
  2. Retaining this notation makes translating text-based applications into graphical applications much easier

Because graphical objects are not constrained to whole line and column locations, you may use non-integer values when specifying a line or column position. For example, LINE 1.5 is a point that is midway between the top of line 1 and the top of line 2. Unless otherwise specified, the line/column position of a graphical object refers to the upper-left pixel of the smallest bounding rectangle that encloses the object.

Recall that the run-time system treats the screen as two layers: a text-based character layer with a graphical-object layer on top. So that the run-time system can execute text-only applications properly, the line and column positions refer to the grid of characters in the text layer. Thus, the font used by the text layer defines the size of a line and column. We call a single character location in the text layer a cell. The height of the cell is the height of one line, and the width of the cell is the width of one column. See Graphical vs Textual Modes for more information

Parent topic: Coordinates


Coordinate Space Problems

The biggest difficulty with the handling of coordinates is that the text-based font used on the text layer may be an inappropriate size for use in locating graphical objects. There are a couple of reasons for this. One is that the text-layer font must be a fixed-pitch font, while the font used by graphical objects is usually variable-pitch. Frequently this means that the two fonts will be different sizes. The second problem is that some common graphical controls (for example, entry fields) are surrounded by a box, which makes the control much larger than its font would otherwise suggest.

For example, under Windows 98 on a VGA display, the height of the usual text-layer font is 15 pixels. The height of the font normally used for entry fields is 13 pixels. The height of a boxed entry field is 50 percent larger than its font, so a boxed entry field is 13 * 1.5 (round up) = 20 pixels high. This means that each boxed entry field is 20 / 15 = 1.33 lines high.

While you are free to specify any coordinates needed to produce the look you want, working largely with non-integer values is difficult and reduces portability. It also makes converting text-based programs much harder, because the text-based coordinates may not be the correct ones for the corresponding graphical objects.

Parent topic: Coordinates


Coordinate Space Solutions

Ideally, you want the majority of your positioning coordinates to be integer values. This is easier to work with and improves portability. While you will undoubtedly encounter cases where you need to use non-integer coordinates, their use should be minimized.

The simplest solution is to use the same font for your graphical objects as you use in the text layer. Then, if you also use unboxed entry fields, you have eliminated both trouble points. The problem with this solution is that it looks wrong when compared to other graphical programs; the font is fixed-pitch and the boxes are missing.

A more sophisticated solution is to change the way that coordinates are measured. If you can set the coordinate space so that your controls fall on integral coordinates, the problem is solved. ACUCOBOL-GT provides a way to do this. When you create a window (including the main application window), you can set its cell size with the CELL phrase of the DISPLAY WINDOW verb. When you do this, you specify your own line and column sizes. The phrase allows you to have the run-time system measure a graphical object and set the coordinate space appropriately. Typically, you would measure an entry field with the font you want to use and have the run-time system lay out the screen accordingly. For details on the CELL phrase, see Format 11 DISPLAY FLOATING WINDOW.

Note: When you change the coordinate space, you affect both the text and graphical layers. Because of this, you have some restrictions if you are going to use the text layer. In particular, you may not make a cell smaller than a character, nor may you make it wider than a character (it can be taller).

Here are some general guidelines to apply when deciding how to set up your coordinate space:

  • If you plan to mix graphical objects with classical textual displays, use the default cell size that is the size of the text-layer font. In this case, the overriding consideration is the placement of the text in cells. The graphical objects will have to be specified with whatever coordinates work. You should try to keep the number of graphical objects to a minimum, or consider converting to an entirely graphical screen if you want to mix in a large number of graphical elements.
  • If you anticipate using entry fields heavily (as would be typical in a conversion of a text-based application), you should set up the coordinate space based on the size of an entry field. This makes the placement of label and entry-field pairs very easy. Note that the CELL phrase allows you to specify OVERLAPPED (vertically adjacent entry fields share a common border) or SEPARATE (a little space placed between entry fields). You can choose whichever style you think looks better. Here is an example CELL phrase:
    CELL SIZE = ENTRY-FIELD FONT MY-FONT, SEPARATE
  • If you will be using a mix of graphical objects, but only a few entry fields, you should base the coordinate space on the size of a label. This lets you measure with the correct font, but ignores the overhead associated with entry fields. This setting is closest to what other graphical-design systems use (typically, these use a coordinate cell size that is some fraction of the size of the system's font). A typical CELL phrase would be:
    CELL SIZE = LABEL FONT MY-FONT
Another way to get the same result is to use the GRAPHICAL phrase with the DISPLAY WINDOW verb. For example:
DISPLAY STANDARD GRAPHICAL WINDOW
  • If you want to compute exact pixel coordinates (for very specialized displays), you should use a cell height and width of 10. Then each tenth of a cell (.1) corresponds to one pixel.
    Note: You should not use 1 as the cell height and width because this produces a text-layer memory map that is too large. Applications that use 1 as a measure are not portable to non-graphical systems.
  • Finally, it is possible to set up your graphical control sizes based entirely on the pixel count. You can specify the 'x' and 'y' coordinates, LINES, and SIZE of a control in pixels. This method allows you to always have your positioning coordinates as integer values, which is nice when you need absolute positioning. You gain better control of your screen layouts, and screens based on different cell sizes can easily be accommodated by the screen designer.

    A sample DISPLAY statement would look like this:

    DISPLAY PUSH-BUTTON    LINE 300 PIXEL(S)
                       COL  225 PIXEL(S)
                       LINES 30 PIXEL(S)
                       SIZE 120 PIXEL(S).
Note: Pixel coordinates are relative to the size of the target window. The lowest legal value is '1', and the highest legal value is equal to the largest resolution covered by the target window. If that value is exceeded, the property defaults to the closest legal value.

It is important to set your coordinate space early in your work. If you lay out screens and then change the coordinate system, all of your previously designed screens will have to be reworked.

Because of the fundamental differences in the coordinate systems of character and graphical systems, ACUCOBOL-GT provides two sets of statement phrases with which to specify control size and positioning. See The Character Coordinate Phrases for a discussion of these phrases.

Parent topic: Coordinates


Fonts

On graphical systems, you are not limited to just one font. ACUCOBOL-GT provides general support for access to most fonts known to the system.

In ACUCOBOL-GT, fonts are represented in your program by handles. Once created, a font handle indirectly refers to all the information the system needs to manage that particular font. When you want to specify a particular font in your program, you use its handle. See Handles for more information.

In ACUCOBOL-GT, you have access to most of the systems add-on fonts (TrueType), as well as several predefined fonts. The set of predefined fonts is used because they are guaranteed to be available on all Windows systems. These fonts correspond to the various Windows system fonts that are accessed with the GetStockObject API function.

Font handles are created in two ways: with the W$FONT library routine and with the ACCEPT FROM STANDARD OBJECT verb. The ACCEPT FROM STANDARD OBJECT verb provides access to the system predefined fonts only. See Procedure Division Statements for a description of the ACCEPT Statement and a list of the available fonts.

The W$FONT library routine provides access to most of the fonts known to the system, including TrueType fonts. W$FONT provides three primary functions.

  1. It returns a handle to the font on the system that either exactly or most closely matches a font description
  2. Given a font handle, it returns a complete description of the font's characteristics
  3. It creates and presents to the user a font selection dialog box, returning a description of the font that the user selected

For a complete description of W$FONT see Appendix I. Library Routines.

Note: Fonts occupy memory. If you no longer need a font, you can free the memory used by that font with the DESTROY Statement. The runtime system automatically destroys all fonts when it exits.
Parent topic: Supporting Concepts and Related Issues


Layout Managers

ACUCOBOL-GT includes a layout manager facility that can be applied to help manage some of the tricky aspects of a screen's layout. A layout manager is a specialized piece of software that is attached to a window and that manages the placement and size of controls in that window. Individual layout managers have their own rules regarding how controls are sized and placed.

By default, a window does not have a layout manager attached to it. For such windows, controls are sized and placed according to their normal properties (for example, LINE, COLUMN, SIZE, and LINES). When a layout manager is attached to a window, the layout manager determines the size and placement of controls, although it is free to use the normal properties to help make decisions. A control can provide additional information about itself, including special size and placement parameters, to the layout manager through the LAYOUT-DATA property. The precise meaning of LAYOUT-DATA varies from layout manager to layout manager.

Layout managers operate whenever a new control is placed in the window or the window is resized.

Currently, ACUCOBOL-GT supports only a single type of layout manager. This manager is called the resize manager. The resize manager does not attempt to layout controls as they are being placed. Rather, it automatically resizes and repositions controls whenever the associated window is resized. Controls use LAYOUT-DATA to tell the resize manager which automatic actions should be applied to them.

To use a layout manager, the program must:

  • Make a copy of the layout manager and attach it to a window
  • Set the LAYOUT-DATA property on the desired controls

These steps, and a description of four control properties that can be used to constrain a control's dimensions, are described in the help topics in this section.

  • Working with Layout Managers
  • Setting LAYOUT-DATA
  • Minimum and Maximum Control Dimensions
  • The Resize Layout Manager
Parent topic: Supporting Concepts and Related Issues


Working with Layout Managers

Layout managers are created and referenced through a handle data item of type LAYOUT-MANAGER.

The declaration of a layout manager handle may include automatic initialization, in the same fashion as font handles. You can name any of the standard layout managers after the word LAYOUT-MANAGER. Currently, there is only one standard layout manager, LM-RESIZE, the resize manager. For example:

77  MY-LAYOUT HANDLE OF LAYOUT-MANAGER, LM-RESIZE.

Like all handles, a layout manager consumes memory while allocated. You free this memory with the DESTROY verb. For example:

DESTROY MY-LAYOUT

You get a layout manager handle by using the statement ACCEPT FROM STANDARD OBJECT. For example:

ACCEPT MY-LAYOUT FROM STANDARD OBJECT "LM-RESIZE"

You do not need to do this if you use the initialization option mentioned above. The layout manager returned by ACCEPT FROM STANDARD OBJECT is a copy of the standard manager. Therefore, you should destroy it when you are done with it. Destroying it will not affect other copies.

  • Attaching a Layout Manager to a Window
Parent topic: Layout Managers


Attaching a Layout Manager to a Window

To be useful, a layout manager must be attached to a window.

To attach a layout manager to a window, you use the standard window property LAYOUT-MANAGER. You must do this when you create the window. For example:

DISPLAY STANDARD GRAPHICAL WINDOW,
      BACKGROUND-LOW,
      LAYOUT-MANAGER = MY-LAYOUT.

A layout manager records data within itself about the window and controls it is managing. Therefore, you should attach a layout manager to only one window. If you want to use the same layout manager for a second window, you should create a second copy of the layout manager.

Once attached to a window, a layout manager begins operating.

Parent topic: Working with Layout Managers


Setting LAYOUT-DATA

All controls have a standard property called LAYOUT-DATA. Layout managers optionally use this data to help determine how to lay out the control. Each manager imposes its own interpretation on the meaning of this data.

LAYOUT-DATA is a numeric standard property. It can be set when you create or modify the control. It can also be inquired.

The LAYOUT-DATA values for the resize manager are described in Resize Manager LAYOUT-DATA Values.

Parent topic: Layout Managers


Minimum and Maximum Control Dimensions

All controls have four properties that can be used to describe their minimum and maximum allowed dimensions. Layout managers can use these properties to determine how to size a control. The properties are:

MIN-HEIGHT | The control's minimum height.
MAX-HEIGHT | The control's maximum height.
MIN-WIDTH | The control's minimum width.
MAX-WIDTH | The control's maximum width.

Each of these properties take a numeric value using the same units as the control's SIZE (width) and LINES (height) properties. Each property has a default value of zero. A value of zero for MAX-HEIGHT and MAX-WIDTH means no maximum.

A layout manager uses these values to limit how much it will modify a control's dimensions. A particular layout manager is free to interpret these values to suit its purposes. The resize manager will treat them as absolute limits.

For example, when creating a multiline entry field, you might want to limit its vertical dimension to have both a minimum and maximum height. One implementation might look like this:

DISPLAY ENTRY-FIELD, MULTILINE
      LINE 5, COL 10
      SIZE 50 CELLS, LINES 10 CELLS
      MIN-HEIGHT = 1.5
      MAX-HEIGHT = 20

In this example, the layout manager will not change the height of the entry field to be less than 1.5 cells or more than 20 cells.

The four properties apply to all controls. Like all property names, they are not reserved words. Therefore, you may use these words as user-defined names anywhere in your program where property names are not allowed (that is, outside of the Screen Section and the scope of DISPLAY, MODIFY, and INQUIRE statements).

Typically, you would start out by leaving the properties at their default values. The default values do not constrain the control's dimensions. Then, to address a particular layout problem, you would set one or more of the properties to resolve the problem. For example, you may want to set a minimum height for a control if the user can resize the window such that the unconstrained control is reduced to a height of zero. Or, you may want to limit an entry field to show no more than the total of lines of data it allows.

Parent topic: Layout Managers


The Resize Layout Manager

The resize layout manager is designed to assist with the process of handling resizable windows (a resizable window is a floating window created with the RESIZABLE phrase. It implements some basic rules that automate what happens to controls when a window changes size. While the resize manager handles only some fairly simple cases, the cases are common ones. This frees the programmer to concentrate on more complex cases. See Format 11 DISPLAY FLOATING WINDOW in the ACUCOBOL-GT Reference Manual for more information.

The standard object name of the resize manager is LMRESIZE.

What the resize manager does affects only controls that have non-zero LAYOUT-DATA. Thus, by default, the resize manager has no effect on a window. If you want the resize manager to act on a control, you assign that control a LAYOUT-DATA value that indicates the kind of action you want it to take.

When the resize manager is first attached to a window, it does two things:

  1. It automatically applies the CONTROLS-UNCROPPED style to the window. This is necessary for the resize manager to function properly
  2. It records the current dimensions of the window. These are called the design dimensions. The resize manager uses the design dimensions when deciding how to size and position controls

The essential concept with the resize manager is that the size of the window when it is attached is the "natural" or "design" size of the window. It assumes that all controls placed on the window look right when placed on a window of this size.

For example:

   DISPLAY STANDARD GRAPHICAL WINDOW
      BACKGROUND-LOW
      LINES 25, SIZE 80
      LAYOUT-MANAGER = LAYOUT-1

The resize manager takes effect anytime the window is resized or a control is added to the window. The resize manager acts on any control that has a non-zero LAYOUT-DATA value. The exact value determines what actions the resize manager takes. The resize manager assumes that it has complete control over the size and placement of controls that have LAYOUT-DATA. After such a control has been displayed, the program should not modify it in a way that changes its size or position (that is the job of the resize manager). Doing so may result in improper resizing or repositioning by the resize manager.

Note that a Screen Section control that is subject to the resize manager has its design values set when the control is created.

There is a COPY file that can be helpful when working with the resize manager. It contains a pre-declared layout manager handle (called LM-RESIZE) and constants for the most common combinations of LAYOUT-DATA settings. This COPY library is called lmresize.def.

Tip: The resize layout manager facility is demonstrated in an AcuBench sample project located in the Support area of the Micro Focus Web site. To download the program, go to: http://supportline.microfocus.com/examplesandutilities/index.asp. Select Acucorp Samples > Graphical User Interface > layoutmgr.zip.
Note: .NET controls cannot be managed by the resize layout manager.
  • Resize Manager LAYOUT-DATA Values
Parent topic: Layout Managers


Resize Manager LAYOUT-DATA Values

For the resize manager, a control's LAYOUT-DATA property may be a combination of any of the following values. To combine values, simply add them together. The names of the values come from the lmresize.def file.

RLM-RESIZE-X (value 1) | This causes the control to be resized horizontally by an amount equal to the width of the current window width minus its design width. This causes the control to grow and shrink horizontally as the window changes width. This is frequently useful if you have a control such as a grid or a multi-line entry field in the middle of the window whose area you want to increase as the user grows the window
RLM-MOVE-X (value 2) | This causes the control to reposition itself horizontally by an amount equal to the difference of the current window width and its design width. This is useful when you have a control that you want to keep near the right edge of the window
RLM-NO-MIN-X (value 4) | Without this, the resize manager will not reposition or resize a control horizontally to be less than its design values. This prevents the control from disappearing or colliding with other controls if the user makes the window too small. Instead, the control will extend off the edge of the window if the window is too small. Specifying this value relaxes this rule and the control is allowed to become smaller than its design size or move to the left of its design position. When you use this, you may want to use the MIN-SIZE window property to limit how narrow the user can make the window
RLM-RESIZE-Y (value 16) | Similar to RLM-RESIZE-X, but it affects the vertical size of the control. Only those controls whose height is specified in CELLS or PIXELS are affected. Use this when you want to add more lines to a control such as a grid or list box when the user grows the window. This setting has undefined effects when used for a control whose height does not use CELLS or PIXELS. This may become defined in a future version, so you should avoid specifying this for controls that do not use CELLS or PIXELS
RLM-MOVE-Y (value 32) | Similar to RLM-MOVE-X, except it affects the vertical position of the control. This is useful when you want a control to stay near the bottom edge of the window
RLM-NO-MIN-Y (value 64) | Same as RLM-NO-MIN-X, except that it affects the vertical aspect of the control instead of the horizontal aspect

The following are also found in lmresize.def. These are not unique values, but useful combinations of the preceding values.

RLM-RESIZE-X-ANY | Combines RLM-RESIZE-X and RLM-NO-MIN-X. This combination allows for arbitrary resizing of the control horizontally
RLM-MOVE-X-ANY | Combines RLM-MOVE-X and RLM-NO-MIN-X. This combination allows for arbitrary repositioning of the control horizontally
RLM-RESIZE-Y-ANY | Combines RLM-RESIZE-Y and RLM-NO-MIN-Y. This combination allows for arbitrary resizing of the control vertically
RLM-MOVE-Y-ANY | Combines RLM-MOVE-Y and RLM-NO-MIN-Y. This combination allows for arbitrary repositioning of the control vertically
RLM-RESIZE-BOTH | Combines RLM-RESIZE-X and RLM-RESIZE-Y. This combination allows for the control to resize itself in both dimensions as the window is resized
RLM-RESIZE-BOTH-ANY | Combines RLM-RESIZE-X-ANY and RLM-RESIZE-Y-ANY. This combination allows the control to resize itself in both dimensions and without a minimum size
RLM-MOVE-BOTH | Combines RLM-MOVE-X and RLM-MOVE-Y. This combination keeps a control near the lower right corner of the window
RLM-MOVE-BOTH-ANY | Combines RLM-MOVE-X-ANY and RLM-MOVE-Y-ANY. This combination keeps a control near the lower right corner of the window, with no minimum position

There are other useful combinations, but these are the most common ones.

Parent topic: The Resize Layout Manager


Control Types Reference

  • The Components of a Control
  • Global Styles
  • Control Types
Parent topic: ACUCOBOL-GT User Interface Programming


The Components of a Control

This section describes the components of ACUCOBOL-GT's graphical controls. Included is a description of the common and special properties of each control, along with the global style properties that are valid for all control types. It also includes reference entries for each control type.

To work efficiently with graphical controls, you need to be thoroughly familiar with the components of controls and their organization.

In most instances, controls are simple to create and manage. In some cases they are complex. In addition to the information in this help section, information pertaining to controls is also in:

Graphical Controls

Provides an overview of controls and how they fit into the graphical environment. In addition, it describes the use of the alternate character coordinate phrases, the creation and use of bitmap buttons, and the general use of paged list boxes and paged grids.

Styles and Special Properties

Describes how the compiler recognizes style and special property names based on the context in which they appear.

Screen Section in the ACUCOBOL-GT Reference Manual

Describes the Screen Section syntax used to create controls.

Common Screen Options in the ACUCOBOL-GT Reference Manual

Describes options that are common to Screen Section entries and the ACCEPT, DISPLAY, and MODIFY verbs. Included in this set are the phrases used to specify a control's common properties.

Components

All controls have the following components:

  • A Type
  • A Handle
  • A set of Properties
  • Type
  • Handle
  • Properties
  • Control Components Diagram
Parent topic: Control Types Reference


Type

The compiler recognizes the following control types:

  • ACTIVEX
  • BAR
  • BITMAP
  • CHECK-BOX
  • COMBO-BOX
  • DATE-ENTRY
  • ENTRY-FIELD
  • FRAME
  • GRID
  • LABEL
  • LIST-BOX
  • .NET
  • PUSH-BUTTON
  • RADIO-BUTTON
  • SCROLL-BAR
  • STATUS-BAR
  • TAB
  • TREE-VIEW
  • WEB-BROWSER

Control type names are reserved by the compiler.

Parent topic: The Components of a Control


Handle

When a control is created, a handle to the control is also created. This handle is a COBOL data item. Its value uniquely identifies the control to the system. Handle values are generated dynamically at run time and cannot be controlled by the programmer.

Note: If you want to assign a constant name to a control (a name that remains the same between runs), you can assign an ID to the control. Anytime the runtime system returns information about a control, it includes both its handle and its ID. Because the handle can change from run to run, examining the ID can be more convenient. Note that using IDs is the only effective way to distinguish controls in the Screen Section, because those controls' handles are hidden from the programmer.
Parent topic: The Components of a Control


Properties

All components of a control, excluding the type and handle, are "properties." Control properties are classified into two groups: common properties (those that apply to all types of controls) and special properties (those that are specific to a single type of control). Note, however, that some common properties have a special meaning (or no meaning) for some control types. In addition, some special properties are used by more than one control type. For example, the special properties that apply to bitmap buttons are used also by push button, radio button, and check box controls.

Note: If a control property takes a text value, when the value is sent to the control the run-time system automatically strips trailing spaces and low-values from the value.
  • Common Properties
  • Special Properties
Parent topic: The Components of a Control


Common Properties

Common properties that apply to virtually all controls include: location, size, title, value, color/intensity, font, style, visibility, usability (enabled/disabled), ID, key, and event list.

The function and syntax of each common property is described in Common Screen Options. Any further qualification of a common property for a specific control type is described in the applicable online help.

  • Style
Parent topic: Properties


Style

STYLE is a common property. The STYLE property holds a numeric value. This value is the sum of the numeric values of the individual styles that have been applied to a particular control. Styles affect the appearance or behavior of a control. For example, some of the styles that apply to a radio button include: BITMAP, FRAMED, and NOTIFY. Individual styles have a predefined numeric value (assigned in the file controls.def) and do not take any other value. A style can be applied or not applied. If the style is indicated in a statement, it is applied to the control; if it is absent, it is not applied. Most styles pertain to only a certain type of control, although a few are common to all controls.

There are two ways to specify a style for a control:

  1. Include the style name in the statement that creates the control
  2. Add the style's numeric value to any other style values that apply, and include the sum value in the STYLE IS style-flags phrase, where style-flags is the sum value

Including the style name in the statement that creates the control is the usual method for specifying a style. The collection of style names included in the statement (such as BITMAP and NOTIFY) instructs the Compiler to build the appropriate STYLE property value (the STYLE property is technically the method by which all styles are stored in the run-time system). However, there is an important restriction: the Compiler understands style names only when it knows what kind of control is being built. If you specify a control that has a variable (undefined) type, then you must specify styles with the STYLE IS style-flags phrase. In this case, you construct the STYLE property value by adding together the appropriate style numbers. Each style has a corresponding numeric value, and the STYLE property holds the sum of the specified styles. For example, if the numbers corresponding to BITMAP and NOTIFY were 1 and 4 respectively, the phrase STYLE IS 5 would specify those two styles. Each style's identifying number can be found in the file controls.def (they are level 78 items).

You can use the MODIFY statement to change a style value after a control has been created. However, in many cases the behavior of Windows, limits in the 32-bit Windows API, or restrictions in the ACUCOBOL-GT runtime, prevent a style change from taking effect. Exactly which styles can be effectively changed for each control is not known and is, therefore, not documented. When a style is known to be modifiable or not modifiable, that information is documented with the style. We recommend, however, that you test the behavior of your application in the target environment to confirm that style changes are handled in the way that you expect.

Parent topic: Common Properties


Special Properties

Each control defines its own set of special properties. Special properties are used to give a control a special attribute or capability. For example, an entry field can have the special properties MAX-TEXT, MAX-LINES, and CURSOR.

Special properties are specified with the PROPERTY and Property-Name phrases of the DISPLAY control-type-name described in Procedure Division Statements, or in a Format 2 Screen Section entry. Note that the PROPERTY reserved word always refers to a special property.

All special properties require a value. For example MAX-TEXT takes a numeric value that specifies the maximum number of characters that can be entered in the field.

In any statement in which control properties can be set (that is, the Screen Section and the DISPLAY and MODIFY verbs), you can specify a list of property values in parentheses. This has the effect of setting the specified property to each value in the list, in turn. This is useful for the special properties that can have multiple settings. For example, you can assign the values 20 and 30 to the DATA-COLUMNS list box property with the following syntax:

DATA-COLUMNS ARE ( 20, 30 )

The optional word ARE is allowed in place of IS or = in the syntax.

Because control property values are set in the order specified, if you specify multiple values for a property that can take only a single value, the net effect is the same as setting the last value in the list.

Parent topic: Properties


Control Components Diagram

Parent topic: The Components of a Control


Global Styles

There are several styles that apply to all controls. These styles include:

  • NO-TAB
  • PERMANENT
  • TEMPORARY
  • HEIGHT-IN-CELLS
  • WIDTH-IN-CELLS
  • OVERLAP-LEFT
  • OVERLAP-TOP
Parent topic: Control Types Reference


NO-TAB

This style causes a Tab (or Shift-Tab) key press to skip the control. Normally, while the program is performing a Screen Section ACCEPT, when the user presses Tab or Shift-Tab, the next or previous element in the Screen Section is activated. Specify NO-TAB on controls that you want skipped when these keys are used. This style affects any key with the following editing actions: Default-Next, Erase-Next, Next, Numeric-Next, and Previous. When the program responds to key presses that invoke the above editing

Parent topic: Global Styles


PERMANENT

A permanent control is one that can be destroyed only by the DESTROY verb, or by destroying the window containing the control. By default, controls are permanent. A control can be made temporary using the TEMPORARY_CONTROLS runtime configuration variable.

Permanent controls are more efficient than temporary controls (see TEMPORARY below). The PERMANENT style is applied to a control when it is created and does not change during the life of that control, even if the control's style is modified.

Parent topic: Global Styles


TEMPORARY

A temporary control self-destructs when its home location is overwritten by another control or by textual output. Temporary controls can also be destroyed in the same manner as permanent controls. A temporary control self-destructs in the following circumstances:

  • Another control is created in the exact same location

    The runtime system maintains location information to the nearest 100th of a character cell. If the newly created control is placed in the same row and column as a temporary control (or less than one one-hundredth of a cell away), it destroys the temporary control. Note that moving a control on top of a temporary control does not destroy the control (the runtime system assumes that the temporary control is about to be moved, also. This occasionally happens with Screen Section updates when several items are of variable size). Only a newly created control can destroy a temporary control.

  • Textual output is placed in the same character cell as the temporary cell's home location
    Note: BLANK SCREEN destroys all temporary controls in a window.

The temporary style is applied when a control is first created and does not change during the life of the control. If you attempt to apply both the PERMANENT and TEMPORARY style to a control, the PERMANENT style is used.

A control can also be made temporary using the TEMPORARY_CONTROLS runtime configuration variable.

Parent topic: Global Styles


HEIGHT-IN-CELLS

Normally, the height of a control is expressed in control units. Each control defines its own meaning for these units. Typically, a control that is n units high will be exactly big enough to hold n lines of text. This allows you to specify the size of a control in logical terms without having to know its exact physical representation on the screen. The HEIGHT-IN-CELLS style overrides this behavior. Instead of using control units, you specify the height of the control exactly, using the cell size of the owning window as the base unit. Thus, a height of one (1) would cause the control to be exactly one row tall.

This option is especially useful in sizing frame control objects. The style allows you to specify the frame's exact dimensions without having to know anything about the frame's title font. You can also specify this style with the CELLS option of the LINES phrase. For example:

LINES = 15 CELLS.

This style is not intended for use in combination with a control's default height. Default heights are based on control units, and when based on character cells, do not typically produce useful results.

Parent topic: Global Styles


WIDTH-IN-CELLS

This option is analogous to HEIGHT-IN-CELLS, except that it affects the width of a control. This style is particularly useful when you want to center a label over a region of the screen. By specifying the label's width in cells, and using the CENTER label style, you can easily do the centering without knowing anything about the label's font. For example, if you have a window that is 40 columns wide, and you want to center a title in it, you could use:

DISPLAY LABEL MY-TITLE, COLUMN 10, SIZE 20 CELLS,
   CENTER

Assuming that the title fits in 20 cells, this works for any title in any font.

Parent topic: Global Styles


OVERLAP-LEFT

This style causes the control to be shifted a small amount to the left from its specified position. The amount is equal to the width of the control's border. This shifting occurs when the control is created or moved. If the control does not have a border, no shifting occurs.

The purpose of this style is to simplify placing several similar controls in a row. For example, if you have a series of adjacent push buttons, the normal appearance would be to draw each push button exactly touching each other. This causes a double border to appear between the push buttons. By shifting each one slightly to the left, you can have the borders overlap and achieve a more uniform appearance with a single border between the buttons. Most applications that have adjacent push buttons do this. You can create the same effect by manually positioning the controls with overlapping borders, but using this style is easier and more portable because you don't need to know exactly how wide the borders are.

Parent topic: Global Styles


OVERLAP-TOP

This style is similar to the OVERLAP-LEFT style, except that in this case the control is shifted slightly upward. The amount of the shift is determined by the height of the control's border. This style is useful when you want to create a series of controls that appear to be adjacent to one another in a single column.

Note: A way to achieve a similar effect with entry fields is to use the OVERLAPPED option on the CELL SIZE phrase of the DISPLAY FLOATING WINDOW verb. This method is usually easier to employ than the OVERLAP-TOP style applied to each individual field, because it applies to the whole window.
Parent topic: Global Styles


Control Types

  • ActiveX
  • Bar
  • Bitmap
  • Check Box
  • Combo Box
  • Date Entry
  • Entry Field
  • Frame
  • Grid
  • Label
  • List Box
  • .NET
  • Push Button
  • Radio Button
  • Scroll Bar
  • Status Bar
  • Tab
  • Tree View
  • Web Browser
Parent topic: Control Types Reference


ActiveX

There are two ways to add ActiveX controls to your ACUCOBOL-GT program:

  1. Using the ACUCOBOL-GT utility, AXDEFGEN. This method requires some manual program modification, but it provides the flexibility of adding any type of control or COM object to your program, even non-graphical controls like a spell checker or automation server (like Microsoft Word, Excel, or Internet Explorer). This method involves running AXDEFGEN, adding new COPY files to the project, modifying a few sections of code, and compiling. This is the recommended method if you are required to license ActiveX controls that are deployed with your application: the generated COPY file embeds the required LICENSE-KEY, which is recognised by the compiler when compiling your applications for deployment.
  2. Using the AcuBench Screen Designer. This method is the easiest, but it limits you to only graphical controls. It involves adding the control to the Component Toolbox, drawing it onto the Screen Designer screen form, modifying properties if desired, then generating code. This method is described in detail in the AcuBench User's Guide.

ACUCOBOL-GT defines a control type named ACTIVE-X that it uses internally whenever you CREATE, MODIFY, INQUIRE, or DESTROY an ActiveX control.

In the vast majority of cases, you will not use the ACTIVE-X control type directly. Instead, you will specify the name of the specific ActiveX control type. This name can be determined by looking at the ***Primary Interface*** section in the COPY file generated by AXDEFGEN.

Note: With some noted exceptions, the following documentation applies even when you specify the name of a specific ActiveX control type.
  • Common Properties
  • Special Properties
  • Events
Parent topic: Control Types


Common Properties

This section lists some of the common properties for ActiveX controls.

TITLE

ActiveX controls associate the TITLE property with the Window Text. The effect is dependent on the specific control type.

VALUE

ActiveX controls do not use values.

LINES/SIZE

The LINES and SIZE values describe the area occupied by the ActiveX control, using the ActiveX control’s font to determine the dimensions of the width and height. Note that the control’s font is otherwise ignored by the ActiveX control.

COLOR

ActiveX controls ignore any colors specified. The actual colors used are control-dependent.

AX-EVENT-LIST, EXCLUDE-EVENT-LIST

AX-EVENT-LIST is an exclusive list of ActiveX events that are either sent to or withheld (blocked) from the program, depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

STYLES

  • USE-RETURN

    The Return (or Enter) key typically terminates entry. If you specify the USE-RETURN style, the Return key is instead used by the ActiveX control when it is active. For example, if the ActiveX control is a text editor or if it offers a command prompt, the USE-RETURN style would allow the user to start a new line by pressing Return. Without this style, pressing Return would terminate input.

  • USE-TAB

    The Tab key is typically used to move between fields or controls. If you specify the USE-TAB style, the Tab is instead used by the ActiveX control, when the control is active. This allows the user to enter a tab into the ActiveX control, but prevents the user from using the Tab key to leave the control.

  • USE-ALT

    The user can normally activate a control by typing its key letter in combination with some other special key. Under Microsoft Windows, key letters are typed in conjunction with the Alt key. If you specify the USE-ALT style, the Alt key is instead used by the ActiveX control when it is active. This allows the user to enter an Alt key combination into the ActiveX control, but prevents the user from using an Alt key combination to activate another control.

Parent topic: ActiveX


Special Properties

CLSID (alphanumeric)

This special property is provided for advanced programming tasks that require a generic interface to ActiveX controls. You may create, modify, inquire and destroy an ActiveX control using the ACTIVE-X control type, but with certain restrictions. The compiler will not recognize symbolic property, method, or event names provided by the ActiveX control. You must specify properties and methods by their dispatch identifier (dispid) using the PROPERTY phrase, and you must identify events by their dispatch identifier in your event procedure. ACTIVE-X controls are identified by a globally unique identifier called a class id (CLSID). In order to create an instance of an ACTIVE-X control, you must provide this class id. Set CLSID to the class id of the control when you create the control (either in the screen section definition or in the DISPLAY statement).

LICENSE-KEY (alphanumeric)

Some ActiveX controls require a deployment license that is different than the development license. The vendor may or may not include that deployment license as part of the control's installation, depending on the ability of the appropriate development tool to discover that deployment license and embed it in the application. AXDEFGEN is able to discover the deployment license, and set a LICENSE-KEY property in the generated COPY file. In this case, your application is ready for distribution with only the ActiveX control.

INITIAL-STATE (multiple parameters)

Use INITIAL-STATE in conjunction with the C$RESOURCE library routine to establish the ActiveX control's initial state.

{ INITIAL-STATE } { Is  } ( resource-handle, resource-name )
                  { Are }
                  { =   }

where:

resource-handle | is a HANDLE OF RESOURCE
resource-name | is a literal or data-item

General Rules

  • resource-handle must be the handle of an open resource file. It is obtained by calling the C$RESOURCE library routine
  • resource-name must be the name of a resource item in the resource file whose handle is specified in resource-handle
  • INITIAL-STATE is set only once per control instance. After a program creates an ActiveX control, only the first DISPLAY or MODIFY that specifies INITIAL-STATE will set it
  • INITIAL-STATE failure raises one of the following exceptions:
    ACU-E-INITIALSTATE | Error reading resource item from resource file
    ACU-E-INVALIDHANDLE | Invalid control handle
    ACU-E-UNEXPECTED | Unexpected error

Example

77 RES-HANDLE USAGE HANDLE OF RESOURCE

CALL "C$RESOURCE" USING CRESOURCE-LOAD, "PROGRAM1.RES"
   GIVING RES-HANDLE.

To set the ActiveX control's initial state:

DISPLAY Calendar LINE 4 COLUMN 6 LINES 10 SIZE 40
   INITIAL-STATE (RES-HANDLE, "CALENDAR-1-INITIAL-STATE")
   HANDLE IN CALENDAR-1.

or in the screen section:

03 CALENDAR-1 Calendar LINE 4 COLUMN 6 LINES 10 SIZE 40
   INITIAL-STATE (RES-HANDLE, "CALENDAR-1-INITIAL-STATE").

CALENDAR-1-INITIAL-STATE is the name of a resource in PROGRAM1.RES. Its binary value is the initial state of the CALENDAR-1 ActiveX control. Note that each program that contains ActiveX controls generally has its own resource file.

Parent topic: ActiveX


Events

CMD-GOTO
CMD-HELP
MSG-VALIDATE
MSG-AX-EVENT
Parent topic: ActiveX


Bar

The BAR control draws a line on the screen. The line can be either horizontal or vertical, and can be any width. Several options allow you to produce special effects such as double lines and raised or engraved lines. Additional options allow lines to be joined together to form rectilinear objects and shapes.

The bar control is available for both character-based systems and graphical environments. However, on character-based systems, the DOTTED, DASHED, and DOT-DASH styles are not supported. The following special properties are also not supported on character systems: WIDTH, COLORS, SHADING, POSITION-SHIFT, TRAILING-SHIFT, and LEADING-SHIFT.

In a graphical environment, the bar control covers any portion of text that occupies the same space as the bar. In a character-based environment, the bar does not cover the text, and it is displayed as a broken line.

Bar controls are drawn in the order created. This can be important when you are overlapping bars to create junctions.

  • Common Properties
  • Special Properties
  • Events
Parent topic: Control Types


Common Properties

The set of bar common properties includes:

TITLE

A bar does not have a title .

VALUE

A bar does not have a value.

SIZE

The SIZE and LINES values of a bar are measured in window cells. One of the SIZE or LINES phrases must be zero (or unspecified). If LINES is zero, the bar is horizontal. If SIZE is zero, the bar is vertical. Setting SIZE and LINES to non-zero values has an undefined effect.

COLOR

A bar uses only the foreground color. The foreground color is the color of the entire bar. See the COLORS special property for other options.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

STYLES

A bar does not have styles in a character-based operating system. In a graphical system, a bar can have the following styles:

DOTTED | This style creates a dotted line instead of a solid line. It is a valid style only when the bar's width is one. The COLORS and SHADING properties are ignored when this style is specified. The line is drawn with the control's foreground color. This style is not available on character-based systems.
DASHED | This style creates a dashed line instead of a solid line. It is valid only when the bar's width is one. The COLORS and SHADING properties are ignored when this style is specified. The line is drawn with the control's foreground color. This style is not available on character-based systems.
DOT-DASH | This style creates a line that alternates dots and dashes. It is valid only when the bar's width is one. The COLORS and SHADING properties are ignored when this style is specified. The line is drawn with the control's foreground color. This style is not available on character-based systems.
Parent topic: Bar
Related concepts
Cascading Style Sheet Syntax


Special Properties

WIDTH (numeric)

This special property specifies the width (thickness) of the bar. Normally, bars are 1-pixel wide. You can set the width to any number of pixels. For example, WIDTH = 5 creates a bar that is 5 pixels wide.

COLORS (numeric)

This property allows you to set the color of an individual pixel row or column in the bar. The COLORS property can be set multiple times. The first value assigned describes the color of the topmost pixel row in a horizontal bar, or the left-most pixel column in a vertical bar. The second setting describes the next pixel row or column, and so on. The value must be the absolute color number you want to use, ignoring any high or low intensity settings for the bar. Usually, you would specify all of the desired colors at once by enclosing the values in parentheses. For example, to create a black double line that is three pixels wide, with a bright-white interior, you would specify the following:

DISPLAY BAR, WIDTH = 3, COLORS = ( 1, 16, 1 ), . . .

Any pixel rows or columns that are not specified by the COLORS property are given the bar’s foreground color. You can reset the COLORS property to an empty list by assigning a value of 999 or higher. This special property is not available on character-based systems.

SHADING (numeric)

This special property allows you to vary the color of individual pixel rows or columns. This works similarly to the COLORS property, but instead of specifying a color, you specify a number that indicates how you would like to adjust the color. The possible values are as follows:

2 | Use color 16 (typically bright white)
1 | Brighten the normal color
0 | Leave the normal color unchanged
-1 | Darken the normal color
-2 | Use color 1 (typically black)

In the preceding table, normal color refers to the color the pixel row or column would otherwise have (as determined by the control's foreground color or the COLORS property). Color shading (values 1 and -1) works for only colors in the default palette and the colors generated by the USER-GRAY, USER-WHITE, and USER-COLORS window options. If you place other colors into the palette, the shading options have no effect.

You can use shading to simplify the process of creating a 3-D line. For example, to create a thin gray engraved line, you might use

DISPLAY BAR, COLOR WHITE, LOW, WIDTH = 2,
    SHADING = ( -1, 1 )

To produce a raised line, simply reverse the shading order:

SHADING = ( 1, -1 )

This special property is not available on character-based systems.

POSITION-SHIFT (numeric)

This property specifies an adjustment to the bar’s position. Positive values move the bar down (for horizontal bars) or to the right (for vertical bars) by the specified number of pixels. Negative values shift the bar upward or leftward instead. The purpose of this property is to simplify manual positioning of a bar when cell measurements are inconvenient. One use is to aid in joining two thick bars to make a corner. For example, to make the lower right half of a box that is 5 cells high and 10 cells wide with a 3-pixel border, you could use:

DISPLAY BAR,  WIDTH = 3,  LINE 1,  placeStateCOL 11,  LINES 5
DISPLAY BAR,  WIDTH = 3,  LINE 6,  placeStateCOL 1,  SIZE 10,
              POSITION-SHIFT = -3

Using the POSITION-SHIFT special property produces a square corner instead of a jagged one. This special property is not available on character-based systems.

TRAILING-SHIFT (numeric)

This special property adjusts the length of each pixel row or column. This is used for special case handling when joining lines together. Similar to the COLORS and SHADING properties, TRAILING-SHIFT can be set multiple times. Each setting affects the next pixel row or column in the bar. The values assigned to TRAILING-SHIFT adjust the ending point of the bar. The ending point is the right-most point for horizontal bars or the uppermost point for vertical bars. A positive TRAILING-SHIFT value extends the pixel row that many pixels. A negative value reduces the pixel row instead. For example, if you want a 3-pixel wide line to end like this:

you would use the following property:

TRAILING-SHIFT = ( 0, 1, 2 )

You can reset the TRAILING-SHIFT property to an empty list by assigning a value of 999 or higher. Generally speaking, TRAILING-SHIFT is most useful when joining two lines having more than one color together to form a corner. This special property is not available on character-based systems.

LEADING-SHIFT (numeric)

This property adjusts the length of each pixel row or column in a manner similar to TRAILING-SHIFT. However, LEADING-SHIFT differs in two ways from TRAILING-SHIFT. First, the effect applies to the starting point of the line, instead of the trailing, i.e., the topmost (vertical) or left-most (horizontal) point. Secondly, negative values lengthen the line while positive values shorten the line. Essentially, each value is added to the ending point coordinate to determine the actual coordinate. This special property is not available on character-based systems.

Parent topic: Bar


Events

Bars do not generate events.

Parent topic: Bar


Bitmap

Using the BITMAP control, a user can place a bitmap on the screen. The effect is similar to using the W$BITMAP library routine. However, with the bitmap control, your bitmap can be animated.

The bitmap control is available only for Microsoft Windows systems. Any attempt to place a bitmap on the screen in other systems fails, and the returned handle is NULL.

To display a bitmap, you must first load it with the W$BITMAP library routine, using the WBITMAP-LOAD option. This operation retrieves the bitmap from disk and loads it into memory. The process is identical to loading bitmaps for bitmap push buttons.

  • Common Properties
  • Special Properties
  • Events
Parent topic: Control Types


Common Properties

TITLE

Bitmaps do not have titles.

VALUE

A bitmap does not have a value.

SIZE

SIZE and LINES are measured in pixels. The specified number of pixels are displayed, starting from the upper left-hand corner of the bitmap (for an exception to this, see the BITMAP-NUMBER special property). If SIZE and LINES are not specified, the entire bitmap is used.

COLOR

This property is ignored. The bitmap is displayed using the colors encoded in the image.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

Parent topic: Bitmap
Related concepts
Cascading Style Sheet Syntax


Special Properties

BITMAP-HANDLE (numeric)

This property indicates the bitmap to display. The value must correspond to the bitmap handle returned by the WBITMAP-LOAD option of W$BITMAP. If this value is omitted, the control uses the bitmap most recently loaded by W$BITMAP.

BITMAP-NUMBER (numeric)

Use this property to display an image from a bitmap strip. A bitmap strip is a series of images of equal width that are strung together horizontally in a single bitmap file. The value of this property is the number of the image in the strip, beginning on the left with 1. You can identify a particular image if you specify the width of the logical image with the SIZE phrase and the number of the image with the BITMAP-NUMBER property. The default value for this property is 1.

BITMAP-NUMBER is updated by the runtime to reflect the current image shown when an animated bitmap is displayed. You can retrieve this value with the INQUIRE verb.

BITMAP-RAW-HEIGHT (numeric)

This property may not be invoked before the property BITMAP-HANDLE has been set to a valid bitmap loaded with WBITMAP-LOAD. The value returned is the image height in device-independent pixels.

The value is read only, any attempt to MODIFY will fail. The receiving variable should take into account a possible image size of 5 digits (PIC 9(5)). The receiving datatype typically is an integer, but any numeric value is accepted.

BITMAP-RAW-WIDTH

This property may not be invoked before the property BITMAP-HANDLE has been set to a valid bitmap loaded with WBITMAP-LOAD. The value returned is the image width in device-independent pixels. The value is read only, any attempt to MODIFY will fail. The receiving variable should take into account a possible image size of 5 digits (PIC 9(5)). The receiving datatype typically is an integer, but any numeric value is accepted.

BITMAP-SCALE

This property is used to enable resizing of bitmaps. If not set, or set to its default value of 0, the bitmap cannot be resized. This means if the size of the interior of the image is smaller than the image, the image is cut to fit. If the interior is larger than the image size, the image size does not increase to fill the interior.

If set to 1, the bitmap will scale up or down to fit the interior given, and no cutting of the bitmap occurs.

When setting this property, you must set it prior to setting the property BITMAP-HANDLE to have any effect. For example:

SCREEN      SECTION.
01  TEMPLATE-SCREEN.
  03      bmp              BITMAP
          BITMAP-SCALE     1
          BITMAP-HANDLE    GT-BITMAP
          SIZE             100 pixels
          LINES            200 pixels
          LINE             1
          placeStateCOL              1.

With this new property, if you perform a MODIFY statement such as

MODIFY bmp SIZE = 200 LINES = 400.

the bitmap is resized accordingly and automatically. Note that you are not limited to specifying pixel units; you may specify any legal display unit.

Important:

To keep the image from becoming blurred in the resizing process, do not scale up or down in just one direction. For example, if you have an image that is 200x300, increase or decrease the width and height, not just one or the other.

If you enter an invalid resizing value for either the width or height, the invalid entry will be ignored and the previous width or height value will be used.

Resizing images is based on the image size, not the interior size. With multiple resizes, you always will be resizing based on the original image size, not the last resizing that you performed. This is done to maintain the best image quality, as resizing a resized image can degrade image quality.

Currently, only 24-bit colors are supported. If your bitmap is not 24 bit, you can use Microsoft paint to store the bitmap as 24 bit.

We recommend that jpeg files be used whenever possible, as they appear to give the best resizing capability.

BITMAP-START and BITMAP-END (both numeric)

These properties are used when you want to animate a bitmap. Like BITMAP-NUMBER, the value of BITMAP-START is the number of a particular image in a bitmap strip, specifically, the first one to use during animation. Animation runs sequentially in the strip from BITMAP-START to BITMAP-END, looping back to BITMAP-START. If BITMAP-START is not set smaller than BITMAP-END, the control sets BITMAP-START equal to BITMAP-END. The default value for each property is 1.

BITMAP-TIMER (numeric)

This property is used for bitmap animation. Its value is the amount of time each bitmap image is displayed during animation, in hundredths of seconds. When this property is set to 0, the bitmap is not animated. Setting the property to a negative value has an undefined effect.

TRANSPARENT-COLOR (numeric)

Use this special property to designate transparent regions in a bitmap. This is done by reserving one of the colors in the bitmap as the transparent color. Any points in the bitmap that contain this color will not be displayed when the bitmap is drawn, allowing the background to show through. This can be useful if you want to integrate a logo onto a screen in a way that accommodates the user's choice of desktop colors.

To designate a transparent region, choose one color in the bitmap to be the transparent color. Then, set the TRANSPARENT-COLOR property to the RGB color value of this color. The RGB color value is computed by the following formula:

   (red * 65536) + (green * 256) + blue

where red, green, and blue are values between 0 and 255. You can use a hexadecimal numeric literal to express this value, because each component of the color occupies one byte in a binary value. For example, the following literal expresses an orange color with red at 255, green at 128, and blue at 0:

78  orange    value x#FF8000.

The first byte (x 'FF') is the red value, the second byte (x'80') is the green value, and the last byte (x'00') is the blue value.

If you set TRANSPARENT-COLOR to -1 (the default), the transparency property is turned off and all colors display normally.

Setting TRANSPARENT-COLOR to the hex value x#1000000 will automatically specify the pixel in the upper-left corner of a bitmap as the transparent color. (This is the level 78 constant BM-CORNER-COLOR in acugui.def.) You don't need to know the exact color of that pixel to use this value.

In order to avoid flashing, the runtime will not update the region under a transparent bitmap once it is in place. One effect of this is that if you animate a bitmap with transparent regions, you must ensure that those regions are the same in each frame of the animation, or the image will blur.

Parent topic: Bitmap


Events

Bitmaps do not generate events.
Parent topic: Bitmap


Check Box

The CHECK-BOX control provides a box that the user can check or uncheck. These controls typically present a series of options that can be independently enabled.

  • Common Properties
  • Special Properties
  • Events
  • Examples
Parent topic: Control Types


Common Properties

The set of check box common properties includes:

TITLE

Check boxes may have titles. The title typically appears to the right of the check box. The TITLE phrase is used to specify the title. A key letter may be specified in the title. See Common Screen Options for more information.

VALUE

Check boxes have numeric values. A value of 0 indicates the absence of a check mark. A value of 1 indicates the presence of a check mark.

SIZE

The LINES and SIZE values describe the size of the check box's title area. The LINES value specifies the number of lines tall the title area will be. The SIZE value specifies the width of the title area, using the width of the 0 (zero) character as the base unit. Added to the title area is overhead needed for the actual check box. This usually adds several character positions to the width, and may affect the height if the check box is taller than the title's font.

When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.

LINES has a default value of 1. The default value of SIZE is computed by measuring the length of the title using the check box's font and dividing by the width of the 0 (zero) character. Thus, the default width of a check box exactly occupies the space its text takes up on the screen.

When the BITMAP style is used, the LINES and SIZE values have a different meaning. The values are the number of pixels in the height and width of the bitmap image. If omitted, the default values depend on the host system. Under Microsoft Windows, the default LINES value is 15 and the default SIZE value is 16. These correspond to the size of buttons typically found on a toolbar. See Creating a Paged List Box for more information.

COLOR

Check boxes use both the foreground and background colors specified. If either is omitted, the corresponding color of the check box's owning subwindow is used.

Bitmap check boxes do not use the specified colors. Instead, the colors are derived from the bitmap and the system defaults for push buttons

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

TEXT-ONLY

Check box controls can appear and behave similar to toggle push buttons. Use the TEXT-ONLY property to have the check box behave similar to a push button. Setting this style will override the bitmap property if set.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

STYLES

BITMAP | Causes the check box to be drawn with a bitmap instead of its normal appearance. See Paged List Boxes for a complete description.
FRAMED | Used only with bitmap buttons, it requests that a thin frame be drawn around the button. Typically this appears as a thin black line. Not all systems support frames, in which case the request is ignored. By default, buttons are framed under Windows NT/Windows 2000.
UNFRAMED | Used only with bitmap buttons, it requests that the button be drawn without a frame. Not all systems support unframed buttons, in which case the request is ignored. By default, buttons are not framed under Windows 98.
SQUARE | Used only with framed bitmap buttons, it forces the button to have square corners. Without this style, the button will have slightly rounded corners.
SELF-ACT | Creates a self-activating check box. A SELF-ACT check box behaves in the same way as a SELF-ACT push button. Self-activating check boxes return control to the previously active control or window when they are clicked. Typically, you will want to use the NOTIFY style (below) in conjunction with SELF-ACT, so that your program is informed whenever the check box is clicked.
NOTIFY | Tells the run-time to generate a CMD-CLICKED event whenever the value of the check box is changed by the user. This allows your program to respond immediately to the change. In essence, the check box acts like a combination check box and push button. Without the NOTIFY style, the check box remains active after it has been changed (exception: see SELF-ACT above.)
LEFT-TEXT | Check boxes with this style display their text to the left of the box instead of to the right. Note that if you use this style and try to vertically align several check boxes, the boxes may not align vertically. This is because the default behavior of the run-time is to place the right edge of the check box at the minimum distance needed from its left edge to accommodate the control's text. This results in the boxes being placed in different columns depending on the text of each control. Supplying a uniform width using the SIZE property overrides this behavior.
FLAT | On Windows systems, and only when a bitmap is used, this style creates a check box without visible borders. On non-Windows systems, this style has no effect.
MULTILINE | Causes the check box to have a multi-line title. When the MULTILINE style is applied, the check box's title text is automatically word wrapped to fit the check box's size. You can force a line break in the text by embedding an ASCII line feed character (h"0A"). The MULTILINE style is ignored in character-based environments.
VTOP | Causes the title text to be vertically aligned with the top of the control's area. By default, the title text is vertically aligned to the center of the control's area.
Parent topic: Check Box
Related concepts
Cascading Style Sheet Syntax


Special Properties

BITMAP-NUMBER (number)

This property identifies the particular bitmap image to use with the check box. If you explicitly name this property when creating the control, the BITMAP style is automatically applied by the compiler. Note that this does not occur if you use the PROPERTY phrase to specify this property (by giving its identifying number). See Paged List Boxes for more information.

BITMAP-HANDLE (handle)

This property identifies the bitmap image strip to use with the check box.

TERMINATION-VALUE (numeric)

This property works in a manner identical to the push button property of the same name (see Special Properties paragraph for the push button control. This property is used only when the NOTIFY style is also used. The compiler applies the NOTIFY style automatically if this property is named when the control is created. Note that the NOTIFY style is not automatically applied if you use the PROPERTY phrase to specify this property (by giving its identifying number). See Push Button for more information.

EXCEPTION-VALUE (numeric)

This property works in a manner identical to the push button property of the same name. This property is used only when the NOTIFY style is also used. The compiler will apply the NOTIFY style automatically if you explicitly name this property when you create the control. Note that the NOTIFY style is not automatically applied if you use the PROPERTY phrase to specify this property (by giving its identifying number).

Parent topic: Check Box


Events

CMD-CLICKED
CMD-GOTO
CMD-HELP
MSG-VALIDATE
Parent topic: Check Box


Examples

The following creates a simple check box:

DISPLAY CHECK-BOX, TITLE "Option &1",
        HANDLE IN CHECK-BOX-1.

Here is the Screen Section equivalent:

03 CHECK-BOX, "Option &1".

In this example, the check box starts out with a check mark in it:

DISPLAY CHECK-BOX "Option &2", VALUE 1,
        HANDLE IN CHECK-BOX-2.

It is common in Screen Section entries to assign a VALUE data item to the box so that you can set and test the check box:

03 CHECK-BOX, "Option &3", USING OPTION-3-FLAG.

Here is a check box that can be dynamically disabled (grayed-out):

03 CHECK-BOX, "Option &4", USING OPTION-4-FLAG,
         ENABLED = BOX-4-ENABLED-FLAG.
Parent topic: Check Box


Combo Box

A COMBO-BOX control provides the features of a list box and entry field combined. The user may enter data into the entry field directly, or may select a value from a list.

  • Common Properties
  • Special Properties
  • Events
  • Using Special Keys
  • Examples
Parent topic: Control Types


Common Properties

The set of combo box common properties includes:

TITLE

Combo boxes do not have titles.

VALUE

Alphanumeric values that represent the data in the entry field portion of the control. For combo boxes with the DROP-LIST style, the value represents the selected list item. In this case, the handling of the value is the same as for list boxes.

SIZE

Describes the width of the entry field portion of the combo box. SIZE is calculated using the standard width of the font selected. The LINES value describes the number of lines shown in the combo box. The entry field portion of the box counts as one of the lines. The remaining lines are part of the list box. Any overhead needed for boxes and other sub-controls (such as scroll bars) is added to these values. Note that a vertical scroll bar is automatically added when the number of items in the list exceeds the value of LINES.

The default LINES value is 5. The default SIZE value depends on whether or not a VALUE is specified when the combo box is created. If a VALUE is specified, the default SIZE value equals the size of the VALUE literal or data item. Otherwise, the default SIZE is 12.

On non-graphical systems, to show less data in the combo box than is present in the data items, set SIZE to the desired width and MAX-TEXT to the length of the longest data item.

When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.

COLOR

Any foreground and background colors specified in the program are used. If the background color is not specified, the owning subwindow's background color is used. If the foreground color is not specified, a system-default color is used. Note that color handling in combo boxes is tricky, because there are several components that make up a control. You will not be able to control all of the colors shown using just foreground and background colors. For this reason, we suggest using the default colors.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options in the ACUCOBOL-GT Reference Manual for more information.

Styles

DROP-DOWN | Indicates that the list portion of the control is normally hidden. To see the list, the user pushes a button shown beside the entry field portion, causing it to drop down from the entry field. This is the default style.
STATIC-LIST | Causes the list to be permanently displayed on the screen.
DROP-LIST | Similar to the DROP-DOWN style, except that the entry field is replaced by a static display of the currently selected list item.
UNSORTED | This style is the same as the list box style of the same name.
3-D | This style behaves identically to the 3-D entry field style of the same name.
LOWER | This style converts all the text in the box to lower-case.
UPPER | This style converts all the text in the box to upper-case.
NOTIFY-DBLCLICK | This style causes the combo box to generate CMD-DBLCLICK events. Normally, double-clicking on an item in the combo box has no special effect. If you specify this style, double-clicking on an item will generate a CMD-DBLCLICK event. This will usually terminate the current ACCEPT statement and allow your program to act on the selection immediately. You can also use an embedded EXCEPTION PROCEDURE in the Screen Section to perform immediate processing. Note that this style is generally useful only for STATIC-LIST style boxes, because the other types of combo boxes close their drop-down list as soon as the user clicks an item (effectively preventing the ability to perform a double-click). See also the TERMINATION-VALUE and EXCEPTION-VALUE properties for related topics
NOTIFY-SELCHANGE | This style causes the combo box to generate NTF-SELCHANGE events. Normally, selecting an item in the combo box has no special effect. If you specify this style, a selection change will generate an NTF-SELCHANGE event. This allows your program to act immediately on the new selection.
Parent topic: Combo Box
Related concepts
Cascading Style Sheet Syntax


Special Properties

MAX-TEXT (numeric)

This property is the same as the entry field property of the same name.

ITEM-TO-ADD (alphanumeric)

This property is the same as the list box property of the same name.

MASS-UPDATE (numeric)

This property behaves the same as the list box property of the same name.

RESET-LIST (numeric)

This property is the same as the list box property of the same name.

ITEM-TO-DELETE (numeric)

This property is the same as the LIST BOX property of the same name.

INSERTION-INDEX (numeric)

This property is the same as the list box property of the same name.

TERMINATION-VALUE (numeric)

This property produces the same behavior as the TERMINATION-VALUE push button property, except that it acts on the CMD-DBLCLICK event instead of the CMD-CLICKED event. This property is used only when the NOTIFY-DBLCLICK style is also used. The compiler applies the NOTIFY-DBLCLICK style automatically if this property is explicitly named when the control is initially created. Note that this does not occur if you use the PROPERTY phrase to supply the property value (by giving its identifying number).

EXCEPTION-VALUE (numeric)

This property produces the same behavior as the push button property of the same name, except that it acts on the CMD-DBLCLICK event instead of the CMD-CLICKED event. This property is used only when the NOTIFY-DBLCLICK style is also used. The compiler applies the NOTIFY-DBLCLICK style automatically if this property is explicitly named when the control is initially created. Note that this does not occur if you use the PROPERTY phrase to supply the property value (by giving its identifying number).

Parent topic: Combo Box


Events

CMD-DBLCLICK
CMD-GOTO
CMD-HELP
MSG-VALIDATE
NTF-SELCHANGE
Parent topic: Combo Box


Using Special Keys

When a combo box has the input focus, the Home and End keys position the cursor at the beginning or end of a line of text. The Page-Up and Page-Down keys can be used to scroll the combo box. Setting KEYSTROKE configuration entries does not affect these actions.

Parent topic: Combo Box


Examples

The first example creates a drop-down combo box (the default style) that contains a one-line entry field and a four-line list box (total of five lines):

DISPLAY COMBO-BOX, LINES 5, HANDLE IN COMBO-BOX-1.

Here is the Screen Section equivalent. This definition also specifies a data item in which the combo box choice will be stored:

03 COMBO-BOX-1, COMBO-BOX, TO COMBO-BOX-DATA, LINES 5.

Here is an example of code that adds 10 items to the combo box:

PERFORM VARYING IDX FROM 1 BY 1 UNTIL IDX > 10
    MODIFY BOX-1, ITEM-TO-ADD = BOX-DATA( IDX )
END-PERFORM.

The following combo box does not use a drop-down list (the list is always displayed):

03 COMBO-BOX, USING BOX-DATA, STATIC-LIST, LINE 5,
    COLUMN 40, SIZE 20, LINES 8.
Parent topic: Combo Box


Date Entry

The date entry control provides a convenient way for users to enter date or time values. The date entry control always stores a complete date and time, even though, in most cases, only a portion of this information is shown to the user. The control's initial value is the date and time that the control is created.

The date entry control includes the following special features for date and time handling:

  • An integrated drop-down calendar from which users can select a date
  • Standard date validation
  • Flexible date and time formatting options
  • A display format independent of the one used by your program to store dates and times
  • In some instances, automatic localization

Because the date entry control is a Microsoft control, there are certain restrictions that apply to its use:

  • The control can be used only in Microsoft Windows environments.
  • Users of Windows NT 4.0 must have Internet Explorer 3.0 or later installed on their system. This restriction does not apply to later versions of the Windows NT operating system.
  • The earliest date supported is January 1, 1752.
  • There is no way to change the color of the control. The control always uses the current system colors.
  • The control has a 3-D border. This can be changed only on Windows XP systems, which allow you to add an application manifest for the control. Information about application manifests and Windows XP is available from Microsoft.
  • Because the date entry control has an intrinsic 3-D appearance, screens containing this control look best if you use the WIN32_3D configuration option for your other 3-D. This creates a consistent appearance.
  • The date entry control does not have an autoterminate capability, so the user must use the arrow keys or separator keys (such as / or -) to move between the various fields of a date or time entry.
  • Common Properties
  • Special Properties
  • Examples
Parent topic: Control Types


Common Properties

TITLE

Date entry controls do not use the TITLE property.

VALUE

The date entry control stores a value that is a complete date and time. The format of this value as seen by your program varies depending on the VALUE-FORMAT property. The initial value for the control is the date and time the control is created.

Although the value of the control is alphanumeric, usual practice is to treat the value as if it were numeric, setting and retrieving its value using numeric variables. The run-time system and the control perform any necessary conversions.

The control does not usually allow invalid date or time values. This can be circumvented with the SHOW-NONE style.

SIZE

Date entry controls determine height using a combination of font height plus overhead of roughly 50 percent for the box and 3-D effect. The default LINES setting is 1.

Date entry controls calculate width by multiplying the SIZE setting by the standard width of the font and then adding overhead for the box, 3-D effect, and calendar drop-down button. In most cases, you will get good results by setting the SIZE roughly equal to the number of characters in the formatted display. The default SIZE value is 8.

Note that a date entry control automatically makes small adjustments to its specified size and position in order to better align with other ACUCOBOL-GT controls that use the 3-D format

COLOR

Date entry controls ignore any specified color settings. The actual colors displayed are chosen by end-users in the Windows Control Panel. This may result in an unusual appearance if a date entry control is added to a screen that uses custom colors. The limitation is inherent to the underlying control.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

STYLES

CENTURY-DATE | Uses nearly the same format as the SHORT-DATE style, but the year portion always appears as four digits, even if the user has specified a two-digit format in the Windows Control Panel. Users must have Internet Explorer 5.0 or later installed to use this style successfully.
LONG-DATE | Causes the date entry control to display a localized long date format. The exact format of the long date depends on settings specified by the user in the Windows Control Panel. In the United States, a common long date format is Monday, February 16, 2004.
NO-F4 | By default, the date entry control lets users open the calendar using the F4 key. This style prevents the control from using this shortcut, reserving this key for your program's use. Note that the Alt+Down Arrow key combination also opens the calendar.
NO-UPDOWN | By default, the date entry control lets users scroll through the valid values for each portion of the date or time using the up and down arrow keys. This style disables these functions, reserving the arrow keys for your program's use. Note that users can still scroll through values in the date entry control using the + and - keys on the numeric keypad.
NOTIFY-CHANGE | Causes the date entry control to generate an NTF-CHANGED event each time the user changes the displayed date or time. If this style is not specified, the program is informed of a new value in the control only when the user leaves the field or performs a terminating event (like pressing a function key).
RIGHT-ALIGN | Causes the drop-down calendar to be roughly aligned with the right edge of the date entry control. By default, the calendar is aligned with the left edge of the control.
SHORT-DATE Causes the date entry control to display a localized short date format. The exact format of the short date depends on settings specified by the user in the Windows Control Panel. In the United States, a common short date format is 02/16/2004.

If no other format is specified, the control will default to the SHORT-DATE format.

SHOW-NONE Adds a check box to the date entry control. When the check box is checked, the control contains a valid date and/or time. When the check box is not checked, the control behaves as if it had no value, returning all zeroes instead of a date, or all nines instead of a time.

If you have created a date entry control with the SHOW-NONE style, you can programatically cause the check-box to be unchecked and the value to appear grayed out by setting a date of zero or a time of all nines. Likewise, by setting a valid date or time, you can cause the check-box to appear checked and the value to appear normally.

To create a date entry control that uses the SHOW-NONE style and starts with no date or no time, for example, you could use one of the following statements:

DISPLAY DATE-ENTRY, SHOW-NONE, VALUE ZERO
DISPLAY DATE-ENTRY, SHOW-NONE, VALUE 999999

Note that the 999999 in the second example assumes the default HHMMSS time format.

SPINNER By default, a date entry control displays the date with a button used to open a drop-down calendar. When you specify this style, that button is replaced with small up and down arrows that can be used to modify each portion of the date without referring to the calendar.

The spinner arrows appear by default when the date entry control displays a time format.

TIME Causes the control to show a localized time format. The exact format depends on settings specified by the user in the Windows Control Panel. 10:35 AM is a typical format.

If this style is set when the control is created, the VALUE-FORMAT property is given the default value DAVF-HHMMSS. See the description of the VALUE-FORMAT special property for more information.

Parent topic: Date Entry
Related concepts
Cascading Style Sheet Syntax


Special Properties

CALENDAR-FONT (handle)

Set this property to the handle of the font that you would like to use in the drop-down calendar. If no value is specified, the calendar uses the same font as the rest of the control.

DISPLAY-FORMAT (alphanumeric)

This special property gives you the ability to display a custom date and time format. When this property is set, its value takes precedence over any SHORT-DATE, CENTURY-DATE, LONG-DATE, or TIME settings that have been specified.

This property takes a string combining coded fields and quoted literals as its value. The literals are displayed exactly as specified and are set off by single quotation marks ' '. The coded fields are replaced as shown in the following table:

d | Numeric day of the month, no leading zeros
dd | Numeric day of the month, with leading zeros
ddd | Three-letter abbreviation for the day of the week
dddd | Full name of the day of the week
M | Numeric month, no leading zeros
MM | Numeric month, with leading zeros
MMM | Three-letter abbreviation for the month
MMMM | Full name of the month
y | Last two digits of the year, without leading zeros if less than 10
yy | Last two digits of the year
yyyy | All four digits of the year
h | Hours without leading zeros (12-hour clock)
hh | Hours with leading zeros (12-hour clock)
H | Hours without leading zeros (24-hour clock)
HH | Hours with leading zeros (24-hour clock)
m | Minutes without leading zeros
mm | Minutes with leading zeros
s | Seconds without leading zeros
ss | Seconds with leading zeros
t | One-character time-marker string (for example, a and p)
tt | Multi-character time-marker string (for example, AM and PM)

For example, the format string dd-MMM-yyyy would create output like 16-Feb-2004.

VALUE-FORMAT (numeric)

This special property defines how the date entry control exchanges data with your program. It establishes the format of the control's value. The default VALUE-FORMAT corresponds to the date/time style, as follows:

SHORT_DATE | DAVF_YYMMDD
CENTURY_DATE | DAVF_YYYYMMDD
LONG_DATE | DAVF_YYYYMMDD
TIME | DAVF_HHMMSS

The following formats, defined in acugui.def, are available:

DAVF-YYYYMMDD (value 0) The control's value is expressed as an eight-digit number:
  • The first four digits are the year
  • The next two digits are the month
  • The last two digits are the day
This is the default format, unless the TIME style was specified when the control was created.
DAVF-YYMMDD (value 1) The control's value is expressed as a six-digit number:
  • The first two digits are the year
  • The next two digits are the month
  • The last two digits are the day
DAVF-HHMMSShh (value 2) The control's value is expressed as an eight-digit, 24-hour time value, including hundredths of a second:
  • The first two digits are the hour
  • The next two digits are the minutes
  • The next two digits are the seconds
  • The last two digits are hundredths of a second
Note that even though the date entry control cannot display hundredths of a second, it will nonetheless hold the value.
DAVF-HHMMSS (value 3) The control's value is expressed as a six-digit, 24-hour time value:
  • The first two digits are the hour
  • The next two digits are the minutes
  • The last two digits are the seconds
This is the default format when the TIME style is specified when the control is created.
DAVF-YYYYMMDDHHMMSShh (value 4) The control's full date and time is expressed as a sixteen-digit value. This combines the DAVF-YYYYMMDD and DAVF-HHMMSShh formats, and is the only format that contains both date and time information.
Parent topic: Date Entry


Examples

This first example builds a simple date entry control.

DISPLAY DATE-ENTRY, VALUE date-val-1.

Since no size or format information is provided, the control will be one line high and eight characters wide, and show the date in the default SHORT-DATE format.

Here is the equivalent Screen Section entry, with the addition of the LONG-DATE style:

03 DATE-ENTRY, LONG-DATE, VALUE DATE-VAL-1.
Parent topic: Date Entry


Entry Field

An ENTRY-FIELD control is a region in which the user can enter or modify text. While entry fields are one of the simplest controls, they are also one of the most complex because of the large number of options that affect them.

Entry fields can occupy multiple lines on the screen. For multiline entry fields, the system automatically performs word wrapping when the user enters data into the field. For single-line entry fields, the system automatically performs horizontal scrolling when the user enters more text than the field can display.

Many editing keys are available to modify the text. These editing keys are defined by the host graphical system, and cannot be defined by your KEYSTROKE configuration entries. For example, under Windows, when the cursor is in an entry field, the left-arrow key moves the cursor to the left in the field. If the left-arrow key is redefined in the KEYSTROKE file to perform another function, that function is ignored while the cursor is in the entry field.

Character-based systems support two ways for users to insert data into an entry field: insert mode and overtype mode. Windows systems support one mode for users to insert data into an entry field: insert mode. By default, character-based systems use overtype mode. If you are running your application on a character-based system and would like Windows-style behavior (insert mode) for your users, you must set the INSERT_MODE runtime configuration variable, or have users press the <Insert> key.

Entry fields are limited to 32K bytes of text. Memory is allocated as needed.

  • Common Properties
  • Special Properties
  • Events
  • Using Special Keys
  • Examples
Parent topic: Control Types


Common Properties

TITLE

Entry fields do not use titles.

VALUE

Entry fields take a numeric or alphanumeric value.

Conversion between the alphanumeric and numeric forms occurs automatically if you specify a numeric value. This allows you to use numeric data items with entry fields. When you use a numeric data item as an entry field's value, the runtime system prevents the user from entering non-numeric data

Note: Under Windows, you may encounter a peculiar behavior that looks like a bug but is actually a limitation of the Windows systems. If your entry field is formatted for numeric value and you paste non-numeric data into it from the clipboard, the runtime system has no way of checking and verifying that the data is of a correct format, and as a result, the entry field will be allowed to contain invalid data.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

MULTIPLE

You may use the VALUE IS MULTIPLE value option with multi-line entry fields. The value data item should be a one-dimensional table with no subscript specified. The effect of the MULTIPLE phrase is to match each line of the entry field to occurrences in the table. The first line is matched to the first occurrence in the table, the second line with the second occurrence, and so on. Occurrences that are larger than the number of lines in the entry field are set to spaces when the entry field is accepted. The MULTIPLE option makes it easy to process a large multi-line entry field in COBOL.

There is one important issue to consider when you use the MULTIPLE value option. The runtime system does not provide a way to limit the amount of text the user can enter on a single line. Thus, the user could enter more text than a single occurrence of the value data item can hold. Normally, to prevent the user from entering extra data, you might set the width of the entry field to be the same as the size of the value data item. However, this does not always work, because entry fields typically use a proportionally spaced font. Some characters are smaller than others, and the user can thus enter more of those characters than the width of the entry field might suggest.

There are two possible ways of addressing this issue. One option is to use a fixed-width font with the entry field. Then the width of the field matches the number of characters that the user can enter. The other option is to use a value data item that is larger than the width of the entry field. You will need to experiment to find appropriate sizes. You might try a value data item that is 20% larger than the entry field.

This issue is not normally a problem for single-line entry fields: the MAX-TEXT property (see below) prevents the user from entering too much data.

Finally, note that you can have a multiple-line entry field without using the MULTIPLE value phrase. In this case, the entire contents of the entry field are returned as a single string. Any carriage returns that the user enters directly are kept as part of the string. Carriage returns implied by word-wrapping are discarded.

BORDER-COLOR

Use BORDER-COLOR to specify a color for the bounding area of the entry field. Use color names as values.

SIZE

Entry fields determine their height by multiplying the LINES value by the height of the entry field's font. If the entry field is also boxed (the default), the space required for the box is added to the height.

Entry fields determine their width by multiplying the SIZE value by the standard or wide font measure. If the entry field is also boxed, the space required for the box is added to the width. Entry fields have a minimum width of at least one character.

When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.

The default LINES value is 1. The default SIZE value depends on whether or not a VALUE is specified when the field is created. If a VALUE is specified, the default SIZE equals the size of the VALUE literal or data item. Otherwise, the default SIZE is 8.

Most controls, including entry fields, base their width on the width of the 0 (zero) character in the control’s font. This usually works well because in most fonts, the 0 character is slightly wider than the average character. This means that the field is optimally sized for numeric data, and nearly optimally sized for alphanumeric data (actually it is slightly oversized, which is preferable because the user can enter data that is wider than average). In cases where the user enters very wide data, the entry field will scroll horizontally to fit all the data.

However, there are a few cases where this rule does not produce the best results. To handle these cases, several special sizing rules apply to entry fields.

The most pronounced problem arises when the input includes a lot of upper-case data. Upper-case characters are quite a lot wider than the average character (0), so when there are many upper-case characters they often do not fit in the space allotted by the normal rule. Therefore, additional rules handle two cases: (a) upper-case-only fields, and (b) small fields. Small fields require special handling because they tend to be coded fields (which are usually shown in upper-case). Also, scrolling in small fields feels odd to most users while scrolling in large fields is familiar.

To do a better job with these cases, the runtime employs a second font measurement. The second measure averages the width of the 0 (zero) character with the width of the maximum-width character in the font. This value is approximately the size of the average upper-case character in most fonts. We call this measurement the wide font measure. The size of the 0 character is known as the standard font measure.

When the runtime constructs an entry field, the first applicable rule from the list below is used to determine the entry field’s physical size. Overhead for the entry field’s box, if present, is added to this width.

  1. An entry field is never allowed to be smaller than the size of the maximum width character. This ensures that at least one character of data is visible in the field.
  2. If the field has the NUMERIC style, then its SIZE is multiplied by the standard font measure (i.e., numeric fields are normal).
  3. If the field has the UPPER style, and the configuration variable EF-UPPER-WIDE is non-zero, then its SIZE is multiplied by the wide font measure (i.e., upper-case fields are wide).
  4. If the field’s SIZE is less than or equal to the value of the configuration variable EF-WIDE-SIZE, then its SIZE is multiplied by the wide font measure (i.e., small fields are wide).
  5. Otherwise, its SIZE is multiplied by the standard font measure (i.e., everything else is normal). The default setting of EF-UPPER-WIDE is 1 (on). The default setting of EF-WIDE-SIZE is 5.
Tip:
  1. If your users will primarily enter upper-case characters in your application, you can set EF-WIDE-SIZE to a large value (for example 1000) to ensure that all of your non-numeric fields allow enough space for upper-case entry.
  2. If you want to ensure that the standard measure is always applied, set both EF-WIDE-SIZE and EF-UPPER-WIDE to zero.
  3. If your upper-case fields are still too narrow (because, for example, you tend to use upper-case W frequently), you can increase the entry field’s size further with the FONT-WIDE-SIZE-ADJUST configuration variable.

See Appendix H. Configuration VariablesFor a detailed description of the FONT-SIZE-ADJUST and FONT-WIDE-SIZE-ADJUST configuration variables.

COLOR

Entry fields will use any specified foreground or background color. If either color is omitted, that color uses a system-dependent default value. On most systems, the default foreground is black and the default background is white. Under Microsoft Windows, the default values are determined by the settings defined by the user in the Control Panel (usually black on bright-white). These system-dependent default colors are not transformed or mapped by the runtime's color-handling configuration options.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program, depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

STYLES

NUMERIC | This style causes the entry field to accept only numeric data. The NUMERIC style is applied automatically to any entry field that has a numeric or numeric-edited VALUE specified for it before it is created. As a result, you don't normally need to specify this style explicitly. Use this style when creating an entry field that does not have an initial value, but which needs to be restricted to accepting only numeric data.
NO-BOX | On most host graphical systems, entry fields are boxed (on character-based systems, they are not). The NO-BOX style prevents the box from being shown. Generally speaking, boxed entry fields are preferred stylistically, but you may need to omit the box to conserve screen space.
BOXED | On graphical systems, this style causes a box to be drawn around the entry field (the default). You can use the BOXED style to override the FIELDS_UNBOXED configuration variable for individual entry fields.
3-D This style causes the entry field to appear inscribed into the surface of the screen. This looks similar to the LOWERED frame style. The runtime system uses the background color of the floating window to determine how to draw the frame. The background color is set when the window is created and each time the window is erased. This color must be one of the low-intensity standard colors, except for black (color numbers 2–7). Any other background color will prevent the 3-D effect from displaying. Only boxed entry fields will display 3-D effects. See Frame for more information.
Note: There are no 3D effects when using WIN32_NATIVECTLS. Instead the border will be blue-gray in color.
LEFT | This style causes the value to be shown left-justified in the entry field (the default). Changing this style after the control has been created has no effect.
RIGHT | This style causes the value to be shown right-justified in the entry field. This style implies that the entry field is MULTILINE. Changing this style after the control has been created has no effect
CENTER, CENTERED | This style is supported only in Windows. It centers the text in the entry field. This style is allowed on other systems, but it has no effect. Changing this style after the control has been created has no effect.
MULTILINE This style indicates that the field can display and accept more than one line of text. An entry field created with a LINES setting of two (2) or more automatically has this style applied to it, unless the CELLS phrase is also used or implied. For this reason, you usually will not need to specify this style explicitly.
Note: An entry field created with the CELLS phrase following the LINES value phrase has the single-line style applied to it by default
VSCROLL | This style allows the user to scroll the contents of the entry field vertically. Without this style, the user may not enter more lines of text than the entry field can hold. With this style, the field will scroll as needed to allow the user to enter multiple lines of text. This style automatically implies the MULTILINE style.
VSCROLL-BAR | This style is identical to the VSCROLL style (above), with the addition that a vertical scroll bar is placed to the side of the entry field. The size of the entry field is extended to include the space needed by the scroll bar.
USE-RETURN | The Enter (or Return) key typically terminates entry. If you specify the USE-RETURN style, the Enter key is instead used to start a new line within the entry field, when the field is active. Without this style, pressing Enter (normally) terminates input.
USE-TAB | The Tab key is typically used to move between fields. If you specify the USE-TAB style, the user can enter a tab within the entry field when the field is active. This prevents the user from using the Tab key to leave the field.
LOWER | This style converts all keyboard entry to lower-case for this field. This style can be changed to UPPER with the MODIFY statement after the control has been created.
UPPER | This style converts all keyboard entry to upper-case for this field. This style can be changed to LOWER with the MODIFY statement after the control has been created.
NO-AUTOSEL | Normally, when an entry field is activated, all of its current contents are selected and highlighted (exception: if the field is activated by the mouse, this does not occur). This allows users to replace the entire contents of the field by simply typing in a new value (they can edit the current contents by using editing keys, or keep the current value by terminating the field). The NO-AUTOSEL style prevents the automatic selection from occurring. This is most commonly used on large multi-line entry fields.
READ-ONLY | Prevents the user from typing or editing data in the entry field. In all other respects, the entry field behaves normally. As of Version 8.1, read-only entry fields were changed to conform to standard Windows behavior in that the background color is always gray (regardless of the COBOL program's Color setting). If you need the ability to change the color of read-only entry fields, set the runtime configuration variable ECN_3699 to 0.
SECURE | This style prevents the characters that are entered into the field from being displayed on the screen. In place of each character, an * is displayed. This style is normally used with fields that take a password. This style is not available with MULTILINE entry fields.
SPINNER (Available only for Windows-based systems) This style attaches up and down arrow buttons to the right side of the entry field. When the user clicks on the up arrow, your program receives a MSG-SPIN-UP event. Clicking the down arrow generates a MSG-SPIN-DOWN event. Your program would normally respond to these events by incrementing or decrementing the entry field's value. Refer to the AUTO-SPIN style for simplified handling.
Note: The SPINNER style may be used only with a single-line entry field. It is ignored if you specify MULTILINE, or if you have an entry field that has more than two lines. In addition, a technical limitation of Windows prevents spinners from being used by entry fields with RIGHT or CENTER justification. This limitation stems from the fact that Windows requires a multiline entry field to use these styles (even if the entry field shows only one line). Windows interprets the up and down arrows as vertical scrolling messages to this multiline field.

Using the SPINNER with a 3-D entry field produces a look significantly different when you use the WIN32-3D configuration option.

AUTO-SPIN Similar to the SPINNER style, AUTO-SPIN provides a more simplified way of handling spinners by automatically updating the value of the entry field. When the user clicks the up arrow, the control's value is incremented by one. The down arrow decrements the value by one. The entry field uses the properties MIN-VAL and MAX-VAL to set the allowed range of values. When the user modifies the entry field's value, the AUTO-SPIN style interprets the current value as an integer and sets the resulting value as an integer. This could have non-obvious results if the field contains something other than an integer when the arrows are clicked. The AUTO-SPIN is available only to entry fields that are left justified.

Entry fields with the AUTO-SPIN style still generate MSG-SPIN-UP and MSG-SPIN-DOWN events. This occurs before the value is changed. If your program sets EVENT-ACTION to EVENT-ACTION-FAIL in response to these events, AUTO-SPIN does not change the value of the entry field. This allows you to do additional range checking; you can also substitute a different value by setting the entry field's value directly in response to the event.

Note: The behavior of an entry field control with the SPINNER, MIN-VAL, and MAX-VAL properties is determined by its event procedure, which processes messages from the spinner arrows. If your COBOL program does not use an event procedure, the behavior is as follows:

When the user enters a value that is outside the permitted range and then uses the spinner arrows to increase or decrease it, the value of the field is incremented or decremented as required. Then, if the value is below MINVAL, it is set equal to MIN-VAL, and if the value is above MAXVAL, it is set equal to MAX-VAL.

AUTO | This style causes the entry field to terminate as soon as it is filled by the user. A field is considered filled when the number of characters it contains equals its MAX-TEXT setting (see below). You may also use the words AUTOTERMINATE and AUTO-SKIP as synonyms for AUTO. This provides compatibility with text-mode COBOL.
NOTIFY-CHANGE | This style causes the entry field to generate NTF-CHANGED events. An NTF-CHANGED event is generated whenever the user changes the value of the entry field. Use this style when you need to track character-by-character changes to an entry field. Note that if you use this style with AUTO, the auto-termination status will take precedence over the NTF-CHANGED event (that is, when the user fills the field, the field will auto-terminate instead of generating an NTF-CHANGED event).
Parent topic: Entry Field
Related concepts
Cascading Style Sheet Syntax


Special Properties

MAX-TEXT (numeric)

This property limits the maximum number of characters that can be entered by the user into the field. This includes any characters generated by entering a return in a multi-line field. If the user attempts to enter more characters than allowed, the system's bell sounds. By default, this property is set to the field's SIZE setting (rounded up to the next whole integer) multiplied by the LINES setting (truncated to the next lower integer). For a single-line field, if you use the default MAX-TEXT and SIZE settings, the user will not be able to enter more characters than the field's VALUE data item can hold. The default MAX-TEXT setting is made when the control is created. After that, the setting changes only if you explicitly change it.

If MAX-TEXT is set to zero, the only limits placed on keyboard input are those imposed by the host system.

To make a single-line entry field that scrolls horizontally, you would typically make the SIZE smaller than the size of the VALUE data item, and then set MAX-TEXT to be the size of the VALUE data item. See below for an example.

MAX-LINES (numeric)

This property limits the total number of lines that the user can enter in a multi-line entry field. If the user tries to enter more lines, a message box displays that informs the user that the box has too many lines. When it is set to 0 (the default), the MAX-LINES setting is ignored.
Note: Regardless of how many lines are set or where in the Entry Field the text is added, the control will accept no more than the number of characters that keeps the total character count equal to the value set in the MAX_TEXT property. This is standard behavior in a Windows edit box.

AUTOFILL-ID (numeric)

This property identifies the entry field as an autofill entry field. The ID identifies the values that should be presented to the user as possible suggestions. Only previous entries from an entry field with this ID will be presented. If this property is not specified, then the other AUTOFILL properties are ignored.

Note that use of this property prevents use of NOTIFY-CHANGE, and your COBOL program will not receive any NTF-CHANGED events for any controls with this property set.

AUTOFILL-FILENAME (alphanumeric)

This property identifies the data store. The data store is where to look for suggestions, and where to store suggestions for future use. If all users have access to this file, then suggestions will be made from all users who have entered data into the entry field with this ID. If only a subset of users have access, then only those users will get and store suggestions for entry fields with this ID. If this file does not exist, it will be created on the first use. All configuration file translating will be done on this filename, including which file system to use (e.g. MSSQL), with a default file system of VISION. If no filename is given, a filename will be constructed from program-name and ID.

If you want this data file to be a database table (for use with Acu4GL), an XFD file can be created automatically, before the file is opened, by setting the configuration variable AUTOFILL-NEEDS-XFD TRUE; without this variable, the XFD is not created.

AUTOFILL-MAX-LINES (numeric)

This is the maximum number of suggestions that a user will be presented with. The default value is 10.

CURSOR (numeric)

This property provides a way to position the cursor within the entry field when the field is activated. You must use CURSOR in conjunction with NO-AUTOSEL; otherwise, the default selection logic will automatically reposition the cursor to the end of the field.

Note: When CURSOR equals 0, the cursor is automatically positioned by the host system. If CURSOR has a positive value, the cursor is positioned at that character position (starting at 1). For example, if you assign CURSOR to 3, the cursor is placed at the third character (either on the third character or between the second and third characters, depending on the appearance of the cursor).

If you use the CURSOR property in a multi-line entry field, it will control the cursor position by counting the characters in the entry field without regard to lines. Significantly, internal control characters are also counted, which often makes it difficult to use the CURSOR property effectively in a multi-line entry field.

When CURSOR equals -1, all of the text in the entry field is selected and the cursor is positioned to the end of the selection.

Ordinarily, this property is not needed. However, one case in which you might want to use it is in combination with the NOTIFY-CHANGE style. As the user fills in the field, your program acts on each keystroke. If you change the value of the field in response, the system returns the cursor to column one of the field. Use CURSOR to reposition the cursor to the point where the user was typing, or to some other position in the field

Note: If you use the CURSOR property in a Screen Section entry, you should set it to 0 after you use it. If you leave it at a non-zero value, the cursor will be repositioned to that value each time you DISPLAY that Screen Section item.

CURSOR-COL (numeric)

This property controls and reports the cursor position in a multiline entry field. Inquiring on CURSOR-COL returns the column number (starting at 1) of the cursor. CURSOR-COL is often used interdependently with the CURSOR-ROW property to determine the exact position of the cursor with respect to the lines and columns of a multiline entry field. For that reason, the two properties are discussed together under the CURSOR-ROW paragraph (below).

CURSOR-ROW (numeric)

This property controls and reports the cursor position in a multiline entry field. Inquiring on CURSOR-ROW returns the line number (starting at 1) of the cursor.

Setting CURSOR-ROW alone has no immediate effect. However, when you set CURSOR-COL, the values of CURSOR-ROW and CURSOR-COL will be taken together to place the cursor at the specified line and column. Thus you should always set CURSOR-ROW before CURSOR-COL if you want to place the cursor at a particular line and column.

If CURSOR-ROW specifies a value =0, the cursor will be placed at the beginning of the entry field. If CURSOR-ROW specifies a line number beyond the end of the text, the cursor will be placed at the end of the text. If CURSOR-ROW is valid and CURSOR-COL specifies a value =0, the cursor will be placed in column 1 of the specified line. If CURSOR-ROW is valid and CURSOR-COL specifies a value greater than the number of characters in the line, the cursor will be placed at the end of the text in that line.

Note: In a single-line entry field, CURSOR-ROW is ignored when set, and it always returns 1 when inquired. CURSOR-COL behaves identically to the CURSOR property in a single-line entry field.

ACTION (numeric)

When set to a non-zero value, this special property initiates a specific operation in the entry field. The meaningful values are as follows:

ACTION-CUT | Cuts the current selection to the clipboard
ACTION-COPY | Copies the current selection to the clipboard
ACTION-PASTE | Pastes the clipboard contents into the entry field at the cursor location. If any text is selected, it is replaced by the paste operation. Text pasted in excess of the field's capacity is truncated
ACTION-DELETE | Deletes the current selection
ACTION-UNDO | Undoes the last change

See the COPY library acugui.def for the value names. Actions are supported only under Windows; specifying these actions under other systems has no effect. Specifying a value other than one listed here has no effect.

See the SET statement for a technique to automate the generation of actions by other screen elements (such as push buttons or menu items).

MIN-VAL (numeric)

This property sets the lower bound for the range of numeric values the user may enter into the entry field. The user may enter numeric values between MIN-VAL and MAX-VAL (inclusive). This property also sets the lower bound for the range of values used by the AUTO-SPIN style. The value of MIN-VAL must be an integer in the range of -2147483647 to 2147483647. If both MIN-VAL and MAX-VAL are set to the default (zero), no range checking is performed.

When the user enters a value that is out of range and shifts the input focus away from the text box of the entry field control (i.e, clicks the spinner or attempts to leave the control altogether), the entry field displays a message box informing the user of the error. The default error message reads Please enter a value between min-val and max-val. You can change this with the TEXT configuration variable.

MAX-VAL (numeric)

This property sets the upper bound for the range of numeric values that the user may enter into the entry field. Along with MIN-VAL, this property is used for range validation; it is also used in conjunction with the AUTO-SPIN style. See MIN-VAL for additional information.

SELECTION-TEXT (alphanumeric)

This property replaces the text currently selected in the control with the value assigned to SELECTION-TEXT. If no text is currently selected, the value is inserted at the current cursor location. When inquired, this property returns the text currently selected or spaces if nothing is selected. Note that you can determine the exact text that is selected by using the LENGTH option when inquiring on SELECTION-TEXT. The following example displays a message box with the currently selected text in quotes:

77  SEL-TEXT    PIC X(100).
77  SEL-LEN     PIC 9(3).

INQUIRE ENTRY-FIELD-1, SELECTION-TEXT IN SEL-TEXT,
     LENGTH IN SEL-LEN
IF SEL-LEN = ZERO
      DISPLAY MESSAGE BOX, "Nothing selected"
ELSE
      DISPLAY MESSAGE BOX,
      QUOTE, SEL-TEXT(1 : SEL-LEN), QUOTE
END-IF

If the selection spans multiple lines, any soft returns added internally by the control to manage word-wrapping are omitted from the returned value. Any hard returns (those inserted by the user via the <Enter> or <Return> key) are represented by the two-character sequence h"0D" h"0A" (carriage-return, line-feed).

Note: You generally should not place SELECTION-TEXT in the Screen Section. If you do, every time you do a DISPLAY of that screen item, the current value of SELECTION-TEXT replaces the currently selected text.

AUTO-DECIMAL (numeric)

This property enables you to specify a minimum number of digits right of the decimal point required for the automatic termination of the entry field. When used as a property, the number of decimals should be given like this:

AUTO-DECIMAL 2

This will auto-terminate the entry field once you have entered two decimals.

When AUTO-DECIMAL is used as a property, the phrase AUTO/AUTOTERMINATE is implied.

Note: There is a configuration variable, AUTO-DECIMAL, which, when set to a non-zero value, performs the same function as the AUTO-DECIMAL property.
Parent topic: Entry Field


Events

CMD-GOTO
CMD-HELP
MSG-SPIN-UP
MSG-SPIN-DOWN
MSG-VALIDATE
NTF-CHANGED
Parent topic: Entry Field


Using Special Keys

When an entry field has the input focus, the Home and End keys position the cursor at the beginning or end of a line of text. The Page-Up and Page-Down keys can be used to scroll a multi-line entry field. Setting KEYSTROKE configuration entries does not affect these actions.

Parent topic: Entry Field


Examples

This first example builds a simple entry field:

DISPLAY ENTRY-FIELD,  HANDLE IN ENTRY-1.

Since no size information is provided, and no VALUE is specified, this field will be one line high and eight characters wide.

In the next example, the entry field gets its initial contents and determines its width from the VALUE data item:

DISPLAY ENTRY-FIELD,  VALUE DATA-1,
    HANDLE IN ENTRY-1.

Here is the equivalent Screen Section entry, with the addition of the LOWER style:

03 ENTRY-FIELD,  USING DATA-1,  LOWER.

You could also use the word VALUE instead of USING.

This next Screen Section entry describes an entry field that is roughly 10 characters wide on the screen but which can take up to 30 characters via horizontal scrolling:

03 ENTRY-FIELD  USING PIC-X-30-ITEM,
      SIZE 10,  MAX-TEXT = 30.

Here is a Screen Section item (along with the relevant Working-Storage items) that creates a 5-line entry box with a vertical scroll bar:

(Working-Storage)

01 DATA-TABLE-1,  OCCURS 15 TIMES  PIC X(40).

(Screen Section)

03 ENTRY-FIELD,  VALUE MULTIPLE DATA-TABLE-1,
       LINES 5,  SIZE 30,  MAX-LINES = 15,
       VSCROLL-BAR,  NO-AUTOSEL.

The above entry field will be 5 lines tall on the screen, but allow for 15 lines of text. Notice that DATA-TABLE-1 is PIC X(40), while the SIZE of the entry field is 30. This provides extra space in DATA-TABLE-1 to allow for the fact that an entry field of width 30 can hold more than 30 characters on a given line. The NO-AUTOSEL style is not required, but would typically be used for a scrolling, multiple-line field.

Parent topic: Entry Field


Frame

A FRAME is a simple box displayed on the screen. Use frames to group together items, to create a progress (or status) bar, or to add visual interest to the screen. Frames may have titles associated with them (which appear in their border) and can have a variety of 3-D effects applied to them. A frame may have only one 3-D style specified for it. If no 3-D styles are used, the frame is drawn as a simple line.

Frames are unusual in that they draw on only a portion of their total area. The interior of the frame is typically occupied by additional controls. Any interior portion of the frame that is not occupied by another control is shown as either spaces over the window's background color or filled with a color specified in the FILL-COLOR property. This means that you cannot display textual data (that is, Format 1 DISPLAY) inside a frame. If you need to create a box around textual data, use DISPLAY BOX.

  • Common Properties
  • Special Properties
  • Events
  • Examples
Parent topic: Control Types


Common Properties

The set of FRAME common properties includes:

TITLE

A frame may have a title. It can appear in several possible positions, depending on the value of the TITLE-POSITION special property. The TITLE phrase is used to specify the title. A key letter may be specified in the title. See Common Screen Options for more information.

VALUE

Frames do not have values.

SIZE

The LINES and SIZE values describe the area occupied by the frame, using the frame's font to determine the dimensions of the row and column. The frame is drawn immediately inside the described area, except that the top or bottom line of the frame is moved by half the height of the title font (even if no title is specified). This allows the title, if any, to appear centered vertically in the frame's upper or lower line, depending on the value of the TITLE-POSITION special property. However, if the FULL-HEIGHT style (below) is specified, the frame's title will descend from the top of the frame instead of being centered vertically. The default LINES value is 5. The default SIZE value is 12.

When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.

COLOR

For the default style, the foreground color is used when the frame is drawn. The background color is not used. However, for the various 3-D styles, the background color is the primary color used, and the foreground color is not used. Normally, you want the background color to match the surrounding area when drawing a 3-D effect. Frames use the current window colors as the default foreground and background colors.
Note: If you are using the WIN32_NATIVECTLS runtime variable to automatically enable XP or Vista control styles, and have frames with labels, see the COLOR property of section Label: Common Properties - Label for information on how the labels may display.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

STYLES

HEAVY | Causes the frame to be thicker or more pronounced than normal. The exact effect depends on the other styles used.
VERY-HEAVY | Creates a very heavy line or 3-D effect. Most of the 3-D effects degrade somewhat when used with this style. However, you should use this style whenever you use the ALTERNATE style.
ALTERNATE Creates an alternate look. To get the alternate look, you must also specify either the HEAVY or VERY-HEAVY styles.

The default (NORMAL) style, when combined with the ALTERNATE and VERY-HEAVY styles, produces a double-line frame. The run-time system accomplishes this by filling the middle pixel of the 3-pixel frame with the background color.

The effect of ALTERNATE on the RAISED, LOWERED, ENGRAVED, and RIMMED styles is described below under their respective entries. All styles can be previewed on screen with the FRAMES sample program.

RAISED One of the four 3-D styles. The raised style causes the interior of the frame to appear as if raised above the surface of the screen. We suggest that you do not use a title with this style, because the title tends to reduce the 3-D effect.

When combined with the ALTERNATE and VERY-HEAVY styles, RAISED creates a frame that appears to have a raised area with a slight rim around it

Note: Be careful when using this style that you don't make a frame that looks like a push button.
LOWERED One of the four 3-D styles. This style causes the interior of the frame to appear to be lower than the surface of the screen. We recommend against using a title with this style, because the title tends to spoil the 3-D effect.

When it is combined with the ALTERNATE and HEAVY (or VERY-HEAVY) styles, LOWERED creates a frame that has a dark border around the interior of the lowered region.

ENGRAVED One of the four 3-D styles. This style causes the frame to appear lower than the surface of the screen, while the interior of the frame appears to be level with the surface.

When combined with the ALTERNATE and VERY-HEAVY styles, the engraved area of the frame appears to be accentuated and deeper. When ENGRAVED is used with the ALTERNATE and HEAVY styles, the middle pixel of the 3-pixel frame is painted black instead of the background color. This makes the framed region look like a separate piece of the screen.

RIMMED One of the four 3-D styles. This style causes the frame to appear to be raised above the surface of the screen, while the interior of the frame appears to be level with the surface.

When combined with the ALTERNATE and VERY-HEAVY styles, the rim appears to be taller than usual.

FULL-HEIGHT Causes the top line of a frame to appear at the exact row position specified. In this case, the frame's title descends from the top of the frame instead of being centered vertically. Use in conjunction with TITLE-POSITION to adjust the frame title's location.

To see how the different frame styles appear on your system, compile and run the sample program frames.cbl.

Parent topic: Frame
Related concepts
Cascading Style Sheet Syntax


Special Properties

HIGH-COLOR (numeric)

In order to draw the 3-D effects, the runtime requires three related colors: the background color, and lighter and darker versions of that color. The HIGH-COLOR property specifies the color number of the brighter color. The LOW-COLOR property specifies the color number of the darker color. If either of these values is zero, the runtime will attempt to find default values. The runtime knows how to find colors for the low-intensity versions of blue, green, cyan, red, magenta, brown, and white (out of the default palette). If the background color is not one of these colors, and either the HIGH-COLOR or LOW-COLOR is zero (0), the 3-D effect will be ignored.

LOW-COLOR (numeric)

This property supplies the color number of the darker version of the background color used to draw the 3-D styles. See HIGH-COLOR for a complete description.

FILL-COLOR (numeric)

This property establishes a color that fills a frame's interior. The color values range from 1 to 16. A value of 0 (the default) indicates that the frame should have no fill color. The color acts like a background color in terms of how color modification settings affect it. (Note that the control's background intensity setting can also affect this color.) For a borderless colored area, make the frame's color and the fill color the same.

The specified fill color is used in the borders of the RAISED and ENGRAVED styles, but not in the borders of the other 3-D styles. Note that the frame's title establishes its own background color, which is visible only if it is not the same as the fill color. We recommend that you do not insert titles on filled frames. (An exception is interior titles; see the TITLE-POSITION property below.)

FILL-PERCENT (numeric)

This property allows you to fill a portion of a frame with the fill color. The property's value is the percentage of the frame filled, from 0 to 100. If the frame is taller than it is wide (in base units), then the fill color is applied from the bottom of the frame up to the specified percentage. Otherwise, the frame is filled with the indicated percentage of fill color from left to right. You can use this property to create a progress (or status) bar. The default value for this property is 100.

FILL-COLOR2 (numeric)

This property has the same range of values (1 - 16) as FILL-COLOR but is used only if the value of FILL-PERCENT is less than 100. The color specified by this property is applied to the part of the frame that is not filled by FILL-COLOR. If the value of FILL-COLOR2 is 0 (the default), then no color is applied to the part of the frame not already filled by FILL-COLOR.

TITLE-POSITION (numeric)

This property determines the position of the frame's title, as follows:

1 | Top left
2 | Top center
3 | Top right
4 | Bottom left
5 | Bottom center
6 | Bottom right
7 | Centered vertically and horizontally

Unless the FULL-HEIGHT style (described above) is in effect, a TITLE-POSITION value of 1, 2, or 3 places the top of the frame half a character lower than the specified position. A TITLE-POSITION value of 4, 5, or 6 places the bottom of the frame half a character higher than the specified position. With values 1 - 6, the frame's title appears centered with respect to the frame's border.

TITLE-POSITION value 7 does not adjust the border position as described above, nor does it have a background color. As a result, it can be used with FILL-COLOR and FILL-PERCENT.

Parent topic: Frame


Events

Frames do not generate events.

Parent topic: Frame


Examples

The following creates a simple frame:

DISPLAY FRAME, LINES 7, SIZE 30.

Here is a frame with a title specified in the Screen Section:

03 FRAME, "Options", SIZE 15, LINES 7.

Here is a frame that has the visual effect of having a dramatically raised surface:

03 FRAME, LINE 4, placeStateCOL 15, LINES 5, SIZE 25,
     RAISED, HEAVY.
Parent topic: Frame


Grid

The Grid Control

The GRID control is a two-dimensional table of data fields. Each element of this table, called a cell, can hold either text or a bitmap, or both. Grids are relatively complex controls with many properties that you can use to customize their appearance and behavior.

Note: Paged Grid controls are discussed in Paged Grids.

Currently the grid control is supported only in Windows environments. Attempting to create a grid control on other systems will fail, causing the handle to be returned with the NULL value.

Grids are organized into rows, columns, and records. In a grid, a row is a grouping of cells that appear on one line in the control. A record is one or more rows that are treated as a logical unit. A column identifies a particular cell in a record.

By default, a record occupies one row in a grid, but you can arrange for a record to wrap around to the next row when it passes the right edge of the grid. When this occurs, a record will occupy more than one row in the grid. You might want to construct a grid like this when you want to see many fields in a data record at once. Alternatively, you can have the grid use scroll bars or wheelmouse events to access cells past the right edge of the control. Column, row, and record numbers all start at 1.

Grids come in two formats: with horizontal scrolling and without. When you opt for horizontal scrolling, each record may occupy only one row in the grid. Grids with horizontal scrolling appear much like a spreadsheet. Without horizontal scrolling, a record may occupy more than one row. In either case, vertical scroll bars appear automatically when needed (providing you allow them with the VSCROLL style).

A grid's capacity is limited by available memory. The grid uses a sparse storage technique in which records with no data have no memory allocated for them. A grid may not have more than 99 columns. There are no other practical limits [2 giga records (2,147,483,647 records) and 2 GB text per record]. A single cell may contain no more than 32,766 bytes of text.

The grid operates in two modes: navigate mode and entry mode. While it is in navigate mode, the arrow keys move the cursor around the grid. This is the default mode. The grid shifts to entry mode when the user starts to modify data. In this mode, the arrow keys are used to edit the current cell's data. When the user finishes a cell, the grid returns to navigate mode.

The exact set of keys understood by the grid depends on the host system. Under Windows, the following keys are used in navigate mode:

Up/Down Arrow | Moves cursor to the same column in the previous/next record
Left/Right Arrow | Moves cursor to the previous/next column in the record
Tab (with USE-TAB) | Moves cursor right, wrapping to next record when at last cell in record
Backtab (with USE-TAB) | Moves cursor left, wrapping to the previous record when at the first cell in record
Home | Moves to first column in record
Ctl-Home | Moves to first column of first record
End | Moves to last column in record
Ctl-End | Moves to first column in last record
Page Up/Down | Moves cursor up/down one page
Enter | Shifts to entry mode for the current cell; highlights contents for editing
Shift-Enter | Moves cursor to the first column of the next record
Any printable character | Shifts to entry mode for the current cell; overwrites contents with character

When in entry mode, the user types into an entry field control. All of the editing keys usable by an entry field are usable here. The user leaves entry mode by using Enter or Tab/Backtab, or by clicking on another cell with the mouse. The special property FINISH-REASON can be used to ascertain why the user left entry mode.

Clicking a mouse on a cell moves the cursor to that cell. Double-clicking a cell shifts to entry mode.

Grids can have row and column headers. Use the ROW-HEADINGS style to establish row headers and the COLUMN-HEADINGS style to make column headers. Headers are normal cells with certain special traits:

  • Headers are always visible, regardless of how the user scrolls the grid
  • The cursor does not move into a header cell
  • The special properties HEADING-COLOR, HEADING-FONT and HEADING-DIVIDER-COLOR apply only to header cells. The style TILED-HEADINGS applies only to header cells
  • The events MSG-HEADING-CLICKED, MSG-HEADING-DBLCLICK, and MSG-HEADING-DRAGGED apply only to header cells

Otherwise, headers are normal cells. When you use column headers, record 1 becomes the column headers. When you use row headers, column 1 of each record supplies the row headers.

The grid control can have different colors and fonts assigned to each cell. For convenience, there are several ways this can be done. For example, you can set the color for the grid as a whole, for a particular row or column, or for a particular cell (in addition to other techniques). For a particular cell, there could be several colors or fonts specified for it. The grid picks the color or font to use by applying a priority list. The first item in the list that provides the color or font is the one that is used. For colors, this is determined independently for foreground and background colors.

For colors, the list of priorities is as follows (highest applying first):

  1. CURSOR-COLOR
  2. DRAG-COLOR
  3. REGION-COLOR
  4. CELL-COLOR
  5. HEADING-COLOR
  6. ROW-COLOR
  7. COLUMN-COLOR
  8. ROW-COLOR-PATTERN
  9. Grid's overall color

For fonts, the following priority list is used:

  1. CELL-FONT
  2. HEADING-FONT
  3. ROW-FONT
  4. COLUMN-FONT
  5. Grid's overall font

Currently, the grid control is available only under Windows.

  • Common Properties
  • Special Properties
  • Events
Parent topic: Control Types


Common Properties

TITLE

Grids do not have titles

VALUE

A grid does not have a (single) value. You can set or inquire the contents of each cell using the CELL-DATA property. You can also retrieve an entire record at once with the RECORD-DATA property.

SIZE

The SIZE of a grid is the number of characters across that you want to be visible in the grid. This is measured using the grid's default font. The LINES of a grid is the number of rows you want to be visible. Note that this is not the same as the number of records in the case where a record occupies more than one row. Normally, you should ensure that the LINES setting of a grid is an even multiple of the number of rows per record.

Space is added as needed to accommodate the grid's scroll bars and any border or grid lines

COLOR

Grids will use any specified foreground or background color. If either color is omitted, that color uses a system-dependent default value. Under Microsoft Windows, the default values are determined by the settings defined by the user in the Control Panel (usually black on bright-white). Note that the grid's color is its default color. You can override this default for a specific row, column, or cell by using various special properties (see ROW-COLOR, COLUMN-COLOR, CELL-COLOR, CURSOR-COLOR, HEADING-COLOR and ROW-COLOR-PATTERN). The grid uses a priority rule for determining which color to use when several are specified for a cell (for example, a cell that has a ROW-COLOR and a different COLUMN-COLOR specified for it). This is discussed in detail in the introduction to the grid above.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

STYLES

3-D | Displays 3-D shading around the border of the control.
ADJUSTABLE-COLUMNS Allows the user to change the size of the columns by dragging the column dividers with the mouse. The grid must have only one row per record for this style to have any effect. When the grid has column headers, the user will be able to change the column widths only by dragging the header dividers (this is to reduce the likelihood of the user accidentally changing a column's width when just clicking on a cell). If the grid does not have column headers, the user can drag any part of the divider.

The minimum column size is 1. The maximum is the visible portion of the grid. If the grid allows for horizontal scrolling, the VIRTUAL-WIDTH property will change as the user changes column sizes. When the user changes a column size, your program will be informed via a MSG-COL-WIDTH-CHANGED message. Because grids use integer character widths for measuring columns, the user will not be able to place the column divider at just any pixel location. The grid will adjust the location given by the user to the nearest character position

Note: Single column grids are not adjustable (the column already occupies all of the grid's display space). If a single column grid has the ADJUSTABLE-COLUMNS property, the column may appear to be adjustable, but when the user releases the mouse after dragging to change the width, the column will return to its original width.
BOXED | Displays a border around the grid. If neither BOXED nor NO-BOX is specified, the default is machine-dependent. Under Windows, a box is displayed.
CENTERED-HEADINGS | Draws column headings centered, regardless of the alignment of the rest of the column. If this is not specified, the column headings match the alignment of the corresponding column. Note that the alignment of row headings is specified as the first entry in the ALIGNMENT property, so there is no need for any special row heading alignment styles.
COLUMN-HEADINGS | Causes the first record to be treated as column headers. See the discussion on headers above for details.
HSCROLL | Specifies a horizontally scrolling grid. A grid with this style may not specify more than one row per record (for more information, see the DISPLAY-COLUMNS special property).
NO-BOX | Causes the grid to display without a surrounding border. See the BOXED property.
NO-CELL-DRAG | Prevents the user from dragging a cell in a grid control. You can configure NO-CELL-DRAG style to be the default setting for grid controls by setting the GRID_NO_CELL_DRAG configuration variable to 1 (on, true, yes). The default value is 0 (off, false, no) and will enable the user to drag a cell in a grid control.
PAGED | Makes the grid a "paged" grid. Paged grids are typically used when the number of records in the grid is too many for a normal grid. When you set this style for a grid that contains data, records above the first visible record and records after the last visible record are deleted. See Paged Grids for a complete description of paged grids.
ROW-HEADINGS | Treats the first column of each record as a row header. Note that this is typically useful only when you have one record per row. See the discussion on headers above for more details.
TILED-HEADINGS Draws the headings with some shading that causes the headings to look like tiles. This gives a light 3-D look to the grid. This style is effective only if the background color for the heading cells is low-intensity and not black. This looks best if you set the heading's background color to low-intensity white (that is, gray) and set the heading's divider color to black. Using the constants found in the COPY library acucobol.def, you can most easily specify this with:
HEADING-COLOR = BCKGRND-WHITE,
HEADING-DIVIDER-COLOR = BLACK
USE-TAB | Causes the grid to use the Tab and Backtab keys as navigation keys within the grid. Without this style, the Tab and Backtab keys move between the grid and other controls in the grid's window.
VSCROLL | Specifies a vertical scroll bar for the grid. Grids without vertical scroll bars may still contain more records than seen on the screen, and the user can still reach these records using the keyboard. The usual reason for creating a grid without a vertical scroll bar is if you are going to limit the number of records to an amount that fits on the screen (see NUM-ROWS below).
Parent topic: Grid
Related concepts
Cascading Style Sheet Syntax


Special Properties

  • ACTION (alphanumeric)
  • ACTION-HIDE-DRAG
  • ALIGNMENT (alphanumeric)
  • BITMAP (numeric)
  • BITMAP-NUMBER (numeric)
  • BITMAP-TRAILING (numeric)
  • BITMAP-WIDTH (numeric)
  • CELL-COLOR (numeric)
  • CELL-DATA (alphanumeric)
  • CELL-FONT (numeric)
  • CELL-PROTECTION (numeric)
  • COLUMN-COLOR (numeric)
  • COLUMN-DIVIDERS (numeric)
  • COLUMN-FONT (numeric)
  • COLUMN-PROTECTION (numeric)
  • CURSOR-COLOR (numeric)
  • CURSOR-FRAME-WIDTH (numeric)
  • CURSOR-X (numeric)
  • CURSOR-Y (numeric)
  • DATA-COLUMNS (numeric)
  • DATA-TYPES (alphanumeric)
  • DISPLAY-COLUMNS (numeric)
  • DIVIDER-COLOR (numeric)
  • DRAG-COLOR (numeric)
  • END-COLOR (numeric)
  • ENTRY-REASON (alphanumeric)
  • FILE-POS (numeric)
  • FINISH-REASON (signed integer)
  • HEADING-COLOR (signed integer)
  • HEADING-DIVIDER-COLOR (numeric)
  • HEADING-FONT (numeric)
  • HIDDEN-DATA (alphanumeric)
  • HSCROLL-POS (numeric)
  • INSERT-ROWS (numeric)
  • INSERTION-INDEX (numeric)
  • LAST-ROW (numeric)
  • MASS-UPDATE (numeric)
  • NUM-COL-HEADINGS (numeric)
  • NUM-ROWS (numeric)
  • NUM-ROW-HEADINGS (numeric)
  • RECORD-DATA (alphanumeric)
  • RECORD-TO-ADD (alphanumeric)
  • RECORD-TO-DELETE (numeric)
  • REGION-COLOR (numeric)
  • RESET-GRID (numeric)
  • ROW-COLOR (numeric)
  • ROW-COLOR-PATTERN (numeric)
  • ROW-DIVIDERS (numeric)
  • ROW-FONT (numeric)
  • ROW-PROTECTION (numeric)
  • SEARCH-OPTIONS (alphanumeric)
  • SEARCH-TEXT (alphanumeric)
  • SEPARATION (numeric)
  • SORT-TYPES (alphanumeric)
  • START-X (numeric)
  • START-Y (numeric)
  • VIRTUAL-WIDTH (numeric)
  • VPADDING (numeric)
  • VSCROLL-POS (numeric)
  • X (numeric)
  • Y (numeric)
Parent topic: Grid


ACTION (alphanumeric)

Used only with paged grids, this special property causes the grid to invoke its paging logic in one of several ways. This simplifies the task of filling the grid with its initial data. After creating a grid, you would typically assign one of the following values to ACTION to load the initial page of data that the user will see. The values of the following are level 78 data names found in acugui.def:

ACTION-FIRST-PAGE | (value 10) | Generates the grid's MSG-PAGED-FIRST event. This fills the grid with the first page of data from the data source.
ACTION-LAST-PAGE | (value 11) | Generates the grid's MSG-PAGED-LAST event. This fills the grid with the last page of data from the data source.
ACTION-CURRENT-PAGE | (value 12) | Empties the grid of any data except for column headers, and generates the grid's MSG-PAGED-NEXTPAGE event. If you position a data file using the START statement before performing this action, the grid will fill the page of data starting with the record selected by the START.
ACTION-PREVIOUS-PAGE | (value 14) | Generates the grid's MSG-PAGED-PREVPAGE event. This fills the grid with the previous page of data from the data source.
ACTION-PREVIOUS | (value 15) | Generates the grid's MSG-PAGED-PREV event. This scrolls up to show the record before the first record of the grid's current data.
ACTION-NEXT | (value 16) | Generates the grid's MSG-PAGED-NEXT event. This scrolls down to show the next record after the last record of the grid's current data.
ACTION-NEXT-PAGE | (value 17) | Generates the grid's MSG-PAGED-NEXTPAGE event. This fills the grid with the next page of data from the data source.
Parent topic: Special Properties


ACTION-HIDE-DRAG

Removes the DRAG-COLOR. See the description of the DRAG-COLOR property below.

Parent topic: Special Properties


ALIGNMENT (alphanumeric)

This special property describes the alignment of each column in the grid. Each time you set this property, you describe the alignment for the next column in the grid, starting with the first. Setting this property to spaces clears the previously specified alignments. Valid values are as follows (case does not matter):

Value | Description
L | left justified
R | right justified
C | centered
U | unaligned

Unaligned data is displayed in the cell as is. Otherwise, leading and trailing spaces are removed from the data, and it is justified as specified. The default for unspecified columns is unaligned.

The following example sets various alignments for a three-column grid:

ALIGNMENT = ( "L", "R", "C" )
Parent topic: Special Properties


BITMAP (numeric)

Places a bitmap in the cell identified by the X and Y properties. This should be set to the handle of a bitmap loaded in memory (using the WBITMAP-LOAD option of W$BITMAP). If it is set to zero, then any existing bitmap is removed. You may place a bitmap in the same cell as text. The bitmap is concatenated to the text (with a small separation), and the whole unit is aligned as specified by the ALIGNMENT property. When the user performs text entry in the cell, the bitmap is hidden until the entry is complete. The same bitmap may be placed in more than one cell. You should not destroy the bitmap handle while any cells contain the bitmap.

Parent topic: Special Properties


BITMAP-NUMBER (numeric)

This special property identifies a particular image when you specify a bitmap strip as the BITMAP for a cell. The first image in the strip is number 1, the second is number 2, and so on. Images in a bitmap strip must be uniform width, as specified by BITMAP-WIDTH. The cell affected is identified by the X and Y properties. The default value is 1.

Parent topic: Special Properties


BITMAP-TRAILING (numeric)

When set to 1, this special property indicates that the bitmap should follow the text in the cell. When it is set to zero (the default), the bitmap precedes the text. Other values have undefined effects. The cell affected is identified by the X and Y properties.

Parent topic: Special Properties


BITMAP-WIDTH (numeric)

This special property identifies the width, in pixels, of the bitmap identified by BITMAP. If the width is not set, the entire bitmap is used. This is used in conjunction with BITMAP-NUMBER to select an image out of a bitmap strip. The cell affected is identified by the X and Y properties.

Parent topic: Special Properties


CELL-COLOR (numeric)

This special property sets the color for the cell identified by the X and Y properties. The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid is ignored — the value is treated as the final color value. See the COLOR common property for related information.

Parent topic: Special Properties


CELL-DATA (alphanumeric)

When set, this special property replaces the text data at the cell identified by the X and Y properties with the specified value. When inquired, this property returns the text data at that cell.

Parent topic: Special Properties


CELL-FONT (numeric)

This special property sets the font for the cell identified by the X and Y properties. This should be set to a valid font handle.

Parent topic: Special Properties


CELL-PROTECTION (numeric)

This special property protects the individual cell identified by the X and Y properties from being changed by the user. Set this property to 1 to protect a cell or 0 to allow the cell to be changed. If the cell is protected, the user can visit the cell, but not modify its contents. The appearance of the cell does not automatically change when the cell is protected.

Parent topic: Special Properties


COLUMN-COLOR (numeric)

Sets the color for the entire column identified by the X property. The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid is ignored — the value is treated as the final color value. For example, to set column three's color to dark blue (2) on bright white (512), you could do the following:

MODIFY GRID-1, X = 3, COLUMN-COLOR = 514

You should be sure to set the X property before setting COLUMN-COLOR. See COLOR above for related information.

Parent topic: Special Properties


COLUMN-DIVIDERS (numeric)

Sets the width, in pixels, of the column dividers. Each time you set this property, you describe the width of the next column's trailing separator, starting with the first column.

Setting this property to -1 clears the previously specified values. Unspecified columns use a system-dependent default value. On graphical systems, the default divider is one-pixel wide. On character systems, the default divider is omitted (zero-pixels wide).

Parent topic: Special Properties


COLUMN-FONT (numeric)

Sets the font to use for the column identified by the X property. This should be set to a valid font handle.

Parent topic: Special Properties


COLUMN-PROTECTION (numeric)

Protects the entire column identified by the X property from being changed by the user. If this property is set to 1, the column is protected; if the property is set to 0, the column is not protected. The appearance of the column does not change when the column is protected.

Parent topic: Special Properties


CURSOR-COLOR (numeric)

Sets the color for the cell containing the cursor. The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid is ignored — the value is treated as the final color value. Note that the cursor is normally hidden when the grid loses the focus. This causes the cell containing the cursor to revert to its normal color. The default cursor color is 0. (For related information, see the COLOR common property and CURSOR-FRAME-WIDTH special property.)

Parent topic: Special Properties


CURSOR-FRAME-WIDTH (numeric)

This special property determines how the cursor should display in the grid. When this is set to a positive value, the cursor displays a frame that many pixels thick around the cursor's cell. The frame extends partially into the cell and partially outside the cell. When this property is set to a negative value, a light dotted line is drawn around the cell's contents. The absolute value of this property is the number of blank pixels between the cell's border and the dotted line. When it is set to zero, no cursor frame is drawn. The default value is 3.

Parent topic: Special Properties


CURSOR-X (numeric)

Identifies the column in which the cursor is located. Setting this property moves the cursor. Inquiring this property returns the cursor’s location. Note that you may MODIFY this property during a MSG-VALIDATE event to direct where the cursor should go after the user finishes an entry into a cell. However, you should do this only if you are not also forcing the user to stay in entry mode on the current cell. If you move the cursor in response to other events while the user is in entry mode, the results can be confusing.

Parent topic: Special Properties


CURSOR-Y (numeric)

Identifies the record in which the cursor is located. Setting this property moves the cursor. Inquiring this property returns the cursor's location. Inquiring this property returns the cursor’s location. See CURSOR-X for additional comments.

Parent topic: Special Properties


DATA-COLUMNS (numeric)

This special property describes where each column begins in records added to the grid. Columns are defined by character positions in the raw data, with the first character being position 1. For example, the following data item:

01 LIST-DATA.
  03  NAME             PIC X(20).
  03  PHONE-NUMBER     PIC X(15).
  03  STATE            PIC X(2).

would normally be displayed in three columns, one at position 1 (NAME), one at position 21 (PHONE-NUMBER), and one at position 36 (STATE). Each time you set DATA-COLUMNS to a positive value, a new column is created at that position. Setting DATA-COLUMNS to zero clears all the existing column definitions.

Note that there is always a column at position 1, so setting position 1 is not required. An example DATA-COLUMNS setting that would match the LIST-DATA group item, above, would be:

DATA-COLUMNS = (21, 36)

You can also specify DATA-COLUMNS using the RECORD-POSITION construct.

Parent topic: Special Properties


DATA-TYPES (alphanumeric)

Describes various entry characteristics of each column. Each time you set this property, you describe the data type for the next column in the grid, starting with the first. Setting this property to spaces clears the previously specified data types.

A data type specification contains two components. The first is a single character that describes the set of legal characters that the user may type in this column. The set of possible values is:

Character | Description | Characters Allowed
X | Alphanumeric | All characters
U | Uppercase alphanumeric | All characters — automatically converted to uppercase
L | Lowercase alphanumeric | All characters — automatically converted to lowercase
9 | Number | Digits, local decimal point, sign, space
Z | Edited number | Digits, sign, period, comma, local currency symbol, $, *, /, %, space
I | Integer | Digits, sign, space
P | Positive integer | Digits, space
D | Date | Digits, /, hyphen
E | European Date | Digits, /, hyphen, period

You may specify the data type character in either upper or lower case. After the data type character, you may specify the maximum number of characters that may be entered in this column. This value is specified in parentheses. Two values have special meanings:

  • 0 indicates that the maximum characters is set equal to the size of the column
  • -1 indicates no limit other than those imposed by the internals of the grid (that is, 32766 characters)

When a cell may contain more text than it can display, the cell scrolls horizontally in a fashion similar to entry fields.

You may omit either part of the specification. If the data type part is omitted, it defaults to X (all characters allowed). If the size is omitted, it defaults to 0 (match the size of the column). These defaults also apply to columns for which DATA-TYPES has not been specified.

For example, to specify that a column should allow 30 uppercase characters, specify U(30). To create a column that allows only digits for the width of the column, use P(0), or just P.

Note: The data type character limits only which characters the user can enter into the column. The grid itself does not further validate or format the entered data. To do so, you should respond to the MSG-FINISH-ENTRY event. The grid's character filtering is intended only to provide the first stage of validation by allowing only characters that are appropriate for certain types of data.
Parent topic: Special Properties


DISPLAY-COLUMNS (numeric)

This special property describes the number of columns and their location in the grid. The first column always displays in column 1. Additional columns display at the locations set by DISPLAY-COLUMNS. Columns are measured with the standard font. Each time you set DISPLAY-COLUMNS to a positive value, a new display column is defined. Setting DISPLAY-COLUMNS to 0 clears all of the columns (except column 1). Usually, you set DISPLAY-COLUMNS in a list, like this:

DISPLAY-COLUMNS = (1, 21, 35)

This example sets three columns, one starting at column 1, the next starting at column 21 and the last starting at column 35. The last column extends to the end of the grid (but see VIRTUAL-WIDTH below).

The maximum number of columns you can set is 30. Any columns over 30 will be ignored by the runtime and will not display.

In a grid without horizontal scrolling specified (see the HSCROLL style common property), you can have a record occupy multiple rows in a grid. To do this, restart numbering columns at 1 after setting the first row's columns. For example, the following describes a grid with records that span two rows, with three columns on the first row and two columns in the second:

DISPLAY-COLUMNS = (1, 21, 35, 1, 21)

On the screen, one record of this grid would look something like this:

column 1      column 2      column 3

column 4      column 5

You can also use columns to hide data. A column set beyond the right side of the grid is not visible on the screen. You can use this behavior to store information in the grid that your program needs to associate with records, but that you do not want to be seen by the user. One potential use for this feature is to store a file record's primary key value in the hidden column so that you can retrieve the full record easily when the user selects an item in the grid.

Parent topic: Special Properties


DIVIDER-COLOR (numeric)

This special property sets the color of the dividers for the grid. Set this to the color number of the desired color (such as 1 for black or 9 for dark gray). The color ignores the grid's foreground and background intensity — it is treated as the final color value. When this property is set to zero (the default), a system-specific divider color is used. This color depends on the background color for the grid.

Parent topic: Special Properties


DRAG-COLOR (numeric)

Sets the highlight color that's applied to the rectangular area defined when the user clicks and drags the mouse. A DRAG-COLOR value greater than zero defines a color to be applied using the COLOR phrase values.

DRAG-COLOR is used for the same purpose as REGION-COLOR. You should use DRAG-COLOR instead of REGION-COLOR when you want to allow users to highlight a block of cells by clicking and dragging the mouse (REGION-COLOR has poor performance in applications that run with the ACUCOBOL-GT Thin Client).

DRAG-COLOR is applied when the user begins a click-and-drag operation.

DRAG-COLOR is removed when one of the following actions occur:

  • The cursor is moved to a new cell after an MSG-END-DRAG event is generated
  • A heading is clicked
  • An MSG-BEGIN-ENTRY event is generated
  • The property ACTION is set to ACTION-HIDE-DRAG (level 78 found in acugui.def)

The DRAG-COLOR is hidden when the grid does not have focus.

If DRAG-COLOR is specified for a grid that has a menu defined for it, the right-click of the mouse inside the drag region brings up the menu. This allows the user to select a menu item intended specifically for a marked region of the grid. The run-time system determines whether or not a grid has a menu immediately after the event MSG-GRID-RBUTTON-DOWN completes. DRAG-COLOR has a color priority above REGION-COLOR but below CURSOR-COLOR.

Parent topic: Special Properties


END-COLOR (numeric)

Controls the color of the grid in the area past the end of the last column or the end of the last row. In some cases, a blank area is visible. If this property is set to zero (the default), this area is filled with the button face color configured for the host machine (this is set in the Control Panel under Windows). If set to a non-zero value, this value represents the exact ACUCOBOL-GT color to use. These values range from 1 (black) to 16 (bright white).

Parent topic: Special Properties


ENTRY-REASON (alphanumeric)

Records the user's action that caused the grid to shift to entry mode. It is set immediately before the MSG-BEGIN-ENTRY event is generated, and it is retained until overwritten by another MSG-BEGIN-ENTRY event or until the grid is destroyed.

The encoding is a single PIC X character as follows:

x"00" | (binary 0, ASCII null) — indicates that the user double-clicked on the cell
x"0D" | (binary 13, ASCII carriage-return) — indicates that the user pressed the <Enter> key
X"18" | A X"18" (binary 24, ASCII delete key) value indicates that the user pressed the Delete key"
Otherwise | Any other value is the key that the user pressed. For example, if the user started typing "John," the letter "J" is returned by ENTRY-REASON

ENTRY-REASON can be inquired only. Setting it has no effect. You may inquire on ENTRY-REASON during a MSG-BEGIN-ENTRY event to determine what caused the current entry to start. Note that you can then prohibit entry if you desire by moving EVENT-ACTION-FAIL to EVENT-ACTION and returning from the event procedure.

Parent topic: Special Properties


FILE-POS (numeric)

This special property is used only for paged grids. The value of FILE-POS is the grid's record number that matches the current file position in the corresponding data file. It is used to simplify the paging logic in your program. FILE-POS computes the number of records that need to be read in order to find the record needed by the grid. The grid uses this value when generating MSG-PAGED-NEXT or MSG-PAGED-PREV events.

The FILE-POS value will often be either the last visible record in the grid or the first non-heading record visible. To illustrate, suppose that you have a four-line grid with no headings. When you are moving forward through the file, FILE-POS will usually be 4, matching the last record added to the grid. If the user clicks the Next Record button, the MSG-PAGED-NEXT event will indicate that only one READ NEXT is needed to retrieve the appropriate record. However, if the user clicks the Previous Record button, the MSG-PAGED-PREV event will indicate that four READ PREVIOUS statements are needed to get the desired record. In this case, FILE-POS will change to 1, indicating that only one READ PREVIOUS is needed to get another previous record while four READ NEXT statements are needed to get the next record.

In addition, FILE-POS has three special values that are level 78 data names defined in acugui.def. These values are listed below:

PAGED-AT-START | (value 2147418113) | The grid will not generate MSG-PAGED-PREV and MSG-PAGED-PREVPAGE events.
PAGED-AT-END | (value 2147418114) | The grid will not generate MSG-PAGED-NEXT and MSG-PAGED-NEXTPAGE events..
PAGED-EMPTY | (value 2147418115) | MSG-PAGED-NEXT, MSG-PAGED-NEXTPAGE, MSG-PAGE-PREV, and MSG-PAGED-PREVPAGE are not generated. Since it is possible that other users will add records to the file (that could be seen by re-reading it), this value will still generate MSG-PAGED-FIRST and MSG-PAGED-LAST events.

The grid automatically manages FILE-POS, using the following rules:

  • When a record is added to the grid in the topmost non-heading position, FILE-POS is set to that position.
  • When a record is added to the grid or past the last grid record, FILE-POS is set to that position.
  • If you set EVENT-ACTION-FAIL in response to a MSG-PAGED-NEXT event, FILE-POS is set to PAGED-AT-END.
  • If you set EVENT-ACTION-FAIL in response to a MSG-PAGED-PREV event, FILE-POS is set to PAGED-AT-START.
  • If you set EVENT-ACTION-FAIL in response to a MSG-PAGED-FIRST or MSG-PAGED-LAST event, FILE-POS is set to PAGED-EMPTY.
  • If a MSG-PAGED-FIRST event sets EVENT-ACTION (this is the default), FILE-POS is set to PAGED-AT-START.
  • If a MSG-PAGED-LAST event sets EVENT-ACTION, FILE-POS is set to PAGED-AT-END.
  • If you reset the grid, FILE-POS is set to PAGED-EMPTY. Adding records to the grid will change this value.

The automatic handling provided here will correctly handle grids whose data is coming from an indexed data file if you move the file's record pointer only in response to grid events (and only as required by those events). In cases in which you move the file's record pointer independent of a grid request, you will need to do one of the following:

  • Modify FILE-POS to reflect the actual record position. You may use FILE-POS numbers outside of the range of available grid records if needed. For example, if you position the file pointer one record before the first record in the grid, set FILE-POS to 0. Set FILE-POS to 1 to point to the first record in the grid, 0 to point to the record before that, -1 to point to two records before it, and so on. You can also use numbers larger than the last grid record to indicate a position beyond the end of the grid.
  • Reposition the current file pointer to match the FILE-POS value. You can do this by reading the appropriate record from the data file again. Note that a START may not be good enough. START positions the file pointer so that the next READ NEXT or READ PREVIOUS returns the selected record; it may not return the record positioned at either side of that record.
  • Ignore the positioning information passed into the MSG-PAGED-NEXT and MSG-PAGED-PREV events, and the positioning information supplied by the grid control. Supply your own positioning logic. In this case, FILE-POS may be incorrect, but FILE-POS is irrelevant at this point because you are not using it. If you ignore the value of FILE-POS, you must decide whether or not you will use the at-end or at-start feature of FILE-POS. If you don't wish to use this feature, don't set EVENT-ACTION-FAIL in MSG-PAGED-NEXT and MSG-PAGED-PREV events.

Any of the techniques mentioned above will work. Note, however, that FILE-POS may be difficult to compute with the first technique because it is often hard to tell how far apart two records are in an indexed file.

Parent topic: Special Properties


FINISH-REASON (signed integer)

Tracks the reason why the grid user left entry mode and entered navigation mode. Its value is set by the control immediately before generation of a MSG-FINISH-ENTRY or a MSG-CANCEL-ENTRY event. It can be inquired by the event procedure for those events to determine why the user is leaving the field she or he was entering. FINISH-REASON is normally only inquired.

FINISH-REASON is a signed, integer property. It is set by the control to a termination or exception value, or one of several preset values. The preset values are described below, along with the name of a corresponding level 78 data item. These items are found in the COPY library acugui.def.

-1 | GRFR-BLANK-PAST-END | This is a special case in which the entry was finished by the user but canceled by the grid control because the user entered spaces into a blank row past the end of the grid. Instead of growing the grid in this case, the grid rejects the user's entry.
-2 | GRFR-TERMINATING | The grid control is terminating in response to some external event. A typical reason for this would be if the user clicked on another control or window.
-3 | GRFR-CELL-CLICKED | The user clicked another cell in the grid.
-4 | GRFR-NAVIGATION-KEY | The user pressed a navigation key, such as an up or down arrow. This is not generated for the Tab key, because that key is sometimes a navigation key and sometimes not.
-5 | GRFR-ESCAPE-KEY | The user pressed the Escape key.
-6 | GRFR-ENTER-KEY | The user pressed the Enter key.
-7 | GRFR-TAB-KEY | The user pressed the Tab key.

Any other value indicates that the control received a termination or exception value and FINISH-REASON is the value received. For example, under the default keyboard configuration, if the user pressed function key F1, FINISH-REASON is set to 1. However, when the user's action corresponds to a preset value, the preset value takes precedence, because the control directly processes those keys. For example, if you configure the Tab key to return a termination value of 9, the control will still use a value of -7 (GRFR-TAB-KEY) when the user presses the Tab key.

Parent topic: Special Properties


HEADING-COLOR (signed integer)

Sets the color for header cells (both column and row headers). The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid is ignored — the value is treated as the final color value. See COLOR ablove for related information.

Parent topic: Special Properties


HEADING-DIVIDER-COLOR (numeric)

Sets the color to use for drawing row and column dividers in the headings. Set this to the color number of the desired color. The color ignores the grid's foreground and background intensity — it is treated as the final color value. Accepted values range from 1 (black) to 16 (bright white). When this property is set to zero (the default), the dividers in the headings are drawn using the same color as the dividers in the rest of the grid.

Parent topic: Special Properties


HEADING-FONT (numeric)

Sets the font to use for row and column headings. This should be set to a valid font handle. Note that HEADING-FONT takes precedence over ROW-FONT and COLUMN-FONT, but not CELL-FONT.

Parent topic: Special Properties


HIDDEN-DATA (alphanumeric)

This special property allows the program to store data that is not displayed in a cell. A cell can contain both displayed data (see CELL-DATA) and hidden data. Hidden data is limited to 255 bytes per cell. Hidden data may be any format, including non-printing characters.

Note: As with all properties that take a text value, when the value of HIDDEN-DATA is stored, the run-time system automatically strips trailing spaces and low-values.
Parent topic: Special Properties


HSCROLL-POS (numeric)

This property controls the current scrolling position of the horizontal scroll bar, specifying the column number of the left-most column currently visible in the grid. When row-headings are used, HSCROLL-POS specifies the column number that would appear in column one of the grid if there were no headings.

Note that scrolling is limited to the normal scrolling range. If you specify a value larger than the highest allowed value, the latter value is used. If you specify a value less than 1, you will receive undefined results. If the grid does not allow scrolling in the specified dimension, setting this property has no effect.

Parent topic: Special Properties


INSERT-ROWS (numeric)

When set to a positive value, this property inserts that many blank records. These are added immediately before the record identified by INSERTION-INDEX. See INSERTION-INDEX.

Parent topic: Special Properties


INSERTION-INDEX (numeric)

Setting this property to a positive value affects the location of records added via RECORD-TO-ADD. When INSERTION-INDEX is set to zero (the default), records are added to the end of the grid. When it is positive, records are added immediately before the corresponding item instead. For example, setting this to 1 causes the record to be inserted as the first record of the list. When you finish adding the next record, INSERTION-INDEX automatically resets itself to a value of zero.

In statements that allow for multiple properties, the properties are set in the order specified. Therefore, you can set both INSERTION-INDEX and RECORD-TO-ADD in the same statement, providing you specify INSERTION-INDEX first. For example, the following statement will add a new record to the top of a grid:

MODIFY GRID-1,
INSERTION-INDEX = 1,
RECORD-TO-ADD = GRID-DATA-1

When you are inserting a record, the following properties are also affected: ROW-COLOR, ROW-FONT, CELL-COLOR, and CELL-FONT. If these are specified for a record past the insertion point, they will be moved down one record. For example, if you have ROW-COLOR specified for record 5, and you insert record 3, the ROW-COLOR will move to record 6. This causes row and cell properties to follow their data.

Parent topic: Special Properties


LAST-ROW (numeric)

When inquired, returns the record number of the last non-blank record in the grid. Row headings are ignored in determining if a record is blank. If the grid contains no non-blank records, LAST-ROW returns zero.

Parent topic: Special Properties


MASS-UPDATE (numeric)

When set to a non-zero value, this property inhibits most (but not all) updates to the screen by the control. This allows you to make multiple changes to the grid faster and with a smoother screen appearance. When set to zero (the default), changes made to the grid are reflected on the screen. Note that the act of setting this property to zero causes the grid to repaint.

Parent topic: Special Properties


NUM-COL-HEADINGS (numeric)

This property determines the number of rows that will be treated as column headings. When it is set to zero, the grid columns will not have headings. When it is set to a positive value, this value will correspond to the number of rows that will be treated as column headings. For example, if you set the value of this property to 2, the first two records in the grid will be headings. Headings are always visible and can be colored differently from the body of the grid. Specifying more column headers than rows visible in the grid has undefined effects.

This property effectively supersedes the COLUMN-HEADINGS style. If you specify COLUMN-HEADINGS, a NUM-COL-HEADINGS value of 0 is treated as if it were 1. The COLUMN-HEADINGS style has no effect when NUM-COL-HEADINGS is set to greater than zero. This rule provides backwards compatibility with COLUMN-HEADINGS while still allowing for a multi-row column header.

Parent topic: Special Properties


NUM-ROWS (numeric)

Determines the total number of records in the grid. When this property is set to a positive value, the grid allows for exactly NUM-ROWS records. When it is set to zero (the default), the grid extends to the last record that has data defined for it. When it is set to -1, the grid extends to one record past the last record that has data defined for it. This provides a blank record at the end of the grid in which the user can add new data. In the case of 0 and -1, the grid will grow as needed when more records are added.

Parent topic: Special Properties


NUM-ROW-HEADINGS (numeric)

This property determines the number of columns that will be treated as row headings. When it is set to zero, the grid rows will not have headings. When it is set to a positive value, this value will correspond to the number of columns that will be treated as row headings. For example, if you set the value of this property to 2, the first two records in the grid will be headings. Headings are always visible and can be colored differently from the body of the grid. Specifying more row headers than columns visible in the grid has undefined effects.

This property effectively supersedes the ROW-HEADINGS style. If you specify ROW-HEADINGS, then a NUM-ROW-HEADINGS value of 0 is treated as if it were 1. The ROW-HEADINGS style has no effect when NUM-ROW-HEADINGS is set greater than zero. This rule provides backwards compatibility with ROW-HEADINGS while still allowing for a multi-column row header. (create, modify, inquire)

Parent topic: Special Properties


RECORD-DATA (alphanumeric)

When set, replaces an entire record of text in the grid at once. You must set DATA-COLUMNS beforehand to denote where each column's data starts. You must also set the Y property to indicate which row you want to overwrite. If you specify a row that is past the current end of the grid, the effect is the same as adding a new record at that point. Otherwise, the row's existing record is overwritten with the new one.

When inquired, RECORD-DATA returns the data contained in the row identified by property Y. This data is formatted according to DATA-COLUMNS. If the requested row does not exist, the returned value will be entirely spaces.

Parent topic: Special Properties


RECORD-TO-ADD (alphanumeric)

Adds an entire record of text to the grid at once. You must set DATA-COLUMNS beforehand to denote where each column's data starts. The record is usually added at the end of the grid, but you can change this by using INSERTION-INDEX. Note that the new record is added to the grid — it does not overwrite any existing data. Also note that RECORD-TO-ADD will not add an empty record. See CELL-DATA for a way to add individual cells to a grid. See INSERT-ROWS for a way to insert empty records.

Parent topic: Special Properties


RECORD-TO-DELETE (numeric)

Deletes an entire record from the grid. The value of this property is the record number to delete. To enable a user to choose a specific record to delete, identify the specified record by using the CURSOR-X and CURSOR-Y grid properties.

For example, you could create a push button labeled Delete that when pressed deletes the record in which the cursor resides. You do this by defining and coding an event paragraph for the delete push button similar to this:

delete-record.
    INQUIRE grid-1, cursor-x IN grid-x, cursor-y IN grid-y.
    MODIFY grid-1, RECORD-TO-DELETE grid-y.

In this example, regardless of the column (cursor-x) that the cursor is in, the row specified by cursor-y will be deleted.

Deleting a record affects not only data, but also ROW-COLOR, ROW-FONT, CELL-COLOR, and CELL-FONT. If any of these are specified for records following the one deleted, they are moved up one record. This causes them to follow their current data. So, for example, if record 5 has a ROW-COLOR specified for it, and you delete record 3, the ROW-COLOR will now apply to record 4.

Parent topic: Special Properties


REGION-COLOR (numeric)

Sets the color for the region bounded by the rows START-Y and Y and the columns START-X and X (inclusive). When you set REGION-COLOR, any previous region color is removed and a new region is set. The boundaries of the region are set when REGION-COLOR is set. Subsequent changes to X, START-X, Y or START-Y have no effect on the region until the next time that REGION-COLOR is set.

Region color is normally used to highlight an area being marked by the user while dragging the mouse. To do this, usually all you need to do is set REGION-COLOR to the desired color in response to a MSG-GOTO-CELL-DRAG event. Note that when this event is generated, START-X, X, START-Y, and Y all have sensible values in them, and they usually do not need to be set by your program.

Note: REGION-COLOR produces counter-intuitive results when you are displaying more than one row per record. It should be avoided in this case.
Parent topic: Special Properties


RESET-GRID (numeric)

When set to a non-zero value, empties the grid of data. In addition, any ROW-COLOR, ROW-FONT, CELL-COLOR, and CELL-FONT settings are cleared. The cursor is positioned at the home cell (the home cell is the uppermost, left-most, non-heading cell), and the grid is scrolled to the home position. RESET-GRID is a one-time action. Note that this clears the headings as well as the body of the grid. Also note that both text and bitmap data are cleared.

Parent topic: Special Properties


ROW-COLOR (numeric)

Sets the color for the entire record identified by the Y property. The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid are ignored — the value is treated as the final color value.

Note that although the property is called ROW-COLOR, it actually refers to a full record, not just a row. See the COLOR above for related information.

Parent topic: Special Properties


ROW-COLOR-PATTERN (numeric)

Establishes a repeating color pattern to apply to the rows in the grid. The first time you set this property, the specified color is applied to the top row of the grid. The next setting is applied to the second row, and so on. The pattern established then repeats throughout the grid's visible rows. The color value specified uses the COLOR phrase values for both foreground and background colors. The foreground and background intensity of the grid are ignored — the value is treated as the final color value. Note that the color pattern is fixed to the visible rows in the grid independently from the current vertical scroll position. Scrolling through the grid does not change the visible aspects of the color pattern. This prevents a jittery display while the user scrolls vertically.

This example sets a two-row pattern in which the first row will be background white (512) and the second will be background yellow (480). In both cases, the foreground is unspecified (zero added to the value) and will come from some other source:

ROW-COLOR-PATTERN = ( 512, 480 )

See COLOR above for related information.

Parent topic: Special Properties


ROW-DIVIDERS (numeric)

This property establishes the width (in pixels) of the row dividers. Each time you set this property to a non-negative value, you set the width of the divider for one row of a record. The first setting applies to the first row, the second to the second row, and so on. The pattern established for one record repeats throughout the grid. You can clear the list of divider settings by assigning a value of -1. Unspecified dividers use a system-dependent default width. The default divider is one-pixel wide.

Assuming two rows per record, the following example would create a pattern in which records are divided from each other by a two-pixel border, and the two rows within the record are divided by a one-pixel border:

ROW-DIVIDERS = (1, 2)
Parent topic: Special Properties


ROW-FONT (numeric)

Sets the font for the record identified by the Y property. This should be set to a valid font handle. Note that ROW-FONT refers to the font used for an entire record, not just a row.

Parent topic: Special Properties


ROW-PROTECTION (numeric)

Protects the entire row identified by the Y property from being changed by the user. Set the property to 1 to protect the row or to 0 to unprotect the row. The appearance of the row does not change when the row is protected. Note that like other row properties, the setting affects an entire record, not just the physical row.

Parent topic: Special Properties


SEARCH-OPTIONS (alphanumeric)

This property controls how searches are performed in the grid.

Note: The grid's search facility does not contain a user interface. You must supply one if you want to give the user a search function. One typical interface is a pop-up dialog box in which the user can set the search text and options desired. Another typical interface is an entry field in the same window as the grid, with a Find button beside the entry field.

The SEARCH-OPTIONS property should be assigned from a structure with the following layout:

01 GRID-SEARCH-OPTIONS.
   03 GRID-SEARCH-DIRECTION         PIC 9.
      88 GRID-SEARCH-FORWARDS       VALUE ZERO,
                                    FALSE 1.

   03 GRID-SEARCH-WRAP-FLAG         PIC 9.
      88 GRID-SEARCH-WRAP           VALUE ZERO,
                                    FALSE 1.

   03 GRID-SEARCH-CASE-FLAG         PIC 9.
      88 GRID-SEARCH-IGNORE-CASE    VALUE ZERO,
                                    FALSE 1.

   03 GRID-SEARCH-MATCH-FLAG        PIC 9.
      88 GRID-SEARCH-MATCH-ANY      VALUE ZERO.
      88 GRID-SEARCH-MATCH-LEADING  VALUE 1.
      88 GRID-SEARCH-MATCH-ALL      VALUE 2.

   03 GRID-SEARCH-LOCATION-FLAG     PIC 9.
      88 GRID-SEARCH-VISIBLE        VALUE ZERO.
      88 GRID-SEARCH-HIDDEN         VALUE 1.
      88 GRID-SEARCH-ALL-DATA       VALUE 2.

   03 GRID-SEARCH-SKIP-FLAG         PIC 9.
      88 GRID-SEARCH-SKIP-CURRENT   VALUE ZERO,
                                    FALSE 1.

   03 GRID-SEARCH-CURSOR-FLAG       PIC 9.
      88 GRID-SEARCH-MOVES-CURSOR   VALUE ZERO,
                                    FALSE 1.

   03 GRID-SEARCH-COLUMN            PIC 9(5).
      88 GRID-SEARCH-ALL-COLUMNS    VALUE ZERO.

A copy of this structure can be found in the copy library acugui.def. It contains the default value settings for all the grid search parameters. Use the COPY statement in the Working Storage section to include this structure with its default values in your program.

To set the SEARCH-OPTIONS property, specify the name of the data structure described above in the screen description entry for the grid or via the MODIFY statement. The example below uses the MODIFY statement to assign the property:

MODIFY GRID-1
SEARCH-OPTIONS = GRID-SEARCH-OPTIONS

To set new search values for a grid, start by using the INQUIRE statement to find out what the current values are (they may have been modified previously). Next, set the desired values to the chosen search parameters with the SETstatement, and finally, modify the grid to apply the new values.

The following sample shows how to change the values for two of the search parameters and apply the new search options to the grid.

INQUIRE grid-1, SEARCH-OPTIONS
       IN GRID-SEARCH-OPTIONS
SET (option-1) TO TRUE
SET (option-2) TO TRUE
MODIFY grid-1,
       SEARCH-OPTIONS = GRID-SEARCH-OPTIONS

The SEARCH-OPTIONS parameters have the following traits:

GRID-SEARCH-FORWARDS | When set to true the default, the search runs from left-to-right and top-to-bottom in the grid. This is the default behavior. When set to false, the search runs from right-to-left, bottom-to-top.
GRID-SEARCH-WRAP | When set to true (the default), a search wraps around when it hits the top or bottom of the grid. This causes the search to proceed from the opposite end of the grid. When set to false, the search stops if it hits the top or bottom of the grid.
GRID-SEARCH-IGNORE-CASE | When set to true (the default), the search ignores case differences between letters when determining if two strings match. When set to false, a difference in case between strings will cause them not to match. You should be certain to set this to "false" when searching for data that contains binary information (this could happen if you search the grid's hidden data).
GRID-SEARCH-MATCH-ANY | When set to true (the default), a search string will match if the string is contained anywhere in the cell's data (similar to a substring search). For example, a search for "bcd" would match the string "abcde".
GRID-SEARCH-MATCH-LEADING | When set to true, a search string will match if the string forms the beginning of the cell's data. For example, a search for "bcd" would match the string "bcde", but not the string "abcde".
GRID-SEARCH-MATCH-ALL | When set to true, a search string matches only if it is identical to the string being searched. For example, "bcd" will match "bcd", but not "abcde" or "bcde".
GRID-SEARCH-VISIBLE | When set to true (the default), the search is performed only against the grid's visible cell data.
GRID-SEARCH-HIDDEN | When set to true, the search is performed only against the grid's hidden data.
GRID-SEARCH-ALL-DATA | When set to true, the search is performed against both the grid's visible and hidden data.
GRID-SEARCH-SKIP-CURRENT | When set to true (the default), the cell in which the search starts is not initially searched. If you allow the search to wrap, it will be searched last. If you do not allow the search to wrap, the starting cell will not be searched. This setting allows a find next function to work. When set to false, the starting cell is searched first. Note that if you start the search from a cell that is outside the range of existing cells, the starting cell is searched first regardless of the setting of this flag. This allows you to find the first occurrence of a string by starting your search at row 0 regardless of the setting of this flag.
GRID-SEARCH-MOVES-CURSOR | When set to true (the default), the grid's cursor will move to the cell found by the search. The grid will also scroll to make that cell visible. If the search fails, the cursor is not moved. When set to false, the cursor is not moved by a successful search.
GRID-SEARCH-COLUMN | When GRID-SEARCH-ALL-COLUMNS is set to true, the search runs through every column in the grid. Otherwise, if you set GRID-SEARCH-COLUMN to a non-zero value, the search runs through that column number only. Columns other than this column are ignored. Note that row and column headings are not normally searched. You can search the row headings by setting GRID-SEARCH-COLUMN to 1 (assuming that you have row headings). You cannot search the column headings.

If you need to limit your search to two or more columns, but not all the columns, you will need to program the limited search yourself by first setting GRID-SEARCH-ALL-COLUMNS and GRID-SEARCH-SKIP-CURRENT to true, and GRID-SEARCH-MOVES-CURSOR to "false". Then perform the search in a loop. Break out of the loop when GRID-SEARCH-COLUMN equals one of the desired columns or when the search fails. The search fails when it does not find a match or the search returns a cell that is the same cell as the first match it returned (in this case, the data you're searching for appears only in cells outside the desired columns). After finding a successful match, you can place the cursor in that cell using the CURSOR-X and CURSOR-Y properties.

The following example turns off wrapping and turns on forward searching for a particular grid. This shows you how to change some settings while leaving others unchanged:

COPY "acugui.def".
INQUIRE GRID-1, SEARCH-OPTIONS
       IN GRID-SEARCH-OPTIONS
SET GRID-SEARCH-WRAP TO FALSE
SET GRID-SEARCH-FORWARDS TO TRUE
MODIFY GRID-1,
       SEARCH-OPTIONS = GRID-SEARCH-OPTIONS

The default settings are the same as the settings you get by moving ZEROS to the GRID-SEARCH-OPTIONS data structure.

Parent topic: Special Properties


SEARCH-TEXT (alphanumeric)

When you assign this property, the grid initiates a search using the current search options. The program looks for the value assigned to this property. The search starts in the cell identified by the X and Y properties, unless overridden by the GRID-SEARCH-SKIP-CURRENT described under SEARCH-OPTIONS. If the search is successful, X and Y are updated to reflect the cell found. The return value of this property is the status of the search:

GRDSRCH-NOT-FOUND | (value 0) | No matching data found
GRDSRCH-FOUND | (value 1) | Search succeeded
GRDSRCH-WRAPPED | (value 2) | Search succeeded but had to wrap

If X and Y identify a cell outside of the range of cells, the starting cell is determined as if the search wrapped from the logical (X,Y) location. For example, if the starting point is a cell past the right-most cell, a forward search starts at the first cell of the next row. You can use this to force a search of the entire grid by starting a forward search at row 0, or a backward search from a row that is past the end of the grid's data.

The following sample code searches a grid for the word "science," starting at the cell where the cursor is currently located:

INQUIRE GRID-1, CURSOR-X IN CUR-COL,
                CURSOR-Y IN CUR-ROW
MODIFY GRID-1 (CUR-ROW, CUR-COL)
SEARCH-TEXT = "science" GIVING RESULT-1
IF RESULT-1 > GRDSRCH-NOT-FOUND
    DISPLAY MESSAGE BOX "Search succeeded".

The grid's search facility does not contain a user interface. You must supply one if you want to give the user a search function. One typical interface is a pop-up dialog box in which the user can set the search text and options desired. Another typical interface is an entry field in the same window as the grid, with a Find button beside the entry field.

Parent topic: Special Properties


SEPARATION (numeric)

Describes the amount of white space that should be preserved at the end of each column. This space appears between the end of the data and the beginning of the next column. The column divider, if any, appears in the region. This space is expressed as tenths of the standard font width. For example, a value of 5 indicates a half-character width.

Each time you set this property, you set the separation amount for the next column in the grid, starting with the first. Setting this property to -1 clears the previously specified separation amounts. The default separation used for unspecified columns is set by the COLUMN-SEPARATION configuration variable. This defaults to 5.

Parent topic: Special Properties


SORT-TYPES (alphanumeric)

SORT-TYPES is an alphanumeric property that can be repeated for each column contained in the grid. The value determines the sorting property of the column as shown in the table. Many of these values are similar to those for the DATA-TYPES property.

Value | Meaning
- | Not sortable. This is the default. Any value other than the ones described below also prevents sorting on the column.
X | Alphanumeric sorting, case-insensitive
U, L | Alphanumeric sorting, case-sensitive
A | Not implemented, reserved for future use
9, N | Numeric sorting, leading sign and current decimal-point used, all other non-digit characters ignored
Z | Not implemented, reserved for future use
I | Integer sorting, leading sign used, all other non-digit ignored
P | Positive integer sorting, all non-digit characters ignored
D, E | Date sorting. Assumes three integer fields separated by one or more non-digit characters. Integers are year, month and day. Two-digit years less than 30 are treated as year 20xx while other two-digit years are treated as year 19xx. The default ordering of the fields is month, day, year if the current decimal point character is a point or period (.), otherwise the default ordering is day, month, year. You can explicitly specify the ordering by appending a three-character string enclosed by parenthesis, using Y, M and D to represent the year, month and day respectively. For example, D(YMD) is date order, with the date being in year-month-day order. Invalid format strings have undefined results. Only MDY, DMY and YMD are currently valid.

Equivalent lowercase letters may substitute for any of the formats above.

The default sort ordering is ascending. You may specify the default order as descending by appending a caret (^) to the SORT-TYPES value. For example A^ specifies a descending alphanumeric sort. Optional elements may be specified in any order. For example D^(MDY) and D(MDY)^ both specify a descending date field using the month-day-year ordering.

Ascending/descending order only determines the sort order when the user first clicks on the column. After that, the user can reverse the ordering by clicking again. The current order is indicated by the triangle or arrow indicator displayed next to the column title; you can configure the type of indicator using the GRID_SORT_INDICATOR configuration variable.

Alphanumeric ordering is done using the current language sort order on the client machine as defined by the operating system (i.e. Windows).

The user requests the sort by clicking on the column header. A grid must have column headings in order to be sorted by the user.

Events

MSG-BEGIN-SORT - Generated when the user clicks on the heading of a sortable column. EVENTDATA-1 contains the column number. EVENT-ACTION determines how the control responds:

  • EVENT-ACTION-NORMAL (default) - The grid's records are sorted by the column.
  • EVENT-ACTION-COMPLETE - Nothing further happens. Use this to provide a custom sort procedure by emptying the grid and reloading it in the desired order.
  • EVENT-ACTION-FAIL - Same effect as EVENT-ACTION-COMPLETE.

MSG-FINISH-SORT - Generated with the grid has completed a sorting operation. EVENT-DATA-1 contains the column number used to sort and EVENT-DATA-2 contains the record number of the last row of data in the grid. Use this to re-synchronize a data source's position for a paged grid.

Note: Grid sorting uses quicksort to sort the columns. While this is very fast, it is known that quicksort is not a stable sorting algorithm. Stable sorting algorithms maintain the relative order of records with equal keys. Since quicksort is not a stable sorting algorithm, sorting on one column and then a different column does not necessarily keep the original column in sorted order (for those rows that have duplicates in the different column).

Also, because rows are not necessarily in the order they were placed into the grid, use the NEXT, PREVIOUS, NEXT PAGE, and PREVIOUS PAGE events with care. And the TOP and END events may show unexpected rows. This is because all of these events assume that the grid rows are in the original order (the order you placed them into the grid originally). Care must be taken when using the SORT property on paged grids to avoid confusing your users.

Parent topic: Special Properties
Related reference
GRID-SORT-INDICATOR


START-X (numeric)

The START-X special property is used in conjunction with the START-Y, X, and Y properties to define a rectangular region in the grid. This region is used when you are setting REGION-COLOR. START-X holds a column number. The region colored by REGION-COLOR starts at START-X and extends through X.

Parent topic: Special Properties


START-Y (numeric)

The START-Y special property is used in conjunction with the START-X, X, and Y properties to define a rectangular region in the grid. This region is used when you are setting REGION-COLOR. START-Y holds a row number. The region colored by REGION-COLOR starts at START-Y and extends through Y. See START-X and REGION-COLOR for a description of this property.

Parent topic: Special Properties


VIRTUAL-WIDTH (numeric)

Sets the overall logical width of the grid. This is used only with grids that have horizontal scrolling. This value is expressed in characters (measured using the standard font width). If not specified, the grid extends to 10 characters past the last DISPLAY-COLUMN specified (making the last column 10 characters wide). You can create hidden columns by setting this value smaller than some of your columns' starting points.

Parent topic: Special Properties


VPADDING (numeric)

Sets the amount of vertical white space in each row. This value is the percentage of the grid's font height to apply as extra white space (that is, separation between the cell's data and the cell's row dividers). The default setting is 50. Note that this produces a look similar to a series of entry fields (because the normal entry field is 50 percent taller than its font). On character systems, the VPADDING value is not used.

Note: The Windows implementation of the grid control uses the standard "edit" (entry field) control to do its data entry (it creates the edit control when the grid shifts to entry mode). The Windows edit control has technical limitations with regards to vertical spacing. These limitations depend on the alignment of the field (left-justified fields have fewer limitations). Setting VPADDING to less than 50 can result in odd behavior. If you set VPADDING to less than 50, be sure to check that the grid behaves the way you want on your target platforms.
Parent topic: Special Properties


VSCROLL-POS (numeric)

This special property controls the current scrolling position of the vertical scroll bar, specifying the first visible row of the grid's scrollable region. Note that scrolling is limited to the normal scrolling range. If you specify a value larger than the highest allowed value, the latter value is used. If you specify a value less than 1, you will receive undefined results. If the grid does not allow scrolling in the specified dimension, setting this property has no effect.

Parent topic: Special Properties


X (numeric)

The X special property holds a column number. It is used by several other properties when they need to know which column to act on. For example, the COLUMN-COLOR property sets the color for the column identified by the X property. Column numbers start at 1. Remember that properties are set in the order specified in a statement. You should be certain to set the X property before setting another property that refers to it.

Parent topic: Special Properties


Y (numeric)

The Y special property holds a record number. It is used by several other properties when they need to know which column to act on. For example, the ROW-COLOR property sets the color for the row identified by the Y property. Row numbers start at 1. Remember that properties are set in the order specified in a statement. You should be certain to set the Y property before setting another property that refers to it.

Parent topic: Special Properties


Events

CMD-GOTO
CMD-HELP
MSG-VALIDATE
MSG-BEGIN-ENTRY
MSG-FINISH-ENTRY
MSG-CANCEL-ENTRY
MSG-GOTO-CELL
MSG-GOTO-CELL-MOUSE
MSG-GOTO-CELL-DRAG
MSG-BEGIN-DRAG
MSG-END-DRAG
MSG-BEGIN-SORT
MSG-END-SORT
MSG-BITMAP-CLICKED
MSG-HEADING-CLICKED
MSG-HEADING-DBLCLICKED
MSG-HEADING-DRAGGED
MSG-BEGIN-HEADING-DRAGGED
MSG-END-HEADING-DRAGGED
MSG-COL-WIDTH-CHANGED
MSG-INIT-MENU
MSG-MENU-INPUT
MSG-END-MENU
MSG-GRID-RBUTTON-UP
MSG-GRID-RBUTTON-DOWN
MSG-PAGED-FIRST
MSG-PAGED-LAST
MSG-PAGED-NEXT
MSG-PAGED-NEXTPAGE
MSG-PAGED-PREV
MSG-PAGED-PREVPAGE
MSG-PAGED-NEXT-WHEEL
MSG-PAGED-PREV-WHEEL
Parent topic: Grid


Label

The LABEL control type displays a simple string of text. Labels cannot take any input from the user and, thus, cannot be activated. Use labels to describe entry fields, or for any other situation in which you need to display simple text.

Labels may occupy multiple lines. When a label is displayed on multiple lines, it will use word-wrapping if possible so that words are not broken across lines.

  • Common Properties
  • Special Properties
  • Events
  • Examples
Parent topic: Control Types


Common Properties

TITLE

Labels can take titles. The text of the title is the text displayed on the screen. The TITLE phrase is used to specify a title. A key letter may be specified in the title. See the entry for TITLE Phrase in Common Screen Options in the ACUCOBOL-GT Reference Manual for more information.

VALUE

Labels cannot be activated and do not take values.

SIZE

Labels define their height by multiplying the LINES value by the height of the label's font (including any interline spacing). For example, a LINES value of 1 indicates one line of text. Labels define their width by multiplying the SIZE value by the width of the zero character of the label's font.

When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.

The default value of LINES is 1. The default value of SIZE is computed by measuring the length of the label's title using the label's font and dividing by the width of the zero character. Thus, the default width of a label exactly occupies the space its text takes up on the screen.

To get a multiline label, set the LINES value to the number of lines wanted and the SIZE value to the desired width. SIZE specifies the width that each line of the label will occupy

COLOR

Labels use both the foreground and background colors specified. If either is omitted, the corresponding color of the label's owning subwindow is used.

If you are using the WIN32_NATIVECTLS runtime variable to automatically enable Windows XP or Vista control styles, label background colors may exhibit a darker background when residing on frames or tab frames. This is because XP and Vista label controls have a different background color than frames or tab frames. Making labels have the TRANSPARENT property resolves this issue.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

STYLES

LEFT | This alignment style causes the label’s text to be left-aligned in its region. By default, the label text is not justified. When LEFT, RIGHT, or CENTER is specified at the time the label is created, the label's text is stripped of leading and trailing spaces before the default size is computed.
RIGHT | This style causes the label's text to be right-aligned in its region. This will appear no differently from LEFT if the SIZE of the label does not provide any extra space for the label's text.
CENTER, CENTERED | This style causes the label's text to be centered in its region. This will appear no differently from LEFT if the SIZE of the label does not provide any extra space for the label's text.
NO-KEY-LETTER | This style suppresses the interpretation of "&" as a key prefix. This is useful in cases in which you are assigning user-entered data to a label and want to allow values that include the ampersand ("&") character (such as "AT&T").
TRANSPARENT | This style makes a label's background invisible, so that anything underneath the label shows through. TRANSPARENT is useful if you want to display a label that blends into a background having more than one color. It is also useful when labels appear on frames or tab frames and you are using the WIN32_NATIVECTLS runtime variable to automatically enable XP or Vista control styles. In this case (due to Microsoft design of these controls) the label may have a darker background than the frame. Making the label transparent resolves this issue.
Parent topic: Label
Related concepts
Cascading Style Sheet Syntax


Special Properties

LABEL-OFFSET (numeric)

Labels are frequently placed to the left of boxed entry fields. Boxed entry fields are typically taller than their labels. This can create an alignment task, because labels and entry fields placed at the same row coordinate will not line up properly (the top of the label will match the top of the entry field's box instead of lining up with the field's center). The LABEL-OFFSET property enables you to adjust for this by moving the label down the screen slightly. The value of LABEL-OFFSET specifies the amount to move the label. Its units are hundredths of rows. The default value is machine-dependent. For Windows, it is "20" (that is, 0.20 rows).

LABEL-OFFSET is ignored when the control's coordinates are specified in pixels (that is, absolute coordinates).

Note: You can globally affect the default value with the FIELDS-UNBOXED configuration variable.
Parent topic: Label


Events

Labels do not generate events.

Parent topic: Label


Examples

The following creates a simple anonymous label. The label is anonymous because the statement doesn't store the label's handle and there is no way to refer to it later in the program.

DISPLAY LABEL "Customer No:", LINE 2, COLUMN 5.

The equivalent in the Screen Section would be:

03 LABEL "Customer No:", LINE 2, COLUMN 5.

The following creates a three-line label:

DISPLAY LABEL,
   TITLE MY-LARGE-TEXT
   SIZE 15, LINES 3.

These Screen Section entries produce a set of labels that are all right-aligned:

03  LABEL "Date Entered:", SIZE 20, RIGHT.
03  LABEL "Date Modified:", LINE + 1,
       SIZE 20, RIGHT.
03  LABEL "Date Closed:", LINE + 1,
       SIZE 20, RIGHT.
Parent topic: Label


List Box

A LIST-BOX control presents a vertical list of items that the user can scroll through and select.

List box text limits are based on machine memory, which essentially equates to no limit. Memory is allocated as needed.

Note: Paged List Boxes are discussed in Paged List Boxes.
  • Common Properties
  • Special Properties
  • Events
  • Using Special Keys
  • Examples
Parent topic: Control Types


Common Properties

The set of list box common properties includes:

TITLE

List boxes do not have titles.

VALUE

A list box has an alphanumeric value.

When VALUE is set, the list is searched for an exact, case-sensitive match with the specified value. If the value is found, it is selected. If an exact match is not found, the list is searched for an exact match regardless of case. If a match is still not found, the list is searched again, this time for the first string that contains the passed VALUE as a leading substring, regardless of case. For example, if your list contains:

  • Capital Building
  • Capital-inc, unit 2
  • Capital-Inc

and VALUE is set to Capital-Inc, the third item is selected. If VALUE is set to CAP, the first item is selected.

On termination of a list box entry, the value is the currently selected list item, or spaces if no item is selected

SIZE

The LINES setting specifies the number of lines of text that are visible in the list box. The SIZE setting determines the maximum width of the text area as a multiple of the width of the zero character of the list box's font. Any overhead needed for the box itself, or any scroll bars, is added to the height and width. The list box handler does not allow partial lines of text to be displayed, so the height of the list box may be reduced accordingly.

When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.

The default LINES value is 5. The default SIZE value is 12.

Note: The scroll bar is hidden if the list of items is small enough to be shown on the screen. If this happens, the list box may appear wider than specified, because some systems add the space devoted to the scroll bar into the text area. When enough items are added to the list to require a scroll bar, the text space is reduced and the scroll bar displayed. If you are using the WIN32_NATIVECTLS runtime variable, drop-down list behavior changes. A Windows XP style list automatically expands downward to show up to 30 items at a time, regardless of whether or not it temporarily overlaps a control beneath it. A scroll bar will not appear unless there are more than 30 items.

COLOR

List boxes will use any specified foreground or background color. If either color is omitted, that color uses a system-dependent default value. On most systems, the default foreground is black and the default background is white. Under Microsoft Windows, the default values are determined by the user's choices in the Control Panel (usually black on bright-white). These system-dependent default colors are not transformed or mapped by the runtime system's color-handling configuration options.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

STYLES

UNSORTED | Normally the items in the list are automatically sorted alphanumerically. Alternatively, the UNSORTED style causes the list to be shown in the order in which the items are added.
LOWER | Converts all the text in the box to lower-case.
UPPER | Converts all the text in the box to upper-case.
PAGED | Specifies that the list box is to be a paged list box. Paged list boxes are typically used when the number of items in the list is too large for a standard list box. See Paged List Boxes in Graphical Controls for a complete description of paged list boxes and an introduction to how they are programmed.
NO-BOX | Removes the box that normally displays around the listed items.
BOXED | This style indicates that a box should be placed around a list box. It is the default for graphical versions of ACUCOBOL-GT For character-based versions of ACUCOBOL-GT, the default depends on the configuration variable LISTS_UNBOXED.
3-D | Causes the list box to appear inscribed into the surface of the screen. This looks similar to the LOWERED frame style. The runtime system uses the background color of the floating window to determine how to draw the frame. The background color is set when the window is created and each time the window is erased. This color must be one of the low-intensity standard colors, except for black (color numbers 2–7). Any other background color will prevent the 3-D effect from displaying. Only boxed list boxes will display 3-D effects. See Frame in Control Types Reference for more information.
NOTIFY-DBLCLICK | This causes the list box to generate CMD-DBLCLICK events. Normally, double-clicking on an item in the list box has no special effect. If you specify this style, double-clicking on an item will generate a CMD-DBLCLICK event. This will usually terminate the current ACCEPT statement and allow your program to act on the selection immediately. You can also use an associated EXCEPTION PROCEDURE in the Screen Section to perform immediate processing. See also the TERMINATION-VALUE and EXCEPTION-VALUE special properties for related information.
NOTIFY-SELCHANGE | This style causes the list box to generate NTF-SELCHANGE events. Normally, selecting an item in the list box has no special effect. If you specify this style, a selection change will generate an NTF-SELCHANGE event. This allows your program to act immediately on the new selection.
NO-SEARCH | This style affects only paged list boxes. It inhibits the box's built-in search facility. If this style is in effect, the user can move around in the paged list box with the arrow buttons and keyboard keys, but cannot bring up the search box.
Parent topic: List Box
Related concepts
Cascading Style Sheet Syntax


Special Properties

  • ITEM-TO-ADD (alphanumeric)
  • RESET-LIST (numeric)
  • MASS-UPDATE (numeric)
  • ITEM-TO-DELETE (numeric)
  • INSERTION-INDEX (numeric)
  • SEARCH-TEXT (alphanumeric)
  • DATA-COLUMNS (numeric)
  • DISPLAY-COLUMNS (numeric)
  • ALIGNMENT (alphanumeric)
  • SEPARATION (numeric)
  • DIVIDERS (numeric)
  • SELECTION-INDEX (numeric)
  • THUMB-POSITION (numeric)
  • QUERY-INDEX (numeric)
  • ITEM-VALUE (alphanumeric)
  • TERMINATION-VALUE (numeric)
  • EXCEPTION-VALUE (numeric)
  • SORT-ORDER (numeric)
Parent topic: List Box


ITEM-TO-ADD (alphanumeric)

This property provides a way of adding items to the list box. Any time you create or modify a list box, the ITEM-TO-ADD property is examined. If it is not spaces, its value is added to the items in the list box. The examples below demonstrate how to use this property to initially populate a list box.

Parent topic: Special Properties


RESET-LIST (numeric)

This property allows you to empty a list. If this property is 0, it is ignored. If it is non-zero, all the items in the list are deleted.

Parent topic: Special Properties


MASS-UPDATE (numeric)

This property improves the efficiency of making large content changes to a combo or list box.

Normally, the runtime system immediately repaints a combo or list box when the program adds/removes an item to/from the box. If you are making several changes in a row, this process can be slow. To improve performance, set the MASS-UPDATE property to 1. While set to 1, MASS-UPDATE inhibits repainting of the box because of changes in the box contents. To repaint after you have finished your changes, set MASS-UPDATE to zero (0).

For example, this code could be used to initially populate the contents of a combo box:

MODIFY COMBO-BOX-1, MASS-UPDATE = 1
PERFORM VARYING IDX FROM 1 BY 1
   UNTIL IDX > COMBO-BOX-SIZE
      MODIFY COMBO-BOX-1,
         ITEM-TO-ADD = COMBO-BOX-ITEM( IDX )
END-PERFORM
MODIFY COMBO-BOX-1, MASS-UPDATE = 0

In this example, the combo box will not be repainted until the last MODIFY statement executes.

Parent topic: Special Properties


ITEM-TO-DELETE (numeric)

Setting this property to a non-zero value deletes the corresponding item in the list box. The first item in the list is item number "1", and each item is numbered sequentially thereafter. Deleting a non-existent item has no effect.

Parent topic: Special Properties


INSERTION-INDEX (numeric)

Setting this property to a positive value affects the location of the next item added to the list box. When it is set to zero (the default), items are added in sort-order, or to the end of the box if the list box has the UNSORTED style. When INSERTION-INDEX is positive, the next item added is placed immediately before the corresponding item instead. For example, setting this to 1 causes the next item to be inserted at the top of the list. You can place an item at the end of the list by specifying an index one greater than the number of items in the list. When you finish adding the next item, INSERTION-INDEX automatically resets itself to a value of zero.

In statements that allow for multiple properties, the properties are set in the order specified. Therefore, you can set both INSERTION-INDEX and ITEM-TO-ADD in the same statement, providing you specify INSERTION-INDEX first. For example, the following statement will add a new item to the top of a list box:

MODIFY LIST-BOX-1,
   INSERTION-INDEX = 1,
   ITEM-TO-ADD = "New top item"
Parent topic: Special Properties


SEARCH-TEXT (alphanumeric)

This property is used only in conjunction with paged list boxes. SEARCH-TEXT returns the current value of the user-supplied search text. Normally, this property is used in an INQUIRE statement when you implement a response to the NTF-PL-SEARCH event (which indicates that the user wants to search for a particular text string in the list box). See Paged List Boxes for a complete description and code example.

Parent topic: Special Properties


DATA-COLUMNS (numeric)

This property describes where each column begins in the data added to the list. Columns are defined by character positions in the raw data, with the first character being position 1. For example, the following data item:

01 LIST-DATA.
   03  NAME           PIC X(20).
   03  PHONE-NUMBER   PIC X(15).
   03  STATE          PIC X(2).

would normally be displayed in three columns, one at position 1 (NAME), one at position 21 (PHONE-NUMBER), and one at position 36 (STATE). Each time you set DATA-COLUMNS to a positive value, a new column is created at that position. Setting DATA-COLUMNS to zero clears all the existing column definitions. Note that there is always a column at position 1, so setting position 1 has no useful effect.

Typically, you specify DATA-COLUMNS by enclosing a list of columns in parentheses. This causes the compiler to generate code to set each column in turn. For example, a setting that would match the preceding example would be:

DATA-COLUMNS = ( 21, 36 )

This can also be specified with the RECORD-POSITION construct. The data item is referenced by a numeric literal whose value corresponds to the location of the data item within the record. See RECORD-POSITION for more information. For example, the above example would be:

DATA-COLUMNS = (
    record-position of PHONE-NUMBER,
    record-position of STATE )

You must also specify DISPLAY-COLUMNS to get the columns to display correctly. If you don't, the results are undefined.

Parent topic: Special Properties


DISPLAY-COLUMNS (numeric)

This property describes where each DATA-COLUMN will display in the list box. The first column always displays in column 1. Additional columns display at the locations set by DISPLAY-COLUMNS. Columns are measured with the standard font measure (that is, the width of the character 0 in the list box's font). Each time you set DISPLAY-COLUMNS to a positive value, a new display column is defined. Setting DISPLAY-COLUMNS to 0 clears all of the columns (except column 1).

If you are using a proportionally spaced font, you should provide enough space in each column to allow for wider-than-average data. You will also want to provide some white space between columns. For example, you might code the following:

DATA-COLUMNS = ( 21, 36 )
DISPLAY-COLUMNS = ( 31, 51 )

In this example, the first column, which is 30 characters wide in the display, accommodates a 20-character data source, and the second column, which is 20 characters wide, accommodates a 15-character data source.

The maximum number of columns you can set is 30. Any columns over 30 will be ignored by the runtime and will not display.

Data contained in a column cannot overflow the allocated space. If the data is too large to be fully displayed, the data is truncated. Therefore, you should always set your columns wide enough to hold the largest data item.

Note: You can also use columns to hide data. A column set beyond the right side of the list box is not visible on the screen. You can use this behavior to store information in the list box that your program needs to associate with list items, but that you don't want to be seen by the user. One potential use for this feature is to store a file record's primary key value in the hidden column so that you can retrieve the full record easily when the user selects an item in the list.
Parent topic: Special Properties


ALIGNMENT (alphanumeric)

This property specifies the alignment of data in each column. Like DATA-COLUMNS and DISPLAY-COLUMNS, each time you assign this property, you affect a new column. Allowed values are:

L | left alignment
R | right alignment
C | centered alignment
U | unaligned

Equivalent lower-case values are also allowed, as are any words that start with the appropriate letters (thus, you can spell out left, right, and center if you want). For example, to establish a left-aligned column followed by two right-aligned columns, you would use:

ALIGNMENT = ( "L",  "R",  "R" )

To empty the alignment list (to establish new alignments, for example) assign an alignment value of space (" "). Left alignment differs from unaligned in that leading spaces are removed from left-aligned data, but not from unaligned data. Any column that does not have an alignment specified for it is unaligned.

Parent topic: Special Properties


SEPARATION (numeric)

This special property establishes a blank region at the end of each column. This has the effect of creating a uniform separation space between each column and prevents data from visually running together. When data is too large to fit in the allocated space, the data is truncated to the column width minus the separation space.

Like DATA-COLUMNS, each time you assign a value to this property, you set the separation amount for a new column. The separation is expressed in tenths of characters. For example, to establish a half-character separation, use a value of 5. On character-based systems, the separation is rounded down to the nearest whole character. The blank region specified appears at the end of the column. Data is never displayed in the separation region, it is truncated if need be. Also, the separation region defines the edge from which right and center justification are computed. To reset the separation list for a box, assign the value -1. Unspecified columns use a default separation value. This value is set by the configuration variable COLUMN-SEPARATION.

Parent topic: Special Properties


DIVIDERS (numeric)

When set, this property causes divider bars to be displayed between columns. Like DATA-COLUMNS, each time you assign a value to this property, you establish the divider for a new column.

The value assigned is the width of the divider, in pixels. A width of zero means that there will be no divider. The divider appears after the column, immediately before the beginning of the next column (there is a small space between the divider and the next column's text). To reset the list of dividers, assign a value of -1. The divider's color is the shadow color of the list box (usually dark gray or black).

Parent topic: Special Properties


SELECTION-INDEX (numeric)

This property, when set, causes the list box selection to change to the indicated item. Items are numbered sequentially from the top of the list box, starting at 1.

Setting this value to -1 clears any selection. Values beyond the number of list box items are undefined. When queried, this property returns the item number of the current selection, or -1 if no item is selected. Using SELECTION-INDEX to change the list box focus causes a faint dotted-line box to appear around the selected item on graphical systems. On character-based systems, the text cursor is displayed at the end of the selected item. The end user presses the space bar to choose the item.

Parent topic: Special Properties


THUMB-POSITION (numeric)

This property, when set, causes the list box to display the line number of the item on top of the list box, scrolling the latter if necessary. Items are numbered sequentially from the top of the list, starting at 1.

Setting THUMB-POSITION to a value greater than the actual number of lines in the list box or to a value less than 1 has no effect. When queried, this property returns the line number of the item currently displayed on top of the list box.

Parent topic: Special Properties


QUERY-INDEX (numeric)

This property is used only in conjunction with the ITEM-VALUE property. This property determines which list box item to return information about. Items are numbered sequentially from the top of the list box, starting at 1.

Parent topic: Special Properties


ITEM-VALUE (alphanumeric)

This special property, when queried, returns the value of a list box item. The item returned is determined by the current value of QUERY-INDEX. If QUERY-INDEX does not correspond to a valid item, nothing is returned.

For example, to determine the value of the first item in a list box, perform the following statements:

MODIFY LIST-BOX-1, QUERY-INDEX = 1
INQUIRE LIST-BOX-1, ITEM-VALUE IN MY-ITEM
Parent topic: Special Properties


TERMINATION-VALUE (numeric)

This property produces the same behavior as the TERMINATION-VALUE push button property, except that it acts on the CMD-DBLCLICK event instead of the CMD-CLICKED event. This property is used only when the NOTIFY-DBLCLICK style is also used. The compiler applies the NOTIFY-DBLCLICK style automatically if this property is explicitly named when the control is initially created. Note that this does not occur if you use the PROPERTY phrase to supply the property value (by giving its identifying number).

Parent topic: Special Properties


EXCEPTION-VALUE (numeric)

This property produces the same behavior as the push button property of the same name, except that it acts on the CMD-DBLCLICK event instead of the CMD-CLICKED event. This property is used only when the NOTIFY-DBLCLICK style is also used. The compiler applies the NOTIFY-DBLCLICK style automatically if this property is named when the control is initially created. Note that this does not occur if you use the PROPERTY phrase to supply the property value (by giving its identifying number).

Parent topic: Special Properties


SORT-ORDER (numeric)

This property applies to paged list boxes only. It determines whether the case of the data items will be considered as the user searches for a data item. It can take one of four values:

0 | PL-SORT-DEFAULT | Use the default sort order. (Same as value 3.)
1 | PL-SORT-NONE | Every character the user types results in a notification to the COBOL program.
2 | PL-SORT-NATIVE | The paged list is searched and case is considered. If the item that the user has entered is on the current page, it is selected.
3 | PL-SORT-NATIVE-IGNORE-CASE | The paged list is searched and case is not considered. If the item that the user has entered is on the current page, it is selected.
Note: If the style is set to UPPER or LOWER, and SORT-ORDER = 2, characters will be made UPPER or LOWER case as they are entered in the search box, negating the attempt to do a case-sensitive search.
Parent topic: Special Properties


Events

  • CMD-DBLCLICK
  • CMD-GOTO
  • CMD-HELP
  • MSG-VALIDATE
  • NTF-SELCHANGE

For paged list box:

  • NTF-PL-FIRST
  • NTF-PL-LAST
  • NTF-PL-NEXT
  • NTF-PL-PREV
  • NTF-PL-NEXTPAGE
  • NTF-PL-PREVPAGE
  • NTF-PL-NEXT-WHEEL
  • NTF-PL-PREV-WHEEL
  • NTF-PL-SEARCH
Parent topic: List Box


Using Special Keys

When list box has the input focus, the Page-Up and Page-Down keys can be used to scroll the list box. Setting KEYSTROKE configuration entries does not affect these actions.

Parent topic: List Box


Examples

This example creates a list box and fills it with the contents of a table:

DISPLAY LIST-BOX,  LINES 5,  SIZE 30, HANDLE IN
BOX-1.
PERFORM VARYING IDX FROM 1 BY 1 UNTIL IDX > TABLE-SIZE
   MODIFY BOX-1,  ITEM-TO-ADD = TABLE-ITEM( IDX )
END-PERFORM.

The following Screen Section entry and accompanying code perform the same actions:

03 LIST-1,  LIST-BOX,  LINES 5,  SIZE 30,
             VALUE SELECTED-ITEM,  ITEM-TO-ADD = ADD-ITEM.
PERFORM VARYING IDX FROM 1 BY 1 UNTIL IDX > TABLE-
SIZE
   MOVE TABLE-ITEM( IDX ) TO ADD-ITEM
   DISPLAY LIST-1
END-PERFORM.
MOVE SPACES TO ADD-ITEM.

The first time through this loop, the list box is created (if it has not already been created). Subsequent iterations of the loop modify the existing list box. Note the move of spaces to ADD-ITEM at the end. This ensures that future DISPLAYs of LIST-1 (or its parent group item) don't accidentally add another item to the list box.

Parent topic: List Box


.NET

ACUCOBOL-GT defines a control type named .NET that it uses internally whenever you CREATE, MODIFY, INQUIRE, or DESTROY a .NET control.

You use a utility called netdefgen to generate a COBOL COPY file that defines the control's methods and properties. For information about adding a .NET control to your program, see A Guide to Interoperating with ACUCOBOL-GT.

  • Common Properties
  • Special Properties
  • Events
Parent topic: Control Types


Common Properties

LINES/SIZE

The LINES and SIZE values describe the area occupied by the .NET control, using the default font to determine the dimensions of the width and height. If size and lines are omitted, the control's default design size is used.

LINE/COL

The LINE and COL values describe the left corner position of the control on the screen. LINE defines the y-axis and COL defines x-axis.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

AX-EVENT-LIST, EXCLUDE-EVENT-LIST

AX-EVENT-LIST is an exclusive list of .NET events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

Parent topic: .NET


Special Properties

FILE-PATH (alphanumeric)

When a .NET control does not reside in the Global Assembly Cache (GAC) or in the directory in which the run-time resides, you must use the FILE-PATH parameter to disclose the location of the control. The parameter value is a file name or a file path and file name of an XML file containing the .NET assembly information.

In the example below, Assembly, Module, StrongName, Version, and Culture are from the assembly COPY file that was generated by the NETDEFGEN utility. FilePath is the full path name of the control.

<?xml version="1.0" encoding="utf-8" ?>
<FILESPEC>
  <Assembly>AmortControl</Assembly>
  <Module>amortcontrol.dll</Module>
  <StrongName />
  <Version>1.0.1242.11216</Version>
  <Culture>neutral</Culture>
  <FilePath>E:\AmortControl\bin\Debug\AmortControl.dll
  </FilePath>
</FILESPEC>

Note that FilePath could also be a UNC or URI notation, like \HostName\bin\Debug\AmortControl.dll or file://HostName//bin/Debug/AmortControl.dll.

Parent topic: .NET


Events

MSG-NET-EVENT

A MSG-NET-EVENT occurs when a .NET control has fired an event. EVENT-DATA-2 contains the control's event type. When a .NET event type is referenced in your program, the name must be preceded with an "@" character.

An example of event handling code might look like:

USERCONTROL-EVENTS.
    EVALUATE EVENT-TYPE
      WHEN MSG-NET-EVENT
        EVALUATE EVENT-DATA-2
              WHEN @UserControl1_FireCalc PERFORM display-update
        END-EVALUATE
    END-EVALUATE.
Parent topic: .NET


Push Button

A PUSH-BUTTON control is a region of the screen that the user can push (click or select) to cause something to happen. Under most graphical systems, push buttons appear to be raised up from the surface of the screen. Push buttons don't have values. Instead, they generate events whenever they are pushed. To simplify programming, you can assign termination or exception values to push buttons so that they act like function keys or other terminating keys when used. You can find information on how this works in the STYLES and PROPERTIES sections that follow for information on how this works.

  • Common Properties
  • Special Properties
  • Events
  • Examples
Parent topic: Control Types


Common Properties

The set of push button common properties includes:

TITLE

A push button appears centered in the button. The TITLE phrase is used to specify the title. A key letter may be specified in the title. See Common Screen Options in the ACUCOBOL-GT Reference Manual for more information.

VALUE

Push buttons do not use values.

SIZE

The LINES and SIZE values describe the size of the button's title area. The LINES value describes the height of the title area. The SIZE value is the width of the title area, using the width of the 0 (zero) character as the base unit. Added to the title area is overhead for the push button's border. The exact size of the border area is system-dependent. Note that the title area may be larger than the actual title. The title itself is centered both vertically and horizontally in the title area.

When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, are used in place of the values specified by the LINES and SIZE phrases.

The default LINES value is 1. The default SIZE value is 8.

When the BITMAP style is used, the LINES and SIZE values have a different meaning. The values are the number of pixels in the height and width of the bitmap image. If omitted, the default values depend on the host system. Under Windows, the default LINES value is 15 and the default SIZE value is 16. These correspond to the size of buttons typically found on a toolbar. See Bitmap Buttons for more information.

COLOR

Push buttons support colors. Use the COLOR property to specify a color. The focus rectangle is the same color as the text on the push-button. Note that this ability depends on using native controls, by setting WIN32_NATIVECTLS to TRUE. The actual colors used are system-dependent. Under Windows, the user selects the colors in the Control Panel.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ISLINK

Push buttons can appear and behave like an HTML link. Use the ISLINK property to do this. These push buttons are drawn as plain text without any button-style frame. When moving the mouse over this type of push button, the cursor changes to a hand, indicating that the link is clickable. Upon clicking, the runtime sends a message to the COBOL program as if a push button is clicked. Specifying this style automatically implies the NOTAB and SELF-ACT styles.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

TITLE-POSITION

Push buttons with bitmaps support text along with the bitmap. The text displayed is the value of the TITLE property. The TITLE-POSITION property value determines the location of the text. Valid values include:

  • TITLE-POSITION = 1 (left)
  • TITLE-POSITION = 2 (right)
  • TITLE-POSITION = 3 (top)
  • TITLE-POSITION = 4 (bottom)

Any other value results in text not displaying. The COLOR property of the push button determines the text color. Adjust the size of the button to display the text as well as the bitmap. otherwise the text or the bitmap may be cropped, based on the TITLE-POSITION.

If the TITLE-POSITION is LEFT or TOP, then the text displays first, with any remaining space used for the bitmap. If the TITLE-POSITION is RIGHT or BOTTOM, then the bitmap displays first, with any remaining space used for text.

TRANSPARENT-COLOR (numeric)

Use this property to designate transparent regions in a bitmap. This is done by reserving one of the colors in the bitmap as the transparent color. Any points in the bitmap that contain this color will not be displayed when the bitmap is drawn, allowing the background to show through. This can be useful if you want to integrate a logo onto a screen in a way that accommodates the user's choice of desktop colors.

To designate a transparent region, choose one color in the bitmap to be the transparent color. Then, set the TRANSPARENT-COLOR property to the RGB color value of this color. The RGB color value is computed by the following formula:

   (red * 65536) + (green * 256) + blue

where red, green, and blue are values between 0 and 255. You can use a hexadecimal numeric literal to express this value, because each component of the color occupies one byte in a binary value. For example, the following literal expresses an orange color with red at 255, green at 128, and blue at 0:

78  orange    value x#FF8000.

The first byte (x 'FF') is the red value, the second byte (x'80') is the green value, and the last byte (x'00') is the blue value.

If you set TRANSPARENT-COLOR to -1 (the default), the transparency property is turned off and all colors display normally.

Setting TRANSPARENT-COLOR to the hex value x#1000000 automatically specifies the pixel in the upper-left corner of a bitmap as the transparent color. (This is the level 78 constant BM-CORNER-COLOR in acugui.def.) You don't need to know the exact color of that pixel to use this value.

To avoid flashing, the runtime does not update the region under a transparent bitmap once it is in place. One effect of this is that if you animate a bitmap with transparent regions, you must ensure that those regions are the same in each frame of the animation, or the image will blur.

STYLES

DEFAULT-BUTTON This style indicates that this button is the default push button. The user can push (activate) the default button by typing a termination key that has a termination code of 13. Under the default runtime configuration, this is the Return (or Enter) key. When this occurs, the run-time generates a button pushed event instead of the normal termination event. This ensures that the program treats the Return key and the default push button in the same manner (since they both generate the same event). For related information, see the TERMINATION-VALUE special property.

Push buttons with the DEFAULT-BUTTON style are typically displayed differently by the host system. Under Microsoft Windows, default push buttons have a thicker border. Only one button should have the DEFAULT-BUTTON style at any one time. If more than one button has the DEFAULT-BUTTON style, the meaning is ambiguous. Note that the DEFAULT-BUTTON style is implied by the OK-BUTTON style

ESCAPE-BUTTON | Similar to the DEFAULT-BUTTON style, this style indicates that the push button corresponds to the Escape key. The user can push this button by typing a key that has an exception value of 27 (that is, the Escape key in the default configuration). When this occurs, the run-time generates a button pushed event instead of the normal exception event. This ensures that your program handles the Escape key and the escape button in the same manner. Note that only one enabled button should have the ESCAPE-BUTTON style at any one time. See the EXCEPTION-VALUE property below for related information.
NO-AUTO-DEFAULT | Normally, when a push button is activated, it becomes the default push button. The run-time accomplishes this by giving the DEFAULT-BUTTON style to the activated push button and removing it from any other push button in the same floating window. This allows the user to press the Return key to push the active button. If you specify NO-AUTO-DEFAULT, this behavior is not applied when this button is made active. The default push button, if any, remains unchanged.
SELF-ACT Normally, when the user clicks a CMD-GOTO event is sent to your to your program. After being activated, the button can then return that it has been pushed. Buttons with the SELF-ACT style are self-activated instead. This means that they do not send the CMD-GOTO event to your program when clicked. Instead they activate themselves and then send the appropriate button pushed termination status to the program. If you also assign an exception value to the button, it will act just like the equivalent function key. For example, the following statement fragment builds a push button that behaves just like function key 1 (usually marked F1).
DISPLAY PUSH-BUTTON, SELF-ACT, EXCEPTION-VALUE=1

Self-activating buttons behave differently in some additional, subtle, ways. Normally, if the user down-clicks on a push button and then moves the mouse away before releasing the button, the push button remains active (shown in Windows by a thicker border around the button). But the button is not clicked. Self-activating buttons do not remain active. Instead, they re-activate the previous control. This is done because self-activating controls don't tell the program about the down-click event. To ensure that the program and screen states are consistent, the previous control is re-activated. Also, self-activating buttons do not automatically become the default push button when clicked on with the mouse.

Generally speaking, there is rarely a need to use this style for push buttons defined in a group within the Screen Section. The Screen Section handler performs all the button activation needed when the group is accepted. The SELF-ACT style is mostly useful when you define individual push buttons using the DISPLAY verb (or as elementary Screen Section items) and you do not want to program the activation of those buttons. A common use would be to add push buttons to an existing application where the push buttons will perform the same operation as some function key. In this case, you can simply create the push button with the SELF-ACT style and an exception value that is the same as the function key. Usually, no other coding is needed, because the button will perform all of its own activation and simulate the function key when it is clicked

Note: The SELF-ACT style performs automatic activation only when the user clicks on the button with the mouse or uses its key letter. You must still program your own activation if you want the user to be able to visit the button in some other fashion (for example, by using the Tab key to move to the button).

Also note that this style makes the button self-activating, but not any associated Screen Section entry. This means that any BEFORE or AFTER procedures named in an associated Screen Section entry will not automatically execute when the button is clicked. They will function only when you ACCEPT the Screen Section entry in your program.

OK-BUTTON This style is used only when the button is created. It has the effect of changing several of the button's default values. It is equivalent to specifying the following:
TITLE  "OK"
DEFAULT-BUTTON
TERMINATION-VALUE = 13
You may override the TITLE and TERMINATION-VALUE settings by providing your own. The net effect of the OK-BUTTON style is that it provides a convenient way of creating a typical OK button.
CANCEL-BUTTON This style is similar to the
OK-BUTTON
style, but it produces a Cancel button instead. It is equivalent to specifying the following defaults when the button is created:
TITLE  "Cancel"
ESCAPE-BUTTON
EXCEPTION-VALUE = 27
You may override the TITLE and EXCEPTION-VALUE defaults by providing your own.
BITMAP | This style causes the push button to be drawn using a bitmap instead of its default appearance. See Bitmap Buttons for a complete description.
FRAMED | This style is used only with bitmap buttons. It requests that a thin frame be drawn around the button. Typically this appears as a thin black line. Not all systems support frames, in which case the request is ignored. By default, buttons are framed under Windows NT/Windows 2000.
UNFRAMED | This style is used only with bitmap buttons. It requests that the button be drawn without a frame. Not all systems support unframed buttons, in which case the request is ignored. By default, buttons are not framed under Windows 98.
SQUARE | This style is used only with framed bitmap buttons. It forces the button to have square corners. Without this style, the button will have slightly rounded corners.
FLAT | On graphical systems, and only when a bitmap is used, this style creates a button without visible borders. On character-based system, this style has no effect.
MULTILINE | On graphical systems, this style causes the push button to have a multiline title. When the MULTILINE style is applied, the push button's title text is automatically word wrapped to fit the push button's size. You can force a line break in the text by embedding an ASCII line feed character (h"0A"). The MULTILINE style is ignored in character-based environments.
Parent topic: Push Button
Related concepts
Cascading Style Sheet Syntax


Special Properties

BITMAP-NUMBER (numeric)

This property identifies a particular bitmap image to use as the push button. If you explicitly name this property when creating a control, the BITMAP style is automatically applied by the compiler. Note that this does not occur if you use the PROPERTY phrase to specify this property by giving its identifying number. See Bitmap Buttons for more information.

BITMAP-HANDLE (handle)

This property identifies the bitmap image strip to use with the push button.

TERMINATION-VALUE (numeric)

This property modifies the way that a push button communicates to your program when it has been pushed. Normally, a push button will generate a CMD-CLICKED event. If you provide a non-zero TERMINATION-VALUE, the push button will generate a termination condition with the specified value instead. This makes the push button act like a keyboard termination key. Most existing COBOL programs are already coded to handle termination keys, so this is easier for the COBOL program to work with.
Note: If you assign the DEFAULT-BUTTON style and a TERMINATION-VALUE property of 13, then the effects of typing the Return key may seem rather odd. The DEFAULT-BUTTON style converts the Return key's termination event into a button pushed event. The TERMINATION-VALUE property then changes the button pushed event into a termination event with a value of 13. The net effect is the same as if neither the style nor property had been used. The reason for this lengthy route is to ensure that the button and Return key are handled identically, and to provide options for programming push button handling, such as the setting of TERMINATION-VALUE.

EXCEPTION-VALUE (numeric)

This property works in a fashion that is identical to the TERMINATION-VALUE property, except that it converts button pushed events into exception events (instead of termination events). If a button has both a TERMINATION-VALUE and an EXCEPTION-VALUE specified, the EXCEPTION-VALUE takes precedence.

Parent topic: Push Button


Events

  • CMD-CLICKED
  • CMD-GOTO
  • CMD-HELP
  • MSG-VALIDATE
Parent topic: Push Button


Examples

The first example creates a simple push button with an ID of 100. The key letter of the push button is H.

DISPLAY PUSH-BUTTON,
        "&Help",  ID 100,  HANDLE IN BUTTON-1

This next example creates a very tall push button:

DISPLAY PUSH-BUTTON,
        TITLE "Tall",  LINES 3,  HANDLE IN BUTTON-2

The following Screen Section entry creates an OK button:

03 PUSH-BUTTON  OK-BUTTON,  LINE 10,  COLUMN 20.

This last example creates a default push button that generates a termination value of 200:

03 PUSH-BUTTON  "&Find",  DEFAULT-BUTTON,
        TERMINATION-VALUE = 200.
Parent topic: Push Button


Radio Button

A RADIO-BUTTON control is similar to a check box, except that the user can usually select only one radio button out of a group of buttons. Selecting one causes any other selected button to become unselected. These groups of buttons typically present a small set of choices that affect a single program function.

  • Common Properties
  • Special Properties
  • Events
  • Examples
Parent topic: Control Types


Common Properties

The set of radio button common properties includes:

TITLE

Radio buttons may have titles; the title typically appears to the right of the button. The TITLE phrase is used to specify the title. A key letter may be specified in the title. See Common Screen Options in the ACUCOBOL-GT Reference Manual for more information.

VALUE

Radio buttons have numeric values. A value of 0 indicates an unselected radio button. A value of 1 indicates a selected radio button.
Note: Radio buttons cannot have array elements in a VALUE or USING phrase. The compiler detects and disallows such usage, and an error message is displayed at compile time.

SIZE

The LINES and SIZE values describe the size of the radio button's title area. The LINES value describes the height of the title area, in lines. The SIZE value specifies the width of the title area, using the width of the 0 (zero) character as the base unit. Added to the title area is the overhead needed for the actual button. This usually adds several character positions to the width and may affect the height if the button is taller than the title's font.

When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.

The default value of LINES is 1. The default value of SIZE is computed by measuring the length of the title using the button's font and dividing by the width of the "0" character. Thus, the default width of a radio button exactly occupies the space its text takes up on the screen.

When used with the BITMAP style, the LINES and SIZE values have a different meaning. The values are the number of pixels in the height and width of the bitmap image. If omitted, the default values depend on the host system. Under Microsoft Windows, the default LINES value is 15 and the default SIZE value is 16. These values correspond to the size of buttons typically found on a toolbar. See Bitmap Buttons for details.

COLOR

Radio buttons use both the foreground and background colors specified. If either is omitted, the corresponding color of the button's owning subwindow is used.

Bitmap radio buttons don't use the specified colors. Instead, the colors are derived from the bitmap and the system defaults for push buttons.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

STYLES

BITMAP | This style causes the radio button to be drawn with a bitmap instead of its usual appearance. See Bitmap Buttons for a complete description.
FRAMED | This style is used only with bitmap buttons. It requests that a thin frame be drawn around the button. Typically this appears as a thin black line. Not all systems support frames, in which case the request is ignored. By default, buttons are framed under Windows NT/Windows 2000.
UNFRAMED | This style is used only with bitmap buttons. It requests that the button be drawn without a frame. Not all systems support unframed buttons, in which case the request is ignored. By default, buttons are not framedunder Windows 98.
SQUARE | This style is used only with framed bitmap buttons. It forces the button to have square corners. Without this style, the button will have slightly rounded corners.
SELF-ACT | This style creates a self-activating radio button. The behavior of the SELF-ACT radio button is the same as that of the SELF-ACT push button. Self-activating radio buttons return control to the previously active control or window when they are clicked. Usually, you will want to use the NOTIFY style in conjunction with SELF-ACT so that your program is informed whenever the radio button is clicked. See Push Button for more information.
NOTIFY | This style tells the runtime to generate a CMD-CLICKED event whenever the value of the radio button is changed by the user. This allows your program to respond immediately to the change. In essence, the radio button will now act like a combination radio button and push button. Without the NOTIFY style, the radio button remains active after it has been changed (exception: see SELF-ACT, above).
NO-GROUP-TAB | Normally, radio buttons that belong to a button group treat the Tab and Backtab keys in a special fashion. Any time a radio button has a non-zero GROUP special property, it acts as if it also has the NO-TAB style unless it is the group leader. The group leader is the radio button that is currently "on," or the first radio button in the group if they are all "off." The effect is that when you tab to a radio button group, control passes to the button that is on, or to the first button in the group if none is on. Note that the NO-GROUP-TAB style suppresses this special handling.
LEFT-TEXT | Radio buttons with this style display their text to the left of the box instead of to the right. Note that if you use this style and try to vertically align several radio buttons, the buttons may not align vertically. This is because the default behavior of the run-time is to place the right edge of the button at the minimum distance needed from its left edge to accommodate the control's text. This results in the buttons being placed in different columns, depending on the text of each control. Supplying a uniform width using the SIZE property overrides this behavior.
FLAT | On Windows systems, and only when a bitmap is used, this style creates a radio button without visible borders. On non-Windows systems, this style has no effect.
MULTILINE | This style causes the radio button to have a multi-line title. When the MULTILINE style is applied, the radio button’s title text is automatically word wrapped to fit the radio button’s size. You can force a line break in the text by embedding an ASCII line feed character(h“0A”). The MULTILINE style is ignored in character-based environments.
VTOP | This style causes the title text to be vertically aligned with the top of the control's area. By default, the title text is vertically aligned to the center of the control's area.
Parent topic: Radio Button
Related concepts
Cascading Style Sheet Syntax


Special Properties

BITMAP-NUMBER (numeric)

This property identifies a particular bitmap image to use with the radio button. If you explicitly name this property when creating a control, the BITMAP style is automatically applied by the compiler. Note that this does not occur if you use the PROPERTY phrase to specify this property (by giving its identifying number). See Paged List Boxes for more information.

BITMAP-HANDLE (handler)

This property identifies the bitmap image strip to use with the radio button. See Paged List Boxes for more information.

TERMINATION-VALUE (numeric)

This property works in a manner identical to the TERMINATION-VALUE push button property. This property is used only when the NOTIFY style is also used. The compiler applies the NOTIFY style automatically if you explicitly name this property when creating a control. Note that the NOTIFY style is not automatically applied if you use the PROPERTY phrase to specify this property (by giving its identifying number).

EXCEPTION-VALUE (numeric)

This property works in a manner identical to the push button property of the same name. This property is used only when the NOTIFY style is also used. The compiler applies the NOTIFY style automatically if you explicitly name this property when creating a control. Note that the NOTIFY style is not automatically applied if you use the PROPERTY phrase to specify this property (by giving its identifying number).

GROUP (numeric)

Radio buttons usually operate in groups of related buttons. Normally, only one button of the group may be selected. When a button is selected, all other buttons of the same group are unselected. The GROUP property describes which buttons belong together. In any one floating window, all radio buttons with the same non-zero GROUP property value are treated as a single group. The runtime will ensure that only one button in a group is selected at any one time.

The default GROUP value is 1. If all radio buttons on the same floating window retain the default value, they will be treated as a single group.

Radio buttons with a GROUP value of 0 do not perform any checks to ensure that only one button is selected. These buttons behave much like check boxes; each one may be independently selected.

GROUP-VALUE (numeric)

This property simplifies the process of managing a group of radio buttons. Normally, the program must determine which button in a group is selected by examining the value of each button. The button with a value of 1 is the selected button. The GROUP-VALUE property is used to turn the value checking process into a single operation. You assign each radio button in a group a distinct GROUP-VALUE number. This links each button with its corresponding GROUP-VALUE. In this way, you can determine which button is selected by assigning all of the buttons in the group the same VALUE data item. The data item will hold the GROUP-VALUE number of the selected radio button.

Technically, this works as follows. For any radio button with a non-zero GROUP-VALUE property, a selected button will update its VALUE data item only during an ACCEPT. A selected button will return its GROUP-VALUE property as its VALUE. During a DISPLAY, a radio button will be selected only if its VALUE matches its GROUP-VALUE. Any other VALUE will be treated as a VALUE of zero.

Use this by assigning distinct GROUP-VALUE numbers to each button in a group, and by assigning all the buttons to the same VALUE data item. Then you can select a button by moving the button's GROUP-VALUE number to the VALUE data item and updating all the buttons. On input, you can determine which button is currently selected by simply examining the VALUE data item. It will contain the GROUP-VALUE number of the selected button.

The default value for GROUP-VALUE is zero, which disables the GROUP-VALUE mechanism.

Parent topic: Radio Button


Events

  • CMD-CLICKED
  • CMD-GOTO
  • CMD-HELP
  • MSG-VALIDATE
Parent topic: Radio Button


Examples

The following creates a simple radio button:

DISPLAY RADIO-BUTTON, "&Left Align",
HANDLE IN RADIO-BUTTON-1.

Frequently, you will want to create several radio buttons, each offering the user a different option. Here is a Screen Section entry that specifies three buttons:

01 ALIGNMENT-CHOICES.
    03  RADIO-BUTTON, "&Left", USING ALIGN-CHOICE
        GROUP-VALUE 1.
    03  RADIO-BUTTON, "&Right", USING ALIGN-CHOICE
        LINE + 1.5
        GROUP-VALUE 2.
    03  RADIO-BUTTON, "&Center", USING ALIGN-CHOICE
        LINE + 1.5
        GROUP-VALUE 3.

In the preceding example, ALIGN-CHOICE is set to 1, 2, or 3 depending on which radio button is selected.

Here are the same buttons as they might appear in a toolbar. These buttons are bitmap buttons. Also, instead of storing their value, they simply notify the COBOL program when they have been pressed (via the EXCEPTION-VALUE). Like most toolbar buttons, they are self activating. This frees the COBOL program from having to explicitly ACCEPT the toolbar buttons.

01 TOOLBAR-CHOICES.
    03  RADIO-BUTTON, "Left",
        NOTIFY, SELF-ACT
        BITMAP-NUMBER 1, EXCEPTION-VALUE 1.
    03  RADIO-BUTTON, "Right", OVERLAP-LEFT,
        NOTIFY, SELF-ACT,
        BITMAP-NUMBER 2, EXCEPTION-VALUE 2.
    03  RADIO-BUTTON, "Center", OVERLAP-LEFT,
        NOTIFY, SELF-ACT
        BITMAP-NUMBER 3, EXCEPTION-VALUE 3.

Several other examples of programming radio buttons can be found in the sample programs included with the release materials. These examples demonstrate a range of application, including use of the GROUP special property and bitmap buttons. Look in tour.cbl for a simple example. See radiobtn.cbl for a set of basic examples. See winspool.cbl for a more complex use of radio buttons.

Parent topic: Radio Button


Scroll Bar

With the use of the SCROLL-BAR control, a user can scroll through a continuous range of items. This control has five elements — next and previous line buttons, next and previous page regions, and a slider (also called a thumb), which indicates the current position in the range.

Scroll bars are available both for character-based and Microsoft Windows systems. For character-based systems, you may choose to display the various parts of the scroll bar with the GO-GUI-MAP and GF-GUI-MAP termcap functions. You may also do this with the GUI_CHARS configuration variable.

When a user clicks on a scroll bar, a message is sent to the scroll bar's event procedure, which updates the screen according to the new scroll position. Scroll bars don't generate terminating events, so any ACCEPT statement remains active while the user adjusts the scroll bar. The scroll bar does not automatically update its own value when the user modifies it. You should respond to each message by setting the scroll bar's value to the new position. Otherwise, the scroll bar will return to its previous setting after the user finishes. For a detailed description of these events, see Events Reference.

The ACUCOBOL-GT runtime supports the use of a mouse wheel with the scroll bar control in all versions of Windows that support the wheelmouse. Those versions are: Windows ME, Windows NT 4.0, and Windows 2000 and higher. Support applies only to vertical scroll bars. The Windows operating system supports mouse wheel rotation through the WM_MOUSEWHEEL message. The runtime intercepts the WM_MOUSEWHEEL events and translates them into WM_VSCROLL messages, which are then handled as conventional mouse button clicks on a scroll bar. By default, a single WM_MOUSEWHEEL event is translated into three WM_VSCROLL messages. The application user can configure this number to suit his or her preference through the Mouse Properties sheet in the Control Panel.

  • Common Properties
  • Special Properties
  • Events
Parent topic: Control Types


Common Properties

TITLE

Scroll bars do not have titles.

VALUE

A scroll bar has an integer value, which represents the slider's position in the control. The range of values is set by the properties MIN-VAL, MAX-VAL, and PAGE-SIZE. Setting the value outside of the legal range has an undefined effect.

SIZE

SIZE and LINES describe the area of the scroll bar in window cells. If SIZE is omitted, the width of a vertical scroll bar is the standard width of the host system's scroll bar. A horizontal scroll bar extends to the right edge of the window when the scroll bar is created. If LINES is omitted, the system makes corresponding calculations — a horizontal scroll bar is standard height, and a vertical scroll bar extends to the bottom edge.

COLOR

Scroll bars always use the system's colors.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

STYLES

HORIZONTAL | This style creates a horizontal scroll bar. Without this style, the scroll bar is vertical.
TRACK-THUMB | This style causes the scroll bar to generate MSG-SB-THUMBTRACK messages while the slider is moved by the user. Without this style, the messages are suppressed. Use this style if you want to update the screen while the user is moving the slider (as opposed to immediately after a new slider position is selected). To minimize network traffic and optimize performance, MSG-SB-THUMBTRACK events are generated differently for thin client applications. With thin client applications, when the slider is moved by the user, a single MSG-SB-THUMBTRACK message is sent immediately before the MSG-SB-THUMB message, and the scroll bar is automatically updated.
Parent topic: Scroll Bar
Related concepts
Cascading Style Sheet Syntax


Special Properties

MIN-VAL (numeric)

This special property sets the lowest value of the range of legal scroll bar values. The default value is "0" (zero).

MAX-VAL (numeric)

This property sets the highest value of the range of legal scroll bar values. The default value is 100. MAX-VAL may not be greater than 65536. Setting a larger range has an undefined effect. See PAGE-SIZE below for additional information.

PAGE-SIZE (numeric)

This property describes the number of elements that appear on a "page" of data. For example, if you scroll through a series of lines and 20 lines fit in the window, then the page size is 20. With a 32-bit runtime, this property determines the size of the slider relative to the scroll bar. If PAGE-SIZE is set to 0 (the default), then the system uses a default slider size. PAGE-SIZE also reduces the range of values that the scroll bar can take. The effective range is MIN-VAL to MAX-VAL minus PAGE-SIZE.

Parent topic: Scroll Bar


Events

  • CMD-HELP
  • MSG-VALIDATE
  • MSG-SB-NEXT
  • MSG-SB-PREV
  • MSG-SB-NEXTPAGE
  • MSG-SB-PREVPAGE
  • MSG-SB-THUMB
  • MSG-SB-THUMBTRACK
Parent topic: Scroll Bar


Status Bar

The above illustration shows a STATUS-BAR control application in a sample window. The text strings "Enter last name", "Page 1 of 2", "Edit", and "View" are all part of the status bar in this window. The status bar runs along the bottom edge of the host window. It is not outlined by a border of its own and appears blended in with the rest of the window area. The height of the status bar is indicated by those of its panels that have borders. This particular status bar consists of four panels and a grip. The first two panels are flat; they have no borders to separate them and thus look like a single flat panel. The Edit panel is raised, while the View panel is lowered (indicating the active mode in this example). The grip is the triangular area in the lower-right corner of the window.

The status bar control is available only on 32-bit Windows platforms. This is a read-only type of control, meaning it does not generate events, and it cannot be ACCEPTed. The behavior when modifying (then displaying) an existing STATUS-BAR control can be controlled by the SINGLE_STATUS_BAR configuration variable, and its default setting of TRUE should be considered best practice.

A status bar contains a number of panels designed to display text. You may assign up to 128 panels to a status bar. Each panel can be programmed to display the status of a certain event in the control's host window.

Status bars don't scroll when the body of the window is scrolled. Instead, the status bar remains accessible at the bottom of the window. Status bars automatically grow and shrink horizontally to match the width of the owning window.

On character-based systems, status bars are not created, that is, any related statements are ignored.

  • Common Properties
  • Special Properties
  • Events
Parent topic: Control Types
Related reference
SINGLE-STATUS-BAR


Common Properties

TITLE

The status bar does not have TITLE for a property, but you may use the phrase TITLE in the same way as you would use PANEL-TEXT and thus accomplish a de facto title of the status bar. Consider the following usage:
DISPLAY STATUS-BAR   "This is the title panel".

or

DISPLAY STATUS-BAR
        TITLE  "This is the title panel".

Both of the above are equivalent to the complete statement:

DISPLAY STATUS-BAR
        PANEL-WIDTHS  -1
        PANEL-STYLE   0
        PANEL-TEXT    "This is the title panel".

Your title will then be in PANEL-INDEX 1.

VALUE

Status bars have no value.

SIZE

Status bars have no size; their width always spans the width of the host window, and their height depends on the window font, always accommodating only one line of text.

COLOR

Status bars don't use colors; the colors of the status bar's host window are used.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

STYLES

GRIP If specified, allows you to include in the lower-right corner of the window a triangular area in which you can click-and-drag to resize the entire window. So the grip affects the entire window, although it is a status bar style.

GRIP applies to only resizable windows. When it is specified, any resizing of a window using the grip triggers the same event as would resizing the window in a conventional way. If you specify grip in a non-resizable window, it is ignored.

Parent topic: Status Bar
Related concepts
Cascading Style Sheet Syntax


Special Properties

PANEL-WIDTHS (numeric)

You may specify this special property's value with an integer data item or literal. PANEL-WIDTHS allows you to specify:

  • How many panels the status bar should hold: You may use an array to specify all the panels on one line, and the number of items in the array determines how many panels are created on the status bar
  • The width of each panel on the status bar: Each number on the array specifies the width of its corresponding panel in characters

So if you specify your status bar using the following array:

DISPLAY STATUS-BAR
        PANEL-WIDTHS   (50,  20,  20)
        [ ... ].

you are setting up a status bar with three panels, the first at 50 characters wide and the other two at 20 characters each.

If you set PANEL-WIDTHS = 0, you create a status bar with one panel extending across its entire width and no text.

If you set PANEL-WIDTHS to a single positive non-zero number greater than the width of the entire status bar (as defined by the width of the host window), the panel gets sized down to fit in the host window and the text is truncated.

If you have a status bar composed of several panels, and you specify particular widths for each of them, for example:

DISPLAY STATUS-BAR
        PANEL-WIDTHS   (25, 25, 25, 25)

and this status bar is displayed in a window that is dynamic, when that window shrinks below the size specified by PANEL-WIDTHS, all the panels are reset to an average size small enough so that all panels fit in the window, say "20, 20, 20, 20".

If you don't want the all of the panels truncated, set the width of the last panel to -1, for example:

DISPLAY STATUS-BAR
        PANEL-WIDTHS   (25, 25, 25, -1)

This will cause the last panel to be sized to whatever space is left available on the window after the first panels have been accommodated. Based on our example, if the window was sized to 80 columns, the panels would be "25, 25, 25, 5".

The widths of panels with no PANEL-WIDTHS specified will be automatically calculated based on the total available width of the status bar divided by the number of panels, as specified through the use of PANEL-STYLE, PANEL-TEXT, or PANEL-INDEX.

When you modify PANEL-WIDTHS, the panel is not visually updated until the text is applied. This means that a MODIFY using PANEL-WIDTHS and no PANEL-TEXT will never be displayed. Conversely, any MODIFY statement without PANEL-WIDTHS reflects the changes immediately.

To erase the contents of a status bar, use:

MODIFY statusbar-handle PANEL-WIDTHS 0.

This removes all the panels and sets up the status bar with one panel extending across its entire width. After this operation, you have one panel with the style of previous panel 1 and no text.

PANEL-STYLE (numeric)

Allows you to specify the preferred style of the actual panel. You may specify the value with an integer data item or literal. Valid values are:

  • Flat (0) - the panel has the same height as the rest of the window, with no visual borders. This style is generally used to present information as a guide, displaying different text to inform the user about the status of the program or the cursor's location on the screen, or prompt for action or data entry into a field. It may also be used to indicate a condition that is temporarily disabled.
  • Lowered (1) - the panel appears sunken in the host window. This style is generally used to indicate that an option is active, for instance, the "numlock" is on or the "insert" mode is active.
  • Raised (2) - the panel appears raised in the host window. This style is generally used to indicate that an option is deactivated ("capslock" off, etc.).

You must apply the PANEL-STYLE before you apply the PANEL-TEXT, in order to have the text displayed properly.

The default is 0 (zero).

PANEL-TEXT (alphanumeric)

Can be specified with a data item or a literal. It allows you to specify the text content of a panel. The text may not exceed 255 characters, else the right-most text is automatically truncated. If the text exceeds the size of the panel, the visibility is the same as in any native Windows control, that is, the left-most text is visible.

PANEL-INDEX (numeric)

An integer data item or literal. It allows you to specify which panel you want to work with. General number range is from 1 to 128. If you specify an index number that is larger than the current number of panels but lower than 128, the status bar attempts to provide the additional panels up to the index number specified. The new panels all have the same width, as determined by the width of the status bar minus the width of the existing panels and divided by the number of additional panels to be generated. The additional panels inherit their style from the first existing panel. If the first panel does not exist, the default style 0 (zero) applies.

SELF-ACT (no parameters)

To have a panel in the status bar act like a push button without additional coding, apply this style to the control. You will also have to constrain your panel styles to either lowered (1) or raised (2). A click on a panel will then toggle the panel between the two styles.

Example:

77 MySecondPanelIsSetToStyle PIC 9.
        ...
        DISPLAY ScreenDemo.
        ACCEPT  ScreenDemo.
        INQUIRE	AUTO-PANEL
                PANEL-INDEX(2)
                IN MySecondPanelIsSetToStyle.

Note that SELF-ACT is related to the CMD-CLICKED event. SELF-ACT turns off the CMD-CLICKED event.

Note: The raised and lowered panels do not work with XP Visual styles (WIN32_NATIVECTLS runtime configuration variable).
  • Array and index modes
  • Sequence order
Parent topic: Status Bar


Array and index modes

There are two modes of specifying the special properties of a status bar:

  1. Array mode, where you specify each property once, in an array, for allthe panels:
    PANEL-WIDTHS ( width-1, width-2, width-3, ... )
PANEL-STYLE ( style-1, style-2, style-3, ... )
PANEL-TEXT ( text-1, text-2, text-3, ... )

    or

  2. Index mode, where you define each panel separately, property by property, assigning an index number to each panel. However, the total number of panels must be defined before any panel style or text is defined. Therefore, you must specify all of the PANEL-WIDTHS first, as in:
    PANEL-WIDTHS width-1
PANEL-WIDTHS width-2
PANEL-INDEX id-1
PANEL-STYLE style-1
PANEL-TEXT text-1
PANEL-INDEX id-2
PANEL-STYLE style-2
PANEL-TEXT text-2

It is generally recommended that you not mix array mode and index mode; however, you can specify PANEL-WIDTHS in array mode, followed by index mode for the remaining properties. For example:

DISPLAY STATUS-BAR
     PANEL-WIDTHS ( 10, 10, 10 )
     PANEL-INDEX 1
        PANEL-STYLE 0
        PANEL-TEXT "Text one"
     PANEL-INDEX 2
        PANEL-STYLE 1
        PANEL-TEXT "Text two"
     PANEL-INDEX 3
        PANEL-STYLE 2
        PANEL-TEXT "Text three".
Parent topic: Special Properties


Sequence order

The Special Properties of the status bar control are reflective of the demands of the underlying Windows API. Two rules apply in the case when you specify a multi-panel status bar:

  • The text is the last item processed before the display is performed. If you do not set the number of panels before you specify the text, the status bar is forced into single panel configuration.
  • The style of a panel is set in accordance with whatever is active at the moment. Thus, if you set the style after the text, it has no effect.

You should, therefore, observe this specific sequence of properties when DISPLAYing or MODIFYing a status bar:

  1. PANEL-WIDTHS, followed by the array;
  2. PANEL-STYLE, followed by the array;
  3. PANEL-TEXT, followed by the array;
  4. GRIP.

So the syntax will look like this:

DISPLAY STATUS-BAR
  PANEL-WIDTHS ( 5, 10, 20 )
  PANEL-STYLE ( 0, 2, 2 )
  PANEL-TEXT ( "Panel 1", "Panel 2", "Panel 3" )
  GRIP.
Parent topic: Special Properties


Events

CMD-CLICKED

If a status bar does not have the SELF-ACT style applied, it will generate the CMD-CLICKED when a mouse is clicked on it. To capture the event, the status bar instance must have an EVENT PROCEDURE assigned.

The event will return two items:

  • EVENT-DATA-1: The current style of the panel clicked
  • EVENT-DATA-2: The index of the panel clicked

Example:

01 ScreenDemo.
           03 MANUAL-PANEL   STATUS-BAR
              PANEL-WIDTHS (10, 10, 10, -1)
              PANEL-STYLE  (1, 2, 1, 2)
              PANEL-TEXT   ("Pan 1", "Pan 2", "Pan 3", "Pan 4")
              EVENT PROCEDURE PanelEvent.
        ...
        PanelEvent.
           IF EVENT-DATA-1 > 1
              MOVE 0 TO EVENT-DATA-1
           ELSE
              ADD  1 TO EVENT-DATA-1
              END-IF
           MODIFY MANUAL-PANEL
                  PANEL-INDEX EVENT-DATA-2
                  PANEL-STYLE EVENT-DATA-1
           EXIT PARAGRAPH
           .

SELF-ACT turns off the new CMD-CLICKED event. Clicking the status bar will not change the focus of the screen. Clicking the status bar will not terminate an accept unless specifically coded to do so.

The raised and lowered panels do not work with XP Visual styles (WIN32_NATIVECTLS runtime configuration variable). Events will occur, but you will have to detect the events and change text to visualize the clicks. The SELF-ACT style will not cause any visual change; it will, however, change the panel style.

Parent topic: Status Bar


Tab

The TAB-CONTROL combines a box with a tab for a control that looks like a file folder. The user may click on any tab to bring it forward. Some tabs have key letters, and in those cases the user may also activate a particular tab by typing the key letter (the underscored letter in the tab's text) in conjunction with the Alt key. You may define a tab's key letter by placing an & in front of the intended key letter in the tab's text. This appears as an underscored letter when the tab is displayed. For example,

DISPLAY TAB-CONTROL, TAB-TO-ADD = ("Tab&1", "Tab&2")

creates a control with two tabs. The first tab has a key letter of "1" and the second tab has a key letter of 2.

The program typically places different screen elements in the box depending on the tab selected.

The tab control can be used by any application that displays its screens on a 32-bit Windows system, including applications deployed with thin client technology. Any attempt to create a tab control on other systems fails and the returned handle is NULL.

When a user clicks on a tab, the program is informed of the new selection and the tab's appearance is updated. (The behavioral distinction between tabs and push buttons is that a tab responds immediately when clicked, and a push button responds with the clicked event only when the mouse button is released.)

You may allow the user to activate the tabs with the keyboard by accepting the tab control as you would any other control (but you need not do so if you want to provide only a mouse interface). During the keyboard operation of the tab controls in Windows applications, the following logic is used by the runtime to process the arrow keys:

  • Left Arrow keys are processed by Windows if the first item in the tab control is not active. If the first item in the tab is active, the runtime processes the left arrow in the usual way (depending on the value of KEYSTROKE entries).
  • Right Arrow keys are processed by Windows if the last item in the tab control is not active. If the last item in the tab control is active, the runtime processes the right arrow in the usual way.

If the tab is a multiline tab, up and down arrows are processed by Windows instead of the runtime. Processed by Windows in this context means that Windows decides which tab is selected next as the active tab, and the runtime has no control over that decision.

It's important to define the elements of the tab control in a particular order in the Screen Section to ensure that the runtime displays the control properly. The preferred method is to use separate Screen Section groups to define the contents of each tab page. See Programming Tips - Tab for more information.

  • Common Properties
  • Special Properties
  • Events
  • Programming Tips
Parent topic: Control Types


Common Properties

TITLE

Tabs do not have titles.

VALUE

A tab control has a numeric value, which represents the currently selected tab. Selecting a value outside of the range of existing tabs has an undefined effect.

SIZE

SIZE and LINES describe the area occupied by the tab control, using the tab's font to determine the dimensions of the row and column. The area described includes the row(s) occupied by the tabs as well as the box.

COLOR

Tab controls are always displayed using the push button colors selected by the user in the Windows Control Panel.

Note: If you are using the WIN32_NATIVECTLS runtime variable to automatically enable XP or Vista control styles and have frames with labels, see the COLOR property in Common Properties (for Label controls) for information on how the labels may display.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

TAB-COLOR, TAB-BACKGROUND-COLOR, ACTIVE-TAB-COLOR

Use the TAB-COLOR and TAB-BACKGROUND-COLOR properties (when adding a new tab to the control). Use the ACTIVE-TAB-COLOR property when creating the main tab control. All of these properties take a color value.

TAB-BORDER-COLOR, TAB-BORDER-WIDTH

Tab controls have a border that encompasses the selected tab and its corresponding page. The border can be set to a specific color using the TAB-BORDER-COLOR property (which accepts a color name). The default color is black. Control the border width with the TAB-BORDER-WIDTH property, which takes a value from 1 to 3, with 3 being the thickest border width.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

ROUND

You can switch between square and rounded corners for the tab control appearance. Use the ROUND property to specify round corners. The default style is square. This can only be done at creation, and cannot be modified.

STYLES

MULTILINE | If the tabs don't all fit on one line, this style allows them to occupy as many lines as needed. If this style is not used, the system adds a scroll bar so the user can scroll to the hidden tabs.
BUTTONS | This style produces a tab control with a different appearance. These tabs look like push buttons (the box is not shown), but they act much like a group of radio buttons.
FIXED-WIDTH | This style causes each tab to occupy the same amount of space. Without this style, each tab is individually sized. Note that setting this style can cause an odd appearance on multiline tabs.
VERTICAL W$FONT library routine When this style is used, tabs are displayed vertically along the left edge of the control. This style automatically implies the MULITLINE style.

Note that with this style, you cannot use the & character in a tab's text to assign a keyboard shortcut. Also note that if you use the WIN32_NATIVECTLS runtime variable for invoking XP control styles, the contents may not render correctly or at all. This is because Windows XP native controls itself does not support this style.

Because some fonts are not displayed properly after being rotated, we recommend using a TrueType font with vertical tabs. You can use the W$FONT library routine to retrieve a TrueType font.

BOTTOM | This style causes tabs to appear on the bottom edge of the control instead of the top. If the VERTICAL style is also specified, tabs appear on the right edge of the control instead of the left.
FLAT-BUTTONS This style is similar to the BUTTONS style, but the button-style tabs appear flat, with no border, rather than having a 3-D appearance
Note: This style is valid only when the tabs are positioned at the top of the control. If the BOTTOM style is used, and FLAT-BUTTONS is also selected, the control will default to the BUTTONS style.
NO-DIVIDERS | This style is used only with the FLAT-BUTTONS style. When specified, no dividers are drawn between the button-style tabs.
HOT-TRACK | When this style is used, a tab's text is highlighted when the mouse hovers over it. Note that the degree of highlighting is determined by Windows and is often fairly subtle.
NO-FOCUS | Users cannot give focus to the tab control when this style is used.
Parent topic: Tab
Related concepts
Cascading Style Sheet Syntax


Special Properties

TAB-TO-ADD (alphanumeric)

Assigning a value to this special property adds a new tab to the control. The value is the text of the tab. You may add several tabs at once by using parentheses, as shown in the following example:

MODIFY TAB-1,
    TAB-TO-ADD = ( "TAB 1", "TAB 2", "TAB 3" )

This example adds three tabs in the order listed. Inquiring from this property has no effect.

TAB-TO-DELETE (numeric)

Assigning a non-zero value to this property removes the correspondingly numbered tab. Inquiring from this property has no effect.

RESET-TABS (numeric)

Assigning a non-zero value to this property removes all existing tabs from the control. Inquiring from this property has no effect.

BITMAP-HANDLE (numeric)

This property allows images from a bitmap file to be placed on individual tabs. The images are displayed before the text of each tab. Before a bitmap image can be placed on a tab, you must load the bitmap file into memory by calling the library routine W$BITMAP with the WBITMAP-LOAD option. The routine returns a handle that is referred to by this property of the tab control.

The bitmap file loaded into memory is treated as a bitmap strip - a series of images of equal width that are laid out side-by-side in a single bitmap. The images are numbered sequentially starting at 1. By default, each tab in the control displays the image whose number is the same as the tab's ordinal number when the tab was defined. If you take the following code as an example,

MODIFY TAB-1,
    TAB-TO-ADD = ( "TAB 1", "TAB 2", "TAB 3" )

then by default, TAB1 will show image 1, TAB2 will show image 2, and TAB3 will show image 3. You may change the default handling of the assignment of these images with the BITMAP-NUMBER property. See BITMAP-NUMBER and BITMAP-WIDTH for additional information.

BITMAP-WIDTH (numeric)

This property sets the width of the images in the bitmap strip described by BITMAP-HANDLE. If this property is not set, the images default to 16-pixels wide. Set this property to match the actual width of the images that make up the bitmap strip to get the look that you desire for the tabs.

BITMAP-NUMBER (numeric)

This property identifies which bitmap image will be displayed for each tab. To use this property, set the value of BITMAP-NUMBER to the number of the image in the bitmap strip.

This property is additive. The first time you set the BITMAP-NUMBER, the image identified with the bitmap number will be displayed on the first tab; the second time you set this property, the image identified will be displayed on the second tab, and so on. The additive behavior of this property may be overridden in one of three ways:

  1. You may assign a value of 1 to this property.
  2. You may empty the tab control through RESET-TABS.
  3. You may specify a new list by keying in the bitmap numbers in parentheses, as shown in the example below.

The following Screen Section entry creates a tab control with three tabs, and places image numbers 3, 5 and 7 on those tabs:

03 TAB-CONTROL
   TAB-TO-ADD = ("Tab 1", "Tab 2", "Tab 3")
   BITMAP-NUMBER = (3, 5, 7)

If you omit the BITMAP-NUMBER, the bitmap images are assigned in ordinal number by default. In other words, the following definition:

03 TAB-CONTROL
   TAB-TO-ADD = ("Tab 1", "Tab 2", "Tab 3")

has the same meaning as:

03 TAB-CONTROL
   TAB-TO-ADD = ("Tab 1", "Tab 2", "Tab 3")
   BITMAP-NUMBER = (1, 2, 3)

When no value is set for this property, the default behavior is to automatically put bitmap number 1 on the first tab, bitmap number 2 on the second tab, and so on.

Parent topic: Tab


Events

  • CMD-HELP
  • CMD-TABCHANGED
  • MSG-VALIDATE
Parent topic: Tab


Programming Tips

The preferred method of programming the tab control involves defining separate level 01 items in the Screen Section for every individual tab page and using a series of DISPLAY statements, in a specific order, to display the control. The following syntax sample demonstrates this technique.

01 TAB-FORM.
   03 MY-TAB,            TAB-CONTROL
      placeStateCOL                10 PIXELS
      LINE               10 PIXELS
      LINES              200 PIXELS
      SIZE               200 PIXELS
      TAB-TO-ADD         IS ("Page 1", "Page 2", "Page 3")
      EVENT              PROCEDURE TAB-EVENT
      VALUE              WS-ACTIVE-PAGE.
01 TAB-PAGE-1.
   03 LABEL
      placeStateCOL                30 PIXELS
      LINE               50 PIXELS
      TITLE              "This is page 1"
      LEFT.
01 TAB-PAGE-2.
   03 LABEL
      placeStateCOL                30 PIXELS
      LINE               50 PIXELS
      TITLE              "This is page 2"
      LEFT.
01  TAB-PAGE-3.
   03 LABEL
      placeStateCOL                30 PIXELS
      LINE               50 PIXELS
      TITLE              "This is page 3"
      LEFT.

The Procedure Division syntax uses successive DISPLAY statements to create the control. In the following example, the first DISPLAY statement creates a standard graphical window as a canvas for the tab control (Fig. 1). The second DISPLAY statement adds TAB-FORM, defined as a separate level 01 item in the Screen Section (Fig. 2). Note that TAB-FORM can be defined in the same group item with other controls for the same window. The third DISPLAY statement adds the content of the first tab, TAB-PAGE-1, defined as another separate level 01 item in the Screen Section (Fig. 3).

DISPLAY STANDARD         GRAPHICAL WINDOW
        SCREEN           LINE 1
        SCREEN           COLUMN 1
        LINES            17
        SIZE             37
        CONTROL          FONT IS WS-DISPLAY-FONT
        AUTO-MINIMIZE
        BACKGROUND-LOW
        MODELESS
        NO               SCROLL
        WITH             SYSTEM MENU
        TITLE            "Tab control demo"
        TITLE-BAR
        NO               WRAP
        HANDLE           IS WS-WIN-HANDLE.
DISPLAY TAB-FORM.
DISPLAY TAB-PAGE-1.

Figure 1

Figure 2

Figure 3

Parent topic: Tab


Tree View

The TREE-VIEW control presents hierarchical data in a list. This list is indented to show the relationships among the data items. Users can expand or collapse items in the list to view or hide subsidiary items.

Items

In a tree view control, each item in the hierarchical list is identified by an ID that is assigned at the time the element is added to the control. This provides a unique way to identify each item and thus allows for duplicate items at different points in the hierarchy without any confusion. Tree view IDs are declared in COBOL as USAGE POINTER data items.

Tree view controls have a variety of special properties, including the ability to store hidden data with any item and to display bitmaps adjacent to the items. The special property called ITEM is used to identify which item in the hierarchy is to be affected by the property values you provide. Typically, you set the value of the ITEM property to the ID of the item to be acted on, and then you set another property (such as ITEM-TEXT or ENSURE-VISIBLE or HAS-CHILDREN or BITMAP-NUMBER) to assign a value or setting to that item. Note that you must set the value of ITEM before you set the other property value to get the desired results. ITEM is the index for the tree view control (see the MODIFY and INQUIRE statements for a description of indexes).

Parent and Child Relationships

Items in a tree view control are placed within the hierarchical list according to parent and child relationships that you specify. The special property PARENT allows you to specify whether an item is at the top level of the hierarchy (PARENT = 0, the default) or is the child of another item in the hierarchy (PARENT value set to the ID of the parent item).

Another special property of the tree view control, HAS-CHILDREN, enables you to specify whether new child items can be added underneath a specific item in the list. When HAS-CHILDREN = 0 (the default), an item has children only if they are already physically present in the control. This means that no additional child items can be added to that item by the user.

If HAS-CHILDREN is set to a non-zero value (such as HAS-CHILDREN = 1), this indicates that the item identified by the ITEM property is entitled to have child items added. This setting is useful when it is impractical to place all of a tree's items in the control at once (see examples immediately following). In this situation, you populate the highest level of the tree and then use this property to identify which of the top-level items are entitled to have children. Then, when the user expands a particular item, you have the program respond to the MSG-TV-EXPANDING event by adding the appropriate child items to the control. The HAS-CHILDREN property tells the control which items can be expanded.

Adding Child Items

In many cases, it is impractical to fully load a tree view with all of the items it logically contains. For example, if you want to represent every file on a local disk drive in its directory hierarchy, a tree view is a natural way to do this. However, it could take a long time to populate this tree: every file on the entire drive would have to be located. One way to solve this problem is to populate only the top level of the tree at first, and then populate only those sub-levels that the user visits.

To do this, you have to tell the tree view whether an item is entitled to have children when you add the item to the control. If you did not do this, the control would not allow the user to expand that item. You establish the ability to add children to an item by setting the property HAS-CHILDREN to 1 when you add the parent item. For example:

MODIFY TV-1, ITEM-TO-ADD = "Parent Item"
   GIVING PARENT-1, HAS-CHILDREN = 1

This informs the control that the item has children, even though the children are not physically present in the control.

There are two approaches you can take when managing the children of a particular item. You can add them the first time the parent item expands, and then leave them in the control, or you can add them as the parent expands and delete them when the parent collapses.

Adding Child Items Once

The first approach is to add child items the first time the parent is expanded and then leave them in the control. To code this, respond to the MSG-TV-EXPANDING message by seeing if there are any children of the parent item. If not, add them at this point. A typical event procedure for this would look like this:

TREE-VIEW-EVENT-1.
    EVALUATE EVENT-TYPE
      WHEN MSG-TV-EXPANDING
          IF EVENT-DATA-1 = TVFLAG-EXPAND    |Item expanding
              MODIFY TV-1( EVENT-DATA-2 ),
                NEXT-ITEM = TVNI-CHILD GIVING ITEM-1
              IF ITEM-1 = NULL               |No children
                PERFORM ADD-CHILDREN
            END-IF
         END-IF
    END-EVALUATE

The paragraph ADD-CHILDREN would do the work needed to add the child items. In this example, EVENT-DATA-1 contains a flag that describes whether the parent item is being expanded or collapsed, and EVENT-DATA-2 contains the ID of the parent item.

Adding Child Items on Each Expansion

The second approach is to add child items each time the parent expands and then remove them when the parent collapses. The code for adding the items is slightly easier because you do not have to guard against adding multiple times. However, you have additional code to handle the removal of the child items. A typical event procedure for this approach looks like this:

TREE-VIEW-EVENT-1.

    EVALUATE EVENT-TYPE
      WHEN MSG-TV-EXPANDING
          IF EVENT-DATA-1 = TVFLAG-EXPAND
             PERFORM ADD-CHILDREN
          END-IF

      WHEN MSG-TV-EXPANDED
          IF EVENT-DATA-1 = TVFLAG-COLLAPSE
             MODIFY TV-1, ITEM-TO-EMPTY = EVENT-DATA-2
          END-IF
Note: It is important that you add the children in response to the MSG-TV-EXPANDING event and remove them in response to the MSG-TV-EXPANDED event. Any other approach can confuse the control and produce odd results.

Navigating a Tree View with the Keyboard

Typically, users use a mouse to interact with a tree view control. However, users can also use the keyboard to accomplish many actions.

The down arrow key selects the next visible item in the tree (that is, moves the selection down one row).

The up arrow key selects the previous visible item in the tree (that is, moves the selection up one row).

If the current item is collapsed (that is, has a plus sign to its left):

  • The right arrow key expands the item
  • The left arrow key selects the parent item

If the current item is expanded (that is, has a minus sign to its left):

  • The right arrow key selects the first child item
  • The left arrow key collapses the item

If the current item has no children:

  • The right arrow key has no effect
  • The left arrow key selects the parent item

The page up (PgUp) and page down (PgDn) keys select items one page minus one item away from the current item.

Editing Label names with the mouse

You can enable user sto change the text of a tree-view item. This feature is controlled by the runtime configuration variable TV_EDITLABELS. When this variable is set to "1" (on, true, yes) you can change the value of the tree-view item by clicking it with the mouse (just like with Windows Explorer). When the variable is set to "0" (off, false, no) text changes are not allowed. The default value of TV_EDITLABELS is "0".

To keep track of the changes, two messages are generated from the tree-view to the COBOL program: MSG_TV_BEGINEDITLABEL and MSG_TV_ENDEDITLABEL.

MSG_TV_BEGINEDITLABEL is sent to the COBOL program when the user begins the edit. EVENT-DATA-1 is always 0, and EVENT-DATA-2 contains the handle of the item being modified. The program can prevent the modification by setting EVENT-ACTION to EVEN-ACTION-FAIL.

MSG_TV_ENDEDITLABEL is sent when the user has successfully finished editing. EVENT-DATA-1 is always 0 and EVENT-DATA-2 contains the handle of the modified item.

  • Common Properties
  • Special Properties
  • Events
Parent topic: Control Types


Common Properties

TITLE

Tree view controls do not have titles.

VALUE

The ID of the currently selected item. When you set the VALUE, the corresponding item is selected (or the selection is removed if there is no corresponding item). When you retrieve the VALUE, the result is the ID of the current selection, or NULL if nothing is selected.

SIZE

SIZE and LINES describe the area occupied by the tree view control, using the control's font to determine the dimensions of a row and column. Additional space is added for the scroll bar (which is hidden when it is not needed). The default height of a tree view is 5 lines; the default width is 12 columns. For character-based systems, the size and appearance of the tree view control depends on the configuration variables TREE-TAB-SIZE and TREE-ROOT-SPACE.

COLOR

Tree views use any specified foreground or background color. If either color is omitted, that color uses a system-dependent default value. Under Microsoft Windows, the default values are determined by the user's choices in the Control Panel (usually black on bright white). These system-dependent default colors are not transformed or mapped by the runtime system's color-handling configuration options.

ITEM-COLOR

Tree views can now have a different color for each item. Use the ITEM-COLOR property (which accepts a numeric value representing a color) to specify this when adding items to the tree view. For example:
MODIFY tree-ctl
ITEM-TO-ADD "Tree Item" ITEM-COLOR 397
GIVING item-ptr

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

SELECTION-COLOR

Tree view controls can specify the selection color. Use the SELECTION-COLOR property (which accepts a numeric value representing a color) to specify this. You can specify the selection color either at creation or with the MODIFY verb.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

STYLES

3-D | Adds 3-D decoration around the border of the control. Effective only on boxed tree views.
BOXED | Indicates that a box should be placed around a tree view. This is the default
BUTTONS | Places small buttons to the left of each item, which the user can click to expand or collapse the item in addition to double-clicking the item. The buttons show a + if the item can be expanded, or a - if it can be collapsed. Items with no subsidiary items do not get a button. Also, buttons are placed on the top level items only if you also specify the SHOW-LINES and LINES-AT-ROOT styles. Note: Some versions of Windows are known to have a bug that prevents the buttons from displaying correctly if you do not also specify the SHOW-LINES style.
LINES-AT-ROOT | Allows the SHOW-LINES and BUTTONS styles to apply to top-level items. Note that the runtime configuration variable TREE_ROOT_SPACE can control the number of screen columns between the left edge of the tree-view control and the root level text.
NO-BOX | This style removes the box that normally displays around the control
SHOW-LINES | This style causes faint lines to be drawn between the items to help clarify their nesting relationship. Lines are not drawn between top-level items unless you also specify the LINES-AT-ROOT style.
SHOW-SEL-ALWAYS | The control always shows the current selection, even when it does not have the focus. The default is to hide the selection when the control does not have the focus.
Parent topic: Tree View
Related concepts
Cascading Style Sheet Syntax


Special Properties

  • BITMAP-HANDLE (numeric)
  • BITMAP-NUMBER (numeric)
  • BITMAP-WIDTH (numeric)
  • ENSURE-VISIBLE (numeric)
  • EXPAND (numeric)
  • HIDDEN-DATA (alphanumeric)
  • HAS-CHILDREN (numeric)
  • ITEM (numeric)
  • ITEM-TEXT (alphanumeric)
  • ITEM-TO-ADD (alphanumeric)
  • ITEM-TO-DELETE (numeric)
  • ITEM-TO-EMPTY (numeric)
  • NEXT-ITEM (numeric)
  • PARENT (numeric)
  • PLACEMENT (numeric)
  • RESET-LIST (numeric)
Parent topic: Tree View


BITMAP-HANDLE (numeric)

Identifies the handle of a loaded bitmap, so that images from that bitmap can be shown in items in the tree view. You obtain the bitmap handle by calling the library routine W$BITMAP with the WBITMAP-LOAD option. The bitmap is treated as a bitmap strip — a series of fixed-width images laid out side-by-side in a single bitmap. The images are numbered sequentially, starting at 1. Note that you have only one bitmap strip for the entire control, although you can select individual images out of this strip for each item. See BITMAP-NUMBER.

Parent topic: Special Properties


BITMAP-NUMBER (numeric)

Identifies the bitmap image that will be displayed for the item identified by ITEM. If you don't specify a bitmap number for a particular item, that item will use bitmap number 1. Note that you can show different bitmaps for expanded or collapsed items by changing an item's BITMAP-NUMBER in response to the MSG-TV-EXPANDING event.

Parent topic: Special Properties


BITMAP-WIDTH (numeric)

Sets the width of the images in the bitmap strip described by BITMAP-HANDLE. If not set, the images default to 16 pixels wide. You should set this to match the actual width of the images that make up the bitmap strip.

Parent topic: Special Properties


ENSURE-VISIBLE (numeric)

When set to a valid item ID, this special property ensures that that item is visible in the control. This may expand collapsed items and may cause scrolling.

Parent topic: Special Properties


EXPAND (numeric)

Programmatically expands or collapses the item identified by the ITEM property. If you set EXPAND to TVFLAG-EXPAND, the item is expanded. To collapse the item, set EXPAND to TVFLAG-COLLAPSE. These constants are defined in the file acugui.def. Set to zero when you want no action to occur.

Parent topic: Special Properties


HIDDEN-DATA (alphanumeric)

This special property allows the program to store data that is not displayed in an item. Hidden data is limited to 255 bytes per item. Hidden data may be any format, including non-printing characters. This property acts on the item identified by the ITEM property.

Note: As with all properties that take a text value, when the value of HIDDEN-DATA is stored, the runtime automatically strips trailing spaces and low-values.
Parent topic: Special Properties


HAS-CHILDREN (numeric)

When set to a non-zero value, this special property indicates that the item identified by ITEM has child items even if there are no child items in the control. When set to zero (the default), an item has children only if they are physically present in the control. This property is useful when it is impractical to place all of a tree's items in the control all at once. In this approach, you don't place child items in the tree, but you mark which items have children via this property. Then, when the user expands a particular item, you have the program respond to the MSG-TV-EXPANDING event by adding the appropriate child items to the control. The HAS-CHILDREN property informs the control which items can be expanded.

Parent topic: Special Properties


ITEM (numeric)

This special property is used in conjunction with other properties to identify which item to affect. Typically, you set ITEM to the ID of the item to act on and then set another property to perform the action. Note that you must set ITEM before the other property to get the desired results. ITEM is the index for the tree view control (see the MODIFY and INQUIRE statements for a description of indexes).

Note: The Windows API does not guard against invalid settings of this property. As a result, setting this property to a value that does not correspond to a valid item ID can result in a general protection fault under Windows.
Parent topic: Special Properties


ITEM-TEXT (alphanumeric)

When set, changes the text of the item identified by ITEM to match the value assigned. When queried, it returns the text of the item identified by ITEM.

Parent topic: Special Properties


ITEM-TO-ADD (alphanumeric)

Places a new item in the tree view control. The text assigned to ITEM-TO-ADD is placed as a new item in the control. Its position in the hierarchy is determined by the PARENT and PLACEMENT special properties. The return value from this property is the ID of the new item. If the new item is successfully added, the ITEM property is set to point to this item (this makes attaching a bitmap or hidden data to the item easier — see BITMAP-NUMBER and HIDDEN-DATA).

Parent topic: Special Properties


ITEM-TO-DELETE (numeric)

When set, deletes the item whose ID matches the assigned value. If you place this in the Screen Section, set this value to NULL to ensure that you don't accidentally delete items.

Parent topic: Special Properties


ITEM-TO-EMPTY (numeric)

Deletes all child items of the item whose ID is assigned to this property. When set to NULL, this property has no effect.

Parent topic: Special Properties


NEXT-ITEM (numeric)

Setting this property returns a specific item ID. The new item found depends on the value used:

Value | Item Found
TVNI-CHILD | First child of the current ITEM
TVNI-FIRST-VISIBLE | First item currently visible in control
TVNI-NEXT | Next sibling of the current ITEM
TVNI-NEXT-VISIBLE | Next visible item after ITEM
TVNI-PARENT | Parent item of the current ITEM
TVNI-PREVIOUS | Previous sibling of ITEM
TVNI-PREVIOUS-VISIBLE | Previous visible item before ITEM
TVNI-ROOT | Topmost item in the entire control

These values are defined in acugui.def.

Note: ITEM must refer to a visible item when you are using TVNI-NEXT-VISIBLE or TVNI-PREVIOUS-VISIBLE. The return value from setting this property is the item ID if successful, or zero if the specified item does not exist. Set NEXT-ITEM to zero when no action is wanted.
Parent topic: Special Properties


PARENT (numeric)

Helps to determine the placement of a new item in the control. When this is set to an ID of an item already in the control, the newly added item will be a child of the PARENT item. If PARENT is set to zero, newly added items are placed at the top level. PARENT is set to zero when the control is created.

In the following example, four items are added to a tree view control. The first item is a parent to the next two items, and the last item is on the top level like the first:

77  ID-1             USAGE POINTER.

MODIFY TREE-VIEW-1, ITEM-TO-ADD = "Item 1",
       GIVING ID-1,
       PARENT = ID-1,
       ITEM-TO-ADD = "Item 1-A",
       ITEM-TO-ADD = "Item 1-B",
       PARENT = 0,
       ITEM-TO-ADD = "Item 2".

The resulting tree looks like this:

Parent topic: Special Properties


PLACEMENT (numeric)

Works in conjunction with PARENT to determine where new items are located in the hierarchy. The PLACEMENT value affects the location within a given sublevel (that is, the list of items that have the same parent). If PLACEMENT is set to a valid item ID (whose parent is PARENT), the new item is placed immediately after this item. Alternatively, you can use any one of the following special values (defined in acugui.def):

TVPLACE-FIRST | Item placed first in the list
TVPLACE-LAST | Item placed last in the list
TVPLACE-SORT | Item sorted alphabetically in the list

The default setting is TVPLACE-LAST.

In the following example, items are sorted alphabetically except at the top level:

77  ID-1        USAGE POINTER.
77  ID-2        USAGE POINTER.

MODIFY TREE-VIEW-1, ITEM-TO-ADD = "Ordinals", GIVING ID-1
    PARENT = ID-1, PLACEMENT = TVPLACE-SORT,
    ITEM-TO-ADD = ( "First", "Second", "Third", "Fourth" )
    PARENT = 0, PLACEMENT = TVPLACE-LAST,
    ITEM-TO-ADD = "Cardinals", GIVING ID-2,
    PARENT = ID-2, PLACEMENT = TVPLACE-SORT,
    ITEM-TO-ADD = ( "One", "Two", "Three", "Four" ).

The resulting tree looks like this:

Note: The Ordinals and Cardinals appear in the order added (TVPLACE-LAST), although the items under each are sorted alphabetically (TVPLACE-SORT).
Parent topic: Special Properties


RESET-LIST (numeric)

When set to a non-zero value, this special property removes all items from the control. It has no effect when set to zero.

Parent topic: Special Properties


Events

The tree view control generates the following events:

  • CMD-GOTO
  • CMD-HELP
  • MSG-TV-DBLCLICK
  • MSG-TV-EXPANDED
  • MSG-TV-EXPANDING
  • MSG-TV-SELCHANGE
  • MSG-TV-SELCHANGING
  • MSG-VALIDATE
Parent topic: Tree View


Web Browser

The WEB-BROWSER control is used in conjunction with Microsoft Internet Explorer 4.0 and later. It provides the view you see in the main window of Microsoft Internet Explorer, and it provides the functionality for displaying Web pages containing HTML, scripting, and ActiveX control and Java applet content. This control also hosts Component Object Model (COM) document objects, supports COM hyperlinks, and allows users to view Windows objects such as folders and files. Because it is an ActiveX control, it can be used in a COM control container application.

For more information about the usage of the Web browser control, refer to Appendix B of A Programmer's Guide to the Internet. That document is included on your ACUCOBOL-GT distribution media and installed in the same directory as the ACUCOBOL-GT manual set.

The ACUCOBOL-GT runtime uses ActiveX (COM control) containment to offer the facilities of Microsoft's Web browser control to COBOL programs. The Web browser control is used just like any other ACUCOBOL-GT control. To create a Web browser control identified by the name BROWSER-1 and using the Working-Storage item URL-1 as its value, for example, you would add the following lines to a screen section item:

03  BROWSER-1 WEB-BROWSER VALUE URL-1
    COLUMN 5, LINE 5, SIZE 60, LINES 20.

or add the following procedure division code:

DISPLAY WEB-BROWSER VALUE URL-1
   COLUMN 5, LINE 5, SIZE 60, LINES 20
   HANDLE IN BROWSER-1.
  • Common Properties
  • Special Properites
  • Other Properties
  • Events
Parent topic: Control Types


Common Properties

TITLE

The Web browser control does not use titles.

VALUE

The Web browser control takes an alphanumeric value, which is the URL.

SIZE

The Web browser control defines its height by multiplying the LINES value by cell size.

Width is defined by multiplying the SIZE value by the standard or wide font measure. If this control is also boxed, the space required for the box is added to the width. The Web browser control has a minimum width of at least one character.

COLOR

The Web browser control ignores specified colors. The actual colors used are system-dependent. Under Windows, the user selects the colors in the Control Panel.

ATW-CSS-CLASS

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

ATW-CSS-ID

This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme ((that is, a #class-name entry in the cascading style sheet)) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.

If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.

See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.

EVENT-LIST, EXCLUDE-EVENT-LIST

EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.

Methods

Methods are implemented as properties in ACUCOBOL-GT. To invoke a method, you modify the control, setting the values of various properties that represent the method parameters. Then, usually in the same modify statement, you set a particular property that represents the method to invoke. Sometimes just setting the value of a control invokes a method.

Here is a table of the methods with their corresponding ACUCOBOL-GT Web browser control properties and descriptions:

Method | Control property | Description
GoBack | GO-BACK | Navigates to the previous item in the history list
GoForward | GO-FORWARD | Navigates to the next item in the history list
GoHome | GO-HOME | Navigates to the current configured home or start page
GoSearch | GO-SEARCH | Navigates to Microsoft's web portal site
Navigate | VALUE | Navigates to a resource identified by a URL or file path
Refresh | REFRESH | Reloads the current page
StopBrowser | STOP-BROWSER | Stops any pending navigation or download

To invoke the GoBack, GoForward, GoHome, GoSearch, Refresh, and StopBrowser methods, modify the control, setting the appropriate properties to 1. To invoke the Navigate method, modify the control setting the VALUE property to the desired URL. For example, to invoke the GoBack method:

MODIFY BROWSER-1 GO-BACK=1.

To invoke the Navigate method:

MODIFY BROWSER-1 VALUE="http://www.microfocus.com".

Alternatively, if you have defined the WEB-BROWSER control with value URL-1 in a screen section item called BROWSER-SCREEN:

MOVE "http://www.microfocus.com" to URL-1.
DISPLAY BROWSER-SCREEN.

These methods are invoked asynchronously. This means that the MODIFY verb may finish executing before the operation is complete. You may check the value of the BUSY property (see below) to determine whether the operation has completed.

Parent topic: Web Browser
Related concepts
Cascading Style Sheet Syntax


Special Properites

  • CUSTOM-PRINT-TEMPLATE (alphanumeric)
  • PRINT (numeric)
  • PRINT-NO-PROMPT (numeric)
  • PAGE-SETUP (numeric)
  • PRINT-PREVIEW (numeric)
  • COPY-SELECTION (numeric)
  • CLEAR-SELECTION (numeric)
  • SAVE-AS (numeric)
  • SAVE-AS-NO-PROMPT (alphanumeric)
  • FILE-NAME (alphanumeric)
  • PROPERTIES (numeric)
  • SELECT-ALL (numeric)
Parent topic: Web Browser


CUSTOM-PRINT-TEMPLATE (alphanumeric)

Internet Explorer versions 5.5 and later give you precise control over the layout and contents of pages printed, print jobs, and the print preview user interface. This is accomplished using an HTML script file that you create called a Custom Print Template. Use the CUSTOM-PRINT-TEMPLATE property of ACUCOBOL-GT's Web browser control to specify the name of your template file.

You may specify an absolute or relative path to the template file. Relative path names are relative to the current working directory. Under thin client, the path refers to a file on the server. The client downloads the file to its local cache directory and gives it a temporary name. If the file already exists in the cache directory, the client downloads a new copy only if the file on the server is a different size or has a later modification date than the file on the client.

You must set CUSTOM-PRINT-TEMPLATE before each print or print preview operation. Its value is cleared after the print or print preview operation completes.

See the Microsoft Developer Network for complete documentation of the format and use of custom print templates.

Parent topic: Special Properites


PRINT (numeric)

The PRINT and PRINT-NO-PROMPT properties let users print the contents of the page displayed via the Web browser control. Set PRINT=1 to display the Print dialog box, allowing users to choose a printer, page range, number of copies, zoom level, and other options before starting a print job.

Parent topic: Special Properites


PRINT-NO-PROMPT (numeric)

Set PRINT-NO-PROMPT=1 to start a print job without displaying the Print dialog box. Default settings are used unless CUSTOM-PRINT-TEMPLATE is specified. The thin client displays a security dialog box to warn users about the risks of running scripts from untrusted servers.

Parent topic: Special Properites


PAGE-SETUP (numeric)

Set PAGE-SETUP=1 to display the Page Setup dialog box, allowing users to change settings for margins, paper size, paper source, and layout prior to printing.

Parent topic: Special Properites


PRINT-PREVIEW (numeric)

Set PRINT-PREVIEW=1 to display the Print Preview window. You can customize the appearance and user interface in this window using the CUSTOM-PRINT-TEMPLATE property.

Parent topic: Special Properites


COPY-SELECTION (numeric)

Set COPY-SELECTION=1 to copy the current selection to the clipboard.

Parent topic: Special Properites


CLEAR-SELECTION (numeric)

Set CLEAR-SELECTION=1 to clear the current selection from the clipboard.

Parent topic: Special Properites


SAVE-AS (numeric)

Set SAVE-AS=1 to display the Save As dialog box and allow the user to save a copy of the page displayed in the Web browser control to disk.

Parent topic: Special Properites


SAVE-AS-NO-PROMPT (alphanumeric)

The SAVE-AS-NO-PROMPT property uses the filename specified with the FILE-NAME property when a page is saved from the browser control. This was originally designed to bypass the Save As dialog box and save the Web page to disk without prompting the user. However, Microsoft has identified this as a security risk and later versions of Internet Explorer will always display the Save As dialog box.

Parent topic: Special Properites


FILE-NAME (alphanumeric)

Set FILE-NAME to the path of a file to be used with the Save As operation. The value of the FILE-NAME property is cleared after the Save As operation is complete.

Parent topic: Special Properites


PROPERTIES (numeric)

Set PROPERTIES=1 to display the Properties dialog box.

Parent topic: Special Properites


SELECT-ALL (numeric)

Set SELECT-ALL=1 to cause the entire contents of the HTML page, current frame, or entry field to be selected. What gets selected depends on which element of the Web page has the keyboard focus. If you click in an HTML form entry field, SELECT-ALL=1 selects the value of that entry field only. If you click in an area of a frame outside of a form, SELECT-ALL=1 selects the entire frame. This behavior was designed by Microsoft and cannot be changed.

Parent topic: Special Properites


Other Properties

Here is a table of the other properties with their corresponding ACUCOBOL-GT Web browser control properties and descriptions:

Property | Control property | Description
Busy | BUSY | Indicates whether a download or navigation is still in progress.
LocationName | TITLE | Name of the resource that the WEB-BROWSER control is currently displaying.
LocationURL | VALUE | URL of the resource that the WEB-BROWSER control is currently displaying.
Type | TYPE | Type of the current contained document object.

BUSY, LOCATION-NAME, and TYPE are read-only properties. Setting their values has no effect. As with all ACUCOBOL-GT control properties, you may use the INQUIRE verb to obtain a Web browser control's properties. For example, to check whether a Web browser control has completed executing the last invoked method:

INQUIRE BROWSER-1 BUSY IN BROWSER-1-BUSY.
IF BROWSER-1-BUSY = 1
...
END-IF

To get the URL that the browser is currently displaying:

INQUIRE BROWSER-1 VALUE IN URL-1.

Alternatively, if you have defined the control with value URL-1 in a screen section item, the LocationURL is automatically moved to URL-1 when an event or exception occurs or the ACCEPT terminates.

Parent topic: Web Browser


Events

The WEB-BROWSER control generates the following events:

  • MSG-WB-BEFORE-NAVIGATE
  • MSG-WB-DOWNLOAD-BEGIN
  • MSG-WB-DOWNLOAD-COMPLETE
  • MSG-WB-NAVIGATE-COMPLETE
  • MSG-WB-PROGRESS-CHANGE
  • MSG-WB-STATUS-TEXT-CHANGE
  • MSG-WB-TITLE-CHANGE
Parent topic: Web Browser


Events Reference

  • Overview of Events
  • Window Events
  • Control Events
  • Menu Events
Parent topic: ACUCOBOL-GT User Interface Programming


Overview of Events

This section describes the events that can be generated when you are using graphical windows and controls in an event-driven environment.

Events are categorized into command events, notify events, and messages. Generally speaking, command events correspond to actions taken by the user that the program needs to act on (for example, closing a window or pushing a button). Notify events generally correspond to informational events that the program may not have to act on. Messages pass information to a screen control's event procedure. This division is somewhat arbitrary, but corresponds to the most common situations.

When a command or notify event occurs, the run-time system assigns a value to the EVENT STATUS data item and then terminates the current ACCEPT with an exception value of 96. Note that the termination occurs even if the particular ACCEPT statement does not normally allow exceptions. The program should examine the EVENT STATUS data item to determine what happened.

Messages are different from other events, because they do not terminate the current ACCEPT. Messages are sent only to a control's event procedure. See PROCEDURE Clause for a detailed discussion of event procedures.

The EVENT STATUS phrase is described in Special-Names Paragraph. The EVENT STATUS data item should be defined as follows:

01  EVENT-STATUS.
  03  EVENT-TYPE              PIC X(4) COMP-X.
  03  EVENT-WINDOW-HANDLE     USAGE HANDLE OF WINDOW.
  03  EVENT-CONTROL-HANDLE    USAGE HANDLE.
  03  EVENT-CONTROL-ID        PIC XX COMP-X.
  03  EVENT-DATA-1            USAGE SIGNED-SHORT.
  03  EVENT-DATA-2            USAGE SIGNED-LONG.
  03  EVENT-ACTION            PIC X COMP-X.

A copy of this data item appears in the COPY file crtvars.def.

In the Screen Section, notification events are treated slightly differently from command events. Normally, when an event triggers an EXCEPTION procedure, the ACCEPT-CONTROL field of the SCREEN CONTROL status item is initialized to 0. This causes the ACCEPT statement to terminate after the EXCEPTION procedure completes. You can cause the ACCEPT statement to continue processing fields by moving alternate values to the ACCEPT-CONTROL data item. When a notification event triggers an EXCEPTION procedure, the ACCEPT-CONTROL field is initialized to 1 instead. This causes the ACCEPT statement to continue processing the current field when the EXCEPTION procedure terminates. This is done as a convenience. Most notification events can be handled entirely within the EXCEPTION procedure and should not terminate ACCEPT processing. If you need to terminate the controlling ACCEPT, simply move a 0 to ACCEPT-CONTROL inside the EXCEPTION procedure.

Event values can be found in the file acugui.def. The names given in the next section are the level 78 data items found in that file.

Parent topic: Events Reference


Window Events

The EVENT-CONTROL-HANDLE and EVENT-CONTROL-ID values will always be zero (NULL) when a window event occurs. The values returned are stored as signed integers and may return negative values.

Note: Command events begin with the prefix CMD. Notification events begin with NTF, and messages begin with MSG.

CMD-CLOSE (value 1)

This event indicates that the user has selected the Close option from the active window's system menu. The application should respond by hiding or destroying the window. The EVENT-WINDOW-HANDLE data item will contain the handle of the window that the user wants to close. The EVENT-DATA-1 and EVENT-DATA-2 values are not used. Note that floating windows always return the exception CMD-CLOSE. Also note that the run-time configuration variable QUIT-MODE affects only the main application window. All other windows in the application return the event CMD-CLOSE when the Close button is clicked.

CMD-ACTIVATE (value 6)

This event occurs when a window is activated by the user, but only if the previously active window belongs to the same program (that is, the user switches windows within the program, and does not transfer control from another program). The normal response is to ACCEPT something in the newly active window, making it the active window from the program's point of view. If you use either the LINK or BIND TO THREAD options when creating the window, the run-time system can automatically handle this event. The EVENT-DATA-1 and EVENT-DATA-2 values are not used. Threads are discussed in detail in Multiple Execution Threads in the ACUCOBOL-GT User's Guide.

NTF-RESIZED (value 4114)

This event occurs when a resizeable window that does not have AUTO-RESIZE specified is resized by the user. The application typically reconstructs the screen in response. EVENT-DATA-1 contains the new height and EVENT-DATA-2 contains the new width, both measured in hundredths of cells (for example, an 80-column-wide screen is expressed as 8000). Alternatively, after the ACCEPT terminates, you can use a format 2 INQUIRE statement to obtain the window's dimensions and other information. See INQUIRE Statement in Procedure Division Statements of the ACUCOBOL-GT Reference Manual.

The resize layout manager can simplify the task of resizing controls in a window that has been resized. For more information, see Layout Managers.

MSG-CLOSE (value 16415)

EVENT-ACTIONThis event occurs when the user clicks on the window's Close box, clicks Close from the window's system menu, or types the host system's key sequence to close the application (Alt-F4 for Windows).

MSG-CLOSE provides a single point at which you can test for the close operation. This event will be followed by the normal close sequence for the window. Handling of the initial window is dictated by the current setting of the QUIT-MODE configuration variable. This may also result in the generation of a CMD-CLOSE event for the other windows. If you set EVENT-ACTION to EVENT-ACTION-FAIL in response to this event, the close operation is inhibited.

Parent topic: Events Reference


Control Events

For any ACUCOBOL-GT, ActiveX, or .NET graphical control in your program, you can specify a list of event types to either send to or withhold from the program. This mechanism can be helpful in improving application performance by eliminating the processing of events that are not required. See the entry for EVENT-LIST in Common Screen Options for more information.

The following events are associated with controls:

  • CMD-CLICKED (value 4)
  • CMD-DBLCLICK (value 5)
  • CMD-GOTO (value 3)
  • CMD-HELP (value 8)
  • CMD-TABCHANGED (value 7)
  • MSG-AX-EVENT (value 16436)
  • MSG-BEGIN-DRAG (value 16406)
  • MSG-BEGIN-ENTRY (value16392)
  • MSG-BITMAP-CLICKED (16400)
  • MSG-BITMAP-DBLCLICK (event 16401)
  • MSG-BEGIN-HEADING-DRAG (value 16408)
  • MSG-CANCEL-ENTRY (value 16394)
  • MSG-COL-WIDTH-CHANGED (value 16410)
  • MSG-END-DRAG (value 16407)
  • MSG-END-HEADING-DRAG (value 16409)
  • MSG-FINISH-ENTRY (value16393)
  • MSG-GOTO-CELL (value 16395)
  • MSG-GOTO-CELL-DRAG (16404)
  • MSG-GOTO-CELL-MOUSE (value 16396)
  • MSG-GRID-RBUTTON-DOWN (value 16426)
  • MSG-GRID-RBUTTON-UP (value 16427)
  • MSG-HEADING-CLICKED (value 16402)
  • MSG-HEADING-DBLCLICK (value 16403)
  • MSG-HEADING-DRAGGED (value 16405)
  • MSG-NET-EVENT (value 16437)
  • MSG-PAGED-FIRST (16423)
  • MSG-PAGED-LAST (value 16424)
  • MSG-PAGED-NEXT (value 16419)
  • MSG-PAGED-NEXTPAGE (value 16421)
  • MSG-PAGED-NEXT-WHEEL (value 16439)
  • MSG-PAGED-PREV (value 16420)
  • MSG-PAGED-PREVPAGE (value 16422)
  • MSG-PAGED-PREV-WHEEL (value 16438)
  • MSG-SB-NEXT (value 16385)
  • MSG-SB-NEXTPAGE (value 16387)
  • MSG-SB-PREV (value 16386)
  • MSG-SB-PREVPAGE (value 16388)
  • MSG-SB-THUMB (value 16389)
  • MSG-SB-THUMBTRACK (value 16390)
  • MSG-SPIN-DOWN (value 16417)
  • MSG-SPIN-UP (value 16416)
  • MSG-TV-BEGINEDITLABEL (value 16440)
  • MSG-TV-ENDEDITLABEL (value 16441)
  • MSG-TV-DBLCLICK (value 16428)
  • MSG-TV-EXPANDED (value 16414)
  • MSG-TV-EXPANDING (value 16413)
  • MSG-TV-SELCHANGE (value 16412)
  • MSG-TV-SELCHANGING (value 16411)
  • MSG-VALIDATE (value 16391)
  • MSG-WB-BEFORE-NAVIGATE (value 16429)
  • MSG-WB-DOWNLOAD-BEGIN (16431)
  • MSG-WB-DOWNLOAD-COMPLETE (value 16432)
  • MSG-WB-NAVIGATE-COMPLETE (value 16430)
  • MSG-WB-PROGRESS-CHANGE (value 16433)
  • MSG-WB-STATUS-TEXT-CHANGE (16434)
  • MSG-WB-TITLE-CHANGE (value 16435)
  • NTF-CHANGED (value 4100)
  • NTF-PL-FIRST (value 4105)
  • NTF-PL-LAST (value 4106)
  • NTF-PL-NEXT (value 4101)
  • NTF-PL-NEXTPAGE (value 4103)
  • NTF-PL-NEXT-WHEEL (value 4109)
  • NTF-PL-PREV (value 4102)
  • NTF-PL-PREV-WHEEL (value 4108)
  • NTF-PL-PREVPAGE (value 4104)
  • NTF-PL-SEARCH (value 4107)
  • NTF-SELCHANGE (value 4099)
Parent topic: Events Reference


CMD-CLICKED (value 4)

This event occurs for PUSH-BUTTON, CHECK-BOX, and RADIO-BUTTON controls, even if NOTIFY is not specified. Specifying NOTIFY makes this a terminating event for check boxes and radio buttons. CMD-CLICKED is always a terminating event for push buttons. The EVENT-DATA-1 and EVENT-DATA-2 values are not used.

Parent topic: Control Events


CMD-DBLCLICK (value 5)

Indicates that the user has double-clicked on an item in a list-box or combo-box (returning this event), and that the box does not have a TERMINATION-VALUE or EXCEPTION-VALUE associated with it. This will occur only if the application requests it via the NOTIFY-DBLCLICK list-box and combo-box styles. EVENT-DATA-1 is the index of the selected item in the list (starting at 1). EVENT-DATA-2 is not used.

Parent topic: Control Events


CMD-GOTO (value 3)

Indicates that the user wants to activate the control that generated the event. This happens when the user clicks on an inactive control with the mouse or types the control's key letter. The application should perform a normal ACCEPT of that control in response. (Failing to ACCEPT a control in response to a CMD-GOTO event for that control is generally not good programming practice, because it prevents the control from behaving normally.) The EVENT-DATA-1 and EVENT-DATA-2 values are not used. Note that the event is not generated if you are ACCEPTing a Screen Section item and the user selects different controls in that screen. The Screen Section handler automatically performs the necessary activation.

The CMD-GOTO event is handled specially in the Screen Section with regard to embedded procedures. This event causes a control's AFTER procedure to execute, instead of its EXCEPTION procedure. We assume that moving between fields with the mouse is a normal event and that field validation and clean-up (normally located in AFTER procedures) should be executed.

Parent topic: Control Events


CMD-HELP (value 8)

This event occurs when help is requested for the control described in EVENT-CONTROL-HANDLE. The control's help ID is in EVENT-DATA-2 (this value is zero if the control does not have a help ID). Because this event is handled by the run-time system, it is not a terminating event in your program. However, you can detect this event in the control's event procedure. You can also handle this event in the event procedure itself and prevent the runtime system's automatic handling by setting the EVENT-ACTION-CONTINUE element of the EVENT-STATUS data item. For a detailed description of EVENT-ACTION-CONTINUE and other elements of the EVENT-STATUS data item. See Special-Names Paragraph in the Reference Manual for more information.

Parent topic: Control Events


CMD-TABCHANGED (value 7)

This event occurs when the user selects a new tab from a TAB control. The value of the selected tab is in EVENT-DATA-1. Unlike most events, this one performs any validation specified in the ACCEPT, and the current field's AFTER procedure is executed rather than its EXCEPTION procedure. This event ensures that the user cannot use the TAB control to leave a form when it contains invalid data. EVENT-DATA-2 is not used

Parent topic: Control Events


MSG-AX-EVENT (value 16436)

This event occurs when an ActiveX control or COM object has fired an event. EVENT-DATA-2 contains the ActiveX control's or COM object's event ID. This is a numeric identifier that matches an EVENT phrase in the description of the class that generates the event. The ID may be positive or negative.

For ActiveX, two pairs of library routines, C$GETEVENTDATA / C$SETEVENTDATA and C$GETEVENTPARAM / C$SETEVENTPARAM are used to get and set event parameters for the current event. For COM, you must use the C$GETEVENTDATA / C$SETEVENTDATA routines to get and set event parameters.

Parent topic: Control Events


MSG-BEGIN-DRAG (value 16406)

This event is generated when the user begins dragging the mouse in a grid control while holding down the left-button. This is generated only for non-header cells, immediately before the first corresponding MSG-GOTO-CELL-DRAG event. EVENT-DATA-1 contains the column number of the cell where the user began dragging the mouse, and EVENT-DATA-2 contains the row number of that cell. The properties X and Y are set to match these values for the duration of this event. The properties START-X and START-Y are also set to match these values (note that unlike X and Y, these settings are retained after this event finishes).

Parent topic: Control Events


MSG-BEGIN-ENTRY (value16392)

This event occurs when the user starts modifying a cell in a grid control. EVENT-DATA-1 contains the column number of the cell, and EVENT-DATA-2 contains its record number. For convenience, the properties X and Y are set to the cursor's cell for the duration of this event (that is, they are set to the cursor's location at entry to the event procedure and restored to their prior values at exit). This allows you to get a before image of the cell easily by simply doing an INQUIRE on CELL-DATA.

You can prevent the entry from occurring by setting EVENT-ACTION to EVENT-ACTION-FAIL.

Parent topic: Control Events


MSG-BITMAP-CLICKED (16400)

This event occurs when the user left-clicks on a bitmap contained in a grid control. EVENT-DATA-1 contains the column number of the cell clicked, and EVENT-DATA-2 contains the record number of that cell. For convenience, the properties X and Y are set to match these values for the duration of the event.

If you set EVENT-ACTION to EVENT-ACTION-FAIL, the normal action of left-clicking in a cell is prevented (that is, the cursor is not moved to that cell).

Parent topic: Control Events


MSG-BITMAP-DBLCLICK (event 16401)

This event occurs when the user double-clicks on a bitmap contained in a grid control. EVENT-DATA-1 contains the column number of the cell double-clicked, and EVENT-DATA-2 contains the record number of that cell. For convenience, the properties X and Y are set to match these values for the duration of the event.

If you set EVENT-ACTION to EVENT-ACTION-FAIL, the normal action of double-clicking in a cell is prevented (that is, the grid does not shift to entry mode for the cell).

Parent topic: Control Events


MSG-BEGIN-HEADING-DRAG (value 16408)

This event is generated when the user begins dragging the mouse in a grid control while holding down the left button. This is generated only for header cells, immediately before the first corresponding MSG-HEADING-DRAGGED event. EVENT-DATA-1 contains the column number of the cell in which the user began dragging the mouse, and EVENT-DATA-2 contains the row number of that cell. The properties X and Y are set to match these values for the duration of this event. The properties START-X and START-Y are also set to match these values (note that unlike X and Y, these settings are retained after this event finishes).

Parent topic: Control Events


MSG-CANCEL-ENTRY (value 16394)

This event occurs when the user leaves entry mode in a grid control by pressing the Cancel key (under Windows, this is the Escape key). The contents of the cell are restored to the cell's contents prior to the start of the entry. EVENT-DATA-1 contains the column number of the cell, and EVENT-DATA-2 contains its record number. For convenience, the properties X and Y are set to the cursor's cell for the duration of this event. This event also occurs in the special case where the user enters spaces (or nothing) into a cell that is in a record past the end of the last record added to the grid. This is to prevent variable-length grids (that is, NUM-ROWS of -1) from expanding when the user enters empty data.

Parent topic: Control Events


MSG-COL-WIDTH-CHANGED (value 16410)

This event occurs when the user changes the width of a column in a grid control. For this to occur, the grid must have the ADJUSTABLE-COLUMNS style and must have only one row per record. EVENT-DATA-1 contains the column number being changed. EVENT-DATA-2 contains the new width (in characters).

Parent topic: Control Events


MSG-END-DRAG (value 16407)

This event indicates that the user has released the mouse button after dragging the mouse during a normal (non-header) drag operation in a grid control. EVENT-DATA-1 contains the column number of the cell in which the user finished dragging the mouse. EVENT-DATA-2 contains that cell's row number. The properties X and Y are set to match these values for the duration of this event.

Parent topic: Control Events


MSG-END-HEADING-DRAG (value 16409)

This event indicates that the user has released the mouse button after dragging the mouse during a header drag operation in a grid control. EVENT-DATA-1 contains the column number of the cell in which the user finished dragging the mouse. EVENT-DATA-2 contains that cell's row number. The properties X and Y are set to match these values for the duration of this event.

Parent topic: Control Events


MSG-FINISH-ENTRY (value16393)

This event occurs when the user finishes editing a cell in a grid control. You can use this opportunity to validate the cell's contents and do any reformatting of the data. EVENT-DATA-1 contains the column number of the cell, and EVENT-DATA-2 contains its record number. For convenience, the properties X and Y are set to the cursor's cell for the duration of this event. This allows you to retrieve the entered data by simply performing an INQUIRE on CELL-DATA. To reformat the entered data, INQUIRE on CELL-DATA, perform the desired formatting, and MODIFY CELL-DATA with the reformatted data. Note that if you INQUIRE directly into a numeric or numeric-edited data item, you get automatic conversion similar to MOVE WITH CONVERSION (with simple truncation on overflow). For more sophisticated testing and reformatting, INQUIRE into an alphanumeric item and examine the data directly.

You can force the user to stay in entry mode on the current cell by setting EVENT-ACTION to EVENT-ACTION-FAIL. This is what you should usually do if the user enters invalid data.

Note: Like all controls that can be activated, grids generate the MSG-VALIDATE event. However, this occurs only when the user attempts to leave the grid entirely. This is not usually very useful, so it is best to do validation in response to MSG-FINISH-ENTRY.
Parent topic: Control Events


MSG-GOTO-CELL (value 16395)

Generated any time the user moves the cursor to a new grid control cell using the keyboard. EVENT-DATA-1 contains the column number of the cell being moved to, and EVENT-DATA-2 contains the record number of that cell. For convenience, the properties X and Y are set to match these values for the duration of the event. You can determine which cell the user is moving from by inquiring CURSOR-X and CURSOR-Y.

You can prevent the user from entering the cell by setting EVENT-ACTION to EVENT-ACTION-FAIL. If you do this, the cursor remains in its previous cell. You can direct the cursor to a different cell by setting EVENT-ACTION to EVENT-ACTION-FAIL and then modifying CURSOR-X and CURSOR-Y directly.

Parent topic: Control Events


MSG-GOTO-CELL-DRAG (16404)

Generated when the user moves the mouse into a new grid control cell while holding the left button down. This event occurs only if the user clicks in a non-header cell first. Clicking outside of the grid and then dragging the mouse over the grid has no effect. Clicking in a header cell and then dragging the mouse over the grid generates MSG-HEADING-DRAGGED events instead.

Like most grid events, EVENT-DATA-1 contains the column number of the cell being moved to, and EVENT-DATA-2 contains the record number of that cell. For convenience, the properties X and Y are set to match these values for the duration of the event.

The default action taken for this event is to scroll the grid (if needed) and then place the cursor in the dragged-to cell. You can prevent the cursor from being moved by setting EVENT-ACTION to EVENT-ACTION-FAIL (the grid is scrolled regardless).

This event can be disabled by setting the style NO-CELL-DRAG, or by setting the run-time configuration file variable GRID_NO_CELL_DRAG.

Parent topic: Control Events


MSG-GOTO-CELL-MOUSE (value 16396)

This event is generated any time the user moves the cursor to a grid control cell using the mouse. This event is similar to MSG-GOTO-CELL, which generates a message when the cursor is moved via the keyboard. One reason you may want to know whether the user is moving to the cell via the mouse or the keyboard is if you are preventing the user from visiting a particular cell. You may want to leave the cursor in its original location if the user clicks on the cell with the mouse. But if the user types a key, you may want to skip over the field (you can tell which direction to skip by looking at the cell the user is starting from). This event differs from MSG-GOTO-CELL in that a message is generated by MSG-GOTO-CELL-MOUSE even when the user clicks in the grid control cell that contains the cursor.

For details about the handling of this event, see MSG-GOTO-CELL.

Note: The behavior of this event changed with Version 5.2. For more information, see Changes Affecting Version 5.1.
Parent topic: Control Events


MSG-GRID-RBUTTON-DOWN (value 16426)

This event occurs in the grid control when the user depresses the right mouse button. EVENT-DATA-1 is set to the column number of the cell being clicked, EVENT-DATA-2 is set to the row number. If the grid is right-clicked outside of any cells, these values are set to zero. The grid properties X and Y are set to these same values for the duration of this event. If you respond to this event by setting EVENT-ACTION to EVENT-ACTION-COMPLETE, no further processing of this event occurs. Otherwise, the grid acts as if the user pressed the left mouse button.

Parent topic: Control Events


MSG-GRID-RBUTTON-UP (value 16427)

This event occurs when the user releases the right mouse button. The event behaves in the same manner as the MSG-GRID-RBUTTON-DOWN event. Once this event finishes processing, any pop-up menu associated with the grid is displayed normally.

One way you can use this event is to select an appropriate pop-up menu depending on the cell clicked. For example, you may want different pop-up menus for the headings and the body of the grid. You can examine the cell clicked in this event and set the appropriate pop-up menu for the control. The selected menu appears after the event has finished.

Parent topic: Control Events


MSG-HEADING-CLICKED (value 16402)

This event occurs when the user left-clicks on a row or column header in a grid control. EVENT-DATA-1 contains the column number of the cell clicked, and EVENT-DATA-2 contains the record number of that cell (one of these will be 1). For convenience, the properties X and Y are set to match these values for the duration of the event.

Parent topic: Control Events


MSG-HEADING-DBLCLICK (value 16403)

This event occurs when the user double-clicks on a row or column header in a grid control. EVENT-DATA-1 contains the column number of the cell double-clicked, and EVENT-DATA-2 contains the record number of that cell (one of these will be 1). For convenience, the properties X and Y are set to match these values for the duration of the event.

Parent topic: Control Events


MSG-HEADING-DRAGGED (value 16405)

This event occurs when the user moves the mouse into a grid control header cell while holding the left button down. This event is generated only when the user first clicks in a header cell. If the user clicks in a header and then drags the mouse over a non-header cell, MSG-HEADING-DRAGGED is generated and the closest header cell is used. These rules allow the user to be a bit sloppy when dragging the mouse.

EVENT-DATA-1 contains the column number of the cell dragged-to, and EVENT-DATA-2 contains the row number (one of these will be 1). For convenience, the properties X and Y are set to match these values for the duration of the event.

Parent topic: Control Events


MSG-NET-EVENT (value 16437)

This event occurs when a .NET control has fired an event. EVENT-DATA-2 contains the .NET control's event type. A library routine, C$GETNETEVENTDATA, is used to get the event parameters for the current event.

Parent topic: Control Events


MSG-PAGED-FIRST (16423)

This event occurs for grids with the PAGED style. It indicates that the user has clicked on the First Page button (the same button as the Previous Record button with the Shift key held down). The runtime system responds to this event by positioning the record pointer at the beginning of the data source. Assuming that the data source is an indexed file, a START statement sets the record pointer so that a READ NEXT would retrieve the first record in the file. If you set EVENT-ACTION to EVENT-ACTION-NORMAL (this is the default), the following occurs after this event has finished:

  1. The control is emptied of data, except for any column headers
  2. The control generates a page-worth of MSG-PAGED-NEXT events to fill up the first page of data

If you opted to fill up the first page itself in response to this event, set EVENT-ACTION to EVENT-ACTION-COMPLETE to inform the grid that it should not generate the MSG-PAGED-NEXT events to fill the first page. If you cannot start at the beginning of the file (because the file is empty), set EVENT-ACTION to EVENT-ACTION-FAIL.

Parent topic: Control Events


MSG-PAGED-LAST (value 16424)

This event occurs for grids with the PAGED style. It indicates that the user has clicked on the Last Page button (the Next Record button with the Shift key held down). This works in the same manner as the MSG-PAGED-FIRST event. You position the data source so that a MSG-PAGED-PREV event would retrieve the last record, and the grid handles the rest.

Parent topic: Control Events


MSG-PAGED-NEXT (value 16419)

This event occurs for grids with the PAGED style. It indicates that the user has clicked on the Next Record button. The expected response from the run-time system is to supply the next record after the end of the grid's current data. To do this, add a new record at the end of the grid (using RECORD-TO-ADD). If the data is from an indexed file, the value of EVENT-DATA-2 is the number of READ NEXTs you need to perform to get to the appropriate record. This value is controlled by the property FILE-POS. (For details on how this works, see the discussion on the FILE-POS property.) If you cannot supply the next record (because you have reached the end of the file), respond by setting EVENT-ACTION to EVENT-ACTION-FAIL. When you do this, you receive no more MSG-PAGED-NEXT events.

Parent topic: Control Events


MSG-PAGED-NEXTPAGE (value 16421)

This event occurs for grids with the PAGED style. It indicates that the user has clicked on the Next Page button. If you do not define a specific action when this event occurs, the grid implements the logic itself by generating a page-worth of MSG-PAGED-NEXT events. This is done with the MASS-UPDATE internally set to a non-zero value.

If you want to supply the logic by adding code to handle this event, set EVENT-ACTION to EVENT-ACTION-COMPLETE. This action-status informs the grid that it should not generate the MSG-PAGED-NEXT events because the Next Page has already been handled.

Parent topic: Control Events


MSG-PAGED-NEXT-WHEEL (value 16439)

This event occurs when the user scrolls a wheelmouse downward or away from the computer screen. The expected behavior from the run-time system is to scroll the grid downwards, that is, to fill in items from the bottom of the grid. The following EVENT-DATA information applies to these wheelmouse events: MSG-PAGED-NEXT-WHEEL, MSG-PAGED-PREV-WHEEL, NTF-PL-NEXT-WHEEL, NTF-PL-PREV-WHEEL.

Note: These events require Windows NT 4.0 or later (a requirement by Microsoft).

EVENT-DATA 1 value indicates if one or more of the virtual keys have been pressed (activated) at the time the scroll took place, for example, scrolling while pressing a key.

Value | Definition
0 | No virtual key pressed.
1 | Left mouse button is pressed (MK_LBUTTON).
2 | Right mouse button is pressed (MK_RBUTTON).
4 | A shift key is pressed (MK_SHIFT).
8 | Control key is pressed (MK_CONTROL).
16 | First X button is down (Windows 2000 or later) (MK_XBUTTON1).
32 | Second X button is down (Windows 2000 or later) (MK_XBUTTON2).

EVENT-DATA-1 values may occur simultanously, for instance, both CONTROL and SHIFT keys may be active at the same time. To test values, use the library function CBL_AND.

Since these values are passed straight through from Windows, any additions made by Microsoft will automatically be made available to the runtime system. Such additions would require you to consult Microsoft documentation on WM_MOUSEWHEEL and wParam to determine what is being passed to the low order of the wParam.

EVENT-DATA-2 contains the number of lines to scroll, as set in the operating system's SPI_GETWHEELSCROLLLINES, and is inquired by using the API function SystemParametersInfo.

The value of EVENT-DATA-2 represents the suggested standard number of lines to scroll (typically three lines), as set and determined by the operating system. Although you are free to change it, consider leaving it as is, because it comes from the operating system and is most likely what the user desires.

Because the number of wheelmouse scroll lines can be changed by users, EVENT-DATA-2 is automatically notified and updated of any scroll line number changes via the runtime system. This behavior cannot be disabled, because it is meant to comply with Windows standards. The run-time system will use the detected scroll line number for all applications, as the value returned is used for each event controlled by the runtime system.

Be aware that not only can users configure the number of lines to scroll, they can also change to scrolling a page at a time. If this is the case, EVENT-DATA-2 will return the following value:

78 WHEEL-PAGESCROLL VALUE 4294967265.

You should test EVENT-DATA-2 against this value, and if matching, scroll a page rather than lines.

Tip: A sample program called wheelevent.cbl is included in the AcuGT > samples directory of your installation. The program shows how to code a paged list box and wheelmouse events.
Parent topic: Control Events


MSG-PAGED-PREV (value 16420)

This event occurs for grids with the PAGED style. It indicates that the user has clicked the Previous Record button. The expected response from the run-time system is to supply the record before the first record of the grid's current data. To do this, add a new record at the start of the grid (using RECORD-TO-ADD to add the record and INSERTION-INDEX to position the record before the first row of data, and making sure that the record is not inserted before any column headings in the grid). If the data is from an indexed file, the value in EVENT-DATA-2 is the number of READ PREVIOUS statements you need to perform to get to the appropriate record. This value is controlled by the property FILE-POS. If you cannot supply the record (because you have reached the beginning of the file), respond by setting EVENT-ACTION to EVENT-ACTION-FAIL. When you do this, you will receive no more MSG-PAGED-PREV events.

Parent topic: Control Events


MSG-PAGED-PREVPAGE (value 16422)

This event occurs for grids with the PAGED style. It indicates that the user has clicked the Previous Page button. This works in the same manner as the MSG-PAGED-NEXTPAGE event. Although this event may be ignored, you may want to supply a specific action in response to this event. See the Help file MSG-PAGED-NEXTPAGE for details.

Parent topic: Control Events


MSG-PAGED-PREV-WHEEL (value 16438)

This event occurs when the user scrolls a wheelmouse upward or towards the computer screen. The expected behavior from the run-time system is to scroll the grid upwards, that is, to fill in items from the top of the grid. EVENT-DATA-1 indicates if any virtual keys have been pressed at the same time as the scroll, and EVENT-DATA-2 indicates the number of lines that should be scrolled on each wheelmouse event.

See MSG-PAGED-NEXT-WHEEL for more information.

Parent topic: Control Events


MSG-SB-NEXT (value 16385)

This event occurs when the user clicks on the down or right button in a scroll bar. When this message is sent to the scroll bar's event procedure, the program should respond by setting the control's new position. EVENT-DATA-1 and EVENT-DATA-2 are not used.

Parent topic: Control Events


MSG-SB-NEXTPAGE (value 16387)

This event occurs when the user clicks on the down or right page region in a scroll bar. When this message is sent to the scroll bar's event procedure, the program responds by setting the control's new position. EVENT-DATA-1 and EVENT-DATA-2 are not used

Parent topic: Control Events


MSG-SB-PREV (value 16386)

This event occurs when the user clicks on the up or left button in a scroll bar. When this message is sent to the scroll bar's event procedure, the program responds by setting the control's new position. EVENT-DATA-1 and EVENT-DATA-2 are not used.

Parent topic: Control Events


MSG-SB-PREVPAGE (value 16388)

This event occurs when the user clicks on the up or left page region in a scroll bar. When this message is sent to the scroll bar's event procedure, the program responds by setting the control's new position. EVENT-DATA-1 and EVENT-DATA-2 are not used.

Parent topic: Control Events


MSG-SB-THUMB (value 16389)

This event occurs when the user repositions the scroll bar's slider, or thumb. When this message is sent to the scroll bar's event procedure, the program responds by setting the control's new position to the value in EVENT-DATA-2. EVENT-DATA-1 is not used.

Parent topic: Control Events


MSG-SB-THUMBTRACK (value 16390)

This event occurs when the user moves a scroll bar's slider that has the TRACK-THUMB style. When this message is sent to the scroll bar's event procedure, the program does not reset the control's position in response. EVENT-DATA-2 contains the new position. EVENT-DATA-1 is not used. This scroll bar message is the only one that should not change the slider's position.

Parent topic: Control Events


MSG-SPIN-DOWN (value 16417)

This event occurs when the user clicks the down arrow of an entry field with the SPINNER style. The program responds to MSG-SPIN-DOWN by decrementing the entry field by a specific value, not necessarily 1. Similar to the MSG-SPIN-UP event, if the entry field has the AUTO-SPIN style, you can set the EVENT-ACTION to EVENT-ACTION-FAIL to prevent the control from decrementing the value itself.

Parent topic: Control Events


MSG-SPIN-UP (value 16416)

This event occurs when the user clicks the up arrow of an entry field with the SPINNER style. The program responds to this event by incrementing the value of the entry field. You are not limited to incrementing by 1. You may increment the value of the field any way you want by inquiring the field's current value and then modifying it to have the desired value.

If the entry field has the AUTO-SPIN style, you can set EVENT-ACTION to EVENT-ACTION-FAIL in response to MSG-SPIN-UP to prevent the control from incrementing the value itself.

Parent topic: Control Events


MSG-TV-BEGINEDITLABEL (value 16440)

This message is generated when the runtime configuration variable TV_EDITLABELS is true and the user is going to change the text of an item of a tree view control. The user can change the text of an item by clicking onto an item already selected (this behavior is consistent with Window system tree-view).

EVENT-DATA-1 is not used and always set to 0, EVENT-DATA-2 contains the ITEM of the tree view being modified. It is possible to prevent the modification by setting EVENT-DATA to EVENT-DATA-FAIL.

Parent topic: Control Events
Related reference
TV_EDITLABELS


MSG-TV-ENDEDITLABEL (value 16441)

This message is generated when the user has successfully finished editing the item text (it is not generated if the user aborts the modification by pressing Esc). EVENT-DATA-1 is not used and always set to 0, EVENT-DATA-2 contains the ITEM of the tree view modified.
Parent topic: Control Events
Related reference
TV_EDITLABELS


MSG-TV-DBLCLICK (value 16428)

This event occurs when the user double-clicks an item in a Tree View control that has no children. Items that have children expand or collapse when double-clicked. The ID of the item clicked is in EVENT-DATA-2.

You may set EVENT-ACTION to EVENT-ACTION-IGNORE to inhibit the control's internal handling of a double-click event. You should do this if you wish to transfer control to a new window in response to the double-click. If your code creates a new window here but does not ignore the event, the control's internal handling can deactivate your new window.

Parent topic: Control Events


MSG-TV-EXPANDED (value 16414)

This event occurs when an item in a Tree View control has expanded or collapsed. The ID of the parent item is in EVENT-DATA-2. One of the following two flags is in EVENT-DATA-1:

TVFLAG EXPAND | Item expanded to show children
TVFLAG COLLAPSE | Item collapsed to hide children
Parent topic: Control Events


MSG-TV-EXPANDING (value 16413)

This event occurs when an item in a Tree View control is about to expand or collapse. EVENT-DATA-1 and EVENT-DATA-2 are set in the same manner as for the event MSG-TV-EXPANDED. You can prevent the control from expanding or collapsing the item by setting EVENT-ACTION to EVENT-ACTION-FAIL. Note that the runtime will send both of these events in response to the user pressing the + or * keys. The difference is that these messages are sent regardless of whether the particular item is expanded already or not, whereas a mouse event will only cause the EXPANDED messages to be sent if the item is not already expanded. This fact can cause problems in COBOL programs, so programmers should be aware of it.

The + and * keys will generate an EXPANDED message with EVENT-DATA-1 set to TVFLAG-EXPAND, while the - key will generate an EXPANDED message with EVENT-DATA-1 set to TVFLAG-COLLAPSE.

Parent topic: Control Events


MSG-TV-SELCHANGE (value 16412)

This event occurs when the selection has changed in a Tree View control. The ID of the new item is contained in EVENT-DATA-2. EVENT-DATA-1 contains the cause of the change. It is one of the following values (found in acugui.def):

TVFLAG MOUSE | New item selected with mouse
TVFLAG KEYBOARD | New item selected with keyboard
TVFLAG PROGRAM | Program changed selected item
Parent topic: Control Events


MSG-TV-SELCHANGING (value 16411)

This event occurs when the selection in a Tree View control is about to change. EVENT-DATA-1 contains the reason for the change (see the Help file MSG-TV-SELCHANGE), and EVENT-DATA-2 contains the ID of the item that is about to be selected. You can prevent the selection from occurring by setting EVENT-ACTION to EVENT-ACTION-FAIL.

This event is generated much more often and in many more circumstances than may be anticipated. For example, the event is generated when the control goes active, even if the selection does not change. If the program is deployed with the thin client, the volume of these events can cause performance problems. The configuration variable TC_TV_SELCHANGING provides some control over the generation of these events in a thin client deployment. See the entry for TC_TV_SELCHANGING for more information.

Parent topic: Control Events


MSG-VALIDATE (value 16391)

This event occurs immediately after the run-time system performs intrinsic validation of a field at data entry (for example, the REQUIRED phrase). Specifically, an MSG-VALIDATE event is generated whenever an activatable control terminates and the termination is not the result of:

  1. An event, except for CMD-GOTO, or CMD-TABCHANGED
  2. A message, except status 95
  3. An exception, except for those that also cause movement between fields in a Screen Section

When the above conditions are met, it is a good point in the program to perform other validation of a control's data.

If the EVENT-ACTION element is set to EVENT-ACTION-CONTINUE (value 2), the control remains active so the user can correct any errors. Note that MSG-VALIDATE is not generated for controls with the SELF-ACT style, nor is it sent when the run-time system does not normally perform validation (for example, in response to a function key). This message is generated for any control that is activated, even if it does not have a value. Because of the dynamic nature of graphical screens, a user can exit a screen without all the fields being validated; therefore, validation should also be performed after completion of data entry.

Parent topic: Control Events


MSG-WB-BEFORE-NAVIGATE (value 16429)

Occurs when the WEB-BROWSER control is about to navigate to a new URL. The NAVIGATE-URL property is set to the new URL. If you set EVENT-ACTION to EVENT-ACTION-FAIL, navigate will be cancelled.

Parent topic: Control Events


MSG-WB-DOWNLOAD-BEGIN (16431)

Occurs when a navigation operation is beginning, shortly after the BeforeNavigate event.

Parent topic: Control Events


MSG-WB-DOWNLOAD-COMPLETE (value 16432)

Occurs when a navigation operation is finished.

Parent topic: Control Events


MSG-WB-NAVIGATE-COMPLETE (value 16430)

Occurs after the browser has navigated to a new URL. The final URL is stored in the VALUE property.

Parent topic: Control Events


MSG-WB-PROGRESS-CHANGE (value 16433)

Occurs when the progress of a download is updated. The PROGRESS property is set to the current progress value. The MAX-PROGRESS property is set to maximum progress value.

Parent topic: Control Events


MSG-WB-STATUS-TEXT-CHANGE (16434)

Occurs when the status bar text has changed. The STATUS-TEXT property is set to the new status text.

Parent topic: Control Events


MSG-WB-TITLE-CHANGE (value 16435)

Occurs when the title of a document in the WEB-BROWSER control becomes available or changes. The TITLE property is set to the new title.

Parent topic: Control Events


NTF-CHANGED (value 4100)

Indicates that the value of an entry field may have been changed by the user. This occurs only for entry fields that have the NOTIFY-CHANGE style. EVENT-DATA-1 is the current position of the cursor in the entry field (starting at 1). EVENT-DATA-2 is not used.

Parent topic: Control Events


NTF-PL-FIRST (value 4105)

This event is generated only by list boxes with the PAGED style and indicates that the user wants to scroll to the top of the list. The normal response is to add the first n records to the list, where n is the number of lines the list box can show. EVENT-DATA-1 and EVENT-DATA-2 are not used.

Parent topic: Control Events


NTF-PL-LAST (value 4106)

Value

This event is generated only by list boxes with the PAGED style and indicates that the user wants to scroll to the bottom of the list. The normal response is to add the last n records to the list, where n is the number of lines the list box can show. EVENT-DATA-1 and EVENT-DATA-2 are not used.

Parent topic: Control Events


NTF-PL-NEXT (value 4101)

This event is generated only by list boxes with the PAGED style and indicates that the user wants to scroll the list box one record in the downward direction. The normal response to this message is to add the next record in the list to the list box. EVENT-DATA-1 and EVENT-DATA-2 are not used.

Parent topic: Control Events


NTF-PL-NEXTPAGE (value 4103)

This event is generated only by list boxes with the PAGED style and indicates that the user wants to scroll the list box one page in the downward direction. The normal response is to add the next n records to the list box, where n is the number of lines the list box can show. EVENT-DATA-1 and EVENT-DATA-2 are not used.

Parent topic: Control Events


NTF-PL-NEXT-WHEEL (value 4109)

This event occurs when the user scrolls a wheelmouse away from the computer screen. The expected behavior from the runtime is to scroll the LIST upwards, that is, to fill in items from the top of the list. EVENT-DATA-1 indicates if any virtual keys have been pressed at the same time as the scroll, and EVENT-DATA-2 indicates the number of lines that should be scrolled on each wheelmouse event. See MSG-PAGED-NEXT-WHEEL (value16439) for more information.

Parent topic: Control Events


NTF-PL-PREV (value 4102)

This event is generated only by list boxes with the PAGED style and indicates that the user wants to scroll the list box one record in the upward direction. The normal response to this message is to add the previous record in the list to the top of the list box. EVENT-DATA-1 and EVENT-DATA-2 are not used.

Parent topic: Control Events


NTF-PL-PREV-WHEEL (value 4108)

This event occurs when the user scrolls a wheelmouse towards the computer screen. The expected behavior from the runtime is to scroll the list upwards, that is, to fill in items from the top of the list. EVENT-DATA-1 indicates if any virtual keys have been pressed at the same time as the scroll, and EVENT-DATA-2 indicates the number of lines that should be scrolled on each wheelmouse event. See MSG-PAGED-NEXT-WHEEL (value16439) for more information.

Parent topic: Control Events


NTF-PL-PREVPAGE (value 4104)

This event is generated only by list boxes with the PAGED style and indicates that the user wants to scroll the list box one page in the upward direction. The normal response is to add the previous n records to the top of the list box, where n is the number of lines the list box can show. EVENT-DATA-1 and EVENT-DATA-2 are not used.

Parent topic: Control Events


NTF-PL-SEARCH (value 4107)

This event is generated only by list boxes with the PAGED style and indicates that the user wants to scroll to the page that contains the text he or she has entered. The normal response is to locate the closest matching record and then to add a page of records to the list box, starting with the record found. EVENT-DATA-1 contains the length of the search text. EVENT-DATA-2 is not used. To determine the search text entered, use the INQUIRE verb on the SEARCH-TEXT property of the list box.

Parent topic: Control Events


NTF-SELCHANGE (value 4099)

This event indicates that the user has selected a new item in a list box or in the list box of a combo box. This event will occur only if the application requests it via the NOTIFY-SELCHANGE list box and combo box styles. EVENT-DATA-1 is the index of the selected item in the list (starting at 1). EVENT-DATA-2 is not used.

Parent topic: Control Events


Menu Events

In addition to control events are events associated with pop-up menus that are tied to a control. You can detect pop-up menu selections directly in a control's event procedure. Messages are generated as the user goes through the process of selecting a pop-up menu item.

MSG-INIT-MENU (value 16398)

This event occurs immediately prior to the display of a control’s pop-up menu. EVENT-DATA-2 contains the control’s menu handle. The control’s event procedure can use this event to update any state information in the menu, such as enabling/disabling items or setting/ removing check marks. If the event procedure sets EVENT-ACTION to EVENT-ACTION-FAIL, or sets the control’s menu handle to NULL, then the menu is not displayed. In this case, any host-defined built-in menu for the control class will display instead (e.g., Windows Cut/Copy/Paste/Undo menu associated with entry fields). If there is no host-defined menu, then no menu is shown.

MSG-INIT-MENU applies to windows in the same manner that it does for controls. When a window’s pop-up menu is about to appear, you can pass the information that came with this event to the window’s event procedure to update the menu’s state before the menu is shown. You can also prevent the menu from being seen by setting EVENT-ACTION to EVENT-ACTION-FAIL.

MSG-MENU-INPUT (value 16397)

This event occurs when the user has activated a control’s pop-up menu and selected an item on the menu. For windows, the information from this message event is passed to a window’s event procedure when the user does any of the following:

  1. selects an item from the window’s pop-up menu bar,
  2. selects an item from the window’s pop-up menu,
  3. selects an item from a pop-up menu owned by a control contained in the window, and that control’s event procedure did not stop further processing of the menu selection, or
  4. selects the Close option from the initial window’s system menu (or clicks the Close button), and you have set the configuration option QUIT-MODE to a positive value. This configuration option causes the runtime to treat the close operation as if it were an item on the initial window’s menu bar.

EVENT-DATA-2 contains the menu item’s ID. Setting EVENT-ACTION to EVENT-ACTION-CONTINUE prevents further processing of the menu selection. Otherwise, the menu selection is treated as a normal menu selection from the menu bar (i.e., it terminates the ACCEPT with an exception value equal to the menu

item’s ID).

MSG-END-MENU (value 16399)

This event occurs when the pop-up menu of either a control or a window has been removed from the screen. EVENT-DATA-2 contains the control’s (or window’s) menu handle. The only normal reason for processing this event would be to undo some effect created in response to MSG-INIT-MENU.

Parent topic: Events Reference


Using the Mouse

  • Mouse Properties
  • Mouse Action Ownership
  • How Mouse Actions Are Handled
  • Automatic Mouse Handling
  • Screen Section Behavior
  • W$MOUSE Library Routine
Parent topic: ACUCOBOL-GT User Interface Programming


Mouse Properties

This section describes how to activate and use a mouse with your COBOL applications.

ACUCOBOL-GT offers mouse support for both character-based and graphical environments. (Currently, Windows environments are supported. Limited mouse support is provided for X terminals if you are using a curses-compatible mouse. Support for character-based UNIX terminals with ANSI mouse support is also available, but limited. Support for other host systems may be added in the future, when their support software becomes available.)

For many applications, ACUCOBOL-GT can provide automatic mouse handling that simplifies the amount of programming you must do to use the mouse effectively.

This section describes which mouse features are automatic when you run your program with the ACUCOBOL-GT run-time system. It also explains how to add other mouse controls — in your COBOL program and your COBOL configuration file — if you want them.

Note: In character-based environments, the mouse pointer is invisible by default. To make use of the mouse, you'll need to enable it, as described in W$MOUSE. Under graphical environments, such as Windows, the mouse is always enabled.

A mouse is a device that allows the user to position a pointer on the screen. A mouse has the following properties:

  • The mouse pointer can be positioned anywhere on the physical screen. (Note that this can include regions outside of your application window in a graphical environment.)
  • Under graphical environments, the mouse pointer can have a variety of shapes. The default shape is typically an arrow. On character-based systems, the mouse pointer is a square in reverse-video.
  • The mouse itself has from one to three buttons on it. These buttons may be either up or down. We say that a mouse button has been clicked if it has been pushed down and then quickly released. Also, a button may be double-clicked (clicked twice in quick succession). (Note that up and down are states; clicking and double-clicking are transient actions.)
  • The buttons are referred to as the left, right, and middle buttons. A mouse with two buttons has only left and right buttons; a one-button mouse has only a left button. Left-handed users typically exchange the meanings of the left and right buttons, but this is handled outside of the application — your program refers to the primary mouse button as the left button regardless of the actual button used.
  • Some mouses, in addition to the buttons, have a wheel. The mouse wheel can be used to scroll a window, just like a scroll bar. In the Windows environment, in the Mouse Properties applet of the Control Panel, the user can configure mouse wheel action so that each click (or notch) of the mouse wheel is equivalent to a certain number of mouse button clicks on the scroll bar.
  • The mouse pointer is independent from the program’s text cursor. Typically, an application lets the user position the text cursor on the screen by positioning the mouse pointer at the desired location and clicking the left button.
Parent topic: Using the Mouse


Mouse Action Ownership

In graphical environments such as Windows, several applications may be running at the same time. How is the activity of moving the mouse pointer or clicking a mouse button communicated to the correct application?

Mouse actions are first communicated directly to the environment. The environment then determines which application receives a message about the mouse activity.

Almost always, the basic rule is that whichever application window is topmost and is sitting directly under the mouse pointer receives the current mouse message.

The graphical environment makes this determination on its own, which means that an ACUCOBOL-GT application is not aware of mouse actions that happen outside its application window. Conversely, mouse actions occurring within an ACUCOBOL-GT application window are not known to other applications that might be running at the same time.

The one exception to the basic rule of who receives the mouse message is that you can capture the mouse in your program by a subroutine call. If you capture the mouse, your program receives all mouse messages, no matter where they occur on the physical screen, until you release the mouse. This option is typically used for situations in which the user is marking or dragging some object on the screen. You can capture the mouse so that you can control the situation even if the user accidentally moves the mouse outside your application window.

Parent topic: Using the Mouse


How Mouse Actions Are Handled

ACUCOBOL-GT treats each mouse action like a unique function key that the program can act on. Each (unmasked) mouse action returns an exception value to the program. By examining the exception value, your program can determine which action just occurred.

Because it would be very disruptive to your program to return exception codes every time the user moved the mouse, the mouse actions can be masked (ignored). By default, all mouse actions are masked (except those that are managed by automatic mouse handling). So, your program is not interrupted by any mouse action. You can enable some or all of the mouse actions in any combination by setting the COBOL configuration variable MOUSE-FLAGS. This allows you to program only for those mouse actions that you care about. See Unmasking Mouse Actions for more information.

After your program becomes aware of a mouse action, you'll need additional information, such as the location of the mouse. ACUCOBOL-GT provides a utility library routine called W$MOUSE that enables you to determine the mouse's location and the state of each of its buttons. You can also use this routine to control mouse behavior. You'd typically call W$MOUSE in response to the user's pressing one of the buttons, to determine where the mouse is located.

  • Mouse Exception Processing
  • Assigning Results to Mouse Actions
  • Unmasking Mouse Actions
Parent topic: Using the Mouse


Mouse Exception Processing

ACUCOBOL-GT treats each of the possible mouse actions in a manner similar to a function key. Each action has a unique key code that allows you to define the desired behavior by using the KEYSTROKE configuration variable. The following table details the mouse action, the corresponding key code, and the default exception value returned.

Action | Key Code | Exception Value
Mouse moved | Mv | 80
Left button pushed | Ml | 81
Left button released | ML | 82
Left button double-clicked | M1 | 83
Middle button pushed | Mm | 84
Middle button released | MM | 85
Middle button double-clicked | M2 | 86
Right button pushed | Mr | 87
Right button released | MR | 88
Right button double-clicked | M3 | 89

For example, if the user moves the mouse while your program is at an ACCEPT statement, that ACCEPT statement will terminate with an exception value of 80. Note that this will occur only if the mouse action is unmasked and your ACCEPT statement allows for exception keys. If the mouse action is masked or if the ACCEPT statement does not allow for exception keys, the mouse movement will be ignored.

Parent topic: How Mouse Actions Are Handled


Assigning Results to Mouse Actions

You may assign different values or results to the mouse actions by using the KEYSTROKE configuration variable. This variable is described in detail in The KEYSTROKE Variable.

For example, to cause the right button to delete the current character, use the following configuration entry:

KEYSTROKE   Edit=Delete   Mr

The Edit=Delete phrase indicates the desired action; the Mr phrase is the key code associated with the user's pressing the right mouse button. You may also accomplish the same thing in COBOL by using the SET ENVIRONMENT verb:

SET  ENVIRONMENT  "KEYSTROKE"  TO  "Edit=Delete  Mr"
Parent topic: How Mouse Actions Are Handled


Unmasking Mouse Actions

Normally, you don't want every mouse action to return an exception value to your program. For example, you usually don't need to know that the user moved the mouse. Having to program for that case for each ACCEPT statement would be very tedious. For this reason, ACUCOBOL-GT allows you to mask out (ignore) some or all of the mouse actions in any combination. By default, all of the mouse actions are masked — you must enable the actions that you want to use.

You control which mouse actions you want to handle by setting the value of the configuration variable MOUSE-FLAGS. The value you set is actually one or more values added together.

Each numeric value shown in the mouse actions table also has a descriptive name (such as arrow-left-down). Note that these descriptive names come from the file acugui.def. If you use these descriptive names in your program, add this statement to the Working-Storage section of your program:

copy "acugui.def"

The possible values are:

AUTO-MOUSE-HANDLING | Value 1. Causes ACUCOBOL-GT to useits automatic mouse handling facility. This is described in detail below. (default)
ALLOW-LEFT-DOWN | Value 2. Enables the left button pushed action.
ALLOW-LEFT-UP | Value 4. Enables the left button released action.
ALLOW-LEFT-DOUBLE | Value 8. Enables the left button double-clicked action
ALLOW-MIDDLE-DOWN | Value 16. Enables the middle button pushed action.
ALLOW-MIDDLE-UP | Value 32. Enables the middle button released action.
ALLOW-MIDDLE-DOUBLE | Value 64. Enables the middle button double-clicked action.
ALLOW-RIGHT-DOWN | Value 128. Enables the right button pushed action.
ALLOW-RIGHT-UP | Value 256. Enables the right button released action.
ALLOW-RIGHT-DOUBLE | Value 512. Enables the right button double-clicked action.
ALLOW-MOUSE-MOVE | Value 1024. Enables the mouse moved action.
ALWAYS-ARROW-CURSOR | Value 2048. Forces the mouse pointer always to be the default arrow shape when you are using automatic mouse handling. If this is not set, then the shape of the mouse pointer varies depending on various configuration options. This is described in detail below.
ALLOW-ALL-SCREEN-ACTIONS | Value 16384. This causes all enabled mouse actions that occur within your application’s window to be acted upon. If this is not set, then only mouse actions that occur within the current ACUCOBOL-GT window are acted upon. (The current ACUCOBOL-GT window is a window created by your program with the DISPLAY WINDOW verb.)

For example, if you wanted to act on the user's pressing either the left or right buttons, you could do the following in COBOL:

ADD  ALLOW-LEFT-DOWN,  ALLOW-RIGHT-DOWN
     GIVING  MOUSE-SETTING
SET  ENVIRONMENT  "MOUSE-FLAGS" TO
     MOUSE-SETTING

You may also set the MOUSE-FLAGS variable directly in the COBOL configuration file. The following entry in the configuration file would produce the same results as the example shown above:

MOUSE-FLAGS  130

See the list above for the numeric values associated with each setting.

The default setting of MOUSE-FLAGS is 1 (AUTO-MOUSE-HANDLING).

Parent topic: How Mouse Actions Are Handled


Automatic Mouse Handling

The setting of the MOUSE-FLAGS configuration variable determines whether or not automatic mouse handling is used. By default, this is turned on.

Automatic mouse handling requires no changes to the COBOL program. It causes the runtime system to interpret any mouse actions that occur within a field that's being entered by an ACCEPT statement. The runtime system processes the mouse actions; your application doesn't have to do anything. Your application doesn't even have to be aware that a mouse action has occurred.

The user is able to do the following with the mouse:

  • Move the cursor to any position within the current field by moving the mouse to that location and pressing the left button. The cursor will move to that location
  • Select a set of characters by moving the mouse to a location in the field, pressing the left button, and then dragging the mouse to a new location and releasing the button. The selected characters will be shown in reverse video. The next character that the user types will replace the selected characters. Also, if the user types any key associated with the Delete action, the selected characters will be deleted
  • When the application is ACCEPTing a Screen Section item that includes several fields, jump to another field by moving the mouse to that field and pressing the left button.
Note: Automatic mouse support takes precedence over other settings. That means that if a mouse action can be handled by automatic support, it will be. If automatic support cannot handle the action, and you have unmasked the action, then your program dictates how it's handled.

In graphical environments, the mouse pointer can assume different shapes. Whenever the mouse cursor is placed anywhere within the current field, it is shown as an I-Bar. This is a vertical bar that's typically used to indicate that the cursor will be positioned at a particular character if you press the left button. If you desire, you may change this by using the MOUSE configuration variable described below, or by setting the ALWAYS-ARROW-CURSOR option in MOUSE-FLAGS. See Unmasking Mouse Actions for a description of ALWAYS-ARROW-CURSOR.

Parent topic: Using the Mouse


Screen Section Behavior

When the user selects a field in the Screen Section, the exact behavior depends on the field's underlying type. You can control the behavior of the mouse with regard to each field type with the MOUSE configuration variable. This variable takes as its arguments one of the field-type names, an equals (=) sign, and then two keywords separated by a comma, as shown:

field-type name=keyword, keyword

Depending on where you are setting the MOUSE variable, there are several methods of setting its configuration.

If you want to implement this variable in a configuration file, the variable can be set without using the equals sign. For example:

MOUSE-NUMERIC-SHAPE     Bar

If you are setting the variable as part of your environment in Windows, the variable would look this:

SET MOUSE-NUMERIC-SHAPE=Bar

If you are setting the variable in your program using COBOL syntax, the variable would look like this:

SET ENVIRONMENT "MOUSE-NUMERIC-SHAPE" TO "Bar"

Field-type name

The runtime system distinguishes between three classes of fields: numeric, numeric-edited, and all others. These are referred to respectively as NUMERIC, EDITED, and ALPHA.

First keyword

The first keyword defines how the field is selected when the user presses the left button. This keyword can be one of the following:

Keyword | Description
NONE | Indicates that this type of field may not be selected with the mouse. When this keyword is used, the second keyword (which defines the mouse's shape) is ignored. The mouse will adopt the shape used for areas of the screen that are not part of any field.
FIELD | Indicates that pressing the left button anywhere in the field will cause the cursor to be positioned at the beginning of the field.
CHARACTER | Indicates that pressing the left button in the field will position the cursor at the character pointed to by the mouse. If this is past the last non-prompt character in the field, the cursor will be placed just after the last non-prompt character.

Second keyword

The second keyword is used only for graphical environments. It indicates the shape that the mouse pointer should take while in the field. It can be one of the following:

ARROW | The mouse pointer appears in the default arrow shape.
BAR | The mouse appears as a vertical bar. This is the I-Bar shape typically used to indicate that the mouse can be positioned at a particular character.
CROSS | The mouse pointer appears as cross-hairs.

In graphical environments such as Windows, you may also define the shape that the mouse will take when it is used in the current field. Because the action of the mouse is the same for all field types once they become the current field, the mouse shape is the same for all three types. You set the desired shape using the CURRENT keyword in the MOUSE configuration variable. This is followed by an equals sign and the desired shape. The default shape is the BAR shape.

The default configuration is as follows:

MOUSE | Alpha=Character, Bar
MOUSE | Numeric=Field, Arrow
MOUSE | Edited=Field, Arrow
MOUSE | Current=Bar
Note: You may place multiple entries on the MOUSE configuration line, but you are not required to do so.

The following configuration variables can also be used to set the behavior of the mouse:

To set field selection: | To set cursor shape:
MOUSE_ALPHA_SELECT | MOUSE_ALPHA_SHAPE
MOUSE_EDITED_SELECT | MOUSE_EDITED_SHAPE
MOUSE_NUMERIC_SELECT | MOUSE_NUMERIC_SHAPE
 | MOUSE_CURRENT_SHAPE

With these variables, you need to set the first and second keywords separately. For example, to change the defaults shown above for a numeric field, you would enter:

MOUSE_NUMERIC_SELECT = character
MOUSE_NUMERIC_SHAPE = bar

The REQUIRED phrase is used in the Screen Section to ensure that a user cannot bypass required fields by jumping to the last field with the mouse.

Parent topic: Using the Mouse


W$MOUSE Library Routine

The runtime system contains a library routine called W$MOUSE that you can use to control the behavior of the mouse. You use this routine with the CALL statement in your COBOL program.

See the W$MOUSE entry in Appendix I for details on using this routine.

Parent topic: Using the Mouse


Menu Bars and Pop-up Menus

  • Menus Overview
  • Generic Menu Handler
  • Graphical Menu Facilities
  • Overview of Menu Handling
  • Creating Menus - the Shortcut
  • Menu Activation and Use
  • Menu Input
  • Changing Menu Results
  • Common Menu Operations
  • Pop-up Menus
  • Menu Handling: Sample Code
  • System Menu Close Handling Under Windows
  • Portability Concerns
  • Menu Bar Sample Programs
Parent topic: ACUCOBOL-GT User Interface Programming


Menus Overview

ACUCOBOL-GT offers significant support for a variety of application menus.

Menu Bars

ACUCOBOL-GT supports a fully integrated menu bar facility. This allows you to display a main menu across the top of the screen, with optional pull-down submenus. Each menu item acts much like a function key, returning an exception value to your program. You decide how you want your program to respond to each exception value.

An individual menu item can be disabled when it's not appropriate for a user to choose that item. At your option, a menu item can be marked to indicate that it has been selected. Submenus can be divided into sections with separator bars. Shortcut keys can be assigned to menu options and displayed next to menu text.

You control when a menu bar is displayed. You can remove a main menu whenever you like and replace it with a different one.

Pop-up Menus

ACUCOBOL-GT also supports pop-up menus for Windows environments. Pop-up menus appear over the application in a vertical orientation while the user is selecting an item, and then they disappear from the screen. Each window and control can have its own pop-up menu. A single pop-up menu can also be shared by several windows and controls. You can invoke a pop-up menu from your program, and you can also arrange for a right mouse-click to invoke a pop-up menu that is tied to a window or control.

Parent topic: Menu Bars and Pop-up Menus


Generic Menu Handler

The menu facility uses the host system's menu handler if one exists; otherwise, it uses ACUCOBOL-GT's own generic menu handler. The generic menu handler accommodates character-based systems and gives you a large measure of control over the appearance of the menu and its submenus.

Of the host systems currently supported, only Windows and Windows NT have their own menu handlers. This section describes the generic menu handler provided with ACUCOBOL-GT, and notes how the Windows menu handlers differ from it.

The generic menu handler displays the main menu bar horizontally along the top of the screen. The main menu bar can take one of two forms: static or pop-up.

  • Static Menu Bars
  • Pop-up Menu Bars
  • Submenus
Parent topic: Menu Bars and Pop-up Menus


Static Menu Bars

A static menu bar occupies the top line of the screen and is visible to the user even when it's not being accessed. The top line of the screen is unavailable to your program while a static menu is displayed.

The second line of the screen becomes line 1 to your program. Thus, the effective screen height is reduced by one line when you display a static menu bar.

When you initially display a static menu bar, the screen is scrolled down one line to make room for it. If this causes your current window to extend past the bottom edge of the screen, the window is truncated at the bottom edge.

When you remove a static menu bar, the screen is scrolled up one line so that line 1 of your program is on the top edge of the screen. If your current window extends to the bottom edge of the screen, it has one line added to it, so that it still extends to the bottom edge after the move.

Parent topic: Generic Menu Handler


Pop-up Menu Bars

A pop-up menu bar is one that is not normally visible. Instead, it pops up over the top line of the screen when the user activates it. The advantage of using a pop-up menu bar is that you have the full screen available to your program. The disadvantage is that the user cannot see the menu bar unless it has been activated (popped up). Pop-up menu bars are often used on character-based systems to conserve space.

You specify which type of menu bar you want by calling W$MENU with the WMENU-SET-CONFIGURATION parameter. (W$MENU is described in Appendix I of the ACUCOBOL-GT Appendices manual). Then, when the menu bar is displayed with the WMENU-SHOW parameter, your preferred menu bar type is used.

Parent topic: Generic Menu Handler


Submenus

No matter which type of main menu you use, submenus pop down from the menu bar. You may also nest submenus, up to a total of five levels (including the main menu). The ACUCOBOL-GT menu handler supports main menu bars that are one line high, and submenus that have one column. You should avoid creating menus that would exceed these limits.

Parent topic: Generic Menu Handler


Graphical Menu Facilities

If you're running in a graphical environment such as Windows, your program controls the general layout and contents of the menu. The environment controls the look of the menu and handles most of the user's interaction with it.

Windows and Windows NT menu bars are static in that they display continually until your program removes them. They are shown horizontally along the top edge of your application's window. They exist outside of your program's screen — you don't need to allow space for the menu bar when creating your application. A menu can contain submenus that pull down vertically when the user selects them. The submenus may contain further submenus, which Windows handles as pop-up menus.

Parent topic: Menu Bars and Pop-up Menus


Overview of Menu Handling

A menu consists of a list of menu entries. Each entry consists of a text label and a numeric ID. The label is displayed on the screen. The ID value does not appear; it's an internal value that uniquely identifies each menu entry. When the user selects a menu entry, your program typically receives its ID value.

Any menu entry may optionally lead to another menu, called a submenu. When the user selects an entry that leads to a submenu, the submenu pops up and the user continues with the selection process. The display and removal of submenus is handled automatically by the system. Submenus may contain additional submenus.

  • Properties of Menu Entries
Parent topic: Menu Bars and Pop-up Menus


Properties of Menu Entries

Menu entries can have these additional properties:

  • Any menu entry can be disabled. When disabled, the menu entry appears differently to the user. Under Windows and Windows NT, it's shown in gray text instead of black text. The generic menu handler lets you pick the color or attribute that distinguishes disabled items. The user is not allowed to select a disabled item.
  • Entries on submenus can also be checked. This means that a small mark is shown next to the menu's label. This is usually used to indicate that the corresponding program option is enabled. Under Windows, the mark is a check mark. With the generic menu handler, you can choose the mark; by default it's an asterisk.
  • Finally, a submenu entry may have a specialized label that generates a horizontal bar (called a separator). Separators may not be selected by the user, nor may they be checked or disabled. Separators are usually used to group related menu entries.

Your program interacts with the menu subsystem using two techniques:

  1. You construct menus and control them with the W$MENU library routine.
  2. You receive input from a menu bar via the ACCEPT statement.

Topics in this section explain how to create and display a menu using a utility program provided with ACUCOBOL-GT and discuss how your program receives input from a menu.

Parent topic: Overview of Menu Handling


Creating Menus - the Shortcut

You create menu bars and pop-up menus by using the W$MENU library routine. The process of creating a large menu can be time-consuming, so ACUCOBOL-GT includes a utility program to simplify this task. This utility is called genmenu. It's a COBOL program provided in source form.

The utility genmenu takes a simple text file that describes one or more menus and generates COBOL source code that can create these menus. You can then include this generated source file in your program by using the COPY statement.

  • Using genmenu
Parent topic: Menu Bars and Pop-up Menus


Using genmenu

  1. Compile genmenu:
  2. Create a text file that describes your menu(s).
  3. Run genmenu on that text file to create a file of COBOL code. (Used later in Step 5.)
  4. Include the copy file acugui.def somewhere in your Working-Storage section.
  5. Name the generated COBOL file (from Step 2) in a COPY statement in your Procedure Division.
  6. Build the menu: use one PERFORM statement in your application for each menu.
  7. Display the menu: call W$MENU to cause one menu to be displayed.

These steps are described in detail below.

Step One

To compile genmenu:
ccble -x -o genmenu genmenu.cbl
Note: If you usually use a suffix on your COBOL object files, you should add that suffix to the command line.

Step Two

The input to genmenu consists of a normal text file that you create using your editor. This file contains the descriptions of one or more menus. You may place blank lines freely in this file as well as comment lines that start with either * or # in column one. You may use either upper case or lower case when creating menu files.

Each line in a menu file consists of one or more fields. Fields are separated from each other by spaces. You may also use commas and tabs as field separators. Initial spaces in a line are ignored. Here's a small example:

MENU  main-menu
    "&File",            0,   submenu
        "&New",         101
        "&Open",        103, disabled
        "Save &As...",  104
        separator
        "E&xit",        105
        end-menu

You start a menu by placing the word MENU (for a menu bar) or POPUP (for a pop-up menu) on a line, followed by a menu name. A menu name may be up to 20 characters long and must be formed like a COBOL identifier (it will be used to build a COBOL paragraph name). The menu name does not appear in the generated menu bar.

Following the MENU or POPUP line, you enter one line for each menu entry that belongs to that menu. You end a menu by one of the following:

  • Ending the file (no more lines)
  • Starting another menu with another MENU or POPUP line
  • Placing the word END-MENU or END-POPUP on a line by itself (these words are treated as synonyms)

Each item in a menu needs both a label (the text that appears on screen) and a numeric ID. So, each menu entry consists of the menu label (in quotes) followed by its ID value. Use lower and upper case in the label so that it appears exactly as you want it to appear on the menu. The ID value may be either a number or the name of a level 78 that you will define in the final program. It should be greater than zero and less than or equal to 4095 (exception: it may be zero for submenus or separators).

When you're typing the label, place an & character in front of the letter that will be the entry's key letter. The user can access that menu entry quickly by typing the key letter at the keyboard. The key letter will appear underlined when the menu is displayed (unless you've specified some other appearance. Under the Windows environment, the user must press <Alt> and then type the key letter to make a menu choice with a key letter. (Menu options can also be selected with the mouse, if one is available and enabled. See Menu Configuration With the Generic Menu Handler for more information.

Note: If you don't select a key letter, no underline will appear and the first letter of the label will be used as its key letter. If two or more key letters are the same, when the user types that key letter, the system will advance to the next menu item with the chosen key letter and then wait for the user to press Enter. If you are programming for future delivery on more than one operating system, be aware that key letters may be handled slightly differently on different systems. See Portability Concerns for more information.

A shortcut key is a keyboard key that you have designated in your program to perform the same action as a menu item. You must create a programmatic association between the menu item and the key. One easy way to do this is to make the menu item's ID value the same as the exception value of the keystroke.

You may display the shortcut key's text next to the menu item in your menu if you want. To specify the shortcut key's text, place it immediately after the characters \t in the item's label. For example, if you want to create a menu item that has the text Exit and you want to display the shortcut key text Ctl-X next to it, you would specify Exit\tCtl-X as the item's label. You might think of \t as specifying a tab character that separates the two columns when they are displayed in the menu. If you need to include \t in your menu label, specify \\t to prevent it from being interpreted as a shortcut key indicator.

After an entry's ID, you may optionally enter up to three flags. These flags are the following words:

CHECKED | The menu entry starts with a check mark placed by it (enabled).
DISABLED | The menu entry starts disabled.
SUBMENU | The menu entry leads to a submenu. Subsequent menu entries refer to items that will be placed in that submenu. You complete a submenu by placing the word END-MENU on a line by itself. After completing a submenu, resume listing menu entries that appear on the parent menu.

Finally, you may enter a separator menu item by using the word SEPARATOR in place of the menu's label and then optionally listing a menu ID for it (if you omit the ID value, it will be treated as zero).

For example, the following menu file would describe one menu that consists of two items, each one of which has a submenu:

MENU main-menu
    "&File",    0,  submenu
        "&New",                    101
        "&Open",                   102
        "&Save",                   103
        "Save &As...",             104
        separator
        "E&xit",                   105
    end-menu
    "&Options",                    0,   submenu
        "&Save Settings on Exit",  201, checked
        "&Password Protect",       202, checked
        "Confirm Deletions",       203
        end-menu
Note: The blank lines and the indenting are not required, but make the menu file easier to read.

Step Three

When your text file is complete, you can use genmenu to create the COBOL source code that builds the menu. Use the following command:

RUNCBL  genmenu  menu-file  copy-file

where menu-file is the name of your text file that describes the menu and copy-file is the name of the file that will hold the generated source code. You may omit copy-file, or both menu-file and copy-file. If you do, genmenu will prompt you for these names. Note that because genmenu is a COBOL program, it will use any FILE-PREFIX and FILE-SUFFIX variables that you have set in your configuration file.

Under graphical systems, genmenu will pause when it is done and will give you an opportunity to view its output. Press <Enter> to continue. If you are running genmenu from a batch file or a makefile and don't want to see the output on a graphical system, specify -1 on the command line. On a character-based system, genmenu is designed to run as a quiet utility that has no screen output.

If genmenu detects any errors, it will display them, along with the line number of menu-file that caused the problem. Otherwise, it will simply place the generated source code in copy-file.

Step Four

Somewhere in your Working-Storage section, include the line:

COPY "acugui.def"

Step Five

Somewhere in the Procedure Division of your application, include the line:

COPY "copy-file"

Step Six

The COPY file created by genmenu will contain a paragraph called BUILD-MENU-NAME where MENU-NAME is replaced by the name you gave in the MENU line of your text file. This paragraph contains all the code necessary to produce the menu you described in your file. If you have more than one menu in your text file, the COPY file will have a paragraph for each of these menus.

You execute each one of these paragraphs with a PERFORM statement. For example:

PERFORM  BUILD-MAIN-MENU.

When the PERFORM returns, it will have set the data item MENU-HANDLE to a value that uniquely identifies the created menu. MENU-HANDLE is declared in acugui.def as a numeric data item.

If MENU-HANDLE is set to zero, it indicates that an error has occurred in the creation of the menu. This is typically caused by the system's running out of memory. Otherwise, MENU-HANDLE contains a valid identifying value. This value is called the menu's handle.

If you plan to use more than one menu, move MENU-HANDLE to another variable so that you don't lose the menu's unique identifier when you PERFORM the code that constructs the other menus. The variable you use must be declared as PIC S9(9) COMP-4.

For example:

MOVE MENU-HANDLE TO FILE-MENU-HANDLE.

Step Seven

To display a menu in your application, be sure that MENU-HANDLE does not have a zero value (zero indicates an error). Then:
CALL "W$MENU" USING WMENU-SHOW, MENU-HANDLE

The variables in this call are declared in acugui.def. This call will cause your menu to be displayed to the user. The user may immediately begin entering menu commands.

In the following code fragment, two menus are created and, if the build is successful, the main menu is displayed:

PERFORM BUILD-MAIN-MENU.
MOVE MENU-HANDLE TO MAIN-HANDLE.
PERFORM BUILD-MAIL-SYSTEM-MENU.
MOVE MENU-HANDLE TO
        MAIL-SYSTEM-HANDLE.
IF MAIN-HANDLE NOT = ZERO
    CALL "W$MENU" USING
        WMENU-SHOW, MAIN-HANDLE.
Parent topic: Creating Menus - the Shortcut


Menu Activation and Use

Under graphical environments such as Windows, once a menu is displayed the user can start selecting items from that menu. The mouse is typically used to make selections. (Under Windows, you can also select an item by pressing the <Alt> key or the <F10> key, and then the succession of key letters that form a path to the desired item.)

Note: By convention, the F10 key is used by Windows to activate program menus. This action is controlled automatically by the program. The configuration variable F10_IS_MENU allows you to set the runtime to handle the F10 key as a user-defined key. The default setting of F10-IS-MENU is 1 (on, true, yes). When you change the setting to 0 (off, false, no) you inhibit the menu activation capability.

On character-based environments, the user may activate the current menu by any of the following methods:

  1. The user may type a menu key. This is a key that is defined by your program to activate menus. You may define as many menu keys as you want. By default, there are no menu keys; your program must define them.
  2. For static menus, the user can click on the menu bar with the mouse. This assumes that the run-time contains mouse support.
  3. On terminals with an ANSI-style mouse (like xterm), the user can press <Alt> to activate the menu and then type a menu item's key letter to select the corresponding item.
Note: The only technique that is guaranteed to work for all machines is the menu key technique. Because of this, you should ensure that either your program or your COBOL configuration file defines one or more menu keys if you create a menu.
  • Defining Menu Keys
Parent topic: Menu Bars and Pop-up Menus


Defining Menu Keys

To define a menu key in a character-based environment, assign the edit-action Menu to a key with the KEYSTROKE variable in your COBOL configuration file. For example, to make the <F1> key a menu key, place this line into your configuration file:

KEYSTROKE  Edit=Menu  k1

Keys and their key codes (such as k1) are listed in Table of Keys.

You can define a menu key within your program with SET ENVIRONMENT. For example,

SET  ENVIRONMENT  "KEYSTROKE"
TO  "Edit=Menu  k1"
Note: <F10> is the menu activation key for Windows environments. This cannot be modified.

You can define a menu key by several methods. Once a menu is active, the user can:

  • Use the arrow keys to move the highlight
  • Select an item with the Spacebar or the Return key
  • Jump to an item and select it by typing its key letter
  • Use the Escape key, along with any program-defined menu keys, to cancel a menu or a submenu
Parent topic: Menu Activation and Use


Menu Input

Menu selections are handled by the ACCEPT statement. Generally speaking, a menu selection acts much like a function key. Each menu item causes an ACCEPT statement to terminate, returning an exception value equal to the item's ID.

For example, suppose the menu has this definition:

menu main-menu
   "&File",                        0,    submenu
        "&New",                    101
        "&Open",                   102
        "&Save",                   103
        "Save &As...",             104
        separator
        "E&xit",                   105
        end-menu
   "&Options",                     0,    submenu
        "&Save Settings on Exit",  201,  checked
        "&Password Protect",       202,  checked
        "&Confirm Deletions",      203
        end-menu

If the user selected the New menu item, any executing ACCEPT statement would terminate with an exception status of 101.

Note: Only ACCEPT statements that allow exception keys will terminate with a menu selection. If the ACCEPT statement does not allow exceptions, any menu selections will be ignored.
  • Function Key Handling
  • Menu Selection Limits
Parent topic: Menu Bars and Pop-up Menus


Function Key Handling

An existing application that uses function keys can readily be upgraded to use menu bars. To create a menu item that behaves exactly the same as a particular function key, give that menu item an ID that is the same as the function key's exception value.

Parent topic: Menu Input


Menu Selection Limits

The runtime system holds only one menu selection in its buffer at any time. Subsequent menu selections overwrite the one being held. For example, if the user clicks Quit from the menu and then clicks Print before the program processes the Quit selection, the program will receive only the Print selection.

Parent topic: Menu Input


Changing Menu Results

The default action of a menu item is to return an exception value equal to the item's ID. You can change the default action of a particular item by using the MENU-ITEM configuration variable.

Use the MENU-ITEM configuration variable in exactly the same fashion as the KEYSTROKE variable, except that the last entry on the line is the menu's ID, not the key code. For example, to cause a menu item whose ID is 200 to act the same as the Delete key, use the following:

MENU-ITEM   Edit=Delete   200

Alternately, you could cause menu item 200 to call the notepad sample program by using:

MENU-ITEM   Hot-Key="notepad"  200

You can program these entries in COBOL by using the SET ENVIRONMENT verb. For example,

SET  ENVIRONMENT  "MENU-ITEM"  TO
"Edit=Delete  200"
Parent topic: Menu Bars and Pop-up Menus


Common Menu Operations

After you have a menu constructed and in use, there are several common operations you may want to perform. These are accomplished with the W$MENU library routine. This section describes only these frequently used operations.

See the entry for W$MENU in ACUCOBOL-GT Appendices manual, Appendix I, for details on using this routine.

The W$MENU routine takes one or more parameters, which are always passed BY REFERENCE (the default in COBOL). The first parameter is always an operation code. This code defines what the routine will do. The remaining parameters depend on the operation selected. The operation codes are defined in the COPY file acugui.def, which by default is located at: ...\AcuGT\sample\def.

  • Disabling Menu Items
  • Checking Menu Items
  • Disabling an Entire Menu
  • Menu Configuration With the Generic Menu Handler
Parent topic: Menu Bars and Pop-up Menus


Disabling Menu Items

Your program may want to enable or disable individual menu entries dynamically. To do this, call W$MENU passing the WMENU-ENABLE or WMENU-DISABLE operation code. Follow this with the handle of the owning menu and the ID of the particular entry you want to change.

For example, to disable menu item 101, use:

CALL "W$MENU" USING WMENU-DISABLE,
MENU-HANDLE, 101

If you enable or disable a menu item on the top level of the menu, you must use the WMENU-SHOW operation to make your change visible. This allows you to modify several top level items at once before re-displaying the menu.

For example, you might have:

CALL "W$MENU" USING WMENU-ENABLE,
MENU-HANDLE, 101
CALL "W$MENU" USING WMENU-DISABLE,
MENU-HANDLE, 102
CALL "W$MENU" USING WMENU-SHOW,
MENU-HANDLE
Parent topic: Common Menu Operations


Checking Menu Items

To place or remove a check mark from a menu item, use the WMENU-CHECK or WMENU-UNCHECK operation code. Follow this by the menu's handle and the ID of the item you want to modify.

For example, to place a check mark beside the menu item 10, use the following code:

CALL "W$MENU" USING WMENU-CHECK,
MENU-HANDLE, 10

Placing check marks on top-level menu items has no effect.

Parent topic: Common Menu Operations


Disabling an Entire Menu

You may want to prevent the user from having access to the menu during certain parts of your program. To do so, call W$MENU using the WMENU-BLOCK operation code. When you want to re-enable access, call W$MENU using WMENU-UNBLOCK.

Normally, you will want to do this when you must have some specific information from the user that you need in order to continue. By disabling the menu, you will prevent the user from trying to initiate a different operation that your program is not prepared to handle.

For example, if the user has clicked Open from the menu, you may want to disable the menu until you have retrieved the name of the file to open. This could be coded like this:

CALL "W$MENU" USING WMENU-BLOCK
PERFORM GET-FILE-NAME-FROM-USER
CALL "W$MENU" USING WMENU-UNBLOCK
Parent topic: Common Menu Operations


Menu Configuration With the Generic Menu Handler

The ACUCOBOL-GT generic menu handler allows you to configure several aspects of its look and feel. This is done with get/set configuration operations of the W$MENU library routine. See the entry for W$MENU in ACUCOBOL-GT Appendices manual, Appendix I, for details on using this routine.

Parent topic: Common Menu Operations


Pop-up Menus

Pop-up menus can be created on Windows environments. Pop-up menus appear over the application in a vertical orientation while the user is clicking an item, and then they disappear from the screen. You can programmatically invoke a pop-up menu, or you can arrange for a right-mouse click to automatically invoke a pop-up menu tied to a window or a control. Each window and control can have its own pop-up menu. In addition, you can share a single menu between several windows and controls.

To create a pop-up menu, use the W$MENU routine with the WMENU-NEW-POPUP operation. This operation works just like WMENU-NEW, except that the resulting menu is a pop-up menu instead of a menu bar. Once created, pop-up menus are acted upon just like menu bars. Adding, changing, and deleting items is done in the same manner as for a menu bar, as is enabling or disabling items. If you want to add a submenu to a pop-up menu, you can use either a menu bar or another pop-up menu as the submenu.

To invoke a pop-up menu directly, use the WMENU-POPUP operation of W$MENU. The first operand is the handle of the menu you want to pop up. The menu is placed at the location of the mouse unless you specify two additional parameters, which are the absolute screen location (first row, then column). The screen location is expressed in pixels, with (1, 1) being the upper left-hand corner of the screen. This operation displays the menu, gets the user's selection (if any), and then removes the menu from the screen. The menu selection is placed into the run-time's input stream for future processing by an ACCEPT statement. This will appear to the ACCEPT statement just like a menu selection off of the menu bar.

You can automate the handling of pop-up menus by associating them with windows and controls. Each window and control can have its own pop-up menu associated with it. To do so, simply specify the menu handle in the POP-UP MENU phrase when you create the window or control. You can also add, change, or remove the pop-up menu later with the MODIFY statement.

When a window or control has a pop-up menu associated with it, the runtime will automatically display and handle this menu when the user clicks the right mouse button on the owning window or control. Your program will simply receive the menu selection in the input stream as if it came from the menu bar.

You can also detect pop-up menu selections directly in a control's event procedure. The following messages are generated as the user goes through the process of selecting a pop-up menu item:

MSG-INIT-MENU

Occurs immediately prior to the display of a control’s pop-up menu. EVENT-DATA-2 contains the control’s menu handle. The control’s event procedure can use this event to update any state information in the menu, such as enabling/disabling items or setting/removing check marks. If the event procedure sets EVENT-ACTION to EVENT-ACTION-FAIL, or sets the control’s menu handle to NULL, then the menu is not displayed. In this case, any host-defined built-in menu for the control class will display instead (e.g., Windows Cut/ Copy/Paste/Undo menu associated with entry fields). If there is no host-defined menu, then no menu is shown.

MSG-MENU-INPUT

Occurs when the user has activated a control’s pop-up menu and selected an item on the menu. EVENT-DATA-2 contains the menu item’s ID. Setting EVENT-ACTION to EVENT-ACTION-CONTINUE prevents further processing of the menu selection. Otherwise, the menu selection is treated as a normal menu selection from the menu bar (i.e., it terminates the ACCEPT with an exception value equal to the menu item’s ID).

MSG-END-MENU

Occurs when a control’s pop-up menu has been removed from the screen. EVENT-DATA-2 contains the control’s menu handle. The only normal reason for processing this event would be to undo some effect created in response to MSG-INIT-MENU.

Using MSG-MENU-INPUT, you can handle all of a control’s pop-up menu items directly in the control’s event procedure, without terminating any controlling ACCEPT statement.

Parent topic: Menu Bars and Pop-up Menus


Menu Handling: Sample Code

The following code fragment constructs a menu that consists of two submenus and displays it, first saving any existing menu:

78  ID-NEW                 VALUE 101.
78  ID-OPEN                VALUE 102.
78  ID-SAVE                VALUE 103.
78  ID-SAVE-AS             VALUE 104.
78  ID-EXIT                VALUE 105.
78  ID-SAVE-SET            VALUE 201.
78  ID-PASSWORD            VALUE 202.
77  OLD-MENU               PIC S9(9) COMP-4.
77  MAIN-MENU              PIC S9(9) COMP-4.
77  SUBMENU                PIC S9(9) COMP-4.

BUILD-MENU.
* Create two empty menus and save their menu handles
    CALL "W$MENU" USING WMENU-NEW.
    MOVE RETURN-CODE TO MAIN-MENU.
    CALL "W$MENU" USING WMENU-NEW.
    MOVE RETURN-CODE TO SUBMENU.
    IF MAIN-MENU = ZERO OR SUBMENU = ZERO
        GO TO BUILD-MENU-EXIT.

* Build "File" submenu

   CALL "W$MENU" USING WMENU-ADD, SUBMENU, 0, 0,
      "&New", ID-NEW.
   CALL "W$MENU" USING WMENU-ADD, SUBMENU, 0, 0,
      "&Open...",ID-OPEN.
   CALL "W$MENU" USING WMENU-ADD, SUBMENU, 0, W-DISABLED,
      "&Save", ID-SAVE.
   CALL "W$MENU" USING WMENU-ADD, SUBMENU, 0, W-DISABLED,
      "Save &As...", ID-SAVE-AS.
   CALL "W$MENU" USING WMENU-ADD, SUBMENU, 0, W-SEPARATOR.
   CALL "W$MENU" USING WMENU-ADD, SUBMENU, 0, 0,
      "E&xit", ID-EXIT.

* Attach "File" submenu to main menu

   CALL "W$MENU" USING WMENU-ADD, MAIN-MENU, 0, 0,
      "&File", 0, SUBMENU.

* When finished with the "File" submenu, make another
* submenu and populate it.

   CALL "W$MENU" USING WMENU-NEW.
   MOVE RETURN-CODE TO SUBMENU.
   IF SUBMENU = ZERO
       GO TO BUILD-MENU-EXIT.
   CALL "W$MENU" USING WMENU-ADD, SUBMENU, 0, W-CHECKED,
      "&Save Settings on Exit", ID-SAVE-SET.
   CALL "W$MENU" USING WMENU-ADD, SUBMENU, 0, 0,
      "&Password Protect", ID-PASSWORD.

* Attach "Options" submenu

   CALL "W$MENU" USING WMENU-ADD, MAIN-MENU, 0, 0,
      "&Options", 0, SUBMENU.

* Save current menu and display new one.

   CALL "W$MENU" USING WMENU-GET-MENU.
   MOVE RETURN-CODE TO OLD-MENU.
   CALL "W$MENU" USING WMENU-SHOW, MAIN-MENU.

Further on in the program, you may want to remove the check mark on the Save Settings on Exit menu item. The following line of code would do that:

    CALL "W$MENU" USING WMENU-CHECK, ID-SAVE-SET,
       W-UNCHECKED.

When it came time to remove this menu and restore the old one, you could use the following code:

    CALL "W$MENU" USING WMENU-SHOW, OLD-MENU.
    CALL "W$MENU" USING WMENU-DESTROY, MAIN-MENU.
Parent topic: Menu Bars and Pop-up Menus


System Menu Close Handling Under Windows

The Windows system menu has a Close item. Normally, if the user clicks this entry, the run-time system performs a normal shut down. The Close option can be controlled with the QUIT_MODE configuration variable or permanently disabled when the window is created with the NO-CLOSE phrase.

A QUIT_MODE setting of zero or less is handled directly by the runtime system. A positive QUIT_MODE setting allows your program to manage the close action instead. When a positive value is used, the Close item becomes a standard menu item with an ID equal to the value of QUIT-MODE. You may then handle the Close item just like any other menu item.

For example, if you set QUIT_MODE to 100, your program will receive exception value 100 when the user selects the Close item. If you wanted to call a special shutdown program when the user selects Close, you can assign the Close action to a hot-key program. For example:

MENU-ITEM  Hot-Key="shutdown"  100

In this example, the program shutdown might pop up a small window to confirm that the user wants to exit and, if so, execute a STOP RUN.

When the NO-CLOSE phrase is specified in a Format 11 or 12 DISPLAY WINDOW statement, the window's Close menu option is permanently disabled. The option can be applied only when the window is created and its effects cannot be reversed. The NO-CLOSE option takes precedence over other settings, including the setting of the QUIT_MODE configuration variable.

Parent topic: Menu Bars and Pop-up Menus


Portability Concerns

The ACUCOBOL-GT runtime supports menu handling. If the host system has its own menu system (such as Windows), the runtime system's menu handler calls the system's menu handler. If the system does not have its own menu handler (such as systems that use character-based terminals), the runtime system supplies its own menu handling.

This implementation causes the look-and-feel of the menus to differ from system to system. This is an advantage in that you can program for a single menu handler while getting a native look-and-feel on each host system. However, some host menuing systems may not support all features identically. The more you know about possible differences in the hosts' menu handlers, the more informed your programming decisions can be. Here are some issues to be aware of while programming:

  1. How the user selects key letters will vary from system to system. The appearance of the key letter in the menu may vary from system to system. In Windows, it appears underlined. In the run-time system's own handler, the appearance is configurable.
  2. If no key letter is supplied, the implied key letter is system-dependent. Under Windows, Windows NT, and the runtime system, the first letter of the text acts as the key letter. Other systems may use some other rule or may not supply any key letter.
  3. The method by which the user activates the menu is system-dependent. If you want to use the same method on all systems, define one or more menu keys in your program. For more information, see the Menu Activation and Use.
  4. Some systems may limit the number of items that appear in the top-level menu. Under the runtime system's own menu handler, the top level is limited to the number of items that can be displayed in one line. Also, a submenu may not have more items than fit in a single column (minus the top line).
  5. If you plan to run the same program under both graphical and character-based systems, remember that the menu bar will occupy space on the terminal. Under graphical systems such as Windows, the menu bar is placed outside of the application's virtual screen. On a character-based screen, the menu bar resides on the top line, thus removing one line from the application.

    ACUCOBOL-GT's Terminal Manager adjusts all the coordinates as needed, but your program will have one less line to work with. Note, however, that you can configure the menu bar to pop up over the top line of the application when the menu is requested by the user. This will result in the full screen being available to your application, although the menu bar will be visible only when the user requests it.

  6. Pop-up menus (which appear in a vertical orientation over the application window and disappear after the user makes a selection) are currently available only under Windows systems. They may be added to other systems in future releases.
Parent topic: Menu Bars and Pop-up Menus


Menu Bar Sample Programs

Two sample COBOL programs called menubar and menubar2 are included on the media sent to you from Micro Focus. We do not recommend either of these routines for use with the current version of the compiler, but we provide them for upward compatibility at sites that have used previous versions of our compiler.

Earlier versions of the compiler came with the sample program menubar that demonstrates how to implement a two-dimensional menu bar in COBOL. The only difference between the menubar program on your media and the original program is that it has been enhanced to support the mouse.

Also included is a variation of the menubar program. This is called menubar2. This variation uses the W$MENU routine to implement its menus. The result is that the menu is implemented by the host if you are running on a graphical system such as Windows. If you desire, you may replace menubar with menubar2. This allows you to convert applications that use menubar to start using graphical menus quickly. menubar2 cannot substitute for all uses of menubar. See the comments in menubar2 for restrictions.

Although these routines are included for compatibility with previous versions of the compiler, we recommend that you avoid using menubar and menubar2 where possible. When you use these programs, the user can select menu items only when the program asks for them. This is the program-driven model of a menu system. Normally, with a graphical user interface, the menus are always active and items can be selected at any time. This is the user-driven menu model. Generally speaking, your users will expect to be able to use the menu at any time. You should try to provide this where possible by using the newest menu features in the compiler

Parent topic: Menu Bars and Pop-up Menus


Color Mapping

  • Overview of Color Choices
  • COLOR_MODEL Settings
  • COLOR_TABLE Settings
  • Additional Color Configuration Variables
  • ActiveX Color Settings
  • Miscellaneous Window Options
Parent topic: ACUCOBOL-GT User Interface Programming


Overview of Color Choices

This section explains what to do if you want your background and foreground color choices to look appropriate in both character-based and graphical environments. The information applies to both black-and-white and multi-color screens.

Many programs written for graphical environments use a white or gray background. This is not the norm for character-based programs. Because of this, chances are good that a character-based application will look out of place when it's run under a graphical environment (such as Microsoft Windows).

You may want to consider using COBOL configuration variables to map your color scheme to a scheme that's more appropriate for a graphical environment. The COBOL program can then remain the same in both types of environments.

With its default settings, ACUCOBOL-GT will display your application using the colors your application specifies. This means your application will look the same whether it's running under a character-based or graphical operating system.

If you want your application to look the same under both types of systems, you don't need to do any color mapping.

However, when an application is moved from a character-based environment to a graphical environment, many developers choose to adjust the color scheme. They do this to match the style of other applications running in the graphical environment. This is especially true if the applications normally use a black background, which would seem out of place in many graphical environments.

You can choose to:

  • change your COBOL code to adjust the colors directly in each environment.
  • make use of any end-user color controls that exist in your application.
  • use one or more ACUCOBOL-GT configuration variables to effect a color remapping. These variables enable you to make global color changes quickly and also give you control over fine details. No changes are needed to the COBOL program itself.

Although ACUCOBOL-GT contains several configuration variables that simplify the mapping of your colors, two in particular are of note. COLOR_MODEL and COLOR_TABLE combine the effects of several variables to give you high-level control over color combinations. The other variables, described in the Additional Color Configuration Variables, permit additional fine-tuning.

COLOR_MODEL affects colors in a global way (for example, exchange foreground and background colors). COLOR_TABLE affects specific color combinations (transform a red foreground on a black background into white on blue).

So if you decide to change any of your colors using configuration variables, you would typically start by adjusting the COLOR_MODEL setting to establish a global color scheme for your program. Then you'd adjust specific colors, if necessary, with the COLOR_TABLE setting.

Using these two variables, you'll probably be able to adjust your application to assume a graphical look with little or no COBOL coding.

Note: On a monochrome monitor the run-time system will display colors as various shades of gray, unless you've set the COBOL configuration variable MONOCHROME to a non-zero value. In that case, the runtime system will use only black and white.
  • Simplified Mapping Approach
  • Controlling the Color Mapping
Parent topic: Color Mapping


Simplified Mapping Approach

The easiest way to start with configuration variables is to try the various COLOR_MODEL settings. If your application is entirely black and white, try all the odd-numbered settings (they affect black and white only), and select the one you like best.

If your program makes use of color, first decide whether or not you like the color portions as they exist in your program. If you do, try the odd-numbered settings to change the black and white portions. If you want to modify your colored portions, try the even-numbered settings.

Note: Automatic transformations of programs that use color usually produce at least one odd-looking color combination. So select a COLOR_MODEL setting that comes close to what you want, and then make specific adjustments using the COLOR_TABLE variable.
Parent topic: Overview of Color Choices


Controlling the Color Mapping

A different approach to color adjustment is to use the COLOR_TABLE facility to do all of your customizations. With this approach, you don't use the COLOR_MODEL setting at all. Instead, you map each foreground-background combination that you use to the desired new combination.

This is usually more work than using the COLOR_MODEL setting, because you must select each color combination individually. However, this approach is straightforward and gives you total control over the colors selected.

The ACUCOBOL-GT debugger uses this technique. When you enter the debugger screen, it saves the current color table and then creates a new one that maps the usual debugger colors to colors more appropriate for a graphical environment. When the debugger restores your application's screen, it also restores your color table.

COLOR_MODEL and COLOR_TABLE are described in the help. It's likely that you can achieve the effects you want with these two variables alone. If you discover that you need additional fine-tuning, see Additional Color Configuration Variables for more information.

Parent topic: Overview of Color Choices


COLOR_MODEL Settings

The runtime system builds color models by using combinations of settings for these three configuration variables:

  • COLOR_TRANS
  • INTENSITY_FLAGS
  • BACKGROUND_INTENSITY

These variables are fully described in Appendix H. Configuration Variables in ACUCOBOL-GT Appendices.

We've combined a few settings of these variables to form ten color models that will suit most situations. For example, COLOR_MODEL 1 is equivalent to this combination: COLOR_TRANS 5, INTENSITY_FLAGS 34, and BACKGROUND_INTENSITY 1.

You can adjust the settings of the three variables individually, whether you use a color model or not. Note that the most recent setting takes precedence.

Use the COLOR_MODEL setting to perform uniform changes to your program's color scheme. These changes are represented by rules that act on your colors. An example of a rule is "exchange the foreground and background colors". You use the COLOR_MODEL setting to change your color scheme in a global way.

There are eleven color models, numbered from 0 to 10. Each of the models performs a particular set of changes.

There are so many possible color schemes, and so many personal preferences, that it's impossible to predict which color model will look best for your application. The quickest way to pick the most suitable model is probably to try each one. To do this, add the line:

COLOR_MODEL     0

to your COBOL configuration file, and then run your program in the Windows environment. Observe the results. Then edit the configuration file to specify color model 1 and run again. You’ll quickly see which model produces the results you want.

The default color model is model 0. It causes no changes to occur to your color scheme. The remaining 10 models are grouped in pairs:

  • The odd-numbered version of each pair transforms only those parts of your program that are entirely black and white. Any character position that contains any color will be left unchanged.
  • The even-numbered version of the pair performs similarly to the odd-numbered version, except that the rules are always applied regardless of color. When selecting a COLOR_MODEL, you can ignore the even-numbered models if you are satisfied with the color portions of your program.

COLOR_MODEL settings 7 and 8 most closely match typical Windows programs.

In the following pages, we give a general description of each model, along with the corresponding component settings, and a picture of the black and white effects caused by the model.

  • COLOR_MODEL Settings 1 and 2
  • COLOR_MODEL Settings 3 and 4
  • COLOR_MODEL Settings 5 and 6
  • COLOR_MODEL Settings 7 and 8
  • COLOR_MODEL Settings 9 and 10
Parent topic: Color Mapping


COLOR_MODEL Settings 1 and 2

COLOR_MODEL settings 1 and 2 cause the default background to be white.

A character's intensity is shown in the foreground, but switched so that high and low intensity are exchanged. This results in the default low intensity being shown as gray-on-white, while high intensity appears as black-on-white. The result is that high-intensity stands out more than low-intensity.

Reverse-video appears as black-on-gray. If you use reverse-video boxed windows, these are good settings if you also want to use the 3D_LINES variable to give your borders a three-dimensional effect.

Equivalent Settings

COLOR_MODEL 1 is equivalent to COLOR_TRANS 5, INTENSITY_FLAGS 34, and BACKGROUND_INTENSITY 1.

COLOR_MODEL 2 is equivalent to COLOR_TRANS 4, INTENSITY_FLAGS 34, and BACKGROUND_INTENSITY 1.

Parent topic: COLOR_MODEL Settings


COLOR_MODEL Settings 3 and 4

COLOR_MODEL settings 3 and 4 are similar to models 1 and 2. The primary difference is in reverse-video, which appears as white-on-gray. Also, background colors are brighter.

For COLOR_MODEL 3, the foreground and background colors are exchanged for each other, but only if they are both black or white. If either the foreground or background contains a color other than black or white, nothing happens. This is equivalent to running the monochrome parts of your program in reverse-video while maintaining the color portions unchanged.

For COLOR_MODEL 4, the foreground and background colors are exchanged for each other, but only if the background is black. This mode insures that you never have a black background.

Equivalent Settings

COLOR_MODEL 3 is equivalent to COLOR_TRANS 3, INTENSITY_FLAGS 34.

COLOR_MODEL 4 is equivalent to COLOR_TRANS 1, INTENSITY_FLAGS 34.

Parent topic: COLOR_MODEL Settings


COLOR_MODEL Settings 5 and 6

COLOR_MODEL settings 5 and 6 create a reverse-video image of your application. Thus, low-intensity white-on-black will appear as black-on-gray, and high-intensity will appear as black-on-white.

These settings cause the intensity to appear in the background instead of the foreground. For applications that have low-intensity legends and high-intensity data fields, this will cause the data fields to be highlighted on the screen.

Equivalent Settings

COLOR_MODEL 5 is equivalent to COLOR_TRANS 1, INTENSITY_FLAGS 129.

COLOR_MODEL 6 is equivalent to COLOR_TRANS 1, INTENSITY_FLAGS 129, BACKGROUND_INTENSITY 2.

Parent topic: COLOR_MODEL Settings


COLOR_MODEL Settings 7 and 8

COLOR_MODEL settings 7 and 8 eliminate intensity altogether. The default colors are shown as black-on-white.

These are the settings that most closely match typical Windows programs. If you combine COLOR_MODEL 7 with the MONOCHROME configuration variable (which causes colors to be ignored), you will have an entirely black-on-white application (except for reverse, which appears as white-on-gray).

Equivalent Settings

COLOR_MODEL 7 is equivalent to COLOR_TRANS 3, INTENSITY_FLAGS 161.

COLOR_MODEL 8 is equivalent to COLOR_TRANS 1, INTENSITY_FLAGS 161.

Parent topic: COLOR_MODEL Settings


COLOR_MODEL Settings 9 and 10

These settings are similar to models 7 and 8, except that the background color will be gray instead of white. This is useful if you want to use 3D_LINES and want to eliminate intensity considerations.

Equivalent Settings

COLOR_MODEL 9 is equivalent to COLOR_TRANS 3, INTENSITY_FLAGS 193.

COLOR_MODEL 10 is equivalent to COLOR_TRANS 1, INTENSITY_FLAGS 193.

Parent topic: COLOR_MODEL Settings


COLOR_TABLE Settings

The COLOR_TABLE setting describes a set of specific changes to make to your color scheme. Instead of acting on all the colors uniformly, the COLOR_TABLE causes transformations of individual color combinations. For example, a COLOR_TABLE entry might cause a red foreground on a black background to be translated to a white foreground on a blue background.

There are four values that need to be set: the foreground and background colors (assigned numbers from 1 to 8) and the foreground and background intensity (high or low). These are the basic color values, without any intensity indicator:

Color | Color value
Black | 1
Blue | 2
Green | 3
Cyan | 4
Red | 5
Magenta | 6
Brown | 7
White | 8

For the color table, we combine intensity and color into a single variable by adding 8 to the color value if high intensity applies. These are the possible values for foreground and background settings:

Color | Color value
low-intensity Black | 1
low-intensity Blue | 2
low-intensity Green | 3
low-intensity Cyan | 4
low-intensity Red | 5
low-intensity Magenta | 6
low-intensity Brown | 7
low-intensity White | 8
high-intensity Black | 9
high-intensity Blue | 10
high-intensity Green | 11
high-intensity Cyan | 12
high-intensity Red | 13
high-intensity Magenta | 14
high-intensity Brown | 15
high-intensity White | 16

With this numbering scheme, you use the COLOR_TABLE variable (or COBOL code) to build a two-dimensional table for background and foreground colors. For example:

Back | Fore | 1 (low Black) | 2 (low Blue) | 3 (low Green) | 4 (low Cyan)
1 |  |  |  |  |
2 |  |  |  |  |
3 |  |  |  |  |
4 |  |  | 3, 6 |  |
– |  |  |  |  |
– |  |  |  |  |

The table maps the colors specified by your program into the actual colors that will appear on the screen. It tells the runtime system which colors to use when the program specifies a particular background-foreground combination.

For example, if the table carried the equivalent of 3, 6 in row 4, column 2, this would mean that a low-intensity Cyan background (row 4) with a low-intensity Blue foreground (column 2) should be mapped to a background of low-intensity Green (3) with a foreground of low-intensity Magenta (6). The value found in each cell in the table represents the final colors to be used.

The values in the table are not actually stored as numbered pairs. They are stored as 8-bit numbers.

Initially, the table is arranged so that no transformations take place. You use the configuration setting COLOR_TABLE to change entries in the table.

Follow the word COLOR_TABLE with the original foreground and background numbers, separated by a comma. Follow these by an equals sign, and then the new foreground and background numbers, again separated by a comma.

For example, to transform the color combination of foreground 5 on background 2 to foreground 13 on background 2, you would use:

COLOR_TABLE   5, 2 = 13, 2

The color table may also be accessed directly by a COBOL program. It has the following definition:

01 w-default-COLOR-TABLE is external.
    03  occurs 16 times
        indexed by background-color.
        05  final-color occurs 16 times
            indexed by foreground-color
            pic x comp-x.

Each table value is an 8-bit number in which the low-order four bits indicate the desired foreground color and the high-order four bits are the background color. Because four bits result in a range of 0 to 15, the colors are stored as one less than their actual value of 1 to 16. Mathematically, the colors are determined by:

Foreground = N(mod 16) + 1

Background = (N/16) + 1

where N is the 8-bit value found in the table.

For example, suppose we wanted to transform a background color of 5 and a foreground color of 14 to be the colors represented by the variables back and fore. The following COMPUTE statement does this, and can serve as a template when you want to accomplish a similar color transformation:

compute final-color(5, 14) =
   (back - 1) * 16 + (fore - 1).

You can also make COLOR_TABLE settings from inside of COBOL by using SET ENVIRONMENT. Using the external table allows you to inquire about current COLOR_TABLE values and allows you to quickly change several values at once (for example, by processing an entire row in a loop).

Parent topic: Color Mapping


Additional Color Configuration Variables

This section describes four additional configuration variables that can be used to determine how colors are displayed. Read this section only if you want to understand the exact effects of the various COLOR_MODEL settings or want to experiment with its component settings. For most sites, COLOR_MODEL and COLOR_TABLE will be adequate for color control.

The four additional configuration variables are:

  • COLOR_TRANS
  • INTENSITY_FLAGS
  • BACKGROUND_INTENSITY
  • FOREGROUND_INTENSITY

For each character position on the screen, ACUCOBOL-GT assigns four values: the foreground color, the background color, the foreground intensity, and the background intensity. Your COBOL application may directly control three of these attributes with various ACCEPT and DISPLAY options. The attributes you control are the foreground and background colors, and the foreground intensity. You do not have direct control of the background intensity from the ACCEPT or DISPLAY verbs.

When the runtime system displays screen data, it performs a series of steps to transform the colors and intensities specified by your program to the actual colors and intensities shown. You can use a variety of configuration options to effect these transformations. By doing so, you can alter the appearance of your program without changing any of the program's code.

In order to explain the available configuration options, we will walk through the steps taken by the run-time system. At each point where an option can affect the results, that option is described.

  • Step 1: Assign Initial Colors
  • Step 2: Assign Initial Attributes
  • Step 3: Transform Colors
  • Step 4: Transform Intensities
Parent topic: Color Mapping


Step 1: Assign Initial Colors

The runtime assigns the initial foreground and background colors as specified by your program. If you use the REVERSE option, the foreground and background colors are exchanged for each other. If the output device is monochrome, then the colors are transformed to black or white at this point.

There are no configuration options that affect this step, except for the MONOCHROME option, which forces the colors to be set to black or white, as if the output device is monochrome. To enable this option, set it to a non-zero value.

Parent topic: Additional Color Configuration Variables


Step 2: Assign Initial Attributes

The runtime selects a background intensity. Because your program does not control this, the runtime relies solely on configuration options to do this. If you do not set any options, the runtime uses a default intensity based on your hardware and operating environment.

You may choose your own intensity by using the BACKGROUND_INTENSITY configuration variable. It can be set to one of the values 0, 1 or 2.

  • When it's set to 0, the runtime uses the default intensity.
  • When it's set to 1, the runtime uses low-intensity.
  • When it's set to 2, the runtime uses high-intensity.

There are two important exceptions:

  • The first is that the runtime always assigns low-intensity to the background if the background color is black. Using high-intensity would cause the background to be dark gray, which tends to make the screen look muddy.
  • The second exception is that many devices do not support a background intensity independent from the foreground intensity (most terminals, for example). If this is the case, the runtime uses a convention of declaring the background intensity to be low-intensity.

After setting the initial background intensity, the runtime selects the initial foreground intensity. If your program specifies an intensity, then that is the intensity used.

If your program uses the default intensity, then the setting of the configuration option FOREGROUND_INTENSITY determines the intensity:

  • If it is set to 1, then the runtime uses low-intensity.
  • Setting it to 2 causes the runtime to use high-intensity.
  • If it is set to 0, then the runtime uses the default intensity for the output device.

If your program specifies a default intensity, the runtime will never assign high-intensity if the foreground is black. As with the background, we do this to prevent a washed-out appearance. There's one exception to this rule. The runtime will assign high-intensity to a black foreground if the output device does not support independent background intensities. In this case, the device will typically show the background in high-intensity and keep the foreground black. Note that if your program explicitly sets high-intensity, then that will be used regardless of the foreground color.

Parent topic: Additional Color Configuration Variables


Step 3: Transform Colors

The configuration variable COLOR_TRANS (described in Appendix H) determines how the initial colors are transformed. It may be set to any of these values:

Value | Description
0 | By default, COLOR_TRANS is set to 0, which causes no transformation.
1 | This mode causes the foreground and background colors to be exchanged for each other. This is equivalent to running the entire program in reverse-video.
2 | This causes white to be exchanged for black and black to be exchanged for white. The foreground and background colors are transformed independently. For example, a green foreground on a black background would turn into a green foreground on a white background. This setting usually has the effect of transforming a black background into white while maintaining the general color scheme of the application.
3 | The foreground and background colors are exchanged for each other, but only if they are both black or white. If either the foreground or background contains a color other than black or white, then nothing happens. This is equivalent to running the monochrome parts of your program in reverse-video while maintaining the color portions unchanged.
4 | The foreground and background colors are exchanged for each other, but only if the background is black. This mode insures that you never have a black background.
5 | If the colors are foreground white and background black, they are exchanged for each other. Otherwise, nothing happens.

Generally speaking, you could use the COLOR_TRANS variable as a starting point in converting an application to appear more natural under a graphical environment such as Windows. Note that if your application is entirely black-and-white, the first three COLOR_TRANS options are essentially identical.

Parent topic: Additional Color Configuration Variables


Step 4: Transform Intensities

Once the colors have been transformed, the runtime system transforms the foreground and background intensities according to the setting of INTENSITY_FLAGS. This option consists of a series of values added together. Except as noted below, these options take effect only if the colors were in some way affected by Step 3 above. In other words, intensity transfer is ignored if Step 3 didn't change your program's colors. The runtime does this to preserve the parts of your program that you left alone in Step 3. The assumption is that you have programmed those parts to behave the way you want.

You may set INTENSITY_FLAGS to a combination of the following values by adding the values together:

Value | Description
1 | This option exchanges the foreground and background intensities for each other. This is useful if you are swapping a black background into the foreground and want to assign the foreground's intensity to the background.
2 | Causes the foreground intensity to be inverted. That is, if the foreground is high-intensity, it becomes low-intensity. Otherwise, it becomes high-intensity. This is useful if you are transforming the background to white and the foreground to black. Setting this will cause your low-intensity foreground to be shown as gray while your high-intensity item will show as black.
4 | Forces the foreground to high-intensity. This will not be applied to a black foreground.
8 | Forces the foreground to low-intensity. This may not be used if 4 is used.
16 | Causes the 4 or 8 setting to be used even if the COLOR_TRANS setting had no effect. This is an override switch that you can use to cause all foreground intensities to be set to high or low.
32 | Forces the background to high-intensity. This will not be applied to a black background.
64 | Forces the background to low-intensity. This may not be used if 32 is used.
128 | Forces the background to high-intensity, but only if it is black. This may be used in conjunction with setting 32 or 64 for special effects.
256 | Causes the 32, 64, or 128 setting to be used even if the COLOR_TRANS setting had no effect.

These transformations are performed in the order listed above.

At this point, the resulting colors and intensities are combined and processed using the COLOR_TABLE map described in COLOR_TABLE. The final result is shown on the screen.

Parent topic: Additional Color Configuration Variables


ActiveX Color Settings

Many ActiveX controls use a special type named OLE_COLOR to represent colors. Methods and properties that accept a color specification of OLE_COLOR type expect that specification to be a number representing an RGB color value. An RGB color value specifies the relative intensity of red, green, and blue in a specific color to be displayed.

The intensities of red, green, and blue are each represented by a number between 0 and 255. These three numbers are combined to form a single OLE_COLOR.

OLE_COLOR is treated internally as a 32-bit integer. The least significant byte is the value representing the red component of the color. The second least significant byte represents the green component, and the third least significant byte represents the blue component.

The following table lists some standard colors and the red, green, and blue values they include:

Color | Red Value | Green Value | Blue Value
Black | 0 | 0 | 0
Blue | 0 | 0 | 255
Green | 0 | 255 | 0
Cyan | 0 | 255 | 255
Red | 255 | 0 | 0
Magenta | 255 | 0 | 255
Yellow | 255 | 255 | 0
White | 255 | 255 | 255

To construct an OLE_COLOR from the red, green, and blue numbers, use the following formula:

OLE_COLOR = red + (green * 256) + (blue * 65536)

or using hexadecimal literals:

OLE_COLOR = red + (green * x#100) + (blue * x#10000)

As a convenience, eight standard colors have been defined in ACTIVEX.DEF.

*Standard OLE_COLOR Values:
78  OLE-BLACK               VALUE X#000000
78  OLE-BLUE                VALUE X#0000FF
78  OLE-GREEN               VALUE X#00FF00
78  OLE-CYAN                VALUE X#00FFFF
78  OLE-RED                 VALUE X#FF0000
78  OLE-MAGENTA             VALUE X#FF00FF
78  OLE-YELLOW              VALUE X#FFFF00
78  OLE-WHITE               VALUE X#FFFFFF
Parent topic: Color Mapping


Miscellaneous Window Options

The help topics in this section describe options available for Windows and Windows NT systems.

  • Background Brush Color
  • Drawing 3-D Lines
Parent topic: Color Mapping


Background Brush Color

The Windows and Windows NT environments use a "background brush" when they resize a window. By default, the background brush color for ACUCOBOL-GT is black. If you have arranged your default background to be white, you will see a black flash when you resize the window. This does not affect the final appearance of the window, but is briefly noticeable while the window is being redrawn.

If you desire, you can set the configuration variable WHITE_FILL to 1 to cause ACUCOBOL-GT's background brush to be set to white instead. Doing this will also cause the initial screen that ACUCOBOL-GT paints to be white instead of black.

Note: This variable must be set in the configuration file to be effective. Modifying this variable with the SET ENVIRONMENT verb has no effect.
Parent topic: Miscellaneous Window Options


Drawing 3-D Lines

In the Windows environment, you may set the configuration variable 3D_LINES to 1 to cause the run-time system to display lines and boxes with 3-D shading. This makes the lines appear to be inscribed into the surface of the screen. Only black lines on a non-black background are shown with shading. Other lines are displayed normally.

The set of colors available to ACUCOBOL-GT significantly impacts how effective the shading will be. Normally, the shading is most effective when the background is low-intensity white. The other low-intensity colors are next best.

The shading is only marginally effective with a high-intensity background. For this reason, the 3D_LINES setting is not used when a high-intensity background is drawn. Note that, by default, ACUCOBOL-GT shows background colors in high intensity, so you will need to use at least one other configuration variable to arrange for a low-intensity background color. For example, the BACKGROUND_INTENSITY variable could be set to 1 to force a low-intensity background.

Under Windows and Windows NT, you may freely change the way lines are displayed in COBOL by using the SET ENVIRONMENT verb to set 3D_LINES, prior to displaying a line or a box:

  • Setting it to 1 gives you the 3-D effect
  • Setting it to zero gives you normal lines

The runtime system remembers which lines are drawn with 3-D, so you don't need to keep track of this yourself. Note, however, that if you attach a 3-D line to a non-3-D line, the intersection will use the 3D_LINES setting currently in effect.

Parent topic: Miscellaneous Window Options


Help Automation

  • Introduction to Help Automation
  • HELP-ID
  • Help Modes
  • The Help Processor
  • Windows Help
Parent topic: ACUCOBOL-GT User Interface Programming


Introduction to Help Automation

Help automation is the name given to the set of constructs and methods included in ACUCOBOL-GT to support context-sensitive help in your application. This section describes these constructs and methods. Many applications provide on-line help information in a way that is sensitive to the application's context. Context-sensitive help responds to a particular screen or control that the user clicks on or otherwise identifies.

Help automation is the mechanism that takes care of informing the help processor that help is needed for a particular item or context. The help processor is a program or subroutine that performs the task of delivering the help content to the user.

In ACUCOBOL-GT, the help automation mechanism consists of:

  • A HELP-ID that identifies context-sensitive elements in the program
  • Two help modes with corresponding exception values that give the user two methods for initiating context-sensitive help
  • Automated run-time support for detecting and passing requests for context-sensitive help to the help processor
Parent topic: Help Automation


HELP-ID

Help automation support is based on the concept of a help ID. A help ID is a special integer value assigned to a control. When a help request is sent to the help processor, the help ID of the associated control is sent as a parameter.

Typically, each control is assigned a unique value. This allows the help processor to uniquely respond to each control. To create help that responds to the window, rather than an individual control within it, you can give all of the controls within a window the same help ID. Or you can mix the two approaches by giving some individual controls unique help IDs, while the remaining controls get a shared help ID. Because help IDs are associated with controls, you cannot use help automation with character-based (textual) ACCEPT fields.

Whether the control is defined in the Screen Section or in a DISPLAY statement, help IDs are assigned with the HELP-ID phrase. You can easily assign a screen-wide help ID to a window by specifying a HELP-ID for the top-level group item in the Screen Section description. You can override the screen-wide ID for a specific control by including the HELP-ID phrase in that control's definition.

Parent topic: Help Automation


Help Modes

After setting up the help IDs, you'll need to decide which help modes to use and how each mode will be presented to the user. The help mode describes the user interface method that the user uses to initiate a context-sensitive help request. The runtime supports two help modes: item help and help cursor.

The item help mode uses a predefined key or button to send an immediate request for help for the active control or screen. When the user clicks on the item help button or presses the item help key, the help ID of the active control is immediately passed to the help processor.

The help cursor mode uses a predefined key (distinct from the item help key) to initiate a special mode for selecting the item for which information is wanted. Pressing the help cursor key or button usually changes the cursor to a question mark that the user positions over the screen item in question and then clicks. The mouse pointer then reverts to normal and the help information for that item is displayed. Should the user click on an object that doesn't have a help ID, the cursor reverts to normal and nothing else happens.

To make the help modes work, you must assign each mode an exception value. This is done with the Format 13 SET statement. After the exception values are assigned, any control, menu item, or key that produces the specified exception value will produce the associated help action. For example, the Microsoft Windows design guidelines recommend that F1 produce help for the active item (item help), and that Shift F1 produce a help cursor. To implement those guidelines, you would use the following statement (assuming the default keyboard configuration):

SET EXCEPTION VALUES 1 TO ITEM-HELP, 11 TO HELP-CURSOR.

The preceding statement reflects the fact that in the default keyboard configuration F1 produces an exception value of 1, while Shift F1 produces an exception value of 11.

After the exception values are assigned, you can create menu items or push buttons that produce item help or help cursor by assigning those items an exception value of 1 or 11. It is important that item help and help cursor push buttons be self activating (SELF-ACT style). If they are not, the effect is that clicking on them will transfer control to the button. This is annoying in the case of help cursor, and useless in the case of item help (the help request would always pass the help ID of the help button).

Parent topic: Help Automation


The Help Processor

The last step in setting up help automation is to define the name of the help processor program. Note that the help processor's entry point is always a COBOL program. The program can be the help processor itself, or a shell to some other help processor, such as Windows Help. The help processor is named by the value of the configuration variable HELP_PROGRAM. If HELP_PROGRAM is undefined, the runtime uses the name AcuHelp.

Calls to the help processor are handled by the run-time using the normal CALL mechanism. Regardless of the outcome of the CALL, when the CALL to the help processor completes, the run-time returns to the current control and continues normal operation.

The help processor is passed only one parameter, the EVENT STATUS data item. It contains the CMD-HELP event that generated the CALL. The CMD-HELP event contains all of the information needed to process the help request: the control's handle, its ID, its help ID (in EVENT-DATA-2) and the handle of its owning window. In the case of HELP-CURSOR, you can get the coordinates of the mouse when it was clicked on the control by calling W$MOUSE wth GET-MOUSE-STATUS before you do any ACCEPTs. Note that the position returned is relative to the control's owning window.

Parent topic: Help Automation


Windows Help

If your target platform is Windows, the obvious help processor to use is Windows Help. You can access Windows Help through the $WINHELP library routine. Note however, that $WINHELP is not supported in Microsoft Windows Vista. $WINHELP takes an OP-CODE parameter that indicates the operation to perform. These codes are defined in the COPY library winhelp.def. For context-sensitive help, the two most useful op-codes are HELP-CONTEXT (value 1) and HELP-CONTEXTPOPUP (value 8). In both cases, a context ID is passed as the last parameter to $WINHELP. Typically, you would use the control's help ID as the context ID.

$WINHELP's HELP-CONTEXT operation starts Windows Help in a separate window and positions the user at the topic identified by the context ID. The user is then free to navigate through the help text at will. The HELP-CONTEXTPOPUP operation causes Windows Help to pop-up a small window over the application that contains the topic identified by the context ID. The window is removed as soon as the user types a key or clicks the mouse.

Preparing your application to use Windows Help requires several steps.

In order to use Windows Help you must have a Windows compatible help compiler to produce your help files. ACUCOBOL-GT does not come with a help compiler and does not include documentation on the construction of help files. A help compiler is included with most Microsoft language products. Third-party help compilers are also available. If this is your first effort to interface to Windows Help, be sure to carefully read the documentation that comes with your Windows help compiler.

The help compiler takes two files as input: the help text source and the help project file. It produces .HLP format help files that are used by Windows Help. The help text source is a rich-text format (.RTF) file that contains a marked-up form of the help text. The markings describe the various sections of the help file, their look, and how they are cross-referenced. The help project file (.HPJ) is a text file that contains project-specific instructions to the help compiler. For information about how to create and use these files, refer to your help compiler documentation.

  • Mapping Context IDs
Parent topic: Help Automation


Mapping Context IDs

Because of an inconsistency in the representation of the context ID value between the Windows Help program and the WinHelp API function, some special work is required. In Windows Help, context IDs are strings. These strings are placed in the help source as footnotes using the # character as the footnote symbol. However, the Windows Help API function (WinHelp) does not accept a string for the context ID parameter. Instead, it requires a number. Fortunately, there is a simple mechanism for translating numbers into context IDs. This is done in the [MAP] section of the help project (.HPJ) file. In the MAP section, you should include entries that map the context string to a context number, like this:

#define   ContextIdName   ContextNumber

For example, if you had a section called Help_CustName in your help file, and you wanted to assign the corresponding ID value 1000, you would use:

#define   Help_CustName   1000

In your COBOL program, you could then assign a HELP-ID of 1000 to your customer name entry field to provide a context link to the appropriate section in the help file.

Because mapping names to numbers on a large scale is prone to error, ACUCOBOL-GT provides a mechanism to simplify the process. We suggest the following approach:

  1. Create a COPY library for each of your help files. Each COPY library should contain all of the context IDs for its associated help file. Typically, one help file services all the programs in an application, but it's possible to organize help files differently.
  2. Whenever you need a new context ID, add a level 78 to the COPY library. The name should be the same as the section name in the help file. Assign a unique number to the entry. You can either number context IDs sequentially, or you can devise your own scheme. To add an entry for the customer name example above, you would add the following line:
    78  Help-CustName   VALUE 1000.
    Note: Context names are not case-sensitive in either COBOL or the help file.
  3. In your COBOL program, include the COPY library and use its level 78 names as HELP-IDs. For example, this statement could be used in a Screen Section entry:
    ENTRY-FIELD USING CUSTOMER-NAME,
HELP-ID = Help-CustName
  4. In your help file text (.RTF file), create a section with the same name as the level 78 entry, followed by its associated help text. When creating section names, be aware that any hyphens in a COBOL name will be converted to underscores in the help file. Therefore, in the preceding example, you would add a section called Help_CustName to your help file.
  5. Compile the program source with the -defines switch to create a file containing #defines that correspond to your level 78s. For example, if the COPY library created in step (1) is called applhelp.def, you would use:
    ccbl -defines applhelp.def

    By default, this creates the file applhelp.h that contains one #define for each level 78 in applhelp.def. Note that any hyphens in the level 78 names are converted to underscores in the corresponding #define. This occurs because the #defines can be used in C programs as well as with help files, and hyphens are not allowed in C names (they are allowed in COBOL and the help file).

  6. In your help project file (.HPJ), include a [MAP] section and add an #include statement that references the .h file created in step (5). For example:
    [MAP]
#include <applhelp.h>

Your help files are now ready for the help compiler. Use your help compiler to create an .HLP file from your help text source and help project files.

For a complete working example, see the help demonstration program included with the Windows versions of ACUCOBOL-GT. The example program and its related files can be found in the sample > help subdirectory of your ACUCOBOL-GT installation.

Parent topic: Windows Help


Tips and Hints

  • Regarding Windows
  • Regarding Controls
  • Regarding Fonts
  • Regarding Configuration Variables
  • Regarding Debugging
Parent topic: ACUCOBOL-GT User Interface Programming


Regarding Windows

Question:

When I click the mouse outside the area of my floating window, the runtime doesn't return any event to my program. Why?

Answer:

This is normal behavior under Windows. Windows delivers the mouse message to the top-most window in which the mouse is located. If the mouse isn't clicked within the floating window, it never receives any indication that a mouse event occurred. The only way to receive such events is to capture the mouse, but that prevents the mouse from being used by any other application. Ordinarily, the mouse should be captured only when the user is marking or dragging some object on the screen.

Question:

How can I trap the CMD-CLOSE event when the user closes the application by selecting the Close option of the System Menu? I need to be able to close files and perform an orderly shutdown.

Answer:

Look at the QUIT-MODE runtime configuration variable. QUIT_MODE allows you to handle this event in a program-defined way, or in a variety of pre-defined ways.

Question:

I don't see any references to Dialog Boxes. How do I build one?

Answer:

Under ACUCOBOL-GT, a Dialog Box is simply a floating window. You can specify many options when creating the window, but the basic Dialog Box is declared with:

DISPLAY FLOATING WINDOW,
   LINES height, SIZE width,
   BOXED, HANDLE IN handle-data-item

Common additions include a TITLE and SYSTEM MENU. You can then populate the Dialog Box with DISPLAY control-type statements. Or a better alternative is to define a Screen Section group item that describes all the Dialog Box contents and then just DISPLAY that group item.

Question:

Which of the Windows Common Dialog Boxes can I create directly from ACUCOBOL-GT?

Answer:

Five are available via ACUCOBOL-GT library routines. The ChooseColor dialog box can be found in W$PALETTE. The PrintDialog setup box is available in WIN$PRINTER. The file Open and Save-as dialog boxes are available in C$OPENSAVEBOX. W$FONT has the ChooseFont dialog box. Other Windows Common Dialogs are not directly available, though they can be accessed indirectly through C.

Question:

How do I handle a dialog box that doesn't have any entry fields, for example a dialog box with only push buttons?

Answer:

All controls are handled in the same general fashion. This means that you can ACCEPT a push button just as you do an entry field. Push buttons are a little strange in that they don't have values, but they do provide a termination value, just as regular fields. The following is sample code for a simple dialog box that prompts for verification before terminating the application. The line and column numbers may need to be adjusted to improve appearance.

*Screen section
01 shutdown-screen.
   03 label  "This will end your application",
      line 2, column 3.
   03 push-button, ok-button, line 4, column 10.
   03 push-button, cancel-button, column 20.
*Procedure Division
display floating window,
   size 30, lines 5,
   title "Application Shutdown",
   handle in shutdown-window.
display shutdown-screen.
perform, with test after,
      until key-status = 13 or 27
   accept shutdown-screen
     on exception key-status continue end-accept
end perform.
destroy shutdown-window.
if key-status = 13
   perform shutdown-windows.

Question:

I'd like to minimize my COBOL application when I switch tasks, but a child window is open, and I can't access the minimize button of the main application window. Why?

Answer:

The child window is a modal window. As long as a modal window is open, you cannot get to any other application window. To minimize the application, you must first close all child windows.

If the current window were a modeless window, you could switch to a different window without closing the first one. ACUCOBOL-GT Version 3.2 and later supports the creation of modeless windows.

Question:

I want to create a toolbar large enough to host bitmap buttons that are 36 pixels square. How do I do that?

Answer:

All you need to do to is to create a toolbar window that is tall enough to handle 36 pixels (or any height you want). When you create the bitmap buttons, be sure to specify the exact size of your buttons. For example, to handle 36-pixel square bitmap buttons, try creating a toolbar four lines high. Remember, you can use fractional line values to create a toolbar that is exactly the height you want. See Procedure Division Statements and Bitmap Buttons for more information about toolbars and bitmap buttons.

Parent topic: Tips and Hints


Regarding Controls

Question:

I have a window in which I've placed a number of SELF-ACT style radio buttons. When one of those buttons is clicked, I see the button flash but the previous control remains selected. What's going on?

Answer:

What you're seeing is correct, if confusing, behavior. Self-activating buttons have two traits: they don't generate CMD-GOTO events, and once the user is finished with them they reactivate the previously active control. In this case, clicking on the radio button turns it on and also completes the use, causing control to be returned to the previously selected radio button, turning off the button that was clicked. All this happens in a flash. The bottom line is, don't make radio buttons self-activating if you plan to ACCEPT them directly.

Question:

I have defined a TERMINATION-VALUE (or EXCEPTION-VALUE) for my push button. When I click on it, I get a status 96 instead of the value I have assigned. Is this a bug?

Answer:

What you are seeing is correct behavior. When you click on a push button with the mouse, two actions take place. First, when you press the mouse button down, the push button requests that the program activate it. It does this by generating a CMD-GOTO event, which is the status 96 that you are seeing. After it gains control, it waits for you to release the mouse button. At this point, the push button generates the termination or exception value that you have assigned to it. Although we talk about pushing a button, in reality, it is the act of releasing the button that is important. You can see this by running any Windows application and pushing a button down with the mouse. As long as you hold the mouse button down, nothing happens other than the push button appearing depressed and gaining the input focus. Once you release the mouse button, the program action associated with the push button takes place.

If you are using push buttons in a Screen Section entry, you usually don't see the CMD-GOTO events because the Screen Section handler responds to these events for you (although you can detect them in AFTER procedures and EVENT procedures). When you are managing the activation of controls directly in your program, it is your responsibility to detect these events and activate the appropriate controls.

Another possibility is to use the SELF-ACT style of push button. This style tells the button to automatically activate itself when pushed. It does not generate CMD-GOTO events.

Question:

I asked for a FRAME that was 20 characters wide. When I use the WIN3-GRID option, I can see that it is nowhere near that size. What's happening?

Answer:

Frames, like other controls, are normally measured in terms of their font. In the case of a frame, the font is the frame's title font (even if the frame is not given a title, it still has a title font). A frame of size 20 is a frame that is 20 title-font-characters wide. What the WIN3-GRID option shows you is the size of each character cell in the window. A window's character cell is normally the same as the size of its text font. If the window's text font and the frame's title font are not the same, a frame of size 20 will not occupy 20 character cells.

You can address this issue in one of four ways:

  1. You can use the CELLS option when specifying the frame's size (for example, SIZE 20 CELLS). This causes the frame to be measured using the window's cell size
  2. You can change the dimensions of the window's cell size to match the frame's title font (by using the CELL SIZE phrase when you create the window)
  3. You can make the frame's font and the window's text font the same
  4. You can use the PIXELS option when specifying the frame's size (for example, SIZE 200 PIXELS). This causes the frame to be measured using the screen's pixel size, and the resulting frame's size is unrelated to either the frame's title font or the window's text font.

Question:

How many items can I put in a standard list box or combo box?

Answer:

List box text limits are based on machine memory, which essentially equates to no limit.

A paged list box can handle an unlimited number of items. For more information, see Paged List Boxes.

Question:

When the runtime is putting data into a standard list box or combo box defined in the Screen Section, the last data item gets repeated. How do I prevent this?

Answer:

You need to move spaces to your ITEM-TO-ADD data item after you have finished filling the list box or combo box. Otherwise, the last data item it contains will be added to the box every time you DISPLAY that Screen Section box, or any of its parent group items.

Question:

When I use a property in a MODIFY statement, I get the compiler error Undefined data item: property-name. I know the property is the right one. Why do I get an error?

Answer:

The handle that you are specifying in the MODIFY statement is a generic handle (that is, USAGE HANDLE instead of USAGE HANDLE OF type). The compiler does not recognize style and property names when you reference a generic handle, because it does not know which set of names to use. To rectify this problem, declare the handle as a handle to the appropriate control type.

Question:

ACCEPT FROM SCREEN doesn't return anything!

Answer:

ACCEPT FROM SCREEN returns classical text-based fields, but not controls or the contents of controls (including entry fields). In other words, it reads the terminal emulator plane of the screen, but not the graphical plane. To determine the current contents of a control, use the INQUIRE verb.

Parent topic: Tips and Hints


Regarding Fonts

Question:

How can I select one of my system's custom fonts?

Answer:

Use the W$FONT library routine.

Parent topic: Tips and Hints


Regarding Configuration Variables

Question:

In the programs I developed with Version 2.3 and 2.4, I used the configuration variable MOUSE-FLAGS to detect certain mouse events. After updating my screens to include graphical controls, I notice that the double-clicked events that I used to get in my entry fields are no longer generated. What's going on?

Answer:

MOUSE-FLAGS does not detect any event that takes place over a control. Mouse events that take place over a control are handled differently than mouse events that interact with text-based screen items. The mouse, when positioned over a control, is owned by the control. All mouse events that take place over the control are sent directly to and handled by the control. List-box controls are the only controls that pass double-click events back to the program. To detect a double-click in a list box, check for CMD-DBLCLICK in EVENT-STATUS.

Question:

In my configuration file I have a KEYSTROKE entry that defines carriage return (^M) to have both a termination and exception value of 13. It also defines edit=next so that a carriage return also moves the cursor to the next field. But when I have a screen that includes an OK button and a carriage return is pressed, the screen terminates and the cursor is not moved to the next field.

Answer:

This is the correct behavior. Remember that the OK button style also implies the DEFAULT button style. The DEFAULT button style has the effect of acting as if it is pushed whenever a key with the value of 13 is pressed.

Question:

A program running in UNIX with the configuration variable KEYSTROKE EDIT=Next terminate=17 kr and KEYSTROKE EDIT=Previous terminate=17 kl can return to the previous field or advance to the next field when the <left arrow> or <right arrow> keys are pressed, but when the program is running in Windows these keys do not work.

Answer:

This is the correct behavior. When using controls, the host GUI determines the meaning of any editing keys in the control itself. For our own simulated GUI, we allow you to define the editing functions using the KEYSTROKE entries. For other systems (such as Windows), the host determines how keys are used. In the case of Windows, the left and right arrow keys move the cursor but do not act as terminators.

While the run-time does allow you to configure which keys are terminating keys (even for Windows), it cannot force the host GUI into a mixed mode where a key is sometimes an editing key and sometimes a terminating key.

Question:

With the KEYSTROKE configuration variable I redefine the menu activation key. The redefinition works fine under UNIX but doesn't under Windows. Why?

Answer:

Windows' menu activation keys are not configurable. The only keys available are the ones defined by Microsoft. The menu activation key under Windows is F10.

Question:

In many of my character-based applications I use BLINK to highlight some text. Why is it that when I run those applications under Windows, the text doesn't blink?

Answer:

BLINK isn't supported under Windows.

Parent topic: Tips and Hints


Regarding Debugging

Question:

When I'm debugging and I can't get to the System Menu, how can I set a break?

Answer:

You can directly request a break to the debugger by typing Ctl-Break. The break will occur as soon as the current ACCEPT statement terminates. If the program is not currently processing an ACCEPT statement, the break will occur after the current statement terminates. This provides a method of dynamically breaking to the debugger when you cannot get to the system menu (for example, when you are in a floating window).

Parent topic: Tips and Hints


UI Terminology

  • active window
  • ActiveX
  • ActiveX control
  • application window
  • bar
  • bitmap
  • border
  • buttons
  • character-based display
  • check box
  • child window
  • client area
  • close box
  • combo box
  • control
  • control border
  • control type
  • current window
  • cursor
  • data entry field
  • desktop
  • dialog box
  • display area
  • document window
  • drop-down list box
  • entry field
  • event
  • event-driven
  • floating window
  • frame
  • Graphical User Interface System (GUI System)
  • grid
  • group box
  • hot spot
  • icon
  • initial window
  • label
  • list box
  • main application window
  • menu bar
  • message box
  • method
  • minimize/maximize buttons
  • mnemonic keys
  • modal window
  • modeless window
  • multi-line entry field
  • parent window
  • pointer
  • pointing device
  • pop-up menu
  • pop-up window
  • pull-down menu
  • push button
  • radio button
  • screen
  • scroll bar
  • selection box
  • static text field
  • subwindow
  • system menu
  • tab
  • text box
  • thread
  • title
  • title bar
  • toolbar
  • widget
  • window
  • window frame
Parent topic: ACUCOBOL-GT User Interface Programming


active window

The window that is receiving the user's input. The window controlled by the user and associated with the current ACCEPT statement. Only one window can be active at a time. On most systems, the active window is visually highlighted. A window is made active by any of the following actions:
  • (a) when it is created
  • (b) when the program does an ACCEPT of a control in the window
  • (c) by some forms of the Format 10 SET statement
  • (d) when the user clicks on a modeless window.
See also current window.
Parent topic: UI Terminology


ActiveX

A component model originally developed by Microsoft to standardize the way that application components and services behave. Today, most component-based technologies are assigned the label ActiveX.
Parent topic: UI Terminology


ActiveX control

An ActiveX control is an Component Object Model (COM) object that performs a well-defined function, usually involving a graphical user interface. ActiveX controls subscribe to the ActiveX component model originally developed by Microsoft. As such, they behave in a manner that developers can predict, they are reusable, and they are toolable. Pre-programmed controls (such as calendars, clocks, and gauges) are sold by third-party vendors along with the licensing rights to use them in your Windows application. By supporting ActiveX controls, ACUCOBOL-GT allows you to take advantage of existing software functionality, as well as create applications that conform to the Windows standard.
Parent topic: UI Terminology


application window

See main application window.
Parent topic: UI Terminology


bar

A control that draws a line on the screen.
Parent topic: UI Terminology


bitmap

A control that allows you to place an animated bitmap on the screen.
Parent topic: UI Terminology


border

The box forming the outermost edge of the window or control. Border types include thin, thick, and shadowed (3D border).
Parent topic: UI Terminology


buttons

A class of controls used for yes/no, on/off choices (push button, radio button, check box).
Parent topic: UI Terminology


character-based display

A video mode that displays only full characters such as those defined by the ASCII or EBCDIC character sets.
Parent topic: UI Terminology


check box

A control having a box which the user clicks on to select an on or off state. An X or check-mark appears in the box when the item is selected.
Parent topic: UI Terminology


child window

A window created by the currently active window (its parent). If the parent window is closed (destroyed), the child is also closed.
Parent topic: UI Terminology


client area

The area of the window inside the borders, menu bar, toolbar, and title bar. synonym: display area
Parent topic: UI Terminology


close box

See system menu.
Parent topic: UI Terminology


combo box

An entry field with an attached list or drop-down list. The user can select an entry from the list, or directly enter a value. synonym: combination box
Parent topic: UI Terminology


control

A graphical screen object with a dedicated input or output function, such as a push button, check box, or entry field. synonym: widget
Parent topic: UI Terminology


control border

See border.
Parent topic: UI Terminology


control type

A classification that specifies a control's properties. Each control type has a set of common and special properties. synonym: control class
Parent topic: UI Terminology


current window

The output window. The window currently being acted on by the program, usually the same as the active window (the window accepting input), but it can be different, temporarily, via use of the UPON phrase. See active window.
Parent topic: UI Terminology


cursor

The insertion point in a text field. The cursor is typically shown as a blinking vertical bar (I-beam).
Parent topic: UI Terminology


data entry field

See entry field.
Parent topic: UI Terminology


desktop

The screen background on top of which windows and icons are displayed.
Parent topic: UI Terminology


dialog box

A modal or modeless window used to supply information or elicit input. Frequently used to get user preferences and confirm program actions.
Parent topic: UI Terminology


display area

See client area.
Parent topic: UI Terminology


document window

A type of window used by the application to support and manage multiple open documents, or multiple views of an open document (such as a spreadsheet or a picture). Not currently supported in ACUCOBOL-GT.
Parent topic: UI Terminology


drop-down list box

A selection box with a drop-down list.
Parent topic: UI Terminology


entry field

A boxed field into which text is entered. If present, the current entry is highlighted and the user can select, delete, or edit up to the maximum length of the field. synonym: entry box, text box, edit box
Parent topic: UI Terminology


event

A transitory action, such as a mouse movement, menu selection, or data entry.
Parent topic: UI Terminology


event-driven

A system in which programs respond to events (actions) initiated by the user or system.
Parent topic: UI Terminology


floating window

A host-based, pop-up window that displays over its parent window. It can be moved independent of its parent.
Parent topic: UI Terminology


frame

A box used to visually group items. A frame can have a label. In Microsoft Windows, frames are called group boxes. Frames can have a variety of border types: normal, heavy and various three dimensional effects.
Parent topic: UI Terminology


Graphical User Interface System (GUI System)

An operating system or layer over the operating system that has as its principal feature the graphical display and control of the application user interface. The GUI system may provide other important operating system functions, but graphical representation and control is central. synonym: GUI Environment, Windowing System.
Parent topic: UI Terminology


grid

A two-dimensional table of data fields. Each element of this table, called a cell, can hold either text or a bitmap, or both. Grids are relatively complex controls with many properties that you can use to customize their appearance and behavior.
Parent topic: UI Terminology


group box

See frame.
Parent topic: UI Terminology


hot spot

The area on or around a display object (such as text, a button, or an icon) that is affected by a mouse action.
Parent topic: UI Terminology


icon

A small bitmapped graphic image variously used to represent the application or as a button label.
Parent topic: UI Terminology


initial window

See main application window.
Parent topic: UI Terminology


label

A static text item. Labels are used to place text next to an entry field, or anywhere it is needed. synonym: static text
Parent topic: UI Terminology


list box

An input field that displays a list of options for the user to choose from. The list box usually highlights the current selection.
Parent topic: UI Terminology


main application window

The primary window of the application, usually including the application’s main menu bar and title bar displaying the application’s name.
Parent topic: UI Terminology


menu bar

The labels usually located below the title bar that provide access to the application's pull down menus. Standard menu bar items include the File, Edit, and Help menus.
Parent topic: UI Terminology


message box

A modal window used to display error and system messages. The message box may be supplied as a specialized service of the GUI system.
Parent topic: UI Terminology


method

An ActiveX term. Methods (or object methods) specify the functions that an ActiveX control provides. They are invoked using the MODIFY verb, and they can take any number of parameters or no parameters. They can also take optional parameters (i.e., parameters that can be omitted) and can return values (with the GIVING phrase.
Parent topic: UI Terminology


minimize/maximize buttons

Small buttons, usually located in the upper right corner of the window's title bar (optional feature). When activated, these buttons reduce the window to an icon or enlarge the window to its largest supported size, respectively.
Parent topic: UI Terminology


mnemonic keys

The underlined letter on menu entries which, when accessed with a special key combination from the keyboard, activates that menu item.
Parent topic: UI Terminology


modal window

A window that, when active, prevents the user from activating any other window.
Parent topic: UI Terminology


modeless window

A window that, when active, allows the user to activate another window via a system-dependent technique (for example, clicking the window with the mouse).
Parent topic: UI Terminology


multi-line entry field

A large entry field displayed as multiple lines. synonym: multi-line edit box
Parent topic: UI Terminology


parent window

The current window when a new window is created. When the parent window is closed, all associated child windows are also closed. See child window.
Parent topic: UI Terminology


pointer

The arrow (or other shape) that is moved by such things as the mouse, trackball, or joystick to navigate the screen.
Parent topic: UI Terminology


pointing device

The mouse, trackball, stylist, or other device manipulated by the user to move the pointer and make selections on the screen.
Parent topic: UI Terminology


pop-up menu

A menu which is displayed when the user positions the mouse over an object with a pop-up menu and clicks or activates the menu with the keyboard. The menu pops up over the current window.
Parent topic: UI Terminology


pop-up window

Any window created by the program that pops up over the current window. Prior to Version 3.0, the term pop-up window was sometimes used to refer to windows created with the DISPLAY WINDOW statement (these windows are now known as subwindows). See also modal window and modeless window.
Parent topic: UI Terminology


pull-down menu

The list of menu options displayed when an option on the main menu bar is activated by the pointer or keyboard. Menu options are displayed in a vertical list that may have horizontal dividers and links to submenus.
Parent topic: UI Terminology


push button

A rectangular area with text or a graphic that describes the action performed by the button. synonym: command button
Parent topic: UI Terminology


radio button

A set of two or more buttons used to present mutually exclusive options. When one button is selected, all other buttons are made to appear empty (like an old fashion car radio - when a button is pushed in, the previously pushed button pops out). synonym: option button
Parent topic: UI Terminology


screen

The entire video display space.
Parent topic: UI Terminology


scroll bar

A bar with a slider box and arrow boxes at each end. Scroll bars are attached to a window when the size of the data exceeds the window's display area. A window can have vertical or horizontal scroll bars, or both.
Parent topic: UI Terminology


selection box

See list box.
Parent topic: UI Terminology


static text field

See label.
Parent topic: UI Terminology


subwindow

The traditional ACUCOBOL-85, text-based pop-up window. The name subwindow was introduced in ACUCOBOL-GT Version 3.0.
Parent topic: UI Terminology


system menu

An optional drop down menu, usually located in the left corner of the title bar, reserved for special control of the active window. The system menu usually includes options such as: Restore, Move, Size, Minimize, Maximize, Close, and Switch To. synonym: close box, control menu
Parent topic: UI Terminology


tab

A control that combines a box with a tab, resulting in a screen element that looks like a file folder.
Parent topic: UI Terminology


text box

See entry field.
Parent topic: UI Terminology


thread

An execution path through your program.
Parent topic: UI Terminology


title

The text label that is displayed in the window's title bar. Also a common property of all control types.
Parent topic: UI Terminology


title bar

The bar, usually at the top of the window, that includes a text label (title) and, optionally, a system menu (left corner) and minimize and maximize buttons (right corner).
Parent topic: UI Terminology


toolbar

A row of icon buttons used to perform or initiate program tasks.
Parent topic: UI Terminology


widget

A synonym for control.
Parent topic: UI Terminology


window

The framed rectangular display space that typically includes a combination of interface devices such as menus, controls, and scroll bars.
Parent topic: UI Terminology


window frame

The border around a window. See border.
Parent topic: UI Terminology


ACUCOBOL-GT Reference Manual

  • Introduction
  • Program Structure
  • Identification Division
  • Environment Division
  • Data Division
  • Procedure Division
Parent topic: ACUCOBOL-GT Version 10.2.0 Documentation Set


Introduction

  • Overview of Reference Manual
  • Conventions
  • Acknowledgment
Parent topic: ACUCOBOL-GT Reference Manual


Overview of Reference Manual

ACUCOBOL-GT® is part of the extend® family of ACUCOBOL-GT solutions. ACUCOBOL-GT is an implementation of the COBOL-1985 programming language (ANSI X3.23-1985 and the ANSI X3.23a-1989 supplement). This manual provides a full technical description of the ACUCOBOL-GT language. It is written in a style similar to the official ANSI definition of COBOL and is designed for experienced COBOL programmers. Intended as a reference, it does not try to teach programming or the COBOL language. Readers interested in a more general introduction to COBOL may want to consider classes or commercially available textbooks.

Note: Software installation instructions are located in a separate Getting Started guide.
Parent topic: Introduction


Conventions

This manual uses a meta-language to describe the ACUCOBOL-GT syntax. This meta-language follows the conventions used in most COBOL manuals as well as the ANSI standard. These conventions are described below.

References to Windows in this manual denote any of the supported Windows platforms, which are listed in the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx. Where it is necessary to make a distinction, the specific version name/number is specified.

  • Upper-case and Special-character Words
  • Lower-case Words
  • Brackets Braces and Vertical Bars
  • Ellipses
  • Shading
Parent topic: Introduction


Upper-case and Special-character Words

Underlined upper-case words are keywords. A keyword is required when it is encountered in the syntax. The following special characters are not underlined but are required when they appear:

  • +
  • -
  • <
  • >
  • *
  • /
  • **
  • <=
  • >=
  • =
  • :
  • .

Upper-case words that are not underlined are optional. They serve only to improve the readability of the source program.

Parent topic: Conventions


Lower-case Words

Lower-case words serve as generic items. They can indicate COBOL variables, literals, PICTURE elements, or other syntactical elements.

Parent topic: Conventions


Brackets Braces and Vertical Bars

Brackets ( [ ] ) enclose optional elements. When several bracketed entries are stacked vertically, you can select one (but not more than one) of these entries.

Braces ( { } ) indicate that you must select one (but not more than one) of the enclosed vertically stacked entries. If only one entry appears, the braces serve as delimiters for repetition (see Ellipses below).

Vertically stacked entries enclosed in vertical bars indicate that you may select one or more of the entries. Any number of entries can be selected, but no entry may be selected more than once.

Parent topic: Conventions


Ellipses

Ellipses ( . . . ) indicate repetition. The immediately preceding element may be repeated any number of times. If an element consists of a required phrase, the phrase is enclosed in braces.

Parent topic: Conventions


Shading

Shaded areas are not currently used in the syntax.

Parent topic: Conventions


Acknowledgment

Much of the material in this manual is from the ANSI X3.23-1985 COBOL standard and the ANSI X3.23a-1989 supplement. The following statement is required by the standards document.

COBOL is an industry language and is not the property of any company or group of companies, or of any organization or group of organizations.

No warranty, expressed or implied, is made by any contributor or by the CODASYL COBOL Committee as to the accuracy and functioning of the programming system and language. Moreover, no responsibility is assumed by any contributor, or by the committee, in connection therewith.

The authors and copyright holders of the copyrighted material used herein are: FLOW-MATIC (trademark of Sperry Rand Corporation), Programming for the UNIVAC (R) I and II, Data Automation Systems copyrighted 1958, 1959 by Sperry Rand Corporation; IBM Commercial Translator Form No. F28-8013, copyrighted 1959 by IBM; FACT, DSI 27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell.

They have specifically authorized the use of this material in whole or in part, in the COBOL specifications. Such authorizations extend to the reproduction and use of COBOL specifications in programming manuals or similar publications.

Parent topic: Introduction


Program Structure

  • Language Elements
  • Source Format
  • Compiler Compatibility Modes
  • Source Management Statements
  • Conditional Compilation
  • Program Organization
Parent topic: ACUCOBOL-GT Reference Manual


Language Elements

This section describes the basic language elements that make up a COBOL program.

  • COBOL Words
  • Literals
  • Picture Strings
  • Separators
  • Comment Entries
Parent topic: Program Structure


COBOL Words

A COBOL word is a string of not more than 60 characters, which forms a user-defined word or a reserved word. Each character of a COBOL word is selected from the set of letters, digits, underscores, and hyphens. Hyphens or underscores may not appear as the first or last character. When used in COBOL words, lower-case letters are treated as if they were upper-case, and underscores are treated as if they were hyphens.

  • User-defined Words
Parent topic: Language Elements


User-defined Words

A user-defined word is a COBOL word that is created by the programmer. Except for section-names, paragraph-names, segment-numbers, and level-numbers, all user-defined words must contain at least one alphabetic character. User-defined words may not be any of the reserved words.

All user-defined words must be unique except as specified in the rules for uniqueness of reference. However, segment-numbers and level-numbers need not be unique.

Parent topic: COBOL Words


Literals

A literal is a character string that defines a value. There are two types of literals: numeric and nonnumeric.

  • Numeric Literals
  • Nonnumeric Literals
  • Figurative Constants
Parent topic: Language Elements


Numeric Literals

A numeric literal is a character string selected from the digits, the plus sign, the minus sign, and the decimal point. Numeric literals may contain up to 18 digits. This increases to 31 digits if 31-digit support (-Dd31) is in effect.

The following rules govern the formation of numeric literals:

  • A literal must contain at least one digit
  • A literal must contain no more than one sign character and, if one is used, it must be the leftmost character of the string
  • A literal must not contain more than one decimal point. The decimal point is treated as an assumed decimal point and may appear anywhere within the literal except as the rightmost character

If a literal conforms to the rules for formation of a numeric literal, but is enclosed in quotation marks, it is a nonnumeric literal.

Numeric literals may also be specified using binary, octal, or hexadecimal notation. To specify a numeric literal in one of these forms, preface the number with one of the following prefixes:

Binary | "B#"
Octal | "O#" "%" is accepted in HP COBOL compatibility mode (-Cp)
Hexadecimal | “X#” or “H#”

For example:

Number | Binary | Octal | Hexadecimal
3 | B#11 | O#3 | X#3 or H#3
8 | B#1000 | O#10 | X#8 or H#8
12 | B#1100 | O#14 | X#C or H#C
128 | B#10000000 | O#200 | X#80 or H#80
255 | B#11111111 | O#377 | X#FF or H#FF

Leading zeroes after the # are ignored. For example, X#00FF and X#FF are equivalent.

The Compiler converts each numeric literal specified in this way to an unsigned long integer. In most cases, this is a 32-bit unsigned number, so the maximum value of a numeric literal that can specified with this notation is 4294967295, or (2**32) -1.

LENGTH OF expression

The LENGTH OF expression can be used anywhere you would use a numeric literal, except as a subscript or reference modifier. The Compiler treats this expression as if you have coded a numeric literal. The LENGTH OF expression is written as follows:

LENGTH OF data-name

data-name can be a numeric or nonnumeric literal or the name of a data item of any type. Data-name may include subscripts if it refers to a table item. The Compiler calculates the value of the LENGTH OF expression and replaces it with a numeric literal equivalent to the current number of bytes of storage used by the data item or literal referenced in LENGTH OF. For example:

77 my-item PIC x(10).
78 my-item-length value LENGTH OF my-item.

becomes:

77 my-item PIC x(10).
78 my-item-length value 10.

The LENGTH OF expression can also be used in the procedure division as demonstrated in this example:

01 my-data.
   03 my-table occurs 20 times.
      05 my-element-1 pic x(10).
   05 my-element-2 pic 99.

MOVE LENGTH OF my-element-1 TO data-size.
MOVE LENGTH OF my-table TO data-size.
MOVE LENGTH OF my-table(1) TO data-size.

In this example the Compiler treats the first MOVE as MOVE 10 TO data-size, the second MOVE as MOVE 240 TO data-size, and the third MOVE as MOVE 12 TO data-size.

Note: This expression (when used on a table) works differently in ACUCOBOL-GT than in other COBOL Compilers, such as IBM Enterprise COBOL. ACUCOBOL-GT returns the size of the entire table, while IBM returns the size of a single element of the table. You can use the IBM method by compiling the program with -Cv, which turns on the Compiler’s IBM compatibility mode. See Compatibility Options for details on the -Cv Compiler option.

Floating-Point Literals

  1. A floating-point literal has the following format:
    [ + ] k.m { E } [ + ] n
[ - ]     { e } [ - ]

    In the above:

    • k.m represents a number with at least one digit.
    • n represents one or more digits.
    • If the functions of the decimal point and comma are switched with DECIMAL IS COMMA, then k.m will be k,m.

    Here are a few examples of floating-point numbers:

    -12.345e12
.0123E-6
123.E1
  2. Floating-point literals in the Procedure Division are stored internally as USAGE DOUBLE.
  3. The legal range of floating-point values is determined by the target machine. If you express a literal that is out of range for a particular machine, the runtime reports a warning message and substitutes the closest boundary value--either zero or the maximum floating-point value for the machine.
  4. On some computers, floating-point computations may give imprecise results. This is a hardware limitation; some floating point numbers cannot be precisely represented on some machines.
Parent topic: Literals


Nonnumeric Literals

A nonnumeric literal (sometimes called an alphanumeric literal) is a character string delimited at the beginning and at the end by quotation marks or apostrophes. The beginning and ending delimiters must be the same (that is, either both quotes or both apostrophes).

Nonnumeric literals may be up to 4096 characters in length. The characters contained in the delimiters may be selected from all characters available on the host computer.

To place the delimiter character in a nonnumeric literal, use two contiguous delimiter characters (either two quotes or two apostrophes). These two characters represent a single occurrence of that character.

You can also specify nonnumeric literals by supplying the hexadecimal value of the characters desired using the native character set. This can be used, for example, to encode device control codes. Any of the following formats are recognized:

X"hex-values"
X'hex-values'
H"hex-values"
H'hex-values'

The initial H or X may be either upper- or lower-case. The hex-values consist of one or more hexadecimal digits. These digits are drawn from the set of characters '0' – '9' and 'A' – 'F'. Every two hexadecimal digits represent one character position, with the first digit encoding the high-order 4 bits of the character, and the second digit encoding the low-order 4 bits. If an odd number of hexadecimal digits is specified, the low-order 4 bits of the last character are treated as zeros.

Note: In ACUCOBOL-GT h"123" is a nonnumeric literal and not numeric literal for all other dialects.

Example:

The following pairs of nonnumeric literals are equivalent (when the native character set is ASCII):

X"414243" | "ABC"
h'32313' | "210"
H"6E" | "n"
x"22" | """"
Parent topic: Literals


Figurative Constants

Figurative constants are literals that are generated by the Compiler through the use of reserved words. These words are described below. The singular and plural forms of the words are equivalent and may be used interchangeably.

Figurative Constant | Description
ZERO, ZEROS, ZEROES | Represents the numeric value "zero" or one or more occurrences of the character 0, depending on whether the constant is treated as a numeric or nonnumeric literal
SPACE, SPACES | Represents one or more space characters
HIGH-VALUE, HIGH-VALUES | Represents one or more characters with the highest ordinal position in the program collating sequence. Usually this is the hexadecimal value "FF"
LOW-VALUE, LOW-VALUES | Represents one or more characters with the lowest ordinal position in the program collating sequence. Usually this is the binary value 0
QUOTE, QUOTES | Represents one or more quotation mark characters. These words may not be used in place of quotation marks for delimiting nonnumeric literals
ALL Literal | Represents all or part of the string generated by successive concatenations of the characters comprising the literal. The literal must be nonnumeric
Symbolic Character | Represents one or more of the characters defined as the value of this symbolic character in the SYMBOLIC CHARACTERS clause of the SPECIAL-NAMES paragraph
NULL, NULLS | Represents the numeric value "zero" or one or more occurrences of a character whose underlying representation is binary zero. This also represents an invalid memory address when it is used in conjunction with POINTER data types

The word "ALL" may be placed in front of any of the preceding forms (except the ALL literal. Its use is redundant in this case.)

When a figurative constant represents a string of one or more characters, the length of the string is determined by the Compiler from the context according to the following rules.

  • When a figurative constant is specified in a VALUE clause, or when it is associated with another data item (for example, when it is moved or compared to another data item), the string of characters specified by the figurative constant is repeated character by character on the right until the size of the resultant string is equal to the number of character positions in the associated data item.
  • When a figurative constant is not associated with another data item (for example in a DISPLAY, STRING, or UNSTRING statement), the length of the string is one occurrence of the ALL literal or one character in all other cases.

A figurative constant is valid anywhere a literal is. However, ZERO and NULL are the only valid figurative constants for a literal restricted to numeric literals.

Parent topic: Literals


Picture Strings

A PICTURE character-string defines the size and category of an elementary data item. A PICTURE character-string consists of certain symbols, which are composed of the currency symbol and certain other characters in the COBOL character set. A full description of the format of a PICTURE string is given when the PICTURE clause is described.

Any punctuation character that appears as part of a PICTURE string is not considered a punctuation character, but rather as a symbol used in the specification of that PICTURE string.

Parent topic: Language Elements


Separators

A separator is a character or two contiguous characters formed according to the following rules.

  1. The space character is a separator. Anywhere a space is used as a separator, more than one space may be used.
  2. The comma and semicolon characters, immediately followed by a space, are separators that may be used anywhere the separator space is used. They can be used to improve program readability.
  3. The period character, followed by a space, is a separator. It must be used only to indicate the end of a sentence or where required by the ACUCOBOL-GT syntax.
  4. The left and right parentheses are separators. They must be used in balanced pairs.
  5. The quotation mark character is a separator. An opening quotation mark must be immediately preceded by a space or left parenthesis; a closing quotation mark must be immediately followed by one of the separators space, comma, semicolon, period, or right parenthesis. Apostrophes may be substituted for quotation marks in balanced pairs.
  6. The colon character is a separator that may be used only when required by the ACUCOBOL-GT syntax.
  7. Spaces may immediately precede or follow any separator unless they would be enclosed by matching quotation marks. In this case, the spaces would be treated as part of the nonnumeric literal.
Parent topic: Language Elements


Comment Entries

A comment entry is an entry in the Identification Division that may be any combination of characters from the computer's character set. A comment-entry ends with the first line that contains text in Area A.

Parent topic: Language Elements


Source Format

The ACUCOBOL-GT Compiler recognizes two source program formats: ANSI and terminal. The ANSI format conforms to the standard COBOL source format. The terminal format is designed for ease-of-use when you are programming from an interactive terminal. It is upward compatible with VAX COBOL terminal format.

The selection of which format to use is made at compile time. See Source Formats for more information.

  • ANSI Format
  • Terminal Format
  • Line Continuation
  • Blank Lines and Comment Lines
Parent topic: Program Structure


ANSI Format

The ANSI source format divides an input line into several fields. These are determined by character position. Each input line must be 80 characters. Input lines that are shorter than 80 characters are padded with spaces to make 80 characters, while lines longer than 80 characters are truncated on the right. Tab characters are converted into spaces such that the tab stops are eight characters apart.

The ANSI format has five fields. These are:

Field | Description
Sequence Number Area (columns 1 – 6) | This area is ignored by the compiler and may contain any characters. It is traditionally used for sequence numbers to re-order a scrambled card deck.
Indicator Area (column 7) This column must contain one of the following characters:
  • Space -- Default. The compiler processes the line normally.
  • Hyphen -- Continuation. The compiler processes the line as a continuation of the previous line.
  • Asterisk -- Comment. The compiler ignores the contents of the line.
  • Dollar sign -- Comment. The compiler ignores the contents of the line.
  • Slash -- New page. Same as asterisk, except that in the source listing created by the compiler this line starts on a new page.
  • "D" -- Conditional debugging line. The Compiler treats this line as a comment line unless the compiler is run with the option to include debugging lines, in which case the line is treated normally.
Area A (columns 8 – 11) | Area A contains division headers, section headers, paragraph names, and some level indicators
Area B (columns 12 – 72) | Area B contains all other COBOL text.
Identification Area (columns 73 – 80) | Any desired text may be placed here. However, the compiler can conditionally compile lines based on patterns found in this area. For details, see Source Code Control.
Parent topic: Source Format


Terminal Format

Terminal format is convenient for interactive programming. Lines may be longer or shorter than 80 characters. Tab characters are expanded to every eight spaces. The terminal format divides the source line into four fields as follows:

Field | Description
Indicator Area (column 1) The contents of this area are identical to the contents of the ANSI format area of the same name, with two exceptions:
  • If the conditional debugging indicator "D" is used, it must be preceded by a backslash (\). This places the "D" in column 2.
  • If a normal COBOL line is desired, the indicator area is eliminated (a space is not used).
Area A | Starts immediately after the indicator area (either column 1, 2, or 3). It extends for four characters. For a standard source line, Area A starts in column 1.
Area B | Starts after Area A, in column 5 or later, and extends to the end of the line or the start of the Identification Area.
Identification Area | Starts when "|" or "*>" is encountered, provided it is not part of a literal. The Identification Area extends to the end of the line. This can be used to introduce in-line comments.

ACUCOBOL-GT allows up to 320 characters per line. If a line goes over the limit, the compiler issues a warning and truncates the line to 320 characters. If truncation causes an error, the compiler reports the error.

The following sample COBOL text is in terminal format:

* The following paragraph is a sample of terminal
* format. Notice how comments and Area A both start
* in column 1

TEST-PARAGRAPH.
      MOVE SAMPLE-1-VALUE TO SAMPLE-1.
\D    DISPLAY "SAMPLE-1 = ", SAMPLE-1.
      PERFORM EDIT-SAMPLE.
Parent topic: Source Format


Line Continuation

Sentences, entries, phrases, and clauses that continue in Area B of subsequent lines are called continuation lines. A hyphen in a line's indicator area causes the first nonblank character in Area B to be the immediate successor of the last nonblank character of the preceding line. This continuation excludes intervening comment lines and blank lines.

If the continued line ends with a nonnumeric literal without a closing quotation mark, the first nonblank character in Area B of the continuation line must be a quotation mark. The continuation starts immediately after the quotation mark. All spaces at the end of the continued line are part of the literal.

If the indicator area of the continuation line is blank, the compiler treats the last nonblank character of the preceding line as if it were followed by a space.

Parent topic: Source Format


Blank Lines and Comment Lines

A blank line is one that contains only spaces in Area A and Area B. A comment line is one that contains an asterisk, dollar sign, or slash character in the indicator area. Conditional debugging lines are also considered comment lines unless the program is compiled with the conditional debugging option. Blank lines and comment lines may appear anywhere in the source program and have no effect. They will appear in the source listing. If a comment line contains a slash in the indicator area, the source listing will contain a page eject prior to that line.

Parent topic: Source Format


Compiler Compatibility Modes

The ACUCOBOL-GT Compiler accepts certain variants of the COBOL language. These variants are designed to make it easier to compile programs written using other COBOL compilers. The variants, or alternate compatibility modes, are based on the following popular compilers: VAX COBOL version 4.0, Ryan McFarland COBOL version 2.X, ICOBOL, and HP COBOL II/XL. Limited compatibility with IBM DOS/VS COBOL is also available.

ACUCOBOL-GT documentation refers to these modes respectively as VAX COBOL compatibility mode, RM/COBOL compatibility mode, ICOBOL compatibility mode, HP COBOL compatibility mode, and IBM DOS/VS COBOL compatibility mode.

The compatibility mode to use for a program is selected when that program is compiled.Different programs may use different compatibility modes, even if they are part of the same run unit. See Compatibility Options for more information.

Differences in these modes are detailed in the appropriate areas of the help. Their differences primarily lie in the handling of files and the ACCEPT and DISPLAY verbs. Unless otherwise noted, any comments applying to VAX COBOL compatibility mode also apply to ICOBOL compatibility mode.

  • ANSI ACCEPT and DISPLAY Verbs
Parent topic: Program Structure


ANSI ACCEPT and DISPLAY Verbs

The ACCEPT and DISPLAY verbs have ANSI formats that provide strict compatibility with the ANSI definition of these verbs. ACCEPT and DISPLAY also have expanded ACUCOBOL-GT formats that are not ANSI-compliant but offer more functionality. The ANSI definition is quite limited in that it does not provide any screen control facilities. However, these verbs can be useful when you are:

  • Converting programs from other COBOL compilers
  • Directing messages to the runtime's error file
  • Providing low-level control of the user's console

The ANSI formats of ACCEPT and DISPLAY are subsets of the extended ACUCOBOL-GT formats. Thus, the compiler needs guidance in determining which format is desired. This is important because different formats result in different behavior. When examining an ACCEPT or DISPLAY statement, the compiler applies the following rules, in order:

  1. If you specify FROM CRT or UPON CRT, the compiler uses ACUCOBOL-GT format.
  2. If you specify a FROM or UPON phrase for a device other than CRT, the compiler uses ANSI format.
  3. If you use any ACUCOBOL-GT extensions, the compiler uses ACUCOBOL-GT format.
  4. If you place the phrase CONSOLE IS CRT in Special-Names, the compiler uses ACUCOBOL-GT format.
  5. If you use the compile-time option -Ca (ANSI compatibility), the compiler uses ANSI format.
  6. Otherwise, the compiler uses ACUCOBOL-GT format.
Note: By default, the compiler uses ACUCOBOL-GT format.
Parent topic: Compiler Compatibility Modes


Source Management Statements

The COPY, ++INCLUDE, and REPLACE statements allow you to modify the program's source text at compile time. Conditional compiling statements such as $IF and $SET statements can be used to specify whether or not certain lines of code are compiled or skipped. For details on these statements, see Conditional Compilation. Below is a brief description of each of these source management statements; for complete details, follow the links.

  • COPY Statement
  • ++INCLUDE Statement
  • REPLACE Statement
Parent topic: Program Structure


COPY Statement

The COPY statement copies text or a resource (static data such as a bitmap) into the source program from the specified file immediately prior to compilation. The text or resource is inserted for compilation only and does not permanently replace the COPY statement in the program source. Resources and COPY files that are inserted in this way into the object code are loaded from the object file at runtime. If you change the resource (such as a bitmap) or the COPY file, you must recompile for the change to be reflected in the object code.

The REPLACING phrase allows word and substring substitutions to be made in the inserted text prior to compilation.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format

Format 1

COPY INDEXED library-name [ {IN} path-name ] [ SUPPRESS ]
                            {OF}
[ REPLACING { { old-text BY new-text              } } ... ] .
            { { {LEADING } literal-1 BY {literal-2} } }
            { { {TRAILING}              {SPACE    } } }
            { {                         {SPACES   } } }

Format 2

COPY RESOURCE resource-name [ {IN} path-name ] .
                              {COPY RESOURCE resource-name [ {IN} path-name ] .
{OF}}

Syntax Rules

  1. The COPY statement must be terminated by a period. The period is part of the COPY statement and does not otherwise affect the program.
  2. library-name must be a nonnumeric literal or user-defined word. path-name must be a nonnumeric literal or a user-defined word. Note that a nonnumeric literal may reference an environment variable by placing a $ in the name, as described in General Rule 2. To preserve the case of library-name and path-name, you must place them within quotation marks, otherwise they will be treated as uppercase by case sensitive operating systems. See COPY Libraries for more information.
  3. The COPY statement may be used anywhere a separator may occur. It may be placed in Area A or Area B.
  4. old-text and new-text may be any of the following:
    1. A series of text words placed between == delimiters. For example ==WORD-1 WORD-2== specifies a two-word sequence. In old-text, at least one word must be specified. In new-text, zero words may be used.
    2. A numeric or nonnumeric literal.

    3. A data name, including qualifiers, subscripts, and reference

      modification.

    4. Any single text word.
  5. For purposes of the COPY statement, a text word is a contiguous sequence of characters in Area A or Area B that form one of the following:
    1. A separator, except for: space, a pseudo-text delimiter (“==”), and the opening and closing delimiters for nonnumeric literals.
    2. A numeric or nonnumeric literal.
    3. Any of a sequence of characters except comment lines and the word COPY, bounded by separators, which is neither a separator nor a literal.
  6. literal-1 and literal-2 are nonnumeric literals.
  7. The phrases SPACE and SPACES are equivalent. When one of these is used instead of literal-2, literal-1 is deleted and no spaces are actually substituted.
  8. The format of the COPY file must conform to one of the allowed ACUCOBOL-GT source formats (either terminal or ANSI). This format need not be the same as that used in the rest of the program.
  9. resource-name must be an alphanumeric literal or a user-defined word. A resource name with a hyphen is equivalent to the same name with an underscore in place of the hyphen. For example, MY-FILE is treated as being identical to MY_FILE. To preserve the case of resource-name, you must place it within quotation marks; otherwise, it will be treated as uppercase by case-sensitive operating systems.
  10. COPY statements may be nested in other COPY libraries. Any one of the COPY statements in this structure can include the REPLACING phrase.

    Depending on the scope of each statement, the REPLACING phrases might affect subsidiary COPY statements. For example, if program-a.cbl contains a copy/replace as follows:

    COPY "program-b.cpy"
   REPLACING ==genericitems== BY ==myitems==.
    and program-b.cpy contains a nested copy/replace statement:
    COPY "program-c.cpy"
   REPLACING ==variabledata== BY == specificdata==.

    The replace performed in program-b.cpy by the copy/replace statement in program-a.cbl will affect program-c.cpy. If you do not want the copy/replace statement in program-a.cbl to cascade to program-c.cpy, you must add the following statement to program-b.cpy, so that the copy/replace performed in program-b.cpy will not be performed in program-c.cpy.

    COPY "program-c.cpy"
   REPLACING ==genericitems== BY ==genericitems==.

General Rules

  1. library-name and path-name identify a source file to be included at the location of the COPY statement. The text of the source file logically replaces the COPY statement, including the terminating period. The rules for interpreting these names are described in COPY Libraries. The -Ce compile option can be used to specify an alternate default filename extension. See Compatibility Options for more information.
  2. You may use operating system environment variables in the OF phrase of a COPY statement. To reference an environment variable, place a $ in front of it. For example, if you assign MYLIB to C:\MYFILES\MYLIB, then the statement:
    COPY "FILE1" OF "$MYLIB"

    would use the file C:\MYFILES\MYLIB\FILE1.

    You may use multiple environment variables by preceding each one with a $ symbol. Symbol names may contain alphanumeric characters, hyphens, underscores, and dollar signs. If the symbol name is not found in the environment, it is left unchanged (including the initial $ symbol). Symbols are not processed recursively — if the value of a symbol contains a $, the dollars sign is used literally in the final file name.

  3. When INDEXED appears after the word COPY, it is ignored by the compiler. It may be included to provide compatibility with some older COBOL dialects.
  4. If the word SUPPRESS appears after library-name and path-name, the program listing file will not include the contents of the COPY file or any other COPY files that may be nested within. This word provides compatibility with one feature of IBM DOS/VS COBOL. It is not a reserved word in ACUCOBOL-GT and may be used in other contexts as a user-defined name.
  5. The text of the COPY file is copied unchanged into the source program unless the REPLACING option is used. If the REPLACING option is used, elements of the COPY file that match old-text or literal-1 are replaced by new-text or literal-2. The comparison operation that determines text replacement is done as follows:
    1. The leftmost library text word that is not a separator comma or semicolon is the first text word used for comparison. Starting with this word, and the first old-text specified, the entire old-text sequence is compared with an equivalent number of contiguous library text words.
    2. old-text matches the library text only if the ordered sequence of text words of old-text is identical to the ordered sequence of library text words. For purposes of matching, a separator semicolon, comma, or space is considered a space, and a sequence of one or more spaces is considered a single space. Also, lower-case characters are considered the same as upper-case characters in all text words except for nonnumeric literals.
    3. If no match occurs, the comparison is repeated for each old-text specified until a match is found or each old-text has been tried.
    4. After all old-text comparisons have been tried and no match has occurred, the leftmost library text word is copied into the source program. The next text word is then considered as the leftmost word and the cycle is repeated.
    5. Whenever a match occurs between the library text and old-text, the corresponding new-text is placed in the source program. The library text word that follows the rightmost word that participated in the match then becomes the new leftmost word for subsequent cycles.
    6. When you are using the LEADING/TRAILING option, the replacement process differs slightly. When a match occurs between library text and literal-1, the only characters replaced by literal-2 are the specific LEADING or TRAILING characters indicated in the COPY statement. These characters can be a substring or a whole word. If a SPACE or SPACES phrase is used, the LEADING or TRAILING characters are deleted. For example, if you have the following COPY library named MYCOPY.CPY:
          01 dummy-rec.
        03 dummy-number-null    PIC X(10)

      and you used this COPY statement:

      COPY "MY-COPY.CPY" REPLACING
        LEADING "dummy" by "employee"
        TRAILING "null" by SPACES.

      Then the replacement will result in:

      01 employee-rec.
        03 employee-number    PIC X(10)
    7. The comparison cycle continues until the rightmost text word in the library has either participated in a match or has been the leftmost word of a comparison cycle.
  6. Comment lines and blank lines occurring in the library or in old-text are ignored for purposes of matching. Comment lines and blank lines occurring in library text that is matched by a REPLACING operand are not copied into the source program.
  7. Debugging lines may appear within the library text and in old-text. Text words appearing in a debugging line participate in the matching rules as if the line were a normal text line.
  8. When new-text is copied into the source program, the first word of new-text is copied into the same Area as the leftmost word of the replaced text. Subsequent words of new-text are copied into Area B.
  9. It is possible to use the REPLACING phrase to replace substrings. This allows you to construct COPY libraries in which several strings have a uniform substring that you plan to modify.

    For example, the substring individual might occur in the COPY library in individual-name, individual-address, individual-state, individual-city, individual-zip, and individual-title. The REPLACING phrase could be used to replace individual with specific substrings such as employee, owner, student, teacher, professor, or advisor.

    To make use of this, delimit the substring that will be replaced in the COPY library with quotes. Then use the standard COPY syntax to replace the quoted substring by another substring. The resulting sequence of characters is re-evaluated by the compiler to make a new string.

    For example, suppose you have a COPY library (called MYLIB) that contains the following:

    77  MY-'DUMMY'-DATA-ITEM  PIC X(10).

    and you used this COPY statement:

    COPY "MYLIB" REPLACING =='DUMMY'== BY ==REAL==.

    The text of MYLIB is effectively treated as:

    77  MY-REAL-DATA-ITEM  PIC X(10).
    You should use hyphens rather than underscores in this instance. In addition to the use of single and double quotes to delimit the substring, the following delimiters are also allowed:
    ==(XYZ)==
==|XYZ|==  (in HP COBOL compatibility mode)
==*XYZ*==
==:XYZ:==
==XYZ*==
==XYZ&==
==XYZ#==
  10. resource-name and path-name identify a resource file to be included in the resulting object file. The rules for interpreting these names are described in COPY Libraries. Note that the compiler's COPY path applies to resources (Format 2) as well as to source files (Format 1).
  11. The effect of a COPY RESOURCE statement is to add resource-name to a list of resources that the compiler embeds into the resulting COBOL object file. The resources are added to the end of the COBOL object in the same order as the corresponding COPY statements. Because the resources are added to the end of the object, the location of the corresponding COPY RESOURCE statement in the COBOL program is irrelevant. Conventionally, COPY RESOURCE statements are placed either in Working-Storage or at the end of the program, but any location is acceptable.
  12. If individual resolves to a COBOL object or library file, the compiler includes this object or library in the resulting object in a manner similar to cblutil -lib. These are not considered resources, but are embedded COBOL objects. Note that we recommend using cblutil -lib to create libraries containing multiple COBOL objects instead of using COPY RESOURCE. There are two advantages to using cblutil. The first is that you do not need to worry about the order in which COBOL objects are compiled (if you use COPY RESOURCE, you must ensure that the copied object is compiled first), and the second is that cblutil also checks for duplicated program names; COPY RESOURCE does not.

Code Examples

Assume the existence of disk directory CODELIB. In directory CODELIB is file ENROLLREC. The contents of ENROLLREC are:

01 ENROLLMENT-RECORD.
   05 STUDENT-NAME PIC X(30).
   05 STUDENT-ADDR PIC X(50).
   05 STUDENT-GPA PIC 99V9.
   05 SID PIC 9(7).

Code Example 1:

IDENTIFICATION DIVISION.
PROGRAM-ID. COPY-EXAMPLE-1.
...
DATA DIVISION.
FILE SECTION.
FD SCIENCE-DEPT-ENROLLMENT-FILE.
COPY ENROLLREC IN "LIBRARY/CODELIB".
...

Code compiled after COPY substitutions:

...
DATA DIVISION.
FILE SECTION.
FD SCIENCE-DEPT-ENROLLMENT-FILE.
01 ENROLLMENT-RECORD.
   05 STUDENT-NAME PIC X(30).
   05 STUDENT-ADDR PIC X(30).
   05 STUDENT-GPA PIC 99V9.
   05 SID PIC 9(7).
...

Code Example 2:

IDENTIFICATION DIVISION.
PROGRAM-ID. COPY-EXAMPLE-2.
...
DATA DIVISION.
  FILE SECTION.
  FD SCIENCE-DEPT-ENROLLMENT-FILE.
  COPY ENROLLREC
     IN "LIBRARY/CODELIB"
        REPLACING ==SID== BY ==STUDENT-ID==,
                  ==9(7)== BY ==9(9)==.
...

Compiled code after COPY/REPLACING substitutions:

...
DATA DIVISION.
FILE SECTION.
FD SCIENCE-DEPT-ENROLLMENT-FILE.
01 ENROLLMENT-RECORD.
   05 STUDENT-NAME PIC X(30).
   05 STUDENT-ADDR PIC X(30).
   05 STUDENT-GPA PIC 99V9.
   05 STUDENT-ID PIC 9(9).
...

Highlights for first-time users

  1. COPY will always import the entire contents of the named COPY file.
  2. The REPLACING text does not appear in the listing produced by the ACUCOBOL-GT compiler (-Lo filename compiler argument). This is a common source of confusion for users who check the compilation listing file for verification that the replacing action occurred. You can, however, use the -Lp compiler option to create an output file that includes the REPLACING text. See Listing Options in the ACUCOBOL-GT User's Guide for more information.
Parent topic: Source Management Statements


++INCLUDE Statement

To provide more compatibility with other COBOLs, ACUCOBOL-GT also supports the ++INCLUDE statement. This statement is very similiar in function, format, and syntax to the COPY statement described in COPY Statement. The differences from the COPY statement are:

  • A terminating period is not required in ++INCLUDE
  • ++INCLUDE can refer to only a single file, not to a library
  • + +INCLUDE does not allow SUPPRESS
  • ++INCLUDE does not allow NOLIST
  • ++INCLUDE does not allow REPLACING

Filenames referenced by ++INCLUDE are searched for in the same way as COPY files.

Parent topic: Source Management Statements


REPLACE Statement

The REPLACE statement provides the ability to modify source text selectively. Text replacement is accomplished by the compiler immediately prior to source compilation.

REPLACE is frequently used to help facilitate single source code maintenance across multiple COBOL versions or multiple hardware or operating system environments. REPLACE may be used wherever there is a need to make temporary text substitutions for compilation purposes.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format

Format 1

REPLACE { { old-text BY new-text }             } ... ] .
        { { {LEADING } literal-1 BY {literal-2} } }
        { { {TRAILING}              {SPACE    } } }
        { {                         {SPACES   } } }

Format 2

REPLACE OFF.

Syntax Rules

  1. The REPLACE statement must be terminated by a period. The period is part of the REPLACE statement and does not otherwise affect the program.
  2. The REPLACE statement may be used anywhere a separator may occur. It may be placed in Area A or Area B.
  3. old-text and new-text may be any of the following:
    • A series of text words placed between == delimiters. For example ==WORD-1 WORD-2== specifies a two-word sequence. In old-text, at least one word must be specified. In new-text, zero words may be used
    • A numeric or nonnumeric literal
    • A data name, including qualifiers, subscripts, and reference modification
    • Any single text word
  4. For purposes of the REPLACE statement, a text word is a contiguous sequence of characters in Area A or Area B that form one of the following:
    • A separator, except for: space, a pseudo-text delimiter (==), and the opening and closing delimiters for nonnumeric literals
    • A numeric or nonnumeric literal
    • Any of a sequence of characters except comment lines and the word COPY, bounded by separators, which is neither a separator nor a literal
  5. literal-1 and literal-2 are nonnumeric literals
  6. The phrases SPACE and SPACES are equivalent. When one of these is used instead of literal-2, literal-1 is deleted and no spaces are actually substituted

General Rules

  1. The REPLACE statement specifies conversion of source statements containing old-text into new-text. The scope of a REPLACE statement continues from the first text word following the REPLACE statement to the beginning of the next REPLACE statement, or the end of the program. A Format 2 REPLACE statement terminates the scope of any preceding REPLACE statement.
  2. REPLACE statements are processed after COPY statements. The text produced by the action of a REPLACE statement must not contain a REPLACE statement.
  3. Within the scope of a REPLACE statement, any source text that matches old-text is logically replaced by new-text. The comparison operation that determines text replacement is done as follows:
    1. The leftmost source text word is the first text word used for comparison. Starting with this word, and the first old-text specified, the entire old-text sequence is compared with an equivalent number of contiguous source text words.
    2. old-text matches the source text only if the ordered sequence of text words of old-text is identical to the ordered sequence of source text words. For purposes of matching, a separator semicolon, comma, or space is considered a space, and a sequence of one or more spaces is considered a single space. Also, lower-case characters are considered the same as upper-case characters in all text words except for nonnumeric literals.
    3. If no match occurs, the comparison is repeated for each old-text specified until a match is found or each old-text has been tried.
    4. After all old-text comparisons have been tried and no match has occurred, the next source text word is then considered as the leftmost word and the cycle is repeated.
    5. Whenever a match occurs between the source text and old-text, the corresponding new-text replaces old-text in the source program. The source text word that follows the rightmost word that participated in the match then becomes the new leftmost word for subsequent cycles.
    6. When you are using the LEADING/TRAILING option, a match between library text and literal-1 will replace only the specific LEADING or TRAILING characters indicated in the REPLACE statement with the text in literal-2. These characters can be a substring or a whole word. If a SPACE or SPACES phrase is used, the LEADING or TRAILING characters are deleted.
    7. The comparison cycle continues until the rightmost text word in the REPLACE scope has either participated in a match or has been the leftmost word of a comparison cycle.
  4. Comment lines and blank lines occurring in old-text are ignored for purposes of matching.
  5. Debugging lines may appear in old-text. Text words appearing in a debugging line participate in the matching rules as if the line were old-text a normal text line.
  6. When new-text is copied into the source program, the first word of new-text is copied into the same Area as the leftmost word of the replaced text. Subsequent words of new-text are copied into Area B.
  7. It is possible to use the REPLACE statement to replace substrings. In addition to the use of single and double quotes to delimit the substring, the following delimiters are also allowed:
    ==(XYZ)==
==*XYZ*==
==:XYZ:==

Code Examples

REPLACE
   ==STANDARD-ALPHA==    BY   ==ALPHA-UPPER-CASE==
   ==TABLE-SIZE==        BY   ==MAX-TABLE-SIZE==
   ==PAGE-BUFFER-SIZE==  BY   ==SHORT-PAGE-SIZE==
   ==WITH-DEBUG-MODE==   BY   ====.
*delete matched text
...
REPLACE OFF.
*turns off REPLACE

Highlights for first-time users

  1. Multiple REPLACE statements are permitted. The REPLACE statement can appear anywhere in the program source.
  2. The substitution actions of the REPLACE statement continue to affect the program source until the REPLACE statement is either superseded by a new REPLACE statement or turned off by the REPLACE OFF statement.
  3. REPLACE statements are processed after COPY statements.
  4. REPLACE statements can not contain COPY statements. COPY statements may contain REPLACE statements.
  5. The replaced text does not appear in the listing produced by the ACUCOBOL-GT compiler (-Lo filename compiler argument). This is a common source of confusion for users who check the compilation listing file for verification that the replacing action occurred. You can, however, use the -Lp compiler option to create an output file that includes the replaced text.
Parent topic: Source Management Statements


Conditional Compilation

Conditional compilation provides a mechanism for selectively compiling part or all of the COBOL source. Conditional compilation is controlled by $IF, $ELSE, and $END constructs, which behave in a similar way to the COBOL IF construct. Conditional compilation also supplies the $DISPLAY Statement, which can be used to display a message during compilation or include a version number in the object file. The $SET statement can be used to define compiler directives for use in $IF statements.

Note: The compiler has special conditional compilation options that turn on compiler directives and set constants to values. There is also a compiler option (-Cg) that turns of conditional compiling features. See the ACUCOBOL-GT Users Guide, Conditional Compilation Options for details.

Syntax Rules

  1. Conditional compilation statements are indicated by a dollar sign ($) in the indicator area of the source line followed by one of the key words IF, DISPLAY, ELSE, END, and SET.
  2. Conditional compilation should not be used to split a COBOL character string; that is, continuation lines should not be split by conditional compilation controls.
  • $DISPLAY Statement
  • $END Statement
  • $ELSE Statement
  • $IF Statement
  • $SET Statement
Parent topic: Program Structure
Related concepts
Conditional Compilation Options


$DISPLAY Statement

The $DISPLAY statement displays a message on the standard output device during compilation, or includes a version number in the object. There are two formats.

Format 1

$DISPLAY text-data

Format 2

$DISPLAY VCS = version-number

Syntax

The entire $DISPLAY statement must appear on a single line.

General Rules

  1. If a $DISPLAY statement is encountered on a source line that is ignored by conditional compilation, there is neither a compile-time nor a runtime effect.

    Format 1

  2. Text-data is displayed on the standard output device during compilation. There is no run-time effect.

    Format 2

  3. Version-number is the content of the entire source line following the "=", excluding leading and trailing spaces.
  4. The character string formed by concatenating "@(#)", version-number, and a null character (binary zero) is included in the object file. If version-number begins with the characters "@(#)", the compiler does not concatenate these characters when forming the character string. In other words, only a single "@(#)" will be included in the object file, whether version-number includes that string or not.
Note: version-number can be any text string, but it is intended to contain a version number for which a pattern matching tool, such as the UNIX sccs what command, can search the object file.
Parent topic: Conditional Compilation


$END Statement

The $END Statement is used in conjunction with the IF Statement to control conditional compilation. There is a single format:

$END

Syntax

The whole statement must appear on a single line.

General Rules

The innermost $IF statement is terminated. The now active $IF condition is considered:

  • If the active condition is true, the source lines following the $END are processed
  • If the condition is false, COBOL source lines are ignored until the next conditional compilation line is encountered
Parent topic: Conditional Compilation


$ELSE Statement

The $ELSE statement is used in conjunction with the IF Statement to control conditional compilation. There is a single format:

$ELSE

Syntax

  1. The whole statement must appear on a single line.

General Rules

  1. The most recent $IF condition is reversed. If the now active $IF condition is true, the source lines following the $ELSE are processed. If the $IF condition is false, COBOL source lines are ignored until the next conditional compilation line is encountered.
Parent topic: Conditional Compilation


$IF Statement

The $IF Statement provides the ability to conditionally include or exclude text based on the state of certain variables. There are three formats:

Format 1

$IF constant-name-1 [NOT] {< > =} literal-1

Format 2

$IF constant-name-2 [NOT] DEFINED

Format 3

$IF directive-setting SET

Syntax

  1. constant-name-1 is defined by a level 78 item or a CONSTANT compiler flag.
  2. directive-setting is specified in the same format as it is given in the $SET statement and may be preceded by NO. However, the format used in the $IF statement differs from the format used in the $SET statement as follows:
    1. No spaces are allowed between the NO and the directive name
    2. Case must be preserved in the directive

    directive-setting may also be specified at compile time by using the -/ (forward slash) compiler option. See Conditional Compilation Options for details on this and other conditional compiler options.

  3. The entire statement must appear on a single line.
  4. $IF can be nested within another $IF.

General Rules

  1. constant-name-2 is DEFINED if it is the name of a level 78 item or a CONSTANT compiler flag. Otherwise it is NOT DEFINED.
  2. Directive setting SET evaluates true if the given string matches the actual directive setting.
  3. The comparison between directive-setting and the actual directive is case-sensitive.
  4. If the condition evaluates "true", the source lines following the $IF statement are processed. If the condition evaluates "false", COBOL source lines are ignored until the next conditional compilation line is encountered.
Parent topic: Conditional Compilation


$SET Statement

The $SET statement can be used to define compiler directives for use in IF Statement. The directives set with this method have no value, they are only set. The $SET statement can also be used to set values for COBOL variables in the same way as a level 78 data item.

There are two formats for the $SET statement.

Format 1

$SET [NO]compiler-directive

Format 2

$SET CONSTANT identifier value

Syntax

  1. The whole statement must appear on a single line.

General Rules

Format 1

  1. The sole effect of the Format 1 $SET statement is to set a directive name in the compilation unit. Alternatively, you can use the -/ (forward slash) compiler option to set a directive name. If a later Format 3 $IF statement is encountered, this statement will evaluate true if the compiler-directive set by $SET matches the directive-setting in the $IF statement. Preceding the compiler directive with NO turns off the setting. See Conditional Compilation Options in the ACUCOBOL-GT User’s Guidefor more information.

Format 2

  1. identifier must be a valid COBOL identifier.
  2. value is any valid value for a COBOL identifier.

  3. If value is surrounded by single (') or double (") quotes, it is a string literal. identifier can be used anywhere a string literal can be used.

  4. If value is surrounded by parentheses (()), it is a numeric literal.
  5. identifier can be used anywhere a numeric literal can be used.
  6. If value is neither quoted nor surrounded by parentheses, it will be

    considered a numeric literal if all of the characters in the value are digits. Otherwise it is considered a string literal.

  7. A format 2 $SET statement is equivalent to the following line:
    77 identifier VALUE value.

    with the exception that the level "77" line doesn't allow numeric values to be surrounded with parentheses.

Parent topic: Conditional Compilation


Program Organization

A COBOL program is divided into four parts, called divisions. The divisions are the Identification Division, the Environment Division, the Data Division, and the Procedure Division. Divisions can contain sections, which in turn can contain paragraphs. Paragraphs are composed of sentences, clauses, statements and entries.

The general format of a program is:

  [ identification division ]
  [ environment division ]
  [ data division ]
  procedure division
  [ END PROGRAM string_literal. ]

The END PROGRAM statement is optional. If used, it must appear in Area A.

  • Program Elements
Parent topic: Program Structure


Program Elements

A program can consist of many types of elements. These elements are described in the help topics in this section.

  • Division Header
  • Section Header
  • Paragraph Header
  • Clauses and Entries
  • Statements
  • Sentences
Parent topic: Program Organization


Division Header

A division header names and marks the beginning of a division. The formats for particular divisions are described in the appropriate syntax charts. Division headers must appear in Area A.

The following division headers are optional and may be included or excluded at your option. The compiler determines which division it is processing by other COBOL syntax.

  • Identification Division
  • Environment Division
  • Data Division
Parent topic: Program Elements


Section Header

A section header marks the beginning of a section in the Environment, Data, and Procedure Divisions. In the Environment and Data Divisions, the formats of the allowed section headers are described in the appropriate syntax charts in Environment Division and Data Division. In the Procedure Division, a section header is a user-defined word followed by the word "SECTION" and an optional segment number. A period always follows a section header. Section headers must appear in Area A.

Parent topic: Program Elements


Paragraph Header

A paragraph header names a paragraph in the Identification, Environment, and Procedure Divisions. In the Identification and Environment Division, a paragraph header is a reserved word followed by a period. These are detailed in the appropriate syntax charts.

In the Procedure Division, a paragraph header is a user-defined word followed by a period. A paragraph header can be placed in Area A or Area B. When a paragraph header is placed in Area B, the Compiler produces the following warning message, unless the -w compile switch is specified:

Warning: Paragraph Name found in Area B

An initial paragraph header, immediately following the Procedure Division header, is not required. If no initial paragraph header is present, the Compiler creates a dummy header named ACU-MAIN.

The first entry or sentence of a paragraph begins on either the same line as the paragraph header or in Area B of succeeding lines. Subsequent entries or sentences must be in Area B.

Parent topic: Program Elements


Clauses and Entries

An entry is an item of descriptive nature composed of separate clauses. Each clause specifies some attribute of its entry. Clauses are separated by spaces (or commas or semicolons). An entry is terminated by a period. The format of clauses and entries is described in the appropriate syntax diagrams.

Parent topic: Program Elements


Statements

A statement is a COBOL key word (called a verb) followed by its operands. A statement directs either the compiler or the object program to take some action. There are four types of COBOL statements:

  1. Compiler-directing statements specify an action to be taken by the Compiler. Only COPY, REPLACE, and USE statements fit this classification.
  2. Imperative statements specify an unconditional action to be taken by the object program at run-time. Whenever an imperative statement is allowed, it may consist of a sequence of consecutive imperative statements.
  3. Conditional statements specify an action to be taken by the object program that is dependent on the truth value of some condition.
  4. Delimited-scope statements specify their explicit scope terminator. This scope terminator always has "END-" as the first four letters of its word. A delimited-scope statement contains elements of a conditional nature. Because of the scope-delimiter, however, these statements may be used anywhere an imperative statement may be.
Parent topic: Program Elements


Sentences

A sentence is a sequence of one or more statements terminated by a period. An imperative sentence is one that contains only imperative statements. A conditional sentence consists of a conditional statement optionally preceding a sequence of imperative statements.

Parent topic: Program Elements


Identification Division

  • Identification Division
  • PROGRAM-ID Paragraph
Parent topic: ACUCOBOL-GT Reference Manual


Identification Division

The Identification Division marks the beginning of a COBOL program. It serves to name and comment the program.

General Format

        [ IDENTIFICATION DIVISION. ]
        [ ID DIVISION.             ]
        [ PROGRAM-ID. program-name [ IS {INITIAL } PROGRAM ] . ]
                                        {RESIDENT}
        [ AUTHOR. [ comment-entry ] ... ]
        [ INSTALLATION. [ comment-entry ] ... ]
        [ DATE-WRITTEN. [ comment-entry ] ... ]
        [ DATE-COMPILED. [ comment-entry ] ... ]
        [ SECURITY. [ comment-entry ] ... ]
        [ REMARKS. [ comment-entry ] ... ]

Syntax Rules

  1. A comment-entry can consist of any set of characters over any number of lines. It ends with the next line that starts in Area A.
  2. ID DIVISION is interchangeable with IDENTIFICATION DIVISION.
  3. The AUTHOR, INSTALLATION, DATE_WRITTEN, DATE_COMPILED, SECURITY, and REMARKS paragraphs may be placed in any order.

General Rule

The AUTHOR, INSTALLATION, DATE-WRITTEN, DATE-COMPILED, and SECURITY paragraphs are used solely for commentary.

Parent topic: Identification Division


PROGRAM-ID Paragraph

General Format

[ PROGRAM-ID. program-name [ IS {INITIAL } PROGRAM ] . ]
                                {RESIDENT}

Syntax Rule

program-name is a user-defined word or a reserved word. It must be unique among separately compiled programs. If a reserved word is used, it is treated as if it were not reserved. The maximum number of characters is 30.

General Rules

  1. The program-name identifies the name of the program. It is used by the run-time system and debugger to identify a program.
  2. The INITIAL clause specifies an initial program. Whenever an initial program is called, it is placed in its initial state. Data contained in an initial program is set to its starting value every time the program is called. Note that the -Zi compiler option causes the program to be compiled as if it had the IS INITIAL PROGRAM phrase specified.
  3. Files contained in the program are not in the open mode:
    1. The first time the program is called.
    2. The first time the program is called after it has been the target of a CANCEL statement.
    3. Every time the program is called if it is an INITIAL program.
  4. On all other entries, the files contained in the program are in the same state and position as when the program last exited.
  5. INITIAL programs are removed from memory when they exit. Non-initial programs remain in memory until they are the targets of a CANCEL statement.
  6. The RESIDENT clause specifies that the program is to remain resident in memory after its first execution. A program with the RESIDENT clause cannot be affected by a CANCEL statement. Note that the RESIDENT clause shields selected programs from the effects of a CANCEL Statement.
  7. The IBM DOS/VS COBOL -Cv compatibility mode allows the name to be enclosed in quotation marks.
  8. If you omit the PROGRAM-ID paragraph, the program's name is derived from the source file name as follows:
    1. All directory information is removed from the filename and only the base filename is used.
    2. If the filename includes a period (".") or space, that portion of the filename (including the period or space) is truncated.
    3. The name is translated to upper case for letters in the ASCII alphabet range.
    4. Characters not in the ASCII alphabet are left unchanged.
  9. If the PROGRAM-ID paragraph is omitted, the program does not have an INITIAL or RESIDENT state.
Parent topic: Identification Division


Environment Division

  • Environment Division
  • Configuration Section
  • Input-Output Section
Parent topic: ACUCOBOL-GT Reference Manual


Environment Division

The Environment Division describes the program's physical environment, primarily through the descriptions of the files it uses.

General Format

[ [ ENVIRONMENT DIVISION. ]
[ [ CONFIGURATION SECTION. ]
[ SOURCE-COMPUTER. source-computer-entry ]
[ OBJECT-COMPUTER. object-computer-entry ]
[ SPECIAL-NAMES. [ special-names-entry ] ] ]
[ [ INPUT-OUTPUT SECTION. ]
  [ FILE-CONTROL. ] { file-control-entry } ...
[ I-O-CONTROL. [ i-o-control-entry ] ] ] ]

Syntax Rule

The division header is optional for the Environment Division.

General Rule

The Environment Division entries are described in the help topics in this section.

Parent topic: Environment Division


Configuration Section

The Configuration Section contains information about the machine environment for the program. The section header for the Configuration Section is optional.

  • Source-Computer Paragraph
  • Object-Computer Paragraph
  • Special-Names Paragraph
Parent topic: Environment Division


Source-Computer Paragraph

The SOURCE-COMPUTER paragraph identifies the computer on which the source program is compiled.

General Format

SOURCE-COMPUTER. computer-name
   [ WITH DEBUGGING MODE ] .

Syntax Rule

computer-name is a user-defined word, or multiple words separated by spaces, that names the source computer.

General Rules

  1. computer-name is for documentation purposes only.
  2. If the WITH DEBUGGING MODE clause is used, conditional debugging lines in the source program will be treated as standard source lines, not comment lines. This can also be accomplished by compiling with the -Sd compiler option.
Parent topic: Configuration Section


Object-Computer Paragraph

The OBJECT-COMPUTER paragraph names the computer on which the program is to be run.

General Format

OBJECT-COMPUTER. computer-name
   [ MEMORY SIZE integer {WORDS     } ]
                         {CHARACTERS}
                         {MODULES   }
   [ PROGRAM COLLATING SEQUENCE IS alphabet-name ]
   [ SEGMENT-LIMIT IS seg-val ] .

Syntax Rules

  1. computer-name is a user-defined word, or multiple words separated by spaces, that names the object computer.
  2. alphabet-name is a user-defined word that describes the collating sequence of the object machine.
  3. seg-val is an integer literal between 1 and 49 inclusive.

General Rules

  1. computer-name is for documentation purposes only.
  2. The MEMORY SIZE clause is for documentation only.
  3. The COLLATING SEQUENCE clause specifies the collating sequence for any alphanumeric comparisons done in the program. alphabet-name must be an alphabet described in SPECIAL-NAMES. The sequence of the characters in the alphabet determines the sequence for character comparisons. It also specifies the default collating sequence for SORT and MERGE verbs. The character that is first in the program collating sequence is treated as the LOW-VALUES character for the program. The character that is last in the program collating sequence is treated as the HIGH-VALUES character for the program. (The one exception to this is that in Special-Names, LOW-VALUES and HIGH-VALUES always refer to the first and last characters in the native collating sequence.)
  4. The SEGMENT-LIMIT clause defines which Procedure Division sections are to be placed in overlays. If the SEGMENT-LIMIT clause is not specified, any section with a segment number of 50 or greater is placed in overlays. When the SEGMENT-LIMIT clause is used, any section with a segment number of seg-val or greater is placed in overlays.
Parent topic: Configuration Section


Special-Names Paragraph

The SPECIAL-NAMES paragraph describes several miscellaneous aspects of the operating environment. The phrases may be listed in any order, with two exceptions. The switch declarations must come first, and alphabets must be defined before they are referenced in SYMBOLIC CHARACTERS phrases.

General Format

SPECIAL-NAMES.
  [ {switch-name} [ IS mnemonic-name ]
    {system-name}
  [ {ON } STATUS IS cond-name ] ... ] ...
    {OFF}
  [ {alphabet-entry } ... ]
  [ SYMBOLIC CHARACTERS
     { {name} ... {IS } {number} ... } ...
                  {ARE}
  [ IN alphabet-name ] ]
  [ CLASS class-name IS
     { lit-1 [ {THROUGH} lit-2 ] } ... ] ...
               {THRU   }
  [ CURRENCY SIGN IS char ]
  [ DECIMAL-POINT IS COMMA ]
  [ NUMERIC SIGN IS TRAILING SEPARATE ]
  [ CONSOLE IS CRT ]
  [ CURSOR IS cursor-name ]
  [ CRT STATUS IS status-name ]
  [ SCREEN CONTROL IS control-name ]
  [ EVENT STATUS IS event-status ].

Alphabet Entry

Format 1

ALPHABET alphabet-name IS (STANDARD-1}
                          {STANDARD-2}
                          {NATIVE    }
                          {EBCDIC    }

Format 2

ALPHABET alphabet-name IS
   {literal-1 [ THROUGH literal-2   ] } ...
              [ THRU literal-2      ]
              [ {ALSO literal-3} ...]

Syntax Rules

  1. switch-name must be one of the system names: SWITCH-1, SWITCH-2, ... SWITCH-26 or the word "SWITCH" followed by a switch number (a numeric literal 1 through 26 or an alphanumeric literal "A" through "Z"). It represents one of the 26 program switches.
  2. mnemonic-name is a user-defined word that may be used in a SET statement to change the state of the associated program switch or to refer to a device in an ACCEPT or DISPLAY statement.
  3. Each system-name must be associated with a mnemonic-name. Also, no system-name may be given an ON or an OFF STATUS. system-name must be one of the following: CONSOLE, SYSIN, SYSIPT, SYSOUT, SYSLIST, SYSLST, SYSOUT-FLUSH, or SYSERR.
  4. cond-name is a user-defined word that can be used to test the status of a program switch.
  5. For each switch-name, at least one mnemonic-name or one cond-name must be specified. No more than one ON STATUS and one OFF STATUS phrase may be specified for a particular switch-name.
  6. name is a user-defined word that names a symbolic character.
  7. number is an integer literal that must be in the range of ordinal positions in the alphabet being referenced.
  8. There must be a one-to-one correspondence between occurrences of name and number. The relationship between each name and number is by position in the SYMBOLIC CHARACTERS clause. The first name is paired with the first number, the second with the second, and so on.
  9. Class-name is a user-defined word that defines a class name.
  10. lit-1 and lit-2 are numeric or alphanumeric literals.
  11. char is a one-character nonnumeric literal that specifies a currency symbol.
  12. cursor-name must be the name of a data item appearing in the Data Division that is four or six characters in length. cursor-name must describe an elementary unsigned numeric integer or a group item containing two such elementary data items.
  13. status-name must name a group item in the Data Division that is three characters in length or must name an elementary numeric data item.
  14. control-name must name a group item with the following structure:
    01 SCREEN-CONTROL.
   03 ACCEPT-CONTROL   PIC 9.
   03 CONTROL-VALUE    PIC 999.
   03 CONTROL-HANDLE   USAGE HANDLE.
   03 CONTROL-ID       PIC X(2) COMP-X.

    You must use the preceding structure, but you may use your own names for the variables.

  15. event-status must refer to a group item with the following structure:
    01 EVENT-STATUS.
   03 EVENT-TYPE           PIC X(4) COMP-X.
   03 EVENT-WINDOW-HANDLE  USAGE HANDLE OF WINDOW.
   03 EVENT-CONTROL-HANDLE USAGE HANDLE.
   03 EVENT-CONTROL-ID     PIC X(2) COMP-X.
   03 EVENT-DATA-1         USAGE SIGNED-SHORT.
   03 EVENT-DATA-2         USAGE SIGNED-LONG.
   03 EVENT-ACTION         PIC X COMP-X.

    You can find a copy of this format in the COPY library crtvars.def. You may name the data items in the EVENT-STATUS declaration arbitrarily, but the data types, storage, and group structure must match the example given. (For compatibility with older source code, the compiler accepts an EVENT-STATUS item that does not have EVENT-ACTION. The runtime behaves as if EVENT-ACTION contains the value 0, indicating normal event handling.) The SIGNED-LONG data item, EVENT-DATA-2, may be compiled with any -Dw setting (-Dw limits the word-size of the target machine). If you use -Dw16 or -Dw32, you should not run the generated object on a 64-bit machine.

  16. alphabet-name is a user-defined word that defines an alphabet name.
  17. The optional word ALPHABET is required in an alphabet declaration if it immediately follows a SYMBOLIC CHARACTERS declaration.
  18. literal-1, literal-2, and literal-3 may be any literal, but if they are numeric, they must be in the range of 1 through 256.
  19. literal-2 and literal-3 must have a size of one character if they are alphanumeric literals.
  20. literal-1 must also have a size of one character if it is associated with a THROUGH or ALSO phrase.

General Rules

  1. The switch-name clause associates status names (cond-name) and switch names (mnemonic-name) with a particular program switch. These can be used to test the on/off status of a switch or to change the switch's status.
  2. The system-name clause associates a user-defined mnemonic-name with one of the predefined system devices. These names may be used in the ACCEPT and DISPLAY statement to refer to the following devices:
    System Name | ACCEPT | DISPLAY
    CONSOLE | system input | system output
    SYSIN | system input | (illegal)
    SYSIPT | system input | (illegal)
    SYSOUT | (illegal) | system output
    SYSLST | (illegal) | system output
    SYSLIST | (illegal) | system output
    SYSOUT-FLUSH | (illegal) | system output
    SYSERR | (illegal) | error output

    The system input and system output devices are normally the console's keyboard and screen, but may be redirected with operating system commands or with the -i and -o runtime options. The "error output" device is normally the console screen, but may be redirected with the -e runtime option.

  3. The SYMBOLIC CHARACTERS clause defines symbolic characters. A symbolic character is a user-defined figurative constant and can be used anywhere a figurative constant may be. For each name, the character it represents is set to the character whose ordinal position in the native character set is specified by the corresponding number. Note that the ordinal position of a character is one greater than its internal representation. Thus a carriage-return character in ASCII (internal value of "13") would be specified as ordinal position "14".
  4. The CLASS clause defines a class name. A class name is used in a class test to determine whether or not a data item entirely consists of a certain set of characters.

    The class name must be unique in the source context. Make sure that there is no name clash between the class name and reserved COBOL words, user-defined variables, enumerators, events, or methods. This is particularly important for COM objects, ActiveX controls, and .NET assemblies, which may have enumerators that use the same identifier as a class name they define. If there is a name clash, rename the class, or if possible, the other element to make the class name unique. Otherwise compiler errors may result. We suggest prefixing ActiveX and .NET class names with an "@" sign to avoid ambiguities.

    For each numeric literal specified in the CLASS clause, the value of the literal specifies the ordinal number of the character in the native character set to include in the class. For example, "33" would refer to the space character (decimal value 32) in the ASCII character set.

    For each alphanumeric literal, the value of the character or characters in the literal specifies the characters to include in the class.

    If the THROUGH phrase is used, lit-1 and lit-2 must be numeric literals or alphanumeric literals containing only one character. The set of contiguous characters between lit-1 and lit-2 (inclusive) is included in the class. The two literals may be specified in either ascending or descending order.

  5. The CURRENCY SIGN clause specifies the PICTURE clause currency symbol. It can be any character from the computer's character set.
  6. If no CURRENCY SIGN clause is present, the dollar sign is used.
  7. The DECIMAL-POINT IS COMMA clause exchanges the functions of the comma and the period in PICTURE clauses and numeric literals.
  8. The NUMERIC SIGN clause specifies that all USAGE DISPLAY numeric data items in the program that do not have an explicit SIGN clause should be treated as if they had a SIGN TRAILING SEPARATE clause. A compile-time option exists to do the same thing. This is usually done to match the behavior of other COBOL systems.
  9. The CONSOLE IS CRT clause causes the compiler to assume that:
    • UPON CRT is specified for every DISPLAY statement that does not have an UPON phrase
    • FROM CRT is specified for every ACCEPT statement that does not have a FROM phrase

    This causes DISPLAY and ACCEPT statements without explicit UPON or FROM phrases to interact with the Micro Focus Window Manager instead of with the low-level (ANSI-style) console driver. Note that CONSOLE IS CRT is automatically implied by the compiler unless the -Ca compiler option is used. If CONSOLE IS CRT is present in a program compiled with -Ca, CONSOLE IS CRT takes precedence.

  10. The CURSOR clause specifies the name of a data item that will be used to control the console's cursor position throughout the program. If the cursor-name data item is four characters long, the first two characters are the cursor's line number, and the last two characters are the column number. If cursor-name is six characters long, the row and column numbers are each three characters long.

    At the beginning of each ACCEPT statement, cursor-name should specify a location in one of the fields being entered. If it does, the cursor will begin the ACCEPT statement at that location. If cursor-name does not specify a valid position, and more than one field is being entered by the ACCEPT statement, the cursor will start at the beginning of the next valid field (the next field described in the Screen Section definition of the screen-name referenced in this ACCEPT). If the cursor position is past the last field, or before the first field, the cursor will be placed at the beginning of the first field.

    At the conclusion of the ACCEPT statement, the cursor's final location will be placed in cursor-name.

    Note: The Micro Focus runtime system will limit the placement of the cursor in some circumstances. It will not place a cursor past the end of valid data in a field. In this case, the cursor will be placed as close to the requested position as possible. Also note that if you specify a CURSOR clause in SPECIAL-NAMES, you must initialize the cursor location prior to every ACCEPT statement.

    If you specify a CURSOR clause in SPECIAL-NAMES, you may not use the CURSOR phrase of the ACCEPT statement, because this would lead to multiple specification of the initial cursor position.

    If you don't initialize cursor-name with numeric data, you'll receive a nonnumeric data warning message on your first ACCEPT statement.

    The cursor may not start over a prompt character (except at the beginning of a field), unless that prompt character is a space.

    The following code demonstrates how a CURSOR clause could be used with a Format 1 ACCEPT statement:

    identification division.
program-id. testcurs.
***  This program shows how the CURSOR clause
***  can be used with a Format 1 ACCEPT statement.
environment division.
configuration section.
special-names.
    cursor is cursor-name.
data division.
working-storage section.

01  cursor-name.
    05  c-line      pic 9(3).
    05  c-col       pic 9(3).

01  accept-field    pic x(10) value "abcdefghij".
procedure division.
main-logic.

display window erase.

display accept-field line 6 col 6.

***  Position the cursor over the "c" in the value
***  of accept-field, which is the eighth column
***  on the screen.

   move 6 to c-line.
   move 8 to c-col.
   accept accept-field line 6 col 6 update.
   stop run.
  11. The CRT STATUS phrase provides a method for returning the termination status of every ACCEPT statement. At the end of each ACCEPT statement, status-name is filled in with information regarding how the ACCEPT terminated. Two forms of status values are supported. One form is a three-character group item in which each character is treated as a key that contains various information. The second form is a simple numeric value in which each status condition is identified by a unique numeric value. The next two rules describe these two forms.
  12. If status-name is a numeric data item, a unique value will be moved to this item at the end of each ACCEPT statement. This value is the same as the CONTROL KEY value described in the ACCEPT statement. See the discussion of the CONTROL KEY phrase in Procedure Division Statements for details on which values are returned.
  13. If status-name is a group item, the first two characters are assigned values according to the following table:
    Key 1 | Key 2 | Meaning
    '0' | '0' | Termination key pressed
    '0' | '1' | Auto-skip out of last field
    '1' | x'00' - x'FF' | Exception key pressed
    '2' | x'00' | End-of-file key pressed
    '3' | x'00' | Statement timed out
    '9' | x'00' | No items fall within screen

    If Key 1 is 1, Key 2 contains the exception key value of the key that was pressed. See Procedure Division Statements for a table of key values.

    The third character always contains the same value that is returned by the CONTROL KEY phrase of the ACCEPT statement, if this value is in the range of 0 to 255. This is the same value returned when status-name refers to a numeric data item instead of a group item (rule 12 above).

    When Key 1 is set to "0", a normal termination has occurred. Any other value indicates an exception condition.

    Note: This form of the CRT STATUS phrase is provided for compatibility with the X/Open COBOL specification, as well as for compatibility with some other COBOL systems. This method of determining the status of an ACCEPT statement differs in several details from the other methods of determining the ACCEPT status supported by Micro Focus. In particular, the other methods return a single numeric value to describe the status (same as the value stored in Key 3). We recommend that only one technique be used to test for the ACCEPT status to avoid confusion. The following table summarizes the various statements and phrases available to return an ACCEPT statement's status.
    Status Statement | Status Type
    CRT STATUS group-item | 3-byte key
    CRT STATUS numeric-item | Numeric value
    CONTROL KEY IS item | Numeric value
    ACCEPT item FROM ESCAPE | Numeric value
    ON EXCEPTION item | Numeric value

    Also note that the formation of Key 2 is tricky. In the case of a normal termination, Key 2 will contain a normal COBOL character digit, but in the other cases, it will contain a binary value. The easiest way to test the status value is to use hexadecimal constants to express the binary value. Alternately, you can declare Key 2 to be COMP-X and test the exception values against numeric literals. Note that some other COBOL systems define Key 2 to be PIC 99 COMP. If you convert programs that use this construct, be sure to use the -D1 or -Dm compile-time flags to cause this data item to be stored in one character. If you do not do this, Key 2 will occupy two characters and return invalid values.

  14. The ALPHABET clause specifies the alphabet to be used for character translations and collating sequences.

    An alphabet may be used in the following circumstances:

    • In the CODE-SET phrase of a sequential file's FD. The alphabet specifies a character translation map. A Format 2 alphabet may not be used for this purpose.
    • In the COLLATING SEQUENCE phrase of an indexed file's SELECT. This specifies an alternate collating sequence for the file's keys.
    • In the COLLATING SEQUENCE phrase of a SORT or MERGE statement. Here, the alphabet specifies the collating sequence to use for key comparisons.
    • In the PROGRAM SEQUENCE phrase of the OBJECT-COMPUTER paragraph. This specifies the collating sequence for any alphanumeric comparisons done in the program. It also specifies the default collating sequence for SORT and MERGE verbs. The character that is first in the program collating sequence is treated as the LOW-VALUES character for the program. The character that is last in the program collating sequence is treated as the HIGH-VALUES character for the program. The one exception to this is that in Special-Names, LOW-VALUES and HIGH-VALUES always refer to the first and last characters in the native collating sequence.
    • In a SYMBOLIC CHARACTERS clause in SPECIAL-NAMES, to indicate the alphabet to which the symbolic character belongs.

    A Format 2 alphabet is used to describe a collating sequence. Explicitly named characters are listed in the order of their positions in the new collating sequence.

    Any characters in the native collating sequence that are not explicitly named in the ALPHABET clause assume a position greater than any of the explicitly named characters. The relative order of these unnamed characters remains the same as in the native collating sequence.

    If a literal in the ALPHABET clause is numeric, it designates a character by specifying that character's ordinal position in the native character set. For example, 66 would designate the letter A in the ASCII character set.

    If the literal is alphanumeric, it is the actual character. For alphanumeric literals that contain more than one character, the characters are assigned successive ascending positions in the new collating sequence.

    Here's an example :

       ALPHABET TINY IS "01", "Z", "AB", SPACE

    This alphabet contains 6 characters. Character 0 is the first character in the sequence, character 1 is the second. Character "Z" is the third, and characters "A" and "B" are the fourth and fifth. The space character is the sixth character. If you were to sort a file using this alphabet, all items that started with "Z" would appear before items that started with "A" or "B". Anything that started with a space would be last.

    Any characters in the native collating sequence that are not explicitly named assume a position in the new collating sequence greater than any of the explicitly named characters. The relative order of these characters remains unchanged from the native collating sequence. In the example above, this means that anything that starts with "C" comes after anything that starts with spaces, and anything starting with "D" comes after "C".

    If the THROUGH phrase is specified, the set of contiguous characters in the native character set beginning with literal-1 and ending with literal-2 are assigned successive ascending positions in the new collating sequence. The THROUGH phrase may specify characters in ascending or descending sequence.

    For example, the following alphabet will sort the alphabetic characters backwards:

    ALPHABET REV-ALPHA IS "Z" THROUGH "A",
           "z" THROUGH "a"

    If the ALSO phrase is specified, literal-1 and literal-3 are assigned the same position in the collating sequence. This is one of the most useful capabilities of the Format 2 ALPHABET clause. For example, the following alphabet will cause the upper case and lower case of each letter to be treated as the same character for sorting:

    ALPHABET NO-CASE IS 1 THRU 65,   'A' ALSO 'a',
'B' ALSO 'b',   'C' ALSO 'c',   'D' ALSO 'd',
'E' ALSO 'e',   'F' ALSO 'f',   'G' ALSO 'g',
'H' ALSO 'h',   'I' ALSO 'i',   'J' ALSO 'j',
'K' ALSO 'k',   'L' ALSO 'l',   'M' ALSO 'm',
'N' ALSO 'n',   'O' ALSO 'o',   'P' ALSO 'p',
'Q' ALSO 'q',   'R' ALSO 'r',   'S' ALSO 's',
'T' ALSO 't',   'U' ALSO 'u',   'V' ALSO 'v',
'W' ALSO 'w',   'X' ALSO 'x',   'Y' ALSO 'y',
'Z' ALSO 'z'

    The "1 THRU 65" phrase causes the portion of ASCII that exists in front of "A" to be sorted in its normal sequence ("A" is the 66th character in ASCII). Then each lower-case character is mapped to its corresponding upper-case character. The remaining characters then follow implicitly.

  15. The following IBM DOS/VS COBOL system names are supported by Micro Focus in the SPECIAL-NAMES paragraph if the -Cv compiler option is used:
       SYSPCH
   SYSPUNCH
   C01 through C12
   CSP
   S01 through S05

    To enable printing to printer channels C01-C12, set the runtime configuration variable COBLPFORM as described in Appendix H in the ACUCOBOL-GT Appendices manual.

    For more information about IBM DOS/VS COBOL conversions, see IBM DOS/VS COBOL Conversions in Transitioning to ACUCOBOL-GT.

  16. The following HP COBOL special names are supported by Micro Focus in the SPECIAL-NAMES paragraph if the -Cp compiler option is used:
       NO SPACE CONTROL
   TOP

    For more information, see HP COBOL Conversions, in Transitioning to ACUCOBOL-GT.

General Rules - Screen Control Entry

In the following rules, the four elementary items belonging to the SCREEN CONTROL group item are referenced by the names in this example:

01 SCREEN-CONTROL.
   03  ACCEPT-CONTROL    PIC 9.
   03  CONTROL-VALUE     PIC 999.
   03  CONTROL-HANDLE    USAGE HANDLE.
   03  CONTROL-ID        PIC X(2) COMP-X.
  1. The following statement allows an embedded procedure to control its ACCEPT statement:
    [ SCREEN CONTROL IS control-name ]

    See PROCEDURE Clause and Using Screen Section Embedded Procedures for more information.

  2. Input and update fields in a Screen Section entry are given field numbers.* The compiler computes the field number for any Screen Section entry by examining all of the input and update fields in that entry’s level 01 group item. Each input and update field in a level 01 Screen Section entry is numbered sequentially, starting at one. For example, consider the following Screen Section entry:
    01 SCREEN-1.
   03 LITERAL-1 VALUE "Field 1: ".
   03 FIELD-1, PIC X(5) TO WS-1.
   03 LITERAL-2 VALUE "Some data: ", LINE + 1.
   03 DATA-1, PIC X(5) FROM WS-2.
   03 LITERAL-3 VALUE "Field 2: "., LINE + 1.
   03 FIELD-2, PIC X(5) USING WS-3.

    This Screen Section entry has two input or update fields: FIELD-1 and FIELD-2. In this case, FIELD-1 is field number 1 and FIELD-2 is field number 2. Note that LITERAL-1, LITERAL-2, and DATA-1 do not receive field numbers because they do not contain a TO or USING phrase—DATA-1 is a display-only (FROM) field. The literals prompt the end user for entries.

    *Graphical controls in the Screen Section are also assigned field numbers. The rules that govern how field numbers are assigned to graphical controls are given in general rule 6 of the Format 2 Screen Description, in Screen Description Entry.

  3. Prior to executing an embedded procedure, an ACCEPT statement initializes the SCREEN CONTROL variable. It sets ACCEPT-CONTROL depending on the reason for entry (if it is a notify (“NTF-…”) event, ACCEPT-CONTROL is set to 1; otherwise, the default is 0), and it sets CONTROL-VALUE to the field number of the Screen Section entry that is executing the embedded procedure.

    On entry to an embedded procedure, CONTROL-HANDLE contains the handle of the current control, and the CONTROL-ID field contains its ID. If the current Screen Section item (the one that names the embedded procedure) is not a graphical control, CONTROL-HANDLE and CONTROL-ID are set to NULL and 0, respectively. See PROCEDURE Clause for more information.

    When the ACCEPT statement terminates, it sets ACCEPT-CONTROL to 0 and sets CONTROL-VALUE to the field number of the last field to have the cursor. This will be zero if the Screen Section entry contains no fields. CONTROL-HANDLE and CONTROL-ID fields contain the handle and ID of the graphical control that was active when the ACCEPT terminated. If the ACCEPT terminated while in a textual (i.e., non-graphical) field, they are set to NULL and 0, respectively.

  4. When an after procedure or exception procedure returns control to its ACCEPT statement, the value of SCREEN CONTROL determines what happens next. By setting this value in your after or exception procedure, you can cause the program to skip fields, continue ACCEPTING data, or terminate the ACCEPT with or without an exception. ACCEPT-CONTROL serves as a flag that is checked to determine how to proceed; SCREEN-CONTROL provides a needed value, as shown in this list:
    1. If ACCEPT-CONTROL is 0, the ACCEPT statement continues normally.
    2. If ACCEPT-CONTROL is 1, the ACCEPT statement moves the cursor to the field identified by the value of CONTROL-VALUE. The ACCEPT statement then continues from there.
    3. If ACCEPT-CONTROL is 2, the ACCEPT statement terminates normally. The value of CONTROL-VALUE determines the termination value of the ACCEPT statement. You can determine its value by examining CRT STATUS or by using the ACCEPT FROM ESCAPE KEY verb.
    4. If ACCEPT-CONTROL is 3, the ACCEPT statement terminates with an exception, assuming that exceptions are allowed. The value of CONTROL-VALUE sets the exception value of the ACCEPT statement. You may use CRT STATUS or the ACCEPT FROM ESCAPE KEY verb to determine the statement’s exception value.
    5. If ACCEPT-CONTROL is 4, control is transferred to the graphical control whose ID matches CONTROL-ID. This works identically to setting ACCEPT-CONTROL to 1, except that the CONTROL-ID field is used and the search is made using the control’s ID instead of the field numbers.
    6. If none of the preceding applies, the ACCEPT statement continues normally.
  5. If you set ACCEPT-CONTROL to 1, several special cases exist:
    1. If you set CONTROL-VALUE to zero, the ACCEPT statement will remain in the current field.
    2. If you set CONTROL-VALUE to a field number that does not exist, the ACCEPT statement will terminate. In this case, the CRT STATUS value for the ACCEPT statement will be zero for a numeric CRT STATUS or 0, 2, x00 for a group-item CRT STATUS.
    3. If you set CONTROL-VALUE to the field number of a protected field, control will pass to the first unprotected field with a higher field number. If no such field exists, the ACCEPT statement will terminate as in case (b) above.
  6. When a Screen Section ACCEPT statement executes, it examines the value of SCREEN CONTROL. If the ACCEPT-CONTROL field is 1, then the ACCEPT statement starts at the field identified by CONTROL-VALUE. This overrides any initial field identified by the CURSOR Special-Names entry. Note that this is usually easier than using the CURSOR clause to identify a starting point in a Screen Section ACCEPT. If the specified field does not exist (or is protected) the cursor is placed at the numerically closest legal field. If two fields are equally close, the one with the larger field number is used.

General Rules - Event Status Entry

EVENT-STATUS is used to identify which data item is to receive information about screen events.

In the description below, the seven elementary items belonging to the EVENT-STATUS group item are referenced by the names in this example:

01 EVENT-STATUS.
   03 EVENT-TYPE           PIC X(4) COMP-X.
   03 EVENT-WINDOW-HANDLE  USAGE HANDLE OF WINDOW.
   03 EVENT-CONTROL-HANDLE USAGE HANDLE.
   03 EVENT-CONTROL-ID     PIC X(2) COMP-X.
   03 EVENT-DATA-1         USAGE SIGNED-SHORT.
   03 EVENT-DATA-2         USAGE SIGNED-LONG.
   03 EVENT-ACTION         PIC X COMP-X.

When a system event occurs during an ACCEPT statement, the EVENT-STATUS data item is filled with the following information:

Holds a value that uniquely identifies the kind of event that occurred.

Holds the handle of the floating window in which the event occurred. If the event occurred in a control, this will be the handle of the floating window that contains the control.

Holds the handle of the control in which the event occurred. If the event did not occur in a control, this item is set to NULL.

Holds the ID of the control in which the event occurred. IDs are assigned by the application when each control is created. If the event did not occur in a control, this item will have the value zero.

Holds information about the event that is unique for each EVENT-TYPE. For many events, this value will always be zero.

Also holds information about the event that is unique for each EVENT-TYPE. For many events, this value will always be zero.

Holds a value that determines the continued handling of an event when an event procedure terminates. On entry to the procedure, EVENT-ACTION is set to zero. The following values are meaningful on exit from the procedure (symbolic names in acugui.def):

EVENT-ACTION-NORMAL | (value 0) The event is processed normally, causing the control to terminate for terminating events.
EVENT-ACTION-TERMINATE | (value 1) The event is processed normally, and then it terminates the active control. This action forces termination of events that do not normally terminate.
EVENT-ACTION-CONTINUE | (value 2) The event is processed normally, but it does not terminate the active control, even if it would ordinarily do so.
EVENT-ACTION-IGNORE | (value 3) The event is not processed further, but it does not terminate the active control. We do not recommend this action because it short-circuits the runtime’s event handler. Events receive a certain amount of processing before the event procedure is entered. Ignoring an event does not prevent this processing from occurring.
EVENT-ACTION-FAIL | (value 4) This setting is used in response to certain events to indicate that a specific action should be taken, usually to prevent the event from taking its normal action. Events that use this setting state that they do so in the event description, along with a description of the effects of setting it.
EVENT-ACTION-FAIL-TERMINATE

(value 7) The effect of this setting is exactly the same as that of EVENT-ACTION-FAIL with the additional effect of EVENT-ACTION-TERMINATE: after performing the “fail” operation, the control terminates with an exception status of W-EVENT.

Certain screen controls produce events that understand the special EVENT-ACTION setting of EVENT-ACTION-FAIL. This setting usually causes the control to process the event in a special fashion. For example, setting EVENT-ACTION-FAIL in response to a MSG-GOTO-CELL-MOUSE event for the grid control prevents the cursor from entering the cell the user clicked.

Returning EVENT-ACTION-FAIL to a control and have that event also terminate the control by setting EVENT-ACTION to EVENT-ACTION-FAIL-TERMINATE.

This setting also corrects the following issue: In earlier versions, the ACCEPT-CONTROL field of the SCREEN CONTROL item was set to 1 when entering an exception procedure that was triggered by a message-style event (any event that starts with MSG- in its name). Normally, message-style events do not cause termination and so the exception procedure is not entered. However, when you set EVENT-ACTION to EVENT-ACTION-TERMINATE, the control terminates and the exception procedure is entered. Having ACCEPT-CONTROL set to 1, however, meant that as soon as the exception procedure terminated, the control would reactivate. You had to explicitly override this by setting ACCEPT-CONTROL to 0 in the exception procedure.

This two-step process to terminate a control in the Screen Section is difficult to remember and generally unclear. This has been corrected so that the default ACCEPT-CONTROL value in this case is 0 instead of 1. This means that when setting EVENT-ACTION to EVENT-ACTION-TERMINATE or EVENT-ACTION-FAIL-TERMINATE, the ACCEPT statement terminates with an exception once the exception procedure completes.

Since this is a change to the semantics of ACUCOBOL-GT, you can inhibit this change by compiling with semantic compatibility for an earlier version of the product (prior to 4.3). For example, you can inhibit this by compiling with -C42. Note that object files produced by earlier versions of the compiler do not see this change.

Parent topic: Configuration Section


Input-Output Section

The INPUT-OUTPUT Section describes the I/O environment that the program will be using. The header for this section is optional.

  • File-Control Paragraph
  • I-O-Control Paragraph
Parent topic: Environment Division


File-Control Paragraph

The FILE-CONTROL paragraph contains descriptions of the physical aspects of the files the program uses.

General Format

[ FILE-CONTROL. ] { file-control-entry } ...
or
{ file-control-entry } ...
File-control-entry has one of the following formats:

Format 1 — Sequential Files

SELECT [ OPTIONAL ] file-name
   ASSIGN TO [ DYNAMIC ] [ device ] [ file-spec ]
             [ EXTERNAL]
[ [ ORGANIZATION IS ] [BINARY] SEQUENTIAL ]
                      [RECORD]
                      [LINE ]
[ ACCESS MODE IS SEQUENTIAL ]
[ RESERVE {number} [ALTERNATE] [AREA ]]
          {NO }                [AREAS]
[ LOCK MODE IS {EXCLUSIVE}
               {AUTOMATIC}
               {MANUAL }
 [ RECORD DELIMITER IS [ STANDARD-1 ]
[ FILE STATUS IS status-variable [status-variable-2]]
[ PADDING CHARACTER IS pad-char ] .

Format 2 - Relative Files

SELECT [ OPTIONAL ] file-name
   ASSIGN TO [ DYNAMIC ] [ device ] [ file-spec ]
             [ EXTERNAL]
[ ORGANIZATION IS ] RELATIVE
[ ACCESS MODE IS
  { SEQUENTIAL [ RELATIVE KEY IS rel-key ] } ]
  { RANDOM       [RELATIVE] KEY IS rel-key   }
                 [ACTUAL]
  { DYNAMIC RELATIVE KEY IS rel-key        }
[ LOCK MODE IS { EXCLUSIVE                      }
                 { AUTOMATIC [ multiple-option ] }
                 { MANUAL    [ multiple-option ] }
  [ RESERVE {number} [ALTERNATE] [AREA ]]
            {NO    }             [AREAS]
  [ FILE STATUS IS status-variable [status-variable-2] ] .

See the multiple-option format at the end of the formats.

Format 3 - Indexed Files

SELECT [ OPTIONAL ] file-name
   ASSIGN TO [ DYNAMIC ] [ device ] [ file-spec ]
             [ EXTERNAL]
 [ WITH {COMPRESSION} ... ]
        {ENCRYPTION }
 [ COMPRESSION CONTROL VALUE IS factor ]
 [ ORGANIZATION IS ] INDEXED
 [ ACCESS MODE IS {SEQUENTIAL} ]
                  {RANDOM    }
                  {DYNAMIC   }
 [ RECORD KEY IS key-name [= seg-name ...]
    [ WITH [NO] DUPLICATES ] ] ...
 [ ALTERNATE RECORD KEY IS alt-name [= seg-name ...]
    [ WITH [NO] DUPLICATES ] ] ...
 [ LOCK MODE IS { EXCLUSIVE [ WITH MASS-UPDATE ] }
                { AUTOMATIC [ multiple-option  ] }
                { MANUAL    [ multiple-option  ] }
 [ RESERVE {number} [ALTERNATE] [AREA ]]
           {NO    }             [AREAS]
 [ FILE STATUS IS status-variable [status-variable-2] ]
 [ COLLATING SEQUENCE IS alphabet-name ] .

Format 4 - Sort Files

SELECT file-name
   ASSIGN TO [ DYNAMIC ] [ device ] [ file-spec ]
             [ EXTERNAL]
 [ FILE STATUS IS status-variable [status-variable-2]] .
Note: multiple-option has the following format for both Format 2 and Format 3.
WITH { { LOCK ON } [ MULTIPLE ] { RECORD } } [WITH ROLLBACK]
     { ROLLBACK }

Syntax Rules

  1. File-spec must be either a nonnumeric literal or the name of an alphanumeric Working-Storage data item.
  2. Device must be one of these words: INPUT, OUTPUT, INPUT-OUTPUT, RANDOM, DISK, DISC, PRINT, PRINTER, PRINTER-1, TAPE, CASSETTE, CARD-PUNCH, CARD-READER, CONSOLE, MAGNETIC-TAPE, DISPLAY, KEYBOARD, SORT, MERGE, SORT-MERGE, or SORT-WORK. The last four may be used only with sort files.
  3. If DYNAMIC is specified, file-spec must be specified and must be the name of a data item. This data item need not be defined in the program, although it can be.
  4. If EXTERNAL is specified, file-spec must be specified and must be a user-defined COBOL word.
  5. status-variable must be the name of an alphanumeric (or USAGE DISPLAY numeric) Working-Storage or Linkage data item with a size of 2 characters. Status-variable-2 must be the name of a group item that is 6 characters (this is not checked by the compiler).
  6. rel-key must name an unsigned integer data item. It must not be in the record description entry for the same file.
  7. factor must be a numeric literal from zero to 100, inclusive.
  8. The key of an indexed file may have any PICTURE and USAGE. Regardless of the PICTURE and USAGE specified, the key is always treated as an alphanumeric data item when the sort order of the file is determined (the individual bytes are compared with the collating sequence).
  9. seg-name must name a data item in the same file's record description entry. A seg-name may not be a group item that contains variable-occurrence data items.
  10. If seg-name is used to define a split RECORD KEY, key-name is a user-defined word. Otherwise, key-name must name a data item in the same file's record description entry. It may not be a group item that contains variable-occurrence data items.
  11. If seg-name is used to define a split ALTERNATE RECORD KEY, alt-name is a user-defined word. Otherwise, alt-name must name a data item in the same file's record description entry. It may not be a group item that contains variable-occurrence data items.
  12. number must be an integer literal.
  13. alphabet-name is the name of an alphabet declared in the Special-Names paragraph.
  14. pad-char must be either a single-character literal or a single-character alphanumeric data item. When a PADDING CHARACTER is specified, the last block of the file is padded with pad-char. When the file is read, any final portion of a block that consists solely of padding characters is skipped.
  15. SELECT must be the first clause in a FILE-CONTROL entry. The other clauses may follow in any order. The SELECT clause may appear in Area A; all other clauses must appear in Area B.
  16. Each file described in the Data Division must be specified exactly once in the FILE-CONTROL paragraph.
  17. Each file described by a SELECT clause must have exactly one corresponding file description in the Data Division.
  18. ORGANIZATION IS RECORD SEQUENTIAL is synonymous with ORGANIZATION IS BINARY SEQUENTIAL.

General Rules

  1. When the FILE STATUS clause is specified, a value will be moved into status-variable after the execution of every statement that references the corresponding file. This value indicates the status of the statement status-variable-2 is treated as commentary by the compiler. See I/O Status for more information.
  2. The ACCESS MODE clause specifies the order in which records are read or written. If it is not specified, SEQUENTIAL is implied.
  3. For sequential access, the records are accessed according to the organization of the file:
    Sequential files | The sequence is the same as that established by the execution of WRITE statements that created the file
    Relative files | The sequence is the order of ascending relative record numbers for the file's existing records
    Indexed files | The sequence is the order of ascending record key values for the file's current key of reference
  4. Random access indicates that the file will be accessed only by key value.
  5. Dynamic access indicates that the file will be accessed both randomly and sequentially.
  6. RELATIVE KEY results in record key numbers that are one-based. ACTUAL KEY may be specified for RANDOM access mode and when compiling version 8.1 and greater objects in IBM DOS/VS (-cv) and HP3000 (-cp) compatibility modes. For such files, the record key numbers will be zero-based. For example, if you have a relative file with a fixed record length of 3 bytes and a relative file with the following contents:
    AAABBBCCC
the record keys for the different modes are:
     RELATIVE  ACTUAL
AAA:    1        0
BBB:    2        1
CCC:    3        2
  7. The ASSIGN clause specifies the association of the file to a storage device. If the file-spec phrase is missing, file-name will be treated as an alphanumeric literal and substituted for it (exception: rule 8.a below). In this case, file-name should conform to the host operating system's rules for file names. Note that the ASSIGN clause is required even if both device and file-spec are missing.
  8. The device phrase of the ASSIGN clause is not required. If it is specified, it can affect the processing of the file in a variety of ways. If the file is not a sequential file, the device phrase is ignored. If it is a sequential file, the following applies depending on the device phrase used:
    1. PRINT, PRINTER, PRINTER-1 — A sequential file marked with one of these device phrases will be treated as a print file. Print files may not be opened for INPUT or I/O. When records are written to a print file, trailing spaces are first removed from the record. Print files have printer carriage control information added to them as specified by the WRITE statements that add records to the file. If PRINTER or PRINTER-1 is specified, and no file-spec is specified, the external file name is treated as PRINTER or PRINTER-1 (unless RM/COBOL compatibility mode is being used, in which case rule 6 applies instead). Normally, these names are translated at runtime to the name of the system spooler. This is an exception to rule 6 above.
    2. CARD-PUNCH, CARD-READER, CASSETTE, INPUT, INPUT-OUTPUT, MAGNETIC-TAPE, OUTPUT — Any of these device phrases indicates that trailing spaces should be removed from records before they are added to the file. This will have effect only if the file is a "line" sequential file. When records are read from one of these files, the records are automatically padded with spaces to reach the maximum record size. A file with one of these designators may not be opened for I/O.
    3. DISPLAY, KEYBOARD — Causes the default file type to be line sequential. You may override this by specifying the file type explicitly in the ORGANIZATION clause. This rule is provided for compatibility with ICOBOL, which uses this method for specifying line sequential files.
    4. RANDOM, DISK, DISC, TAPE, CONSOLE — Indicates no additional processing. This is the same as if the device phrase were omitted.
    5. MERGE, SORT, SORT-MERGE, SORT-WORK — Also indicates no additional processing. These device phrases may be associated with a sort file only.
  9. The word "DYNAMIC" in an ASSIGN phrase indicates that file-spec is the name of a variable that contains the file's name. Because this is the normal meaning of file-spec when it refers to a variable, the word DYNAMIC is largely commentary.
  10. When DYNAMIC is specified, if file-spec refers to a variable that is not otherwise defined, the compiler creates a Working-Storage variable by that name that is PIC X(256). It is the program's responsibility to move a valid file name to this data item prior to opening the file.
  11. The word EXTERNAL in an ASSIGN phrase indicates that the COBOL word that makes up file-spec is the name of the file itself. This name is processed first by ignoring any characters that appear before the last hyphen in the word (including the hyphen itself). For example:
       ASSIGN TO EXTERNAL UT-S-MYFILE

    results in MYFILE being used for the file name. In other COBOL systems, this name is normally assigned to a specific file name using environment variables. This kind of name mapping occurs automatically under Micro Focus. There is no special meaning associated with ASSIGN phrases containing the EXTERNAL option. Such files have name mapping applied through the environment just like all other files.

    Note: If neither DYNAMIC nor EXTERNAL is included in the ASSIGN clause, you can use the --fileAssign= compiler option to specify DYNAMIC or EXTERNAL at compile time. For more information, see File Options.
  12. The WITH COMPRESSION phrase of the ASSIGN clause specifies that file record compression is desired. This phrase must be specified before the ORGANIZATION IS INDEXED phrase. The Micro Focus indexed file system supports compression, but not all file systems do. The WITH COMPRESSION phrase takes effect only when the file is initially created or re-created via the OPEN statement. When no compression factor is specified (see next paragraph), WITH COMPRESSION uses the default compression factor (70).

    A compression factor other than the default may be selected via the COMPRESSION CONTROL VALUE IS clause. The factor must be a numeric literal from zero (meaning no compression) to 100 (maximum compression). A compression factor of 1 is equivalent to the default compression.

    The exact meaning of the compression factor depends upon the host file system. See Indexed Files Vision for specifics about the Vision file system.

  13. The WITH ENCRYPTION phrase specifies that record encryption is desired on the file. Encryption is currently available with the Micro Focus indexed file system only. The ENCRYPTION clause takes effect only when the file is initially created or re-created via the OPEN statement.
  14. The ORGANIZATION clause specifies the logical structure of the file. This is established when a file is first created and may not be changed. If it is absent, then SEQUENTIAL organization is implied. Records stored in an ORGANIZATION IS RELATIVE file are uniquely identified by record number. The relative record number of a given record specifies the record's ordinal position in the file. The first record has a relative record number of one.
  15. Records in an ORGANIZATION IS INDEXED file are uniquely identified by the values in the record's primary key.
  16. The primary key is identified by the RECORD KEY clause. Records are ordered in ascending collating sequence by the primary key. If the WITH DUPLICATES phrase is present, the primary key may contain duplicate values, if the indexed file system supports them. The Micro Focus indexed file system supports duplicate primary key values. If WITH DUPLICATES is used with a file system that does not support them, when the file is created via the OPEN statement a status of 0M is returned, indicating that the file was successfully created but that duplicate primary keys are not supported. When WITH DUPLICATES is used with Micro Focus and other file systems that support it, the rules that govern how REWRITE and DELETE operations are handled are determined by the file system. The rules for Micro Focus are as follows:
    1. If the last record locked via a READ statement is still locked and it matches the primary key value specified in a REWRITE or DELETE statement, that record is the record rewritten or deleted.
    2. Otherwise, the first record with the matching key value is rewritten or deleted.

    For information about how HP COBOL KSAM handles REWRITE and DELETE with duplicate primary keys, see HP COBOL Conversions in Transitioning to ACUCOBOL-GT.

    The WITH NO DUPLICATES phrase is commentary. By default, duplicate primary key values are not allowed.

  17. The ALTERNATE RECORD KEY clause specifies additional record keys for an indexed file. If the WITH DUPLICATES phrase is present, these key values may contain duplicated values. Otherwise, each key value must be unique for a given key.

    You may specify the word NO in front of the word DUPLICATES in a declaration of an alternate indexed file key. This is useful for ICOBOL compatibility mode where, by default, alternate keys allow duplicates.

  18. Up to 16 seg-names may be specified in Micro Focus to indicate that a primary or alternate key consists of non-contiguous data elements. The key-name or alt-name is then a user-defined word that can be used in READ and START.
  19. The OPTIONAL phrase, if specified, indicates that the file need not be present when the program is run. The exact effects of this phrase are detailed in the discussion of the OPEN Statement. Note that the -Fp compile option causes all files to be treated as if the OPTIONAL phrase is present.
  20. The LOCK MODE clause specifies how file and record locking should be handled for the file. Each mode has the following characteristics:
    AUTOMATIC | Each time a record is read from a file open for I/O, that record is locked unless the WITH NO LOCK option is used on the READ statement. Files open for INPUT do not lock records
    MANUAL | Records read from a file with manual locking are locked only if the WITH LOCK option is used on the READ statement. Like automatic mode, files open for INPUT do not lock records even if WITH LOCK is specified
    EXCLUSIVE | Exclusive mode files are opened with a lock on the entire file. No locking options may be specified on an OPEN statement associated with an exclusive mode file. Instead, files opened for INPUT are treated as if they were opened with the ALLOWING READERS phrase, and files opened for OUTPUT, I-O, or EXTEND are treated as if they were opened with the ALLOWING NO OTHERS phrase. If the WITH MASS-UPDATE phrase is used, the MASS-UPDATE option is implied for each OPEN (except for OPEN INPUT). See the OPEN Statement for details on these options
  21. If the COLLATING SEQUENCE phrase is used, the alphabet-name is the name of an alphabet declared in Special-Names. This alphabet can be standard or can be a custom alphabet defined by the programmer to allow special handling. For example, upper-case and lower-case letters could be mapped together so that two keys that are alphabetically the same (but differ in case) would be treated as the same letter. European character sets can also be re-ordered in Special-Names (so that keys are sorted alphabetically).
  22. If the LOCK ON MULTIPLE RECORDS phrase is used, the program may lock more than one record in the file at once. If the MULTIPLE option is not used, each I-O statement automatically unlocks the currently locked record before executing. When the MULTIPLE option is used, record locks are released only when an UNLOCK or a CLOSE statement is executed for the file. The ROLLBACK clause is useful when you compile with -Fl, which enables single locking rules as the lock mode default. When the ROLLBACK clause is used with this phrase, multiple locking rules are enabled for the file, regardless of the compiler option used.
  23. If the LOCK phrase is omitted, LOCK MODE IS AUTOMATIC is implied, unless the -Fm compiler option is used, in which case LOCK MODE IS MANUAL is implied. In ICOBOL compatibility mode (-Ci), the default is LOCK MODE IS MANUAL WITH MULTIPLE RECORDS.
  24. The RECORD DELIMITER and RESERVE AREA clauses are treated as commentary by the compiler.
  25. If the ROLLBACK clause is specified, WITH LOCK ON MULTIPLE RECORDS will automatically be in effect. However, if you compile with the -Fl option, you must specify multiple locking rules for the files that need them.
  26. If the ROLLBACK clause is specified, the runtime will automatically effect a START TRANSACTION before opening the file, and a COMMIT after opening it. Thus, every OPEN of the file will automatically be done within a transaction; the COBOL code need not explicitly include the START TRANSACTION and COMMIT.
  27. It is possible that a RECORDING MODE clause may appear in the IBM DOS/VS COBOL -Cv compatibility mode and be ignored by the ACUCOBOL-GT compiler.
Parent topic: Input-Output Section


I-O-Control Paragraph

The I-O-CONTROL paragraph specifies input-output techniques to be used for the program's files.

General Format

I-O-CONTROL
    [ APPLY {LOCK-HOLDING } ... ON {file} ... ] ...
            {PRINT-CONTROL}
    [ SAME [RECORD    ] AREA FOR {file} ... ] ...
           [SORT      ]
           [SORT-MERGE]
    [ MULTIPLE FILE TAPE CONTAINS
      { tape-file [ POSITION pos ] } ... ] ... .

Syntax Rules

  1. file and tape-file name a file described by a SELECT clause in the FILE-CONTROL paragraph.
  2. A file name cannot appear in more than one SAME RECORD AREA clause.
  3. If file is a sort file, one of the RECORD, SORT, or SORT-MERGE options must be used in a SAME AREA clause.
  4. SORT and SORT-MERGE are equivalent.
  5. At least one file must be a sort file if the SORT or SORT-MERGE option is used.
  6. Pos must be an integer literal.
  7. You may put APPLY clauses of the IBM DOS/VS COBOL type into the I-O-CONTROL paragraph, but only when the compiler is in the IBM DOS/VS COBOL compatibility mode. The clauses of the I-O-CONTROL paragraph may be arranged in any order, and the existing APPLY clause may be used, regardless of the compiler mode. See IBM DOS/VS COBOL Conversions, in Transitioning to ACUCOBOL-GT for more information.

General Rules

  1. The APPLY clause modifies various characteristics of each file.
    1. If the PRINT-CONTROL option is specified, the named file must be a sequential file. This option causes the file to be treated as a print file. This has the same effect as specifying "PRINT" in the file's ASSIGN clause.
    2. If the LOCK-HOLDING option is used, record locks on the file will not be automatically released by any I-O statement. Instead, only the UNLOCK and CLOSE statements will release any record locks held on the file. This option has the same effect as the LOCK ON MULTIPLE RECORDS phrase in the file's SELECT.
  2. The SAME AREA clause indicates that the compiler should share file information areas for the named files. ACUCOBOL-GT automatically applies the most efficient use of memory possible for file information areas and treats this clause as commentary. In ICOBOL compatibility mode, the SAME AREA clause is treated as a SAME RECORD AREA clause (see below).
  3. The SAME RECORD AREA clause indicates that the named files should share the same memory area for their current logical records.
  4. The SAME RECORD AREA clause is identical to an implicit redefinition of the shared files' record areas.
  5. The SAME SORT AREA clause indicates that the same memory should be used for each file. Because ACUCOBOL-GT dynamically allocates memory to sort files as needed and then discards the memory when finished, this phrase is treated as commentary by the compiler.
  6. The MULTIPLE FILE TAPE clause is treated as commentary.
Parent topic: Input-Output Section


Data Division

  • Data Structures
  • Data Names
  • Data Division Format
  • File Section
  • WORKING-STORAGE Section
  • LINKAGE Section
  • Record Description Entry
  • Screen Section
  • Screen Description Entry
Parent topic: ACUCOBOL-GT Reference Manual


Data Structures

The Data Division describes the data used by the program in both physical and logical terms.

COBOL data structures are defined and described in the following sections.

  • Record Description
  • Level-Numbers
  • Classes of Data
  • Standard Alignment Rules
  • Table Handling
  • Large Data Handling
  • File Types
  • Floating-Point Data
Parent topic: Data Division


Record Description

All user-defined data used in a COBOL program belongs to one or more logical records. A logical record is defined by a record description entry. Logical records may correspond to actual disk records (by being defined in the File Section), or they may simply be areas of computer memory used by the program. A record description entry is itself composed of one or more data description entries. Each data description entry defines one COBOL data item.

Logical records can be divided into a hierarchy of individual data items. Subdivision can continue for each of the record's parts. The lowest level subdivision of a record is the elementary data item. Elementary data items are never subdivided. A logical record is either an elementary data item or a set of elementary data items.

A group item is a piece of data that contains other subordinate data items. These subordinate items may be either elementary data items or other group items. The lowest level group item is always a sequence of one or more elementary data items.

Parent topic: Data Structures


Level-Numbers

Level-numbers are used to describe the hierarchical organization of a record. Level-numbers that describe this hierarchy range from 01 through 49.

The topmost data item is the record. It always has a level-number of 01. Items that are included in the record have greater (although not necessarily consecutive) level-numbers.

All items subordinate to a group item must have level-numbers greater than the group's level-number. The end of a group item is delimited by the next data description entry that has a level-number less than or equal to the group's level-number.

Four special level-numbers are used to specify special types of data. They are never used in a hierarchical structure. Instead, they define the following special types:

  • Level-number 66 identifies a RENAMES item which regroups other data items.
  • Level-number 77 identifies an elementary data item in the Working-Storage or Linkage sections. These are essentially identical to a level 01 elementary data item. The level-number is used to emphasize that the data item is not part of a hierarchy and cannot itself be subdivided.
  • Level-number 78 associates a value with the name of a constant.
  • Level-number 88 identifies a condition-name and its values

The following example shows how level-numbers define a record's hierarchy and shows how records, groups, and elementary items interact. The items are indented to display the hierarchy. This is a recommended programming practice but is not required by COBOL.

01  EMPLOYEE-RECORD.                    (record)
    03  EMPLOYEE-KEY.                   (group)
        05  DEPARTMENT-CODE             (elementary)
        05  EMPLOYEE-NUMBER             (elementary)
    03  EMPLOYEE-IDENTIFICATION.        (group)
        05  EMPLOYEE-NAME               (elementary)
        05  EMPLOYEE-ADDRESS.           (group)
            07  STREET-ADDRESS-1        (elementary)
            07  STREET-ADDRESS-2        (elementary)
            07  CITY                    (elementary)
            07  STATE                   (elementary)
            07  ZIP-CODE                (elementary)
        05  EMPLOYEE-RACE               (elementary)
        05  MARRIAGE-STATUS             (elementary)
    03  PAYROLL-INFORMATION.            (group)
        05  SALARY                      (elementary)
        05  PAY-FREQUENCY               (elementary)
        05  DEDUCTION-CODE-1            (elementary)
        05  DEDUCTION-CODE-2            (elementary)
        05  SICK-ACCRUAL-RATE           (elementary)
        05  VACATION-ACCRUAL-RATE       (elementary)
Parent topic: Data Structures


Classes of Data

Depending on how a data item is defined, it belongs to one of the five following categories:

  1. Alphabetic
  2. Alphanumeric
  3. Alphanumeric Edited
  4. Numeric
  5. Numeric Edited

These categories are further grouped into the following classes:

  1. Alphabetic class: alphabetic
  2. Numeric class: numeric
  3. Alphanumeric class: alphanumeric, alphanumeric edited, numeric edited

Every elementary item is classified into one of these classes and categories by its PICTURE clause. Elementary items that do not have a PICTURE clause are in the numeric category.

Group items always belong to the alphanumeric category regardless of the categories of any elementary items they contain. A group item may be used in any place an alphanumeric item is allowed.

Parent topic: Data Structures


Standard Alignment Rules

The standard alignment rules define how characters are positioned in a data item when the item is receiving data. Positioning depends on the category of the receiving item.

  1. For a numeric receiving item, the data is aligned by decimal point. Truncation or zero fill occurs as necessary. If no decimal point is explicitly stated, then the item is treated as if it had a decimal point after its rightmost character.
  2. For a numeric edited item, the data is aligned by decimal point with zero fill or truncation as needed. Editing requirements can replace leading zeros with some other symbol.
  3. For alphabetic, alphanumeric, and alphanumeric edited items, the data is aligned at the leftmost character position in the item. Space fill or truncation occurs on the right as needed.

The JUSTIFIED clause can change the standard alignment rules. For details, see the JUSTIFIED clause in JUSTIFIED Clause. The --TruncANSI compile option alters the truncation rules for COMP-5 items. See Truncation Options in the ACUCOBOL-GT User’s Guide for more information.

Parent topic: Data Structures


Table Handling

Tables of data are common components of business data processing problems. You define tables of data items in COBOL by including the OCCURS clause in their data description entries. This clause specifies that the item is to be repeated as many times as stated. The item is considered to be a table element, and its name and description apply to each repetition or occurrence. Because each occurrence of a table element does not have a unique data name assigned to it, you can refer to a desired occurrence only by specifying the data-name of a table element, along with the occurrence number of the desired element. The occurrence number is known as a subscript.

The number of occurrences of a table element may be specified to be fixed or variable. Although the number of occurrences of a table may be variable, the physical size of the table in computer memory is always fixed.

To define a one-dimensional table, use an OCCURS clause as part of the data description of the table element. The OCCURS clause must not appear in the description of group items which contain the table element. The following example shows a one-dimensional table defined by the item TABLE-ELEMENT.

01  TABLE-1.
    03  TABLE-ELEMENT OCCURS 20 TIMES.
        05  SUB-ELEMENT-1 ...
        05  SUB-ELEMENT-2 ...

In the preceding example, the complete set of occurrences of TABLE-ELEMENT has been assigned the name TABLE-1. However, you need not give a group name to a table unless you want to refer to the complete table as a unit. In the preceding example, TABLE-ELEMENT, SUB-ELEMENT-1, and SUB-ELEMENT-2 are all repeated data items and require subscripts.

Defining a one-dimensional table within each occurrence of an element of another one-dimensional table gives rise to a two-dimensional table. For example:

01  TABLE-2.
    03  BAKER OCCURS 20 TIMES.
        05  CHARLIE ...
        05  DOG OCCURS 5 TIMES ...

In the preceding example, DOG is a two-dimensional table; BAKER and CHARLIE are both one-dimensional.

Repeat this pattern to form multi-dimensional tables. Tables may have no more than 15 dimensions.

Parent topic: Data Structures


Large Data Handling

All COBOL data items may be larger than 64 KB in size, with some minor limitations:

  • A file's maximum record size is 64MB, so no data item in the FILE SECTION may exceed 64MB.
  • A data item with a size greater than 64KB may not be given a VALUE phrase.

Data items larger than 64KB may be used with most verbs, and data items larger than 64KB may be reference modified.

Note: Earlier versions of ACUCOBOL-GT have different limitations. Refer to the appropriate version of your ACUCOBOL-GT documentation for details.
Parent topic: Data Structures


File Types

ACUCOBOL-GT manages four types of file organization. These are:

  1. Sequential Files - are ordered by the historical order in which records are written to the file.
  2. Relative Files - contain records that are identified by their record number, where the first record in the file is record number one. Relative files are ordered by ascending record numbers.
  3. Indexed Files - contain records that have one or more key fields. Records in an indexed file are ordered by ascending values in these key fields. Each key of an indexed file represents an ordered sequence by which the records can be accessed. One of the key fields, known as the primary key, must contain a unique value for each record and is used to identify records uniquely.
  4. Sort Files - are used only by the SORT, MERGE, RELEASE, and RETURN verbs. These are used to sort and merge records.

There are also four record types. These are:

  1. Fixed-length Records - these records are a constant size.
  2. Variable-length Records - these records contain information about the length of each record, which may vary.
  3. Text Records - are sequential file records that contain text data. Text files should generally contain only USAGE DISPLAY fields, because the binary information contained in other types of fields may inadvertently resemble line-length delimiters used by the host computer system (e.g., carriage return or line-feed characters). Text records may optionally have trailing spaces automatically removed from them by the runtime system. This is determined by the device type named in the file's ASSIGN phrase.
  4. Print Records - are text records that additionally contain printer carriage control information. Only sequential files may be print files. Print records have trailing blanks removed from them when they are written to the file. This is done to improve printing performance for printers that use serial communications. Unless otherwise noted, a print file follows the same rules as a text file.

The organization of a file is determined by the file's SELECT clause of the Environment Division and its FD or SD clause of the Data Division. The record type is determined by the first of the following rules that applies:

  1. If the file's ASSIGN clause has the PRINT option, print records are used.
  2. If any WRITE statement that references the file contains the ADVANCING phrase, print records are used.
  3. If LINAGE is specified for the file, print records are used.
  4. If PRINT-CONTROL is specified, print records are used.
  5. If the file's SELECT has the LINE SEQUENTIAL clause, text records are used.
  6. If the file's device type is DISPLAY or KEYBOARD, text records are used.
  7. In RM/COBOL compatibility mode, if the file is sequential and -Cb is not specified, text records are used.
  8. If the file's FD or SD contains a RECORD clause, variable-length records are used if the IS VARYING IN SIZE phrase is used or if both a minimum and maximum record size is specified. If only a single record size is specified, then fixed-length records are used.
    Note: For objects compiled for runtimes earlier than version 10, the compiler has an internal restriction of at least 6 bytes for SORT FILE records. If a record is shorter than that, the compiler detects it and pads the record to 6 bytes. Note also that in versions prior to 5.0, using SORT FILE with records shorter than 6 bytes would cause crashes.
  9. If multiple record layouts are declared for the file and these records are not all the same size, variable-length records are used.
  10. If the -Cf flag is used, then any variable-length record is made fixed-length.
  11. If none of the preceding rules applies, then fixed-length records are used.
Parent topic: Data Structures


Floating-Point Data

A floating-point item is a numeric data item that allows for a very wide range of values. However, compared to other numeric data types in COBOL, floating-point data is less accurate. Most computer languages use floating-point to represent non-integer values. This makes floating-point a good method for sharing non-integer data with these other languages.

Floating-point data items differ in several ways from normal numeric data items:

  • Floating-point items are stored in a machine-dependent format. In particular, they are stored in a format that is native to each machine. There are many floating-point formats currently in use by different machines, so floating-point data should not be considered portable.
  • Floating-point items do not have pictures associated with them. Instead, floating-point items are either 4 or 8 bytes in size. The size of the item determines the range of values it can hold.
  • The range of values that can be stored in a floating-point item is machine-dependent.

Because floating-point items do not maintain accuracy very well, you should limit their use. Some examples where floating-point is appropriate are:

  • You need to share non-integer data with another language such as C or FORTRAN.
  • You need to hold very large or very small values that exceed the usual 18 digits available in COBOL.
  • You need to process existing data that contains floating-point values.
  • Using Floating-Point Data
Parent topic: Data Structures


Using Floating-Point Data

Generally speaking, you may use a floating-point data item anywhere that you can use a non-integer data item. Data moved to or from a floating-point item is converted to the appropriate format.

If you use a floating-point item in an arithmetic expression, then that expression is computed by converting all the values to double-precision floating-point and doing the arithmetic using the machine's conventions for double-precision math. The result is then converted to the type appropriate for the destination.

Parent topic: Floating-Point Data


Data Names

The programmer assigns data names to COBOL data items in order to refer to those items in the program. Data names typically must be unique so that the compiler can know which data item the programmer is referring to. Data names that do not uniquely identify a data item may be made unique through qualification and subscripting. The programmer may also create new data names by reference modification. These three techniques are explained in the next three subsections.

  • Qualification
  • Subscripting
  • Reference Modification
  • Condition-Name Level 88
  • RECORD-POSITION
Parent topic: Data Division


Qualification

Every user-defined name explicitly referenced in a COBOL program must be uniquely defined in one of these ways:

  1. No other name has the same spelling and hyphenation.
  2. The name is unique within the context of a REDEFINES clause.
  3. The name exists within a hierarchy of names, and reference to the name can be made unique by mentioning one or more of the higher level names in the hierarchy.

These higher-level names are called qualifiers. Identical user-defined names may appear in a source program; however, uniqueness must then be established through qualification for each user-defined name explicitly referenced. All available qualifiers need not be referenced as long as uniqueness is established.

General Format

Format 1
{data-name-1} { {OF} name-2 } ... [ {OF} file-name ]
{cond-name  }   {IN}                {IN}

Format 2

{data-name-1} {OF} file-name
{cond-name  } {IN}
Format 3
paragraph-name {OF} section-name
               {IN}

Format 4

lib-name {OF} dir-name
         {IN}

Format 5

LINAGE-COUNTER {OF} file-name
               {IN}

Syntax Rules

  1. For each non-unique user-defined name that is explicitly referenced, uniqueness must be established through a sequence of qualifiers that precludes any ambiguity.
  2. A name may be qualified even though it does not need qualification.
  3. IN and OF are equivalent.
  4. In Format 1, each qualifier must be the name associated with a group item to which the item being qualified is subordinate, or the name of a condition-variable with which the condition-name being qualified is associated. Qualifiers are specified in the order of successively more inclusive levels in the hierarchy.
  5. If the program contains explicit references to a paragraph-name, the paragraph-name cannot appear more than once in the same section. A paragraph-name need not be qualified in a reference from within the same section that contains paragraph-name.
  6. The LINAGE phrase of a file's FD creates an implicit data item called LINAGE-COUNTER. If more than one file in a program contains a LINAGE phrase, then reference to a file's LINAGE-COUNTER must be qualified by the name of the file.
  7. If both qualification and subscripting are used in a data reference, the qualification is done first.
  8. If both qualification and reference modification are used in a data reference, the qualification is done first.
  9. A Format 4 form of qualification is used with the COPY statement. It is described in that section.
Parent topic: Data Names


Subscripting

Subscripting is used when reference is made to an individual element of a table.

General Format

{data-name     }  ( { index-val [ {+} integer  ] } ...)
{condition-name}                  {-}

Syntax Rules

  1. index-val must be either an integer literal, an integer elementary data item, or an index name. It may be qualified.
  2. data-name and condition-name must be subordinate to an OCCURS clause.
  3. integer must be an integer literal.
  4. The number of subscripts must equal the number of OCCURS clauses in the description of the table element being referenced. When more than one subscript is required, they are written in the order of successively less inclusive dimensions of the table.
  5. If both qualification and subscripting of a data name are being used, the qualification is done first.
  6. If both subscripting and reference modification of a data name are being used, the subscripting is done first.

General Rules

  1. The value of the subscript must be a positive integer. The lowest occurrence value is represented by the value 1. Each successive element of a table within a dimension is referenced by occurrence numbers of 2, 3, 4, and so on. The highest permissible occurrence number for any given dimension of a table is the maximum number of occurrences of the item as specified by the associated OCCURS clause.
  2. If integer is specified, the value of the subscript is determined by adding or subtracting the integer from index-val. This modified value is subject to all of the conditions of rule 1 above.
  3. By default, it is not an error to reference a table element beyond the last one in the table, but the results are undefined and may adversely affect your program. In fact, this is the single most frequent cause of memory access violation errors. Use the -Za compiler option to cause an error message to display whenever an out-of-bounds table element is referenced. The error text is: Index out of bounds. This error is an intermediate runtime error that can trigger the execution of installed error procedures.
Parent topic: Data Names


Reference Modification

Reference modification is a syntax for referencing a portion (substring) of a data item. The reference defines a temporary, unique data item. Reference modification may be used anywhere in the Procedure Division.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format

data-name ( leftmost-position : [length] )

Syntax Rules

  1. leftmost-position and length are arithmetic expressions.
  2. Unless otherwise specified, reference modification is allowed anywhere a data item of the class alphanumeric is permitted.
  3. data-name may be qualified or subscripted. Reference modification is done after both qualification and subscripting.

General Rules

  1. Each character of the data item referenced by data-name is assigned an ordinal number starting at one for the leftmost position and incrementing by one for each character in the item.
  2. Reference modification for an operand is evaluated as follows:
    1. If subscripting is specified, the reference modification is evaluated immediately after the evaluation of the subscripts.
    2. If subscripting is not specified, the reference modification is evaluated at the time subscripting would have been evaluated if subscripts had been specified.
  3. Reference modification creates a unique data item which is a subset of data-name. This unique data item is defined as follows:
    1. The evaluation of leftmost-position specifies the leftmost character of the unique data item relative to the start of data-name. Evaluation of leftmost-position must result in an integer greater than zero and less than or equal to the number of characters contained in data-name.
    2. The evaluation of length specifies the size of the unique data item. The evaluation of length must result in a positive integer. The sum of leftmost-position and length must be less than or equal to the number of characters contained in data-name, plus one. If length is not specified, the unique data item extends through the rightmost character of data-name.
  4. The unique data item is considered an elementary data item without the JUSTIFIED clause. It has the same class and category as data-name except that categories numeric, numeric edited, and alphanumeric edited are treated as class and category alphanumeric.
  5. If the reference modification start or length parameter is out of range for the item it references, a runtime error occurs. How the runtime responds depends on the value of the WARNINGS configuration variable. By default, the runtime attempts to correct the error (see rule 6, below), and the warning message Reference modifier range error is displayed or sent to the error file. This error is an intermediate runtime error that can trigger the execution of installed error procedures.
  6. By default, the runtime silently corrects reference modification range errors by applying the following rules:
    • A start reference less than 1 is treated as 1. For example, var(0:3) is treated as var(1:3).
    • A length reference less than 0 is treated as 0. Moving a zero-byte item is equivalent to moving spaces to the destination item. A zero-byte destination is not affected by the move. In a STRING statement, a length of zero for a string source is treated as 1, not 0.
    • A start plus length reference that is past the end of the item is treated as meaning to the end of the item. For example, if the var is a PIC X(5) item, var(4:23) is treated as var(4:2).

    The WARNINGS runtime configuration variable provides some control over how the runtime handles reference modification range errors.

CAUTION:
Reference modification is allowed on source-item and dest-item of a Format 1 MOVE statement. However, when reference modification is used, source-item and dest-item should not reference the same item (or memory location). See general rule 7 of the MOVE Statement in Procedure Division.

Code Examples

Reference modification is akin to substringing in other programming languages. Reference modification is very useful for referencing a component part of a composite string. For example, it might be used to reference the area code digits of a 10-character string containing a phone number (area code + seven digits):

01  PHONE-NUMBER  PIC 9(10) VALUE 3017728134.
{ . . . }
PHONE-NUMBER (1:3).
*The reference modification begins at position 1
*of string PHONE-NUMBER and has a length of 3.
*The reference modification value = "301"

For the following code examples, assume these data items:

01 ACCOUNT-CODE PIC X(20) VALUE "AB700648xSMITHxxCLA1".
01 ACCOUNT-NAME PIC X(6)  VALUE ALL SPACES.
01 ACCT-CLASS-1 PIC X(4)  VALUE "CLA1".

Code example 1:

MOVE ACCOUNT-CODE (10:6) TO ACCOUNT-NAME.
*This reference modification selects the
*characters that form the name portion of
*ACCOUNT-CODE.  The reference starts at position
*10 and has a length of 6 characters.
*The ACCOUNT-CODE substring = "SMITHx"

Code example 2:

IF ACCOUNT-CODE (17:) = ACCT-CLASS-1 THEN
*When the reference modification does not
*include a length, the reference begins at the
*value specified and extends to the end of the
*data item.
*The ACCOUNT-CODE substring = "CLA1"

Highlights For First-time Users

  1. Reference modification may be used anywhere in the program where an alphanumeric data item may be referenced.
  2. A reference modification does not create a persistent data item. Unless the result of the reference modification is assigned to a compatible data object, you can refer to the value of the reference modification later in the program only by repeating the reference modification.
  3. The reference-modified data item is treated as an alphanumeric field.
Parent topic: Data Names


Condition-Name Level 88

Level-number 88 designates a condition-name entry. Level 88s are used to assign names to values at execution time. Thus, a condition-name is not the name of an item, but rather the name of a value. A level 88 doesn't reserve any storage area.

Each level 88 must be associated with a data item and must immediately follow that item in the Data Division. The associated data item is called a condition-variable. A level 88 may name a specific value, a set of values, or a range of values. For example:

05  student-status    pic 9(2).
    88  kindergarten  value 0.
    88  elementary    values are 1 through 6.
    88  jr-high       values 7, 8, 9.
    88  high-school   values are 10 through 12.

Condition-names are often used in the Procedure Division as a test (usually with an IF statement) to specify conditions under which control will pass to another part of the program. They can make sentences much more meaningful to the reader. For example, if you've defined the condition-names shown above, then you could write this code:

if kindergarten
    perform assign-half-day-schedule.

without the condition-name, you would have to write:

if student-status = "0"
    perform assign-half-day-schedule.

If you defined this condition-name:

07 priority-code        pic x.
   88 highest-priority  value "d".

then you could write this easily understood code:

if highest-priority perform fill-order-at-once.

without the condition-name, you would have to write:

if priority-code = "d" perform fill-order-at-once.

Thus, real benefit comes from choosing a meaningful name for each value or set of values.

Setting a condition-name to TRUE is equivalent to moving any one of its values to the associated condition-variable. For example, note how the SET verb is used below to establish the truth of the condition:

05  end-of-shipping-file    pic x value "n".
    88  no-more-shipments   value "y".

...

perform process-daily-arrivals
  until no-more-shipments.

...

read shipping-file
  at end set no-more-shipments to true.

The same result could have been achieved with this code:

read shipping-file
  at end move "y" to end-of-shipping-file.

If explicitly referenced, a condition-name must be unique or must be made unique through qualification or subscripting. If qualification is used to make a condition-name unique, the associated condition-variable may be used as the first qualifier. The hierarchy of names associated with the condition-variable may be used in further qualification. If references to a condition-variable require subscripting, then references to the associated condition-name also require the same combination of subscripting.

For more information about condition-names, see Data Description Entry, VALUE Clause, and the SET Statement.

Parent topic: Data Names


RECORD-POSITION

The RECORD-POSITION construct allows you to refer to a data item by creating a numeric literal representing the location of the data item within a record.

General Format

RECORD-POSITION OF data-name

Syntax Rules

  1. data-name must refer to a data item with a level number of 01 through 50 or 77. data-name may be qualified, but may not be subscripted or reference modified.
  2. The RECORD-POSITION phrase is allowed anywhere a numeric literal data item may appear.

General Rules

  1. The RECORD-POSITION phrase creates a numeric literal whose value is the character position of data-name within its record, as follows:
    • If data-name is a level 01 or 77 data item, then the value is 1.
    • Otherwise, the value is the character position of the start of data-name within its containing level 01 group item. Character positions start numbering at 1.
  2. If data-name refers to a table item, the value is computed from the first occurrence of that item.
  3. The format of the resulting literal is the same as a PIC 9(9) DISPLAY data item.

Code Examples

If you assume the following group item:

01  GROUP-1.
    03  ELEM-1  PIC X(10).
    03  ELEM-2  PIC X(10).
    03  GROUP-2.
        05  ELEM-3
            OCCURS 10 TIMES  PIC X(10).
        05  ELEM-4  PIC X(10).

then, the following procedure division code:

DISPLAY RECORD-POSITION OF ELEM-1, CONVERT, LEFT
DISPLAY RECORD-POSITION OF ELEM-2, CONVERT, LEFT
DISPLAY RECORD-POSITION OF ELEM-3, CONVERT, LEFT
DISPLAY RECORD-POSITION OF ELEM-4, CONVERT, LEFT

would produce the following output:

1
11
21
121

The RECORD-POSITION construct is particularly useful with the DATA-COLUMNS property of the list box and grid controls. For example, in a list box control, you might have a line that reads:

data-columns - (1, 13, 24, 33 )

changing the line to:

data-columns = (
    record-position of data-key-1,
    record-position of data-city,
    record-position of data-state,
    record-position of data-amount )

makes it easier to understand. With this syntax, changes to the record format do not need to be echoed in the data-columns format, so this is also easier to maintain.

Parent topic: Data Names


Data Division Format

General Format

[ DATA DIVISION. ]

[ FILE SECTION.
   [ file-desc { record-description } ... ] ... ]
   [ sort-desc { record-description } ... ]

[ WORKING-STORAGE SECTION.
   [ record-description ] ... ]

[ LINKAGE SECTION.
   [ record-description ] ... ]

[ SCREEN SECTION.
   [ screen-description ] ... ]

Syntax Rules

  1. The division header is optional for the Data Division.
  2. The FILE SECTION header is optional.

General Rules

The Data Division entries are described in:

  1. The File Section defines the structure of data files.
  2. A file-desc entry and its associated record-descriptions specify the format, layout, and sizes of a file's logical records. A sort-desc entry specifies the layout and sizes of a sort file's logical records.
  3. For each file described by a SELECT in the Environment Division, a corresponding file-desc or sort-desc must be made in the Data Division.
  4. The Working-Storage Section describes the records and independent data items which are not part of data files but are developed and processed by the program internally.
  5. Each record-description in Working Storage describes the format, layout, and size of an internal data item.
  6. Data items in Working Storage can be given initial values (see VALUE Clause). Items that are not explicitly initialized are set to spaces, or the value specified with the -Dv compile option, when the program is in its initial state. This may or may not be a valid value for the data item.
  7. The Linkage Section is used only in a called program. It defines the data available from the calling program. Both the called and calling program can use this data.
  8. To access data described in the Linkage Section, the called program may specify a USING phrase in its Procedure Division header. An alternative way to do this is through the SET ADDRESS OF statement. In the example below, note that the USING phrase has been omitted from the Procedure Division header.
    LINKAGE SECTION.
01  my-var       pic x(30).

PROCEDURE DIVISION.
main-logic.
    if switch-1
       set address of my-var to msg-1
    else
       set address of my-var to msg-2
    end-if.
    display my-var.

    See Procedure Division Statements for additional information on the SET Statement.

  9. The Screen Section describes the format, layout, and behavior of console screen items. These screen items are used with the ACCEPT and DISPLAY verbs to perform single- and multi-field console I/O.
Parent topic: Data Division


File Section

The File Section describes the record-level information about the files that the program uses.

General Format

FILE SECTION.

   [ file-desc { record-description } ... ] ...
   [ sort-desc { record-description } ... ]

General Rules

  1. The File Section header is followed by a series of file-desc entries and sort-desc entries.
  2. A file-desc entry consists of a level indicator (FD), a file name, and a series of independent clauses. These clauses specify various logical and physical record attributes.
  3. A sort-desc entry consists of a level indicator (SD), a file name, and a series of independent clauses. These clauses specify various record attributes.
  • File Description Entry
  • Sort File Description Entry
  • IS EXTERNAL Clause
  • BLOCK CONTAINS Clause
  • RECORD Clause
  • LABEL RECORDS Clause
  • VALUE OF LABEL Clause
  • VALUE OF FILE-ID Clause
  • CODE-SET Clause
  • DATA RECORDS Clause
  • LINAGE Clause
Parent topic: Data Division


File Description Entry

A file description entry describes the physical structure, identification, and record names for a program's data files.

General Format

FD file-name [IS EXTERNAL] [IS GLOBAL]

   [BLOCK CONTAINS [min TO] max  {RECORDS   } ]
                                 {CHARACTERS}

   [RECORD { CONTAINS [min TO] max CHARACTERS  } ]
           { IS VARYING IN SIZE [ FROM min ]   }
           {   [ TO max ] CHARACTERS           }
           {   [ DEPENDING ON depend ]         }

   [ LABEL  { RECORD IS   }  {STANDARD} ]
            { RECORDS ARE }  {OMITTED }

   [ VALUE OF LABEL IS label-lit ]

   [ VALUE OF { FILE-ID } IS id-name ]
              { ID      }

   [ CODE-SET IS alphabet ]

   [ DATA  { RECORD IS   }  {record-name} ... ]
           { RECORDS ARE }

   [ LINAGE IS page-size LINES

     [ WITH FOOTING AT footing-line ]

     [ LINES AT TOP top-lines ]

     [ LINES AT BOTTOM bottom-lines ] ] .

Syntax Rules

  1. file-name must refer to a file name contained in a SELECT clause in the Environment Division.
  2. The clause IS EXTERNAL must immediately follow the file-name in each program that declares the file.
  3. An external file must have the same file-name in each COBOL program that declares it, and must be described the same way in each program.
  4. The other clauses following file-name can appear in any order.
  5. One or more record description entries must follow a file description entry.
  6. The LINAGE phrase may be specified only for an FD associated with a sequential file.

General Rule

The file description entry clauses are described separately in the online help.

Parent topic: File Section


Sort File Description Entry

A sort file description entry describes the physical structure for a sort file.

General Format

SD file-name
   [ RECORD { CONTAINS [min TO] max CHARACTERS } ]
            { IS VARYING IN SIZE [ FROM min ]  }
            {        [ TO max ] CHARACTERS     }
            {        [ DEPENDING ON depend ]   }

   [ DATA { RECORD IS   } {record-name} ... ]
          { RECORDS ARE }

   [ VALUE OF FILE-ID IS id-name ]

Syntax Rules

  1. file-name must refer to a file name contained in a SELECT clause in the Environment Division. That SELECT clause may contain only ASSIGN and FILE STATUS clauses. However, a PASSWORD clause, TRACK-AREA clause, PROCESSING MODE clause, RECORDING MODE clause, FILE-LIMIT clause, VALUE OF clause, and APPLY clause may appear when the compiler is in the IBM DOS/VS COBOL compatibility mode. These phrases are scanned, but otherwise they are ignored.
  2. The clauses following file-name may appear in any order.
  3. id-name must be either a non-numeric literal or the name of an alphanumeric data item in Working Storage. The value of this name is used as the file's external name.
  4. If a file-spec is specified in the file's ASSIGN clause, id-name must be identical to file-spec.
  5. One or more record description entries must follow a sort file description entry.

General Rules

  1. No I/O statement may refer to a file described by a sort file description entry. Only the SORT and MERGE statements may refer to file-name.
  2. The sort file description entry clauses are further described in this section.
Note: For objects compiled for runtimes earlier than version 10, the compiler has an internal restriction of at least 6 bytes for SORT FILE records. If a record is shorter than that, the compiler detects it and pads the record to 6 bytes. Note also that in versions prior to 5.0, using SORT FILE with records shorter than 6 bytes would cause crashes.
Parent topic: File Section


IS EXTERNAL Clause

The IS EXTERNAL clause specifies that the file is shared by more than one program in a run unit.

General Format

IS EXTERNAL

Syntax Rules

  1. The IS EXTERNAL declaration must be made in all the programs that access the file or item externally. The file must be declared external by each program in the run unit that will share a file's current state and record area.
  2. The COBOL name of the file must be the same for all the programs that declare the file.
  3. Each program that declares an external file must describe the file the same way.

General Rules

  1. If one program opens the file, it is open for all programs that declare the same file.
  2. If one program moves the record pointer, the record pointer moves in all the programs that declare the file.
  3. Any data placed in the record area is accessible by all the programs that declare the file.
Parent topic: File Section


BLOCK CONTAINS Clause

The BLOCK CONTAINS clause specifies the size of a physical record.

General Format

BLOCK CONTAINS [min-block TO] max-block {RECORDS   }
                                        {CHARACTERS}

Syntax Rules

  1. min-block is an integer literal which specifies the minimum block size.
  2. max-block is an integer literal which specifies the maximum block size.

General Rules

  1. The BLOCK CONTAINS clause specifies the physical record size.
  2. The min-block specification is treated as commentary by the compiler. However, if RM/COBOL compatibility mode is being used, and min-block is specified, then the entire BLOCK CONTAINS clause is ignored by the compiler.
  3. The compiler ignores the BLOCK CONTAINS clause for relative files.
  4. For Vision files, max-block should be a multiple of 512 up to 8192 (the value is the block size in bytes). For Version 3 and 2 files, max-block should not exceed 1024. If it does, Vision automatically reduces it to 1024.
  5. For sequential files, all input and output is done by blocks.
  6. The RECORDS phrase specifies the physical record size in terms of logical records. If the file contains variable-length records, then the exact block size will vary from machine to machine depending on how variable-length records are stored on the host machine. The record size used to compute the block size is equal to the largest logical record.
  7. The CHARACTERS phrase specifies the physical record size in terms of characters.
  8. The final block of a file may contain fewer characters than specified by the BLOCK CONTAINS clause.
  9. If no BLOCK CONTAINS clause is specified, the block size is set to one record. For files with variable-length records, the block size is set to the current record size (not necessarily the largest).
  10. Records read from a file with variable-length records are internally blocked by ACUCOBOL-GT if no BLOCK CONTAINS clause is specified. This allows for efficient processing of these files on input while still allowing for line-by-line control over an output device (such as a printer).

See Handling Files for details on the handling of file blocking.

Parent topic: File Section


RECORD Clause

The RECORD clause describes the size of the logical records.

General Format

RECORD { CONTAINS [min-rec TO] max-rec CHARACTERS }
       { IS VARYING IN SIZE [ FROM min-rec ]      }
       {       [ TO max-rec ] CHARACTERS          }
       {       [ DEPENDING ON depend ]            }

Syntax Rules

  1. min-rec is an integer literal that defines the smallest record size.
  2. max-rec is an integer literal that defines the largest record size.
  3. depend is a numeric data item described in Working Storage or in Linkage. ddepend cannot be in the File Section.

General Rules

  1. This clause is never required, because the minimum and maximum record sizes of a file are computed by the compiler from the file's record descriptions. However, you may want to use this clause to indicate variable-length records.
    Note: For objects compiled for runtimes earlier than version 10, the compiler has an internal restriction of at least 6 bytes for SORT FILE records. If a record is shorter than that, the compiler detects it and pads the record to 6 bytes. Note also that in versions prior to 5.0, using SORT FILE with records shorter than 6 bytes would cause crashes.
  2. No record description for a file can contain more characters than specified by max-rec or fewer characters than specified by min-rec.
  3. If min-rec is omitted, it is set to be equal to max-rec.
  4. If the VARYING phrase is used, then the file has variable-length records. If the CONTAINS phrase is used, and both min-rec and max-rec are specified, the file will contain variable-length records. If the CONTAINS phrase is used and only max-rec is specified, then the file will contain fixed-length records.
  5. If the DEPENDING ON phrase is used, the size of the record written or rewritten to the file is set according to the value of depend. When a record is read from the file, depend is set to the size of the record found. Using the DEPENDING ON phrase automatically implies that the file has variable-length records.
Note: Other source statements may take precedence over the RECORD clause in determining the record type. The complete rules for determining a file's record type are described in File Types.
Parent topic: File Section


LABEL RECORDS Clause

The LABEL RECORDS clause describes how file labels should be processed by the compiler.

General Format

LABEL  { RECORD IS   }  {STANDARD}
       { RECORDS ARE }  {OMITTED }

General Rule

This clause is ignored by the compiler.

Parent topic: File Section


VALUE OF LABEL Clause

This clause describes the values contained in a file's label records.

General Format

[ VALUE OF LABEL IS label-lit ]

Syntax Rule

label-lit must be a non-numeric literal.

General Rule

This clause is ignored by the compiler.

Parent topic: File Section


VALUE OF FILE-ID Clause

The VALUE OF FILE-ID clause specifies the file's external name. (This can also be accomplished by the file's ASSIGN clause. The VALUE OF FILE-ID clause is provided for compatibility with other COBOL compilers.)

General Format

[ VALUE OF { FILE-ID } IS id-name ]
           { ID      }

Syntax Rules

  1. id-name is either a non-numeric literal or the name of an alphanumeric data item in Working-Storage. The value of this name is used as the file's external name.
  2. If a file-spec is specified in the file's ASSIGN clause, id-name must be identical to file-spec.
Parent topic: File Section


CODE-SET Clause

The CODE-SET clause specifies the alphabet to use for a sequential file.

General Format

CODE-SET IS alphabet

Syntax Rules

  1. alphabet is the name of an alphabet declared in the SPECIAL-NAMES section.
  2. The CODE-SET clause may be associated only with a sequential file.
  3. If the CODE-SET clause is used, then only USAGE DISPLAY items may appear in the file's record description entry. Furthermore, every signed numeric field must have a SIGN IS SEPARATE clause.

General Rule

The CODE-SET clause associates a character set with a sequential file. If the character set is not the native character set, then a translation to the native set is also implied.

Parent topic: File Section


DATA RECORDS Clause

This clause names the record descriptions used by the file.

General Format

DATA { RECORD IS  } {record-name} ...
     { RECORDS ARE}

Syntax Rule

record-name must name level 01 record descriptions associated with the file.

General Rule

This clause is never required, because the compiler can determine which records are associated with each file.

Parent topic: File Section


LINAGE Clause

The LINAGE clause is used to specify the number of lines on a logical page, and optionally provide margin information.

General Format

LINAGE IS page-lines LINES

   [ WITH FOOTING AT footing-line ]

   [ LINES AT TOP top-lines ]

   [ LINES AT BOTTOM bottom-lines ]

Syntax Rules

  1. page-lines is a numeric literal or numeric data item whose value must be a positive integer. It specifies the number of lines on the logical page. page-lines may be qualified.
  2. footing-line is a positive integer or numeric data item. Its values must be greater than zero and less than or equal to page-lines. It specifies the line number where the footing area begins on the page. footing-line may be qualified.
  3. top-lines and bottom-lines are integers or numeric data items. Their values must be greater than or equal to zero. They represent the numbers of lines in the top and bottom margins respectively. top-lines and bottom-lines may be qualified.
  4. The LINAGE clause may be specified for a Sequential file only.

General Rules

  1. The LINAGE clause specifies the number of lines on a logical page. The total page size is the sum of page-lines, top-lines, and bottom-lines. If the TOP or BOTTOM phrase is omitted, the corresponding value is treated as zero. Note that footing-line is not added to the page size.
  2. page-lines specifies the size of the page body. This is the area of the logical page in which the program can write or space lines.
  3. Each logical page follows the preceding logical page with no additional spacing. ACUCOBOL-GT does not provide physical page ejects (form-feeds) when the LINAGE clause is used. Device positioning occurs by line spacing rather than by page ejection.
  4. The footing area is composed of the area between footing-line and page-lines, inclusive. The footing area causes a page-overflow condition when written in. If the FOOTING phrase is omitted, there is no footing area.
  5. Evaluation of the logical page size occurs as follows:
    • When the file is opened with the OUTPUT or EXTEND phrases, the LINAGE clause values are evaluated and applied to the first logical page. The device is assumed to be positioned at the beginning of the logical page.
    • When the program executes a WRITE statement with the ADVANCING PAGE option, or when a page-overflow condition occurs, the LINAGE clause values are evaluated and applied to the next logical page.
  6. For each file that has a LINAGE clause associated with it, the compiler creates an implicit data item called LINAGE-COUNTER associated with that file. If more than one file in the program specifies a LINAGE clause, reference to a LINAGE-COUNTER will have to be qualified by the appropriate file name. The LINAGE-COUNTER is an elementary numeric data item that contains the same number of digits as page-lines.
  7. At any time, the value of LINAGE-COUNTER is the line number in the current page body at which the device is positioned.
  8. LINAGE-COUNTER may be treated as a normal numeric data item except that it may never be explicitly modified by the program.
  9. The LINAGE-COUNTER is set to one when the file is opened.
  10. Every WRITE statement that refers to a file with a LINAGE clause affects the associated LINAGE-COUNTER in the following manner:
    • If the WRITE statement has the ADVANCING PAGE phrase, the LINAGE-COUNTER is set to one.
    • If the WRITE statement has the ADVANCING LINES phrase, the LINAGE-COUNTER is incremented by the value in the ADVANCING phrase.
    • If the WRITE statement does not have an ADVANCING phrase, the LINAGE-COUNTER is incremented by one.
Parent topic: File Section


WORKING-STORAGE Section

The Working-Storage Section is used to define data items local to the program that do not reside in files.

General Format

WORKING-STORAGE SECTION.

   [ record-description ] ...

General Rules

  1. Storage level 01, 77, and 78 data descriptions in Working-Storage must be unique since they cannot be qualified.
  2. Subordinate data names need not be unique if they can be made unique through qualification.
  3. Unless given a value by a VALUE clause, each data item defined in Working-Storage is initialized to spaces or the value specified with the -Dv compile option.
  4. Level 01 and 77 data items in Working-Storage may be declared to be external, which means they are shared by more than one program.

    Each program of a run unit that declares an external data item may access that item. Any change to the item made by one program is automatically seen by all the other programs. External data items may be shared between COBOL and C programs.

Parent topic: Data Division


LINKAGE Section

The Linkage Section is used to define data items that are passed from a calling program.

General Format

LINKAGE SECTION.

   [ record-description ] ...

General Rules

  1. Each level 01 and 77 data item described in Linkage must be uniquely named.
  2. Subordinate data names need not be unique if they can be made unique through qualification.
  3. Each level 01 and 77 data item declared in Linkage should be named in a USING phrase of the Procedure Division header. Data items that are REDEFINES of other data items should not be named, however.
  4. There is a limit of 255 level 01 Linkage data items per program. There is no limit for the number of subordinate items allowed for each of these level 01 items.
Note: There are two runtime configuration variables that relate to linkage items: CHECK_USING for specifying parameter size-matching testing; and OPTIMIZE_INDIVIDUAL_LINKAGE that perform address optimizations on each Linkage item individually.
Parent topic: Data Division


Record Description Entry

A record description entry describes the name, size, and format of a COBOL logical record or data item.

General Format

{ data-description-entry } ...

Syntax Rule

The first data description entry of a record must have a level-number of 01 or 77 and start in Area A.

General Rules

  1. Any data description entry which is not further subdivided is called an elementary item. A record itself may consist of an elementary item consisting of a single level 01 data description entry. A non-elementary entry is called a group item.
  2. An elementary data item that is not part of a larger record must have a level-number of 01 or 77.
  3. A group item that is not part of an enclosing group item must have a level-number of 01.
  • Data Description Entry
Parent topic: Data Division


Data Description Entry

A data description entry specifies the attributes of one data item.

Format 1

level-number [ data-name ]
             [ FILLER    ]

   [ REDEFINES prev-data-name ]

   [ IS EXTERNAL      ]
   [ IS GLOBAL        ]
   [ IS SPECIAL-NAMES   {CURSOR        } ]
                        {CRT STATUS    }
                        {CHART STATUS  }
                        {SCREEN CONTROL}
                        {EVENT STATUS  }

[ IS EXTERNAL-FORM [ IDENTIFIED BY template-file-name ] ]
   [ IS IDENTIFIED BY external-name                    ]

   [ {PICTURE} IS picture-string ]
     {PIC    }

   [ [ USAGE IS ] usage-type ]

   [ [ SIGN IS ] {LEADING } [ SEPARATE CHARACTER ] ]
                 {TRAILING}

   [ OCCURS
         { table-size TIMES                       }
         { min TO max TIMES DEPENDING ON dep-item }

         [ {ASCENDING } KEY IS {key-name} ... ] ...
           {DESCENDING}

         [ INDEXED BY {index-name} ... ] ]

   [ {SYNCHRONIZED}  [LEFT ] ]
     {SYNC        }  [RIGHT]

   [ {JUSTIFIED} RIGHT ]
     {JUST     }

   [ BLANK WHEN ZERO ]

   [ VALUE IS value-lit ] .

Format 2

66 new-name RENAMES name-start [ {THRU   } name-end ] .
                                 {THROUGH}

Format 3

78 user-name VALUE IS {literal-1} [ {+} literal-2 ] .
                      {NEXT     }   {-}
                                    {*}
                                    {/}

Format 4

88 cond-name  {VALUE IS  } { low [ {THRU   } high ] } ...
              {VALUES ARE}         {THROUGH}

      [ WHEN SET TO FALSE false-val ] .

Syntax Rules

  1. Level-number in Format 1 can be any number from 01 through 49, or 77.
  2. Data description clauses may appear in any order, with two exceptions:
    • The optional data-name or FILLER clause must immediately follow the level-number.
    • The optional REDEFINES clause must immediately follow the data-name or FILLER clause.
  3. Only level 01 and level 77 Working Storage data items may be declared EXTERNAL. Each program that declares an external data item must use the same name for that item, and the item must occupy the same number of bytes. External data items may not have a VALUE phrase.
  4. The phrase IS GLOBAL is accepted by the compiler as a commentary.
  5. template-file-name and external-name are alphanumeric literals or unqualified data names. If a data name is used, it must refer to an unambiguous data item.
  6. Format 1 data description entries that specify a PICTURE clause, or a USAGE clause that allows a PICTURE clause, are elementary items. All other Format 1 entries are group items.
  7. There must be a PICTURE clause for all Format 1 elementary items except those that specify a USAGE clause that does not allow a PICTURE clause. See USAGE Clause for more information.
  8. The SYNCHRONIZED, PICTURE, JUSTIFIED, and BLANK WHEN ZERO clauses can appear only in a record description for an elementary item.
  9. A level 78 entry associates a value with the name of a constant. user-name names the constant, and literal may be any literal.
  10. Each cond-name requires a separate Format 4 entry. The level 88 entry associates a set of values with cond-name. All cond-name entries for a data item must immediately follow that data item's record description.
  11. A cond-name can be associated with any data item except the following:
    1. another cond-name
    2. a level 66 or 78 data item
    3. a group item that contains items with JUSTIFIED, SYNCHRONIZED, or USAGE (other than USAGE DISPLAY) clauses.
    4. an index data item

General Rule

The individual clauses are described in other topics in this help.

  • Level-number
  • The data-name or FILLER Clause
  • REDEFINES Clause
  • IS EXTERNAL Clause
  • IS SPECIAL-NAMES Clause
  • IS EXTERNAL-FORM Clause
  • PICTURE Clause
  • USAGE Clause
  • SIGN Clause
  • OCCURS Clause
  • SYNCHRONIZED Clause
  • JUSTIFIED Clause
  • BLANK WHEN ZERO Clause
  • VALUE Clause
  • RENAMES Clause
Parent topic: Record Description Entry


Level-number

The level-number of a data item shows the hierarchy of that data item within its logical record. It is also used to denote individual data items and condition names.

Syntax Rules

  1. Data description entries subordinate to an FD entry must have level-numbers with the values 01 through 49, 66, 78, or 88.
  2. Data description entries in Working-Storage may have level-numbers with the values 01 through 49, 66, 77, 78, or 88.
  3. Data description entries in Linkage may have level-numbers with the values 01 through 49, 66, 77, 78, or 88.

General Rules

  1. The level-number 01 indicates the first entry in a record description.
  2. Each data description entry in a record description can be subdivided into multiple data description entries, each having the same level-number. This level-number must be greater than the level-number of the subdivided entry, but less than 50. These level-numbers do not have to be successive. Thus you construct a record hierarchy of data items by using level-numbers.
  3. An elementary data item may not be immediately followed by a data item with a higher level-number (except for levels 66, 77, 78, and 88).
  4. Multiple level 01 entries subordinate to a file description entry represent implicit redefinitions of the same area.
  5. Level-number 66 may be used to identify only RENAMES entries (Format 2 data description entry).
  6. Level-number 77 identifies a non-contiguous data item entry. Level-number 77 entries may not have subordinate data description entries except for level 88 items.
  7. A level 78 entry associates a value with the name of a constant. The name of the constant can be used anywhere the corresponding literal can be used.
  8. You may use a level 78 named constant as a repeat count in a PICTURE string. This means that, in a PICTURE string, you may substitute a level 78 for a number in parentheses. In the following example, DATA-1 and DATA-2 are both the same size:
        78  LENG-20     VALUE 20.
    01  DATA-1      PIC X(20).
    01  DATA-2      PIC X(LENG-20).

    The PICTURE string that results from the substitution of the level 78 for its value must be legal. Use this in programs when several data items must be the same size and you want to be able to easily change the size in the future.

  9. Level-number 88 defines a condition name. It can be used only in a Format 4 data description entry.
Parent topic: Data Description Entry


The data-name or FILLER Clause

The data-name clause specifies the name of the data area.

General Format

[ data-name ]
[ FILLER    ]

Syntax Rules

  1. The data-name or FILLER clause must appear immediately after the level-number in a data description entry.
  2. data-name is a user-defined word.
  3. A FILLER data item may not be declared EXTERNAL.

General Rules

  1. If there is no data-name or FILLER clause, the FILLER clause is implied.
  2. The FILLER clause names a data item that the program cannot explicitly refer to.
  3. The FILLER clause can name a data item that is the object of a level 88 condition name.
Parent topic: Data Description Entry


REDEFINES Clause

The REDEFINES clause allows the same computer memory area to be described by different data items. ACUCOBOL-GT extends ANSI85 COBOL by allowing a REDEFINES phrase to reference an item that is itself a redefinition of an area.

General Format

level-number  [ data-name ]  REDEFINES  prev-data-name
              [ FILLER    ]

Syntax Rules

  1. The level-number, data-name, and FILLER phrases in the General Format are not actually part of the REDEFINE clause. They are included for clarity.
  2. The level-numbers of the subject of a REDEFINES clause and prev-data-name must be the same. They may not be 66 or 88.
  3. REDEFINES is allowed in a level 01 entry in the File Section, but it will generate a warning message.
  4. The number of character positions described by prev-data-name need not be the same as the number of character positions in the subject of the REDEFINES clause. The compiler generates a warning, however, if the number of character positions is greater in the subject of the REDEFINES clause than in prev-data-name and the level-number of the two data items is not 01 or 77 (this case is not allowed under ANSI COBOL).
  5. The data item being redefined may be qualified, but any qualification specified is ignored.

    Example: 01 MY-FILLER REDEFINES THIS-FIELD OF THIS-GROUP.

    The phrase in the example compiles, but the qualification OF THIS-GROUP is ignored.

  6. Several data items can redefine the same memory area.
  7. No entry with a level-number lower than that of prev-data-name can occur between the data description entry for prev-data-name and the redefinition.
  8. All entries redefining the storage area of a data item must immediately follow the entries describing that data item. No intervening entries that define additional storage may appear.
  9. The IS EXTERNAL clause may not be used with the FILLER or REDEFINES clauses.

General Rules

  1. Storage allocation for the redefining data item starts at the location of prev-data-name.
  2. Storage allocation continues until it defines the number of character positions described by the redefining entry.
  3. prev-data-name may contain the OCCURS clause, although this is not compatible with ANSI COBOL. If such a situation exists, the compiler will return a caution warning indicating a non-ANSI construct. Cautions are shown only when you compile with the -a option. When you REDEFINE a data item with an OCCURS clause, the redefining item starts at the same memory location as the first occurrence of the redefined item.
  4. In large model programs, certain REDEFINES could cause VALUE clauses to be lost. This happens when the VALUEs are set in a data item that is not a large data item, and then that data item is redefined as a large data item. When that occurs, the compiler detects the situation and issues a warning message:
    Warning: Large redefines of a regular variable with a
value: desc2 redefines desc1

    When you see this warning message, you should modify your COBOL program to add FILLER to the first data item in order to make it a large data item. For example, the following code:

    01  small-group-item.
  03  small-data-item pic x(100) value "this is a test".

01  large-group-item redefines small-group-item.
  03  free-form-text  pic x(100) occurs 1000 times.

    will compile, but the value of small-data-item will be spaces when the program starts. To work around this, add:

    03  filler   pic x(65000).

    to the small-group-item after the small-data-item. The resulting code should look like this:

    01  small-group-item.
  03  small-data-item pic x(100) value "this is a test".
  03  filler          pic x(65000).
Parent topic: Data Description Entry


IS EXTERNAL Clause

The IS EXTERNAL clause declares that a data item is shared by two or more programs.

General Format

[ IS EXTERNAL ]

Syntax Rules

  1. Only level 01 and 77 data items in Working-Storage may be declared to be external.
  2. Each program that declares an external data item must use the same name for that item, and the item must occupy the same number of bytes.
  3. External data items may not have a VALUE phrase.
  4. The IS EXTERNAL clause may not be used with the REDEFINES clause.

General Rules

  1. The phrase IS EXTERNAL must be included in the data description of the item in each program that accesses the item externally. Each program of a run unit that declares an external data item may access that item. Any change to the item made by one program is automatically seen by all the other programs. External data items may be shared between both COBOL and C programs.
  2. An external data item belongs to the run unit, not to any of the programs that are part of the run unit. This means that an external data item is allocated for the duration of the run, regardless of the action of CANCEL verbs.

    The one exception to this rule is external data items that are also C data items. These belong to the runtime system itself, not to the run unit. The distinction is that you can initiate another run unit with the CALL RUN verb, but this does not initiate another runtime system. In this case, you get new copies of the COBOL-only external data items, but keep the same data items that are shared with C programs.

  3. Instructions for declaring a C data item external can be found in the file direct.c supplied with the runtime system. External data items may not have a VALUE phrase. They are initialized to binary zeros (NULL) by the runtime.
Parent topic: Data Description Entry


IS SPECIAL-NAMES Clause

The IS SPECIAL-NAMES clause allows you to identify select Special-Names directly in the Data Division.

General Format

   [ IS SPECIAL-NAMES   {CURSOR        } ]
                        {CRT STATUS    }
                        {CHART STATUS  }
                        {SCREEN CONTROL}
                        {EVENT STATUS  }

Syntax Rule

The syntax is identical to declaring data-name in Special-Names with the indicated phrase. See Input-Output Section for more information.

General Rule

Only one data item can be declared for each Special-Names type. Items identified in the IS SPECIAL-NAMES phrase cannot appear in the Special-Names paragraph of the Environment Division. If there is a corresponding item, the declaration must be identical.

The advantage of the IS SPECIAL-NAMES syntax over naming the items in Special-Names is that a single COPY library can be used to include all of your commonly used Special-Names items. For example, you might have a COPY library that reads:

* Declare commonly used screen handling items

01  SCREEN-CONTROL IS SPECIAL-NAMES SCREEN CONTROL.
    03  ACCEPT-CONTROL     PIC 9.
    03  CONTROL-VALUE      PIC 999.

01  CURSOR-POSITION IS SPECIAL-NAMES CURSOR.
    03  CURSOR-ROW         PIC 999.
    03  CURSOR-COL         PIC 999.

77  CRT-STATUS IS SPECIAL-NAMES CRT STATUS PIC 9(5).
Parent topic: Data Description Entry


IS EXTERNAL-FORM Clause

The IS EXTERNAL-FORM clause associates a group item with HyperText Markup Language (HTML) data using the Common Gateway Interface (CGI) specification. It allows you to define input and output records for HTML forms and is useful when your COBOL code is part of an Internet-based application.

General Format

[ IS EXTERNAL-FORM [ IDENTIFIED BY template-file-name ] ]
[ IS IDENTIFIED BY external-name ]

Syntax Rule

template-file-name and external-name are alphanumeric literals or unqualified data names. If a data name is used, it must refer to an unambiguous data item.

General Rules

  1. The EXTERNAL-FORM clause associates a group item with HTML data using the Common Gateway Interface (CGI) specification. It allows you to define input and output records for HTML forms. The EXTERNAL-FORM clause affects the way ACCEPT and DISPLAY process the data item. It does not put any restrictions on the way that the data item may be used in your program.
  2. An EXTERNAL-FORM data item is called an output form if the IDENTIFIED BY clause is used in the description of the group item. This clause associates the data item with an HTML template file. If the IDENTIFIED BY clause is omitted from the group item, the EXTERNAL-FORM data item is called an input form.
  3. For input forms, the IDENTIFIED BY clause establishes an association between an elementary data item and a CGI variable. The value of external-name is the name of the CGI variable. If the IDENTIFIED BY phrase is omitted, then data item's own name (data-name) is used as the name of the CGI variable. If both the IDENTIFIED BY phrase and data-name are omitted, then the data item has no corresponding CGI variable.
  4. CGI variables are case-sensitive. The runtime matches CGI names according to their case. However, if a CGI variable is not found using a case-sensitive match, then the runtime tries a case-insensitive match. Note that data-name is always treated as if it were upper case regardless of the case used in the COBOL source. The case of the value specified by the IDENTIFIED BY phrase is preserved.
  5. The ACCEPT verb treats input forms and output forms in the same manner. ACCEPT sets the value of each elementary item, in order, to the value of its associated CGI variable. The CGI data is retrieved from the program's standard input. ACCEPT automatically decodes and translates the CGI input data before moving it to the elementary data item. The value of each CGI variable is converted to the appropriate COBOL data type when it is moved. If the CGI variable is empty or does not exist, ACCEPT sets the value of numeric data items to zero, and nonnumeric data items to spaces.
  6. To receive a CGI variable that is repeated (this occurs when multiple items have been selected in a choose many list), you should use an elementary data item that is part of a table. Each occurrence of the data item receives one of the repeated values. The first occurrence receives the first repeated CGI item; the second occurrence receives the second repeated item; and so forth. Occurrences that do not correspond to repeated CGI items are set to zero if the data item is numeric, or spaces otherwise.
  7. Data items are matched to CGI variables immediately before the particular CGI data item is retrieved. Thus it is possible for a form to have CGI variable names supplied by the CGI input itself. Consider:
    01  MY-FORM IS EXTERNAL-FORM
    03  CGI-VAR1 PIC X(20) IDENTIFIED BY "Name".
    03  CGI-VAR2 PIC X(50) IDENTIFIED BY CGI-VAR1.

    In this example, an ACCEPT MY-FORM statement would first locate the CGI variable called "Name" and move its value to CGI-VAR1. It would then locate a CGI variable identified by that value and move the corresponding value to CGI-VAR2. Note that, for this to work, you must specify CGI-VAR1 before CGI-VAR2 in MY-FORM, because ACCEPT updates the elementary data items in order.

  8. The DISPLAY verb treats input and output forms differently. For output forms, DISPLAY merges the data contained in the elementary items into the associated HTML template file and sends the result to the standard output stream in conformance with the CGI specification. To do this, DISPLAY scans the HTML template file for data names delineated by two percentage signs on either side (i.e. %%data-name%%). It then replaces those data names with the contents of the associated elementary items from the output form, stripping trailing spaces. The maximum length of a single line in the template file is 256 bytes. There is virtually no limit to the length of a single HTML output line. No conversion is performed on the output form items before they are merged with the HTML template file.
  9. When an input form is specified in a DISPLAY statement, the names and values of each elementary item are sent to the standard output stream in HTML format. One line is generated for each elementary item. The line consists of the name of the item followed by " = ", followed by the first 100 bytes of the item's value. This can be useful when you are testing and debugging your CGI program.
  10. template-file-name specifies the name of the HTML template file. You can specify a series of directories for locating HTML template files. To do this, use the HTML_TEMPLATE_PREFIX configuration variable. This variable is similar to FILE_PREFIX and CODE_PREFIX. It specifies a series of one or more directories to be searched for the desired HTML template file. The directories are specified as a sequence of space-delimited prefixes to be applied to the file name. All directories in the sequence must be valid names. The current directory can be indicated by a period (regardless of the host operating system).
  11. You can omit the suffix if it is either .html or .htm. If the suffix is omitted or is something other than .html or .htm, DISPLAY first appends .html to the specified file name and tries to open it. If that fails, DISPLAY appends .htm to the file name and tries to open it. If that fails, DISPLAY tries to open the file exactly as specified. If these attempts fail, the following error message is sent to the standard output stream in HTML format:
    Can't open HTML template "template-file-name"
  12. When the Web Server executes your CGI program, the current working directory depends on the configuration of the specific Web Server that is running. In many cases it is the same as the Web Server's root directory. As part of the CGI specification, when the Web Server executes your CGI program, it sets an environment variable called PATH_TRANSLATED to the directory containing your CGI program. You may want to use this information to locate your HTML template files.

    For example, if your template files are in the same directory as your CGI programs, then set the HTML_TEMPLATE_PREFIX configuration variable to the value of PATH_TRANSLATED as follows:

    01  CGI-DIRECTORY     PIC X(100).

ACCEPT CGI-DIRECTORY FROM ENVIRONMENT "PATH_TRANSLATED"
SET CONFIGURATION "HTML_TEMPLATE_PREFIX" TO
   CGI-DIRECTORY.
  13. The output from a CGI program must begin with a response header. DISPLAY automatically generates a Content-Type response header when template-file-name specifies a local file (i.e., not a URL - see rule #16 below).
  14. You may specify the EXTERNAL-FORM clause for an item that has no subordinate items. This is useful for displaying static Web pages. To do this, specify the name of the static Web page in template-file-name. For example, if you have a Web page called webpage1.html, add the following lines to your COBOL program:
    01  WEB-PAGE-1 IS EXTERNAL-FORM,
          IDENTIFIED BY "webpage1".

DISPLAY WEB-PAGE-1.
  15. You may also specify a complete URL in template-file-name. In this case, DISPLAY generates a Location response header that contains the URL. This header specifies that the data you're returning is a pointer to another location. To determine whether template-file-name is a URL, DISPLAY scans it for the string "://". DISPLAY does not apply HTML_TEMPLATE_PREFIX when template-file-name is a URL. For example, if your program determines that the information the user has requested is on another Web server, and its URL is http://www.theinfo.com, add the following lines to your COBOL program:
    01  THE-INFO-URL IS EXTERNAL-FORM
         IDENTIFIED BY "http://www.theinfo.com"

DISPLAY THE-INFO-URL.

    The length of the URL must not exceed 256 bytes. Only one response header is sent to the standard output stream. Your CGI program should exit immediately after sending a location header (i.e., after displaying an external form identified by a URL).

  16. You may use as many HTML template files as you like in a single program. A common way to use multiple HTML template files is to have three output forms: a header, body, and footer. Each of these has a corresponding HTML template file. You first display the header form, then move each row of data to the body form and display it, and finally display the footer form.
  17. Data items that do not have EXTERNAL-FORM specified are treated as regular data items by ACCEPT and DISPLAY, even if they are subordinate to an external form. For example:
    01  MY-FORM IS EXTERNAL-FORM.
    03  CGI-VAR1  PIC X(10)
    03  CGI-VAR2  PIC 9(5).

    Using this data structure, an ACCEPT of MY-FORM would fill in CGI-VAR1 and CGI-VAR2 with CGI data. An ACCEPT of CGI-VAR1 would simply get data from the user just as it does for any regular data item.

Parent topic: Data Description Entry


PICTURE Clause

The PICTURE clause describes the general characteristics and editing formats of an elementary item.

General Format

{PICTURE} IS picture-string
{PIC    }

Syntax Rules

  1. A PICTURE clause can appear for elementary items only.
  2. The maximum size of the picture-string is 100 characters.
  3. A PICTURE clause is required for every elementary data item except for those items with a USAGE clause that disallows a PICTURE, or those items that are the subject of a RENAMES clause. A PICTURE clause is prohibited for these items.
  4. PIC and PICTURE may be used interchangeably.
  5. A picture is invalid if it specifies more than 31 digits to the left of the decimal point or more than 32 digits to the right of the decimal point, including assumed zero digits represented by"P and floating insertion positions that may hold digits. If a picture exceeds these scaling limitations, a compile-time error message is produced.

General Rules

The PICTURE clause defines a data item as belonging to one of five categories and determines what the item can contain. The five categories are:

  • Alphabetic
  • Numeric
  • Alphanumeric
  • Alphanumeric Edited
  • Numeric Edited
  1. An item is alphabetic when its picture-string consists solely of A symbols.
  2. An alphabetic item may contain only one or more alphabetic characters.
Note: The alphabetic declaration shows the programmer's intent to store only alphabetic data, however the system does not provide any checks to ensure compliance.
  1. An item is numeric when its picture-string contains only the symbols 9, P, S, and V. The number of digit positions described by picture-string must range from 1 to 18 inclusive. This increases to 31 digit positions if 31-digit support (-Dd31 compiler option) is in effect.
  2. If unsigned, its contents must be one or more numeric characters. If signed, then the item may also contain a "+" or "-" (or other representation of the sign). See SIGN Clause for more information.
  3. The numeric category of the PICTURE clause includes an external floating-point data item, which is defined by a picture that strongly resembles a floating-point numeric literal.
  1. An item is alphanumeric when its picture-string consists solely of the symbols A, X, and 9. A picture-string containing all A or all 9 symbols is not alphanumeric. When used in an alphanumeric item, the A and 9 symbols are treated as if they were X symbols.
  2. Its contents may contain one or more characters in the computer's character set.
  1. An item is alphanumeric edited when its picture-string contains certain combinations of the symbols A, X, 9, B, 0, and /. The picture-string must contain at least one A or X symbol and at least one B, 0, or / symbol.
  2. Its contents may contain two or more characters in the computer's character set.
  1. An item is numeric edited when its picture-string contains certain combinations of the symbols B, /, P, V, Z, 0, 9, comma, period, *, +, -, CR, DB, and the currency symbol. The number of digit positions that can be represented by the picture-string must range between 1 and 18 inclusive. This increases to 31 digit positions if 31-digit support (-Dd31) is in effect. The picture-string must contain at least one 0, B, /, Z, *, +, comma, period, -, CR, DB, or currency symbol.
  2. The content of each character position must be consistent with the corresponding PICTURE symbol.
  1. Some PICTURE symbols represent character positions and some do not. A data item's size is determined by adding up all the symbols that represent character positions.
  2. A picture-string may contain repeat counts for its symbols. You denote this by placing the repeat count in parentheses immediately after the symbol that is being repeated. For example, X(4) and XXXX are equivalent PICTURE strings.
  3. Only one S may appear in a PICTURE string, and it must be the leftmost character. Only one of the following symbols may appear in a PICTURE string: V or the period character. It may appear only once. At least one of the symbols A, X, Z, 9, or * or at least two occurrences of the symbols +, -, or the currency symbol must be present in a PICTURE string.

The PICTURE symbols and their functions are the following:

A | Represents a character position that can contain only an alphabetic character. It is counted in the size of an item. An alphabetic character is any character A through Z, "a" through z, or a space.
B | Represents a character position where a space will be inserted. It is counted in the size of an item.
E | A delimiter directly preceding the (signed or unsigned) exponent part of an External Floating-Point notation. The exponent is always exactly two digits long, so the last two characters of the picture must be 99. This delimiter is counted in the size of an item.
P | This symbol is used to specify an assumed scaling position in a number. The P character is not counted in the size of the data item. Instead, each P represents a scaling of the data item by a power of ten. P elements can appear only as a contiguous string of Ps in either the leftmost or rightmost digit positions of a picture-string. If the V character is used, it must be to the left of all leading Ps or to the right of all trailing Ps. The assumed decimal point for the item is located at the point where the V character may be placed. For example, the PICTURE string 9P is a one-digit item that can have numeric values of 10, 20, ..., 90, and a PICTURE string of PPP9 is a one-digit item that can have numeric values of 0.0001 though 0.0009. The "." character may not be specified in the same picture-string as a P character. When a data item is treated as a numeric value, each P position acts as if it were a digit position that contained a zero. When a data item is not treated as a numeric value, then its P positions are ignored.
S Indicates the presence of an operational sign for a numeric item. It does not specify the sign representation or position. Only one S may appear in a PICTURE string, and it must be the leftmost character. It does not count in the size of the data item unless the SIGN IS SEPARATE clause is also specified.

Note that the PICTURE definition for a PIC X(n) COMP-5 cannot be signed.

V | Specifies the location of an assumed decimal point. It may appear only once in a PICTURE string. It does not represent a character position and is not counted in the size of the data item.
X | Represents a character position that can contain any character from the computer's character set. It is counted in the size of an item.
Z | Represents a leading digit position that is replaced by a space when its value and the digit positions to its left are all zero. It is counted in the size of an item.
9 | Represents a digit position which is counted in the size of an item.
0 | Represents a digit position where a zero will be inserted. It is counted in the size of an item.
/ Represents a character position where a slash will be inserted. It is counted in the size of an item.
, The comma character represents a character position where a comma will be inserted. It counts in the size of an item.
. The period character represents a character position where a decimal point will be inserted. It also implies an operational decimal point for alignment purposes. It counts in the size of an item. Note that the functions of comma and period are exchanged if the DECIMAL-POINT IS COMMA clause is stated in the program's SPECIAL-NAMES paragraph.
+ - Represent editing sign control symbols. These can occur more than once. Each counts in the size of an item.
CR | Represents an editing sign control symbol. It may be used only once on the rightmost side of the PICTURE string. It adds two to the size of a data item.
DB | Represents an editing sign control symbol. It may be used only once on the rightmost side of the PICTURE string. It adds two to the size of a data item.
* Represents a leading digit that is replaced by asterisks when its value and all of the digits to its left are zero. It is counted in the size of an item.
$ Represents a character position into which the currency symbol is inserted. It is counted toward the size of an item. Note that the dollar sign is the default currency symbol. It may be changed by the CURRENCY clause of the SPECIAL-NAMES paragraph.

Editing Rules

  1. The two methods of editing

    There are two general methods of performing editing in the PICTURE clause, either by insertion or by suppression and replacement.

  2. The four types of insertion editing :
    • Simple insertion
    • Special insertion
    • Fixed insertion
    • Floating insertion
  3. The two types of suppression and replacement editing:
    • Zero suppression and replacement with spaces
    • Zero suppression and replacement with asterisks
  4. Types of editing allowed:

    The type of editing that may be performed on an item is dependent on the category of that item. No editing may be performed on alphabetic, numeric, or alphanumeric items. Simple insertion of types 0, B, and / may be performed on alphanumeric edited types. All forms of editing are allowed on numeric edited items.

  5. Floating insertion, zero suppression, and the PICTURE clause

    Floating insertion and zero suppression and replacement are mutually exclusive in a PICTURE clause. Only one type of zero suppression and replacement may be used in a PICTURE clause.

  6. Simple Insertion Editing

    The comma, B, 0, and / are used as simple insertion characters. The insertion characters represent positions in an item where those characters will be inserted. If the comma is the last symbol in a PICTURE clause, the PICTURE clause must be the last clause in its data description entry, and the clause must be immediately followed by a period.

  7. Special Insertion Editing

    The period is used as an insertion character, as it is in simple insertion. In addition to being used as an insertion character, it also represents the operational decimal point of the item. The period may not appear in the same PICTURE clause as the V symbol. If the period is the last symbol in the PICTURE clause, then the PICTURE clause must be the last clause in its data description entry, and the clause must be immediately followed by a period.

  8. Fixed Insertion Editing

    The currency symbol and the editing sign control symbols "+", "-", CR, and DB are the insertion characters. Only one currency symbol and only one of the editing sign control symbols can be used in a given PICTURE clause. The symbols CR and DB, when used, must appear as the rightmost symbols in the PICTURE string. The symbol "+" or "-", when used, must either be the leftmost or rightmost character position to be counted in the size of the item. The currency symbol must be the leftmost character except that it may be preceded by either a "+" or "-" symbol.

    Fixed insertion editing results in the insertion character's occupying the same character position in the edited item as it occupied in the PICTURE string. Editing sign control symbols produce the following results depending on the value of the data item:

    Editing Symbol | Zero or Positive | Negative
    + + -
    - space -
    CR | 2 spaces | CR
    DB | 2 spaces | DB
  9. Floating Insertion Editing

    The currency symbol and editing sign control symbols "+" and "-" are the floating insertion characters. They are mutually exclusive in a PICTURE clause. You indicate floating insertion by using a string of at least two of the floating insertion characters. This string may contain any of the simple insertion characters or have the simple insertion characters immediately to the right. These simple insertion characters are part of the floating string.

    The leftmost character of the floating insertion string represents the leftmost limit of the floating symbols in the data item. The rightmost character represents the rightmost limit. The second floating character from the left represents the leftmost limit of the numeric data that can be stored in the data item. Non-zero numeric data may replace all the characters at or to the right of this limit.

    In a PICTURE string, there are only two ways of representing floating insertion editing. One way is to represent any or all of the leading numeric character positions on the left of the decimal point by the insertion character. The other way is to represent all of the numeric character positions by the insertion character.

    If the insertion character positions are only to the left of the decimal point, the result is that a single floating insertion character will be placed into the character position immediately preceding either the decimal point or the first non-zero digit in the data represented by the insertion symbol string, whichever is leftmost. The character positions preceding the insertion character are replaced by spaces.

    If all numeric character positions in the PICTURE string are represented by the insertion character, the results depend on the value of the data. If the value is zero, the entire data item will contain spaces. If the value is not zero, then the results are the same as when the insertion character is only to the left of the decimal point.

    The character inserted for the "+" symbol is "+" if the value is zero or positive and "-" if it is negative. The character inserted for the "-" symbol is "-" if the value is negative and space otherwise.

  10. Zero Suppression and Replacement Editing

    The suppression of leading zeros in numeric character positions is indicated by the use of the "Z" and "*" symbols. These symbols are mutually exclusive in a PICTURE clause. If a "Z" is used, the replacement character is a space. If "*" is used, the replacement character is an asterisk.

    You indicate zero suppression and replacement by using a string of one or more of the allowable symbols to represent leading numeric character positions which are to be replaced when the associated character position in the data contains a leading zero. Any of the simple insertion characters embedded in the string of symbols or to the immediate right of this string are part of the string.

    In a PICTURE string, there are only two ways of representing zero suppression. One way is to represent any or all of the leading numeric character positions to the left of the decimal point by suppression symbols. The other is to represent all of the numeric character positions by suppression symbols.

    If the suppression symbols appear only to the left of the decimal point, any leading zero in the data that corresponds to a symbol in the suppression string is replaced by the replacement character.

    If all numeric positions in the PICTURE string are represented by suppression symbols and the value of the data is not zero, the result is the same as if the suppression characters were only to the left of the decimal point. If the value is zero and the suppression symbol is Z, the entire data item is set to spaces. If the suppression symbol is "*" instead, the entire data item is set to asterisks except for the decimal point (if any), which will appear in the data item.

  11. The symbols "+", "-", "*", Z, and the currency symbol, when used as floating replacement characters, are mutually exclusive in a given PICTURE clause.
Parent topic: Data Description Entry


USAGE Clause

The USAGE clause specifies the format of a data item in computer memory or in a file record.

In some circumstances, a data item's file-record format may differ from its computer-memory format as specified by the USAGE clause. This can occur when non-COBOL file systems with different data storage formats are being accessed through an interface. For example, Acu4GL uses SQL to access non-COBOL file systems, and in the process a translation occurs on the data.

Note: There are numerous compiler options for affecting data storage behavior. See Data Storage Options in the ACUCOBOL-GT User's Guide for details on these options.

General Format

[ USAGE IS ] {COMPUTATIONAL                                 }
             {COMP                                          }
             {COMPUTATIONAL-1                               }
             {COMP-1                                        }
             {COMPUTATIONAL-2                               }
             {COMP-2                                        }
             {COMPUTATIONAL-3                               }
             {COMP-3                                        }
             {COMPUTATIONAL-4                               }
             {COMP-4                                        }
             {COMPUTATIONAL-5                               }
             {COMP-5                                        }
             {COMPUTATIONAL-6                               }
             {COMP-6                                        }
             {COMPUTATIONAL-X                               }
             {COMP-X                                        }
             {COMPUTATIONAL-N                               }
             {COMP-N                                        }
             {BINARY                                        }
             {PACKED-DECIMAL                                }
             {DISPLAY                                       }
             {INDEX                                         }
             {POINTER                                       }
             {FLOAT                                         }
             {DOUBLE                                        }
             {SIGNED-SHORT                                  }
             {UNSIGNED-SHORT                                }
             {SIGNED-INT                                    }
             {UNSIGNED-INT                                  }
             {SIGNED-LONG                                   }
             {UNSIGNED-LONG                                 }
             {HANDLE [ OF {WINDOW                       } ] }
                          {SUBWINDOW                    }
                          {FONT [font-name]             }
                          {control-type                 }
                          {THREAD                       }
                          {MENU                         }
                          {VARIANT                      }
                          {LAYOUT-MANAGER [layout-name] }

Syntax Rules

  1. The column on the left shows the accepted abbreviations for the terms on the right:
    COMP      COMPUTATIONAL

COMP-1    COMPUTATIONAL-1

COMP-2    COMPUTATIONAL-2

COMP-3    COMPUTATIONAL-3

COMP-4    COMPUTATIONAL-4

COMP-5    COMPUTATIONAL-5

COMP-6    COMPUTATIONAL-6

COMP-X    COMPUTATIONAL-X

COMP-N    COMPUTATIONAL-N
  2. A USAGE clause may be used in any data description entry except those with level-numbers 66, 78, and 88.
  3. A USAGE clause may not be used with an external floating-point data item.
  4. If a USAGE clause is in the data description entry for a group item, then any USAGE clauses that appear for subordinate entries must be of the same type.
  5. The PICTURE string of a COMP, COMP-1, COMP-2, COMP-3, COMP-4, COMP-5, COMP-6, BINARY, or PACKED-DECIMAL item can contain only the symbols 9, S, V, and P. COMP-6 items may not use the S symbol.
  6. The PICTURE string of a COMP-X or COMP-N item may contain only all 9 symbols or all X symbols.
  7. The data description entry for a USAGE IS INDEX data item cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, PICTURE, and VALUE IS.
  8. Level 88 items may not be specified for a USAGE IS INDEX data item.
  9. The data description entry for a USAGE IS POINTER data item cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE. A POINTER data item may have a value clause specified for it, but the value must be the word NULL.
  10. The data description entry for a USAGE IS FLOAT or a USAGE IS DOUBLE data item cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE. FLOAT or DOUBLE data items may have a value clause. The value may be a floating point literal, a numeric literal, or the word ZERO. Here is an example of a Working-Storage Section data item:
    01  F-DATA-1  USAGE IS FLOAT
              VALUE IS 3.97E+24.
  11. The following are collectively called the C-style data types: SIGNED-INT, UNSIGNED-INT, SIGNED-SHORT, UNSIGNED-SHORT, SIGNED-LONG, UNSIGNED-LONG. These data types are similar to the data types found in the C programming language.

    The data description entry for a C-style data type cannot contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE.

  12. control-type is one of the graphical control type names known to the compiler, such as LABEL or ENTRY-FIELD, or the name of an ActiveX, COM, or .NET control.
  13. The data description entry for USAGE HANDLE data items may not contain any of the following clauses: BLANK WHEN ZERO, JUSTIFIED, or PICTURE. If it contains a VALUE clause, the value specified must be the word NULL.
  14. font-name is one of the following identifiers: DEFAULT-FONT, FIXED-FONT, TRADITIONAL-FONT, SMALL-FONT, MEDIUM-FONT, LARGE-FONT.
  15. It should be noted that either the -Df option or the -Cv option will cause the compiler to treat COMP-1 and COMP-2 as FLOAT and DOUBLE, respectively.
  16. layout-name is the name of one of the system's standard layout managers. Currently, this can only be LM-RESIZE.

General Rules

  1. A USAGE clause written at a group level applies to every elementary item subordinate to that group item.
  2. If no USAGE clause is specified, then USAGE IS DISPLAY is implied.
  3. The internal format of a USAGE IS DISPLAY item is ASCII.
  4. The format of an index item is 32-bit signed binary. Its size is always four, and it holds a range of values from -2147483647 to 2147483647. When using a compile switch for compatibility with versions prior to 6.0.0 (-Z52 for example) an index item is 16-bit unsigned binary, size is always two, and it holds values from 0 to 65535.
  5. The format of a COMP-1 data item is 16-bit signed binary. The legal values range from -32767 to 32767. The size of the data item is always two bytes, and the high-order half of the data is stored in the leftmost byte. The PICTURE string that describes the item is irrelevant. Unlike other numeric data types, a size error will occur on a COMP-1, COMP-X, or COMP-N data item only when the value exceeds the physical storage of the item (in other words, the number of "9"s in the item's PICTURE is ignored when size error is determined).
  6. For COMP-2 (decimal storage), each digit is stored in one byte in decimal format. If the value is signed, then an additional trailing byte is allocated for the sign. The storage of COMP-2 is identical with USAGE DISPLAY with the high-order four bits stripped from each byte.
  7. For COMP-3 (packed-decimal storage), two digits are stored in each byte. An additional half byte is allocated for the sign, even if the value is unsigned. The sign is placed in the rightmost position, and its value is 0x0D for negative; all other values are treated as positive (but see rule 18 below). The size of an item (including one for the implied sign) is divided by two to arrive at its actual size (rounding fractions up).
  8. The format of a COMP-4 item is two's-complement binary (the value without its decimal point). COMP-4 values are stored in a machine-independent format. This format places the highest-order part of the value in the leftmost position and follows down to the low-order part in the rightmost position. The number of bytes a data item occupies depends on the number of 9s in its PICTURE and on the presence of various compile-time options. For example, you may include more than eighteen 9s only if your program has been compiled for 31-digit support. This is summarized in the following table:
    # of "9"s | Default | -D1 | -Dm | -D7
    1-2 | 2 | 1 | 1 | 1
    3-4 | 2 | 2 | 2 | 2
    5-6 | 4 | 4 | 3 | 3
    7 | 4 | 4 | 4 | 3
    8-9 | 4 | 4 | 4 | 4
    10-11 | 8 | 8 | 5 | 5
    12 | 8 | 8 | 6 | 5
    13-14 | 8 | 8 | 6 | 6
    15-16 | 8 | 8 | 7 | 7
    17-18 | 8 | 8 | 8 | 8
    19 | 12 | 12 | 9 | 8,9
    20 | 12 | 12 | 9 | 9
    21 | 12 | 12 | 9 | 9
    22 | 12 | 12 | 10 | 10
    23 | 12 | 12 | 10 | 10
    24 | 12 | 12 | 11 | 10,11
    25 | 12 | 12 | 11 | 11
    26 | 12 | 12 | 11 | 11
    27 | 12 | 12 | 12 | 12
    28 | 12 | 12 | 12 | 12
    29 | 16 | 16 | 13 | 13
    30 | 16 | 16 | 13 | 13
    31 | 16 | 16 | 13 | 13
    Note: Where two values are given, the smaller value applies to unsigned data items, and the larger value applies to signed data items.
  9. COMP-5 is primarily used to communicate with external programs that expect native data storage.

    The format of a COMP-5 data item is identical to a COMP-4 data item, except that the data is stored in a machine-dependent format. It is stored in an order that is natural to the host machine. For example, a PIC S9(9) COMP-5 data item is equivalent to a 32-bit binary word on the host machine, and a PIC S9(20) COMP-5 item is equivalent to a 64-bit word.

    Note: Data stored in a COMP-5 field may not be transportable to other machines because different machines have different natural byte-orderings. On many machines (68000, most RISC), COMP-5 is identical to COMP-4. On others (80x86, VAX), it is the same with the bytes in the reverse order.

    A VALUE clause for a COMP-5 data item is stored in a machine-independent format and is adjusted when it is loaded into the data item. This ensures that the value is the same from machine to machine.

    On arithmetic and non-arithmetic stores into COMP-5 items, if truncation is required, by default ACUCOBOL-GT truncates in decimal to the number of digits given in the PICTURE clause. You can use the --TruncANSI compiler option to force truncation in binary to the capacity of the allocated storage of COMP-5 items. The -Dz and --noTrunc options also effects truncation. See Data Storage Options for more information.

    Level 01 and level 77 data items that are COMP-5 are automatically synchronized to an appropriate machine boundary, regardless of any compile-time settings. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.

    If COMP-5 is used with a PIC X(n) data item and assigned an alphanumeric value, the results are undefined. For example, the following code fragment causes NUM to have an undefined number and the resulting value for the last line will be 100:

    NUM PIC X(5) COMP-5.
ALPHANUM PIC X(9).
MOVE "ABC" TO NUM.
MOVE "1,000" TO NUM.
MOVE ALPHANUM TO NUM.
MOVE "100" TO NUM.

    A PIC X(n) data item used with COMP-5 cannot be signed.

  10. The format of a COMP-6 item is identical to a COMP-3 item except that it is unsigned and no space is allocated for the sign. If the number of digits is odd, a zero is added to the left end of the number before it is packed. Thus there are two decimal digits per byte, and the actual size of the item is determined by dividing its PICTURE size by two and rounding up.
  11. A COMP-X data item must be described with a picture string consisting of only 9 or only X symbols. In either case, the data item is treated as an unsigned binary integer, with internal storage similar to that of a COMP-4 data item. If X symbols are used to describe the item, then the number of bytes allocated to the item is the same as the number of X symbols in the picture string. If 9 symbols are used instead, then the number of bytes allocated is the least number of bytes required to hold a number of that size. For example, a PIC 99 data item will be allocated 1 byte; a PIC 9(9) data item will be allocated 4 bytes.

    Regardless of the number of 9 symbols in the item's picture string, the maximum value that can be stored in a COMP-X item is determined by the number of bytes allocated to it (to a maximum of 18 digits, or a maximum of 31 digits if 31-digit support is in effect). For example, a COMP-X item consisting of 1 byte can hold a range of numbers from 0 to 255. A 2-byte COMP-X number can hold from 0 to 65535. A size error occurs on a COMP-X item only when the value is larger than the data item can physically hold. When COMP-X is used with a PIC(X) data item, the maximum is PIC X(8). (This maximum is increased to PIC X(16) when 31-digit support is in effect.)

  12. A COMP-N data item is identical to a COMP-X data item, except that the data is stored in the host machine's native format, instead of machine-independent format.
  13. Data items described as PACKED-DECIMAL are identical to COMP-3. You can cause unsigned PACKED-DECIMAL to be treated as COMP-6 by using a compile-time option.
  14. By default, a BINARY data item is identical to a COMP-4 data item. The compile-time option -D5 treats BINARY data items as COMP-5 items instead.
  15. In VAX/COBOL compatibility mode, a COMP data item is the same as COMP-4 and is treated as binary data.
  16. A pointer data item is treated as an unsigned numeric data item. The internal format differs for each machine. Pointer data items are intended to hold addresses of other data items (see the SET Statement.) A pointer data item may have a VALUE clause specified for it, but the specified value must be the word NULL. This indicates that the pointer does not currently point to any item. If a pointer is not explicitly given an initial value, then its initial value is arbitrary.

    Pointer data items occupy 8 bytes. This provides enough space to hold an address on a 64-bit machine. If you are on a smaller machine, the runtime uses only the first 4 bytes of pointer data items (the trailing 4 bytes remain in memory, they are just left unused). You can use the -Dw compile-time option to adjust the space allocated to pointer data items. You can do this to conserve storage if you know you will not be running on a 64-bit machine.

    Pointers may be used in conditional expressions, where they can be compared to each other or to the value NULL. A comparison involving a pointer must be either "equals" or "not equals" ("greater" and "less than" comparisons are not allowed).

    Level 01 and level 77 data items that are POINTER items are automatically synchronized to an appropriate machine boundary, regardless of any compile-time settings. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.

    Except for the automatic synchronization, USAGE POINTER data items are treated in all respects like USAGE UNSIGNED-LONG data items. This handles all current machines correctly. This behavior may change to meet the requirements of some future machine.

  17. Floating-point data items are stored in a machine-dependent format. USAGE FLOAT items have 4 bytes allocated to them. USAGE DOUBLE items occupy 8 bytes.

    Level 01 and level 77 data items that are USAGE FLOAT or DOUBLE are automatically synchronized to appropriate machine boundaries, regardless of any compile-time settings. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.

  18. The ANSI definition of COBOL does not state how signs should be stored in numeric fields (except for the case of SIGN IS SEPARATE). ACUCOBOL-GT lets you select alternate sign-storage conventions by using the compile-time options -Dca, -Dcb, -Dci, -Dcm, -Dcn, -Dcr, and -Dcv. Specifying a sign-storage convention is sometimes useful when you are exporting and importing data. See Data Storage Options in the ACUCOBOL-GT User's Guide for more information.

    The storage convention affects how data appears in USAGE DISPLAY, COMP-2, and COMP-3 data types. In USAGE DISPLAY, standard ASCII storage, if the sign is incorporated into a digit position, the digit is encoded according to the following table:

    USAGE DISPLAY

    DIGIT VALUE -Dca,

    -Dcb,

    -Dcm,

    -Dcr

    Positive

            -Dci,

    -Dcn

    Positive

            -Dca,

    -Dci,

    -Dcn

    Negative

            -Dcb

    Negative

            -Dcm

    Negative

            -Dcr

    Negative

    0 '0' '{' '}' '@' 'p' ' ' (space)
    1 '1' 'A' 'J' 'A' 'q' '!'
    2 '2' 'B' 'K' 'B' 'r' '"' (double-quote)
    3 '3' 'C' 'L' 'C' 's' '#'
    4 '4' 'D' 'M' 'D' 't' '$'
    5 '5' 'E' 'N' 'E' 'u' '%'
    6 '6' 'F' 'O' 'F' 'v' '&'
    7 '7' 'G' 'P' 'G' 'w' ''' (single-

    quote)

    8 '8' 'H' 'Q' 'H' 'x' '('
    9 '9' 'I' 'R' 'I' 'y' ')'
    Note: For import compatibility with some systems that do not have the symbols "{" and "}", the symbols "[" and "?" are considered equivalent to "{", and the symbols "]", ":", and "!" are considered equivalent to "}", when an item with USAGE DISPLAY is read.

    The next two tables show sign representation for COMP-2 and COMP-3 items, when you are using the -Dca, -Dcb, -Dci, -Dcm, -Dcn, -Dcr, and -Dcv storage conventions. For COMP-2, the trailing byte is reserved for the sign. For COMP-3, the trailing half-byte is reserved for the sign.

    USAGE COMP-2

    -Dca Positive | x'0B'
    -Dcb/-Dci/-Dcm/-Dcn/-Dcr Positive | x'0C'
    -Dca/-Dcb/-Dci/-Dcm/-Dcn/-Dcr Negative | x'0D'

    USAGE COMP-3

    -Dca Positive | x'0F'
    -Dcb/-Dci/-Dcm/-Dcr Positive | x'0C'
    -Dca/-Dcb/-Dci/-Dcm/-Dcr Negative | x'0D
    -Dca/-Dcb/-Dci/-Dcm/-Dcr Unsigned | x'0F'
    -Dcv Unsigned | x'0C'
  19. There are six USAGE types for integer data that simplify communications with other programming languages such as C. These types are designed to provide a portable method for handling machine-dependent data. The six USAGE types handle three classes of machine data: short words, words, and long words. These three correspond to the C data types: short, int, and long. There are signed and unsigned versions of each of these data types.

    These USAGE types are specified without a PICTURE clause (like USAGE INDEX and POINTER).

    The names of the types are:

    SIGNED-SHORT | UNSIGNED-SHORT
    SIGNED-INT | UNSIGNED-INT
    SIGNED-LONG | UNSIGNED-LONG

    Each of these represents a binary value that is stored using the machine's native byte ordering. Since there is no PICTURE phrase, size checking for these items is performed only on byte boundaries. These data types are automatically SYNCHRONIZED.

    The unusual characteristic of these data types is that their size is not necessarily set at compile time. Instead, the size of these items is determined at execution time. This allows them to match the working characteristics of the host machine. For example, a SIGNED-LONG data item will contain 64 bits when run on a DEC Alpha machine, but it will have 32 bits when run on an Intel 80486-based machine. This lets you write one program that can communicate effectively with an external routine written in another language (such as C), regardless of the target environment.

    In order to lay out memory, the compiler assigns a maximum size to each of these data types. This is the number of bytes that the item will occupy. At run time, these items may be reduced in size to match the host machine's characteristics. Any remaining bytes are then treated as FILLER. The -Dw compile option determines the maximum size of these types:

    USAGE -Dw32 -Dw64
    SIGNED-SHORT

    UNSIGNED-SHORT

            2* 2*
    SIGNED-INT

    UNSIGNED-INT

            4 4
    SIGNED-LONG

    UNSIGNED-LONG

            4* 8

    Table entries marked with an asterisk indicate fixed-size items. A fixed-size item is the same size regardless of the target machine. Entries without an asterisk are variable in size. These items will occupy space up to the number of bytes listed in the table.

    Note: The sizes listed in the table above cover all current and anticipated machines that run ACUCOBOL-GT. Future architectures may require changes to the maximum size assigned to these items.

    In the execution environment, these items act in all ways as if they were fixed-size data items of the appropriate size.

    For example, the following code fragment:

       77  LONG-1         SIGNED-LONG.
   77  SIZE-1         PIC 9.

   SET SIZE-1 TO SIZE OF LONG-1.
   DISPLAY SIZE-1.

    will print 4 when run on a 32-bit machine, but it will print 8 when run on a 64-bit machine.

    Examples

    In the following examples, each byte is represented by two hexadecimal digits or by a single quoted character. Each value is shown in the various formats. Also shown is USAGE DISPLAY using the various SIGN options. The following examples use the default ACUCOBOL-GT sign-storage conventions.

    PIC 9(3) VALUE 123.
TRAILING            '1'   '2'   '3'
TRAILING SEPARATE   '1'   '2'   '3'
LEADING             '1'   '2'   '3'
LEADING SEPARATE    '1'   '2'   '3'
COMP-1                    00    7B
COMP-2              01    02    03
COMP-3                    12    3F
COMP-4                    00    7B
COMP-5(68000)             00    7B
COMP-5(8086)              7B    00
COMP-6                    01    23

PIC S9(3) VALUE -123.
TRAILING                 '1'   '2'   'L'
TRAILING SEPARATE  '1'   '2'   '3'   '-'
LEADING                  'J'   '2'   '3'
LEADING SEPARATE   '-'   '1'   '2'   '3'
COMP-1                         FF    85
COMP-2             01    02    03    0D
COMP-3                         12    3D
COMP-4                         FF    85
COMP-5(68000)                  FF    85
COMP-5(8086)                   85    FF
COMP-6             illegal

PIC 9(5)V9 VALUE 12345.6.
TRAILING             '1'   '2'   '3'   '4'   '5'   '6'
TRAILING SEPARATE    '1'   '2'   '3'   '4'   '5'   '6'
LEADING              '1'   '2'   '3'   '4'   '5'   '6'
LEADING SEPARATE     '1'   '2'   '3'   '4'   '5'   '6'
COMP-1               illegal
COMP-2               01    02    03    04    05    06
COMP-3                           01    23    45    6F
COMP-4                           00    01    E2    40
COMP-5(68000)                    00    01    E2    40
COMP-5(8086)                     40    E2    01    00
COMP-6                                 12    34    56

PIC S9(5)V9 VALUE -12345.6.
TRAILING                '1'  '2'  '3'  '4'  '5'  '0'
TRAILING SEPARATE  '1'  '2'  '3'  '4'  '5'  '6'  '-'
LEADING                 'J'  '2'  '3'  '4'  '5'  '6'
LEADING SEPARATE   '-'  '1'  '2'  '3'  '4'  '5'  '6'
COMP-1             illegal
COMP-2             01   02   03   04   05   06   0D
COMP-3                            01   23   45   6D
COMP-4                            FF   FE   1D   C0
COMP-5(68000)                     FF   FE   1D   C0
COMP-5(8086)                      C0   1D   FE   FF
COMP-6             illegal
  20. HANDLE data items make up their own data class and category in COBOL. Internally they are stored as integer values, and behave like numbers when used. A HANDLE data item is normally used to store the handle of a dynamically created object such as a floating window or a graphical control.

    HANDLE data items come in two forms: typed and generic. You create a generic handle when you omit the OF phrase. You create a typed handle when you include the OF phrase.

  21. You may use HANDLE data items only when explicitly allowed, or as part of a MOVE statement, a CALL statement (as a parameter), or in a Boolean expression.
  22. Generic handles may be used in any situation where handles are allowed. When you use a generic handle as the source of a MODIFY statement, you will not be able to use any control-specific property or style names in that statement. This is because the generic handle could be associated with any type of control. In this case, the compiler cannot determine which set of style and property names is valid.
  23. Typed handles may be used in statements where any handle is allowed, or when you are referring to an object of a matching type. For example, a HANDLE OF WINDOW cannot be used as the handle in a DISPLAY LABEL statement. Instead, you must use either a generic handle or a HANDLE OF LABEL. Typed handles allow the compiler to recognize associated style and property names when appropriate. Typed handles also improve the readability of your program by providing additional information about the intended use of the handle, in addition to providing compile-time checking to ensure that you are using the handles in appropriate situations.
  24. Handles may be used in comparisons. There are only two meaningful comparisons: checking for equality or inequality to NULL, and comparison to another handle data item. A handle value of NULL always indicates an invalid handle.
  25. Handles are stored internally as 4-byte binary integers. This information can be useful when you are debugging a program (you can examine the values of handles in the debugger). You should not rely on this definition in your program, however, because it is subject to change in the future.
  26. Handle data items are automatically SYNCHRONIZED on a 4-byte boundary. Note that this occurs regardless of the setting of the -Dl compile-time option (which limits the amount of synchronization). The runtime system requires this level of alignment to avoid generating bus errors on some machines.
  27. If font-name is specified, then the data item described by the USAGE clause is initialized at program startup with the corresponding font handle. This acts identically to placing the statement:
    ACCEPT data-item FROM STANDARD OBJECT "font-name"

    at the beginning of your program, where data-item is the data item described by the USAGE clause and font-name is the same as font-name in the USAGE clause.

Parent topic: Data Description Entry


SIGN Clause

The SIGN clause specifies the location and format of an item's operational sign.

General Format

[ SIGN IS ]  {LEADING } [ SEPARATE CHARACTER ]
             {TRAILING}

Syntax Rules

  1. The SIGN clause may appear only in a numeric data description entry whose PICTURE string contains the S symbol, or on a group item that contains such an entry.
  2. The item must have USAGE DISPLAY.
  3. A SIGN clause may not be used with an external floating-point data item.

General Rules

  1. If the SIGN clause is omitted for a data item, then the operational sign is incorporated into the final digit of the data item. The S symbol does not occupy any space in the data item in this case.
  2. If the SIGN clause is specified, but without the SEPARATE CHARACTER phrase, then the sign is incorporated into the first or last digit of the data item as specified.
  3. If the SEPARATE CHARACTER phrase is specified in the SIGN clause, then the S symbol represents a separate character position and it adds one to the size of the data item. This character is located as the first or last character of the data item as specified in the clause. The sign is represented with a "+" or "-" character as appropriate. The zero value may have either sign.
  4. If the SIGN phrase is specified for a group item, then it applies to each subordinate elementary numeric data item. A SIGN phrase specified for an elementary data item takes precedence over a SIGN phrase specified for one of its group items. If more than one group item has a SIGN phrase specified for it in a hierarchy, the lowest level one takes precedence.
Parent topic: Data Description Entry


OCCURS Clause

The OCCURS clause allows for the creation of tables or arrays.

Format 1

OCCURS table-size TIMES

   [ {ASCENDING } KEY IS {key-name} ... ] ...
     {DESCENDING}

   [ INDEXED BY {index-name} ... ]

Format 2

OCCURS [ min-size TO ] max-size TIMES DEPENDING ON dep-item

   [ {ASCENDING } KEY IS {key-name} ... ] ...
     {DESCENDING}

   [ INDEXED BY {index-name} ... ]

Syntax Rules

  1. table-size is a positive integer that specifies the exact number of occurrences.
  2. min-size is an integer that specifies the minimum number of occurrences. Its value must be greater than or equal to zero. If omitted, it has a default value of one.
  3. max-size is an integer that specifies the maximum number of occurrences. Its value cannot be less than min-size; it cannot be larger than 2147483647.
  4. dep-item is the name of an elementary unsigned integer data item. Its value specifies the current number of occurrences.
  5. Index-name is an index-name. It associates an index with the table. Index-name is implicitly defined by the INDEXED phrase. It may not be defined elsewhere in the program. Each index-name must be a unique word in the program, because it cannot be qualified.
  6. key-name is the data-name of the entry that contains the OCCURS clause, or an entry subordinate to it. key-name may be qualified. Each key-name after the first must name a subordinate item to the entry containing the OCCURS clause. A key-name may not contain an OCCURS clause unless that key-name is the name of the subject of the current OCCURS clause.
  7. If a Format 2 OCCURS clause appears in a record description for a file, dep-item must appear in the same record.
  8. An item described by a Format 2 OCCURS clause can be followed, in the same record description, only by items subordinate to it.
  9. An OCCURS clause may not appear in a data description entry that has a level-number of 66, 78, or 88. A variable occurrence data item (one that has a Format 2 OCCURS clause) may not be subordinate to another data item that has an OCCURS clause.
  10. The dep-item may not occupy any character positions subordinate to the data item described by that OCCURS clause.

General Rules

  1. The OCCURS clause defines tables. All items subordinate to an OCCURS clause must be referenced with subscripting or indexing.
  2. Except for the OCCURS clause itself, all data description clauses associated with that data item apply to each occurrence of the item.
  3. A Format 1 OCCURS clause defines a fixed-size table.
  4. A Format 2 OCCURS clause defines a table that contains a variable number of occurrences. The current number of occurrences depends on dep-item. Only the number of occurrences is variable; the table's size is fixed (max-size). dep-item must fall in the range from min-size to max-size. Values contained in the table that are beyond the current number of occurrences (dep-item) are unpredictable.
  5. The size occupied by a table is the size of one of its occurrences multiplied by the maximum number of occurrences in the table (max-size in Format 2).
  6. If a group item containing a subordinate data item with a Format 2 OCCURS clause is involved in an operation, the operation uses only that part of the table specified by dep-item.
  7. Index names are treated in all respects as USAGE INDEX data items by the compiler.
  8. The KEY IS phrase indicates that the data is arranged in ascending or descending order according to the values in the data items named by key-name. The position of each key-name in the list determines its significance. The first key-name is the most significant, the last is the least significant. The KEY IS phrase is used by the SEARCH ALL verb.
Parent topic: Data Description Entry


SYNCHRONIZED Clause

The SYNCHRONIZED clause specifies elementary item alignment on word boundaries of the computer's memory.

General Format

{SYNCHRONIZED}  [LEFT ]
{SYNC        }  [RIGHT]

Syntax Rules

  1. SYNC is an abbreviation of SYNCHRONIZED.
  2. The SYNCHRONIZED clause can be used for elementary items only.
  3. A SYNCHRONIZED clause may not be used with an external floating-point data item.

General Rules

  1. The SYNCHRONIZED clause is used to specify that word boundary alignment should be performed for the data item. Normally, data contained in records is aligned on byte boundaries. Only data items whose underlying representation is binary are affected by the SYNCHRONIZED clause.
  2. The SYNCHRONIZED clause causes the data item to be placed on a boundary that is an even multiple of the natural size of the data item. The following table lists the boundary used for each size of data item:
    Data Size | Boundary Multiple
    1-2 | 2
    3-4 | 4
    5-8 | 8
  3. A group item that contains a synchronized data item is also synchronized on the same boundary. Regardless of the effects of synchronization, a group item always begins at the same location as its first elementary data item.
  4. Synchronization may result in the creation of filler bytes. These bytes count in the size of any group item that contains them. For this reason, a group item that contains synchronized data may be larger than the total size of its elementary items.
  5. Level 01 and level 77 data items that are not otherwise synchronized are placed on a boundary that can be selected at compile time. By default, these items are placed at word boundaries that are divisible by two.
  6. Level 01 and level 77 data items that are POINTER or COMP-5 items are automatically synchronized to an appropriate machine boundary, regardless of any compile-time settings. All C-style data types are automatically synchronized regardless of their level. This allows you to pass these items safely to C subroutines without having to concern yourself with alignment.
  7. A compile-time (-Dl) option can be used to cut back the maximum boundary multiple. For example, -Dl4 would cause items of size 1 or 2 to be synchronized on 2-byte boundaries, and all other items synchronized on 4-byte boundaries. If this option is not specified, then the maximum boundary multiple depends on the compatibility mode being used:
    Mode | Boundary Limit
    VAX COBOL | 8
    RM/COBOL | 2
    ICOBOL | 1

    A limit of 1 effectively inhibits synchronization.

  8. The LEFT and RIGHT options are treated as commentary. They have the same effect as a SYNCHRONIZED clause without either option.
Parent topic: Data Description Entry


JUSTIFIED Clause

The JUSTIFIED clause specifies alternate data positioning rules for alphanumeric data.

General Format

{JUSTIFIED} RIGHT
{JUST     }

Syntax Rules

  1. JUST is an abbreviation for JUSTIFIED.
  2. The JUSTIFIED clause may be used for elementary items only.
  3. The JUSTIFIED clause may not be used on index, numeric, or edited data items. It may be used only on alphabetic and alphanumeric data items.

General Rules

When an operation transfers data to an item described with the JUSTIFIED clause, the standard alignment rules are altered.

  1. If the sending item is larger than the receiving item, excess characters are truncated from the left.
  2. If the sending item is smaller than the receiving item, data is aligned at the rightmost character position of the receiving item. The excess characters on the left are filled with spaces.
Parent topic: Data Description Entry


BLANK WHEN ZERO Clause

The BLANK WHEN ZERO clause causes the data item to be filled with spaces when its value is zero.

General Format

BLANK WHEN ZERO

Syntax Rules

  1. The BLANK WHEN ZERO clause may be used only for a numeric or numeric edited elementary item whose picture does not contain S or "*".
  2. The data item must have USAGE DISPLAY.
    Note: The compiler accepts any sign designation other than S without declaring an error. That includes "+", "-", CR, and DB.

General Rules

  1. The BLANK WHEN ZERO clause causes an item to be filled with spaces when its value is zero.
  2. Any numeric item described with a BLANK WHEN ZERO clause becomes a numeric edited item.
Parent topic: Data Description Entry


VALUE Clause

The VALUE clause defines the initial value of Working-Storage. It also describes the values associated with conditionals.

Format 1

VALUE IS value-lit

Format 2

{VALUE IS  } { low-val [ {THROUGH} high-val ] } ...
{VALUES ARE}             {THRU   }

    [ WHEN SET TO FALSE false-val ]

Format 3

78 user-name VALUE IS {literal-1} [ {+} literal-2 ] .
                      {NEXT     }   {-}
                                    {*}
                                    {/}

Syntax Rules

  1. value-lit is a numeric or non-numeric literal that defines the initial value of a Working-Storage item.
  2. low-val is a numeric or non-numeric literal that defines the value of a condition, or the lower value of a condition range.
  3. high-val is a numeric or non-numeric literal that defines the upper value of a condition range. It must be the same type as low-val and must have a value greater than low-val.
  4. false-val is a numeric or non-numeric literal that defines the FALSE value for the corresponding data item.
  5. literal-1 is a numeric or alphanumeric literal. If literal-2 is specified, then literal-1 must be a numeric, non-floating-point literal. literal-1 can also be a LENGTH OF expression, as described in Numeric Literals.
  6. literal-2 is a numeric, non-floating point literal or a LENGTH OF expression.
  7. The VALUE clause may not be used for any item whose size is variable.
  8. A VALUE clause may not be used with an external floating-point data item.
  9. All literals used in a VALUE clause must have a value which falls within the range of allowed values for the item's PICTURE clause. Non-numeric literals may not exceed the size of the item. Numeric items must have numeric literals. Alphabetic, alphanumeric, group, and edited items must have non-numeric literals.
  10. The words THROUGH and THRU are equivalent.
  11. The Format 2 VALUE clause may be used only in a condition-name (level 88). Its use is required in this case.
  12. VALUE clauses may appear in the File Section and the Linkage Section. They have no effect in these sections unless they are part of condition-name entries (level 88s) or named constants (level 78s).

    Their presence in these two sections simplifies the management of COPY libraries. For example, if you plan to use the same COPY library in Working Storage in program-A and in Linkage in program-B, you need not remove the VALUE clauses in the Linkage Section.

  13. The VALUE clause may not be specified for a group item that contains subordinate items with any of the following clauses: JUSTIFIED, SYNCHRONIZED, or USAGE (other than USAGE DISPLAY).
  14. A Format 1 VALUE clause may not appear on a data item that is subordinate to a REDEFINES clause.
  15. A level 78 entry associates a value with the name of a constant, and user-name is a user-defined word that names the constant. user-name must be unique, because it may not be qualified.

General Rules

  1. A Format 1 VALUE clause specifies the initial state of a Working-Storage item or the value of a named constant. A Format 2 VALUE clause defines a condition-name. A Format 3 VALUE clause defines a constant.
  2. When a VALUE clause is applied to an edited item, that item is treated as if it were alphanumeric. Editing characters in the PICTURE clause count toward the size of the item but have no effect on initialization. The literals must therefore appear in edited form.

Initialization (Format 1)

  1. A Format 1 VALUE clause takes effect only when the program enters its initial state.
  2. The VALUE clause initializes its data item to the value of value-lit.
  3. If no VALUE clause is specified, the initial value of a Working-Storage item is set to spaces, or the value specified with the -Dv compile option. This may, or may not, be a legal value for the item.
  4. When a VALUE clause appears on a data item that is subordinate to an x OCCURS clause, every occurrence of that data item is initialized to the specified value.
  5. When a VALUE clause is applied to a group item, that item is initialized as if it were an alphanumeric item. It is not affected by characteristics of any subordinate items to the group. No subordinate item may contain a VALUE clause within this group.
  6. The BLANK WHEN ZERO and JUSTIFIED clauses do not affect initialization.

Condition-Name (Format 2)

  1. The VALUE clause is required in a condition-name entry. The only clauses allowed in a condition-name entry are the level-number (88), the condition-name itself, and its VALUE clause. See File Section for examples of condition-name entries.
  2. The characteristics of the condition-name are implicitly the same as those of its condition-variable. The condition-variable is the immediately preceding completed record description entry.
  3. The VALUE clause describes the values of the condition-variable that imply a true state for the associated condition-name. This consists of a single value, a range of values, or a set of both single values and ranges. For example VALUES ARE 1, 2, 4 THRU 7 would define a condition-name that was "true" when its associated condition-variable had any of the values 1, 2, 4, 5, 6, and 7.
  4. The WHEN SET TO FALSE phrase defines the "false" value for the condition-name. The SET statement cannot set the condition-name to FALSE unless a "false" value is specified here.

Level 78 Constant (Format 3)

  1. When it is used with a level 78 item, the VALUE clause associates a literal with a user-defined word. The user-defined word is then called a named constant. A named constant may be used anywhere the corresponding literal may be used. The compiler replaces each occurrence of the named constant with the literal.
  2. The literal is constructed as follows:
    • If literal-1 is specified (without literal-2), then user-name acts as a synonym for that literal in the remainder of the program.
    • If NEXT is specified (without literal-2), then user-name acts as an integer numeric constant whose value is the virtual address of the first byte past the end of the immediately preceding data item. However, if the immediately preceding data item is a group item, then the value is the virtual address of the beginning of the group item. Note that the effect of synchronization and data alignment may mean that the next data item does not start at the same virtual address as the first byte past the end of the previous data item. This construct has undefined effects if the immediately preceding data item is, or is part of, a data item greater than 64KB in size.
      Note: The use of NEXT is designed for compatibility with other COBOL compilers. The effects of data alignment and data space segmentation make this feature difficult to use with standard ACUCOBOL-GT code. Acucorp does not recommend its use except when you are migrating code that already contains similar syntax. ACUCOBOL-GT provides other techniques for address manipulation (e.g. POINTER data items) and size computation (e.g. SET TO SIZE OF statement).
    • If literal-2 is specified, then user-name is an integer numeric constant whose value is the same as it would be without literal-2 specified, acted upon by the specified operation. For example, the following two level 78s have the same value:
         78  THREE         VALUE 3.
   78  THREE-AGAIN   VALUE 1 + 2.

      In some cases, literal-1 and literal-2 may, themselves, be level 78s. For example:

      78  ONE           VALUE 1.
   78  TWO           VALUE ONE + 1.
   78  THREE         VALUE TWO + 1.

      When literal-2 is used, both literal-1 and literal-2 are evaluated as integers, and the arithmetic is done using 32-bit integer arithmetic. The result is always an integer.

  3. You may use a level 78 named constant as a repeat count in a PICTURE string. This means that, in a PICTURE string, you may substitute a level 78 for a number in parentheses. In the following example, DATA-1 and DATA-2 are both the same size:
    78  LENG-20   VALUE 20.
01  DATA-1    PIC X(20).
01  DATA-2    PIC X(LENG-20).
Parent topic: Data Description Entry


RENAMES Clause

The RENAMES clause provides an alternate data name for a set of data items.

General Format

66 new-name RENAMES rename-1 [ {THRU   } rename-2 ]
                               {THROUGH}

Syntax Rules

  1. The level-number (66) and new-name are not actually part of the RENAMES clause. They are included in the General Format for clarity.
  2. new-name is a user-defined word that is the name of the item being described.
  3. rename-1 is the data name of the leftmost data item in the area.
  4. rename-2 is the data name of the rightmost data item in the area.
  5. All RENAMES entries referring to data items in a logical record must immediately follow the last data description entry of that record.
  6. new-name may not be used as a qualifier.
  7. new-name must be unique, because it may not be qualified.
  8. rename-1 and rename-2 must be the names of items in the same logical record.
  9. The data description entries for rename-1 and rename-2 may not contain or be subordinate to an OCCURS clause.
  10. A level 66 entry may not rename another level 66 entry. Nor can it rename a level 78, 88, level 01, or level 77 entry.
  11. None of the items in the range from rename-1 to rename-2 may contain variable occurrence items.
  12. The words THRU and THROUGH are equivalent.
  13. rename-2 may not be subordinate to rename-1. The beginning of rename-2 cannot be to the left of the beginning of rename-1. The end of rename-2 must be to the right of the end of rename-1.

General Rules

  1. If rename-2 is used, new-name contains all the character positions between the start of rename-1 and the end of rename-2.
  2. If rename-2 is used, new-name is treated as a group item. If rename-2 is not used, all the data attributes for rename-1 become attributes of new-name. In this case, you are providing an alternate name for a single data item.
Parent topic: Data Description Entry


Screen Section

The Screen Section describes the format, layout, and behavior of console screens. It contains one or more uniquely named screen description entries.

A screen item in the Screen Section is analogous to a data item in the Working-Storage Section. The terms screen item or Screen Section entry may refer to an elementary item or a group item.

Screen Section entries:

  • provide "form level" ACCEPT and DISPLAY, which means a single ACCEPT or DISPLAY statement can activate any number of elements on the screen.
  • are referenced by Format 2 ACCEPT and DISPLAY statements in the Procedure Division.
  • define one or more controls, data fields, or literals, and their associated attributes.

ACCEPT and DISPLAY statements that reference a Screen Section entry include built-in features that greatly simplify programming. A single ACCEPT statement will reference the controls and input fields that you named and defined in a Screen Section entry, and a single DISPLAY statement will display the corresponding collection of prompts for the user. When you code your programs with Format 2 ACCEPT and DISPLAY, the tab and arrow keys (or their substitutes if you have customized the keyboard) are automatically functional so the user can move from field to field during data entry.

See Screen Section for more on the Screen Section.

Note: Since Screen Section entries are defined in the Data Division but acted upon in the Procedure Division, you will want to read the information given here with that for the Format 2 ACCEPT and DISPLAY described in Procedure Division Statements.

General Format

SCREEN SECTION.

   [ screen-description ] ...

Syntax Rules

  1. Each level 01 screen item described in the Screen Section must be uniquely named.
  2. Subordinate screen names need not be unique if they can be made unique through qualification.

Parent topic: Data Division


Screen Description Entry

A screen description entry specifies the characteristics of a single screen item. Many of the phrases permitted in a Screen Description Entry are explained in Common Screen Options.

General Format

Format 1

level-number  [ screen-name ]
              [ FILLER      ]

Remaining phrases are optional, can appear in any order.

GRAPHICAL
CHARACTER
{PICTURE} IS picture-string
{PIC    }

[ [FROM from-item] [TO to-item] ]
[       USING using-item        ]

[USAGE IS] DISPLAY

[SIGN IS] {LEADING } SEPARATE CHARACTER
          {TRAILING}

OCCURS table-size TIMES

{JUSTIFIED} RIGHT
{JUST     }

BLANK WHEN ZERO

VALUE IS value-lit

{BLANK} {SCREEN}

{ERASE} {LINE  }
        {EOS   }
        {EOL   }

LINE [ NUMBER IS [PLUS] line-no ]
                 [ +  ]
                 [ -  ]

{COLUMN  } [ NUMBER IS [PLUS] col-no ]
{COL     }             [ +  ]
{POSITION}             [ -  ]
{POS     }

SIZE IS length

COLOR IS color-val
COLOUR
FOREGROUND-COLOR IS fg-color
FOREGROUND-COLOUR
BACKGROUND-COLOR IS bg-color
BACKGROUND-COLOUR
{BACKGROUND-HIGH     }
{BACKGROUND-LOW      }
{BACKGROUND-STANDARD }

{BELL}
{BEEP}

{UNDERLINED}
{UNDERLINE }

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{BLINKING}
{BLINK   }

{REVERSE-VIDEO}
{REVERSED     }
{REVERSE      }

SAME
OUTPUT {LEFT    }
       {RIGHT   }
       {CENTERED}

{NO-ECHO}
{NO ECHO}
{SECURE }
{OFF    }

PROMPT [ CHARACTER IS prompt-lit ]

{UPPER}
{LOWER}

{AUTO         }
{AUTO-SKIP    }
{AUTOTERMINATE}
{TAB          }

{REQUIRED   }
{EMPTY-CHECK}

{FULL        }
{LENGTH-CHECK}

{ZERO-FILL   }
{NUMERIC-FILL}

HELP-ID {IS} help-id
        {= }

ENABLED {IS} enabled-state
        {= }

VISIBLE {IS} visible-state
        {= }

{BEFORE } PROCEDURE IS { proc-1 [{THROUGH} proc-2] }
{AFTER  }                        {THRU   }

{EXCEPTION}            { NULL                      }

Format 2

level-number [ screen-name ]
             [ FILLER      ]

{control-type-name}
{OBJECT control-type}

[ title ]

Remaining phrases are optional, can appear in any order.

GRAPHICAL
CHARACTER
{IDENTIFICATION} {IS} control-id
{ID            } {= }

{PICTURE } IS picture-string
{PIC}

{FROM } [MULTIPLE] from-item
{VALUE} [TABLE   ]

TO [MULTIPLE] to-item

{USING} [MULTIPLE] using-item
{VALUE} [TABLE   ]

OCCURS table-size TIMES

LINE [ NUMBER IS [PLUS] line-no ] [CELL  ]
                 [ +  ]           [CELLS ]
                 [ -  ]           [PIXEL ]
                                  [PIXELS]

{COLUMN  } [ NUMBER IS [PLUS] col-no ]  [CELL  ]
{COL     }             [ +  ]           [CELLS ]
{POSITION}             [ -  ]           [PIXEL ]
{POS     }                              [PIXELS]

CLINE NUMBER cline-num

CCOL NUMBER ccol-num

SIZE   {IS} length   [CELL  ]
       {= }          [CELLS ]
                     [PIXEL ]
                     [PIXELS]

LINES  {IS} height   [CELL  ]
       {= }          [CELLS ]
                     [PIXEL ]
                     [PIXELS]

CSIZE  {IS} clength  [CELL ]
       {= }          [CELLS]

CLINES {IS} cheight  [CELL ]
       {= }          [CELLS]

MAX-HEIGHT {IS} max-height
           {= }

MAX-WIDTH  {IS} max-width
           {= }

MIN-HEIGHT {IS} min-height
           {= }

MIN-WIDTH  {IS} min-width
           {= }

TITLE {IS} title
      {= }

KEY {IS} key-letter
    {= }

STYLE {IS} style
      {= }

{style-name} ...

FONT {IS} font-handle
     {= }

{COLOR } IS color-val
{COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

{BACKGROUND-HIGH     }
{BACKGROUND-LOW      }
{BACKGROUND-STANDARD }

{BELL}
{BEEP}

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{REVERSE-VIDEO}
{REVERSED     }
{REVERSE      }

{REQUIRED   }
{EMPTY-CHECK}

LAYOUT-DATA {IS} layout-data
            {= }
ENABLED {IS} {enabled-state}
        {= }

VISIBLE {IS} {visible-state}
        {= }

HELP-ID {IS} help-id
        {= }

EVENT-LIST    {IS} ( event-value { event-value ... } )
              {= }

AX-EVENT-LIST {IS} ( ax-event-value { ax-event-value ... } )
              {= }

EXCLUDE-EVENT-LIST {IS} list-state
                   {= }

{property-name          } {IS } { property-value            }
{PROPERTY property-type } {ARE} { ( {property-value} ... )  }
                          {=  } { {MULTIPLE} property-table }
                                  {TABLE   }

{BEFORE   } PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
{AFTER    }                         {THRU   }
{EXCEPTION}              { NULL                        }
{EVENT    }

Format 3

level-number [ screen-name ]
             [ FILLER      ]

{assembly-name}
{OBJECT assembly-name}

[ title ]
NAMESPACE { IS } "namespace"

CLASS-NAME { IS } "class-name"

Remaining phrases are optional.

HANDLE { IS } handle-1
VERSION { IS } "version"

CULTURE { IS } "culture"

STRONG-NAME { IS } "strong-name"

CONSTRUCTOR { IS } CONSTRUCTOR[n] parameters...

MODULE { IS } "module"

FILE-PATH { IS } "file-path"

SIZE  {IS} length [CELL  ]
      {= }        [CELLS ]
                  [PIXEL ]
                  [PIXELS]

LINES {IS} height [CELL  ]
      {= }        [CELLS ]
                  [PIXEL ]
                  [PIXELS]

Syntax Rules

  1. Each screen description entry must start with a level-number from 01 through 49.
  2. Each level 01 screen description entry must have a screen-name specified. screen-name is a user-defined word.
  3. A screen-name may be referenced only in those contexts where it is explicitly allowed.
  4. An ACCEPT statement may reference only a screen-name that has a TO or USING clause specified for it, or is a group item that contains such a screen entry.
  5. from-item and using-item are data items.
  6. to-item is a literal or a data item.
  7. table-size is an integer literal.
  8. fg-color, bg-color, cline-num, ccol-num, clength, cheight, color-val, control-id, layout-data, enabled-state, visible-state, and help-id are integer literals or data items.
  9. max-height, max-width, min-height, and min-width are numeric data items or numeric literals.
  10. line-no, col-no, length, and height are numeric literals or data items. In Format 1, these must be integer values.
  11. value-lit is a alphanumeric literal or a figurative constant.
  12. prompt-lit is a single-character alphanumeric literal or the figurative constant SPACE, ZERO, or QUOTE.
  13. control-type-name is one of the control type reserved words known by the compiler.
  14. control-type is a numeric literal or data item. It may not be subscripted or reference modified.
  15. title and key-letter are alphanumeric literals or data items.
  16. font-handle is a USAGE HANDLE or HANDLE OF FONT data item that contains a valid font handle.
  17. syle-name is the name of a style associated with the class of control being described. If the control-type-name phrase is omitted, then you may not use the style-name phrase. The STYLE phrase may be used instead.
  18. property-name is the name of a property specific to the type of control being referenced. If the type of control is unknown to the compiler (as in a DISPLAY OBJECT object-1 statement), then property-name may not be used. You must use the PROPERTY property-name option instead.
  19. property-name is a numeric literal or data item. It may not be subscripted or reference modified. It identifies the property to use. The numeric values that identify the various control properties can be found in the COPY library controls.def.
  20. property-value is a literal or data item. Note that the parentheses in the phrase are required.
  21. property-table is a data item that appears in a one-dimensional table. No index should be specified.
  22. In Format 1, if the PICTURE clause is used, then at least one of the FROM, TO, or USING clauses must also be used. The VALUE clause cannot be used. In Format 2, if the PICTURE clause is used, then you must specify one of the FROM, TO, USING, or VALUE phrases.
  23. The MULTIPLE option and the PICTURE phrase cannot be used in the same entry.
  24. The JUSTIFIED and BLANK WHEN ZERO clauses may be specified only if the PICTURE clause is also specified.
  25. The COLOR clause may not be specified if either the FOREGROUND-COLOR or BACKGROUND-COLOR clause is specified.
  26. You may not use either the FROM or TO phrase if you use the USING phrase.
  27. In a Format 1 entry, if the VALUE phrase is used, then its meaning depends on the following data element. If it is a literal, then VALUE is synonymous with FROM. Otherwise, it is synonymous with USING.
  28. If you use the MULTIPLE option of either the FROM, TO, or USING phrase, the following data element must contain an OCCURS clause or be subordinate to an OCCURS clause. The corresponding table must be one-dimensional. The data element should not be subscripted.
  29. The following items may reference a table containing the appropriate type of data items, providing its entry is subordinate to an OCCURS clause: COLOR, HELP-ID, VISIBLE, ENABLED, ID, STYLE, FONT, TITLE, LINE, COL, SIZE, LINES, CCOL, CLINE, CSIZE, CLINES, KEY, and PROPERTY. See the description of the OCCURS Clause.
  30. In Format 1, HELP-ID, VISIBLE, and ENABLED may be specified only for group items. The effect is to apply the phrase to each control contained in the group. You can override the setting for a particular control or sub-group by specifying another HELP-ID, VISIBLE, or ENABLED phrase. These phrases have no effect on screen items that are not controls.
  31. event-value and ax-event-value are numeric literals or data items that identify an event type. List elements must be enclosed by parentheses. Elements must be separated by a space. If the list contains a single element, the parentheses can be omitted.
  32. list-state is an integer literal or numeric data item. Valid values are 0 and 1.
  33. assembly-name is the name of a .NET assembly defined in a COPY file created by NETDEFGEN. This must be the DLL name of a graphical control, not an executable file. Graphical controls are generated by Visual Studio when a developer selects a Windows Control Library project type.
  34. handle-1 is a USAGE HANDLE or PIC X(10) data item.
  35. A value surrounded by quotation marks is an alphanumeric literal and is case-sensitive. Literal values for assembly parameters are located in the COPY file generated by NETDEFGEN. The same COPY file must be included in the SPECIAL-NAMES paragraph of your program.
  36. The optional phrases may be specified in any order.
  37. CELL(S) and PIXEL(S) are mutually exclusive for the same phrase.
  38. In Format 2, the PLUS phrase requires PIXEL(S) to follow if the preceding LINE Number or COLUMN Number also used PIXEL(S).
  39. You may mix PIXEL and conventional coordinates/sizing in the same statement, as shown here:
    DISPLAY push-button AT 00100200 PIXELS
         LINES 50 PIXELS
         SIZE 5.
  40. CELL and CELLS are equivalent.
  41. PIXEL and PIXELS are equivalent.
  42. IS and "=" are synonymous.
    Note: Because the Screen Section is not part of ANSI-standard COBOL, there is substantial variation in the syntax supported by various COBOL vendors. ACUCOBOL-GT supports a superset of most other Screen Section implementations. This situation results in a large number of reserved words with the same meaning. These synonyms are detailed in each of the following rules. We recommend that you restrict yourself to one of the synonyms for each option in order to improve your program's clarity.
  43. AUTO, AUTO-SKIP, and AUTOTERMINATE are equivalent.
  44. NO-ECHO, NO ECHO, OFF, and SECURE are equivalent.
  45. PIC is an abbreviation for PICTURE.
  46. JUST is an abbreviation for JUSTIFIED.
  47. BLANK and ERASE are equivalent.
  48. COLUMN, COL, POSITION, and POS are equivalent.
  49. BELL and BEEP are equivalent.
  50. UNDERLINE and UNDERLINED are equivalent.
  51. HIGHLIGHT, HIGH, and BOLD are equivalent.
  52. LOWLIGHT and LOW are equivalent.
  53. BLINK and BLINKING are equivalent.
  54. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  55. REQUIRED and EMPTY-CHECK are equivalent.
  56. FULL and LENGTH-CHECK are equivalent.
  57. MULTIPLE and TABLE are equivalent.

General Rules

  1. When a screen-name is referenced by an ACCEPT or DISPLAY statement, that screen entry and all subordinate screen entries are acted upon at once. This allows you to accept or display many fields with one statement.
  2. The word NULL in the PROCEDURE phrase indicates that there is no procedure. It has the same effect as omitting the PROCEDURE phrase altogether and is essentially commentary.
  3. Screen Section entries may include the labels GRAPHICAL and CHARACTER. These markings have the effect of restricting the display of the elements nested within them. The elements contained in a GRAPHICAL Screen Section entry are displayed only when the program is run on a graphical system. The contents of a CHARACTER Screen Section entry are displayed only when the program is run on a character-based system. When the program attempts to execute a marked entry on a system of the opposite type, that entry is ignored.

    The purpose of these phrases is to better allow you to develop and support two distinct user interfaces in one program; a user interface for graphical systems, and a user interface for character-based systems. The GRAPHICAL and CHARACTER labels allow you to place and maintain all of the screen definition code in one place (the Screen Section), while also allowing you to customize the look and function of the user interface for these two classes of systems. For many developers, this approach is easier and produces more satisfying results than attempting to develop a single, generic user interface that works well on both types of systems.

    The following code provides an example of this approach. Suppose you want a label that describes a set of function keys to be displayed along the bottom of the screen. However, when you run the program on a graphical system you want to display push buttons instead.

    A Screen Section entry to do this might look like:

    01  function-key-screen.
    03  line 24.
    03  character.
        05  "F1 = Exit, F2 = Lookup, F3 = Help".
    03  graphical.
        05  push-button, "E&xit", self-act,
            exception-value = 1,
            column 3.
        05  push-button, "&Lookup", self-act,
            exception-value = 2,
            column + 3.
        05  push-button, "&Help", self-act,
            exception-value = 3,
            column + 3.

    When the program executes a "DISPLAY FUNCTION-KEY-SCREEN" statement, it displays the line of text on character-based systems, or the set of push buttons on a graphical system.

    Note: The use of these labels also allows you to create two screen description entries with the same name. In statements where a Screen Section name is allowed, you may now reference an ambiguous (duplicate) Screen Section name. When you do so, the name must resolve to exactly two Screen Section items, one having the CHARACTER attribute and the other having the GRAPHICAL attribute. The compiler constructs conditional code for these cases. The Screen Section item with the CHARACTER attribute is used when the program runs on a character-based system; the GRAPHICAL item is used on graphical host systems. One use for this feature is to keep a program's original screen layouts for use on character systems while creating all new screens for graphical systems. By giving the screens the same name, you can keep the existing processing logic unchanged.

Format 1 Only Rules

  1. A Format 1 statement describes any of three types of screen description entries:
    1. If a VALUE clause is specified, the screen entry is a display literal.
    2. If a PICTURE, TO, FROM, or USING clause is specified, then the screen entry is a data field.
    3. If VALUE, PICTURE, TO, FROM, or USING is not specified, then the screen entry is a group item.
  2. A LINE, COLUMN, BLANK, or BELL clause specified for a group item is acted upon immediately when that group item is accessed by an ACCEPT or DISPLAY statement. All other clauses specified for a group item are applied to each screen entry subordinate to that group item.
  3. If the same clause is specified more than once for a particular screen entry, the clause specified at the lowest level within the hierarchy is the one which takes effect.
  4. The level-number, screen-name, USAGE, SIGN, JUSTIFIED, and BLANK WHEN ZERO clauses follow the rules for data items appearing in Working Storage. These rules are in Data Description Entry.
  5. The PICTURE, OCCURS, and VALUE clauses have meanings similar to those clauses in Working Storage, but have some additional properties when used in the Screen Section.
  6. The HELP-ID, VISIBLE, and ENABLED phrases may be specified only for group items. The effect is to apply the phrase to each control contained in the group. You can override the setting for a particular control or sub-group by specifying another HELP-ID, VISIBLE, or ENABLED phrase. These phrases do not affect screen items that are not controls.
  7. All other clauses are described in Common Screen Options.

Format 2 (SCREEN CONTROLS) only Rules

  1. A Format 2 Screen Section entry defines a screen control.
  2. control-type-name identifies the type of the control. Use the OBJECT control-type phrase when the type of the control is not known at compile time. control-type must contain the identifying number of a control type known to the system. If it does not correspond to any control type, the Screen Section entry is ignored. The identifying number of each control type is defined in the controls.def file.
  3. When you DISPLAY a Screen Section control, the following steps are performed:
    • If this is the first DISPLAY of this control, the runtime builds a new control of the specified type.
    • The various properties specified by the Screen Section control phrases are set. Unspecified properties are then assigned default values when the control is initially created. Properties are assigned in the order listed in the Screen Section, except that the VALUE property is always assigned last.
    • The control is displayed or updated on the screen.
    • The cursor is positioned after the control.
  4. When you ACCEPT a Screen Section control, that control receives the input focus, and the runtime system processes user actions until the user terminates the ACCEPT according to the rules for the ACCEPT verb.
  5. When you DISPLAY a Screen Section group item, each subsidiary Screen Section entry is displayed. This can be a mix of textual fields and graphical controls. When you ACCEPT a Screen Section group item, the cursor (or input focus) is placed according to the rules for the ACCEPT verb, and the runtime proceeds to accept data from the user for each field or control. The runtime automatically handles cursor movements between the fields and controls.
  6. Screen Section controls are assigned field numbers in the same way as Format 1 Screen Section entries. If the control is activatable (the user can interact with the control), it is given a field number. Controls that cannot take user input (e.g., LABEL controls) are not given field numbers. Field numbers are assigned sequentially, starting with 1, for each appropriate Format 1 or Format 2 Screen Section entry subordinate to a given 01-level group item. For Screen Section controls that omit the ID phrase, but have an implied field number, the corresponding control is given that field number as its ID.

    Note that the field number is not assigned until the control is created.

  7. If you specify a PICTURE, the memory for that picture is allocated in the Screen Section entry. Each DISPLAY of that entry moves the data in the FROM or USING data item to itself using the standard MOVE rules. That entry is then used as the value of the control. Each ACCEPT of that entry stores the control's value in the Screen Section entry and then moves the entry into the TO or USING data item in accordance with the standard MOVE rules. If you omit the PICTURE phrase, the control's value is retrieved directly from the FROM or USING item and stored directly in the TO or USING item. Note that specifying a PICTURE allocates additional memory. As a result, it is preferable to specify a PICTURE only in cases where you need to reformat the data (e.g., by specifying a numeric-edited PICTURE).
  8. The MULTIPLE phrase in the FROM, TO, or USING clause indicates that you want the control's value to be mapped to the corresponding data item on a line-by-line basis. Each line of data in the control corresponds to one element in the data table. This should be used only with controls that have the concept of multiple lines of data (e.g., an ENTRY-FIELD that contains multiple lines of text). For example, the following Working-Storage and Screen Section definitions would construct a five-line entry field on the screen, and place each line of input into a separate data item in the Working-Storage table:
    WORKING-STORAGE SECTION.
01  ENTRY-LINES OCCURS 5 TIMES  PIC X(30).

SCREEN SECTION.
01  ENTRY-FIELD, USING MULTIPLE ENTRY-LINES,
          LINES 5, SIZE 30.
  9. If you specify a FROM or USING item, and you do not specify a title, the runtime will substitute the from-item or using-item for the title if the corresponding control type does not take a value (i.e., is a LABEL, PUSH-BUTTON, or FRAME). This allows you to associate a PICTURE with a LABEL control. Because the picture formats the value of the control, and because a LABEL does not take a value, this rule allows the picture-string to set the value of the label's title.
  10. The REQUIRED phrase is meaningful only for controls that take alphanumeric input (e.g., entry fields). When specified, it forces the user to enter non-space data into the control before the ACCEPT will terminate. The user can also terminate the ACCEPT by generating an exception. See Common Screen Options for more information about the REQUIRED phrase.
  11. The EVENT option of the PROCEDURE phrase establishes an event procedure for the control. Event procedures are different from the other Screen Section embedded procedures in that an event procedure becomes part of the control when it is created, and is executed directly by the control (the BEFORE, AFTER, and EXCEPTION procedures execute as part of the flow of control of the Screen Section). An event procedure can potentially execute any time after its owning control has been created, even when the defining Screen Section item is not being ACCEPTed. For more about event procedures, see PROCEDURE Clause.
  12. All phrases not described here or in Common Screen Options are treated in the same manner as in a Format 1 Screen Section entry.

Format 2 Screen Section example:

SCREEN SECTION.

01  SEARCH-SCREEN.
    03  LABEL "Search for", LINE 1, COL 5.
    03  ENTRY-BOX USING SEARCH-TEXT, COL + 1,
           SIZE 30.
    03  PUSH-BUTTON, TITLE "Ok", LINE 3, COL 10,
           DEFAULT-BUTTON, TERMINATION-CODE IS 13.
    03  PUSH-BUTTON, TITLE "Cancel", COL 25,
           CANCEL-BUTTON, EXCEPTION-CODE IS 27.

Format 3 (.NET ASSEMBLIES) only Rules

  1. A Format 3 Screen Section entry defines a graphical .NET assembly.
  2. Literal values for assembly parameters are located in the COPY file generated by the NETDEFGEN utility. The same COPY file must be included in the SPECIAL-NAMES paragraph of your program.
  3. Graphical assemblies show the keyword "VISUAL" in the COPY file after the CLASS keyword. If the word "VISUAL" does not appear, use the CREATE statement to instantiate the assembly. A Format 3 Screen Section is for graphical .NET assemblies only.
  4. assembly-name is the name of a .NET assembly defined in the NETDEFGEN COPY file. This must be the DLL name of a graphical control, not an executable file. Graphical controls are generated by Visual Studio when a developer selects a "Windows Control Library" project type.
  5. namespace is a NameSpace in the assembly, as it appears in the COPY file.
  6. class-name is a class in the NameSpace.
  7. handle-1 receives a handle to the assembly when it is created.
  8. version is the version number of the assembly.
  9. culture is cultural information related to the assembly.
  10. strong-name is the cryptographic key required to access the assembly, if any. If the assembly requires such a key, as all assemblies in the Global Assembly Cache (GAC) do, it is shown in the COPY file under the keyword STRONG.
  11. All classes that result in an object have a CONSTRUCTOR, which is a unique method. If you see a CONSTRUCTOR identifier in the COPY file without a parameter list, then the field may be omitted from your COBOL program. If all listed CONSTRUCTORs have parameters, then you must choose which CONSTRUCTOR and parameters to use. constructor(n) is the constructor that you want to use followed by its parameter data.
  12. module identifies a file where a combination of NameSpaces and Classes resides. It is used when the assembly is constructed of other assemblies.
  13. file-path is the path of an XML file, and that XML file contains the path where the .NET assembly is located. Use FILE-PATH when the assembly that you want to access does not reside in the GAC or in the same directory as wrun32.exe. Assemblies that reside in the GAC will have the STRONG keyword in the NETDEFGEN COPY file.
  14. LINES and SIZE default to the design control height and width.

Format 3 Screen Section example:

SCREEN SECTION.
01  screen-1.
    03  SOME-NETCONTROL, "@My.Assembly",
        LINE 1, COL 2,
NAMESPACE IS "My.Test.Namespace",
CLASS-NAME IS "UserControl1",
      CONSTRUCTOR IS CONSTRUCTOR2(PARM1, PARM2, PARM3,
      PARM4, PARM5, PARM6, PARM7),
EVENT PROCEDURE IS USERCONTROL-EVENTS.
  • PICTURE FROM TO and USING Clauses
  • VALUE Clause
  • OCCURS Clause
  • LINE Clause
  • COLUMN Clause
  • PROCEDURE Clause
Parent topic: Data Division


PICTURE FROM TO and USING Clauses

These Screen Section clauses describe the format, storage, and action of a screen data field.

General Format

[ {PICTURE} IS picture-string  ]
  {PIC    }

[ [ FROM out-item ] [ TO in-item ]  ]
[       USING update-item           ]

Syntax Rules

  1. See IS EXTERNAL-FORM Clause for rules for the Screen Section PICTURE clause.
  2. If the PICTURE clause is specified, then a VALUE clause may not be specified.
  3. out-item is a literal or an identifier referencing a data item in the File, Working-Storage, or Linkage sections. out-item may be subscripted and reference modified.
  4. in-item and update-item are identifiers referencing data items in the File, Working-Storage, or Linkage sections. These items may be subscripted and reference modified.
  5. in-item, out-item and update-item must be such that a MOVE specified between them and the screen entry is legal according to the rules of the MOVE statement.

General Rules

  1. Because of the difficulty in viewing the internal storage of certain classes of numeric items, you should avoid using the picture symbol V in a screen entry. If you use the picture symbol S, you should also specify the SIGN SEPARATE clause. Alternately, you can use a numeric edited screen entry to display these types of data items in a sensible format.
  2. A screen entry specifying the FROM phrase is an output field. A screen entry specifying the TO phrase is an input field. A screen entry specifying both the FROM and TO phrases is an update field.
  3. A screen entry with the USING phrase is equivalent to a screen entry specifying both the FROM and TO phrases referencing the same data item.
  4. When a DISPLAY verb executes, each output and update field referenced is sent to the screen. When this occurs, each out-item and update-item is first moved to the corresponding screen entry using the standard rules of the MOVE statement. These fields are then displayed on the user's screen.
  5. Input fields are initialized when a DISPLAY verb executes. Numeric and numeric-edited fields have ZERO moved to them, all other fields have SPACES moved to them. These moves occur using the standard rules of the MOVE statement. The appearance of input fields on the screen when a DISPLAY verb executes is configurable by various runtime options. Note that the screen entry is initialized; the corresponding in-item or update-item is not.
  6. When an ACCEPT verb executes, each input and update field referenced is input by the user. After the user is done, each screen entry is moved to the corresponding in-item or update-item using the standard rules of the MOVE statement.
  7. If the PICTURE phrase is omitted, then the screen entry derives its PICTURE from the in-item, out-item, or update-item specified. The derived PICTURE is identical to the PICTURE for the specified item. If both in-item and out-item are specified, then the PICTURE is derived from out-item. Note that only the PICTURE is derived; other clauses such as the SIGN clause are not inherited.
Parent topic: Screen Description Entry


VALUE Clause

The Screen Section VALUE clause specifies a literal screen item.

General Format

VALUE IS value-lit

Syntax Rules

  1. value-lit is any alphanumeric literal or figurative constant.
  2. If a VALUE clause is specified, a PICTURE clause may not be specified.

General Rules

  1. A VALUE clause specifies a literal display field.
  2. When a DISPLAY verb executes that references a screen entry with a VALUE clause, value-lit is sent to the user's screen.
  3. If value-lit is a figurative constant, one occurrence of that constant is sent.
Parent topic: Screen Description Entry


OCCURS Clause

The Screen Section OCCURS clause simplifies the handling of repeated data items.

General Format

OCCURS table-size TIMES

Syntax Rules

  1. table-size is an integer that specifies the number of occurrences of the screen entry.
  2. An OCCURS clause may not be specified for a screen entry that has a level-number of 01.
  3. An OCCURS clause may be subordinate to a group item with an OCCURS clause to create a two-dimensional table. An OCCURS clause may not be nested more than two deep (three dimensional or greater tables are not allowed).
  4. If an OCCURS clause applies to a screen output or update field, then one OCCURS clause specifying the same number of occurrences, or no OCCURS clause at all, must apply to the source item. This OCCURS clause must not include the DEPENDING phrase.
  5. If an OCCURS clause applies to a screen input or update field, then one OCCURS clause specifying the same number of occurrences must apply to the receiving item. This OCCURS clause must not include the DEPENDING phrase.
  6. If a COLOR clause is specified for a screen description entry that contains or is subordinate to an OCCURS clause, that COLOR clause may reference a table of numeric data items. The number of occurrences in the color table must match the number of occurrences in the screen entry.

General Rules

  1. The general rules that apply to an OCCURS clause specified for a data item in the File, Working-Storage, or Linkage sections also apply to an OCCURS Clause.
  2. Each screen entry affected by an OCCURS clause is repeated table-size times.
  3. If line or column numbers are given to screen items in a table, at least one of these numbers should specify relative positioning. If absolute positioning is used, then every occurrence of the screen item will appear in the same place.
  4. If the screen item is an output or an update field, and no OCCURS clauses apply to the sending item, then a DISPLAY verb causes the sending item to be moved to every occurrence of the screen item.
  5. If the screen item is an output or an update field with an OCCURS clause applying to the sending item, then a DISPLAY verb causes each occurrence of the sending item to be moved to the corresponding occurrence of the screen item.
  6. If the screen item is an input or an update field, then an ACCEPT verb causes each occurrence of the screen item to be moved to the corresponding occurrence of the receiving item.
  7. If a COLOR clause that references a table is specified, each occurrence of the table specifies the color for the corresponding occurrence of the screen item. For example:
    DATA DIVISION.
WORKING-STORAGE SECTION.

01  DATA-TABLE.
    03  DATA-ELEMENT OCCURS 5 TIMES PIC X(5).

01  COLOR-TABLE.
    03  COLOR-ELEMENT OCCURS 5 TIMES PIC 9(5).

SCREEN SECTION.

01  SCREEN-1.
    03  OCCURS 5 TIMES, USING DATA-ELEMENT
        COLOR COLOR-ELEMENT.

Examples

Example: Table on One Line

This program accepts a simple table on one line:

IDENTIFICATION DIVISION.
PROGRAM-ID. OCCURS-SAMPLE-1.
DATA DIVISION.
WORKING-STORAGE SECTION.

01  TABLE-1.
    03  TABLE-ITEM OCCURS 5 TIMES     PIC X(5).

SCREEN SECTION.

01  SCREEN-1.
    03  "TABLE ITEMS:".
    03  OCCURS 5 TIMES USING TABLE-ITEM, COLUMN + 2.

PROCEDURE DIVISION.

MAIN-LOGIC.

   DISPLAY WINDOW ERASE.
   DISPLAY SCREEN-1.
   ACCEPT SCREEN-1.
   STOP RUN.

Example: Two-element Table

This program accepts a two-element table, each pair on its own line:

IDENTIFICATION DIVISION.
PROGRAM-ID. OCCURS-SAMPLE-2.

DATA DIVISION.
WORKING-STORAGE SECTION.

01  TABLE-1.
    03  TABLE-GROUP OCCURS 5 TIMES.
        05  ITEM-1    PIC X(5).
        05  ITEM-2    PIC 9(5).

SCREEN SECTION.

01  SCREEN-1.
    03  "TEXT  NUMBER".
    03  OCCURS 5 TIMES.
        05  USING ITEM-1, LINE + 1.
        05  USING ITEM-2, COLUMN + 2.

PROCEDURE DIVISION.
MAIN-LOGIC.
   DISPLAY WINDOW ERASE.
   DISPLAY SCREEN-1.
   ACCEPT SCREEN-1.
   STOP RUN.

Example with Output

You don't have to use a table data-item when you're doing output:

SCREEN SECTION.
01  LINES-SCREEN.
    03  "-" OCCURS 10 TIMES.

This would cause ---------- to be displayed. This is an example of rule 4, where no OCCURS clause applies to the source item.

Parent topic: Screen Description Entry


LINE Clause

The LINE clause specifies the row on which the screen entry is to be placed.

General Format

LINE [ NUMBER IS  [PLUS] line-no ]
                  [ +  ]
                  [ -  ]

Syntax Rules

  1. line-no is a numeric literal or data item.
  2. line-no may not be subscripted or reference modified.

General Rules

  1. The LINE clause specifies the screen row on which to place the screen entry. Line number 1 is the line number specified in the AT phrase of the ACCEPT or DISPLAY statement. If the AT phrase is not specified, then line number 1 is the first line of the current screen window.
  2. The LINE clause without the PLUS option specifies an absolute line number.
  3. The LINE clause with the PLUS option specifies a line number relative to the previous screen entry in the group. If the PLUS or "+" option is used, line-no is added to the previous line number. If the "-" option is used, line-no is subtracted from the previous line number.
  4. If relative positioning is specified for a level 01 screen entry, the position is relative to LINE 1.
  5. If line-no is not specified, then LINE PLUS 1 is implied.
  6. If the LINE clause is omitted:
    • If no previous screen item has been defined, LINE 1 is assumed.
    • If a previous screen item has been defined, the line of that previous item is used.
Parent topic: Screen Description Entry


COLUMN Clause

The COLUMN clause specifies which screen column to use for a screen entry.

General Format

{COLUMN  } [ NUMBER IS  [PLUS] col-no ]
{COL     }              [ +  ]
{POSITION}              [ -  ]
{POS     }

Syntax Rules

  1. col-no is a numeric literal or data item.
  2. col-no may not be subscripted or reference modified.
  3. COLUMN, COL, POSITION, and POS are equivalent.

General Rules

  1. The COLUMN clause specifies the screen column on which to place the screen entry. Column number 1 is the column number specified in the AT phrase of the ACCEPT or DISPLAY statement. If the AT phrase is not specified, then column number 1 is the first column of the current screen window.
  2. The COLUMN clause without the PLUS option specifies an absolute column number.
  3. The COLUMN clause with the PLUS option specifies a column number relative to the end of the previous screen entry in the group. If the PLUS or "+" option is used, col-no is added to the previous column number. If the "-" option is used, col-no is subtracted from the previous column number.
  4. If relative positioning is specified for a level 01 screen entry, the position is relative to COLUMN ZERO (in other words, COLUMN PLUS 1 is the same as COLUMN 1).
  5. If col-no is not specified, then COLUMN PLUS 1 is implied.
  6. If the COLUMN clause is omitted:
    • If a LINE clause is specified, COLUMN 1 is implied.
    • If the LINE clause is omitted, COLUMN PLUS 1 is implied.
  7. In ICOBOL compatibility mode, the COLUMN phrase is interpreted slightly differently. Relative positioning is based from the character just to the right of the previous data item. This causes COLUMN PLUS 1 to place a space between the end of the last data item and the beginning of the next one. Also, if the COLUMN phrase is omitted and would normally default to COLUMN PLUS 1, then COLUMN PLUS ZERO is used instead.
Parent topic: Screen Description Entry


PROCEDURE Clause

A Screen Section entry may refer to paragraphs and sections in the Procedure Division. The reference describes a procedure that the runtime will execute when a Format 2 ACCEPT statement transfers control to or from that field. The procedure temporarily suspends the operation of the ACCEPT statement. When the procedure finishes, control returns to the ACCEPT statement.

Procedures named in the Screen Section in this way are called embedded procedures. You can use embedded procedures to perform immediate validation of user-supplied data.

Another type of procedure named in the Screen Section is an event procedure, which is tied to a screen control. When a control generates events, it executes its event procedure as one of its first operations. When the procedure terminates, the control resumes execution. You can use event procedures to detect and act on desired events. Event procedures are explained in detail in the General Rules section below. See Events for a description of the specific events that can be generated in an event-driven environment.

General Rule 1 describes when an AFTER or EXCEPTION procedure is executed.

You create embedded procedures or event procedures by using syntax in the Screen Section. On any Screen Section entry, you may use the following syntax.

General Format

{BEFORE   } PROCEDURE IS {proc-1 [{THROUGH} proc-2]}
{AFTER    }                       {THRU }
{EXCEPTION}              {NULL }
{EVENT    }

Syntax Rules

  1. proc-1 and proc-2 must be names of paragraphs or sections defined in the Procedure Division of the program.
  2. THROUGH and THRU are synonymous.
  3. You may have one event procedure or up to three embedded procedures defined for each Screen Section entry–one BEFORE, one AFTER, and one EXCEPTION. You may not have more than one of each type in any one Screen Section entry.

General Rules

Embedded Procedures

  1. An ACCEPT statement executes embedded procedures when the cursor reaches the field defined by the associated Screen Section entry. The type of an embedded procedure defines exactly when it will execute:
    • BEFORE procedures execute when control is transferred to the associated field, before the user can enter any data.
    • AFTER procedures execute when the user attempts to leave the field normally. This can be due to typing a termination key, filling an auto-terminate field, or typing a field-movement key such as the Tab key. Keys that serve as both movement and exception keys, such as the default definition of the Up arrow key, always cause the AFTER procedure to execute.

      As pertains to this rule, the movement actions are defined as:

      Default-Next, Down, Erase-All, Erase-Next, First, Last, Left, Next, Next-Line, Numeric-Next, Previous, Previous-Line, Right, and Up.

      In the default keyboard configuration, this affects the handling of the Up and Down arrows in the first and last fields of a Screen Section item.

      To avoid having keys that are both movement keys and exception keys, you can make the affected keys movement and termination keys. In the default keyboard configuration, you would change the Up and Down arrows to be:

           KEYBOARD   Edit=Up    Terminate=52  ku
     KEYBOARD   Edit=Down  Terminate=53  kd
    • EXCEPTION procedures execute when the user types an exception key (assuming that exception keys are allowed) or when some other exception condition exists.
  2. The word NULL in the PROCEDURE phrase indicates that no procedure exists. It has the same effect as omitting the PROCEDURE phrase and is essentially commentary.
  3. When the ACCEPT statement executes an embedded procedure, it treats proc-1 and proc-2 in the same manner that a PERFORM statement does. That is, it begins execution at proc-1 and continues to the end of proc-2 (or proc-1 if you omit proc-2). When the embedded procedure completes, control returns to the ACCEPT statement.
  4. An embedded procedure may contain other ACCEPT statements, which, in turn, can contain embedded procedures. This is handled in the same fashion as nested PERFORMS. Embedded procedures may CALL subprograms. An embedded procedure remains active until one of the following occurs:
    • The embedded procedure finishes and returns control to its ACCEPT statement.
    • The program containing the embedded procedure does an implicit or explicit EXIT PROGRAM.
    • The run-unit containing the embedded procedure does an implicit or explicit STOP RUN.
  5. Prior to executing an embedded procedure, the ACCEPT statement moves the contents of each input and update field to its corresponding data item. In addition, each control is INQUIREd for its current VALUE (unless the TC_CONTROL_SYNC_LEVEL configuration variable is set to a value that contradicts this behavior). This allows you to examine the current Screen Section data from inside an embedded procedure.
  6. The ACCEPT statement updates any CURSOR variable that you have declared in Special-Names. It does this prior to executing any AFTER or EXCEPTION procedure. Note that BEFORE procedures do not update the variable. This is due to the fact that the cursor does not actually move to the field being entered until the BEFORE procedure returns control to the ACCEPT statement.
  7. The ACCEPT statement updates any CRT STATUS variable that you have declared prior to executing an AFTER or EXCEPTION procedure. This allows you to determine what key the user typed to leave the field. You may also use the ACCEPT FROM ESCAPE KEY verb inside an embedded procedure for this purpose.
    • If the user leaves the field due to the action of an editing key (such as an arrow key or a "next field" key), the CRT STATUS will be set to zero (for a numeric CRT STATUS) or to 0", "0", x"00" (for a group item CRT STATUS). See Special-Names Paragraph for the format of a group item CRT STATUS.
    • Note that some keys are both editing keys and termination keys. For example, by default, the Tab key is set up to be a "next field" key until the last field of the Screen Section, when it becomes a termination key. These keys are treated as editing keys until their termination condition applies. Therefore, their CRT STATUS value will change depending on whether the key is being treated as an editing key or a termination key.
  8. After completing an embedded procedure, the ACCEPT statement re-computes all variable information contained in the Screen Section entry being accepted. This allows you to change colors and other aspects of the Screen Section entry dynamically.
    • Note, however, that data is not automatically moved to update (USING) fields from their corresponding data items. If you want to change the contents of an update field from inside an embedded procedure (to provide a new default, for example), you must DISPLAY the changed field. The DISPLAY verb moves data to the Screen Section and shows it on the screen.
    • In an embedded procedure, you may "protect" screen fields by changing their COLOR value. As a result, the ACCEPT statement may terminate when the embedded procedure returns control because there are no remaining fields to enter. If this occurs, the CRT STATUS is left unchanged from the value it had when the embedded procedure returned.
  9. An embedded procedure can alter the behavior of its controlling ACCEPT statement. See Special-Names Paragraph for details on the SCREEN CONTROL data item.
  10. You may specify an embedded procedure for a group item in the Screen Section. The effect is to apply that procedure to each elementary item contained in the group. Subsidiary items may specify their own embedded procedures, which take precedence over the group's embedded procedures. See Using Screen Section Embedded Procedures for more information.

Event Procedures

  1. The EVENT option of the PROCEDURE phrase establishes an event procedure for a control. Event procedures are different from Screen Section embedded procedures in that an event procedure becomes part of the control when it is created, while embedded procedures do not. An event procedure is executed directly by the control. Embedded procedures execute as part of the flow of control of the Screen Section. An event procedure can potentially execute any time after its owning control is created, even when the defining Screen Section item is not being ACCEPTed.
  2. By default, a control does not have an event procedure, which is like specifying an event procedure of NULL.
  3. When a control invokes an event procedure, the EVENT-STATUS data item reflects the invoking event. When the procedure terminates, the previous contents of the EVENT-STATUS item are restored (this is important when nested events exist). If the program does not contain an EVENT-STATUS data item, then the event is processed normally. See Special-Names Paragraph for more information about the EVENT-STATUS data item.
  4. Event procedures are similar to embedded procedures (for example, the AFTER procedure). However, you should note the following differences:
    • Unlike embedded procedures, the values of data elements corresponding to a control's values are not updated when an event procedure is entered. You must use the INQUIRE verb to examine the current value of a control inside an event procedure.
    • Unlike embedded procedures, the event procedure executes while processing the control, instead of after the control terminates. Every event that occurs in the control is passed to the event procedure. When the event procedure terminates, the event is processed by the control and the control continues normal processing as dictated by the value of the EVENT-ACTION element of EVENT-STATUS. An advantage of event procedures is that they receive all events. You do not need to remember if the event should be processed in the AFTER or EXCEPTION procedure.
    • Event procedures can be executed any time the control receives events. The Screen Section embedded procedures receive control only during an ACCEPT of the corresponding Screen Section. This behavior can be important with tool bar controls, which normally are not ACCEPTed.
    • Events classified as messages (whose symbolic names start with MSG-) are sent only to event procedures. They cannot be detected by the Screen Section embedded procedures. See Events Reference in User Interface Programming for detailed information about messages.
    • You can change a control's event procedure via the MODIFY verb. The Screen Section's embedded procedures are fixed.
  5. Event procedures are unique in that they can receive control when the owning COBOL program is otherwise inactive. The following rules cover the activation of an event procedure:
    1. If the current program contains the event procedure, then it is executed as if it were the subject of the PERFORM statement.
    2. If the program containing the event procedure is active, but is not the current program, control flows to the containing program at the point of the event procedure. This situation is not considered a recursive call, because the transfer of control is not via CALL. When the event procedure terminates, control returns to the original program.
    3. If the program containing the event procedure is not active, but is resident in memory, it is made active with the following conditions:
      • It has no USING items passed to it, so program parameters are not defined and should not be used.
      • While active, the program is not affected by CANCEL (just like all active programs).
      • When the event procedure terminates, the program is made inactive again.
      • On entry to the event procedure, all other states of the program (e.g., the values of variables) are unchanged from the time when the program was last active.
      • The program retains any changes made to its state (variables and file state) when the procedure exits.
    4. If the program containing the event procedure is not memory resident, then the event procedure is removed from the control.
    5. For recursive programs, the copy of the program at the depth that registered the procedure is the one that counts for determining which program contains the event procedure.
    6. While an event procedure is active (due to an event), an EXIT PROGRAM statement is ignored in the event procedure's controlling program.
  6. When programming an event procedure, you should avoid using the ACCEPT statement to allow input from controls. Most graphical host systems are not designed to expect input events while in the process of handling another input event. This situation stresses the host system and can lead to situations where the results are unpredictable.

    If you want to place an ACCEPT statement inside an event procedure, one way to avoid this situation is to turn the event to a terminating event and then perform the ACCEPT in the corresponding exception procedure. Exceptions occur after event handling is complete, so this avoids the nested input events syndrome. To turn an event into a terminating event, see the description of EVENT-STATUS in Special-Names Paragraph. Another effective technique is to run the procedure that performs the ACCEPT in a separate thread. This allows the original event to complete and also avoids the situation. Typically you can do this by placing the desired event-handling code in a separate paragraph and then using PERFORM THREAD to run that paragraph from the control's event handler.

Parent topic: Screen Description Entry


Procedure Division

  • Organization
  • Arithmetic Expressions
  • Conditional Expressions
  • Common Statement Rules
  • Procedure Division Format
  • Procedure Division Statements
Parent topic: ACUCOBOL-GT Reference Manual


Organization

The Procedure Division holds the COBOL statements that the program executes. This section describes the general rules covering COBOL statements and covers each statement type in detail.

The Procedure Division is organized as a series of paragraphs made up of sentences. These sentences describe the desired behavior of the program. Paragraphs may optionally be organized into sections. Most paragraphs in the Procedure Division contain statements that are executed in the normal course of the program. Paragraphs may also be placed in Declaratives. Declarative paragraphs execute only in response to some external condition, such as failure of a file input/output statement.

  • Statements and Sentences
  • Flow of Control
Parent topic: Procedure Division


Statements and Sentences

A COBOL statement is always introduced by a reserved word called a verb. A verb and its operands describe some action to be taken when the program runs. A sentence is one or more statements that are terminated by a period.

There are four types of statements:

  1. Compiler-directing statements specify an action to be taken by the compiler. Only the COPY, REPLACE, and USE statements fit this classification.
  2. Imperative statements specify an unconditional action to be taken by the object program. Whenever an imperative statement is allowed, it may consist of a sequence of consecutive imperative statements.
  3. Conditional statements specify an action to be taken by the object program that is dependent on the truth value of some condition.
  4. Delimited-scope statements specify their explicit scope delimiter. A delimited-scope statement contains elements of a conditional nature. Because of the scope-delimiter, however, these statements may be used anywhere an imperative statement may be.

An imperative sentence is one that contains only imperative and delimited-scope statements. A conditional sentence consists of a single conditional statement optionally preceded by a sequence of imperative statements.

Several verbs can be either imperative, conditional, or delimited-scope. For example, a simple READ statement is imperative. If the AT END clause is included, it becomes conditional. On the other hand, if the END-READ phrase is also included, then it is a delimited-scope statement.

  • Scope of Statements
Parent topic: Organization


Scope of Statements

The scope of a statement designates when a statement ends. A period terminates all currently active statements. In a delimited-scope statement, the scope delimiter ends the statement. An imperative statement ends at the beginning of the next statement.

Conditional and delimited-scope statements can contain other statements. These statements can be terminated implicitly by elements of the containing statement. In the following example, the ELSE clause terminates the ADD and DISPLAY statements. The period terminates the MOVE and IF statements.

    IF VAR-1 = VAR-2
        ADD VAR-X TO VAR-Y
            ON SIZE ERROR DISPLAY "OVERFLOW"
    ELSE
        MOVE VAR-2 TO VAR-1.

Clauses or scope-delimiters that terminate a statement always terminate the statement that begins with the closest preceding unpaired verb of the appropriate type. In the following example, the first ELSE terminates the DISPLAY statement, the second ELSE terminates the MOVE statement and the second IF statement, and the period terminates the ADD statement and the first IF statement.

    IF VAR-1 = VAR-2
        IF VAR-3 = VAR-4
            DISPLAY "CONDITION 1"
        ELSE
            MOVE "CONDITION 2" TO VAR-5
    ELSE
        ADD 1 TO VAR-3.

A delimited-scope statement is one that contains a scope-delimiter. A scope-delimiter is always a reserved word that begins with END- and finishes with a verb name. For example, END-ADD and END-START are scope delimiters for the ADD and START statements. The presence of a scope-delimiter converts a conditional statement into a delimited-scope statement. A delimited-scope statement may be used anywhere an imperative statement can appear.

Note: Only imperative statements may be nested within another statement, unless the other statement is an IF statement.

The following is illegal:

ADD VAR-1 TO VAR-2 ON SIZE ERROR
       IF VAR-1 < ZERO
          DISPLAY "VAR-1 IS NEGATIVE"
       ELSE
          DISPLAY "VAR-1 TOO LARGE".

Since the IF statement is conditional, it may not be nested within the ADD statement. The correct version of this construct is:

    ADD VAR-1 TO VAR-2 ON SIZE ERROR
       IF VAR-1 < ZERO
          DISPLAY "VAR-1 IS NEGATIVE"
       ELSE
          DISPLAY "VAR-1 TOO LARGE"
       END-IF.

The presence of the END-IF converts the conditional IF statement into a delimited-scope statement which may be used in place of an imperative statement. Thus it may appear nested within the ADD statement.

Parent topic: Statements and Sentences


Flow of Control

Execution of a program begins at the first paragraph encountered outside of Declaratives. Statements are executed in order except when an explicit or implicit transfer of control occurs. The program halts when there is no next statement available to execute.

The following methods of implicit control are used by COBOL.

  1. If a paragraph is being executed under control of another COBOL statement (such as a PERFORM) and the paragraph is the last in the range of the controlling statement, then an implied transfer of control occurs from the last statement in the paragraph to the control mechanism of the controlling statement.
  2. When any COBOL statement is executed which results in the execution of a Declarative section, an implicit transfer of control to that Declarative section occurs. After the section completes, another implicit transfer of control occurs to the statement immediately after the statement that caused the Declarative to execute.

An explicit transfer of control occurs in response to certain COBOL statements such as GO TO and PERFORM. The rules for transfer are described under the appropriate verbs. All conditional and delimited-scope statements also perform explicit transfer of control based on some condition.

Parent topic: Organization


Arithmetic Expressions

Arithmetic expressions are used in COBOL to represent a fixed or computed numeric value. An arithmetic expression can be one of the following:

  1. a numeric elementary data item
  2. a numeric literal
  3. the address of a data item (ADDRESS OF phrase)
  4. two or more of the above, separated by arithmetic operators
  5. two or more arithmetic expressions, separated by arithmetic operators
  6. an arithmetic expression enclosed in parentheses
  7. an arithmetic expression preceded by a unary operator (a sign)

Arithmetic expressions can use five binary and two unary arithmetic operators. A space must precede and follow each operator. The operators are:

Binary Operator | Meaning
+ | Addition
- | Subtraction
* | Multiplication
/ | Division
** | Exponentiation
Unary Operator | Meaning
+ | Multiplication by +1
- | Multiplication by -1
Note: Spaces are often required before and after minus signs to prevent ambiguity.
  • Evaluation of Arithmetic Expressions
  • ADDRESS OF Phrase in Expressions
Parent topic: Procedure Division


Evaluation of Arithmetic Expressions

Parentheses may be used in expressions to specify the order of evaluation. Expressions within parentheses are evaluated first. When parentheses are nested, the innermost set of parentheses is evaluated first, and then successively more inclusive parentheses are evaluated.

When an expression contains no parentheses, the expression evaluates the arithmetic operators in the following hierarchical order:

  1. unary plus and minus
  2. exponentiation
  3. multiplication and division
  4. addition and subtraction

When the sequence of execution is not specified by parentheses and two or more operators exist at the same hierarchical level, the order of evaluation is from left to right.

An arithmetic expression can begin with only a left parenthesis, a plus sign, a minus sign, an identifier, or a literal. It can end only with a right parenthesis, an identifier, or a literal. Each left parenthesis in an expression must have a matching right parenthesis, and each right parenthesis must have a matching left parenthesis. If the first operator is unary, it must be preceded by a left parenthesis if the expression immediately follows an identifier or another arithmetic expression.

Operands in an arithmetic expression may be any format or USAGE.

Parent topic: Arithmetic Expressions


ADDRESS OF Phrase in Expressions

In an arithmetic expression, you may use the address of a data item anywhere you can normally place a numeric data item. The address is treated as an unsigned integer with sufficient range to express any address in the host machine's address space.

To create an address, you use the following syntax:

ADDRESS OF data-item-1

where data-item-1 is a data item.

For example, the following statement produces a pointer that points one character position past the beginning of ITEM-1:

COMPUTE PTR-1 = ADDRESS OF ITEM-1 + 1

If a data item has not been given an address by the program, then the data item's address acts as if its uppermost parent item (or itself if it has no parent) has an address of zero. This makes it possible to test for a NULL address without generating a runtime exception. For example:

SET POINTER-1 TO ADDRESS OF LINK-ITEM-1
IF POINTER-1 = NULL
   SET ADDRESS OF LINK-ITEM-1 TO WS-ITEM-1

This rule only applies to ADDRESS OF calculations.

Parent topic: Arithmetic Expressions


Conditional Expressions

Conditional expressions specify a condition the program must evaluate to determine the program's behavior. Conditional expressions have a value of true or false. Conditional expressions can either be simple or complex. The simple conditional expressions are the relation, class, sign, and condition-name conditions. The complex conditions are formed with the logical operators AND, OR, and NOT.

  • Relation Conditions
  • Class Condition
  • Sign Condition
  • Condition-Name Condition
  • Switch-Status Condition
  • Complex Conditions
  • Order of Evaluation
  • Abbreviated Combined Relation Conditions
Parent topic: Procedure Division


Relation Conditions

A relation condition specifies a comparison of two operands, each of which may be a data item or a literal. A relation condition has the value true if the relation exists between the operands. Comparison of two numeric operands is permitted regardless of the formats specified by their respective USAGE clauses. For all other comparisons, the operands must have the same USAGE.

The format of a relation condition is:

value1 IS [NOT]  { GREATER THAN            }  value2
                 { >                       }
                 { LESS THAN               }
                 { <                       }
                 { EQUAL TO                }
                 { =                       }
                 { <>                      }
                 { GREATER THAN OR EQUAL TO}
                 { >=                      }
                 { LESS THAN OR EQUAL TO   }
                 { <=                      }

In the preceding format, value1 and value2 may be either an arithmetic expression, a data name, or a literal (including NULL or NULLS). The relational operators have the following meanings:

Meaning | Operators
Greater than | IS GREATER THAN IS > IS NOT <= IS NOT LESS THAN OR EQUAL TO
Equal to | IS EQUAL TO IS =
Less than | IS LESS THAN IS < IS NOT >= IS NOT GREATER THAN OR EQUAL TO
Greater than or equal | IS NOT LESS THAN IS NOT < IS >= IS GREATER THAN OR EQUAL TO
Not equal to | IS NOT EQUAL TO IS NOT = IS <>
Less than or equal | IS NOT GREATER THAN IS NOT > IS <= IS LESS THAN OR EQUAL TO
  • Comparison of Numeric Operands
  • Comparison of Nonnumeric Operands
Parent topic: Conditional Expressions


Comparison of Numeric Operands

For operands whose class is numeric, a comparison is made with respect to the algebraic value of the operands. The size of the operands (in terms of number of digits) is not significant. Zero is a unique value regardless of sign. Comparison is allowed regardless of the USAGE of the operands. Unsigned operands are considered positive or zero.

Index data items are compared as if they were numeric operands.

Parent topic: Relation Conditions


Comparison of Nonnumeric Operands

For nonnumeric operands, or one numeric and one nonnumeric operand, a comparison is made with respect to the program's collating sequence of characters.

If one of the operands is numeric, it must be an integer data item or an integer literal. The numeric operand is treated as though it were moved to an alphanumeric data item of the same size as the numeric data item. This alphanumeric item is then used in the comparison. A non-integer numeric operand may not be compared to a nonnumeric operand.

When the comparison is performed, the shorter operand (if any) is treated as though it were extended on the right with spaces to make the operands of equal size. Characters are then compared in corresponding positions starting from the left end and continuing until either a pair of unequal characters is encountered or the right end of the operand is reached. If all the characters are the same, then the operands are considered equal. Otherwise, the operand with the smaller character in the first unequal pair is considered less than the other operand.

Parent topic: Relation Conditions


Class Condition

The class condition tests whether or not an operand contains a particular type of data. The general format of the class condition is:

variable IS [NOT] {NUMERIC         }
                  {ALPHABETIC      }
                  {ALPHABETIC-UPPER}
                  {ALPHABETIC-LOWER}
                  {class-name      }

Variable must name a data item with USAGE DISPLAY. If class-name is used, it must be a name defined in a CLASS clause in the SPECIAL-NAMES paragraph.

The NUMERIC test cannot be used with an elementary item whose class is alphabetic or a group item composed of elementary items which contain operational signs. If the item being tested is not described as having an operational sign, the item is considered numeric only if the content consists of the digits 0 through 9. If the item is described as having an operational sign, the item is considered numeric only if the content consists of the digits 0 through 9 and a valid operational sign.

The ALPHABETIC test cannot be used with an item whose class is numeric. The test is true if the content of the data item consists entirely of the characters A through Z, a through z, and space. The ALPHABETIC-LOWER and ALPHABETIC-UPPER tests are similar to the ALPHABETIC test except that only lower-case or upper-case characters are allowed respectively.

If class-name is used, then variable may not be numeric. The test is true if variable consists solely of characters named in the CLASS clause that defined class-name. See Special-Names Paragraph for a description of the CLASS clause.

If the NOT option is specified, then the test is true if and only if the same condition without the NOT option is false.

Parent topic: Conditional Expressions


Sign Condition

The sign condition tests whether an arithmetic expression is positive, negative, or zero. The format of a sign condition is:

arithmetic-expression IS [NOT] {POSITIVE}
                               {NEGATIVE}
                               {ZERO    }

An arithmetic expression is POSITIVE if it is greater than zero, NEGATIVE if it is less than zero. If the NOT option is specified, the truth value of the test is reversed.

Parent topic: Conditional Expressions


Condition-Name Condition

A condition-name condition tests whether a condition-variable has one of the values associated with the condition-name. The format of the condition-name condition is simply the condition-name.

If the condition-name is associated with a range or ranges of values, then the condition-variable is tested to determine whether or not its value falls in this range, including the end values. The rules of comparison are the same as those for a relation condition.

Parent topic: Conditional Expressions


Switch-Status Condition

A switch-status condition tests the value of one of the external program switches. Program switches can be set at the command line when the program is run, or may be set with the SET verb. By default, each switch is initially set to "off".

The STATUS clause of the SPECIAL-NAMES paragraph associates a switch-status name with either the on or off setting of a particular switch. When a switch is set, the corresponding ON STATUS name is true and the OFF STATUS name is false. When the switch is reset, the reverse is true. In a conditional expression, you can test a switch's on/off status by simply specifying the desired switch-status name.

An example of code involving switches follows:

identification division.
program-id. testit.
environment division.
special-names.
    switch 1 is switch-1 on status is first-on off status is first-off
    switch 2 is switch-2 on status is second-on off status is second-off
    switch 3 is switch-3 on status is third-on off status is third-off
data division.
procedure division.
main.
    display window erase.
    set switch 3 to off.

    if first-on
        display "First Switch On. . ." line 5 col 4
    else
        display "First Switch Off. . ." line 5 col 4.

    if second-on
        display "Second Switch On. . ." line 7 col 4
    else
        display "Second Switch Off. . ." line 7 col 4.

    if third-on
        display "Third Switch On. . ." line 9 col 4
    else
        display "Third Switch Off. . ." line 9 col 4.

    accept omitted.
    stop run.
Parent topic: Conditional Expressions


Complex Conditions

A complex condition is formed by combining conditions (either simple or complex) with logical connectors (AND and OR) or by negating these conditions with logical negation (NOT). The truth value of a complex condition depends on the interaction of the logical operators and their component conditions.

The logical operators and their meanings are:

Operator | Meaning
AND | true when both components true
OR | true when either component true
NOT | true when condition false

A condition is negated by the logical operator NOT, which reverses the truth value of the condition to which it is applied. In other words, a negated condition is true when its component condition is false, and is false when its component condition is true. The format of a negated condition is:

NOT condition
  • Combined Conditions
Parent topic: Conditional Expressions


Combined Conditions

A combined condition results from connecting conditions with one of the logical operators AND or OR. The general format is:

condition { {AND} condition } ...
            {OR }

In the general format, condition may be any of the following:

  1. a simple condition
  2. a negated simple condition
  3. a combined condition
  4. a negated combined condition; that is, a "NOT" followed by a combined condition enclosed in parentheses

Parentheses may be used in a complex condition to alter the rules of evaluation. Parentheses must be made in matched pairs and must be placed in such a way so that the enclosed symbols constitute a well-defined condition.

The truth value of a combined condition using AND is true only when both component conditions are true. The truth value of a combined condition using OR is true when either or both of the component conditions are true.

Parent topic: Complex Conditions


Order of Evaluation

A condition is evaluated according to the following hierarchy:

  1. Components contained in parentheses are evaluated first. For those components in parentheses, the most deeply nested are evaluated first, followed by those that are less deeply nested. Evaluation always progresses from the most to the least deeply nested components.
  2. NOT conditions are evaluated next. Thus NOT A OR B is equivalent to (NOT A) OR B.
  3. AND conditions are evaluated next.
  4. OR conditions are evaluated next.
  5. Conditions are evaluated from left to right.

Here are some examples of equivalent conditions:

NOT A AND B OR C AND D     ((NOT A) AND B) OR (C AND D)
NOT A AND B AND C          ((NOT A) AND B) AND C
A AND B OR NOT (C OR D)    (A AND B) OR (NOT (C OR D))
NOT ( NOT A OR B OR C )    NOT ( ((NOT A) OR B) OR C )

Evaluation of a condition halts as soon as its truth value is determined. For example, in the condition A AND B, the condition B would not be evaluated if 'A' were false.

Parent topic: Conditional Expressions


Abbreviated Combined Relation Conditions

When simple or negated simple conditions are combined in a consecutive sequence, the relation conditions may be abbreviated. You can do this by either:

  1. omitting the subject of the relation condition (the left-hand component condition).
  2. omitting both the subject and the relational operator.

The format for an abbreviated combined relation condition is:

condition { {AND} [NOT] [relation] object } ...
            {OR }

Within a sequence of relation conditions, both of the above forms of abbreviation may be used. When you use such abbreviations, it is as if the last preceding stated subject were inserted in place of the omitted subject, and the last stated relational operator were inserted in place of the omitted relational operator. The insertion of an omitted subject or relational operator terminates once a complete simple condition is encountered within a complex condition. Except for the source of the initial relation condition, no parentheses may appear in the sequence of abbreviated conditions.

If the word NOT is used in an abbreviated combined relation condition, it has the following meaning:

  1. If the word immediately following NOT is GREATER, ">", LESS, "<", EQUAL, "<=", ">=", or "=", then the NOT participates as part of the relational operator.
  2. Otherwise, the NOT is interpreted as a logical operator and the implied insertion of the subject or relational operator results in a negated relation condition.

The following are examples of abbreviated combined relation conditions and their expanded equivalents:

A > B AND NOT < C      (A > B) AND (A NOT < C)
(A > B AND NOT < C)    (A > B) AND (A NOT < C)
A NOT = B OR C         (A NOT = B) OR (A NOT = C)
NOT A = B OR C         (NOT (A = B)) OR (A = C)
NOT (A > B OR < C)      NOT ((A > B) OR (A < C))

--newARC compiler option

With --newARC compiler option,the syntax rules for Abbreviated Combined Relation conditions become relaxed to allow for parenthesis to appear immediately after the relation.

For example:

IF A = (B OR C OR D)

would now be accepted by the compiler.

Parent topic: Conditional Expressions


Common Statement Rules

The following sections cover rules that apply to several verb types.

  • Arithmetic Operations
  • Multiple Receiving Fields
  • ROUNDED Option
  • SIZE ERROR Option
  • CORRESPONDING Option
  • Unpredictable Results
  • I/O Status
  • AT END and INVALID KEY Phrases
  • Common Screen Options
Parent topic: Procedure Division


Arithmetic Operations

The arithmetic statements are ADD, COMPUTE, DIVIDE, MULTIPLY, and SUBTRACT. They have several common features.

  1. The data descriptions of the operands need not be the same. Any necessary conversion and decimal point alignment is supplied throughout the calculation.
  2. The maximum size of each operand is 18 digits. This increases to 31 if 31-digit support (-Dd31) is in effect. If the composite of operands contains more than 18 digits, the results will be undefined. The composite of operands is a hypothetical data item resulting from the superposition of the operands aligned on their decimal point.
  3. A calculation may result in the compiler's constructing a temporary data item to hold an intermediate result. The temporary item holds the 20 most significant digits of the intermediate result. (If 31-digit support (-Dd31) is in effect, the temporary data item holds 33 digits.) The truncated low-order digits (if any) are treated as zeros.
  4. When the final value of the operation is stored in the receiving field(s), it is transferred to maintain its arithmetic value. If the receiving field is too small to hold the result, leading digits before the decimal point and trailing digits after the decimal point are removed as needed (but see the ON SIZE ERROR phrase for an exception). If the receiving field is unsigned and the value is negative, the results are undefined.
  5. An attempt to use non-numeric data in a field defined as numeric results in an intermediate runtime error. Intermediate errors call installed error procedures. See Appendix I. Library Routines for detailed discussion of the runtime Error and Exit Procedures.
    Note: In division operations, the remainder is calculated before the quotient is moved to the destination item(s). The remainder will almost always be 0 if the dividend or divisor is floating-point. This is because all of the arithmetic is performed using floating-point variables. The remainder will be non-zero only if precision is lost during the calculation.
Parent topic: Common Statement Rules


Multiple Receiving Fields

The arithmetic statements may have multiple resultant fields specified for them. These statements are evaluated as if they were written as a series of statements involving a temporary data item.

The following example illustrates the process.

The statement

ADD A, B, C TO C, D(C), E

is equivalent to

ADD A, B, C GIVING TEMP
ADD TEMP TO C
ADD TEMP TO D(C)
ADD TEMP TO E
Parent topic: Common Statement Rules


ROUNDED Option

The arithmetic statements allow for the ROUNDED phrase to be optionally specified. The results of an arithmetic statement depend on whether this phrase is present or not. When this phrase is specified, the operation adds 1 to the absolute value of the low-order digit of the resultant data item, if the absolute value of the next least significant digit of the intermediate result is greater than or equal to 5. If the ROUNDED phrase is not specified, all excess digits in the intermediate result are truncated when it is moved to the resultant data item. See Arithmetic Operations and see the DIVIDE Statement in Procedure Division Statements for more information.

Parent topic: Common Statement Rules


SIZE ERROR Option

The SIZE ERROR clause allows the programmer to specify actions to be taken when a size error occurs in an arithmetic statement. A size error condition exists under the following circumstances:

  1. The absolute value of an operation's result exceeds the largest value the resultant data item can contain.
  2. A division by zero is performed.
  3. The value zero is raised to a power of zero.
  4. A negative number is raised to a non-integer power.

The size error condition exists only for those resultant data items to which it applies. If the ROUNDED phrase is specified, it is applied before the size error condition is checked.

If a size error occurs, the results depend on whether or not the SIZE ERROR (or NOT SIZE ERROR) clause is specified. If the SIZE ERROR clause is present, the values of the data items on which a size error occurs remain unchanged. If there are multiple resultant data items in the statement, the ones on which size errors occur will be unchanged while the ones in which no size error occurs will be updated to the computed values. If a size error occurs and no SIZE ERROR clause is specified, the results are undefined. In cases where the size error is a divide by zero condition, by default the results are still undefined, however, the A_CECKDIV configuration variable can be used to specify either of two alternate runtime behaviors. For more information, see A_CHECKDIV.

If the SIZE ERROR clause is present and a size error occurs, the corresponding statement is executed. If the NOT SIZE ERROR clause is present, its statement is executed if no size errors occur during the computation.

If the CORRESPONDING option is used in an ADD or SUBTRACT statement, any individual operation can cause a size error to occur. The SIZE ERROR clause is not executed, however, until all individual operations are completed.

Parent topic: Common Statement Rules


CORRESPONDING Option

The CORRESPONDING option of the MOVE, ADD, and SUBTRACT verbs allows the programmer to specify group items as operands in order to use their corresponding subordinate data items. All identifiers in a CORRESPONDING phrase must refer to group items.

The operation specified by the statement acts on each pair of corresponding items in the specified group items. If two or more source data items have the same name, or two or more destination items have the same name, the operation may be performed more than once on some items.

Data items are considered to correspond if they match the following rules. In these rules, ident-1 and ident-2 refer to the two group items specified in the CORRESPONDING phrase.

  1. The data items in ident-1 and ident-2 must have the same data-name (which may not be FILLER).
  2. They must have the same qualifiers up to but not including ident-1 and ident-2.
  3. At least one of the data items must be elementary, and the resulting operation must be legal under the rules of the statement being executed. A violation to this rule causes a compile-time error; it does not exclude the item from the operation.
  4. In ADD or SUBTRACT statements, both of the data items must refer to an elementary numeric data item.
  5. Data items subordinate to a REDEFINES, RENAMES, OCCURS, or USAGE IS INDEX clause are ignored.
Parent topic: Common Statement Rules


Unpredictable Results

When a sending and a receiving item in any statement share a part or all of their storage areas, the result of the statement is undefined.

Parent topic: Common Statement Rules


I/O Status

After the execution of any file I/O verb (CLOSE, DELETE, OPEN, READ, REWRITE, START, UNLOCK, or WRITE), information about the I/O is available in the form of a status number. This number is placed in the FILE STATUS variable for the appropriate file if one has been declared.

status-variable must be the name of an alphanumeric (or USAGE DISPLAY numeric) Working-Storage or Linkage data item with a size of 2 characters. (The compiler also allows status-variable to be a numeric item; however, in this case it emits a Warning.) The first digit indicates a general classification of the status, while the second digit provides detail information. Any file status whose first digit is 0 is considered a successful I/O. Any non-zero initial digit indicates failure.

Parent topic: Common Statement Rules


AT END and INVALID KEY Phrases

Several of the I/O statements can take an optional AT END phrase and NOT AT END phrase. Both of these phrases are followed by a statement that is conditionally executed, depending on the result of the I/O statement. The discussion of each I/O statement that can take the AT END phrase specifies the conditions that cause the at-end condition to be in effect. If the at-end condition is in effect, one of the following happens:

  1. If the AT END phrase is present, the statement it contains is executed; otherwise
  2. If an appropriate Declarative section exists, it is executed; otherwise
  3. The program prints a message and halts. Note, however, that the runtime can be configured to ignore the error and keep running. See the configuration variables ERRORS_OK and EOF_ABORTS in Appendix H for more information. See also the additional information on ERRORS_OK in File Handling Options in the ACUCOBOL-GT User's Guide.

If the NOT AT END phrase is present, it is executed if the I/O statement is successful. Note that it is possible to execute neither the AT END nor NOT AT END phrases if an I/O error occurs that does not set the at-end condition. In this case, the AT END phrase is not executed (because the at-end condition is not in effect) and the NOT AT END phrase does not execute (because the I/O statement is not successful).

All of the preceding comments about the AT END and NOT AT END phrases also apply to the INVALID KEY and NOT INVALID KEY phrases (except that the invalid-key condition is tested instead of the at-end condition).

Parent topic: Common Statement Rules


Common Screen Options

The ACCEPT, DISPLAY, and MODIFY verbs, along with screen entries defined in the Screen Section, have several options in common. The syntax details for these options are presented in the individual sections where they are allowed. See:

  • Screen Description Entry
  • Procedure Division Statements for the ACCEPT, DISPLAY, and MODIFY statements

The following subheadings describe the effects of these options.

Note: Options that are specific to a single statement or have specialized meanings are described under those statements.
  • AUTO Phrase
  • BACKGROUND-HIGH, BACKGROUND-LOW, and BACKGROUND-STANDARD Phrases
  • BELL Phrase
  • BLINK Phrase
  • CCOL, CLINE, CLINES, and CSIZE Phrases
  • COLOR Phrase
  • COLUMN NUMBER Phrase
  • CONTROL Phrase
  • CONVERT Phrase
  • DEFAULT Phrase
  • ECHO Phrase
  • ENABLED Phrase
  • ERASE Phrase
  • EVENT-LIST, AX-EVENT-LIST, EXCLUDE-EVENT-LIST Phrases
  • FONT Phrase
  • FOREGROUND-COLOR and BACKGROUND-COLOR Phrases
  • FOREGROUND-RGB and BACKGROUND-RGB Phrases
  • FULL Phrase
  • HELP-ID Phrase
  • HIGH, LOW, and STANDARD Phrases
  • IDENTIFICATION Phrase
  • KEY Phrase
  • LAYOUT-DATA Phrase
  • LINE NUMBER Phrase
  • LINES Phrase
  • MAX-HEIGHT, MAX-WIDTH, MIN-HEIGHT, MIN-WIDTH Phrases
  • NO ADVANCING Phrase
  • NO ECHO Phrase
  • OUTPUT Phrase
  • PROMPT Phrase
  • PROPERTY and Property-Name Phrases
  • REQUIRED Phrase
  • REVERSED Phrase
  • SAME Phrase
  • SCROLL Phrase
  • SIZE Phrase (with a text entry field)
  • SIZE Phrase (with Windows and Controls)
  • STYLE Phrase and Style-Name
  • TAB Phrase
  • TITLE Phrase
  • UNDERLINED Phrase
  • UPON Phrase
  • UPPER and LOWER Phrases
  • VALUE Phrase
  • VISIBLE Phrase
  • ZERO-FILL and NUMERIC-FILL Phrases
Parent topic: Common Statement Rules


AUTO Phrase

{AUTO         }
{AUTO-SKIP    }
{AUTOTERMINATE}
  1. The AUTO phrase causes a field entry to automatically terminate as soon as the field is filled with data. If the field is the last field in a group of screen items (or the only field), then the ACCEPT statement will terminate when this occurs.
  2. If the AUTO phrase is not specified, then the field entry must be terminated by the user's typing a valid termination key (such as the enter key).
  3. When you are using RM/COBOL compatibility mode, AUTO is implied by default for any Format 1 ACCEPT statement. This may be overridden with the TAB phrase (see below).
Parent topic: Common Screen Options


BACKGROUND-HIGH, BACKGROUND-LOW, and BACKGROUND-STANDARD Phrases

{BACKGROUND-HIGH    }
{BACKGROUND-LOW     }
{BACKGROUND-STANDARD}
  1. Specifying BACKGROUND-HIGH causes the background color to be shown in high-intensity. BACKGROUND-LOW causes it to be shown in low intensity.
  2. BACKGROUND-STANDARD causes fields and controls to use the current subwindow's background intensity. When a window is created, BACKGROUND-STANDARD causes the window to use the default background intensity for the host system. See the BACKGROUND_INTENSITY runtime configuration variable in Appendix H for more details.
  3. If no background intensity is specified, the current subwindow's intensity is used.
    Note: Most character-based systems cannot control the background intensity.
Parent topic: Common Screen Options


BELL Phrase

WITH [NO] {BELL}
          {BEEP}

The BELL phrase causes the terminal's bell to ring prior to performing the I/O. The NO BELL phrase inhibits the bell from ringing. The default is NO BELL except that in RM/COBOL compatibility mode, a Format 1 ACCEPT statement defaults to BELL. See the BELL configuration variable in Appendix H for more information.

Parent topic: Common Screen Options


BLINK Phrase

WITH  {BLINKING}
      {BLINK   }

Specifying the BLINK phrase causes the field to have the "blink" video attribute set for it. If the terminal hardware does not support blinking, this phrase is ignored. Note that many implementations of ACUCOBOL-GT will set the foreground and background colors for a field with the BLINK phrase to white-on-black. Note also that BLINK cannot be combined with UNDERLINED. Microsoft Windows does not support blinking.

Parent topic: Common Screen Options


CCOL, CLINE, CLINES, and CSIZE Phrases

AT CLINE NUMBER cline-num

AT CCOL NUMBER ccol-num

CSIZE   {IS} clength  [CELL ]
        {= }          [CELLS]

CLINES  {IS} cheight  [CELL ]
        {= }          [CELLS]
  1. The CCOL, CLINE, CLINES, and CSIZE phrases provide an alternate method for specifying the placement (row and column) or size (height and width), or both, of a control for display on a non-graphical system. Together these phrases are called the character coordinate phrases. In any context where the COL, LINE, LINES, and SIZE phrases can be specified for a control, you can also specify the corresponding character coordinate phrase. These phrases make it easier to use controls on both graphical and non-graphical systems. See The Character Coordinate Phrases for more information.
  2. You specify the character coordinate phrases in exactly the same fashion as their regular counterparts (i.e., CLINE is similar to LINE, CCOL to COL, etc.). All of the syntax supported by one phrase works in the corresponding phrase. For example, a Screen Section control item that has a twin set of column offsets is:
    entry-field, col + 2, ccol + 1, ...

    When the application is run on a graphical host system, the character coordinate phrases have no effect (exception: in some contexts the values are evaluated, so any relevant table indexes should be set to legal values to prevent access violations). When the application is run on a character-based host, the character coordinate phrases substitute for their counterparts. For example, if you specify both LINE and CLINE for a control, the CLINE specification will be used as the line number on a character-based system. Omitting a character coordinate phrase causes the regular counterpart to be used instead.

  3. If you specify the CELLS option in either the SIZE or CSIZE phrase, then you must use the CELLS option in both phrases. The same rule applies to the use of the CELLS option with the LINES and CLINES phrases.
Parent topic: Common Screen Options


COLOR Phrase

{COLOR } IS color-val
{COLOUR}
  1. The COLOR phrase provides an alternate method for setting video attributes. It also allows the specification of colors for screen fields and controls.
  2. color-val can be set to different numeric values to express various combinations of colors and video attributes. You may make combinations by adding the appropriate values together. The following color values are accepted:
    Color | Foreground | Background
    Black | 1 | 32
    Blue | 2 | 64
    Green | 3 | 96
    Cyan | 4 | 128
    Red | 5 | 160
    Magenta | 6 | 192
    Brown | 7 | 224
    White | 8 | 256

    You may specify other video attributes by adding the following values:

    Reverse video | 1024
    Low intensity | 2048
    High intensity | 4096
    Underline | 8192
    Blink | 16384
    Protected | 32768
    Background low-intensity | 65536
    Background high-intensity | 131072

    You may also specify high intensity by adding "8" to the foreground color value.

  3. Only one foreground color and one background color may be specified. High intensity and low intensity may not both be specified. If neither is specified, the default intensity is used. If either the foreground or background color value is missing, then the corresponding default for the current subwindow is used. However, some control types follow different rules for selecting the default color. These rules are described in Control Types Reference.

    When a control is assigned a non-zero foreground or background color, that component will no longer revert to the default when assigned the value 0 (zero). Instead, assigning 0 simply reassigns the current color. The runtime uses this behavior to preserve one component (foreground or background) when changing the other.

  4. Other video attribute clauses (such as the REVERSED clause) may be specified along with the COLOR clause. The effects of all such clauses are used together. If any conflict exists, the COLOR clause takes precedence.
  5. Reverse video exchanges the foreground and background colors.
  6. If a terminal does not support color, then all non-black colors are mapped to white at runtime. If this results in a white-on-white combination, then the background color is set to black. However, if you explicitly specify identical foreground and background colors, then the characters will be invisible.
  7. The Protected attribute applies to only Format 1 Screen Section entries. Any input or update field that has the Protected attribute set for it is ignored during an ACCEPT statement. This enables you to selectively allow entry of certain data fields. The Protected attribute does not affect the behavior of the DISPLAY statement.
  8. The Protected attribute cannot be applied with the MODIFY statement and the COLOR phrase. For example, the following will not set the field to "Protected":
    01   my-field, ENTRY-FIELD, LINE 1, COL 1.

MODIFY my-field, COLOR=32768

    Instead, use a color variable to accomplish the effect, as in:

    01  my-color   PIC 9(5) VALUE ZERO.

01  my-field, ENTRY-FIELD, LINE 1, COL 1,
       COLOR my-color.

ADD 32768 TO my-color.
  9. When the COLOR phrase is used with controls, each control type determines the allowable set of colors. Each control class defines its own method of assigning default colors. Note that many host systems limit the ability to define a control's colors. The colors used will be as close to the requested colors as the host system allows.
Parent topic: Common Screen Options


COLUMN NUMBER Phrase

AT {COLUMN  } NUMBER col-num
   {COL     }
   {POSITION}
   {POS     }
  1. The COLUMN phrase specifies the terminal column to use. Column number one (1) indicates the leftmost column of the current subwindow. A column number of zero (0) indicates the current cursor column.
  2. When the COLUMN phrase is used with controls and floating windows, the COLUMN NUMBER refers to the left edge of the control or window. You may use CELL(S) or PIXEL(S) to specify the coordinates of controls. With cells, non-integer values are allowed, and with pixels, non-integer values are not allowed.
  3. If the COLUMN phrase is missing, the results depend on the compatibility mode being used.
    1. In VAX COBOL and ICOBOL compatibility modes, the current cursor position is used unless the LINE phrase is specified. In this case, column one is used. This rule is always applied when controls are placed, regardless of the compatibility mode being used.
    2. In RM/COBOL compatibility mode, column one is used for the first ACCEPT or DISPLAY operand. For subsequent operands, the current cursor position is used (implies COLUMN 0).
  4. If the column number specifies a column value greater than the number of columns in the current window, then one is added to the line number used, and the column number is reduced by the width of the window. This is repeated until the column number specifies a value that is contained within the window.
    Note: This rule is not used when you are placing controls on the screen. If a control is placed outside of the subwindow, the control is not created.
  5. The COLUMN NUMBER phrase used for entries in the Screen Section has a different format. See COLUMN Clause for more information.
Parent topic: Common Screen Options


CONTROL Phrase

CONTROL cntrl-string
  1. The CONTROL phrase provides the ability to modify the static attributes of the ACCEPT or DISPLAY statement at runtime. The CONTROL data item is treated as a series of comma-separated keywords that control the action of the statement. Within the CONTROL data item, spaces are ignored and lower-case letters are treated as if they were upper-case. When a CONTROL item conflicts with the statically declared attributes of the ACCEPT or DISPLAY statement, the actions specified in the CONTROL item take precedence.

    The keywords allowed in cntrl-string are listed in the following groups. If more than one keyword from within a group appears in cntrl-string, only the rightmost one in the data item is used:

    • ERASE, ERASE EOL, ERASE EOS, NO ERASE.
    • BEEP, NO BEEP
    • HIGH, LOW, STANDARD, OFF
    • BLINK, NO BLINK
    • REVERSE, NO REVERSE
    • TAB, NO TAB
    • PROMPT, NO PROMPT
    • CONVERT, NO CONVERT
    • UPDATE, NO UPDATE
    • ECHO, NO ECHO
    • UPPER, NO UPPER, LOWER, NO LOWER
    • UNDERLINED, NO UNDERLINE
    • LEFT, RIGHT, CENTERED, NO JUST
    • SAME
    • FCOLOR
    • BCOLOR
  2. Each of the keywords performs the same action as the statically declared attribute of the same name. The NO forms (NO ERASE, NO BLINK, etc.) cancel the effects of the named attribute.

    The FCOLOR and BCOLOR keywords are used to set foreground and background colors respectively. These keywords must be followed by an equals sign and the name of a color taken from the following list: BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, and WHITE. The named color becomes the default foreground or background color for the window. Note that this is different from the COLOR phrase, which sets the color only for the current ACCEPT or DISPLAY statement. The FCOLOR and BCOLOR keywords set the default colors for every subsequent ACCEPT and DISPLAY until explicitly changed.

Parent topic: Common Screen Options


CONVERT Phrase

WITH {CONVERSION}
     {CONVERT   }
  1. Specifying the CONVERT phrase allows non-USAGE DISPLAY items to be accepted or displayed. It also allows for automatic conversion of entered data into the internal format of the destination field.
  2. In a DISPLAY statement, the CONVERT phrase affects only numeric and numeric edited data items. For numeric data items, leading zeros are converted into spaces, a decimal point is inserted (if needed), and a leading minus sign is inserted (if the value is negative). The result is then left-justified if RM/COBOL compatibility mode is being used. Numeric edited items are not converted, but they are justified in the same manner as numeric items. This form of the CONVERT phrase is called output conversion.

    Floating-point data items are converted from internal format to E-notation. The format of E-notation is as follows:

    • FLOAT items have eight digits, one of which is before the decimal point.
    • DOUBLE items have 17 digits, one of which is before the decimal point.
    • A leading sign is shown for negative values, otherwise there is a leading space.
    • The exponent is shown as an "E", followed by a sign if negative, followed by one or more digits.
    • The decimal point is shown using the program's current decimal point character.
  3. In an ACCEPT statement, the action of the CONVERT phrase depends on the data type of the receiving field:
    1. A nonnumeric field receives the entered data as if it were the destination of a MOVE statement with an alphanumeric source. This causes justification and editing to have their normal effect.
    2. A numeric or numeric edited field causes the ACCEPT statement to first check the data for correctness. Legal characters for numeric items include any characters that can appear in a numeric edited data item (digits, plus and minus sign, period, comma, currency symbol, CR, DB, "/", and "*"). Characters that are legal but have no meaning in an arithmetic literal are simply ignored (space, "*", "/", currency symbol, currency comma). Any other non-space character is an error. Legal values are then assigned to the receiving field such that the algebraic value remains the same.
    3. The input format for floating-point numbers consists of the following components in the order given:
      • An optionally signed string of digits (possibly containing a decimal point)
      • An optional exponent field consisting of:
        1. "E" or "e"
        2. an optional + or -
        3. an integer

        See Numeric Literals for more information.

  4. If the CONVERT phrase is not specified, the accepted data is placed in the receiving field from left to right with no editing or justification. In RM/COBOL compatibility mode, however, a numeric receiving field causes the data to be assigned from right to left instead.
  5. For entries in the Screen Section, conversion is automatically used during input and not used during output. For this reason, Screen Section entries for non-integer numeric fields should specify a numeric edited PICTURE so that the decimal point is visible. Likewise, signed numeric fields should either specify SIGN SEPARATE or be represented by numeric edited items. Note that conversion occurs automatically for all controls that reference numeric, numeric edited, right justified, or wide character data.
  6. If a conversion error occurs, the runtime system prints an error message and forces the user to correct the field. This behavior can be modified. See The KEYBOARD Variable for more information.
  7. Several compile-time and run-time options are available to change various aspects of the CONVERT phrase, including the behavior of conversion errors and justification of the output of numeric items. See Video Options and The SCREEN Option in the ACUCOBOL-GT User's Guide for more information.
Parent topic: Common Screen Options


DEFAULT Phrase

{DEFAULT [IS default]}
{UPDATE              }
  1. The DEFAULT phrase allows for a default value to be displayed in an input field ready for editing by the user. It is displayed in a form that can be accepted with the CONVERT phrase. For numeric receiving fields, this will cause leading spaces to be removed. If a default value is specified, then it is the value displayed. Otherwise the current value of the receiving field is used. The UPDATE phrase is equivalent to the DEFAULT phrase with no default value specified.
  2. If the PROMPT phrase is also specified, then the prompt character replaces any trailing spaces in the field.
  3. The DEFAULT phrase is automatically implied for any update field specified in the Screen Section. The DEFAULT phrase implies the CONVERT phrase in a Format 1 ACCEPT statement.
    Note: The -Vu compiler option allows you to imply the UPDATE phrase for all Format 1 ACCEPT statements that do not have an explicit UPDATE or DEFAULT phrase specified for them.
Parent topic: Common Screen Options


ECHO Phrase

ECHO
  1. This causes the data entered to be redisplayed in the field. This allows for the action of the OUTPUT phrase to take place. Data will also be redisplayed with output conversion under the following circumstances:
    1. in VAX COBOL and ICOBOL compatibility modes, if the CONVERT or UPDATE phrase is used;
    2. in RM/COBOL compatibility mode, if the UPDATE phrase is used.
      Note: NO ECHO is not the opposite of ECHO. See the NO ECHO phrase below for more details.
  2. For entries specified in the Screen Section, the ECHO phrase is automatically implied. Output conversion does not occur, however.
  3. See the CONVERT phrase above for details on the effects of output conversion.
Parent topic: Common Screen Options


ENABLED Phrase

ENABLED {IS} {TRUE         }
        {= } {FALSE        }
             {enabled-state}

The ENABLED phrase determines whether or not the control can be used. When a control is enabled, it can be used normally. When it is disabled, it can be seen on the screen (if it is also visible), but the user cannot interact with it. If the TRUE phrase is used, then the control is enabled. The FALSE phrase makes the control disabled. If enabled-state is used instead, then its value determines whether the control is enabled. Any non-zero value enables the control; a value of zero (0) disables it. If the ENABLED phrase is omitted, the control is initially created enabled.

Disabled controls are displayed differently than enabled controls. For example, under Windows, disabled controls usually have dimmed text. See the configuration variable DISABLED_CONTROL_COLOR in Appendix H for information on how to configure the appearance of a disabled control when running on a character-based system.

Note: Under Microsoft Windows, the appearance of disabled controls can change depending on whether the program is running under the 16- or 32-bit runtime. The differences are intrinsic to the Windows API and cannot be worked around.
Parent topic: Common Screen Options


ERASE Phrase

{ERASE} [TO END OF] {LINE  }     (VAX, ICOBOL)
{BLANK}             {SCREEN}
{ERASE} [EOS]                    (RM)
{BLANK} [EOL]
  1. The ERASE phrase specifies that some or all of the current line or screen should be cleared to spaces. The spaces will use the currently selected background color for the active window, unless the -Vi compiler option was used. Cursor positioning occurs before the ERASE clause takes effect. See Video Options for more information.
  2. The ERASE LINE phrase causes the current line to be erased. The ERASE TO END OF LINE and ERASE EOL phrases both erase the line from the current cursor position to the end of the current window.
  3. The ERASE and ERASE SCREEN phrases cause the current window to be cleared. The ERASE TO END OF SCREEN and ERASE EOS phrases cause the window to be erased from the current cursor position to the end of the window.
  4. The cursor is not moved by these operations except in RM/COBOL compatibility mode, where ERASE (without the EOL or EOS phrases) specified on a Format 1 ACCEPT or DISPLAY verb causes the default cursor location to be line 1, column 1.
  5. When ERASE SCREEN is specified in a Screen Section entry, and that entry either contains or is subordinate to a COLOR phrase, then the default window colors are changed to match that COLOR phrase. This also applies to the FOREGROUND-COLOR and BACKGROUND-COLOR phrases.
  6. If a control has the TEMPORARY style and its upper-left location is within the erased area, the control will be destroyed. PERMANENT controls, however, are not affected.
Parent topic: Common Screen Options


EVENT-LIST, AX-EVENT-LIST, EXCLUDE-EVENT-LIST Phrases

EVENT-LIST    {IS} ( event-value { event-value ... } )
              {= }

AX-EVENT-LIST {IS} ( ax-event-value { ax-event-value ... } )
              {= }

EXCLUDE-EVENT-LIST {IS} list-state
                   {= }
  1. These phrases provide a mechanism for specifying a list of event types to either send or withhold (block) from the program depending on the value of EXCLUDE-EVENT-LIST. By default, listed events are sent to the program.
  2. Event-value and ax-event-value are numeric literals or data items that identify an event type. List elements must be enclosed by parentheses and separated by a space. If the list contains a single element, the parentheses can be omitted.
  3. List-state is an integer literal or numeric data item. Valid values are 0 and 1.
  4. EVENT-LIST and AX-EVENT-LIST hold a list of numeric values that correspond to event types.
  5. EVENT-LIST is used with ACUCOBOL-GT graphical controls. See Events Reference in the ACUCOBOL-GT Reference Manual for a discussion of events related to graphical controls, including a description of each event and its value.
  6. AX-EVENT-LIST is used with ActiveX and .NET controls. ActiveX and .NET events associated with a given control are listed in the COPY file (.def) created for that control with the AXDEFGEN or NETDEFGEN utility.
  7. The value of EXCLUDE-EVENT-LIST determines whether the event types in EVENT-LIST and AX-EVENT-LIST are sent to or withheld from the program. When EXCLUDE-EVENT-LIST is set to 0, the default value, events in the list are sent to the program. When EXCLUDE-EVENT-LIST is set to 1, events in the list are blocked (not sent to the program).
  8. Three runtime configuration variables, TC_EVENT_LIST, TC_AX_EVENT_LIST, and TC_EXCLUDE_EVENT_LIST, augment this facility in thin client deployments. For more information, see Preparing the Client in Thin Client(s) in the AcuConnect User's Guide.
Parent topic: Common Screen Options


FONT Phrase

FONT {IS} font-handle
     {= }

font-handle identifies the font to use for the control. If the font phrase is omitted, the window's default font for controls is used.

If you change a control's font after the control has been created, and its size is based on its font (true for controls that do not use the CELLS phrase), the control's dimensions are recomputed using the new font.

Parent topic: Common Screen Options


FOREGROUND-COLOR and BACKGROUND-COLOR Phrases

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}
  1. These phrases allow the specification of the foreground or background color. The color is a literal value taken from the following table:
    Value | Color
    0 | Black
    1 | Blue
    2 | Green
    3 | Cyan
    4 | Red
    5 | Magenta
    6 | Brown
    7 | White
    8 | Dark-Gray
    9 | Bright-Blue
    10 | Bright-Green
    11 | Bright-Cyan
    12 | Bright-Red
    13 | Bright-Magenta
    14 | Yellow
    Note: The values in this table are not the same as the Background Color and Foreground Color values in the acucobol.def file.
  2. fg-color and bg-color can also be used to set a control's colors. They specify both foreground and background colors in the same manner as they do for textual screen fields.

    Each control type determines the allowable set of colors and the interpretation of foreground color and background color. If either the foreground color or background color is omitted (or its particular value is not meaningful), then default colors are used. Each control class defines its own method of assigning default colors. Note that many host systems limit the ability to define a control's colors. The colors used will be as close to the requested colors as the host system allows.

  3. If both the COLOR phrase and the FOREGROUND-COLOR or BACKGROUND-COLOR phrase appear in the statement, the COLOR phrase takes precedence.
  4. These phrases are provided for compatibility with other COBOL systems. Note that the color value must be an integer literal or a numeric data item, and it may be an arithmetic expression. Also note that the color number is one less than the corresponding color value in the COLOR phrase (this is done to maintain compatibility with other COBOLs). For a method of assigning colors that can be variable, see the COLOR phrase above.
    Note: The -Vi compiler option changes the behavior of a Screen Section ERASE (and BLANK) phrase with respect to color handling. See Video Options for more information.
Parent topic: Common Screen Options


FOREGROUND-RGB and BACKGROUND-RGB Phrases

{FOREGROUND-RGB } val
{BACKGROUND-RGB}

These phrases apply to the following controls:

  • check box
  • combo box
  • entry field
  • frame
  • grid
  • label
  • list box
  • push button
  • radio button
  • toolbar

These phrases do not apply to the following controls:

  • bar
  • bitmap
  • browser
  • date entry
  • scroll bar
  • status bar
  • tab
  • tree view

Each control class determines the exact implementation or meaning.

The value is the normal Windows RGB encoding. See the MSDN GDI reference for more information.

A negative value causes the property to be ignored. The default value for all controls is -1.

When non-negative, the value overrides any other color specification. Also, the HIGH, LOW, NORMAL and REVERSE styles have no effect on the -RGB properties. The palette is also irrelevant. Normal color handling does occur, but is overwritten by any -RGB specification. This is important since not all systems support RGB colors.

FOREGROUND-RGB and BACKGROUND-RGB are ignored on any system with 256 colors or less.

Parent topic: Common Screen Options


FULL Phrase

{FULL        }
{LENGTH-CHECK}
  1. The FULL phrase applies only to input and update fields. When it is specified, the user must either leave the field blank or must enter non-space data into both the first and last character positions of the screen field. The user will not be able to leave the field until these requirements are met.
  2. If the user types an exception key (and exception keys are allowed), then the ACCEPT will terminate without forcing the user to meet the requirements of the FULL phrase.
Parent topic: Common Screen Options


HELP-ID Phrase

HELP-ID {IS} help-id
        {= }

The HELP-ID phrase establishes help-id as the control's help ID. The help ID is used in conjunction with certain events to provide context-sensitive application help. Usually, each control is given a unique, system-wide value so that it can be easily identified by the help processor. The maximum value of help-id is 2,147,483,647. For more information about HELP-ID and help automation, see Help Automation in User Interface Programming.

Parent topic: Common Screen Options


HIGH, LOW, and STANDARD Phrases

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }
  1. The HIGH, LOW, and STANDARD phrases set the high/low video attributes for the input field. If the terminal hardware does not support high/low intensity, then these phrases are ignored.
  2. HIGH sets the video attribute to high intensity. LOW sets the video attribute for the field to low intensity.
  3. STANDARD sets the video attribute for the field to be the default intensity for the terminal type being used. This will either be high or low intensity depending on the terminal.
  4. If none of these phrases is specified, STANDARD is used. This may be overridden by compile time options to set the default to either HIGH or LOW. See Video Options in the ACUCOBOL-GT User's Guide for more information.
Parent topic: Common Screen Options


IDENTIFICATION Phrase

{IDENTIFICATION} {IS} control-id
{ID            } {= }
  1. Use control-id to assign a unique identifier to a control. This identifier is used any time that control must communicate with your program. It is returned with any messages from the control. You can examine the ID to distinguish which control sent the message. This can be more convenient than using the control's handle because you can assign a fixed identifier that is the same in every run of the program.
  2. If control-id is omitted, then it will be treated as if it were zero (0), unless the control is defined in the Screen Section. In this case it will be assigned the same value as the control's field number (see Screen Description Entry, General Rules for Format 2, for a description of how Screen Section field numbers are assigned). Control IDs must be in the range of 0 to 32767.
Parent topic: Common Screen Options


KEY Phrase

KEY {IS} key-letter
    {= }
  1. The KEY phrase assigns a key letter to the control. The user can activate the control by typing its key letter in combination with some other special key. Under Microsoft Windows, key letters are typed in conjunction with the Alt key. The first character in key-letter becomes the control's key letter. The key letter can be given in lower- or upper-case.
  2. If the KEY phrase is omitted, the control's key letter is derived from its title. (See the TITLE phrase for details.) If a key letter is not indicated in the title, the control does not have a key letter. If a key letter is designated in both the title and the KEY phrase, the KEY phrase takes precedence. If the letter specified in the KEY phrase is not the same as the letter indicated in the title, the letter indicated in the title is highlighted and the letter specified in the KEY phrase is the key letter (this could be confusing to the user).
  3. The activation technique for key letters is shared with the menu bar handler on most systems. You should avoid assigning duplicate key letters in any one floating window, or assigning key letters that conflict with key letters used by the window's menu bar.
  4. Controls that cannot be activated, such as a label, may have key letters (see the example that follows). In this case, the runtime system uses the following rules to determine which control to activate when the key letter is typed:
    1. if another control has the same key letter, then the first control created with that key letter is activated when that key letter is pressed; otherwise,
    2. the next control that can be activated (in the same floating window) is activated. The runtime uses the order in which the controls were created to determine which control is next.

    In practice, these rules mean that you can usually assign a key letter in the title of a label and use rule b) to associate that key letter with a corresponding entry field. In this case, you do not need to use the KEY phrase. If rule (b) does not give you the effect you desire, you can use the KEY phrase and rule (a) to explicitly state the effect you want.

    For example, the following Screen Section segment:

       03 LABEL "&Customer: ".
   03 ENTRY-FIELD USING CUST-NO, COLUMN + 2."

    would assign a key letter of "C" to the label (using the implied key letter assignment from the label's title). Since labels cannot be activated, typing Alt-C would activate the CUST-NO entry field because it is the next control that can be activated.

    Note: If you use "&" in the control title, the letter that directly follows it becomes the accelerator key for this control, indicated by an underline. If you use the KEY IS construct to specify the accelerator key, that letter is not underlined in the control's title.
  5. A control's key letter is assigned when the control is created. It cannot be changed.
Parent topic: Common Screen Options


LAYOUT-DATA Phrase

LAYOUT-DATA {IS} layout-data
            {= }

The LAYOUT-DATA phrase sets the control's LAYOUT-DATA property. Some layout managers use this property to determine how to manage certain attributes of the control, such size and position. See the documentation for the specific layout manager for a description of layout-data and its accepted values. See Layout Managers for more information.

Parent topic: Common Screen Options


LINE NUMBER Phrase

AT LINE NUMBER line-num
  1. The LINE NUMBER phrase is used to position the cursor on a specific line or cell row of the terminal. A line number value of one indicates the top line of the current subwindow. To support fine positioning of controls in graphical environments, non-integer values are allowed. On text-mode systems, non-integer values are rounded down to the nearest whole number.
  2. When used with controls and floating windows, the line number positions the top edge of the control or window.
  3. If the LINE NUMBER phrase is missing or zero, then the results depend on the compatibility mode being used.
    1. In VAX COBOL and ICOBOL compatibility modes, the current cursor line is used. This is used in all cases when the statement refers to controls.
    2. In RM/COBOL compatibility mode, the current line is used if the COLUMN phrase specifies a value of zero or the NO ADVANCING phrase is used. Otherwise, the next line is used. In any case, if ERASE is also specified (without EOL or EOS), then line 1 is used instead.
  4. If the line number results in a value greater than the number of lines in the current window, the current window is scrolled up one line, and the line number is set to be the bottom line of the current window.

    This rule does not apply to controls. If a control is positioned outside of the current subwindow, it is not created.

  5. You may use LINE NUMBER with different units, such as CELLS or PIXELS. PIXELS apply only with controls, and not with windows. Non-integer values are allowed with cells, but they are not allowed with pixels.
  6. The LINE NUMBER phrase used for entries in the Screen Section has a different format. See section LINE Clause for details.
Parent topic: Common Screen Options


LINES Phrase

LINES {IS} height
      {= }
  1. The LINES phrase is used to set a window or control's height. Note that each control type defines exactly how this value is interpreted.

    Typically, the height field represents the logical height of the control. Frequently, this is based on the size of the control's title or value. For example, a LABEL control's height of 1 would specify a one-line label. If this phrase is omitted, the control type employs its own method of determining a default size.

  2. The CELLS option of the LINES phrase causes the HEIGHT-IN-CELLS control style to be used. This means that the height of the control is specified exactly using the cell size of the owning window. For example:
    LINES = 15 CELLS

    causes the control to have a height of 15 cells, where the exact height of a cell is inherited from the parent window.

  3. You may employ the PIXELS option with the LINES phrase to specify the control's size more precisely using the pixel size of the owning window. For example:
    LINES = 60 PIXELS
Parent topic: Common Screen Options


MAX-HEIGHT, MAX-WIDTH, MIN-HEIGHT, MIN-WIDTH Phrases

MAX-HEIGHT {IS} max-height
           {= }
MAX-WIDTH  {IS} max-width
           {= }
MIN-HEIGHT {IS} min-height
           {= }
MIN-WIDTH  {IS} min-width
           {= }
  1. MAX-HEIGHT, MAX-WIDTH, MIN-HEIGHT, and MIN-WIDTH are common properties of all graphical controls. They are unique from other common properties in that their names are reserved by the compiler only when they appear in the context of acting on a control: in a Screen Section entry, or a DISPLAY, MODIFY, or INQUIRE statement. See Styles and Special Properties for more information about the compilerreserves style and property names.
  2. The MAX-HEIGHT, MAX-WIDTH, MIN-HEIGHT, MIN-WIDTH phrases are used to specify a control's maximum and minimum height and width. These values are used by layout managers when resizing a control. See Layout Managers for more information.
  3. max-height is the maximum height of the control. It's value is in the same units as the control's LINES setting. The default value, zero, indicates no maximum height.
  4. max-width is the maximum width of the control. It's value is in the same units as the control's SIZE setting. The default value, zero, indicates no maximum width.
  5. min-height is the minimum height of the control. It's value is in the same units at the control's LINES setting. The default value, zero, indicates no minimum height.
  6. min-width is the minimum width of the control. It's value is in the same units at the control's SIZE setting. The default value, zero, indicates no minimum width.
Parent topic: Common Screen Options


NO ADVANCING Phrase

WITH NO ADVANCING
  1. This phrase inhibits the normal carriage-return, line-feed sequence that is sent to the terminal. In VAX COBOL and ICOBOL compatibility modes, this sequence is normally sent after the ACCEPT or DISPLAY statement executes. In RM/COBOL mode, this sequence is sent before the statement executes. These characters can cause the current terminal window to scroll if the current line is the last line in the window.
  2. This phrase is automatically implied when the LINE phrase is used. In VAX COBOL compatibility mode, this phrase is also implied when the COLUMN phrase is used. In RM/COBOL mode, this phrase is also implied when the COLUMN phrase is used with a zero value.
Parent topic: Common Screen Options


NO ECHO Phrase

{WITH NO ECHO}
{NO-ECHO     }
{SECURE      }
{OFF         }

The NO ECHO phrase enables data to be entered without being displayed on the terminal screen. This can be used to enter passwords and other secure data.

Parent topic: Common Screen Options


OUTPUT Phrase

OUTPUT {JUSTIFIED}  {LEFT    }
       {JUST     }  {RIGHT   }
                    {CENTERED}
  1. The OUTPUT phrase affects the alignment of displayed data. It has no effect in a Format 1 ACCEPT statement unless the ECHO phrase is also specified.
  2. The LEFT option causes data to be justified to the left edge of the field, the RIGHT option causes right-justification, and the CENTERED option causes the displayed data to be centered in the field.
  3. When the OUTPUT phrase is used, leading and trailing spaces are removed from the data before it is displayed. This is also done before the default size of the field is computed (except for Screen Section entries). Thus the three forms of justification are the same unless the SIZE phraseis also specified with a size larger than the data's length. Computing the default size after stripping the leading and trailing spaces allows fields to be concatenated together on the screen without computing column positions.
Parent topic: Common Screen Options


PROMPT Phrase

PROMPT [ CHARACTER IS prompt-lit ]
  1. The PROMPT phrase causes the input field to be filled with the specified prompt character prior to entry. If the prompt character is omitted, underscores are used.
  2. If the DEFAULT phrase is also used, then the prompt character replaces any trailing spaces in the field.
  3. The PROMPT phrase is automatically used for every entry in the Screen Section. Thus this phrase is treated as commentary in the Screen Section unless it specifies a prompt character other than underscores.
Parent topic: Common Screen Options


PROPERTY and Property-Name Phrases

{ property-name          } {IS }
   { prop-option [GIVING result-1] }...
{ PROPERTY property-type } {ARE}
{ method-name            } {=  }
{ object-expression      }

where prop-option is one of the following:

{ property-value [ LENGTH {IS} length-1 ] }
{                         {= }            }
{                                         )
{ ( {property-value} ... )                }
{                                         }
{ { MULTIPLE } property-table             }
{ { TABLE    }                            }
{                                         }
{ parameter                               }
{                                         }
{ ( { parameter } ... )                   }
  1. The PROPERTY phrase assigns a value to one of a control's special properties or invokes a control-specific method. The PROPERTY phrase takes the types of only special properties and methods for controls. See The Components of a Control for more information. See Methods for more information about methods. Each type of control has its own set of special properties and methods. These are described in the help topics for each control type. property-value specifies which special property to modify or which method to invoke (each of a control's special properties and methods is uniquely identified by a number). property-value is the value to assign to that special property. property-value must be a data type that is appropriate for the specified property. If property-type specifies a special property that does not exist, it is ignored for most control types. If the control type is ACTIVE-X, then an exception is raised.Each property's unique value is defined in the file controls.def or in the ActiveX control's COPY file. See ActiveXfor more information.
  2. property-value and method-name provide an alternate method for identifying which special property to modify or which method to invoke. The compiler knows the names of the special properties and methods that belong to each control type. In situations where the compiler knows which type of control is being acted upon, you can use the appropriate property-name or method-name directly instead of using the special property's or method's identifying number in the PROPERTY phrase.

    For example, the MAX-TEXT special property of entry fields is property number 1. You can set the value of this property to 10 with either of the following phrases:

    PROPERTY 1 = 10
MAX-TEXT = 10

    The second method can be used only when your code makes it clear to the compiler that you're acting on an entry field.

    You can use either the PROPERTY phrase or method-name to specify which method to invoke. For example, the LoadFile method of the Microsoft Rich Textbox Control is method number 37. You can invoke this method with either of the following phrases:

    PROPERTY 37 ("myfile.rtf", rtfRtf)
LoadFile ("myfile.rtf", rtfRtf)

    The second method can be used only when your code makes it clear to the compiler that you're acting on a Microsoft Rich Textbox Control.

  3. Some properties return specific values when set. These values are placed in result-1 of the GIVING phrase. The meaning of the value depends on the property being set; see the documentation for the specific property. Properties that do not have a pre-defined return value set result-1 to 1 if the property was set successfully, or "0" if not. When a property is being given multiple values in a single assignment (for example: Display-Columns = (1, 10, 30)), then result-1 is set in response to the last value assigned.
  4. When multiple special property assignments are made in a single statement, those assignments are performed in the order listed in the statement.
  5. If more than one property-value is specified, each one is applied to the property in the order listed. This is normally used for cumulative properties. These are properties that perform some special action each time they have a value assigned to them. For example, you can set three columns in a list box with DISPLAY-COLUMNS = (1, 20, 35 ). In the case of the DISPLAY-COLUMNS property, each time it is assigned a value, it sets a new column location. Note that the parentheses are required.

    When you specify property-table, then each element of the table is assigned to the property. The elements are assigned in ascending occurrence order. For example, the following code fragment fills a list box with the names of three colors:

    01  COLOR-NAMES.
    03  PIC X(10) VALUE "Red".
    03  PIC X(10) VALUE "Green".
    03  PIC X(10) VALUE "Blue".

01  COLOR-TABLE REDEFINES COLOR-NAMES
    OCCURS 3 TIMES
    PIC X(10).

PROCEDURE DIVISION.
MAIN-LOGIC.
    DISPLAY LIST-BOX, SIZE 10, LINES 3,
            ITEM-TO-ADD = TABLE COLOR-TABLE.
    Note: The current size of the table is used, so you can use OCCURS DEPENDING ON tables when you want to have a variable number of items in a table.

    You should use caution when specifying property tables in the Screen Section. Remember that each DISPLAY statement of a Screen Section item reloads all of that item's properties into the control. This can be inefficient if the property table is large, and it can cause duplicate entries if you are not careful. To avoid this, you can create your controls in the Screen Section, but use the MODIFY statement to set any table-oriented properties at the appropriate point in your program. In this way, the tables are not referenced in the Screen Section and a DISPLAY will not cause those tables to be reprocessed.

  6. When the LENGTH option is specified, length-1 establishes the exact size of property-value. The text value presented to the control must not contain trailing spaces or have trailing spaces added. When you specify the LENGTH option, the control uses exactly the number of characters of length-1. However, if length-1 is a value larger than the size of the data item it is modifying, the size of the data item is used instead. If length-1 is negative, it is ignored and the default handling occurs.
  7. {parameter}... is a list of parameters to pass when invoking one of a control's methods or setting a multiple-parameter property. When setting a multiple-parameter property, the first parameters identify which aspect of the property to set. The last parameter is the actual property value. For example, to set the Microsoft Chart Control DataGrid::RowLabel property you must specify the row number and label index. You could use the following phrase:
    DataGrid::RowLabel( ROW-NUMBER, ROW-LABEL-INDEX,
    "My Row Label" )
  8. object-expression can only be used in the procedure division, not the screen section. It has the following format:
    { {^} property-1 [ ( param-1 ... ) ]
  [ :: property-2 [ ( param-2 ... ) ] ]... }

    object-expression specifies a property or method of an object referenced by another object. This object in turn can be referenced by yet another object. The "root" object can be an ActiveX control or COM object or a graphical control. "^" can only be used in conjunction with Format 5 USE verb (see the documentation for the USE verb for more information). property-1 is the name of a property of the ActiveX control or COM object. property-1 must not be a write-only property. property-2 is the name of a property of the ActiveX control or COM object which is the value of property-1. property-2 must not be a write-only property. param-1 and param-2 are literals, data items or numeric expressions. param-1 is the first parameter passed when getting the value of property-1 and param-2 is the first parameter passed when getting the value of property-2.

    For example, to set the Microsoft Chart Control legend, you get the value of the Legend property. This value is an object that you may then modify to change the legend. The Legend object has properties whose values are other objects, and so on. The following phrases set properties and invoke methods of the Microsoft Chart Legend object:

    Legend::Location::Visible = 1
Legend::Location::LocationType = VtChLocationTypeRight
Legend::TextLayout::HorzAlignment =
           VtHorizontalAlignmentRight
Legend::VtFont::VtColor::Set (255, 255, 0)
Legend::BackDrop::Fill::Style = VtFillStyleBrush
Legend::BackDrop::Fill::Brush::Style = VtBrushStyleSolid
Legend::BackDrop::Fill::Brush::FillColor::Set (255, 0, 255)

    or assuming the handle to the Microsoft Chart Control is MS-CHART-1:

    USE MS-CHART-1 Legend
      MODIFY ^Location::Visible = 1
         ^Location::LocationType = VtChLocationTypeRight
         ^TextLayout::HorzAlignment =
               VtHorizontalAlignmentRight
         ^VtFont::VtColor::Set ( 255, 255, 0 ).
USE MS-CHART-1 Legend::BackDrop::Fill
      MODIFY ^Style = VtFillStyleBrush
         ^Brush::Style = VtBrushStyleSolid
         ^Brush::FillColor::Set ( 255, 0, 255 ).
Parent topic: Common Screen Options


REQUIRED Phrase

{REQUIRED   }
{EMPTY-CHECK}
  1. The REQUIRED phrase applies only to input and update fields. When it is specified, the user may not leave the field empty--some non-blank data must be entered. If the receiving field is numeric or numeric edited (and input conversion is being used), then the entered value may not be zero. The user will not be able to leave the field without meeting these requirements.
  2. In a Screen Section, the REQUIRED phrase forces the user to enter data in the field before terminating the ACCEPT.

    This prevents the user from jumping to the last field with the mouse, and thus bypassing a required field. If the user attempts to terminate an ACCEPT while required fields are still blank, an error message is displayed and the cursor is positioned at the first required field that is blank.

  3. If the user types an exception key (and exception keys are allowed), the ACCEPT will terminate without forcing the user to meet the requirements of this phrase. Note that leaving a field by clicking on another control with the mouse will cause the REQUIRED check to occur. Therefore, CANCEL buttons should always have the SELF-ACT style. The SELF-ACT style does not cause the runtime to change the focus of the current control - the input or update field is not left - and the REQUIRED phrase is not triggered. Without the SELF-ACT style, the CANCEL button will cause focus to shift to itself, triggering the REQUIRED check and preventing the user from canceling without first entering some data.
Parent topic: Common Screen Options


REVERSED Phrase

{REVERSE-VIDEO}
{REVERSE      }
{REVERSED     }

The REVERSED phrase causes the field to have reversed foreground and background colors. If the terminal hardware does not support reverse-video, then this phrase is ignored.

Parent topic: Common Screen Options


SAME Phrase

SAME
  1. The SAME phrase causes the field to use the video attributes currently present at the field's screen location. This allows data on the screen to be changed without changing the screen's video attributes.
  2. The SAME phrase may not be specified along with the UNDERLINED, BLINK, REVERSED, HIGH, LOW, STANDARD, COLOR, FOREGROUND-COLOR, or BACKGROUND-COLOR phrases.
Parent topic: Common Screen Options


SCROLL Phrase

SCROLL [UP  ] [ BY scrl-num {LINE } ]
       [DOWN]               {LINES}
  1. The SCROLL phrase specifies the number of lines to scroll the current window. Scrolling is the first operation performed by the ACCEPT or DISPLAY statement--it occurs before any cursor positioning or the operation of any ERASE clauses. Scrolling does not affect the current cursor position.
  2. If the UP phrase is specified, the contents of the current window are scrolled upward (normal scrolling). If DOWN is used, then the contents are moved downward (reverse scrolling). A blank line with the default video attributes for the window is introduced at the top or bottom of the window (as appropriate). Upward scrolling is used if neither the UP nor DOWN phrase is specified.
  3. If a scrolling value is specified, its value is the number of lines to scroll the screen. If this value is not positive, no scrolling occurs. If the scrolling value is omitted, one line is scrolled.
Parent topic: Common Screen Options


SIZE Phrase (with a text entry field)

WITH PROTECTED SIZE length
  1. The SIZE phrase specifies the size (length) of the field. After the ACCEPT or DISPLAY is finished, the cursor is placed immediately after the field defined by this clause, unless this would place the cursor outside of the current terminal window. In this case, the cursor is wrapped around to the beginning of the next line (scrolling the window if necessary).
  2. If the SIZE phrase is not used, then the field length defaults to the size of the item being accepted or displayed. If the CONVERT phrase is used, however, then the size of the field depends on the data type of the item and the verb being used:
    1. If the DISPLAY verb is executing, then the size is the same as if the CONVERT phrase were not specified except for numeric items. For numeric items, the size is the number of digits in the item, plus one if it is not an integer, plus one if it is signed. This rule also applies to the action of the ECHO phrase of the ACCEPT statement (see below). The remaining cases cover the size when an ACCEPT statement is used.
    2. If the item is numeric or numeric edited, then the size is the number of digits in the item, plus one if it is not an integer, plus one if it is signed.
    3. If the item is alphanumeric edited, then the size is set to the number of "A" or "X" positions specified in its PICTURE clause.
    4. For all other data types, the field size is set to the size of the item (same as if CONVERT were not specified).
      Note: You cannot supply the CONVERT phrase in the Screen Section. Thus the size of a Screen Section field is always the size of its screen entry unless the SIZE phrase is specified.
  3. Note that the OUTPUT phrase changes the way in which the default field size is computed. See that heading above for details. Also note that the OUTPUT phrase affects only the way items are displayed on the screen; the internal format of accepted data is not affected.
Parent topic: Common Screen Options


SIZE Phrase (with Windows and Controls)

SIZE {IS} length [CELL  ]
     {= }        [CELLS ]
                 [PIXEL ]
                 [PIXELS]
  1. The SIZE phrase is used to set a window or control's width (length). Non-integer values are allowed. Note that each control type defines exactly how this value is interpreted.

    Typically, the length field represents the logical width of the control. Frequently, this is based on the size of the control's title or value. For example, an ENTRY-FIELD's width of 8 would specify a field large enough to enter eight (average size) characters. If this phrase is omitted, the control type employs its own method of determining a default size.

  2. The CELLS option of the SIZE phrase causes the WIDTH-IN-CELLS control style to be used. This means that the width of the control is specified exactly using the cell size of the owning window. For example:
    SIZE = 15 CELLS

    causes the control to have a width of 15 cells, where the exact width of a cell is inherited from the parent window.

  3. You may use the SIZE phrase with PIXELS when defining controls. This means that the width of the control is specified exactly using the pixel size of the owning window. For example:
    SIZE = 150 PIXELS

    causes the control to have a width of 150 pixels, where the exact width of a pixel is inherited from the parent window. Non-integer values are not allowed with pixels.

Parent topic: Common Screen Options


STYLE Phrase and Style-Name

STYLE {IS} style-flags
      {= }

{style-name} ...
  1. In the STYLE phrase, style-flags is a numeric field that holds a value that specifies the styles to apply to the control. Each control type defines its own set of styles and how the style-flags value is interpreted. style-flags holds the sum of the numbers that represent the desired styles. Each style's identifying number is defined in the file controls.def. If style-flags is omitted, the default style attributes are applied to the control.
  2. A style-name is the name of a valid style for the type of control being acted upon. For example, some of the styles that apply to a radio-button include: BITMAP, FRAMED, and NOTIFY. Each style-name causes that style to be applied to the control.
  3. You may use both the STYLE phrase and individual style-names for a particular control. The effect is to add the set of specified styles together. You would typically use the STYLE phrase to specify styles that may change at runtime, and style-name for those styles that are fixed.

    For more information about control styles, and the STYLE and style-name phrases, see Styles and Special Properties in ACUCOBOL-GT User Interface Programming.

Parent topic: Common Screen Options


TAB Phrase

TAB

The TAB phrase forces the user to finish entering data by typing a valid termination key. It is the opposite of the AUTO phrase. The TAB phrase is the default behavior except in a Format 1 ACCEPT statement when you are using RM/COBOL compatibility mode.

Parent topic: Common Screen Options


TITLE Phrase

TITLE {IS} title
      {= }
  1. The value of title sets the control's title. If title is omitted, then the control does not have a title. Some controls (such as entry fields, list boxes, and combo boxes) do not have titles. In these cases, any specified title is ignored.
  2. If you change the title of a control and that control was created with the default sizing rules (did not have a size explicitly specified for it), the control is resized based on the length of the new title.
  3. You can specify a key letter in a title by including the "&" character immediately before the key letter. The key letter is usually highlighted by the host system (under Windows, the key letter is underlined). The "&" character both defines the key letter and performs the highlighting. The key letter indicates that the user can go to the appropriate field by typing the key letter in combination with another key. Exactly how this occurs is system dependent. Under Windows, the user presses the "Alt" key in conjunction with the key letter. Some systems do not support key letters, in which case the first "&" character in a title is ignored. When the KEY phrase is used and an "&" character appears in title, the KEY phrase specifies the key letter and the character following the "&" indicates the highlighted character.
Parent topic: Common Screen Options


UNDERLINED Phrase

{UNDERLINE }
{UNDERLINED}

The UNDERLINED phrase causes the field to have the underscore video attribute applied to it. If the terminal hardware does not support underlining, then this phrase is ignored. UNDERLINED cannot be combined with BLINK.

Parent topic: Common Screen Options


UPON Phrase

UPON new-window
  1. The UPON phrase is used to update a floating window that is not the current floating window. In this phrase new-window is a USAGE HANDLE or PIC X(10) data item that contains a valid floating window handle. The floating window specified by new-window becomes the current window for the duration of the DISPLAY statement.
  2. If you create a new floating window while in the scope of the UPON phrase, the new window becomes the current window after the DISPLAY statement terminates. Otherwise, the window that was current before the DISPLAY UPON statement executed is restored to the current window. For example, if the main application window is current and you execute:
    DISPLAY FLOATING WINDOW UPON MAIN-WINDOW, ...

    when the DISPLAY statement terminates, the new floating window becomes the current window, instead of the main application window.

    Note: new-window is always the current window for the entire remaining DISPLAY statement, even if you mix DISPLAY formats. For example:
    DISPLAY SUBWINDOW UPON WINDOW-1,
   AT 0504, LINES 5, SIZE 30, BOXED
   "Line 1", LINE 1,
   "Line 2", LINE 2.

    The above code creates a new subwindow in WINDOW-1 and then displays two lines in the new subwindow. The UPON WINDOW-1 phrase applies to both the DISPLAY SUBWINDOW operation and the display of the subsequent text items because they are all specified in one DISPLAY statement.

  3. When you mix several DISPLAY formats, the logic to determine the current window is applied sequentially through the statement. Here is a complex example:
    DISPLAY FLOATING WINDOW UPON WINDOW-1
   LINES 10, SIZE 40, BOXED,
   HANDLE IN WINDOW-99;
   "Line 1", LINE 1,
   "Line 2", UPON WINDOW-2, LINE 2
   "Line 3", LINE 3.

    In this example, the new floating window (WINDOW-99) is created with WINDOW-1 as its parent (because of the first UPON phrase). Normally, this UPON phrase would cause "Line 1" to display in WINDOW-1 too, but the DISPLAY FLOATING WINDOW operation causes the new window to become the current window. So, "Line 1" is shown in WINDOW-99 instead. This would apply to "Line 2" also, but it specifies its own UPON phrase, so it displays in WINDOW-2. "Line 3" also displays in WINDOW-2 because that was the last window specified. At the end of the DISPLAY statement, the new floating window, WINDOW-99, is made the current window.

Parent topic: Common Screen Options


UPPER and LOWER Phrases

{UPPER}
{LOWER}

When the UPPER phrase is specified, all lower-case characters received by the ACCEPT statement are converted to upper-case. If the LOWER phrase is specified, all upper-case characters are converted to lower-case. If the ECHO phrase is also specified, the redisplayed data will be in the converted form.

Note: It may be necessary for you to use the configuration variable UPPER_LOWER_MAP to ensure correct translation.
Parent topic: Common Screen Options


VALUE Phrase

VALUE {IS} [ MULTIPLE ] value
      {= } [ TABLE    ]
  1. Value sets the value of the control. If the control does not take a value, then the VALUE phrase is ignored. The exact interpretation of value depends on the type of control. A control's value is either an integer or an alphanumeric string. If the control takes an integer value, then value should specify a numeric literal or data item. If the control takes an alphanumeric string, then value may be either numeric or alphanumeric. If value is numeric, it is converted to an alphanumeric string that represents its numeric value.
  2. The MULTIPLE phrase is used only with certain control types that allow for multiple values. The Screen Section VALUE phrase has some additional rules. See Screen Description Entry for more information. TABLE is a synonym for MULTIPLE.
Parent topic: Common Screen Options


VISIBLE Phrase

VISIBLE {IS} {TRUE         }
        {= } {FALSE        }
             {visible-state}

The VISIBLE phrase determines whether or not the control is shown on the screen. If the VISIBLE phrase is set to TRUE, the control is shown. If it is set to FALSE, the control is invisible. If visible-state is used instead, then its value determines whether the control is shown. Any non-zero value indicates that the control is visible; zero indicates that it is invisible. Controls that are invisible do not appear on the screen and cannot be used. They continue to exist, however, and can be made visible subsequently in the program. If the VISIBLE phrase is omitted, then the control is initially made visible.

Parent topic: Common Screen Options


ZERO-FILL and NUMERIC-FILL Phrases

{ZERO-FILL   }
{NUMERIC-FILL}
  1. The ZERO-FILL and NUMERIC-FILL phrases may be applied only to alphanumeric input or update fields. These phrases are ignored for output fields. Only one of these options may be specified for a single field.
  2. The ZERO-FILL phrase causes trailing spaces in the entered data to be replaced by the 0 character. If the destination is JUSTIFIED, then leading spaces will be replaced instead.
  3. The NUMERIC-FILL phrase causes the runtime system to examine the entered data. If the entered value consists entirely of digits and trailing spaces, then the entered digits are right justified and the leading character positions are replaced by the "0" character. If the entered data is empty, or contains any non-digit characters, the data is left alone.
Parent topic: Common Screen Options


Procedure Division Format

Format 1

PROCEDURE DIVISION

   [ {USING   } {parameter} ... ] .
     {CHAINING}

[ DECLARATIVES.

{ section-name SECTION [segment-no] .

   declarative-sentence

[ paragraph-name.

  [ sentence ] ... ] ... } ...

  END DECLARATIVES. ]

{ section-name SECTION [segment-no] .

[ paragraph-name.

   [ sentence ] ... ] ... } ...

Format 2

PROCEDURE DIVISION
   [ {USING   } {parameter} ... ] .
     {CHAINING}

{ paragraph-name.

   [ sentence ] ... ] ... } ...

Syntax Rules

  1. If one paragraph is in a section, all paragraphs must be in sections.
  2. A section consists of a section header followed by zero or more paragraphs.
  3. A paragraph consists of a paragraph header followed by zero or more sentences.
  4. A sentence is one or more statements terminated by a period.
  5. parameter must refer to a data item defined with a level-number of 01 or 77. If the USING phrase is used, then each parameter must be declared in the Linkage Section. If the CHAINING phrase is used, then each parameter must be declared in the File or Working-Storage Section.
  6. Each parameter may not appear more than once in a USING/CHAINING phrase.
  7. declarative-sentence must be a USE statement followed by a period.
  8. segment-no must be a number between zero and 99.
  9. Each segment-no in the Declaratives must be less than 50.
  10. If the segment-no is absent, it is treated as if it were zero.
  11. Each section-name must be a unique user-defined word (exception: a section-name may be the same as a data name).

General Rules

  1. The USING phrase is used only for programs that are invoked by a CALL statement with a USING phrase.
  2. The USING phrase identifies the names used in the program to refer to arguments passed from the calling program. In the calling program, the USING phrase of the CALL statement identifies the arguments. The two USING lists correspond positionally.
  3. References to USING phrase parameters operate according to the data description entries in the program's Linkage Section independent of their descriptions in the calling program.
  4. A Linkage Section data item can be referred to in the Procedure Division only if it satisfies one of the following conditions:
    1. It is named in the Procedure Division's USING phrase.
    2. The address of the data item is assigned to another data item or a pointer. This is accomplished through the SET ADDRESS OF statement. See the Linkage Section in Data Division Format and the SET Statement for additional information.
    3. It is subordinate to a parameter named in the USING phrase.
    4. It is a data item defined by a REDEFINES or RENAMES clause whose object is named in the USING phrase. Data items subordinate to such items may also be referenced.
    5. It is a condition-name or index-name associated with any data item that satisfies any of the previous conditions.
  5. Any changes made to the data items referred to in the USING phrase are reflected in the calling program when the current program exits.
  6. The CHAINING phrase is used only for a program that is the first program executed in a run unit (a "main" program). Each parameter has its initial value set according to the following rules:
    1. If the program is initiated from the host operating system, each parameter is initialized to the corresponding command-line argument
    2. If the program is initiated by a CHAIN statement, then each parameter receives the value of the corresponding USING item specified by that CHAIN statement.
    3. Values are assigned to each parameter as if the value were the alphanumeric source for an elementary MOVE to parameter. If parameter is not alphanumeric, then it is treated as if it were implicitly redefined as alphanumeric before this MOVE occurs.
    4. If there are fewer arguments than parameters, then the excess parameters are initialized according to the rules that would apply if they were not listed in the CHAINING phrase.
    5. If there are more arguments than parameters, the excess arguments are ignored.
  7. Segment-numbers describe the segments of the program. If segmentation is used, then sections must be placed so that a particular segment number is never smaller than the segment number for any previous section (in other words, all the sections belonging to a particular segment must be placed together).
  8. Unless altered by the SEGMENT-LIMIT phrase of the Configuration Section, segment numbers less than 50 are placed in the program's fixed memory space. The fixed memory space is loaded when the program first starts and remains resident until the program is canceled.
  9. Segment numbers of 50 or greater reside in the swapped memory space. The swapped memory space contains only one segment at a time. If the program's flow of control requires that a different segment be executed than the one that is currently residing in the swapped memory space, then it is loaded from the program's object file. This reduces the amount of memory space required by the program, at the expense of performing additional disk reads when new segments are needed. This swapped memory space applies only to Version 7.2 and earlier. Later versions treat segmentation as commentary.
  10. Sections with the same segment-no are considered to be part of the same segment. They are all loaded together when that segment is read into memory.
  11. The functional behavior of a program with segmentation is identical to that same program without segmentation. The only difference is that the program requires less memory but (potentially) more time to run. It is legal for the flow of control to pass directly or indirectly from one swapped segment to another.
  12. When using segmentation, take care that the program's flow of control does not cause excessive swapping. If it does, the performance of the program may be substantially degraded.
  13. An individual segment may not exceed 64 KB.
Parent topic: Procedure Division


Procedure Division Statements

Every statement in COBOL is started with a reserved word called a verb. The topics in this section cover the verbs available in ACUCOBOL-GT.

  • ACCEPT Statement
  • ADD Statement
  • ALTER Statement
  • CALL Statement
  • CANCEL Statement
  • CHAIN Statement
  • CLOSE Statement
  • COMMIT Statement
  • COMPUTE Statement
  • CONTINUE Statement
  • CREATE Statement
  • DELETE Statement
  • DESTROY Statement
  • DISPLAY Statement
  • DIVIDE Statement
  • ENTRY Statement
  • EVALUATE Statement
  • EXHIBIT Statement
  • EXIT Statement
  • GOBACK Statement
  • GO TO Statement
  • IF Statement
  • INITIALIZE Statement
  • INQUIRE Statement
  • INSPECT Statement
  • LOCK Statement
  • MERGE Statement
  • MODIFY Statement
  • MOVE Statement
  • MULTIPLY Statement
  • NEXT SENTENCE Statement
  • OPEN Statement
  • PERFORM Statement
  • READ Statement
  • RECEIVE Statement
  • RELEASE Statement
  • RETURN Statement
  • REWRITE Statement
  • ROLLBACK Statement
  • SEARCH Statement
  • SEND Statement
  • SET Statement
  • SORT Statement
  • The SORT Statement (for SORT TABLE)
    The SORT statement creates a sort file by executing input procedures or by transferring records from another file, sorts the records in the sort file on a set of specified keys, and in the final phase of the sort operation, makes available each record from the sort file, in sorted order to some output procedures or to an output file.
  • START Statement
  • STOP Statement
  • STRING Statement
  • SUBTRACT Statement
  • UNLOCK Statement
  • UNSTRING Statement
  • USE Statement
  • WAIT Statement
  • WRITE Statement
  • XML GENERATE Statement
  • XML PARSE Statement
Parent topic: Procedure Division


ACCEPT Statement

The ACCEPT statement makes low-volume data available to the program. See Common Screen Options for more information on many of the optional clauses shown below.

The different forms of the ACCEPT statement perform the following functions:

  • Format 1, ACCEPT (an individual field)
  • Format 2, ACCEPT (a Screen Section item, one or more fields)
  • Format 3, ACCEPT FROM (returns selected data from the operating environment)
  • Format 4 , ACCEPT SCREEN (accepts data found on screen)
  • Format 5, ACCEPT ENVIRONMENT (accepts value of variable from user's environment or from ACUCOBOL-GT's runtime configuration settings)
  • Format 6, ACCEPT (ANSI style)
  • Format 7, ACCEPT (activates a specific control)
  • Format 8, ACCEPT (accepts HTML forms)
  • Format 9, ACCEPT EVENT (accepts an event)
  • Format 10, ACCEPT (HP COBOL)
  • Format 11, ACCEPT (HP COBOL)
  • Format 12, ACCEPT (HP COBOL)
  • Format 13, ACCEPT FROM ENVIRONMENT-VALUE (returns the value of the special register ENVIRONMENT-NAME)

Depending on the Format and options used, an ACCEPT statement can return the following predefined exception values. The numbers listed here are the actual values that are returned. Exception values can be found in the file acugui.def. The names given here are the level 78 data items found in that file.

95 W-MESSAGE | - message received (ACCEPT ALLOWING MESSAGES)
96 W-EVENT | - ACCEPT terminated by an event
97 W-NO-FIELDS | - no input fields, or all fields protected or hidden
98 W-CONVERSION-ERROR | - numeric conversion error
99 W-TIMEOUT | - ACCEPT timed out (ACCEPT BEFORE TIME)

Note that ACCEPT works differently on Windows and character-based systems. In Windows, an entry field is automatically in insert mode—that is, typing characters moves other characters instead of overwriting them. In character-based systems, entry fields start in overwrite mode, so typing new characters overwrites characters that already exist.

Format 1

ACCEPT {dest-item}
       {OMITTED }

Remaining phrases are optional, can appear in any order.

AT screen-loc

{FROM} LINE NUMBER line-num
{AT  }

{FROM} {COLUMN  } NUMBER col-num
{AT  } {COL     }
       {POSITION}
       {POS     }

WITH PROTECTED SIZE length

WITH NO ADVANCING

{ERASE} [TO END OF] {LINE  } (VAX, ICOBOL)
{BLANK}             {SCREEN}

{ERASE} [EOS]                (RM)
{BLANK} [EOL]

WITH [NO] {BELL}
          {BEEP}

{UNDERLINE }
{UNDERLINED}

WITH {BLINKING}
     {BLINK   }

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{REVERSE-VIDEO}
{REVERSE      }
{REVERSED     }

SAME

WITH {COLOR } color-val
     {COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

SCROLL [UP ] [ BY scrl-num {LINE } ]
       [DOWN]              {LINES}

OUTPUT {JUSTIFIED} {LEFT    }
       {JUST     } {RIGHT   }
                   {CENTERED}

WITH {CONVERSION}
     {CONVERT   }

{WITH NO ECHO}
{NO-ECHO     }
{SECURE      }
{OFF         }

PROMPT [ CHARACTER IS prompt-lit ]

{DEFAULT [IS default]}
{UPDATE              }

ECHO

{AUTO         }
{AUTO-SKIP    }
{AUTOTERMINATE}
{TAB          }

{UPPER}
{LOWER}

CURSOR curs-offset

CONTROL cntrl-string

{REQUIRED   }
{EMPTY-CHECK}

{FULL        }
{LENGTH-CHECK}

{ZERO-FILL   }
{NUMERIC-FILL}

CONTROL KEY IN key-dest

BEFORE TIME timeout

ALLOWING MESSAGES FROM { THREAD thread-1 }
                       { LAST THREAD     }
                       { ANY THREAD      }

[ { ON EXCEPTION [key-dest] } {statement-1 } ]
  { ON ESCAPE    [key-dest] } {NEXT SENTENCE}
  { AT END                  }

[ NOT { ON EXCEPTION } statement-2 ]
      { ON ESCAPE    }
      { AT END       }

[ END-ACCEPT ]

Format 2

ACCEPT screen-name

Remaining phrases are optional, can appear in any order.

AT screen-loc

{FROM} LINE NUMBER line-num
{AT  }

{FROM} {COLUMN  } NUMBER col-num
{AT }  {COL     }
       {POSITION}
       {POS     }

BEFORE TIME timeout

ALLOWING MESSAGES FROM { THREAD thread-1 }
                       { LAST THREAD }
                       { ANY THREAD }
[ UNTIL condition-1 ]

[ ON {EXCEPTION} statement-1 ]
     {ESCAPE   }

[ NOT ON {EXCEPTION} statement-2 ]
         {ESCAPE   }

[ END-ACCEPT ]

Format 3

ACCEPT dest-item FROM {DATE                       }
                      {DAY                        }
                      {CENTURY-DATE               }
                      {DATE YYYYMMDD              }
                      {CENTURY-DAY                }
                      {DAY YYYYDDD                }
                      {TIME                       }
                      {DAY-OF-WEEK                }
                      {TERMINAL-INFO              }
                      {SYSTEM-INFO                }
                      {INPUT STATUS               }
                      {ESCAPE KEY                 }
                      {LINE NUMBER                }
                      {COMMAND-LINE               }
                      {STANDARD OBJECT object-name}
                      {THREAD HANDLE              }
                      {WINDOW HANDLE              }

Format 4

ACCEPT dest-item FROM SCREEN

Remaining phrases are optional, can appear in any order.

AT screen-loc

{FROM} LINE NUMBER line-num
{AT  }

{FROM} {COLUMN  } NUMBER col-num
{AT }  {COL     }
       {POSITION}

SIZE length

Format 5

ACCEPT dest-item FROM {CONFIGURATION} env-name
                      {ENVIRONMENT  }

[ ON EXCEPTION statement-1 ]

[ NOT ON EXCEPTION statement-2 ]

[ END-ACCEPT ]

Format 6

ACCEPT dest-item [ FROM mnemonic-name ]

Format 7

ACCEPT {control-handle}
       {CONTROL       }

Remaining phrases are optional, can appear in any order.

VALUE IN [ MULTIPLE ] value

AT screen-loc [CELL  ]
              [CELLS ]
              [PIXEL ]
              [PIXELS]

AT LINE NUMBER line-num [CELL  ]
                        [CELLS ]
                        [PIXEL ]
                        [PIXELS]

AT {COLUMN  } NUMBER col-num [CELL  ]
   {COL     }                [CELLS ]
   {POSITION}                [PIXEL ]
   {POS     }                [PIXELS]

AT CLINE NUMBER cline-num [CELL ]
                          [CELLS]

AT CCOL NUMBER ccol-num [CELL ]
                        [CELLS]

WITH {BELL}
     {BEEP}

BEFORE TIME timeout

CONTROL KEY IN key-dest

ALLOWING MESSAGES FROM { THREAD thread-1 }
                       { LAST THREAD     }
                       { ANY THREAD      }

ON {EXCEPTION} [key-dest] statement-1
   {ESCAPE   }

NOT ON {EXCEPTION} statement-2
       {ESCAPE   }

END-ACCEPT

Format 8

ACCEPT external-form-item

Format 9

ACCEPT EVENT

Remaining phrases are optional.

BEFORE TIME timeout
ALLOWING MESSAGES FROM { THREAD thread-1 }
                       { LAST THREAD     }
                       { ANY THREAD      }

[ { ON EXCEPTION [code-dest] } {statement-1 } ]
  { ON ESCAPE    [code-dest] } {NEXT SENTENCE}
  { AT END                   }

[ NOT { ON EXCEPTION } statement-2 ]
      { ON ESCAPE    }
      { AT END       }

[ END-ACCEPT ]

Format 10 (HP COBOL)

ACCEPT identifier [FREE] [FROM { SYSIN        }]
                               { CONSOLE       }
                               { mnemonic-name }

Format 11 (HP COBOL)

ACCEPT identifier FREE [FROM { SYSIN         }]
                             { CONSOLE       }
                             { mnemonic-name }

[ON INPUT ERROR imperative-statement-1]

[NOT ON INPUT ERROR imperative-statement-2]

[END-ACCEPT]

Format 12 (HP COBOL)

ACCEPT identifier FROM { DATE        }
                       { DAY         }
                       { DAY-OF-WEEK }
                       { TIME        }

Format 13

ACCEPT value FROM ENVIRONMENT-VALUE

Syntax Rules

Note: For Syntax Rules and General Rules specific to Formats 10, 11, and 12, see HP COBOL Conversions, in Transitioning to ACUCOBOL-GT.
  1. dest-item is a data item that receives the accepted data. It must be USAGE DISPLAY unless the WITH CONVERSION phrase is also used.

    If the Format 3 STANDARD OBJECT, THREAD HANDLE, or WINDOW HANDLE phrase is used, dest-item must be a USAGE HANDLE data item of the appropriate type. If the WINDOW HANDLE phrase is used, dest-item can also be a PIC X(10) item.

  2. screen-name is the name of a screen entry declared in the program's Screen Section. See Screen Section for more information.
  3. screen-loc is a numeric literal or data item containing either 4 or 6 digits. It may also be a group item of 4 or 6 characters. If a numeric item is used, it must be a non-negative integer.
  4. In Format 7, the AT, LINE, COLUMN, CLINE, and CCOL phrases may be used only if the CONTROL phrase is also used.
  5. line-num, col-num, cline-num, and col-num are numeric data items or literals. Note that they may be non-integer, unless the value is in pixels.
  6. length, color-val, curs-offset, timeout, and scrl-num are numeric literals or data items. They must specify non-negative integers. You may also specify the value of line-num, col-num, length, and color-val with an arithmetic expression.
  7. fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. They may not be subscripted or reference modified. See FOREGROUND-COLOR and BACKGROUND-COLOR Phrases, for a more detailed discussion of color settings and values.
  8. prompt-lit is a single-character alphanumeric literal or the figurative constant SPACE, ZERO, or QUOTE.
  9. Default is a literal or data item. It specifies the default entry value.
  10. Key-dest is a numeric data item. It receives the value of the key that terminated input.
  11. thread-1 is a USAGE HANDLE or HANDLE OF THREAD data item.
  12. statement-1 and statement-2 are any imperative statements.
  13. condition-1 is any conditional expression.
  14. cntrl-string and env-name are nonnumeric literals or data items.
  15. mnemonic-name must be a user-defined word declared in Special-Names that refers to a display device, or it must be the name of the display device itself. See Special-Names Paragraph for a list of valid devices.
  16. object-name must be an alphanumeric literal or data item.
  17. control-handle must be USAGE HANDLE. If control-handle is a typed handle, it must be associated with a control. It should hold a handle returned by a DISPLAY Control-Type (Format 14) statement.
  18. value can be any data item. It receives the current value of the control when the ACCEPT statement terminates.
  19. code-dest is a numeric data item.
  20. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  21. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  22. The CURSOR phrase may not be specified if a CURSOR phrase is specified in the program's Configuration Section.
  23. AUTO, AUTO-SKIP, and AUTOTERMINATE are equivalent.
  24. NO-ECHO, NO ECHO, OFF, and SECURE are equivalent.
  25. BLANK and ERASE are equivalent.
  26. BOLD, HIGH, and HIGHLIGHT are equivalent.
  27. LOWLIGHT and LOW are equivalent.
  28. COLUMN, COL, POSITION, and POS are equivalent.
  29. BELL and BEEP are equivalent.
  30. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  31. BLINK and BLINKING are equivalent.
  32. UNDERLINE and UNDERLINED are equivalent.
  33. CONVERSION and CONVERT are equivalent.
  34. REQUIRED and EMPTY-CHECK are equivalent.
  35. FULL and LENGTH-CHECK are equivalent.
  36. EXCEPTION and ESCAPE are equivalent.
  37. If the OMITTED option is used, then none of the following phrases may be specified: SIZE, JUSTIFIED, CONVERT, NO ECHO, PROMPT, DEFAULT, ECHO, UPPER, LOWER, REQUIRED, FULL, ZERO-FILL, NUMERIC-FILL or any of the attribute setting phrases (such as COLOR or REVERSE).
  38. The ERASE phrase has two forms. In VAX COBOL and ICOBOL compatibility modes, the ERASE LINE/SCREEN form must be used. In RM/COBOL mode, the ERASE EOS/EOL form must be used. This is indicated in the General Format by the symbols (VAX, ICOBOL) and .
  39. A NOT AT END phrase may not be paired with an ON EXCEPTION phrase, nor may a NOT ON EXCEPTION phrase be paired with an AT END phrase.
  40. In a Format 6 ACCEPT statement, if you omit the FROM phrase, you must use the -Ca compile-time option. Otherwise, the compiler treats the statement as a Format 1 ACCEPT instead.
  41. If the CONTROL KEY phrase is used, the key-dest option of the ON EXCEPTION phrase may not be specified.
  42. You may add FROM CRT to a Format 1 ACCEPT statement to distinguish it from a Format 6 ACCEPT statement. You need to do this only if you use the -Ca compile-time option.
  43. external-form-item is an input record for an HTML form when used in a Common Gateway Interface (CGI) program. It is a group data item (declared with the IS EXTERNAL-FORM clause) that has one or more elementary items associated with CGI variables. The association is made with the IS IDENTIFIED BY clause in the description of the elementary item(s).

    External-form-item may also be an output record for an HTML form. In this case, the group item is declared with both the IS EXTERNAL-FORM and IDENTIFIED BY clauses.

    See the IS EXTERNAL-FORM clause for more information about declaring external forms.

  44. For Format 13, value is a Working-Storage data item of the type needed to receive the value of the environment or configuration value stored in ENVIRONMENT-NAME (see DISPLAY Format 17).

General Rules Format 1 (ACCEPT dest-item)

  1. The ACCEPT statement accepts data typed by the user. The data accepted is placed in dest-item. If the OMITTED option is used instead of dest-item, then the user is required to enter a termination key, and no data is transmitted to the program. This can be used if you want to enter a function key only and do not need any other data from the user.
  2. The precise action of the ACCEPT statement depends both on the various clauses specified and the compatibility mode that the compiler is using. The compiler is run in RM/COBOL, VAX COBOL, or ICOBOL compatibility mode.
  3. Use of the AUTO phrase causes a field to terminate as soon as it is filled with data--this is the default mode in RM COBOL. Use of the TAB phrase forces the user to finish with a termination key--this is the standard mode except for RM COBOL.

    The effects of the CURSOR, CONTROL KEY, BEFORE TIME, ALLOWING MESSAGES, ON EXCEPTION, and AT END clauses are described below. The effects of the remaining optional clauses are described in section Common Screen Options.

CURSOR Phrase
  1. The CURSOR phrase specifies the initial cursor offset from the beginning of the field. The leftmost position of the ACCEPT field is offset one. If the CURSOR phrase is omitted or zero, then an offset of one is used.
  2. The offset specified is reduced as needed to keep the cursor in the bounds of the field. Also, the offset is reduced to keep the cursor within the data contained in the field. This means that an offset of one will always be used if the DEFAULT (or UPDATE) phrase is not used.
  3. If curs-offset is a numeric data item, then the ending cursor offset will be assigned to it when the ACCEPT statement terminates. This can be used to find the current cursor location (field column + curs-offset - 1).
  4. If a CURSOR clause is specified in the program's Configuration Section, then that clause is used to determine the cursor's initial offset. See Special-Names Paragraph for details.
CONTROL KEY Phrase
  1. The CONTROL KEY clause allows for the entry of special keys and the recording of which key terminated input. When the CONTROL KEY clause is specified, all of the special keys named in the following table can be used.
  2. key-dest is a numeric item that receives the value of the key that terminated input. The keys allowed by the CONTROL KEY phrase and their returned values are:
    Key | Value | Key | Value
    Enter/Return | 13 | F-13 | 13*
    Tab | 9 | F-14 | 14*
    F-1 | 1* | F-15 | 15*
    F-2 | 2* | F-16 | 16*
    F-3 | 3* | F-17 | 17*
    F-4 | 4* | F-18 | 18*
    F-5 | 5* | F-19 | 19*
    F-6 | 6* | F-20 | 20*
    F-7 | 7* | Do (Command) | 40*
    F-8 | 8* | Up Arrow | 52*
    F-9 | 9* | Down Arrow | 53*
    F-10 | 10* | Page Up | 67*
    F-11 | 11* | Page Down | 68*
    F-12 | 12* | Help | 90*

    Control keys may also be used. They return their underlying ASCII value (for example, Control-B returns the value 2). If a field is entered in AUTO mode and the ACCEPT terminates because the field was filled with data, then key-dest receives the value zero. If the BEFORE TIME phrase is specified and a time-out occurs, then key-dest receives the value 99.

  3. The keys marked with "*" are exception keys. These keys may be used only if a CONTROL KEY or ON EXCEPTION phrase is specified for the ACCEPT statement (alternately, the -Vx compile-time option can be used). If these keys are not allowed, then the runtime system will ignore them when they are typed. Note that if you use the -Ve compile-time option to disable the ON EXCEPTION phrase for exception keys, then using the ON EXCEPTION phrase will not enable exception keys. (See also rule number 2 under ALLOWING MESSAGES Phrase.)
  4. By using the -Ve compile-time option, you can cause ACUCOBOL-GT to return numeric conversion errors to the program. If you use this option to enable program handling of conversion errors, then key-dest will be assigned the value 98 whenever a conversion error occurs. See CHECK-NUMBERS for more information.
  5. For compatibility with programs written under other systems, the values returned by these keys may be changed at runtime. Also, other keys may be added or removed from this table. See Redefining the Keyboard for details on how to do this.
BEFORE TIME Phrase
  1. The BEFORE TIME phrase allows you to automatically terminate an ACCEPT statement after a certain amount of time has passed. The timeout value specifies the time to wait in hundredths of a second. For example, BEFORE TIME 500 specifies a timer value of 5 seconds.
  2. The user must enter data to the ACCEPT statement before the timer elapses. As soon as the user starts entering data, the timer is canceled and the user may take as much time as desired to complete the entry. If the user does not enter any data before the timer elapses, then the ACCEPT statement terminates and returns a value exactly as if the user had typed the "enter" key. An exception condition is then raised and the exception key value is set to 99.
  3. The precise amount of time waited can vary significantly from machine to machine. Factors involved include the rate of the system clock and the current load on the machine. For example, some UNIX systems update the system clock only once every second. The ACUCOBOL-GT runtime system takes the specified value and rounds it up to a whole number of ticks of the system clock. It then calls the system's alarm mechanism to interrupt the ACCEPT after this many ticks have elapsed. Different operating systems will handle this interrupt with varying degrees of accuracy. You should think of the timeout value as only an approximate one.
    Note: If you want to program a task that executes at a regular interval, such as updating an on-screen clock, it is best to program the task in a separate thread (as opposed to timing out all of your ACCEPT statements). The periodic task would be placed inside a loop in a separate thread. The task would sleep for some period, wake and perform the update, and then loop back to the sleep state. This approach allows the runtime's thread manager to schedule the update, and ensures that no input, such as a mouse click, is missed when the update takes place. For more about threads, see Multiple Execution Threads.
ALLOWING MESSAGES Phrase
  1. The ALLOWING MESSAGES phrase causes the ACCEPT statement to terminate when a message is sent from the appropriate thread, as follows:
    1. The THREAD thread-1 option allows messages from the thread identified by thread-1.
    2. The LAST THREAD option allows for messages from the "last" thread. See Thread Fundamentals for a discussion of the last thread.
    3. The ANY THREAD option allows messages from any thread.
  2. If an allowed message is available when the ACCEPT begins, or one arrives while the ACCEPT is active, the ACCEPT terminates with an exception value of 95. The exception occurs even if exceptions are not otherwise allowed in the ACCEPT.
  3. When an ACCEPT terminates due to a message, the target data item is not updated with the data entered by the user up to that point. This affects the following cases:
    1. In Format 1, dest-item is not updated.
    2. In Format 2, any VALUE, USING, or TO data items in the Screen Section are not updated.
    3. In Format 7, value is not updated.
    Note: Testing of the data item is not performed (such as the REQUIRED phrase). Essentially, you get the termination status, but no other information. This allows you to share a data item between two controls. When the user changes one of them, it can send a message to the other to have that control update its appearance. If this rule was not in place, the message would terminate any ACCEPT on that control, and that control's current contents would overwrite the correct data in the shared data item. If you need to determine the current value of a control in response to a message, you can INQUIRE the control's value directly.
  4. An ACCEPT statement that is suspended (because another thread has an active ACCEPT) terminates when an allowed message arrives.
  5. If the ALLOWING MESSAGES phrase is omitted, messages will not terminate the ACCEPT. Instead, they are queued as normal.
ON EXCEPTION Phrase
Note: The -Ve compiler option alters the rules that determine which conditions cause an ON EXCEPTION phrase to receive control in a Format 1 ACCEPT statement. See Video Options for more information.
  1. When this phrase is used, statement-1 is executed when an exception condition occurs. An exception condition occurs under the following circumstances:
    1. An end-of-file condition occurs on the console.
    2. A BEFORE TIME phrase was specified and the ACCEPT statement timed out.
    3. An exception key was used to terminate input. This may be disabled with the -Ve compile-time option.
    4. A conversion error occurred when numeric data was entered with the CONVERSION phrase. You must use the -Ve compile-time option to enable program handling of conversion errors for this exception condition to be used. Normally, the ACUCOBOL-GT runtime system does not allow invalid numeric data to be entered.
    5. A message terminates the ACCEPT.
    6. An event terminates the ACCEPT.
    7. the screen contains no input fields, or all input fields are protected or disabled.
  2. key-dest, if specified, causes this phrase to have all of the effects of the CONTROL KEY phrase in addition to its normal effects. See the CONTROL KEY phrase above for details. If you specify key-dest, then exception keys will cause statement-1 to execute even if you have used the -Ve compile-time option to turn off handling of exception keys by the ON EXCEPTION phrase.
  3. If you specify an ON EXCEPTION phrase, then exception keys will be allowed for the ACCEPT statement. Otherwise exception keys will be disabled unless you use the CONTROL KEY phrase or the -Vx compile-time option. However, if you use the -Ve compile-time option to disable exception key handling, then an ON EXCEPTION phrase will not enable exception keys unless the key-dest option is also used.
  4. If the NEXT SENTENCE option is used, then control will pass to the next executable sentence when an exception condition exists. Note that the ANSI standard states that NEXT SENTENCE is an archaic feature and its use should be avoided.
  5. If the NOT ON EXCEPTION phrase is specified, then statement-2 executes if no exception condition exists.
  6. The ON EXCEPTION phrase may not be specified if the AT END phrase is used. The key-dest option may not be used if the CONTROL KEY phrase is specified.
AT END Phrase
  1. The AT END phrase causes the following statement-1 to execute if an end-of-file occurs during the ACCEPT.
  2. If NEXT SENTENCE is specified instead of statement-1, control passes to the next executable sentence if an end-of-file occurs. Note that the ANSI standard states that NEXT SENTENCE is an archaic feature and its use should be avoided.
  3. If the NOT AT END phrase is used, then statement-2 executes if an end-of-file does not occur during the ACCEPT.
  4. By default, ACUCOBOL-GT does not have a method of generating end-of-file conditions from a terminal. The runtime system can be reconfigured, however, to generate an end-of-file for selected keys. See Redefining the Keyboard for more information.
  5. The AT END phrase may not be specified when the ON EXCEPTION phrase is.

Format 2 (ACCEPT screen-name)

  1. This is a form level ACCEPT. A Format 2 ACCEPT statement allows the user to enter data into all of the input and update fields (as well as every control that can be activated) contained in screen-name. screen-name must be a screen item declared in the program's Screen Section. After the user finishes, each input and update field is moved to its corresponding data item. See Screen Section for a complete description of a screen item.
  2. The AT, LINE, and COLUMN phrases describe the starting location of the screen item. These phrases are described in detail in section Common Screen Options. If either the line or column number is missing or zero, then line or column number 1 is used.
  3. The BEFORE TIME phrase works in the same manner as described above for a Format 1 ACCEPT. If multiple input fields are being entered, then the timer is set only for the first field. As soon as the user starts entering data, as much time as desired may be taken to enter the screen.
  4. The ALLOWING MESSAGES phrase works in the same manner as described above for a Format 1 ACCEPT.
  5. If an exception condition occurs, the ON EXCEPTION phrase causes control to be transferred to statement-1. (Exception codes are stored in the variable named in SPECIAL-NAMES with the CRT STATUS phrase.) See rule number 1 under ON EXCEPTION phrase (above) for a list of the conditions that cause an exception. Exception keys are listed under the heading CONTROL KEY Phrase above. If an exception does not occur, and the NOT EXCEPTION phrase is specified, then statement-2 executes.
  6. Specifying the EXCEPTION phrase allows the user to terminate input with an exception key. Otherwise, exception keys are disabled unless the program is compiled with the -Vx option.
    Note: You can code Screen Section entries that reference embedded procedures or an event procedure for Format 2 ACCEPT statements. See PROCEDURE Clause for more information.

    You can also code a Special-Names entry that allows an embedded procedure to control an ACCEPT statement. See Special-Names Paragraph for more information.

  7. If condition-1 is specified, then the ACCEPT statement executes repeatedly until condition-1 evaluates true. The effect is exactly the same as coding:
    PERFORM, WITH TEST AFTER, UNTIL condition-1
         ACCEPT screen-name, accept options
END-PERFORM

    This can be convenient when you are retrieving data from a graphical screen. For example, you could use a statement like the following to get data from a dialog box until the user presses the box's OK button:

    ACCEPT screen-1, UNTIL ok-button-pressed

Format 3 (ACCEPT FROM)

  1. The Format 3 ACCEPT statement causes information to be transferred to dest-item according to the rules for the MOVE statement.
  2. The DATE option causes the current date to be moved to dest-item. The date is composed of the year of the century, the month of the year, and the day of the month. Each element occupies two digits. For example, December 25, 1998, would be expressed 981225. DATE is treated as if it were described by a PICTURE 9(6) clause.
  3. The DAY option causes the current date to be moved to dest-item. The format of the date is the year of the century (2 digits) followed by the day of the year (3 digits). For example, December 25, 1998, is 98359. DAY acts as if it were described by a PICTURE 9(5) clause.
  4. ACCEPT FROM CENTURY-DATE returns the current date in the format YYYYMMDD (year/month/day). ACCEPT FROM DATE YYYYMMDD is equivalent to ACCEPT FROM CENTURY-DATE. ACCEPT FROM CENTURY-DAY returns the current date in the format YYYYDDD (year/day-of-year). ACCEPT FROM DAY YYYYDDD is equivalent to ACCEPT FROM CENTURY-DAY. These are the same as ACCEPT FROM DATE and ACCEPT FROM DAY, except that the year field is 4 digits instead of 2 digits.

    The compiler option -Zy lets you treat ACCEPT FROM DATE as ACCEPT FROM CENTURY-DATE, and ACCEPT FROM DAY as ACCEPT FROM CENTURY-DAY. See Miscellaneous Options for more information.

  5. The TIME option causes the current time of day to be moved to dest-item. The format of the time is the hour (24hour clock), the minutes, the seconds and the hundredths of a second. Each element occupies two digits. For example, 2:41 PM would be expressed 14410000. TIME acts as if it were described by a PICTURE 9(8) clause.

    Generally speaking, older UNIX machines keep time only to the nearest second. Thus the hundredths portion of the value returned by ACCEPT FROM TIME is typically zero on UNIX machines. However, System V Release 4 and some other UNIX versions have an alternate method for determining the time with greater precision. The runtime system will use this alternate method if it is available, and then the hundredths portion will be filled in.

  6. The DAY-OF-WEEK option causes the current day of the week to be moved to dest-item. The format of this item is a single digit where 1 represents Monday, 2 represents Tuesday, up through 7 for Sunday. DAY-OF-WEEK acts as if it were described by a PICTURE 9 clause.
  7. The TERMINAL-INFO option causes information about the user's terminal to be moved to dest-item. This information is returned in the following format, as contained in the TERMINAL-ABILITIES group item defined in acucobol.def:
    01  TERMINAL-ABILITIES.
    03  TERMINAL-NAME                PIC X(10).
    03  FILLER                       PIC X.
        88  HAS-REVERSE              VALUE "Y".
    03  FILLER                       PIC X.
        88  HAS-BLINK                VALUE "Y".
    03  FILLER                       PIC X.
        88  HAS-UNDERLINE            VALUE "Y".
    03  FILLER                       PIC X.
        88  HAS-DUAL-INTENSITY       VALUE "Y".
    03  FILLER                       PIC X.
        88  HAS-132-COLUMN-MODE      VALUE "Y".
    03  FILLER                       PIC X.
        88  HAS-COLOR                VALUE "Y".
    03  FILLER                       PIC X.
        88  HAS-LINE-DRAWING         VALUE "Y".
    03  NUMBER-OF-SCREEN-LINES       PIC 9(3).
    03  NUMBER-OF-SCREEN-COLUMNS     PIC 9(3).
    03  FILLER                       PIC X.
        88  HAS-LOCAL-PRINTER        VALUE "Y".
    03  FILLER                       PIC X.
        88  HAS-VISIBLE-ATTRIBUTES   VALUE "Y".
    03  FILLER                       PIC X.
        88  HAS-GRAPHICAL-INTERFACE  VALUE "Y".
    03  USABLE-SCREEN-HEIGHT         PIC X(2) COMP-X.
    03  USABLE-SCREEN-WIDTH          PIC X(2) COMP-X.
    03  PHYSICAL-SCREEN-HEIGHT       PIC X(2) COMP-X.
    03  PHYSICAL-SCREEN-WIDTH        PIC X(2) COMP-X.
    03  FILLER                       PIC X.
        88  IS-REMOTE                VALUE "Y".
    03  CLIENT-MACHINE-NAME          PIC X(64).
    03  FILLER                       PIC X.
        88  ACU-NO-TERMINAL          VALUE "Y".
    03  CLIENT-USER-ID               PIC X(20).
    03  ATW-BROWSER-NAME             PIC X(30).
    03  ATW-BROWSER-VERSION          PIC X(10).
    03  ATW-ENGINE-NAME              PIC X(30).
    03  ATW-ENGINE-VERSION           PIC X(10).
    03  ATW-CLIENT-OS-NAME           PIC X(30).
    03  ATW-CLIENT-OS-VERSION        PIC X(10).
    03  ATW-CLIENT-DEVICE-TYPE       PIC X(30).
    03  ATW-CLIENT-DEVICE-VENDOR     PIC X(30).
    03  ATW-CLIENT-DEVICE-MODEL      PIC X(30).
    1. The TERMINAL-NAME field contains a short descriptive name of the terminal type being used (e.g., "vt100", "tvi925", "pc-color"). For the Windows runtime and thin client, the TERMINAL-NAME field contains the string "Windows". The number-of-lines and number-of-columns fields contain the number of lines and columns the screen contains in its current configuration. The remaining fields contain a Y if the user's terminal has the named feature and an N if it does not.
    2. The NUMBER-OF-SCREEN-LINES and NUMBER-OF-SCREEN-COLUMNS fields hold the number of whole lines and columns (respectively) in the current floating window. If no window has been created, these values are set to the size of the default application window.
    3. The HAS-VISIBLE-ATTRIBUTES field is set to Y if setting a video attribute on the terminal causes a character to be taken up on the screen. Terminals that behave in this fashion have additional restrictions over the terminals that have hidden attributes. For additional information on these restrictions, see Restricted Attribute Handling.
    4. The HAS-GRAPHICAL-INTERFACE item is set to TRUE (value "Y") if the runtime is using a graphical user interface. Otherwise, it is FALSE (value N). You can generally assume that graphical systems can support non-integer row/column positions and window/control sizes.
    5. Non-graphical (i.e., character-based) systems will truncate non-integer row and column positions, along with window and control sizes to the nearest integer that is smaller (e.g., line 1.5 will be treated as line 1).
    6. The USABLE-SCREEN-HEIGHT field holds the height of the usable portion of the user's display device in base units. This value represents character cells for character-based systems or pixels for graphical systems. On graphical systems, this value can be larger than the area used by your program (it is the largest area that a program could conceivably use). Under Windows 98, this value excludes the Taskbar if the user has set the Always on top Taskbar option. On character-based systems, this value is the size of the actual screen, or the current application window if you are running in a character-emulator such as the Windows console-mode (DOS box) or an X-term.
    7. USABLE-SCREEN-WIDTH is the same as USABLE-SCREEN-HEIGHT except that it returns the width instead of the height.
    8. PHYSICAL-SCREEN-HEIGHT is the same as USABLE-SCREEN-HEIGHT except that it includes the entire screen instead of just the usable portion of the screen. Under Windows 98, this is the actual screen resolution. Under character-based systems, this value is normally the same as USABLE-SCREEN-HEIGHT because most character-based systems do not provide a method for measuring the physical screen.
    9. PHYSICAL-SCREEN-WIDTH is the same as PHYSICAL-SCREEN-HEIGHT except that it returns the screen's width instead of the screen's height.
    10. IS-REMOTE is set to TRUE (value Y) if the program is running with the Thin Client. When IS-REMOTE is true: CLIENT-MACHINE-NAME is set to the name of the client that is running acuthin, plus a hyphen ("-") and the hex value of the client process ID. For example:
         techxp-2ef1

      CLIENT-USER-ID is set to the client-side login name of the current user. This is the name the user entered when logging in to the client that is running acuthin. If it is not set, acuthin looks for the environment variable USERNAME. If that is not set, then the literal "USER" is placed in the field.

    11. CLIENT-MACHINE-NAME provides the name of the client machine. When executing using Thin Client, the Process ID of the server runtime is appended to the client machine name in order to distinguish multiple instances of acuthin running against the same server.
    12. ACU-NO-TERMINAL is set to TRUE if the runtime was started with the -b option (-b inhibits terminal initialization and implies that no terminal is attached to the process). In this scenario, terminal I/O is undefined and should be avoided. When ACU-NO-TERMINAL is TRUE, other fields in TERMINAL-ABILITIES return their default value.
    13. The ATW- prefixed fields remain blank if you are not running through AcuToWeb.

    On many UNIX systems, the runtime can use ACCEPT FROM TERMINAL-INFO to determine the initial size of its window when it is running under the X Window system, Motif, OpenLook, or Sunview. It uses this information to set the number of rows and columns available to the program, and to scroll the screen correctly. The size found overrides the size specified in the a_termcap entry for the terminal. If you need to, you can override these settings with the LINES and COLUMNS environment variables.

  8. The SYSTEM-INFO option causes some general information about the runtime to be moved to dest-item. The information is returned in the following format (SYSTEM-INFORMATION is defined in acucobol.def):
    01  SYSTEM-INFORMATION.
    03  OPERATING-SYSTEM                PIC X(10).
        88  OS-IS-MSDOS                 VALUE "MS-DOS".
        88  OS-IS-OS2                   VALUE "OS/2".
        88  OS-IS-VMS                   VALUES "VMS",
                                               "VAX/VMS".
        88  OS-IS-UNIX                  VALUES "Unix",
                                               "Unix-V", "Unix-4",
                                               "UNOS".
        88  OS-IS-WINDOWS               VALUE "WINDOWS".
        88  OS-IS-WIN-NT                VALUE "WIN/NT".
        88  OS-IS-WIN-FAMILY            VALUES "WINDOWS",
                                               "WIN/NT".
   03  USER-ID                         PIC X(12).
    03  STATION-ID                      PIC X(12).
    03  FILLER                          PIC X.
        88  HAS-INDEXED-READ-PREVIOUS   VALUE "Y".
    03  FILLER                          PIC X.
        88  HAS-RELATIVE-READ-PREVIOUS  VALUE "Y".
    03  FILLER                          PIC X.
        88  CAN-TEST-INPUT-STATUS       VALUE "Y".
    03  FILLER                          PIC X.
        88  IS-MULTI-TASKING            VALUE "Y".
    03  RUNTIME-VERSION.
        88  VERSION-PRIOR-TO-2-2        VALUE SPACES.
        05  RUNTIME-MAJOR-VERSION       PIC 99.
        05  RUNTIME-MINOR-VERSION       PIC 99.
        05  RUNTIME-RELEASE             PIC 99.
    03  FILLER                          PIC X.
        88  IS-PLUGIN                   VALUE "Y".
    03  SERIAL-NUMBER                   PIC X(20).
    03  FILLER                          PIC X.
        88  HAS-LARGE-FILE-SUPPORT      VALUE "Y".
    03  FILLER                          PIC X.
        88  HAS-BIS-SUPPORT             VALUE "Y".
    03  FILLER                          PIC X.
        88  IS-64-BIT                   VALUE "Y".
    1. The OPERATING-SYSTEM field returns information about the operating system the runtime is ported to. It may contain one of the following values:
      Value | Host System
      Unix | Any version of Unix
      VMS | VMS or OpenVMS
      WINDOWS | Microsoft Windows 98
      WIN/NT | Microsoft Windows NT 4.0, or Windows 2000

      These values are intended to give the program fundamental information about the runtime.

      Note: The sample copy library acucobol.def includes some useful level 88 descriptions of operating system labels. For example, OS-IS-UNIX covers all UNIX platforms. For a complete list, see acucobol.defin the samples directory of your ACUCOBOL-GT installation.
    2. The USER-ID field is filled in with the login name of the current user. If it is not set, the runtime looks for the symbol . If it is not set, the literal USER is placed in this field.
    3. The STATION-ID field is filled in with the station name of the video terminal attached to the executing program. For UNIX systems, the initial /dev/ is removed from the name first.

      On Windows machines, the value of the symbol STATIONwill be returned if it is set in the host environment. If it is not set, then the literal "CON" will be placed in this field.

      If the program is displaying on a thin client, STATION-ID is filled with "at<pid>" where pid is the process ID of the runtime running on the server.

    4. The HAS-INDEXED-READ-PREVIOUS field is Y if the READ PREVIOUS and START LESS THAN verbs are available for indexed files on the host system. If these verbs are not available, this field is set to N. If more than one indexed file system is being used, then this field is set to Y only if all of the file systems support READ PREVIOUS.
    5. The HAS-RELATIVE-READ-PREVIOUS field is Y if the READ PREVIOUS and START LESS THAN verbs are available for relative files on the host system. If these verbs are not available, this field is set to N.
    6. The CAN-TEST-INPUT-STATUS field is Y if the ACCEPT FROM INPUT STATUS verb is available on the host system. If not, it is set to N. Most machines can use this verb, but a few cannot. On these machines, executing this verb will return a constant value that you can pre-select with a configuration file option. There is a runtime configuration variable called SCRIPT_STATUS that controls the behavior of ACCEPT FROM INPUT STATUS when the input is not attached to a terminal.
    7. The IS-MULTI-TASKING field is Y if the host system can run multiple tasks at once and has record locking facilities installed. This can be used to determine whether or not multiple copies of the runtime system can be run with correct file handling.
    8. RUNTIME-VERSION fields are filled in with numbers that identify the major version number, minor version number, and release number. For example, ACUCOBOL-GT Version 3.2.0 would return 03 as the major version, 02 as the minor version, and 00 as the release number.
    9. The IS-PLUGIN field is Y if the runtime is the Web Runtime running within a Web browser. Otherwise, it is set to N. See A Programmer's Guide to the Internet for more information about the Web Runtime.
    10. The SERIAL-NUMBER field is filled with the serial number of the runtime.
    11. The HAS-LARGE-FILE-SUPPORT field is Y if the UNIX port in question has extended support for large sequential and relative files. Otherwise, it is set to N.
    12. The IS-64-BIT field is Y if the runtime is 64-bit; otherwise, the runtime is 32-bit.
  9. The INPUT STATUS form of the ACCEPT statement returns a value that indicates whether or not there is data currently available from the standard input. Normally, when an ACCEPT statement executes, the program pauses until the user types in some data. The INPUT STATUS option can be used to test to see if the user has entered some data before executing an ACCEPT.

    This can be useful in a loop that constantly updates information while still allowing for user input.

    The INPUT STATUS option causes this information to be moved to dest-item. It is treated as if the source item were described as PICTURE 9(1). The value is 1 if input is currently available, 0 if not.

    If the input is being redirected, by default the value returned is zero. You can control this with the configuration variables INPUT_STATUS_DEFAULT and SCRIPT_STATUS.

    A small number of hardware platforms do not have the ability to test for pending input. On these machines, this verb returns a constant value. By default, this value is zero, but it may be set to another value via the configuration variable INPUT_STATUS_DEFAULT.

    Note: Another method of waiting for input while performing another operation is to use threads. A separate thread is used to perform the regular ACCEPT (for example), while the original thread performs the ongoing operation. See Multiple Execution Threads for more information.

    When you use the INPUT STATUS phrase of the ACCEPT verb with controls, and especially with ActiveX controls, the results may be undefined. A much better way of handling detection of user input in programs using controls is to employ event procedures or a separate thread for that purpose.

  10. The ESCAPE option of the ACCEPT statement returns the termination key value of the last Format 1 or Format 2 ACCEPT statement. These values are listed under the heading CONTROL KEY Phrase above. The value is treated as a COMP-1 data item that is moved to dest-item using the standard rules for a numeric move (exception: in ICOBOL compatibility mode, the value is treated as a PIC 99 data item).
  11. The ACCEPT FROM LINE NUMBER option returns a 3-digit number corresponding to the console device that is controlling the executing program. Because most of the machines that run ACUCOBOL-GT do not use device numbers, but use alphanumeric names instead, ACUCOBOL-GT computes the device number by the following procedure. First the device name is converted to upper case and hyphens are converted to underscores (on UNIX systems, the initial /dev/ is removed). This name is then searched for in the environment (including the configuration file). If it is found, then the value of the name is returned. This allows you to assign a customized value for each device. If the name is not found in the environment, then a number is formed from any digits found in the original device name (for example, tty15 would return as 15). If there are no digits in the device name, the value 0 is used.

    If the program is displaying on a thin client, ACCEPT FROM LINE NUMBER returns the last three digits of the process ID of the runtime running on the server.

  12. The ACCEPT FROM COMMAND-LINE option causes the contents of the original command line to be moved to dest-item. Only those elements of the command line that appear after the program name are returned. No parsing is done; you must parse the command line into separate arguments yourself.

    On Windows machines, the command line is limited to 1024 characters. The command line remains unchanged regardless of the actions of any CHAIN, CALL PROGRAM, or CALL RUN verbs (which all start new run units).

    For an alternate method in which the runtime system parses the arguments for you, see the CHAIN Statement.

    To change the contents of the command-line buffer, see the DISPLAY UPON COMMAND-LINE statement (Format 8) in this topic. You can also access the command-line buffer from a C program. The buffer is an external data array named Acmd_line.

  13. The STANDARD OBJECT option returns a handle to one of the system's pre-defined resources. The resource returned depends on the value of object-name, as described in the following table:
    Object-Name | Resource
    FIXED-FONT | The host system's default fixed-size font. This is the default font used for textual displays. Under Microsoft Windows, this font is Windows' SYSTEM-FIXED-FONT.
    TRADITIONAL-FONT | Also a fixed-size font. This font uses the standard character set associated with the host hardware (as opposed to the host graphical system). On many systems, this font is the same as FIXED-FONT. Under Microsoft Windows, this font is Windows' OEM-FIXED-FONT and uses the "OEM" character set instead of the ANSI character set.
    DEFAULT-FONT | This is the default font used by controls. On a graphical system, this font is usually a proportional font, and usually the same as SMALL-FONT. On non-graphical systems, this is the same as the FIXED-FONT. You can specify the default font with the DEFAULT_FONT configuration variable. See DEFAULT_FONT for more information.
    LARGE-FONT | A moderately large font that is appropriate for controls. On graphical systems, this is a proportionally spaced font. Under Microsoft Windows, this is Windows' SYSTEM-FONT. On non-graphical systems, this is the same as FIXED-FONT. On some systems, this is the same as MEDIUM-FONT.
    MEDIUM-FONT | An average size font that is appropriate for controls. On graphical systems, this is a proportionally spaced font. Under Microsoft Windows, this font is a boldface version of Windows' ANSI-VAR-FONT. On non-graphical systems, this is the same as FIXED-FONT.
    SMALL-FONT | A small font that is appropriate for controls. On graphical systems, this is a proportionally spaced font. Under Microsoft Windows, this font is Windows' ANSI-VAR-FONT. On non-graphical systems, this is the same as FIXED-FONT. On some systems, this is the same as MEDIUM-FONT.
    LM-RESIZE | A standard layout manager that assists in moving or resizing controls when a window changes size. See Layout Managers for more information.

    You may use either upper-case or lower-case values in object-name. If object-name does not match any of the allowed values, dest-item is set to NULL.

  14. The ACCEPT FROM THREAD statement moves the thread ID of the executing thread to dest-item.
  15. The WINDOW HANDLE option causes dest-item to receive the handle of the initial or current floating window. Note that this is the only way to get the handle of the default main application window. You do this by performing an ACCEPT FROM WINDOW HANDLE prior to creating any floating windows in your application.

Format 4 (ACCEPT SCREEN)

  1. The ACCEPT FROM SCREEN verb returns data present on the user's terminal. This differs from the Format 1 ACCEPT statement in that the user does not enter the data. Instead, the data is what is already present on the screen. This can be used to obtain an image of the user's current screen. Note however that screen attributes such as underlines and reverse colors are not returned.

    On graphical systems, this verb does not return any information contained in controls. To determine the current value of a control, use the INQUIRE verb.

  2. dest-item must specify an alphanumeric data item without the JUSTIFIED phrase. It is filled with the returned screen contents. dest-item is space-filled on the right if it is larger than the returned screen contents.
  3. The LINE phrase specifies the screen line to use for the ACCEPT. Line one refers to the top line of the current window. If the LINE phrase is missing or line-num is zero, the current cursor line is used.
  4. The COLUMN phrase specifies the screen column to use. Column one refers to the leftmost column of the current window. If the COLUMN phrase is missing or zero, then the column depends on the following:
    1. If the LINE phrase is used (and is not zero), then column one is used.
    2. Otherwise, the current cursor column is used.
  5. The SIZE phrase specifies the number of screen positions to return. If the SIZE phrase is missing, then the size of dest-item is used. If the SIZE phrase specifies fewer characters than the size of dest-item, then dest-item is space-filled on the right.
  6. The ACCEPT FROM SCREEN verb does not change the cursor position or modify the screen in any way. A single ACCEPT FROM SCREEN can "wrap around" the right edge of the window to return characters from multiple screen lines.
  7. Except as specified in the following rule, all characters on the terminal screen are returned using the underlying representation of the character in the native character set. This is usually the ASCII value of the character.
  8. The ACUCOBOL-GT Terminal Manager returns consistent values for certain special characters, regardless of the hardware being used. This is done for certain characters used by the Terminal Manager that do not have an ASCII representation. These special characters are the following:
    Character | Value
    Unknown | 1
    Horizontal Line | 2
    Vertical Line | 3
    Upper Left Corner | 4
    Upper Right Corner | 5
    Lower Left Corner | 6
    Lower Right Corner | 7
    "Tee" Up | 8
    "Tee" Right | 9
    "Tee" Down | 10
    "Tee" Left | 11
    4-Way Intersection | 12
    Bottom Endpoint | 13
    Left Endpoint | 14
    Top Endpoint | 15
    Right Endpoint | 16
    Visible Attribute | 17

    The "Unknown" value is returned for any screen position that cannot be determined by ACUCOBOL-GT. The "Visible Attribute" character is used by certain types of terminals when they are displaying video attributes. On these types of terminals, video attributes take up screen positions. They usually appear as spaces on the screen. The remaining special characters are various line segments used by the DISPLAY WINDOW, DISPLAY LINE, and DISPLAY BOX verbs.

  9. It is often desirable to translate the special case characters into ASCII values. You can do this easily with the INSPECT CONVERTING verb. For example, the following statement converts the line-drawing characters into hyphens, vertical bars, and plus signs, and translates the "unknown" and "visible attribute" characters into spaces:
    INSPECT ... CONVERTING
        X'0102030405060708090A0B0C0D0E0F1011'
    TO " -|+++++++++|-|- "

Format 5 (ACCEPT ENVIRONMENT)

  1. A Format 5 ACCEPT statement returns values from the user's environment or the ACUCOBOL-GT runtime system's configuration settings. env-name is the name of the environment setting whose value is to be returned. If you provide the literal name of this item (such as CURSOR-MODE), you must enclose it in quotes. The value returned from this item is moved to dest-item.
  2. This verb will search for env-name in the following places:
    1. First, the runtime system sees if env-name matches any of its configuration variables. If it does, the configuration variable's current setting is moved to dest-item. Not all configuration variables can be returned by the ACCEPT verb, because some of them have multiple settings.
    2. Next, env-name is searched for in the runtime system's local environment. This environment consists of all of the entries in the ACUCOBOL-GT configuration file plus any entries made with the SET ENVIRONMENT verb. This excludes the runtime system's configuration variables that are covered in rule (a) above. Note that any entry in the ACUCOBOL-GT configuration file that is also in the user's host environment has its initial value set the same as the entry in the user's environment.
    3. Finally, on machines that have a user-maintained environment, that environment is searched for env-name. A description of the user's environment for each machine is given in section Supported Hardware of the ACUCOBOL-GT User's Guide.

      When the runtime system searches for env-name, only the first 30 characters are used. Also, any lower-case characters in env-name are treated as upper-case, and any hyphens are treated as underscores. If the truncated name is not found, the runtime searches again, this time looking for env_name exactly as specified.

  3. If an entry is found, then its value is moved to dest-item. For numeric configuration variables, the source item is treated as if it were a COMP-1 data item. For all other entries, the source item is treated as an alphanumeric data item. The value is moved to dest-item according to the rules for the MOVE statement. Note that if the source item is numeric, then dest-item may be defined either as a numeric field or as an alphanumeric field of five or more characters. If dest-item is alphanumeric and is larger than five characters, the value that is returned will occupy the leftmost five characters of dest-item.
  4. If no matching entry is found, or if the env-name is the name of a configuration variable whose value cannot be returned, spaces are moved to dest-item and statement-1, if specified, is executed.
  5. If a legal matching entry is found, then statement-2 (if specified) is executed.

Format 6 (ANSI ACCEPT)

  1. A Format 6 ACCEPT statement reads a line of input from the standard input device (usually the user's console). This data is then moved into dest-item. If the data is longer than the size of dest-item, it is truncated on the right. If it is smaller, then it is space-filled on the right.
  2. Prior to reading the line, the runtime system places the user's terminal into the state it normally occupies when it is used by the operating system. The runtime then requests the input from the operating system. The operating system usually provides some form of input editing, such as backspacing. The exact editing available depends on the host operating system.
  3. Technical Note: Because this verb requests input directly from the operating system, ACUCOBOL-GT's Terminal Manager is not aware of the changes that are occurring to the screen. This can cause problems if you mix ANSI-style and ACUCOBOL-GT-style ACCEPT and DISPLAY verbs in the same program. On many machines, ACUCOBOL-GT's Terminal Manager maintains an image of the user's screen. (This improves efficiency by removing redundant screen output and is also used to implement pop-up windows.) Bypassing the Terminal Manager can cause the Terminal Manager's screen image to become incorrect. This can cause strange effects when it is mixed with an ACUCOBOL-GT-style ACCEPT or DISPLAY verb, including:
    • lost data
    • incorrect functioning of CLOSE WINDOW
    • incorrect cursor position
    • incorrect character attributes
    • incorrect display in debugger

    For these reasons, you must be careful when using ANSI ACCEPT. Here are some useful guidelines:

    1. If your statement does not affect the screen image, then it can be used safely. For example, sending a control sequence to an attached cash register is safe.
    2. If you use only ANSI-style ACCEPT and DISPLAY verbs, then you should not experience any problems except that the debugger will not be able to show the user's screen.
    3. If you must mix formats, then you can use the library routine W$FORGET to correct the behavior of the Terminal Manager. This routine causes the Terminal Manager to enter its initial state. It will assume that it does not know the screen image or current attribute settings. Calling this routine after a series of ANSI-style ACCEPT or DISPLAY verbs will place the Terminal Manager into a state where it can operate correctly.
    4. You can safely use the verb if your ANSI-style ACCEPT or DISPLAY sends data to a device other than the user's console, such as the standard error file.
      Note: When you are running a 32-bit Windows CGI program with the -f option or with the A_CGI environment variable set, the runtime reads only the number of bytes specified by the web server in the CONTENT_LENGTH environment variable. The runtime does not wait for an end of file condition. If you are running without the -f option and have not set the A_CGI environment variable, then the runtime reads until an end of file condition occurs. Note that some web servers such as Microsoft Internet Information Server 4.0 do not terminate input to a CGI program with an end of file condition. Instead, they rely upon the CGI program to read exactly the number of bytes specified in the CONTENT_LENGTH variable. When running an ANSI ACCEPT style CGI program using these web servers, you must use the -f option or set the A_CGI environment variable.

Format 7 (ACCEPT control-handle)

  1. The ACCEPT Control-Handle statement activates the control identified by control-handle. The user interacts with the control until some terminating event occurs. The event that caused the termination is then stored in key-dest, and the control's current value is stored in value. The ACCEPT statement then terminates.
  2. If the CONTROL phrase is used, the runtime activates the control located at the screen position specified by the AT, LINE, and COLUMN phrases in the current window (on non-graphical systems, the CLINE and CCOL phrases also apply). The runtime maintains a list of controls in each window. When attempting to activate a control at a specific location, the runtime searches this list, using the first control it finds that exactly matches the given location. The list is maintained in order in which the controls are created. If the runtime does not find a control at the specified location, it returns an exception value of 96 (the same as doing an ACCEPT of a invalid control handle).

    The following example creates an anonymous entry field and then ACCEPTs it, using its screen position.

    DISPLAY ENTRY-FIELD, LINE 2, COL 5, SIZE 15.
ACCEPT CONTROL, VALUE MY-DATA, LINE 2, COL 5.
  3. key-dest names a data item that will receive a code indicating the terminating event. The program's CRT STATUS (if any) also receives the termination code.
  4. When the ACCEPT statement terminates, the current value of the control is moved to value in accordance with the rules for the MOVE statement. The type of control determines the source format of the value.
  5. The BEFORE TIME phrase operates in the same manner as it does in a Format 1 ACCEPT statement.
  6. The WITH BELL phrase causes the station's bell to sound when the control is initially activated.
  7. The ALLOWING MESSAGES phrase works in the same manner as described above for a Format 1 ACCEPT.
  8. The ACCEPT statement can terminate in several different ways. These ways are classified as either normal terminations or as exceptions. If an exception caused the termination, then statement-1 is executed. Otherwise, statement-2 is executed. If you do not specify the ON EXCEPTION phrase, then the ACCEPT statement ignores exception keys (function keys). You can override this behavior with the -Vx compile-time option.

    If you attempt to ACCEPT a disabled or otherwise invalid control, or if the active control is hidden during the ACCEPT either by an event procedure or by code running in a different thread, the ACCEPT will immediately terminate, returning a CRT STATUS value of 97. For a Screen Section ACCEPT, this will occur only if all of the referenced controls are disabled.

  9. You may also activate a control with a Format 2 ACCEPT statement (a Screen Section ACCEPT). If the referenced Screen Section entry defines any controls, they are activated as appropriate.

Format 8 (ACCEPT external-form-item)

  1. The external form of Format 8 is called an output form if the IDENTIFIED BY clause is used to associate it with an HTML template file. If the IDENTIFIED BY clause is omitted, it is called an input form.

    For example, the following is an input form:

    01  CGI-FORM IS EXTERNAL-FORM.
    03  CGI-VAR1  PIC X(10).
    03  CGI-VAR2  PIC X(10).

    and this is an output form:

    01  HTML-FORM IS EXTERNAL-FORM IDENTIFIED BY
    "tmplate1".
    03  HTML-VAR1  PIC X(10).
    03  HTML-VAR2  PIC X(10).
  2. The ACCEPT verb treats input and output forms the same. ACCEPT sets the value of each elementary item, in order, to the value of its associated CGI variable, padding with trailing spaces. ACCEPT automatically decodes and translates the CGI input data before moving it to the elementary items of external-form-item. The value of each CGI variable is converted to the appropriate COBOL data type when it is moved to the external form.

    CGI variable names are case-sensitive. However, for convenience, if ACCEPT cannot identify a CGI variable, it will repeat the search for the variable ignoring the case.

  3. If the CGI variable is empty or does not exist, ACCEPT sets the value of numeric data items to zero and nonnumeric data items to spaces. This behavior is configurable. If you do not want ACCEPT to clear the value of the data item when its CGI variable does not exist in the CGI input data, set the CGI_CLEAR_MISSING_VALUES configuration variable to 0 (off, false, no). See the entry for CGI_CLEAR_MISSING_VALUES for details.
  4. If the CGI variable is repeated in the CGI input data (as it would be in the case where multiple items have been selected from a choose-many list), the external form item that is identified with the CGI variable must be in a table. Otherwise, only the first CGI value is moved to the external form item.

    For example:

    01  CGI-FORM IS EXTERNAL-FORM.
    03  CGI-TABLE    OCCURS 10 TIMES.
        05  CGI-VAR1   PIC X(10).
        05  CGI-VAR2   PIC X(10).
or
01  CGI-FORM     IS EXTERNAL-FORM.
    03  CGI-VAR1  PIC X(10) OCCURS 10 TIMES.
    03  CGI-VAR2  PIC X(10) OCCURS 10 TIMES.

    ACCEPT moves the values of the CGI variable to the items in the table. After all of the CGI values have been moved to items in the COBOL table, the remaining items in the table are set to 0 if they are numeric items, and set to spaces otherwise.

Format 9 (ACCEPT EVENT)

  1. The ACCEPT EVENT statement waits for a terminating event to occur. The event that caused the termination is stored in code-dest. The ACCEPT statement then terminates.
  2. code-dest names a data item that will receive a code indicating the terminating event. The program's CRT STATUS (if any) also receives the termination code.
  3. The BEFORE TIME phrase operates in the same manner as it does in a Format 1 ACCEPT statement.
  4. The ALLOWING MESSAGES phrase works in the same manner as described above for a Format 1 ACCEPT.
  5. ACCEPT EVENT is similar to ACCEPT OMITTED except that it does not display a default initial window and it does not detect keyboard termination or exception keys.
  6. The ACCEPT EVENT statement is designed for use in programs without a user interface. However, if the program has a user interface and interacting with it causes a terminating event to occur, ACCEPT EVENT will terminate. In the debugger, ACCEPT EVENT will terminate if the user presses the Enter key.
  7. The ACCEPT EVENT statement can terminate in several different ways. These ways are classified as either normal terminations or as exceptions. If an exception caused a termination, then statement-1 is executed. Otherwise, statement-2 is executed.
Code Example - Format 9

The following program uses the Microsoft Agent Control (ActiveX) to create a genie character and then directs it to speak Hello World. It does not have a visible initial window or a user interface that allows keyboard or mouse input.

identification division.
program-id.  no-ui.
environment division.
special-names.
copy "msagent.def".
                  .
data division.
working-storage section.

77  genie1-handle       usage handle of Agent.
77  request-handle      usage handle of IAgentCtlRequest.
77  request-status      pic 9.

procedure division.
Main-Logic.

   display initial window visible = 0.

   display Agent of AgentObjects handle in genie1-handle.

   modify genie1-handle
             Characters::Load("Genie1", "genie.acs").

   use genie1-handle Characters::Item("Genie1")

       modify ^LanguageID 1033
              ^Show()
              ^Speak "Hello World" giving request-handle

       perform until request-status = 1
           ACCEPT EVENT BEFORE TIME 1000
           inquire request-handle status in request-status
       end-perform

       destroy request-handle

       modify ^Hide()

   end-use.

   destroy genie1-handle.

   stop run.

Formats 10, 11, 12

See HP COBOL Conversions - jumpoff.

Format 13 (ACCEPT FROM ENVIRONMENT-VALUE)

  1. Use a Format 13 ACCEPT to fetch the value of an environment or configuration variable stored with a Format 17 DISPLAY statement (DISPLAY UPON ENVIRONMENT-NAME).
  2. The value data item should be of a size and type that will accommodate the value of the environment or configuration variable.
Parent topic: Procedure Division Statements


ADD Statement

The ADD statement performs arithmetic addition.

Format 1

ADD {num} ... TO { result [ROUNDED] } ...

   [ ON SIZE ERROR statement-1 ]

   [ NOT ON SIZE ERROR statement-2 ]

   [ END-ADD ]

Format 2

ADD {num} ... TO num GIVING { result [ROUNDED] } ...

   [ ON SIZE ERROR statement-1 ]

   [ NOT ON SIZE ERROR statement-2 ]

   [ END-ADD ]

Format 3

ADD {CORRESPONDING} group-item TO group-item [ROUNDED]
    {CORR         }

   [ ON SIZE ERROR statement-1 ]

   [ NOT ON SIZE ERROR statement-2 ]

   [ END-ADD ]

Format 4

ADD TABLE src-table TO dest-table [ROUNDED]

   [ FROM INDEX src-start TO src-end ]

   [ DESTINATION INDEX dest-start ]

   [ ON SIZE ERROR statement-1 ]

   [ NOT ON SIZE ERROR statement-2 ]

   [ END-ADD ]

Syntax Rules

  1. Num is a numeric literal or elementary numeric data item.
  2. Result is an elementary numeric data item or, in Format 2, an elementary numeric edited data item.
  3. group-item is a group item containing one or more elementary numeric data items.
  4. statement-1, and statement-2 are imperative statements.
  5. CORR is an abbreviation of CORRESPONDING.
  6. src-table and dest-table are numeric data items that are table elements. The low-order subscript of these items must be omitted. For example, if SRC-1 was an element of a one-dimensional table, then you would just use SRC-1 in the statement. If SRC-2 was an element of a two-dimensional table, and you wanted to add all the elements in row 2, you would use SRC-2( 2 ).
  7. src-start, src-end and dest-start are numeric literals or data items. These items may not be subscripted.

General Rules

  1. Note that pertinent additional information is located in the sections covering Arithmetic Operations (6.4.1), Multiple Receiving Fields (6.4.2), the ROUNDED Option (6.4.3), the SIZE ERROR Option (6.4.4), and the CORRESPONDING Option (6.4.5).
  2. In Format 1, all nums are added together and their sum is then added to each result in turn.
  3. In Format 2, all nums are added together and their sum is moved to each result field.
  4. In Format 3, each pair of corresponding elementary numeric items in the two group-items are added together. The results are moved to the corresponding items in the second group-item.
  5. In Format 4, a range of src-table elements is added to a range of dest-table elements. The results are stored in dest-table. The first element of the src-table range is added to the first element of the dest-table range, the second element to the second, and so on.
  6. src-end specifies the first element of the source range. If omitted, the value defaults to 1. src-end specifies the last element of the range (inclusive). If omitted, it is set to the current upper bound of the source table. In a multidimensional table, the range of elements varies over the innermost OCCURS.
  7. dest-start indicates the first element of the destination range. If omitted, it defaults to 1. Note that the last element of the destination range is dest-start + src-end -1.
  8. If the SIZE ERROR phrase is used, elements for which the size error condition occurs are not updated; other elements are updated. When an add results in a size error, statement-1 executes, otherwise statement-2 executes.
    Note: A Format 4 ADD TABLE statement is usually substantially faster than an equivalent PERFORM loop. The degree of improvement depends on the size of the range (larger ranges show better improvement). The SIZE ERROR and ROUNDED phrases typically add significant overhead. The runtime always performs table boundary checking in ADD TABLE, even if the program is not compiled with -Za.

Code Example Format 4

The following definitions will be used in the examples:

01  SOURCE-TABLE OCCURS 20 TIMES    PIC S9(9)V99.
01  DEST-TABLE OCCURS 20 TIMES      PIC S9(9)V99.

01  ROLL-UP-TABLE.
    03  TOTALS OCCURS 10 TIMES.
        05  REPORT-SUM
            OCCURS 20 TIMES         PIC S9(9)V99.
77  CTR                             PIC 99.

To add all the elements of SOURCE-TABLE to DEST-TABLE:

ADD TABLE SOURCE-TABLE TO DEST-TABLE

To add the first five elements of SOURCE-TABLE to the last five elements of DEST-TABLE:

ADD TABLE SOURCE-TABLE TO DEST-TABLE
     FROM INDEX 1 TO 5
     DESTINATION INDEX 16

To add all the REPORT-SUM elements in the last TOTALS row to the row above it (second to last row):

ADD TABLE REPORT-SUM(10) TO REPORT-SUM(9)

To perform the same operation using a PERFORM loop you would have to write the following code:

PERFORM VARYING CTR FROM 1 BY 1 UNTIL CTR > 20
    ADD REPORT-SUM(10, CTR) TO REPORT-SUM(9, CTR)
END-PERFORM
Parent topic: Procedure Division Statements


ALTER Statement

The ALTER statement changes the destination of a GO TO statement.

General Format

ALTER { goto-proc TO [ PROCEED TO ] new-proc } ...

Syntax Rules

  1. goto-proc is the name of a paragraph consisting of a single GO TO statement without the DEPENDING phrase.
  2. new-proc is a procedure name.

General Rules

  1. The ALTER statement changes the destination of the GO TO statement in goto-proc.
  2. After execution of the ALTER statement, the GO TO in goto-proc causes control to transfer to new-proc.
  3. The ALTER verb has been declared an obsolete element of COBOL by the COBOL standards committee. It is recommended that instances of ALTER be replaced by the GO TO verb using the DEPENDING ON phrase.
Parent topic: Procedure Division Statements


CALL Statement

The CALL statement causes control to be transferred to another program. For a discussion of how the runtime handles program calls, see Calling Subprograms. See Working with Windows Technologies and Working with C and C++ Programs for information about calling subroutines in DLLs and UNIX shared libraries.

Format 1

CALL [IN THREAD] program-name

 [ HANDLE IN handle-1 ]

 [ USING { [ BY {REFERENCE} ] {parameter} size-phrase ...} ...]
                {CONTENT  }   {OMITTED  }
                {VALUE    }   {NULL     }

 [ {RETURNING} INTO return-val ]
   {GIVING   }

 [ ON     {EXCEPTION} statement-1 ]
          {OVERFLOW }

 [ NOT ON {EXCEPTION} statement-2 ]
          {OVERFLOW }

 [ END-CALL ]

where size-phrase is:

[WITH MEMORY SIZE {= } memory-size]
                  {IS}

Format 2

CALL RUN program-name

 [ USING {parameter} ... ]

 [ ON  {EXCEPTION} statement-1 ]
       {OVERFLOW }
 [ NOT ON  {EXCEPTION} statement-2 ]
           {OVERFLOW }

 [ END-CALL ]

Format 3

CALL PROGRAM program-name

 [ USING {parameter} ... ]

 [ ON  {EXCEPTION} statement-1 ]
       {OVERFLOW }

 [ END-CALL ]

Format 4 (HP COBOL)

CALL { identifier-1            } [ USING { \\             } ... ]
     { [ INTRINSIC ] literal-1 }         { @identifier-2  }
                                         { identifier-2   }
                                         { literal-2      }
                                         { \identifier-2\ }
                                         { \literal-2\    }

     [ GIVING identifier-3 ]

     [ ON {EXCEPTION} statement-1 ]
          {OVERFLOW )

     [ NOT ON {EXCEPTION} statement-2 ]
              {OVERFLOW )

     [ END-CALL ] ]

Syntax Rules

Note: For Syntax Rules and General Rules specific to Format 4, see HP COBOL Conversions in Transitioning to ACUCOBOL-GT.
  1. program-name is a nonnumeric literal or an alphanumeric data item.
  2. handle-1 must be a USAGE HANDLE or HANDLE OF THREAD data item.
  3. The NULL and OMITTED options are synonymous.
  4. memory-size is a numeric literal or data item.
  5. parameter is any non-level 88 data item or a literal. It may be subscripted and reference modified. It may be the SELECT name of an open COBOL file.
  6. statement-1 and statement-2 are imperative statements.
  7. EXCEPTION and OVERFLOW are equivalent.
  8. The NOT EXCEPTION phrase may not be used when the PROGRAM option is used.
  9. return-val must specify a numeric data item.
  10. RETURNING and GIVING are synonymous.

General Rules

  1. program-name specifies the name of the called program. The exact procedure for resolving this name into the name of a program to call is described in File Name Interpretation.
  2. The THREAD option starts a new thread before calling the target program. The called program executes in the new thread. The calling program continues to execute in parallel. When the called program exits, its thread is terminated.
  3. The HANDLE phrase stores the ID of the thread in handle-1 immediately after the new thread starts. This occurs before the USING parameters are evaluated, so that it is possible to pass handle-1 to the called program.
  4. The parameters' order of appearance in the USING phrases of the CALL verb, and the called program's Procedure Division header, determine the correspondence between the data names used in the called and calling programs. This correspondence is established by position, not by name.
  5. The SIZE phrase is used when the parameter in the USING phrase is a memory address (pointer to memory) and you need to specify the size of the piece of memory that is located at that address. The SIZE phrase supports the calling of DLLs on the display host by thin client applications..
  6. The BY phrase controls how parameters are passed to the called program. The default method is BY REFERENCE. This method causes the address of the data item to be passed to the receiving program. This is the only method of passing data available in versions of ACUCOBOL-GT prior to 2.0.

    The BY CONTENT phrase is similar to BY REFERENCE, except that the address of a copy of the data item is sent. This has the effect that any changes made to the parameter in the called program are not seen by the caller. Starting with Version 2.0, literals passed as parameters are automatically passed BY CONTENT.

    The BY VALUE method causes the contents of the data item to be passed to the receiving program (the actual data, not its address). This may not be specified if the receiving program is a COBOL program (results are undefined in this case). This method is typically used to pass numeric data to C subprograms. For optimal portability we recommend that parameters being passed by this method be level 01 or 77 items described as SIGNED-INT, UNSIGNED-INT, SIGNED-SHORT, UNSIGNED-SHORT, SIGNED-LONG, UNSIGNED-LONG, or POINTER.

    When the name of an open COBOL file is given as a parameter, the operating system's file handle is passed. One possible reason for doing this is to call an operating system function that allows the file to retrieve some information that is not available through COBOL. Several special rules apply to this usage. See rules 30 through 35 below.

  7. The NULL and OMITTED options are synonymous. They allow you to skip a parameter in a USING phrase. The corresponding parameter in the called program must not be referenced. If the called program is a C program, then a NULL value is passed to the corresponding parameter.
  8. Index names referred to in the Linkage Section of the called program do not correspond to any index names in the calling program. Index data items are always stored in the local memory of their programs.
  9. If the called program does not have the INITIAL attribute, then it is in its initial state the first time it is called, and the first time it is called after a CANCEL verb has referred to it. On all other calls, the program is in the same state as when it last exited.
  10. If the called program has the INITIAL attribute, it is in its initial state every time it is called.
  11. Files contained in the called program are not open whenever the called program is in its initial state. Otherwise, the status and positioning of the contained files is the same as when the program last exited.
  12. If the ON EXCEPTION phrase is present and the called program cannot be initiated, statement-1 executes. If the called program cannot be initiated when there is no EXCEPTION phrase, a runtime error occurs and the program halts. A program cannot be initiated if program-name cannot be resolved using the rules described in Calling Subprograms.
  13. If the NOT ON EXCEPTION phrase is present and the called program is successfully initiated, statement-2 executes when the called program returns.
  14. The ON EXCEPTION and NOT ON EXCEPTION phrases execute in the original (parent) thread. The parent thread suspends long enough to determine whether or not the CALL will succeed. This allows it to determine whether to execute the EXCEPTION or NOT EXCEPTION case.
  15. A called program's file state and data items are distinct for each thread that exists at the time of the call (including the thread created by the CALL THREAD). Thus, if thread-1 calls program-a, and thread-2 calls program-a, there will be two copies of the data from program-a in memory, one set for each thread. Threads created in the called program, or any of its subprograms, share the called program's data and file state.
  16. The CALL PROGRAM verb is similar to the CHAIN verb. It causes the current run unit to terminate and initiates a new run unit. However, USING parameters are passed to data items specified in Linkage, just as they are for a standard CALL verb.

    Some (incorrect) usages of the CALL statement USING parameters from the Linkage section of the called program can result in so-called "intermediate" runtime errors that call installed error procedures. There currently are two such related errors: Use of a LINKAGE data item not passed by the caller, and Passed USING item smaller than corresponding LINKAGE item. A passed USING item that is larger than the corresponding Linkage item does not generate an error.

    Another runtime error can occur when the CALL statement attempts USING parameters of invalid structure or missing parameters. That kind of error is announced as Invalid or missing parameter, and it is also an "intermediate" type of runtime error that calls installed error procedures.

    See Appendix I. Library Routines for detailed discussion of the runtime error and exit procedures.

  17. When a CALL PROGRAM verb succeeds, all program switches are set to their off state. You can specify switches to be set on in the CALL PROGRAM statement. You accomplish this by specifying the switch names immediately after the program name in the statement. Each switch name must be alphabetic and must be preceded by a slash (/). For example, to turn on switches "A" and "B" you could use this statement:
    CALL PROGRAM "MYPROG/A/B" USING ...
  18. If the CALL PROGRAM verb cannot find the called program, and no EXCEPTION phrase has been specified, control passes to the next executable statement.
  19. The CALL PROGRAM verb accepts the presence of routines whose name begins with a "#" sign. When one of these routines is specified, the CALL PROGRAM statement is ignored. In ICOBOL, routines with these names are special-purpose system routines.
  20. If the RUN option is used, then program-name refers to the main program of another run unit. This run unit is initiated and continues until it executes a STOP RUN. At that point, control is returned to the next executable sentence in the calling program. Parameters are passed to the called run unit in the same manner as specified for the CHAIN statement.

    The called run unit is logically distinct from the calling run unit. It may call programs that are active in the calling unit without generating an error. External areas are associated with a logical run unit, so that a new run unit does not have access to external areas created by the calling run unit. Take care that file records locked by the calling run unit do not interfere with the called run unit, because there will be no opportunity for the caller to release its records while the called unit is active.

    type-ahead is retained both when the new run unit is called and upon return from it.

    The precise amount of memory required for the runtime varies by platform and is affected by configuration variables such as V_BUFFERS and by any products or C routines you have linked in. When the CALL RUN executes, the memory associated with the new run unit is allocated, and the old run unit (with its attendant memory) remains active. Memory allocated by the runtime for program code is freed automatically at the STOP RUN in the called program. Memory used for open windows and V_BUFFERS is not freed until the runtime exits. You should explicitly free any memory that you allocated with the M$ALLOC (Dynamic Memory Routine) otherwise this memory is not freed until the runtime exits.

  21. A special register named RETURN-CODE is automatically created by the compiler and is shared by all programs of a run unit. This special register is defined as:
    77  RETURN-CODE  SIGNED-LONG, EXTERNAL.

    If you call a C program via the direct interface, the return value of the C function is placed into this register. If you call the SYSTEM library routine, the status of the call is placed into this register. The verbs EXIT, STOP, and GOBACK can also place a value into the RETURN-CODE register. The compiler also creates an unsigned version of the return code called RETURN-UNSIGNED. It has the following implied definition:

    77  RETURN-UNSIGNED
    REDEFINES RETURN-CODE
    UNSIGNED-LONG, EXTERNAL.
  22. If the RETURNING phrase is used, then the return value of the called program is moved to return-val. This is accomplished by the following rule:
    1. If return-val is a signed data item, then the value of RETURN-CODE is moved to return-val according to the rules of the MOVE statement.
    2. If return-val is unsigned, then RETURN-UNSIGNED is moved instead.
  23. You should avoid using RETURN-CODE or RETURN-UNSIGNED for return-val. This is pointless because, after assigning a value to return-val, the CALL statement restores the previous value of RETURN-CODE.
  24. On Windows systems, if you CALL a DLL, the runtime assumes that the DLL returns a long (at least 32 bits of data). This ensures that all of the data returned from the DLL is captured. However, in situations where the DLL returns less than 32 bits of data (such as a DLL that returns a short), some of the data might be random. To get the right size for the return value of DLLs, use the RETURNING phrase and set the receiving variable to the same size as the DLL's return value. The easiest way to do this is to declare the receiving variable to be the same type as the DLL's return type. For example, if the DLL MYDLL returns an int, you could do the following:
    77  RETURN-VAL       SIGNED-INT.
CALL "MYDLL" RETURNING RETURN-VAL.
  25. After return-val is set, RETURN-CODE is set to the value it had immediately prior to the CALL statement. Thus the called program does not affect the value of RETURN-CODE in the calling program.
  26. If the CALL statement fails with an exception, then return-val is not updated.
  27. You may pass floating-point data to subroutines normally with the CALL verb. Note that you may not pass a floating-point item BY VALUE. This restriction exists for portability reasons (some machines pass floating-point using a convention different from that used for integer items). You should pass floating-point items BY REFERENCE. This will pass a pointer to the item, which the receiving routine can then retrieve by de-referencing the pointer.
  28. A program may directly or indirectly call itself. A CALL statement that calls the active program (itself) is a recursive call. For more information, see the RECURSION configuration variable. For information on sharing data in recursively called programs (such as in the HP COBOL environment), see the RECURSION_DATA_GLOBAL configuration variable.
  29. Errors that occur as a result of the CALL statement USING parameters from the Linkage section of the called program belong to an intermediate type of runtime errors that call installed error procedures. There are two such errors: Use of a LINKAGE data item not passed by the caller, and Passed USING item smaller than corresponding LINKAGE item.
Passing File Handles
  1. For compatibility with HP COBOL, a file handle is automatically passed BY VALUE unless it is immediately preceded by a BY REFERENCE or BY CONTENT specification. File handles passed to COBOL subroutines must be preceded with BY REFERENCE or BY CONTENT because COBOL routines cannot take BY VALUE parameters.
  2. If the called subroutine is a COBOL routine, the handle passed is PIC S9(4) COMP-5. You can override this with the compiler option --fileIdSize=# where # is either 2, 4, or 8 to specify the number of bytes you want in the passed integer.
  3. If the called subroutine is not COBOL, the handle is passed as a signed native integer using the host's default integer size.
  4. The file handle passed is the host file system's identifying value for the open file. For all current implementations, this is the value returned by the C open function. If the host file system does not have this information available, then -1 is used instead. This can happen if the host system is not a file (e.g. Acu4GL for Oracle) or the host system does not provide a way of obtaining the handle (e.g. C-ISAM interface). Files served by AcuServerÂ® also use -1 because there is no useful way to use a remote process' open file handle.
  5. For Vision files in the multi-file format (Versions 4, 5, or 6), the handle used is the handle of the first data segment (this is the same file used when opening the file).
  6. It is best to avoid performing actual I/O on the file using this file handle because the COBOL file system will be unaware of any state changes to the file and may perform incorrectly. It is possible to corrupt data this way.
Parent topic: Procedure Division Statements


CANCEL Statement

The CANCEL verb places a program into its initial state.

Format 1

CANCEL {program-name} ...

Format 2

CANCEL ALL

Format 3

CANCEL SORT

Syntax Rule

program-name is a nonnumeric literal or an alphanumeric data item. It may not be an ALL literal.

General Rules

  1. After a CANCEL verb executes, the affected programs are placed into their initial states. This closes any open files contained in the cancelled program and ensures that any VALUE clauses are in effect when those programs are called again. By default, memory used by the programs is released. If the mechanism for logical cancels is enabled, the programs are cached in memory. For information about the effects and use of logical cancels, see Memory Management.
  2. In Format 1, each program-name refers to the CALL name of a program to cancel. For more information, see Calling Subprograms.
  3. In Format 2, every program that has been called but is not active is cancelled. A program is active if it has been called (or is the initial program of the run) and has not yet exited.
    Note: The CANCEL_ALL_DLLS configuration variable can be used to exclude DLLs and shared object libraries from the results of the CANCEL ALL statement. See CANCEL_ALL_DLLS for details.
  4. A CANCEL statement is ignored if it refers to an active program. A CANCEL statement may also refer to a program that has never been active. Such a reference has no effect.
  5. A CANCEL statement has no effect on a program that has a RESIDENT phrase in its PROGRAM-ID paragraph.
  6. When you cancel a program that exists in more than one thread, it is canceled only in the current thread. CANCEL ALL cancels only programs in the current thread. If a program is active in any thread that it shares data with, the CANCEL will have no effect.
  7. In Format 3, any active sort is terminated. Only one sort may be active at a time; using Format 3 guarantees that no sort is active, and thus prepares you to initiate a new sort safely.
Parent topic: Procedure Division Statements


CHAIN Statement

The CHAIN statement provides a method for starting another run unit.

General Format

CHAIN program-name [ USING {parameter} ... ]

   [ ON {EXCEPTION} statement ]
        {OVERFLOW }

   [ END-CHAIN ]

Syntax Rules

  1. program-name is a nonnumeric literal or an alphanumeric data item.
  2. parameter is any non-level 88 data item or a nonnumeric literal. No more than 50 parameters may be specified.
  3. statement is an imperative statement.
  4. If a CHAIN statement appears in a consecutive sequence of imperative statements within a sentence, it must be the last statement in that sequence, unless the EXCEPTION phrase is specified.

General Rules

  1. The CHAIN statement causes the current run unit to terminate and initiates a new run unit. Executing a CHAIN statement has the following effects:
    1. The current run unit is halted as if a STOP RUN statement were executed.
    2. The run unit specified by program-name is initiated. program-name is resolved into an executable program name using the same rules specified for the CALL statement.
  2. If the EXCEPTION phrase is used, then statement executes if the CHAIN statement is unable to load program-name. This is usually caused by program-name being either absent or not readable by the runtime system. Certain types of errors cannot be caught by the ON EXCEPTION phrase because of the nature of the CHAIN statement. If the EXCEPTION phrase is not present when an error occurs, the runtime system prints a message and halts.
  3. If the USING phrase is specified, each parameter is transferred to the new run unit. Each parameter is mapped to the corresponding CHAINING argument in the new run unit. See Procedure Division Format for a description of the CHAINING phrase.
Parent topic: Procedure Division Statements


CLOSE Statement

The CLOSE statement is used to terminate the processing of a file or files, to change the current video-terminal window, or to close a floating window.

Format 1

CLOSE { file-name [REEL] [ WITH {NO REWIND} ] } ...
                  [UNIT]        {LOCK     }

Format 2

CLOSE WINDOW window-handle [ WITH NO DISPLAY ]

Syntax Rules

  1. file-name must be the name of a file described in the Data Division. It may not be a sort file.
  2. If the REEL or UNIT option is used, then file-name must refer to a sequential file.
  3. window-handle can be either a PIC X(10) data item or a HANDLE data item. If used with a SUBWINDOW, window-handle must have been the object of a POP-UP AREA phrase in a DISPLAY statement.

Format 1 (CLOSE File) General Rules

  1. A file referred to by a CLOSE statement must be in the open state. After the execution of a successful CLOSE statement, each file-name is in the closed state. All record and file locks held by those files are released.
  2. Any FILE STATUS variables associated with the file-names are updated by the CLOSE verb.
  3. The NO REWIND option lets you hold a pipe open when closing its corresponding file. This allows you to gather multiple reports into a single job for the print spooler. To use NO REWIND in this way, create a configuration file entry as described in SPOOL_FILE in ACUCOBOL-GT Appendices.
  4. The LOCK option prevents the affected files from being opened again by this run unit in its current execution.
  5. If the UNIT or REEL option is specified, then the file remains open and the next reel of the multi-reel file is mounted. Since ACUCOBOL-GT does not directly support multi-reel files, specifying this option causes the CLOSE statement to have no effect other than to update the FILE STATUS variable.

Format 2 (CLOSE WINDOW) General Rules

  1. The CLOSE WINDOW verb is used to remove floating windows and subwindows.
  2. window-handle must be a handle returned by a DISPLAY FLOATING WINDOW statement, or the object of a POP-UP phrase of a DISPLAY WINDOW statement that executed in the current run unit. Furthermore, it cannot have been the object of a CLOSE WINDOW verb nor may it have been otherwise modified.
  3. The CLOSE WINDOW verb restores the contents of the screen covered by the window that is being destroyed. In other words, the window that was created by that DISPLAY FLOATING WINDOW or DISPLAY WINDOW statement is removed from the screen and replaced by the contents of the screen that was under that window. Any memory associated with the closed window is then freed.
  4. The window that was current when the terminating window was created becomes the active window. The cursor is positioned to the location it occupied when the window was created.
  5. The WITH NO DISPLAY option causes the closed window to remain on the screen. The effect is the same as a normal CLOSE WINDOW verb, except that no updating of the console takes place. This can be used to free memory used by a window when you do not want to physically remove it from the screen. For example, suppose you want to remove a series of nested windows and want to reduce the amount of screen activity that occurs. In this case, you can close all of the nested windows with the NO DISPLAY option and then close the outermost window in the normal manner.

    WITH NO DISPLAY is ignored when a floating window is closed. It is effective only when pop-up windows are closed.

  6. CLOSE WINDOW window-handle is synonymous with DESTROY window-handle.
Parent topic: Procedure Division Statements


COMMIT Statement

The COMMIT statement unlocks locked records and (optionally) flushes buffers to disk. COMMIT may also indicate the end of a transaction, and cause the changes to be written to the transaction log file.

General Format

COMMIT TRANSACTION

General Rules

  1. When this statement is executed, all locked records owned by the current run-unit are unlocked.
  2. COMMIT also causes a request to be made to the host operating system to flush all buffers to disk. The exact effect of flushing disk buffers depends on the host operating system. Some systems do not ensure that buffers are fully flushed when the COMMIT verb finishes. For example, UNIX only schedules a flush, which occurs over the next few seconds. VAX/VMS already flushes after each write (except for locked files).
  3. You can prevent the buffers from being flushed to disk by using the FLUSH-ON-COMMIT line in your runtime configuration file.
  4. The function of COMMIT depends on whether or not it ends a transaction. The following rules describe how transaction management operates with Vision and relative files. For other file systems linked with the runtime, each system's native mechanism for transaction management is invoked. See the Acucorp interface document for the specific file system for more details.
  5. When ROLLBACK is enabled in the FILE-CONTROL entry for a file, the record and file locking rules are extended for that file. Every record updated as part of a transaction is locked until that transaction is committed or rolled back. The COMMIT verb removes these locks. Record locks applied when the file is read are kept until the end of the transaction, if ROLLBACK is enabled for the file.

    Record locks are held during a transaction in order to prevent another process from updating the records in a way which might make rollback impossible. Note, however, that a record may be deleted during a transaction, and another process is allowed to write a record with the same record key to the file. If this happens, and duplicates are disallowed on that record key, then the ROLLBACK will fail with a duplicate key error.

  6. During a transaction involving Vision or relative files, a CLOSE of a file that is locked, or that has locked records, is postponed until the transaction is committed or rolled back.

    If the same physical file is opened again within the transaction, even if a different logical file (different SELECT) is used, the postponed CLOSE is canceled. Note that the mode of the original OPEN is retained. (For example, if the file were originally OPEN I-O, and if the CLOSE were canceled, then an OPEN OUTPUT on the same file within the same transaction would not empty the file.) When the second OPEN is encountered, the file position is reset to the beginning so that a READ NEXT would read the first file in the record. CLOSE is handled in this special way so that record locks are held--these locks are necessary for rollback.

  7. COMMIT locks the log file, checks its integrity, then writes the changes and unlocks the log file. The log file is specified with the filename_LOG or LOG_FILE configuration variable. See Multiple Log Files in the ACUCOBOL-GT User's Guide for more information.
  8. There is an implicit COMMIT before a STOP RUN or before the end of the program, unless the STOP_RUN_ROLLBACK configuration variable is set to 1. Then, an implicit ROLLBACK occurs.
Parent topic: Procedure Division Statements


COMPUTE Statement

The COMPUTE statement provides the ability to perform general arithmetic computations.

General Format

COMPUTE { result [ROUNDED] } ... { =     } arithmetic-expr
                                 { EQUAL }

   [ ON SIZE ERROR statement ]

   [ NOT ON SIZE ERROR statement ]

[ END-COMPUTE ]

Syntax Rules

  1. result is an elementary numeric or numeric-edited data item.
  2. arithmetic-expr is any arithmetic expression.
  3. statement is an imperative statement.

General Rules

  1. The arithmetic-expr is evaluated and assigned to each result variable.
  2. Additional information can be found in the help topics covering Arithmetic Operations, Multiple Receiving Fields, the ROUNDED Option, and the SIZE ERROR Option.
Parent topic: Procedure Division Statements


CONTINUE Statement

The CONTINUE statement is a no action statement.

General Format

CONTINUE

General Rule

The CONTINUE statement performs no actions. It can be used in any case where a statement is required but no action is wanted.

Parent topic: Procedure Division Statements


CREATE Statement

The CREATE statement creates a new instance of a non-graphical object such as a COM object or .NET assembly. Use it specifically for objects or assemblies that are not visual in nature. Use the Screen Section or DISPLAY statement to create an instance of a graphical .NET assembly or an ActiveX control.

Note: CREATE can be used with thin client applications to create instances of an object on the client or on remote Windows servers. CREATE cannot be used to create an object on a non-Windows server such as UNIX or VMS; however, non-Windows servers running AcuConnect can provide connectivity to Windows servers in a multi-tiered configuration.

Format 1

CREATE object-name creates a COM object.

CREATE object-name

HANDLE { IN } object-handle
       { IS }

Remaining phrases are optional.

SERVER-NAME { IS } server-name
            { =  }
LICENSE-KEY { IS } license-key
            { =  }
EVENT PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
                              {THRU }
                   { NULL }

Format 2

CREATE assembly-name creates a non-graphical .NET object.

CREATE "assembly-name"

NAMESPACE { IS } "namespace"

CLASS-NAME { IS } "class-name"

HANDLE { IN } object-handle
       { IS }

EVENT PROCEDURE { IS } "event-proc"

Remaining phrases are optional.

VERSION { IS } "version"

CULTURE { IS } "culture"

STRONG-NAME { IS } "strong-name"

CONSTRUCTOR { IS } CONSTRUCTOR[n] parameters...

MODULE { IS } "module"

FILE-PATH { IS } "file-path"

Syntax Rules

  1. object-name is an optionally qualified name of a COM object defined in the special-names paragraph.
  2. server-name is an alphanumeric literal or data item.
  3. license-key is an alphanumeric literal or data item.
  4. object-name is a USAGE HANDLE data item.
  5. proc-1 and proc-2 are procedure names relating to COM events. See ActiveX and COM Events for more information.
  6. Any value surrounded by quotation marks is an alphanumeric literal and is case-sensitive.

Format 1 (CREATE object-name) General Rules

  1. In a non-Thin Client environment the COM object is registered and instantiated on the same machine the runtime is executing on. In a Thin Client scenario the COM object is registered and instantiated on the client machine rather than the server where the runtime is executing.
  2. server-name identifies a remote machine on which to create and execute the COM object. It can be specified as a UNC, DNS name, or IP address. Server-name must be the name of a Windows machine. CREATE cannot create objects on non-Windows servers. When a server-name is provided - the COM object's interface is instantiated on the machine where the application is executing and the back-end is instantiated on the specified server where the work is done and resources can be accessed. In this case the COM object must be registered on both machines.
  3. In a Thin Client environment the customer may also specify the server-name with the prefix, Local: e.g. CREATE COM_object SERVER-NAME "Local:the_server_name". In this case the COM object is wholly instantiated on the specified server where the COM object is registered, all the work is done and all resources must reside.
  4. Some COM objects are licensed for run time using a license key that is provided to you by the object vendor. This license key is a text string usually located in a .lic file. By setting the value of the LICENSE-KEY property to this license key, you embed this license key in your COBOL program. Then when you run your COBOL program, the license key is passed to the COM object for verification. You do not send the .lic file or license key to the end-user. Set LICENSE-KEY when you create the object (i.e., in the CREATE statement). The default value is " ". When LICENSE-KEY is " " (i.e., the default) and the COM object supports the licensing mechanism, the control performs its own license verification. Some objects require a .lic file to do this. Others may check the system registry or hard disk for other properly installed and licensed software.

Format 2 (CREATE assembly-name) General Rules

  1. Literal values for assembly parameters are located in the COPY file generated by the NETDEFGEN utility. The same COPY file must be included in the SPECIAL-NAMES paragraph of your program.
  2. assembly-name is the name of a .NET assembly defined in the NETDEFGEN COPY file. This must be the DLL name of a non-graphical control, not an executable file. Non-graphical controls are generated by Visual Studio when a developer selects a "Class Library" project type.
  3. Namespace is a NameSpace in the assembly.
  4. Ccass-name is a class in the NameSpace.
  5. Version is the version number of the assembly.
  6. culture is cultural information related to the assembly.
  7. strong-name is the cryptographic key required to access the assembly, if any. If the assembly requires such a key, as all assemblies in the Global Assembly Cache (GAC) do, it is shown in the COPY file under the keyword STRONG.
  8. All classes that result in an object have a CONSTRUCTOR, which is a sort of method. If you see a CONSTRUCTOR identifier in the COPY file without a parameter list, the field may be omitted from your COBOL program. If all listed CONSTRUCTORs have parameters, then you must choose which CONSTRUCTOR and parameters to use. constructor(n) is the constructor that you want to use followed by its parameter data.
  9. module identifies a file where a combination of NameSpaces and Classes resides. It is used when the assembly is constructed of other assemblies.
  10. file-path is the path of an XML file, and that XML file contains the path where the .NET assembly is located. Use FILE-PATH when the assembly that you want to access does not reside in the GAC or in the same directory as wrun32.exe. Assemblies that reside in the GAC have the STRONG keyword in the NETDEFGEN COPY file.
    When using a C# assembly and Thin client, where the C# assembly is on the client, file-path points to an XML-FILE. The xml file needs to reside in the run time bin directory. Here is a sample XML file:
    <?xml version="1.0"?>
<FILE_PATH>@[DISPLAY]:C:\path-on-client-where dll-resides</FILE_PATH>
    This allows a C# assembly to be executed on the client when running Thin client.
Parent topic: Procedure Division Statements


DELETE Statement

The DELETE statement logically removes a record from a file or a file from the host system.

Format 1

DELETE file-name RECORD

   [ INVALID KEY statement-1 ]

   [ NOT INVALID KEY statement-2 ]

   [ END-DELETE ]

Format 2

DELETE FILE file-name

Syntax Rules

  1. file-name must refer to a file described in the Data Division. It may not be a sort file. In Format 1, it cannot be the name of a sequential file.
  2. statement-1 and statement-2 are imperative statements.
  3. The INVALID KEY and NOT INVALID KEY clauses must not be specified for a DELETE statement that references a file that is in the sequential access mode.
  1. The file must reside on a mass-storage device and be open in the I/O mode when the DELETE statement executes.
  2. For files in the sequential access mode, the last I/O statement executed for the file prior to the execution of the DELETE statement must have been a successful READ statement. The DELETE statement deletes that record from the file.
  3. For a relative file in the random or dynamic access mode, the DELETE statement removes the record identified by the file's RELATIVE KEY data item. If that record does not exist, an invalid key condition exists.
  4. For an indexed file in the random or dynamic access mode, the DELETE statement removes the record identified by that file's RECORD KEY data item. If that record does not exist, an invalid key condition exists.
  5. After a successful DELETE, the deleted record has been logically removed from the file and may no longer be accessed.
  6. The execution of the DELETE statement does not affect the file's record area.
  7. The current file position is not changed by the DELETE statement.
  8. The FILE STATUS variable of the file is updated.
  9. If there is an applicable USE AFTER EXCEPTION procedure, it executes whenever a non-zero I/O status applies to the DELETE. However, it does not execute if an invalid key condition exists and the INVALID KEY phrase is used. If a USE AFTER EXCEPTION procedure would normally execute, but none has been specified, then the program prints an error message and halts.
  10. statement-1 is executed if it is specified and the invalid key condition exists.
  11. statement-2 is executed if it is specified and the DELETE statement is successful.

Format 2 - DELETE FILE General Rules

  1. The DELETE FILE statement removes a file from the host computer system. The file named by file-name must be closed and reside on a mass-storage device.
  2. With one exception, the organization and record layout of file-name need not match the file being deleted, although it is highly recommended that they do. For Vision Version 4, 5, or 6 files, the organization and record layout of file-name must match the file being deleted.
  3. If you match the type of the file referenced (sequential, relative, or indexed) with the type of the file being removed, your programs will consistently work with versions of ACUCOBOL-GT based on different file systems. For example, C-ISAM and Vision Versions 5 and 4 implement indexed files using two physical disk files for each COBOL indexed file. An ACUCOBOL-GT runtime using Vision Version 5, 4, or C-ISAM needs to know if an index file is being removed so that it will look for both physical files when an indexed file is removed.

    When the DELETE statement executes, file-name is translated as for the OPEN statement, and the corresponding file is removed from the system.

  4. The FILE STATUS data item is updated by the DELETE FILE statement.
Parent topic: Procedure Division Statements


DESTROY Statement

The DESTROY statement eliminates windows, controls, threads, fonts, layout managers, and menus.

Note: The DESTROY verb cannot destroy the main application window. If you attempt to use the DESTROY verb to destroy the main application window, the statement is ignored. The main application window is destroyed automatically when the program terminates.

Format 1

DESTROY  { screen-name-1 } ...
         { handle-1      }

Format 2

DESTROY ALL CONTROLS

Format 3

DESTROY { CONTROL

Remaining phrases are optional and can appear in any order.

AT screen-loc  [CELL  ]
               [CELLS ]
               [PIXEL ]
               [PIXELS]

AT LINE NUMBER line-num  [CELL  ]
                         [CELLS ]
                         [PIXEL ]
                         [PIXELS]

AT {COLUMN  } NUMBER col-num  [CELL  ]
   {COL     }                 [CELLS ]
   {POSITION}                 [PIXEL ]
   {POS     }                 [PIXELS]

AT CLINE NUMBER cline-num   [CELL ]
                            [CELLS]

AT CCOL NUMBER ccol-num   [CELL ]
                          [CELLS]
  } . . .

Syntax Rules

  1. screen-name-1 is the name of a screen description entry found in the Screen Section.
  2. handle-1 is a USAGE HANDLE or PIC X(10) data item.
  3. screen-loc is an integer data item or literal that contains exactly 4 or 6 digits.
  4. line-num, col-num, cline-num and ccol-num are numeric data items or literals. These may contain non-integer values.
  5. Format 1 and Format 3 statements can be mixed into a single DESTROY statement.

General Rules

  1. The DESTROY verb removes from memory the items it acts on. It also removes those items from the screen if that is appropriate. The exact meaning of the DESTROY verb depends on the type of item it is acting upon, as described below.
  2. If the statement is a Format 1 DESTROY handle-1 statement, the handle is valid, and the DESTROY statement succeeds, handle-1 is set to the value NULL (binary zeros).
  3. If handle-1 contains a valid handle to a control, then the control is removed from the screen (if it is visible) and any memory associated with the control is released.
  4. If handle-1 contains the valid handle of a floating window or subwindow, the DESTROY statement acts the same as a CLOSE WINDOW statement acting on handle-1 (with no additional options), except that DESTROY sets the value of handle-1 to NULL. When you destroy (close) a floating window, every control contained in that window is also destroyed. Also, any other floating windows that are children of that window are destroyed.
    Note: Attempting to DESTROY the main application window has no effect. However, this behavior is subject to change in a future release and should not be relied on.
  5. If handle-1 is a handle of a font, that font is removed from memory. If handle-1 is a standard font (that is, one retrieved by ACCEPT from STANDARD OBJECT), destroying it has no effect. Destroying a font that is actively in use by a control or window is an error with unpredictable consequences. If you are destroying a set of controls and their associated fonts, you should destroy the controls first, and then destroy their fonts.
  6. If handle-1 is a handle to a thread, DESTROY handle-1 has the same affect as a STOP THREAD handle-1 statement, except that the DESTROY statement also sets the value of handle-1 to NULL.
  7. If handle-1 is the handle of a menu, then that menu is destroyed, and any memory associated with it is freed. It is an error (not caught) to destroy a menu that is currently associated with a window or a control. A menu that is displayed as the menu bar of a window is automatically destroyed when the corresponding window is destroyed. A menu displayed as the menu bar of a window should not be explicitly destroyed by your program (unless you remove it from the window first). Menus associated with windows or controls as pop-up menus are not automatically destroyed when the corresponding window or control is destroyed. This makes it easier to use the same pop-up menu in more than one control or window.
  8. If handle-1 is a handle to a layout manager, the layout manager is removed from memory. A layout manager that is actively being used by a window should not be destroyed. You should first destroy the window or remove the layout manager from the window.
  9. If handle-1 contains a value other than a valid handle to a window, control, thread, font, menu, or layout manager, the DESTROY verb has no effect.
  10. If screen-name-1 is a Format 2 screen description entry (i.e., it describes a control), that control is removed from the screen, and any memory associated with it is released. screen-name-1 no longer refers to an existing control.
  11. If screen-name-1 is an elementary Format 1 screen description entry (i.e., it describes a textual field), the DESTROY verb has no effect.
  12. If screen-name-1 is a group item, each subsidiary elementary item is destroyed (i.e., the controls are destroyed and the textual fields are left alone).
  13. A Format 2 DESTROY statement (DESTROY ALL CONTROLS) destroys every control contained in the current window. This includes controls created by Screen Section entries as well as controls created directly with a DISPLAY Control verb.
  14. A Format 3 DESTROY statement destroys the control located at the screen position specified by the AT, LINE, and COLUMN phrases in the current window (on non-graphical systems, the CLINE and CCOL phrases also apply). The runtime system maintains a list of controls in each window. When attempting to destroy a control at a specific location, the runtime searches this list, using the first control it finds that exactly matches the location. The list is maintained in the order in which the controls are created. If the runtime does not find a control at the specified location, then nothing happens.
  15. Use Format 1 DESTROY handle to destroy non-graphical .NET controls or assemblies. For graphical .NET controls, you can use either Format 1 DESTROY handle or Format 2 DESTROY ALL.
Parent topic: Procedure Division Statements


DISPLAY Statement

The DISPLAY statement provides for low-volume output from the program. This section describes each DISPLAY statement format.

Note: Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  • DISPLAY src-item
  • DISPLAY screen-name
  • DISPLAY WINDOW
  • DISPLAY SCREEN SIZE
  • DISPLAY LINE
  • DISPLAY BOX
  • DISPLAY UPON WINDOW TITLE
  • DISPLAY UPON COMMAND LINE
  • DISPLAY src-item ANSI format
  • DISPLAY UPON GLOBAL TITLE
  • DISPLAY FLOATING WINDOW
  • DISPLAY INITIAL WINDOW
  • DISPLAY TOOL-BAR
  • DISPLAY control-type-name
  • DISPLAY MESSAGE BOX
  • DISPLAY external-form-item
  • DISPLAY UPON ENVIRONMENT-NAME
  • DISPLAY assembly-name
Parent topic: Procedure Division Statements


DISPLAY src-item

Format 1

DISPLAY src-item displays an individual field to the screen.

DISPLAY { {src-item}
          {OMITTED }

 [ UPON new-window ]

Remaining phrases are optional, can appear in any order.

AT screen-loc

AT LINE NUMBER line-num

AT {COLUMN  } NUMBER col-num
   {COL     }
   {POSITION}
   {POS     }

WITH SIZE length

WITH NO ADVANCING

{ERASE} [TO END OF] {LINE  }     (VAX, ICOBOL)
{BLANK}             {SCREEN}

{ERASE} [EOS]                    (RM)
{BLANK} [EOL]

WITH  {BELL}
      {BEEP}

{UNDERLINED}
{HIGHLIGHT }
{HIGH      }
{BOLD      }
{LOWLIGHT  }
{LOW       }
{STANDARD  }

WITH  {BLINKING}
      {BLINK   }

{REVERSE-VIDEO}
{REVERSE      }
{REVERSED     }

SAME
WITH {COLOR } color-val
     {COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

SCROLL [UP  ] [ BY scrl-num {LINE } ]
       [DOWN]               {LINES}

OUTPUT {JUSTIFIED}  {LEFT    }
       {JUST     }  {RIGHT   }
                    {CENTERED}

WITH {CONVERSION}
     {CONVERT   }

CONTROL cntrl-string

UPON CRT
} ...

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. src-item is a literal or data item. It must be USAGE DISPLAY unless the CONVERSION phrase is also specified. Src-item specifies the data to be displayed.
  3. new-window is a USAGE HANDLE or PIC X(10) data item.
  4. Screen-loc is an integer data item or literal containing exactly 4 or 6 digits. It may also be a group item of 4 or 6 characters. If a numeric item is used, it must be a non-negative integer.
  5. line-num, col-num, and length are numeric data items or literals. They may be non-integer values. You can also specify the value with an arithmetic expression.
  6. color-val and scrl-num are numeric data items or literals. color-val can also be an arithmetic expression, except when used in the Screen Section.
  7. fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. See Common Screen Options for a more detailed discussion of color settings and values.
  8. cntrl-string is a nonnumeric literal or data item.
  9. If the UPON phrase is used it must be the first optional phrase specified.
  10. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  11. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  12. IS and "=" are synonymous.
  13. COLUMN, COL, POSITION, and POS are equivalent.
  14. BELL and BEEP are equivalent.
  15. BLANK and ERASE are equivalent.
  16. HIGHLIGHT, HIGH and BOLD are synonymous.
  17. LOWLIGHT and LOW are equivalent.
  18. UNDERLINE and UNDERLINED are equivalent.
  19. BLINK and BLINKING are equivalent.
  20. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  21. CONVERT and CONVERSION are equivalent.
  22. COLOR and COLOUR are synonymous.
  23. FOREGROUND-COLOR and FOREGROUND-COLOUR are synonymous.
  24. BACKGROUND-COLOR and BACKGROUND-COLOUR are synonymous.
  25. The ERASE phrase has two forms. In VAX COBOL and ICOBOL compatibility modes, the ERASE SCREEN/LINE form must be used. In RM/COBOL mode, the ERASE EOS/EOL form must be used. This is indicated in the General Format by the symbols (VAX, ICOBOL) and (RM)
  26. You may add UPON CRT to a Format 1 DISPLAY statement to distinguish it from a Format 9 DISPLAY statement. You need to do this only if you use the Ca compiler option.

General Rules

  1. The DISPLAY statement sends each of its src-items to the video terminal attached to the executing program. If more than one src-item is specified, each is treated as if it were in a separate DISPLAY statement in the order listed. Note, however, in VAX COBOL and ICOBOL compatibility mode, NO ADVANCING is automatically implied for each src-item except for the last one.
  2. The precise action of the DISPLAY statement depends both on the various clauses specified and the compatibility mode that the compiler is run in. These actions are detailed in the following rules.
  3. The effects of the various optional phrases are described in Common Screen Options.
  4. If the OMITTED option is used, then no src-item is sent to the screen. This can be used to cause the action of various optional phrases without sending any actual data. For example, DISPLAY OMITTED, BELL will cause the terminal's bell to ring. If a SIZE phrase is specified, then the OMITTED phrase will act like an alphanumeric src-item of the specified size whose value is identical to the characters located on the screen where the DISPLAY will occur. This can be used to modify the video attributes of the screen without changing the displayed data. For example,
    DISPLAY OMITTED, SIZE 5, REVERSE

    will cause the five characters located at the current cursor location to be changed to reverse-video.

  5. The DISPLAY statement can be used with the -Cv IBM DOS/VS COBOL compatibility command line.
Parent topic: DISPLAY Statement


DISPLAY screen-name

Format 2

DISPLAY screen-name displays a Screen Section item defining one or more fields to the screen.

DISPLAY screen-name

 [ UPON new-window ]

Remaining phrases are optional, can appear in any order.

AT screen-loc

AT LINE NUMBER line-num

AT {COLUMN  } NUMBER col-num
   {COL     }
   {POSITION}
   {POS     }

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. screen-name is the name of a screen entry declared in the program's Screen Section.
  3. new-window is a USAGE HANDLE or PIC X(10) data item.
  4. screen-loc is an integer data item or literal containing exactly 4 or 6 digits. It may also be a group item of 4 or 6 characters. If a numeric item is used, it must be a non-negative integer.
  5. line-num and col-num are numeric data items or literals. They may be non-integer values. You can also specify the value with an arithmetic expression.
  6. If the UPON phrase is used, it must be the first optional phrase specified.
  7. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  8. COLUMN, COL, POSITION, and POS are equivalent.

General Rules

  1. A Format 2 DISPLAY statement causes all of the output and update fields in screen-name to be displayed on the user's screen. Screen-name must be a screen item declared in the program's Screen Section. Before the fields are displayed, each field has its corresponding data item moved to it. Any controls described in screen-name are either created or updated as appropriate.
  2. When a Format 2 DISPLAY statement executes, spaces are moved to each alphabetic, alphanumeric, and alphanumeric edited input field. Zeros are moved to each numeric and numeric edited input field. Input fields are identified by the word TO in their Screen Section entry.
  3. The AT, LINE, and COLUMN phrases describe the starting location of the screen item. These phrases are described in detail in Common Screen Options. If either the line or column number is missing or zero, line or column number 1 (one) is used.
Parent topic: DISPLAY Statement


DISPLAY WINDOW

Format 3

DISPLAY WINDOW creates and displays a subwindow.

DISPLAY {SUBWINDOW}
        {WINDOW   }

 [ UPON new-window ]

Remaining phrases are optional, can appear in any order.

AT screen-loc

AT LINE NUMBER line-num

AT {COLUMN  } NUMBER col-num
   {COL     }
   {POSITION}
   {POS     }

SIZE length

LINES height

{ERASE} SCREEN
{BLANK}

{REVERSE-VIDEO}
{REVERSE      }
{REVERSED     }

WITH {COLOR } color-val
     {COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{BACKGROUND-HIGH    }
{BACKGROUND-LOW     }
{BACKGROUND-STANDARD}

BOXED
SHADOW
[TOP   ] [CENTERED] TITLE IS title
[BOTTOM] [LEFT    ]
         [RIGHT   ]

WITH NO SCROLL
WITH NO WRAP
CONTROL VALUE IS control-val

POP-UP AREA IS save-area

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. new-window is a USAGE HANDLE or PIC X(10) data item. If used, the UPON phrase must be the first optional phrase specified.
  3. screen-loc is an integer data item or literal containing exactly 4 or 6 digits. It may also be a group item of 4 or 6 characters. If a numeric item is used, it must be a non-negative integer.
  4. line-num, col-num, length, and height are numeric data items or literals. They may be non-integer values. You can also specify the value of any of these items with an arithmetic expression.
  5. color-val is a numeric data item or literal. It can also be an arithmetic expression, except when used in the Screen Section.
  6. fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. See Common Screen Options for more information on color settings and values.
  7. title is an alphanumeric literal or data item.
  8. control-value is a numeric expression.
  9. save-area is a USAGE HANDLE or PIC X(10) data item.
  10. If the UPON phrase is specified, it must be the first optional phrase.
  11. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  12. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  13. The POP-UP phrase may be specified anywhere in the statement after the required initial elements.
  14. WINDOW and SUBWINDOW are synonymous. The SUBWINDOW synonym is available to improve code clarity. Its use makes it clear that a SUBWINDOW is created.
  15. IS and "=" are synonymous.
  16. COLUMN, COL, POSITION, and POS are equivalent.
  17. BLANK and ERASE are equivalent.
  18. HIGHLIGHT, HIGH, and BOLD are synonymous.
  19. LOWLIGHT and LOW are equivalent.
  20. UNDERLINE and UNDERLINED are equivalent.
  21. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  22. COLOR and COLOUR are synonymous.
  23. FOREGROUND-COLOR and FOREGROUND-COLOUR are synonymous.
  24. BACKGROUND-COLOR and BACKGROUND-COLOUR are synonymous.
  25. The LINES phrase can take a numeric expression.

General Rules

  1. The DISPLAY SUBWINDOW verb creates or modifies the current subwindow. The subwindow is a rectangular region of the screen. In essence, the current subwindow defines a virtual terminal screen that occupies some area of the user's physical screen. Line and column numbers for ACCEPT and DISPLAY statements are computed from the upper left-hand corner of the current subwindow. For example, the statement DISPLAY SPACE, ERASE SCREEN erases only the current subwindow.
  2. When used with floating windows (Format 11), this verb creates a subwindow in the current floating window. Note that every floating window has an implicit subwindow. Each time a floating window is made current, its subwindow is also made current.
  3. When used with floating windows, subwindow coordinates are relative to the current floating window. Initially, this is the main application window. The subwindow never extends past the boundaries of the current floating window.
  4. The initial subwindow is set to the entire screen. When created inside a floating window, the subwindow is set to the floating window's display area (the area inside the borders, menu bar, toolbar, and title bar).
  5. Any subwindows contained in a floating window are automatically closed if the floating window is closed.
LINE NUMBER Phrase
  1. The LINE NUMBER phrase sets the top line of the subwindow. In this context, line number one refers to the top line of the current floating window.
  2. If this phrase is missing, then the top line of the current floating window is used.
COLUMN NUMBER Phrase
  1. The COLUMN NUMBER phrase sets the leftmost column of the window. Column number one refers to the left side of the current floating window.
  2. If this phrase is not specified, column number one is used.
AT Phrase

The AT phrase sets both the starting line and column number. The line and column numbers arrived at are interpreted as described in the LINE NUMBER and COLUMN NUMBER sections described above. See Common Screen Options for more information.

SIZE Phrase
  1. The SIZE phrase sets the number of columns the subwindow will contain. If this causes the window to extend past the right edge of the current floating window, the subwindow's width is adjusted to fit.
  2. If this phrase is missing, the subwindow extends to the right edge of the current floating window.
LINES Phrase
  1. The LINES phrase sets the number of rows the subwindow will contain. If this causes the window to extend past the bottom of the current floating window, the height will be adjusted to fit.
  2. If this phrase is missing, the subwindow extends to the bottom edge of the current floating window.
  3. The LINES phrase of a DISPLAY WINDOW, DISPLAY LINE, or DISPLAY BOX verb can take a numeric expression.
ERASE Phrase
  1. When the ERASE phrase is specified, the window will be cleared immediately after it is created. Otherwise the window's contents will not be changed. When a window is cleared, it is set to spaces with the current foreground and background colors.
  2. This phrase is implied by the BOXED and REVERSED phrases.
BOXED Phrase
  1. The BOXED phrase causes a box to be drawn around the new window. The box is drawn outside of the window. Any portions of the box that lie off the screen will not be drawn.
  2. The terminal's line drawing set is used to draw the box. If the terminal does not have a line drawing set, hyphens and vertical bar characters are used.
  3. If the POP-UP phrase is also specified, the box will overlay any other boxes on the screen. If this phrase is not specified, the box drawn will be attached to any other boxes it intersects.
  4. This phrase implies the ERASE phrase.
REVERSED Phrase
  1. The REVERSED phrase exchanges the window's foreground and background colors. This will affect every ACCEPT and DISPLAY statement in the new window.
  2. This phrase implies the ERASE phrase. Note that this will usually cause the entire window to be set to reverse video spaces when it is initially created.
COLOR Phrase
  1. The COLOR phrase sets the window's foreground and background colors. These colors are used whenever the window is erased and as default colors for future ACCEPT and DISPLAY statements. Color-val contains a numeric representation of the colors to use. See Common Screen Options for more information on setting numeric values for colors.
  2. If the foreground color is not specified, the new window inherits the current window's foreground color. If the background color is not specified, the new window inherits the current window's background color.
  3. You may use the WINDOW_INTENSITY configuration variable to control whether the intensity information in the COLOR setting should be used or ignored (see Appendix H for details).
HIGH, LOW, and STANDARD Phrases

The HIGH, LOW, and STANDARD phrases set the foreground intensity of the subwindow. This affects any drawing done to the subwindow itself (such as its border or title). In addition, they set the default intensity for any future ACCEPT/DISPLAY statements made to this window.

The STANDARD option indicates that a system-dependent default value should be used. You can affect this value with the FOREGROUND-INTENSITY configuration option.

If no option is given, the current subwindow's foreground intensity is used (inherit the foreground intensity of the parent).

BACKGROUND-HIGH, BACKGROUND-LOW, and BACKGROUND-STANDARD Phrases

The BACKGROUND-HIGH, BACKGROUND-LOW, and BACKGROUND-STANDARD phrases set the background intensity for the subwindow. This works in a fashion analogous to the foreground intensity described above. Note that the COLOR phrase, if present, takes precedence over the BACKGROUND phrases.

CONTROL VALUE Phrase

The CONTROL VALUE phrase provides a method for specifying certain window characteristics at run time. control-value must be a numeric expression that contains one or more of the following values added together:

Boxed | 1
Shadow | 2
No Scroll | 4
No Wrap | 8
Reverse | 16
TITLE Phrase
  1. The TITLE phrase causes a title to be printed in the window's border. This has effect only if the BOXED phrase is also specified.
  2. One top title and one bottom title may be specified for each window. Top titles can be placed in one of three positions in the border region: top left, top center, or top right. Bottom titles can be placed in the bottom left, bottom center, or bottom right. If TOP or BOTTOM is not specified, TOP is used. If LEFT, CENTERED, or RIGHT is not specified, CENTERED is used.
NO SCROLL and NO WRAP Phrases
  1. Specifying NO SCROLL disables automatic scrolling for the new window. Normally, when the cursor is moved past the bottom edge of the window, the window is scrolled up one line. If NO SCROLL is specified, then the window will not be scrolled. The bottom line will be overwritten instead. When NO SCROLL is specified, then the only way to scroll a window is explicitly with a SCROLL phrase on a Format 1 DISPLAY statement.
  2. Specifying NO WRAP disables line wrap for the window. Normally, a line that extends past the right edge of the window is wrapped around to the next line. If NO WRAP is specified, then the line is truncated instead. This will leave the cursor logically positioned on the same line just to the right of the window's edge. Further output will not be visible until the cursor is repositioned inside the window.
  3. The scroll and wrap states of the current window are saved when a pop-up window is created. When that pop-up window is closed, the scroll and wrap states of the old window are restored.
  4. Note that the ACUCOBOL-GT runtime system contains two configuration variables, SCROLL and WRAP, that control the scroll and wrap states of all windows. When these variables are set to zero, then scrolling or wrapping for all windows is disabled regardless of the scroll and wrap states of the individual windows. When these variables are non-zero, then the window's individual states determine the use of scrolling and wrapping.
POP-UP AREA Phrase
  1. The POP-UP AREA phrase causes the screen manager to save information about the current subwindow prior to creating the new window. This information can be used by the screen manager later to remove the new window and restore the saved window. This is meant to be used to create pop-up windows.
  2. Boxed pop-up windows are automatically detached slightly from any intersecting line segments, such as the borders of other windows.
  3. The save-area is an elementary data item described by a PICTURE X(10) clause. It is filled in with information about the current window dimensions and contents before the new window is created. This data item is required for restoration of a window and must not be subsequently modified in any way. It can be referenced in a CLOSE WINDOW verb to restore the saved window to the screen and re-establish the saved window as the current window.
  4. Pop-up subwindows are an older technology that is not compatible with graphical controls. You should avoid using pop-up windows if you also use controls. Use floating windows instead.
SHADOW Phrase

The SHADOW phrase causes the window to appear to float over the screen, giving it a three-dimensional effect.

The way the shadow is displayed is determined by the SHADOW-STYLE setting of the SCREEN option in your runtime configuration file.

When a shadow is specified for a window, that window is automatically detached slightly from any intersecting line segments, such as the borders of other windows.

Note: Phrases not described above are described in Common Screen Options.
Parent topic: DISPLAY Statement


DISPLAY SCREEN SIZE

Format 4

DISPLAY SCREEN SIZE shifts the display between 80 and 132 column mode

DISPLAY SCREEN SIZE  {80 }
                     {132}

   [ ON EXCEPTION statement-1 ]

   [ NOT ON EXCEPTION statement-2 ]

   [ END-DISPLAY ]

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. statement-1 and statement-2 are imperative statements.

General Rules

  1. The DISPLAY SCREEN verb is used to shift between the 80-column mode and 132-column mode of the terminal. On character-based systems, the terminal is physically set to either 132- or 80-column mode. For all systems, the main application window is then set to 132 columns wide; it is cleared, and its subwindow set to cover the entire interior. Some graphical systems simulate 132-column mode by scrolling the main application window.

    In graphical environments, the MODIFY verb is the preferred method for changing the size of a graphical screen.

  2. If the terminal hardware does not support the mode shifted to, the screen and current window do not change and the EXCEPTION phrase statement-1 (if specified) executes. If the mode change is successful and the NOT EXCEPTION phrase is used, statement-2 executes.
Parent topic: DISPLAY Statement


DISPLAY LINE

Format 5

DISPLAY LINE draws a horizontal or vertical line on the screen.

DISPLAY LINE
 [ UPON new-window ]

   { SIZE length  }
   { LINES height }

Remaining phrases are optional, can appear in any order.

AT screen-loc

AT LINE NUMBER line-num

AT {COLUMN  } NUMBER col-num
   {COL     }
   {POSITION}
   {POS     }

{REVERSE-VIDEO}
{REVERSE      }
{REVERSED     }

WITH {COLOR } color-val
     {COLOUR}

[CENTERED] TITLE IS title
[LEFT    ]
[RIGHT   ]

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. new-window is a USAGE HANDLE or PIC X(10) data item. If used, the UPON phrase must be the first optional phrase specified.
  3. screen-loc is an integer data item or literal containing exactly 4 or 6 digits. It may also be a group item of 4 or 6 characters. If a numeric item is used, it must be a non-negative integer.
  4. line-num, col-num, length, and height are numeric data items or literals. They may be non-integer values. You can also specify the value of any of these items with an arithmetic expression.
  5. color-val is a numeric data item, literal, or arithmetic expression.
  6. Title is an alphanumeric literal or data item.
  7. If the UPON phrase is specified, it must be the first optional phrase.
  8. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  9. Exactly one of the SIZE or LINES phrases must be specified. The selected phrase may appear anywhere in the statement.
  10. The LINES phrase can take a numeric expression.
  11. IS and "=" are synonymous.
  12. COLUMN, COL, POSITION, and POS are equivalent.
  13. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  14. COLOR and COLOUR are synonymous.

General Rules

  1. The DISPLAY LINE verb provides the ability to draw horizontal and vertical lines in a machine- and terminal-independent fashion. The lines are drawn using the best mode available on the display device. Used together with the DISPLAY BOX verb, this verb provides the ability to draw forms on the user's screen.

    DISPLAY LINE is an older, character-based technology. If you want fine control over lines displayed on graphical systems, use the BAR control instead. See Control Types Reference in User Interface Programming for more information.

  2. The appropriate intersection character (corner or three-way intersection) is used when drawn lines intersect other lines on the screen.
  3. If the SIZE phrase is specified, the line drawn is horizontal. The value of length gives the size of the line in screen columns. If the LINES phrase is used instead, the line drawn is a vertical line and height describes the number of screen rows to use.
  4. Lines never wrap around or cause scrolling. If the LINES or SIZE phrase would cause the line to leave the current window, the line is truncated at the edge of the window.
AT, LINE, and COLUMN Phrases
  1. The value of line-num gives the starting row of the line. The value of col-num gives the starting column. The value of screen-loc gives the starting row and column. Lines are always drawn to the right or downwards as appropriate. screen-loc, line-num, and col-num must specify a position that is contained in the current window. See Common Screen Options for more information.
  2. If the LINE NUMBER phrase is not specified, line one is used. If the COLUMN NUMBER phrase is missing, column one is used.
TITLE Phrase
  1. The TITLE phrase has effect only when you are drawing horizontal lines. When it is specified, title-string is printed in part of the line.
  2. The title may be printed near the right side, near the left side, or in the center of the line depending whether the RIGHT, LEFT, or CENTERED phrase is specified. If none is specified, CENTERED is used.
COLOR and REVERSE Phrases

The COLOR and REVERSE phrases operate in the same manner as described in Common Screen Options. Note, however, that the COLOR value may not specify blinking, underlining, or an intensity. Lines are always drawn in a terminal-dependent intensity.

Note: Phrases not described above are described in Common Screen Options.
Parent topic: DISPLAY Statement


DISPLAY BOX

Format 6

DISPLAY BOX draws a box on the screen.

DISPLAY BOX
 [ UPON new-window ]

Remaining phrases are optional, can appear in any order.

AT screen-loc

AT LINE NUMBER line-num

AT {COLUMN  } NUMBER col-num
   {COL     }
   {POSITION}
   {POS     }

SIZE length

LINES height

{REVERSE-VIDEO}
{REVERSE      }
{REVERSED     }

WITH {COLOR } color-val
     {COLOUR}

[TOP   ] [CENTERED] TITLE IS title
[BOTTOM] [LEFT    ]
         [RIGHT   ]

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. new-window is a USAGE HANDLE or PIC X(10) data item. If used, the UPON phrase must be the first optional phrase specified.
  3. screen-loc is an integer data item or literal containing exactly 4 or 6 digits. It may also be a group item of 4 or 6 characters. If a numeric item is used, it must be a non-negative integer.
  4. line-num, col-num, length, and height are numeric data items or literals. They may be non-integers, but only the integer value will be applied. You can also specify the value of any of these items with an arithmetic expression.
  5. color-val is a numeric data item, literal, or arithmetic expression.
  6. Title is an alphanumeric literal or data item.
  7. If the UPON phrase is specified, it must be the first optional phrase.
  8. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  9. The LINES phrase can take a numeric expression.
  10. IS and "=" are synonymous.
  11. COLUMN, COL, POSITION, and POS are equivalent.
  12. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  13. COLOR and COLOUR are synonymous.

General Rules

  1. The DISPLAY BOX verb provides the ability to draw a box in a machine- and terminal-independent manner. The best drawing mode of the display device is used. If the lines used in drawing a box intersect other lines already present on the screen, the appropriate intersection characters are used.
  2. DISPLAY BOX is an older, character-based technology. For fine control of boxes on graphical systems, use the FRAME control. See Control Types Reference in User Interface Programming for more information.
  3. You specify the location of the box by providing the location of the upper-left corner. You specify the size of the box by providing a height and a width.
AT, LINE, and COLUMN Phrases

The AT, LINE NUMBER, and COLUMN NUMBER phrases operate in the same manner as they do when they are used in a DISPLAY LINE statement (Format 5).

SIZE and LINES Phrases

The SIZE phrase specifies the width of the box. The LINES phrase specifies its height. Length and height must specify values greater than one. If the SIZE phrase is absent, the box will extend to the right edge of the current window. If the LINES phrase is missing, the box will extend to the bottom of the current window.

COLOR and REVERSE Phrases

The COLOR and REVERSE phrases operate in the same manner as described in Common Screen Options. Note that the COLOR value may not specify blinking, underlining, or an intensity (boxes are always drawn in a terminal-dependent intensity).

TITLE Phrase

The TITLE phrase operates in the same manner as it does for a DISPLAY WINDOW verb (Format 3).

Note: Phrases not described above are described in Common Screen Options.
Parent topic: DISPLAY Statement


DISPLAY UPON WINDOW TITLE

Format 7

DISPLAY UPON WINDOW TITLE modifies a subwindow's title

DISPLAY source UPON WINDOW [TOP   ] [CENTERED] TITLE
                           [BOTTOM] [LEFT    ]
                                    [RIGHT   ]

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. source is an alphanumeric data item or nonnumeric literal.

General Rules

  1. The DISPLAY UPON WINDOW TITLE verb is used to modify a boxed subwindow's title. Either the top or bottom title may be modified.
  2. If any of the positioning phrases is used, the new title is placed in the indicated position.
  3. If neither the TOP/BOTTOM nor the CENTERED/LEFT/RIGHT option is used, then the window's title is modified in its current position. If the window has both a top and bottom title, the top title is modified.
  4. If the TOP/BOTTOM phrase is omitted, TOP is implied.
  5. If the CENTERED/LEFT/RIGHT phrase is not used, CENTERED is implied.
Parent topic: DISPLAY Statement


DISPLAY UPON COMMAND LINE

Format 8

DISPLAY UPON COMMAND LINE changes the contents of the command-line buffer

DISPLAY cmd-line UPON COMMAND-LINE

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. cmd-line is an alphanumeric data item or nonnumeric literal.

General Rules

  1. The DISPLAY UPON COMMAND-LINE verb is used to move the contents of an alphanumeric data item into the buffer where the command line is stored. The command line is not re-executed. The only effect of this verb is that it changes the value that will be returned by subsequent ACCEPT FROM COMMAND-LINE statements.
  2. You can also access the command-line buffer from a C program. The buffer is an external data array named Acmd_line.
Parent topic: DISPLAY Statement


DISPLAY src-item ANSI format

Format 9

DISPLAY src-item (ANSI format) sends data directly to the screen without using the ACUCOBOL-GT window manager.

DISPLAY {src-item} ... [ UPON mnemonic-name ] [ WITH NO ADVANCING ]

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. src-item is a literal or data item that specifies the data to be displayed. It must be USAGE DISPLAY unless the CONVERSION phrase or the Vd compiler option is specified. Note that by default the screen is cleared when the program starts. If you specify the Ca compiler option, the screen is not cleared until the first DISPLAY statement with the CONVERSION phrase is executed. If you want the conversion to take place without the screen being cleared, you must specify the Ca and Vd options without the CONVERSION phrase on the DISPLAY statement.
  3. Mnemonic-name must be a user-defined word declared in Special-Names that refers to a display device, or it must be the name of the display device itself. See Special-Names Paragraph for a list of valid devices.
  4. If the UPON phrase is specified it must be the first optional phrase.
  5. If the UPON phrase is omitted, then the -Ca compiler option must be specified. If it is not, then the statement is treated as a Format 1 DISPLAY statement instead.

General Rules

  1. The data contained in src-item is sent to the output device named by the UPON phrase. If the UPON phrase is omitted, the output device is assumed to be the user's console.
  2. If the WITH NO ADVANCING phrase is omitted, then the device is advanced to the next line after the last src-item is displayed. If WITH NO ADVANCING is specified, no additional action takes place after the data is sent to the output device. If line advancing is used, trailing spaces are removed from the last src-item before it is sent to the device.
  3. If the output device is any of the following, the data is sent to the user's console:
    CONSOLE, SYSOUT, SYSLST, SYSLIST

    This data may be redirected with the -o runtime option or with operating system commands. If line advancing is used, the system's output buffer is flushed, but if NO ADVANCING is specified, then the buffer is not flushed. When data is sent to these devices, no editing or formatting of the data occurs.

  4. If the output device is SYSOUT-FLUSH, the data is sent to the user's console. After the last src-item is sent, the output buffer is flushed, forcing the data to be sent immediately. No editing or formatting of the data occurs.
  5. If the output device is SYSERR, the data is sent to the runtime's error output. This is either the user's screen or the file specified in the -e runtime option.
  6. Technical Note: This form of the DISPLAY statement sends data directly to the user's screen without using ACUCOBOL-GT's window manager. On many machines, the window manager maintains an image of the user's screen in memory. (This improves efficiency by omitting redundant screen displays and is used to implement pop-up windows.) By sending data directly to the screen, you can cause the window manager's screen image to be in error. This can cause strange effects when mixed with ACUCOBOL-GT-specific DISPLAY statements, including:
    • lost data
    • incorrect functioning of CLOSE WINDOW
    • incorrect cursor position
    • incorrect character attributes
    • incorrect display in debugger

    For these reasons, you must be careful when using ANSI DISPLAY. Here are some useful guidelines:

    • If your DISPLAY does not affect the screen image, then it's OK to use it. For example, you can use ANSI DISPLAY to send a control sequence to an attached printer or cash register.
    • If you use only ANSI DISPLAY statements, then you should not experience any problems (except that the debugger will not be able to restore the user's screen). With this approach, you should avoid all DISPLAY statements except for Format 9.
    • If you must mix formats, then you can use the library routine W$FORGET to correct the behavior of the window manager. This routine causes the window manager to enter its initial state, where it does not know the screen image or current attribute settings. If you call this routine after a series of Format 9 DISPLAY statements, the window manager will be set to a state where it can correctly manage the screen. Note that this routine will cause the cursor to be positioned to the last line on the screen.
    • You can always use UPON SYSERR safely. When sent to the screen, the output is directed through the window manager. Normally, you would use this with the -e runtime option to direct error messages to an error log file.
    • In the DOS/VS COBOL compatibility mode, output may be sent to a simulated card punch. See ACUCOBOL-GT and IBM DOSVS COBOL-Specific Features in Transitioning to ACUCOBOL-GT for more information.
Parent topic: DISPLAY Statement


DISPLAY UPON GLOBAL TITLE

Format 10

DISPLAY UPON GLOBAL TITLE changes the title of the application window in a graphical user interface, or the title of a floating window.

DISPLAY title-1 UPON { FLOATING WINDOW handle-1 } TITLE
                     { GLOBAL WINDOW            }

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. title-1 is an alphanumeric literal or identifier that contains the new title.
  3. handle-1 is the handle of the floating window in which the new title is applied.
  4. If the UPON phrase is specified, it must be the first optional phrase.

General Rules

  1. DISPLAY UPON FLOATING WINDOW TITLE is used to change the title of the main application window or floating window. When you are changing a floating window's title, handle-1 identifies which window to change.
  2. The case of the title will be exactly as given in title-1.
  3. Alternatively, you can use the MODIFY verb to change a window's title.
Parent topic: DISPLAY Statement


DISPLAY FLOATING WINDOW

Format 11

DISPLAY FLOATING WINDOW creates and displays a floating window.

DISPLAY FLOATING [GRAPHICAL] WINDOW
 [ UPON parent-window ]

Remaining phrases are optional, can appear in any order.

{MODELESS}
{MODAL   }

{LINK} TO THREAD
{BIND}

SCREEN LINE NUMBER screen-line

SCREEN {COLUMN  } NUMBER screen-col
       {COL     }
       {POSITION}
       {POS     }

AT screen-loc

AT LINE NUMBER line-num

AT {COLUMN  } NUMBER col-num
   {COL     }
   {POSITION}
   {POS     }

SIZE  length

LINES height

FONT {IS} font-1
     {= }

CONTROL FONT {IS} font-3
             {= }

CELL
 {SIZE  }  [IS] {cell-units                                 }
 {HEIGHT}  [= ] {control-type-name  FONT font-2 [SEPARATE  ]}
 {WIDTH }       {control-type-name  FONT        [OVERLAPPED]}

{ERASE} SCREEN
{BLANK}

{REVERSE-VIDEO}
{REVERSE      }
{REVERSED     }

WITH {COLOR } color-val
     {COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{BACKGROUND-HIGH    }
{BACKGROUND-LOW     }
{BACKGROUND-STANDARD}

{ [USER-GRAY] [USER-WHITE] }
{        USER-COLORS       }

BOXED
SHADOW
TITLE-BAR
[TOP   ] [CENTERED] TITLE IS title
[BOTTOM] [LEFT    ]
         [RIGHT   ]

WITH SYSTEM MENU
WITH NO SCROLL
WITH NO WRAP
{NO-CLOSE}

{AUTO-RESIZE}

{RESIZABLE  }

MIN-SIZE  {= } min-size
          {IS}
MAX-SIZE  {= } max-size
          {IS}
MIN-LINES {= } min-lines
          {IS}
MAX-LINES {= } max-lines
          {IS}

CONTROL VALUE {IS} control-val
              {= }

LAYOUT-MANAGER {IS} manager
               {= }

VISIBLE {IS} {TRUE         }
        {= } {FALSE        }
             {visible-state}

POP-UP MENU {IS}  {menu-1}
            {= }  {NULL}

{POP-UP AREA IS } handle-name
{HANDLE {IS}    }
        {IN}

CONTROLS-UNCROPPED
EVENT PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
                              {THRU   }
                   { NULL                        }

ACTION {IS} action
       {= }

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. parent-window is a USAGE HANDLE or PIC X(10) data item. If used, the UPON phrase must be the first optional phrase specified.
  3. screen-line and screen-col are numeric expressions.
  4. screen-loc is an integer data item or literal containing exactly 4 or 6 digits. It may also be a group item of 4 or 6 characters. If a numeric item is used, it must be a non-negative integer.
  5. line-num, col-num, length, and height are numeric data items or literals. They may be non-integer values. You can also specify the value of any of these items with an arithmetic expression.
  6. font-1, font-2, and font-3 are data items described as USAGE HANDLE or HANDLE OF FONT. They should contain valid handles to screen fonts.
  7. cell-units is a positive integer data item or literal.
  8. control-type-name is one of the control type reserved words known by the compiler.
  9. color-val is a numeric data item or literal. color-val can also be an arithmetic expression, except when used in the Screen Section.
  10. fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. See FOREGROUND-COLOR and BACKGROUND-COLOR Phrases for more information on color settings and values.
  11. min-size, max-size, min-lines, and max-lines are integer literals or data items.
  12. title is an alphanumeric literal or data item.
  13. control-value is a numeric expression.
  14. The word NO-CLOSE is reserved by the compiler only when it appears in a Format 11 or 12 DISPLAY statement.
  15. manager is a USAGE HANDLE or HANDLE OF LAYOUT-MANAGER that contains a valid reference to a layout manager.
  16. visible-state is a numeric literal or data item.
  17. menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
  18. handle-name is a USAGE HANDLE, HANDLE OF WINDOW, or PIC X(10) data item.
  19. proc-1 and proc-2 are procedure names.
  20. action is a numeric literal or data item.
  21. You must compile allowing for recursive paragraphs in order to specify the EVENT PROCEDURE phrase. Compiling for recursive paragraphs is allowed by default, but can be turned off with the -Zr0 compiler option.
  22. If the UPON phrase is specified, it must be the first optional phrase.
  23. The SCREEN LINE phrase and the SCREEN COLUMN phrase must be used together. If they are used, you cannot use the AT, LINE, or COLUMN phrases.
  24. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  25. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  26. The POP-UP/HANDLE phrase may be specified anywhere in the statement after the required initial elements.
  27. IS and "=" are synonymous.
  28. COLUMN, COL, POSITION, and POS are equivalent.
  29. BLANK and ERASE are equivalent.
  30. HIGHLIGHT, HIGH, and BOLD are synonymous.
  31. LOWLIGHT and LOW are equivalent.
  32. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  33. COLOR and COLOUR are synonymous.
  34. FOREGROUND-COLOR and FOREGROUND-COLOUR are synonymous.
  35. BACKGROUND-COLOR and BACKGROUND-COLOUR are synonymous.

General Rules

  1. The syntax for DISPLAY FLOATING WINDOW is a superset of the DISPLAY WINDOW verb. This simplifies conversion of DISPLAY WINDOW statements to DISPLAY FLOATING WINDOW statements.
  2. The DISPLAY FLOATING WINDOW verb creates a new floating window and stores a handle to the window in handle-name. Use the value of handle-name with other verbs (such as DESTROY) when you need to refer to the window.
  3. After the new window is created, it becomes both the current and active window.
  4. The window created may be either modal or modeless. A modal window is a window that the user cannot leave until it is closed. A modeless window is a window that the user can leave (switch to another window) while it is still open. These names are derived from the idea that a modal window enters a new mode in the program (for example, selecting a file to open) while a modeless window does not (since the user can continue working on tasks in other windows).
  5. The DISPLAY FLOATING WINDOW verb also creates a new subwindow that exactly covers the interior of the floating window. This is identical to an implied DISPLAY SUBWINDOW statement (with no options). Any HIGH, LOW, STANDARD, BACKGROUND-HIGH, BACKGROUND-LOW, BACKGROUND-STANDARD, REVERSE, COLOR, NO SCROLL, or NO WRAP phrases specified in the DISPLAY FLOATING WINDOW verb are inherited by the implied subwindow.
  6. Each window has a controlling thread. A window's controlling thread is the most recent thread to have created that window or done an ACCEPT from that window. When a thread performs an ACCEPT from a window, and that thread is not the controlling thread of the active window, the thread suspends. The thread remains suspended until the window it is accessing becomes active (either because the user activates it or the program does).
  7. Most of the optional phrases have the same meaning as they do for DISPLAY SUBWINDOW. However, note the following exceptions:
    1. The ERASE SCREEN phrase is always implied by DISPLAY FLOATING WINDOW, so specifying this phrase has no additional effect.
    2. Most GUIs (including Windows) cannot display shadowed pop-up windows. On these systems, the SHADOW phrase has no effect. On character-based systems, the SHADOW phrase has its normal effect.
    3. All GUIs create borders around their windows. If there is a choice of border thickness, specifying BOXED will select a thicker border than omitting BOXED. Under character-based systems, the BOXED phrase determines whether or not there will be a border.
    4. The HIGH, LOW, STANDARD, BACKGROUND-HIGH, BACKGROUND-LOW, BACKGROUND-STANDARD, REVERSE, COLOR, NO WRAP, and NO SCROLL phrases do not directly affect the created window. Instead, they are passed on to the initial subwindow as described in Rule 5, above.
    5. Most GUIs (including Windows) cannot display more than one window title and do not give you a choice of title position. On these systems, the specified TITLE appears in the location determined by the GUI (usually top center, or top left). If you specify more than one title, the TOP title is the one used. If you specify only one title (either TOP or BOTTOM), it is used regardless of the title location.
GRAPHICAL Phrase

The optional GRAPHICAL phrase directs the compiler to use a default CELL phrase equivalent to:

CELL SIZE = LABEL FONT

This phrase establishes the window's coordinate space based on the font used by controls that occupy the window. The CELL phrase can still be used and any values set in that phrase take precedence over the default value established with GRAPHICAL option. In other words, if you specify only a CELL HEIGHT or CELL WIDTH, then the other dimension receives the default assignment.

The intent of the GRAPHICAL option is to make it easier to consistently establish an appropriate coordinate space for windows that contain only controls (see the discussion of cell sizing and coordinate space that is included with the CELL phrase rules, below).

For example, the window that is specified with:

DISPLAY FLOATING WINDOW,
    CELL SIZE = LABEL FONT

can be more simply specified with:

DISPLAY FLOATING GRAPHICAL WINDOW
UPON Phrase

The UPON phrase specifies the parent of the new floating window. Parent-window must be a valid floating window handle. If the UPON phrase is omitted, the current window is used as the parent. If you create a new floating window in the scope of an UPON phrase, the new window becomes the current window when the DISPLAY statement terminates.

MODAL and MODELESS Phrases
  1. The word MODAL makes a floating window modal. Floating windows are modal by default, so this word is just commentary. When a modal window is active, all other windows are disabled. The user cannot activate another window, including any of its components (such as its menu or close button). Note, however, that while a user cannot activate another window, the program can (see Format 10 of the SET statement).
  2. The word MODELESS makes a window modeless. When a modeless window is active, the user can activate another window by using the host system's techniques for doing so (for example, by clicking on another window with the mouse). When this happens, any ACCEPT that is active is terminated by a CMD-ACTIVATE event. Your program should respond by performing an ACCEPT in the window requested by the user. Alternatively, you can link your modeless window to a thread, see rule 1 under LINK TO THREAD and BIND TO THREAD Phrases (below).
LINK TO THREAD and BIND TO THREAD Phrases
  1. The LINK TO THREAD phrase allows the runtime to automate the handling of the CMD-ACTIVATE event. If the user activates a window created with the LINK TO THREAD phrase, the runtime will examine that window to see if it has a controlling thread different from the current thread. If it does, then the current thread suspends and the thread controlling the newly active window is allowed to run. The runtime handles all aspects of the window activation. The CMD-ACTIVATE event is not returned to the program in this case. If the controlling thread of the new window is the same as the current thread, then the runtime does not perform any special handling and the CMD-ACTIVATE event is passed on to your program. In order to get the best benefit from the LINK TO THREAD phrase, you should arrange to have a separate thread control each modeless window in your program.
  2. The BIND TO THREAD phrase has the same effect as the LINK TO THREAD phrase. In addition, the window is automatically destroyed when its controlling thread terminates.
SCREEN LINE and SCREEN COLUMN Phrases

The SCREEN LINE and SCREEN COLUMN phrases determine the initial location of the window on the screen. screen-line and screen-col give the coordinates of the upper left corner of the window in screen base units. Screen base units are machine dependent. On character systems, they are character cells. On graphical systems, they are pixels. The upper left corner of the screen is location 1,1. Under Windows, the runtime ensures that the initial window is fully visible, so the specified location may not be used if that would place a portion of the window off the screen (the closest allowed location is used). Windows other than the initial window may be placed arbitrarily. On graphical systems, the location of a floating window is interpreted to mean the location of its exterior. On character systems, the location is the same as it is for subwindows: the location of the window's interior.

LINE, COLUMN, and AT Phrases
  1. The LINE phrase indicates the starting row of the new window. This is always relative to the first line of the parent window. Non-integer values are allowed. If the LINE phrase is omitted, then the new window is first centered vertically over the parent window and then adjusted to be fully on the screen.
    Note: This rule differs from the handling of DISPLAY SUBWINDOW. With DISPLAY SUBWINDOW, omitting the LINE phrase is the same as specifying LINE 1.

    In all cases, the positioning is relative to the parent window as physically displayed on the screen, ignoring any aspect of the window not currently displayed. Thus, if the current window is the main application window, and that window has been scrolled by the user, line 1 refers to the first line of the physical window--not the (undisplayed) first line of the main application window.

  2. The COLUMN phrase works analogously to the LINE phrase, except that it controls the horizontal positioning.
  3. The AT phrase screen-loc item must be either a 4-digit or 6-digit number. The first half of this number is the starting row, the second half the starting column. These values are interpreted in the same manner as they are for the LINE and COLUMN phrases. A value of zero is treated as zero (i.e., AT 0000 is equivalent to ROW 0, COL 0).
SIZE and LINES Phrases
  1. The SIZE phrase indicates the width of the interior of the new window. If it is omitted, then the width is the same as the main application window. If there is no main application window available, the default size of the floating window is the same as the current window.
    Note: A non-integer SIZE is allowed. If the SIZE is not an integer, then the partial column created cannot be used to display textual characters; however, graphical controls can be located there. The partial column is always shown as spaces with the floating window's background color. The minimum SIZE value allowed is 1. The runtime currently limits the maximum size to 132 columns.
  2. The LINES phrase indicates the height of the new window's interior. If it is omitted, then the height is the same as the main application window. As with the SIZE phrase, a non-integer number of lines may be specified. Any partial lines created are always displayed as spaces with the background color. The minimum value for LINES is 1 (one). The runtime currently limits the maximum size to 200 lines.
FONT Phrase

The FONT phrase assigns the font that will be used for all textual ACCEPT and DISPLAY statements used in the window. This also sets the default cell size to the size of the 0 (zero) character described by font-1. The cell size determines the height of one row and the width of one column. The font described by font-1 must be a fixed-width font. If it is not, or if the FONT phrase is not specified, then the font used is the same as the one used by the parent window.

CONTROL FONT Phrase

The CONTROL FONT phrase specifies the default font to use for any graphical controls displayed in this window. If you omit the CONTROL FONT phrase, a system default is used (the font DEFAULT-FONT).

CELL Phrase

The CELL phrase defines the height, or width, or height and width of one cell in the window. A cell defines the height of one row and the width of one column. The default cell size is set by the size of the font used in the window.

The cell size is described in terms of cell units. The exact meaning of a cell unit is machine-dependent. Typically, for character-based systems, one cell unit is equal to the height or width (as appropriate) of one screen character. On graphical systems, a cell unit is typically one pixel in size. When developing programs, you should avoid writing code that depends on fixed (hard-coded) values for cell units.

The HEIGHT option of the CELL phrase defines the cell height for the new window. The WIDTH option defines the width. The SIZE phrase defines both the height and width together.

The cell-units option sets the cell's height, or width, or both, to the value of cell-units.

The control-type-name phrase causes the cell height, or width, or both, to be based on a particular font and control type. The system measures the size of font-2 when it is used in a control described by control-type-name, and sets the cell size accordingly. This option is typically used to set the coordinate space of the window to one that is convenient for aligning several controls of a particular type and font. Note that the font handle (font-2) is not required. When it is omitted, the window's CONTROL FONT is used. Also note that if the font handle is omitted, the optional word FONT is required (in order to avoid ambiguity with the FONT phrase).

If the SEPARATE option is specified, then a system-dependent amount is added to the measured font height to provide for some vertical separation between controls. This is typically used to provide some space between boxed entry-fields on adjacent rows. On the other hand, if OVERLAPPED is specified, the height is reduced by the size of the top border of a boxed entry field. This causes boxed fields on adjacent rows to share a common border.

The runtime currently limits control-type-name to be either a LABEL or ENTRY-FIELD. If another control type name is used, the runtime treats it as if it were type "LABEL".

If a window's cell width does not match the width of its font, or if its cell height is less than the height of its font, then the effects of a textual ACCEPT or DISPLAY statement in that window are undefined. If its cell height is larger than its font's height, then the characters are positioned at the top of each cell, and the lower portion of the cell is filled with the text's background color.

Note: The purpose of the CELL phrase is to simplify the construction of windows that contain only controls. We strongly recommend that you use it (or the GRAPHICAL phrase described above) whenever you create a window that will only contain controls. If you do not, your screens will be less portable.

In particular, if the relative size of the font you use in your controls changes in relation to the system's fixed font, then you will experience problems, including overlapping controls. This is because the default cell size that defines the coordinate space is based on a fixed-size font in order to maintain compatibility with character-based applications. The size relationship between the variable-pitch font used in controls and the default fixed-font that defines the coordinate space determines the appearance of the screen. If the relationship changes, the appearance of the screen changes. One way that this can happen is if the end user's machine is missing one of the fonts. In this case, Windows will substitute a different font, which may be a different size. To avoid these problems, define your coordinate space based on the same font that your controls use (with the CELL phrase). Then if the font changes the entire screen is rescaled uniformly.

For example, the following statement defines the coordinate space based on the font used with entry fields. This definition allows you to easily position entry fields vertically with LINE 1, LINE 2, etc., and have it look right.

  CELL SIZE IS ENTRY-FIELD FONT SEPARATE
USER-GRAY, USER-WHITE, and USER-COLORS Phrases

The USER-GRAY, USER-WHITE, and USER-COLORS phrases provide a convenient way of matching your application's normal colors to those chosen by the user. The USER-GRAY option causes the palette manager to map color number 8 (low-intensity white) to the color that the user has chosen to use with 3-D objects on the host system. Similarly, USER-WHITE maps color number 16 (high-intensity white) to the color the user has chosen to be the normal background color for application windows. If you arrange your application so that it uses color number 8 as the background for regions populated with graphical controls, and color number 16 for plain text regions, your application will look much like other applications on the system.

The USER-COLORS phrase indicates that you want to apply both the USER-GRAY and USER-WHITE options. These phrases are effective only on host graphical systems that have a palette manager. On other systems, these phrases have no effect. Also, note that the palette applies to the entire application. Because of this, you usually specify these options only on the first window you create.

Note: Because Windows make abundant use of 3-D effects in displaying controls, we strongly suggest that you use the USER-GRAY or USER-COLORS options for programs with graphical controls that run under Windows. Graphical controls look best when placed on a "gray" background (color number 8). Other color choices may make 3-D controls look odd.
TITLE-BAR Phrase

The TITLE-BAR phrase indicates that you want to have a title bar placed along the top edge of the new window. This phrase is automatically implied by the TITLE phrase (exception: this is not true if you also use the CONTROL VALUE phrase). Under some GUIs (including Windows), you must place a title bar in order to move the floating window with the mouse. Without a title bar, the user's ability to move the window depends on the host GUI. Note that you can have a title bar without specifying a title.

SYSTEM MENU Phrase

The SYSTEM MENU phrase causes a system menu (also known as a close box) to appear on the created window. This menu allows the user to close the floating window. It may also have additional properties depending on the host system. Under Windows, this menu contains the Move and Close operations. If you include a system menu, your program must be ready to act on a close window event (cmd_close) at any time. See Configuration Section, and Events Reference, in User Interface Programming for more information. See QUIT_MODE Appendix H for shutdown handling options. Note that the SYSTEM MENU phrase also implies the TITLE-BAR phrase.

NO-CLOSE Phrase

The NO-CLOSE phrase causes the window's Close menu option to be disabled. This option can be applied only when the window is created and its effects cannot be reversed (the associated window's Close option is permanently disabled). The NO-CLOSE option takes precedence over other settings, including the setting of the QUIT_MODE configuration variable.

AUTO-RESIZE and RESIZABLE Phrases
  1. The AUTO-RESIZE phrase specifies that the window be displayed with resizable borders. When the window is created, it is displayed full size as defined by the SIZE and LINES phrases. By dragging the resizable borders the user can reduce or increase the size of the window. The runtime automatically adds scroll bars as needed and manages any required scrolling. The window also has a maximize button that allows the user to immediately resize the window to its full size. The exact representation and functioning of the resizable borders and the maximize button is host system dependent. Although the user can change the physical size of the window, the logical size does not change. Neither do controls in the window change size or position. If AUTO-RESIZE is omitted, the window is a fixed size.
  2. The RESIZABLE phrase creates a window that the user can resize but omits the automatic handling provided by the AUTO-RESIZE phrase. When the user resizes the window, the size of the logical window is changed to match the new physical window. Any area that is new is displayed with spaces in the window's background color. Any area that has been removed is lost (although any permanent controls in that area will still exist). The window's subwindow is resized to fill the interior of the resized window. The subwindow's background color is changed to match the window's background color. Other traits of the subwindow remain unchanged. The program receives a NTF-RESIZED event to inform it of the new size. Windows that have the RESIZABLE attribute can use a resize layout manager to help handle the resizing and positioning of controls in the window. See The Resize Layout Manager for more information.
  3. For windows with the RESIZABLE phrase, min-size and min-lines set the windows' smallest width and height respectively. This value is expressed in character cells (fractional cells are ignored). If omitted, or set to zero, the smallest window size is determined by the host system. Similarly, the max-size and max-lines values set the window's largest width and height. If omitted, or set to zero, the host system determines the largest size (usually the entire screen). For windows without the RESIZABLE phrase, these values are ignored.
    Note: Adding or removing a menu or toolbar from a window normally causes the window to be resized to maintain its interior dimensions. For windows with the RESIZABLE phrase, the window is not resized. Instead, the interior dimensions are reduced or increased as needed. You should either modify the window to be the desired size, or inquire the current dimensions when you add or remove a menu or toolbar for resizable windows.
ACTION Phrase
  1. The ACTION phrase allows you to programmatically maximize, minimize, or restore a window. To use ACTION, assign it one of the following values (these names are found in acugui.def):
    ACTION-MAXIMIZE | maximizes the window. It has the same effect as if the user clicked the maximize button. Allowed only for windows that have RESIZABLE or AUTO-RESIZE specified or implied for them.
    ACTION-MINIMIZE minimizes the window. Allowed only with INDEPENDENT windows that have the AUTO-MINIMIZE property set to true. It is not supported with other types of floating windows; if set, it is ignored by the runtime.

    ACTION-MINIMIZE has the same effect as if the user clicked the minimize button.

    ACTION-RESTORE | If the window is currently maximized or minimized, restores the window to its previous size and position; otherwise, it has no effect. Allowed only for windows that can be maximized or minimized.
  2. If you assign an ACTION value that is not allowed, then there is no effect other than to trigger the ON EXCEPTION phrase of the MODIFY statement (if present). Note that you can use the ACTION phrase to create a window that is initially maximized or minimized.
CONTROL VALUE Phrase

The CONTROL VALUE phrase allows you to specify certain attributes of the new window at run time instead of at compile time. control-val must be a numeric expression. In it, you can specify certain floating window traits by adding together any of the following values:

Boxed | 1
Shadow | 2
No Scroll | 4
No Wrap | 8
Reverse | 16
Title-Bar | 32
System Menu | 64
User-Gray | 128
User-White | 256

For each value specified, the corresponding attribute is given to the new window. When a value is not specified, the presence or absence of that trait depends on the other phrases included in the DISPLAY FLOATING WINDOW statement. Note that you can only give traits to a window with the CONTROL VALUE phrase; you cannot negate traits specified by the DISPLAY FLOATING WINDOW statement. For example, if you want to specify at run time whether or not a window gets a shadow, you should omit the SHADOW phrase from the DISPLAY FLOATING WINDOW statement and use a CONTROL VALUE phrase to add shadowing when you want it.

LAYOUT-MANAGER Phrase

The LAYOUT-MANAGER phrase attaches a layout manager to the window.

VISIBLE Phrase

The VISIBLE option determines whether the window created is visible or invisible. If the FALSE option is used, or visible-state is the value zero, then the window is invisible. Otherwise, the window is visible. If the VISIBLE phrase is omitted, then the window is visible.

POP-UP MENU Phrase

The POP-UP MENU phrase associates a pop-up menu with the window. If menu-1 is specified, then the menu associated with menu-1 becomes the pop-up menu. If NULL is specified, the window is not given a pop-up menu. Pop-up menus are activated by a machine-dependent technique. Under Windows, the technique is to right-click on the window's background.

CONTROLS-UNCROPPED Phrase

Normally, when you create a control in a window, the control is cropped to fit the current subwindow's dimensions. In addition, if the control's home position is outside of the current subwindow, the control is not created. Adding the phrase CONTROLS-UNCROPPED overrides these rules. When this phrase is used, the control is created with the specified location and dimensions, regardless of whether the control will be physically in the window.

This can be useful when you are dealing with RESIZABLE windows. Sometimes a resizable window is too small to show all of the controls that your program creates. Normally, these controls either would not be created or would be cropped. This could produce odd results when the window is later resized larger by the user. Although the resized window is now large enough to show everything, the controls still show their cropped appearance, because their (cropped) creation size is recorded in the controls as their actual size. Specifying CONTROLS-UNCROPPED avoids the cropping behavior.

This style is useful also when you want to place a combo-box near the bottom of a window. Because the size of the drop-down portion of the combo-box is determined by the control's overall height, cropping the control limits the drop-down box to the window's boundaries. If you want the box to drop down beyond the edge of the window, you need to use the CONTROLS-UNCROPPED window style to allow this.

EVENT PROCEDURE Phrase
  1. A window's event procedure is executed whenever an event is processed for that window. The event procedure is executed as if it were the target of a PERFORM statement. Only the window's own events trigger the event procedure. Events generated by controls contained in the window do not trigger the window's event procedure (they trigger the control's event procedure instead). The event procedure executes while the event is being processed, before the event causes termination of any executing ACCEPT statement. See PROCEDURE Clause for more information about event procedures.
  2. Specifying proc-1 assigns that procedure as the window's event procedure. Flow of control returns at the end of proc-1, unless proc-2 is specified, in which case flow of control returns at the end of proc-2. If you specify the NULL option, the window does not have an event procedure. This is the default, so the NULL option is treated as commentary.
Note: Phrases not described above are described in Common Screen Options.
Parent topic: DISPLAY Statement


DISPLAY INITIAL WINDOW

Format 12

DISPLAY INITIAL WINDOW creates and displays the main application window and independent windows.

DISPLAY {INITIAL    } [GRAPHICAL] WINDOW
        {STANDARD   }
        {INDEPENDENT}

Remaining phrases are optional, can appear in any order.

MODELESS
LINK TO THREAD
SCREEN LINE NUMBER screen-line

SCREEN {COLUMN  } NUMBER screen-col
       {COL     }
       {POSITION}
       {POS     }

AT screen-loc                       (independent only)
AT LINE NUMBER screen-line          (independent only)
AT {COLUMN  } NUMBER screen-col     (independent only)
   {COL     }
   {POSITION}
   {POS     }

SIZE  length

LINES height

FONT {IS} font-1
     {= }

CONTROL FONT {IS} font-3
             {= }

CELL
 {SIZE  } [IS]  {cell-units                                 }
 {HEIGHT} [= ]  {control-type-name  FONT font-2 [SEPARATE  ]}
 {WIDTH }       {control-type-name  FONT        [OVERLAPPED]}

{ERASE} SCREEN
{BLANK}

{REVERSE-VIDEO}
{REVERSE      }
{REVERSED     }

WITH {COLOR } color-val
     {COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{BACKGROUND-HIGH    }
{BACKGROUND-LOW     }
{BACKGROUND-STANDARD}

{ [USER-GRAY] [USER-WHITE] }
{        USER-COLORS       }

TITLE-BAR
[TOP   ] [CENTERED] TITLE IS title
[BOTTOM] [LEFT    ]
         [RIGHT   ]

WITH SYSTEM MENU
WITH NO SCROLL
WITH NO WRAP
{NO-CLOSE}

{AUTO-RESIZE}
{RESIZABLE  }

MIN-SIZE  {= } min-size
          {IS}
MAX-SIZE  {= } max-size
          {IS}
MIN-LINES {= } min-lines
          {IS}
MAX-LINES {= } max-lines
          {IS}

AUTO-MINIMIZE
CONTROL VALUE {IS} control-val
              {= }

LAYOUT-MANAGER {IS} manager
               {= }

VISIBLE {IS} {TRUE         }
        {= } {FALSE        }
             {visible-state}

POP-UP MENU {IS}  {menu-1}
            {= }  {NULL}

{POP-UP AREA IS  } handle-name
{HANDLE     {IS} }
            {IN}

CONTROLS-UNCROPPED
EVENT PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
                              {THRU   }
                   { NULL                        }

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. screen-line and screen-col are numeric expressions.
  3. screen-loc is an integer data item or literal containing exactly 4 or 6 digits. It may also be a group item of 4 or 6 characters. If a numeric item is used, it must be a non-negative integer.
  4. line-num, col-num, length, and height are numeric data items or literals. They may be non-integer values. You can also specify the value of any of these items with an arithmetic expression.
  5. font-1, font-2, and font-3 are data items described as USAGE HANDLE or HANDLE OF FONT. They should contain valid handles to screen fonts.
  6. cell-units is a positive integer data item or literal.
  7. control-type-name is one of the control type reserved words known by the compiler.
  8. color-val is a numeric data item or literal. color-val can also be an arithmetic expression, except when used in the Screen Section.
  9. fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. See FOREGROUND-COLOR and BACKGROUND-COLOR Phrases for more information on color settings and values.
  10. Title is an alphanumeric literal or data item.
  11. min-size, max-size, min-lines, and max-lines are integer literals or data items.
  12. control-value is a numeric expression.
  13. The word NO-CLOSE is reserved by the compiler only when it appears in a Format 11 or 12 DISPLAY statement.
  14. Manager is a USAGE HANDLE or HANDLE OF LAYOUT-MANAGER that contains a valid reference to a layout manager.
  15. visible-state is a numeric literal or data item.
  16. menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
  17. handle-name is a USAGE HANDLE, HANDLE OF WINDOW, or PIC X(10) data item.
  18. proc-1 and proc-2 are procedure names.
  19. You must compile allowing for recursive paragraphs in order to specify the EVENT PROCEDURE phrase. Compiling for recursive paragraphs is allowed by default, but can be turned off with the -Zr0 compiler option.
  20. The SCREEN LINE phrase and the SCREEN COLUMN phrase must be used together. If they are used, you cannot use the AT, LINE, or COLUMN phrases.
  21. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  22. The POP-UP/HANDLE phrase may be specified anywhere in the statement after the required initial elements.
  23. IS and "=" are synonymous.
  24. COLUMN, COL, POSITION, and POS are equivalent.
  25. BLANK and ERASE are equivalent.
  26. HIGHLIGHT, HIGH, and BOLD are synonymous.
  27. LOWLIGHT and LOW are equivalent.
  28. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  29. COLOR and COLOUR are synonymous.
  30. FOREGROUND-COLOR and FOREGROUND-COLOUR are synonymous.
  31. BACKGROUND-COLOR and BACKGROUND-COLOUR are synonymous.

General Rules

  1. The DISPLAY INITIAL WINDOW verb creates the main application window. The main application window has several special properties. If it is minimized, all other windows in the application are also minimized. If it is closed, the application terminates. A program can have only one main application window.
  2. If you attempt to create a main application window after one already exists, the DISPLAY INITIAL WINDOW statement will have no effect other than to set handle-name to NULL.
  3. The runtime automatically constructs the main application window if needed. This occurs any time a screen operation is dictated by the program and the program has not yet constructed a main application window. When this occurs, the runtime executes the following implied statement:
    DISPLAY INITIAL WINDOW
    TITLE-BAR,
    SYSTEM MENU,
    AUTO-MINIMIZE,
    AUTO-RESIZE.
  4. The main application window is always modeless. A modeless window is one where the user can switch to another window while the current window is still open. You can include the word MODELESS in the statement as commentary.
  5. The INDEPENDENT phrase creates an independent window. Independent windows act like additional main application windows. Independent windows have the following traits:
    1. Independent windows do not have a parent. As a result, any other window in the application can be placed over them. Also, destroying another window in the application will not destroy the independent window.
    2. Although they do not have a parent, independent windows use the current window to determine their default fonts, cell size, and colors. Also, independent windows use the current window when determining their position. This is computed in the same manner as it is for floating windows.
    3. Independent windows can be minimized separately. Under Windows and Windows NT, each visible independent window has its own button on the task bar.
    4. Independent windows process their close box in the same manner as floating windows--by generating a CMD-CLOSE event.
    5. Independent windows can be created before the main window. In this case, there is no current window to provide defaults, so the independent window uses the same defaults as the main application window would. The window is located on the screen as follows:

      According to SCREEN LINE and SCREEN COL, if specified; otherwise

      If the window has a title bar, the host system places the window as if it were a new application; otherwise

      The window is centered in the screen.

      Note that LINE and COL (without the SCREEN option) are ignored in these cases.

    6. If an independent window is current when the main application window is created, the defaults for the main window are derived from the independent window.
  6. Most of the phrases allowed for DISPLAY INITIAL WINDOW work in exactly the same way that they work in a DISPLAY FLOATING WINDOW (format 11) statement. The following rules are supplemental.
SCREEN-LINE and SCREEN-COLUMN Phrases

Under Windows, the runtime ensures that the initial window is fully visible, so the location specified by screen-line and screen-col may not be used if that would place a portion of the window off the screen (the closest allowed location is used).

TITLE-BAR Phrase

If you specify a TITLE-BAR but do not give a TITLE, the default title is the name of the program (PROGRAM-ID in the IDENTIFICATION DIVISION).

AUTO-MINIMIZE Phrase
  1. The AUTO-MINIMIZE phrase indicates that a minimize button should be displayed. The runtime handles the minimizing and restoring of the application automatically. If you do not specify AUTO-MINIMIZE, the user is not allowed to minimize the application.
  2. In addition, the AUTO-MINIMIZE phrase implies the SYSTEM MENU and TITLE-BAR phrases.
Window Location and Size
  1. The window's location on the screen is determined by the host system, as are its initial dimensions if it is resizable. You can use the SCREEN runtime configuration variable to specify the initial window dimensions (including whether it is maximized or minimized).

    On a character-based system, the initial window always occupies the entire terminal surface. Setting the various sizing options has no effect.

  2. If you do not use the LINES and SIZE phrases, the lines and size values are taken from the SIZE option of the SCREEN runtime configuration variable. If SCREEN is not set, the default size is 25 lines by 80 columns. The host system may provide a smaller default (for example, 24line character-based terminals will default to 24 lines).
STANDARD Phrase

The STANDARD option is identical to the INITIAL option except that it automatically implies the following options:

  1. TITLE-BAR
  2. SYSTEM MENU
  3. AUTO-MINIMIZE
  4. USER-COLORS
  5. For graphical systems, a black foreground on a white background. For character-based systems, a white foreground on a black background. You may override these default colors with the various color setting phrases.
GRAPHICAL Phrase

The GRAPHICAL phrase has the same effect as in the DISPLAY FLOATING WINDOW statement.

VISIBLE Phrase

The VISIBLE option determines whether the window created is visible or invisible. If the FALSE option is used, or visible-state is the value zero, then the window is invisible. Otherwise, the window is visible. If the VISIBLE phrase is omitted, then the window is visible.

POP-UP MENU Phrase

The POP-UP MENU phrase associates a pop-up menu with the window. If menu-1 is specified, then the menu associated with menu-1 becomes the pop-up menu. If NULL is specified, the window is not given a pop-up menu. Pop-up menus are activated by a machine-dependent technique. Under Windows, the technique is to right-click on the window's background.

CONTROLS-UNCROPPED Phrase

Normally, when you create a control in a window, the control is cropped to fit the current subwindow's dimensions. In addition, if the control's home position is outside of the current subwindow, the control is not created. Adding the phrase CONTROLS-UNCROPPED overrides these rules. When this phrase is used, the control is created with the specified location and dimensions, regardless of whether the control will be physically in the window.

This can be useful when you are dealing with RESIZABLE windows. Sometimes a resizable window is too small to show all of the controls that your program creates. Normally, these controls either would not be created or would be cropped. This could produce odd results when the window is later resized larger by the user. Although the resized window is now large enough to show everything, the controls still show their cropped appearance, because their (cropped) creation size is recorded in the controls as their actual size. Specifying CONTROLS-UNCROPPED avoids the cropping behavior.

This style is useful also when you want to place a combo-box near the bottom of a window. Because the size of the drop-down portion of the combo-box is determined by the control's overall height, cropping the control limits the drop-down box to the window's boundaries. If you want the box to drop down beyond the edge of the window, you need to use the CONTROLS-UNCROPPED window style to allow this.

EVENT PROCEDURE Phrase
  1. A window's event procedure is executed whenever an event is processed for that window. The event procedure is executed as if it were the target of a PERFORM statement. Only the window's own events trigger the event procedure. Events generated by controls contained in the window do not trigger the window's event procedure (they trigger the control's event procedure instead). The event procedure executes while the event is being processed, before the event causes termination of any executing ACCEPT statement. See PROCEDURE Clause for more information about event procedures.
  2. Specifying proc-1 assigns that procedure as the window's event procedure. Flow of control returns at the end of proc-1, unless proc-2 is specified, in which case flow of control returns at the end of proc-2. If you specify the NULL option, the window does not have an event procedure. This is the default, so the NULL option is treated as commentary.
  3. Note: The Support area of the Micro Focus Web site includes a sample program that demonstrates how a main application window can be coded to detect the system display's screen resolution and then size itself to fill the entire screen. To download the program, go to: http://supportline.microfocus.com/examplesandutilities/index.asp. Select ACUCOBOL-GT examples > Graphical User Interface Sample Programs > WIN-START-MAX.cbl.
Parent topic: DISPLAY Statement


DISPLAY TOOL-BAR

Format 13

DISPLAY TOOL-BAR adds a toolbar to the current window.

DISPLAY TOOL-BAR
HANDLE {IS} handle-name
       {IN}

Remaining phrases are optional, can appear in any order.

LINES {IS} height [CELL ]
      {= }        [CELLS]

CONTROL FONT {IS} font-1
             {= }

CELL
 {SIZE  }  [IS] {cell-units                                 }
 {HEIGHT}  [= ] {control-type-name  FONT font-2 [SEPARATE  ]}
 {WIDTH }       {control-type-name  FONT        [OVERLAPPED]}

WITH {COLOR } color-val
     {COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{BACKGROUND-HIGH    }
{BACKGROUND-LOW     }
{BACKGROUND-STANDARD}

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. height is a numeric data item or literal. It may be a non-integer value. You can also specify the value as an arithmetic expression.
  3. color-val is a numeric data item, numeric literal, or arithmetic expression
  4. fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. See FOREGROUND-COLOR and BACKGROUND-COLOR Phrases for more information on color settings and values.
  5. font-1 is a USAGE HANDLE or HANDLE OF FONT data item. It should contain a valid handle to a screen font.
  6. handle-name is a USAGE HANDLE, HANDLE OF WINDOW, or PIC X(10) data item.
  7. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  8. The HANDLE phrase may be specified anywhere in the statement after the required initial elements.
  9. IS and "=" are synonymous.
  10. HIGHLIGHT, HIGH and BOLD are synonymous.
  11. LOWLIGHT and LOW are equivalent.
  12. COLOR and COLOUR are synonymous.
  13. FOREGROUND-COLOR and FOREGROUND-COLOUR are synonymous.
  14. BACKGROUND-COLOR and BACKGROUND-COLOUR are synonymous.
  15. cell-units is a positive integer data item or literal.

General Rules

  1. DISPLAY TOOL-BAR adds a toolbar to the current floating or main-application window. A toolbar is a region of the window that is devoted to holding buttons and other controls that are used as mouse accelerators that the user can activate with the mouse to quickly specify a program operation. Toolbars extend across the entire width of the window. They appear at either the top or the bottom of the window depending on the host system. Under Microsoft Windows, toolbars appear at the top of the window.

    On character-based systems, toolbars are created but are always invisible. This is done to simplify cross-platform support: you can unconditionally create toolbars in your application. They will seem to behave properly on character-based systems, but they will not actually show up.

  2. You may have more than one toolbar associated with a particular window. All toolbars associated with a window are stacked vertically in the order that they are created. You may have a maximum of five toolbars associated with each window.
  3. Like menu-bars, the space that a toolbar occupies is not part of the body (client area) of the window. When you create a toolbar, the window it is attached to is enlarged to accommodate the space required by the toolbar (unless the window is RESIZABLE; see the description of the RESIZABLE phrase in the General Rules section of the Format 11 DISPLAY statement). You do not lose any application space when adding a toolbar to a window, except as constrained by the physical screen. Toolbars do not scroll when the body of the window is scrolled. Instead, the toolbar remains accessible at the top of the window. Toolbars automatically grow and shrink horizontally to match the width of the owning window.
  4. In several respects, toolbars act like windows. Because of this, they are called child windows of the window they are attached to. When you create a toolbar, a handle that identifies it is returned in handle-name. Like other window handles, you can use handle-name in an UPON phrase of a DISPLAY statement to direct output to the toolbar. You can also use handle-name in a DESTROY statement to remove the toolbar. Unlike other windows, toolbars are not made current or active when they are created. This means that the only way to place a control on the toolbar is with the UPON phrase.
  5. Toolbars cannot take textual output (i.e., text-style ACCEPT and DISPLAY statements cannot refer to a toolbar). You can only place graphical controls on a toolbar. However, any type of graphical control may be placed on a toolbar. Most commonly, push buttons appear on toolbars (either text or bitmap buttons), as well as bitmap check-boxes and radio-buttons.
  6. font-1 identifies the default font to use for any controls shown in the toolbar. If font-1 is not specified, DEFAULT-FONT is used.
  7. height specifies the height of the toolbar. Height units are derived from the height of font-1 (or DEFAULT-FONT if font-1 is not used). If height is omitted, then the toolbar uses a host-dependent default height.
  8. The color and intensity phrases have their usual meaning as described in Common Screen Options. The toolbar directly uses the background-color and background-intensity only when it is drawn. The foreground-color and intensity are used as defaults for controls displayed on the toolbar. Any color and intensity elements that are omitted from the DISPLAY TOOL-BAR statement are inherited from the window that the toolbar is attached to.
  9. The easiest way to make effective use of a toolbar is to populate it with controls that can act like function keys. When you do this, the toolbar acts in a manner that is very similar to a menu bar. This simplifies other programming because you do not need to attempt to directly activate the controls on the toolbar. Controls that can act like function keys are push buttons, check boxes and radio buttons. For push buttons, use the SELF-ACT style. For check boxes and radio buttons, use both the SELF-ACT and NOTIFY styles. This ensures that these controls behave like function keys (i.e., they activate themselves when clicked, and inform your program).
Parent topic: DISPLAY Statement


DISPLAY control-type-name

Format 14

DISPLAY control-type-name creates a graphical control, including a graphical ActiveX or COM control.

DISPLAY {control-type-name  }
        {OBJECT control-type}

 [ title ]

 [ UPON new-window ]

Remaining phrases are optional, can appear in any order.

{IDENTIFICATION} {IS} control-id
{ID            } {= }

AT screen-loc   [CELL  ]
                [CELLS ]
                [PIXEL ]
                [PIXELS]

AT LINE NUMBER line-num   [CELL  ]
                          [CELLS ]
                          [PIXEL ]
                          [PIXELS]

AT {COLUMN  } NUMBER col-num   [CELL  ]
   {COL     }                  [CELLS ]
   {POSITION}                  [PIXEL ]
   {POS     }                  [PIXELS]

AT CLINE NUMBER cline-num   [CELL ]
                            [CELLS]

AT CCOL NUMBER ccol-num   [CELL ]
                          [CELLS]

SIZE  {IS} length [CELL  ]
      {= }        [CELLS ]
                  [PIXEL ]
                  [PIXELS]

LINES {IS} height [CELL  ]
      {= }        [CELLS ]
                  [PIXEL ]
                  [PIXELS]

CSIZE   {IS} clength  [CELL ]
        {= }          [CELLS]

CLINES  {IS} cheight  [CELL ]
        {= }          [CELLS]

MAX-HEIGHT {IS} max-height
           {= }

MAX-WIDTH  {IS} max-width
           {= }

MIN-HEIGHT {IS} min-height
           {= }

MIN-WIDTH  {IS} min-width
           {= }
TITLE {IS} title
      {= }

KEY   {IS} key-letter
      {= }

{COLOR } IS color-val
{COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{BACKGROUND-HIGH    }
{BACKGROUND-LOW     }
{BACKGROUND-STANDARD}

STYLE {IS} style-flags
      {= }

{style-name} ...

VALUE {IS} [ MULTIPLE ] value [ LENGTH {IS} length-1 ]
      {= } [ TABLE    ]                {= }

FONT {IS} font-handle
     {= }

HANDLE {IN} control-handle
       {IS}

LAYOUT-DATA {IS} layout-data
            {= }
ENABLED  {IS} {TRUE         }
         {= } {FALSE        }
              {enabled-state}

VISIBLE  {IS} {TRUE         }
         {= } {FALSE        }
              {visible-state}

POP-UP MENU {IS}  {menu-1}
            {= }  {NULL}

HELP-ID {IS} help-id
        {= }

EVENT-LIST    {IS} ( event-value { event-value ... } )
              {= }

AX-EVENT-LIST {IS} ( ax-event-value { ax-event-value ... } )
              {= }

EXCLUDE-EVENT-LIST {IS} list-state
                   {= }

EVENT PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
                              {THRU   }
                   { NULL                        }

{{property-name         } {IS } property-option
                                        [GIVING result-1]}. ...
 {PROPERTY property-type} {ARE}

where property-option is one of the following:

    { property-value [ LENGTH {IS} length-1 ] }
    {                         {= }            }
    { ( {property-value} ... )                }
    {                                         }
    { {MULTIPLE} property-table               }
    { {TABLE   }                              }

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. control-type-name is one of the control type reserved words known by the compiler.
  3. control-type iNew-windows a numeric literal or data item.
  4. new-window is a USAGE HANDLE or PIC X(10) data items. If used, the UPON phrase must be the first optional phrase specified.
  5. control-id is an integer numeric literal or data item. Its value should be in the range of 0 to 32767.
  6. screen-loc is an integer data item or literal containing exactly 4, 6, or 8 digits. It may also be a group item of 4, 6, or 8 characters. If a numeric item is used, it must be a non-negative integer.
  7. line-num, col-num, cline-num, ccol-num, length, height, clength, and cheight are numeric data items or literals. They may be non-integer values, except when pixels are specified. You can also specify the value of any of these items with an arithmetic expression.
  8. max-height, max-width, min-height, and min-width are numeric data items or literals.
  9. color-val is a numeric data item or literal. color-val can also be an arithmetic expression.
  10. fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. See FOREGROUND-COLOR and BACKGROUND-COLOR Phrases for more information on color settings and values.
  11. title is an alphanumeric literal or data item. In Format 14, title may appear only once, either in a TITLE phrase or the initial title option. The title option must be the first option specified.
  12. key-letter is an alphanumeric literal or data item.
  13. font-handle is a data item of type USAGE HANDLE or HANDLE OF FONT.
  14. style-flags is a numeric expression.
  15. style-name is the name of a style associated with the class of control being described. If control-type-name is omitted, then you may not use the style-name phrase. You may use the STYLE phrase instead.
  16. value is a literal or data item. If the MULTIPLE option is specified, then value must be a one-dimensional table. In this case, value is not subscripted.
  17. length-1 is a numeric literal or data item. The LENGTH phrase may be specified only if the immediately preceding value or property-value is an alphanumeric literal or data item, and not a figurative constant. In addition, the MULTIPLE option may not be specified along with the LENGTH phrase.
  18. control-handle is a USAGE HANDLE data item.
  19. layout-data is an integer literal, data item, or expression.
  20. enabled-state, visible-state, and help-id are integer numeric literals or data items.
  21. menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
  22. event-value and ax-event-value are numeric literals or data items that identify an event type. List elements must be enclosed in parentheses. Elements must be separated by a space. If the list contains a single element, the parentheses can be omitted.
  23. list-state is an integer literal or numeric data item. Valid values are 0 and 1.
  24. proc-1 and proc-2 are procedure names.
  25. property-name is the name of a property specific to the type of control being referenced. If the type of control is unknown to the compiler (as in a DISPLAY OBJECT object-1 statement), then property-name may not be used. You must use the PROPERTY property-type option instead.
  26. property-type is a numeric literal or data item. It identifies the property to modify. The numeric values that identify the various control properties can be found in the COPY library "controls.def".
  27. property-value is a literal or data item. Property-value may also be a numeric expression (however, only the first property-value in a phrase may be an expression, subsequent values must be literals or data items). When multiple values are specified, the parentheses are required. An example of their use is: DISPLAY-COLUMNS = ( 1, 20 )
  28. property-table is a data item that appears in a one-dimensional table. No index should be specified.
  29. result-1 is a numeric data item.
  30. If the title option is used, it must be the first optional phrase.
  31. If the UPON phrase is specified, it must be the first optional phrase, except when the title option is used, then the UPON phrase must be second, following the title phrase.
  32. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  33. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  34. If the CELLS option is used in either the SIZE or CSIZE phrase, it must be present in both phrases if both are specified. The same rule applies to the CELLS option in the LINES and CLINES phrases.
  35. The HANDLE phrase may be specified anywhere in the statement after the required initial elements.
  36. IS and "=" are synonymous.
  37. COLUMN, COL, POSITION, and POS are equivalent.
  38. HIGHLIGHT, HIGH, and BOLD are synonymous.
  39. LOWLIGHT and LOW are equivalent.
  40. COLOR and COLOUR are synonymous.
  41. FOREGROUND-COLOR and FOREGROUND-COLOUR are synonymous.
  42. BACKGROUND-COLOR and BACKGROUND-COLOUR are synonymous.
  43. MULTIPLE and TABLE are synonymous.

General Rules

  1. The DISPLAY control-type-name verb creates a new control and displays it on the screen. A handle to the new control is returned in control-handle. The handle is used in future references to the control. If control-handle is not specified, the control is an anonymous control. Anonymous controls can be referenced in future statements only by position.
  2. control-type-name identifies the type of the control. The exact set of controls available and their types are discussed in Control Types Reference in User Interface Programming. Use OBJECT control-type when the control type is not known at compile time. At run time, control-type must contain the identifying number of a control type known to the system. If it does not correspond to any control type, the DISPLAY statement is ignored and control-handle is set to NULL. The identifying number of each control type is defined in the controls.def COPY file.
  3. The LENGTH option of the VALUE and property phrases establishes the exact size of the source data to use. Without the LENGTH option, a text value presented to the control is the data contained in the COBOL data element with trailing spaces removed. When you specify the LENGTH option, exactly length-1 characters of the data are used instead. No trailing space removal occurs. This is useful in a few cases when you need to treat trailing spaces as data.

    If length-1 is a value larger than the size of the data item it is modifying, then the size of the data item is used instead. If length-1 is negative, it is ignored and the default handling occurs.

  4. Some properties return specific values when set. These values are placed in result-1 of the GIVING phrase. The meaning of the value depends on the property being set; see the documentation for the specific property. Properties that do not have a pre-defined return value set result-1 to 1 if the property was set successfully, or 0 if not. When a property is being given multiple values in a single assignment (for example: Display-Columns = (1, 10, 30)), then result-1 is set in response to the last value assigned.
  5. After the DISPLAY statement is executed, the cursor is positioned at the first whole column immediately to the right of the control. If this column is past the right edge of the current subwindow, the cursor is not moved from its previous location.
  6. Once created, a control remains in existence until one of the following events:
    1. The control is explicitly destroyed with a DESTROY verb.
    2. The control has the TEMPORARY style, the control is overwritten.
    3. The window containing the control is destroyed.
  7. Under some systems, controls do not interact properly with pop-up subwindows. This is due to the fact that the controls are maintained by the GUI directly while pop-up subwindows are managed by the ACUCOBOL-GT runtime system. Since the GUI is not aware of the pop-up nature of the subwindow, it displays the control over the subwindow, even if the program's intent is to have the pop-up subwindow on top. For this reason, pop-up subwindows are not recommended for programs that will be using graphical controls. You should use floating windows instead.
  8. The POP-UP MENU phrase associates a pop-up menu with the control. If menu-1 is specified, then the menu associated with menu-1 becomes the pop-up menu. If NULL is specified, the control is not given a pop-up menu. Pop-up menus are activated by a machine-dependent technique. Under Windows, the technique is to right-click on the control.
  9. Any phrases not described there behave in the same manner as in a Format 1 DISPLAY statement. See Common Screen Options for a description of the remaining optional phrases.
  10. The runtime ignores events from all controls while it is creating an ActiveX control, via the DISPLAY statement or otherwise. If you are using a control that delivers significant information using events and you don't want to miss those events while you are creating a new control, set the CONTROL_CREATION_EVENTS runtime configuration variable to 1 (On, True, Yes). Alternatively, you could avoid creating an ActiveX control when you are expecting an event.
Parent topic: DISPLAY Statement


DISPLAY MESSAGE BOX

Format 15

DISPLAY MESSAGE BOX creates a simple message box

DISPLAY MESSAGE BOX

 { text } . . .

Remaining phrases are optional and may be used in any order.

TITLE {IS} title
      {= }

TYPE {IS} type
     {= }

ICON {IS} icon
     {= }

DEFAULT {IS} default
        {= }

{GIVING   } value
{RETURNING}

Syntax Rules

  1. text is a literal or data item.
  2. title is an alphanumeric literal or data item.
  3. type, icon, and default are numeric literals or data items.
  4. value is a numeric data item.

General Rules

  1. Format 15 (DISPLAY MESSAGE BOX) creates a simple modal pop-up window with a title-bar, a text message, an icon (on some systems) and one or more push buttons. It then waits for the user to push one of the buttons and returns the results. The window is then destroyed. Message boxes come in OK and Yes/No formats, with an optional Cancel button in each format. Message boxes are a programming convenience when you need to create a simple dialog box that can fit one of these predefined formats.
  2. Text forms the body of the message box. It is the string of text that the user will see. When more than one text item is specified, they are concatenated together to form a single string that the user sees. The limit on the length of the message string is host dependent. The host system wraps the text as needed to fit the message box. If you want to force the text to a new line, you can embed an ASCII line-feed character (h"0A" in COBOL) where you want the new line to start. For example, the following code produces a message box with two lines of text:
    78  NEWLINE      VALUE H"0A".

DISPLAY MESSAGE BOX,
   "This is line 1", NEWLINE,

   "and this is line 2" .
  3. When text is numeric, it is converted to a text string using the CONVERT phrase rules. Leading spaces in the resulting string are suppressed in the message. When text is numeric-edited, leading spaces are suppressed in the message, and the rest of the item is displayed without modification. For all other data types, text is displayed without modification.
  4. Title is displayed in the message box's title bar. If title is omitted, the message box displays the same title as the application's main window.
  5. Type, icon, default and value use a set of constants to describe the type of message box and the buttons it contains. These constants have level 78 definitions for them in the COPY library "acugui.def" supplied with the compiler. These constants are as follows:
    78  MB-OK               VALUE 1.
78  MB-YES-NO           VALUE 2.
78  MB-OK-CANCEL        VALUE 3.
78  MB-YES-NO-CANCEL    VALUE 4.
78  MB-YES              VALUE 1.
78  MB-NO               VALUE 2.
78  MB-CANCEL           VALUE 3.
78  MB-DEFAULT-ICON     VALUE 1.
78  MB-WARNING-ICON     VALUE 2.
78  MB-ERROR-ICON       VALUE 3.
  6. Type describes the set of buttons contained in the box. The possible values are:
    Type Value | Buttons
    MB-OK | "OK" button
    MB-YES-NO | "Yes" and "No" buttons
    MB-OK-CANCEL | "OK" and "Cancel" buttons
    MB-YES-NO-CANCEL | "Yes", "No" and "Cancel" buttons

    If type is omitted, or if it contains an invalid value, then MB-OK is used. The text that appears on the buttons is set by the current language installed for Windows. For non-Windows systems, the text is configurable by the TEXT configuration entry.

  7. Icon describes the icon that will appear. The icon appears only under Windows. On other systems, the icon selected is ignored. If icon is set to MB-ERROR-ICON, then a stop icon is shown. If icon is set to MB-WARNING-ICON, then an exclamation icon displays. If icon is set to MB-DEFAULT-ICON, then boxes with OK buttons will display an information icon, and boxes with Yes/No buttons will display a question mark icon. If icon is omitted or contains an invalid value, then MB-DEFAULT-ICON is used.
  8. Default describes which button will be the default button (i.e., the button used if the user simply presses Return). The possible values are:
    Value | Button
    MB-OK | "OK" button
    MB-YES | "Yes" button
    MB-NO | "No" button
    MB-CANCEL | "Cancel" button

    If default is omitted, or contains an invalid value, then the default button will be the OK button or the "Yes button.

  9. Value will contain the identity of the button the user pressed to leave the message box. It uses the same values as default does, described above. For example, if the user presses the No button, then value will contain MB-NO.
    Note: For each invocation of the message box, only one keystroke entry is picked up. If you want to drive the message box from your defined keystroke file (or from the COPY library acugui.def), make sure that you make this one entry a valid character for the message box, such as Y or N for a message requiring a Yes or a No response.
Parent topic: DISPLAY Statement


DISPLAY external-form-item

Format 16

DISPLAY external-form-item merges data into an HTML template file and sends the result to standard output.

DISPLAY external-form-item

Syntax Rules

external-form-item is an output record for an HTML form when used in a Common Gateway Interface (CGI) program. It is a group data item, declared with the IS EXTERNAL-FORM and IDENTIFIED BY clauses. It may have one or more elementary items associated with HTML template fields. The association is made with the IS IDENTIFIED BY clause.

external-form-item may also be an input record for an HTML form. In this case, the group item is declared with only the IS EXTERNAL-FORM clause. This is used primarily when you are debugging your CGI program. See the General Rules below for more details. See Data Description Entry for information about how to declare external forms.

General Rules

  1. An external form is called an output form if the IDENTIFIED BY clause is used to associate it with an HTML template file. If the IDENTIFIED BY clause is omitted, it is called an "input form". For example, the following is an input form:
    01  CGI-FORM IS EXTERNAL-FORM.
    03  CGI-VAR1  PIC X(10).
    03  CGI-VAR2  PIC X(10).

    And here is an output form:

    01  HTML-FORM IS EXTERNAL-FORM
      IDENTIFIED BY "tmplate1".
    03  HTML-VAR1 PIC X(10).
    03  HTML-VAR2 PIC X(10).

    The DISPLAY verb treats input and output forms differently. Input forms are discussed in rule 7, below. For output forms, DISPLAY merges the data contained in the elementary items into the associated HTML template file and sends the result to the standard output stream in conformance with the CGI specification. To do this, DISPLAY scans the HTML template file for data names delineated by two percentage signs on either side (i.e. %%data-name%%). It then replaces those data names with the contents of the associated elementary items from the output form, stripping trailing spaces.

  2. The maximum length of a single line in the template file is 256 bytes. The maximum length of a single HTML output line is 512 bytes. No conversion is performed on the output form items before they are merged with the HTML template file.
  3. You may specify a series of directories for locating HTML template files. To do this, use the HTML_TEMPLATE_PREFIX configuration variable. This variable is similar to FILE-PREFIX and CODE-PREFIX. It specifies a series of one or more directories to be searched for the desired HTML template file. The directories are specified as a sequence of space-delimited prefixes to be applied to the file name. All directories in the sequence must be valid names. The current directory can be indicated by a period (regardless of the host operating system).

    You may omit the template file suffix if it is either .html or .htm. If the suffix is omitted or is something other than .html or .htm, DISPLAY first appends .html to the specified file name and tries to open it. If that fails, DISPLAY appends .htm to the file name and tries to open it. If that fails, DISPLAY tries to open the file exactly as specified. If these attempts fail, the following error message is sent to the standard output stream in HTML format:

    Can't open HTML template "template-file-name"

    When the Web Server executes your CGI program, the current working directory depends on the configuration of the specific Web Server that is running. In many cases the current working directory is the same as the Web Server's "root" directory. As part of the CGI specification, when the Web Server executes your CGI program, it sets an environment variable called PATH_TRANSLATED to the directory containing your CGI program. You may want to use this information to locate your HTML template files. For example, if your template files are in the same directory as your CGI programs, then set the HTML-TEMPLATE-PREFIX configuration variable to the value of PATH_TRANSLATED as follows:

    01  CGI-DIRECTORY  PIC X(100) VALUE SPACES.

...

ACCEPT CGI-DIRECTORY FROM ENVIRONMENT "PATH_TRANSLATED".

SET CONFIGURATION "HTML-TEMPLATE-PREFIX" TO CGI-DIRECTORY.

    The output from a CGI program must begin with a "response header". DISPLAY automatically generates a "Content-Type" response header if the specified template file is a local file (i.e., not a URL--see rule 5 below).

  4. You may specify the EXTERNAL-FORM clause for an item that has no subordinate items. This is useful for displaying static Web pages. To do this, specify the name of the static Web page in the IDENTIFIED BY clause. For example, if you have a Web page called webpage1.html, add the following lines to your COBOL program:
    01  WEB-PAGE-1 IS EXTERNAL-FORM
       IDENTIFIED BY "webpage1".

...

    DISPLAY WEB-PAGE-1.
  5. You may also specify a complete URL instead of a template file name in the IDENTIFIED BY clause. In this case, DISPLAY generates a Location response header that contains the URL. This header specifies that the data you're returning is a pointer to another location. To determine whether the template file name is a URL, DISPLAY scans it for the "://" string. DISPLAY does not apply the HTML-TEMPLATE-PREFIX when the template file name is a URL.

    For example, if your program determines that the information the user has requested is on another Web server, and its URL is http://www.theinfo.com, add the following lines to your COBOL program:

    01 THE-INFO-URL IS EXTERNAL-FORM
       IDENTIFIED BY "http://www.theinfo.com"

...

    DISPLAY THE-INFO-URL.

    The length of the URL must not exceed 256 bytes.

    Only one response header is sent to the standard output stream. Your CGI program should exit immediately after sending a location header (i.e., after displaying an external form identified by a URL).

  6. You may use as many HTML template files as you like in a single program. A common way to use multiple HTML template files is to have three output forms: a header, body, and footer. Each of these has a corresponding HTML template file. You first display the header form, then move each row of data to the body form and display it, and finally display the footer form.
  7. When an input form is specified in a DISPLAY statement, the names and values of each elementary item are sent to the standard output stream in HTML format. One line is generated for each elementary item. The line consists of the name of the item followed by " = ", followed by the first 100 bytes of the item's value. This can be useful when you are testing and debugging your CGI program.
Parent topic: DISPLAY Statement


DISPLAY UPON ENVIRONMENT-NAME

Format 17

DISPLAY UPON ENVIRONMENT-NAME (and VALUE) sets the value of the specified environment variable in the ENVIRONMENT-NAME register.

DISPLAY name UPON ENVIRONMENT-NAME
DISPLAY value UPON ENVIRONMENT-VALUE

Syntax Rules

name and value are alphanumeric Working-Storage data items that is the name and value of an environment variable or configuration variable.

General Rules

DISPLAY UPON ENVIRONMENT-NAME sets ENVIRONMENT-NAME to the value of the environment variable or configuration variable specified by name. The value of ENVIRONMENT-NAME can be queried with a Format 13 ACCEPT statement.

Example

DISPLAY "DEFAULT-HOST" UPON ENVIRONMENT-NAME
DISPLAY "MSSQL" UPON ENVIRONMENT-VALUE

Now, any file operations should go through SQL Server instead of Vision. Note that you can ACCEPT my-value FROM DEFAULT-HOST and get MSSQL back into my-value.

Parent topic: DISPLAY Statement


DISPLAY assembly-name

Format 18

DISPLAY assembly-name instantiates a graphical .NET control or assembly.

DISPLAY {assembly-name       }
        {OBJECT assembly-name}

NAMESPACE { IS } "namespace"

CLASS-NAME { IS } "class-name"

Remaining phrases are optional.

HANDLE { IS } handle-1
VERSION { IS } "version"

CULTURE { IS } "culture"

STRONG-NAME { IS } "strong-name"

CONSTRUCTOR { IS } CONSTRUCTOR[n] parameters...

MODULE { IS } "module"

FILE-PATH { IS } "file-path"

AT LINE NUMBER line-num   [CELL  ]
                          [CELLS ]
                          [PIXEL ]
                          [PIXELS]

AT {COLUMN  } NUMBER col-num   [CELL  ]
   {COL     }                  [CELLS ]
   {POSITION}                  [PIXEL ]
   {POS     }                  [PIXELS]

SIZE  {IS} length [CELL  ]
      {= }        [CELLS ]
                  [PIXEL ]
                  [PIXELS]

LINES {IS} height [CELL  ]
      {= }        [CELLS ]
                  [PIXEL ]
                  [PIXELS]

Syntax Rules

  1. assembly-name is the name of a .NET assembly defined in a COPY file created by NETDEFGEN. This must be the DLL name of a graphical control, not an executable file. Graphical controls are generated by Visual Studio when a developer selects a Windows Control Library project type.
  2. handle-1 is a USAGE HANDLE or PIC X(10) data item assigned to the graphical .NET assembly. The HANDLE phrase can be specified anywhere in the statement after the initial elements.
  3. A value surrounded by quotation marks is an alphanumeric literal and is case-sensitive. Literal values for assembly parameters are located in the COPY file generated by NETDEFGEN. The same COPY file must be included in the SPECIAL-NAMES paragraph of your program.
  4. line-num, col-num, length, and height are numeric data items or literals. They may be non-integer values, except when pixels are specified. They may be numeric expressions.

General Rules

  1. The Format 18 DISPLAY statement is only for graphical .NET assemblies. Graphical assemblies show the keyword VISUAL in the COPY file after the CLASS keyword. If the word "VISUAL" does not appear, use the CREATE statement to instantiate the assembly.
  2. assembly-name is the name of a .NET assembly defined in the NETDEFGEN COPY file. This must be a DLL name or a control name, not an executable.
  3. namespace is a NameSpace in the assembly, as it appears in the COPY file.
  4. class-name is a class in the NameSpace.
  5. version is the version number of the assembly.
  6. culture is cultural information related to the assembly.
  7. strong-name is the cryptographic key required to access the assembly, if any. If the assembly requires such a key, as all assemblies in the Global Assembly Cache (GAC) do, it is shown in the COPY file under the keyword STRONG.
  8. All classes that result in an object have a CONSTRUCTOR, which is a sort of method. If you see a CONSTRUCTOR identifier in the COPY file without a parameter list, then the field may be omitted from your COBOL program. If all listed CONSTRUCTORs have parameters, then you must choose which CONSTRUCTOR and parameters to use. Constructor(n) is the constructor that you want to use followed by its parameter data.
  9. module identifies a file where a combination of NameSpaces and Classes reside. It is used when the assembly is constructed of other assemblies.
  10. file-path is the path of an XML file, and that XML file contains the path where the .NET assembly is located. Use FILE-PATH when the assembly that you want to access does not reside in the GAC or in the same directory as wrun32.exe. Assemblies that reside in the GAC will have the STRONG keyword in the NETDEFGEN COPY file.
  11. LINES and SIZE default to the design control height and width.
Parent topic: DISPLAY Statement


DIVIDE Statement

The DIVIDE statement performs arithmetic division.

Format 1

DIVIDE divisor INTO { result [ROUNDED] } ...

   [ ON SIZE ERROR statement ]

   [ NOT ON SIZE ERROR statement ]

   [ END-DIVIDE ]

Format 2

DIVIDE divisor INTO dividend

     GIVING { result [ROUNDED] } ...

   [ ON SIZE ERROR statement ]

   [ NOT ON SIZE ERROR statement ]

   [ END-DIVIDE ]

Format 3

DIVIDE dividend BY divisor

     GIVING { result [ROUNDED] } ...

   [ ON SIZE ERROR statement ]

   [ NOT ON SIZE ERROR statement ]

   [ END-DIVIDE ]

Format 4

DIVIDE divisor INTO dividend GIVING result [ROUNDED]

     REMAINDER remainder

   [ ON SIZE ERROR statement ]

   [ NOT ON SIZE ERROR statement ]

   [ END-DIVIDE ]

Format 5

DIVIDE dividend BY divisor GIVING result [ROUNDED]

     REMAINDER remainder

   [ ON SIZE ERROR statement ]

   [ NOT ON SIZE ERROR statement ]

   [ END-DIVIDE ]

Syntax Rules

  1. divisor is a numeric literal or numeric data item. It represents the number to be divided by.
  2. dividend is a numeric literal or numeric data item. It represents the number to be divided into.
  3. result is a numeric or numeric-edited data item. In Format 1, result must be a numeric data item.
  4. remainder is a numeric or numeric-edited data item.
  5. statement is an imperative statement.
  6. The REMAINDER phrase may not be used if any operand or result is an external floating-point data type.
Note: Avoid mixing external floating-point types with other numeric types in DIVIDE statements, because mixed-type DIVIDE operations are not completely reliable.

Format 1 General Rules

The divisor is individually divided into each result and the quotient stored there.

Format 2 and 3 General Rules

The divisor is divided into the dividend. The quotient is stored in each result.

Format 4 and 5 General Rules

  1. The divisor is divided into the dividend, the quotient is stored in result, and the remainder is stored in remainder.
  2. If the ROUNDED phrase is not specified, the quotient is truncated to fit into the result and the remainder is computed by subtracting the product of the truncated quotient and divisor from the dividend. If the ROUNDED phrase is specified, the quotient is rounded to fit the result, but the remainder is still computed by subtracting the product of the truncated quotient and the divisor from the dividend.
  3. If the SIZE ERROR clause is specified, and a size error occurs during the computation of the quotient, the remainder is not computed and remainder remains unchanged. If a size error occurs during the computation of the remainder, the result is updated, but the remainder is left unchanged. The SIZE ERROR statement executes in either case.
    Note: In division operations, the remainder is calculated before the quotient is moved to the destination item(s).

    The remainder will almost always be 0 if the dividend or divisor is floating-point. This is because all of the arithmetic is performed using floating-point variables. The remainder will be non-zero only if precision is lost during the calculation.

  4. Additional information can be found in Arithmetic Operations, Multiple Receiving Fields, the ROUNDED Option, and the SIZE ERROR Option.
Parent topic: Procedure Division Statements


ENTRY Statement

The ENTRY statement is used to establish an alternate entry point in the program.

General Format

ENTRY entry-name [ USING {parameter} ... ]

Syntax Rules

  1. entry-name is a non-numeric literal. The maximum number of characters is 30.
  2. parameter is a data item defined with a level-number of 01 or 77 and it must appear in the Linkage Section.
  3. Each parameter cannot appear more than once in the USING phrase.
  4. An ENTRY statement can begin in Area A. The compiler will not recognize this as an error. This provides compatibility with other compilers that support the ENTRY statement.

General Rules

  1. entry-name must be unique within the program. No duplicates are allowed.
  2. The maximum number of parameters that may be passed to an ENTRY point is 255.
  3. If the USING phrase is used, then each parameter must be declared in the Linkage Section.
  4. The constraints on the parameters are the same as those for the Procedure Division USING items. See Procedure Division Format for more information.
  5. There is a limit of 255 level 01 Linkage data items per program.
  6. An ENTRY point can be called just like any other program; however, the program containing the ENTRY point must be loaded and present in memory at the time of the CALL. Once loaded, COBOL objects may be called by any of their ENTRY point names. See Calling Subprograms for more information.
  7. The CALL succeeds if the specified program-name finds an exact entry-name match. By default, the matching logic is case sensitive and distinguishes between hyphens and underscores. The matching logic can be configured to be case insensitive and to not distinguish between hyphens and underscores with the LITERAL_ENTRY configuration variable described in Appendix H.
  8. When a program is called by one of its ENTRY point names, the execution begins immediately after the ENTRY statement. The ENTRY point parameters are initialized in the same way as the Procedure Division parameters.
    Note: Care should be taken not to enter a COBOL program in the middle of a control flow statement like a loop or a conditional statement. Doing so will result in undefined behavior.
  9. Execution of the program passes through entry points with no effect.
  10. There is a limit of 65536 ENTRY points per program, including the main entry point at the beginning of the Procedure Division.
Parent topic: Procedure Division Statements


EVALUATE Statement

The EVALUATE statement causes multiple conditions to be evaluated. The subsequent action of the program depends on the results of these evaluations.

The EVALUATE statement is very similar to the CASE construct common in many other programming languages. The EVALUATE/CASE construct provides the ability to selectively execute one of a set of instruction alternatives based on the evaluation of a set of choice alternatives.

EVALUATE extends the power of the typical CASE construct by allowing multiple data items and conditions to be named in the EVALUATE phrase (see code example 2).

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format

EVALUATE  {subject}  [ ALSO {subject} ] ...
          {TRUE   }         {TRUE   }
          {FALSE  }         {FALSE  }

  { { WHEN obj-phrase [ ALSO obj-phrase ] ... } ...

           statement-1 } ...

  [ WHEN OTHER statement-2 ]

  [ END-EVALUATE ]

obj-phrase has the following format:

  { ANY                                  }
  { TRUE                                 }
  { FALSE                                }
  { [=] cond-obj                         }
  { [NOT =] obj-item [ {THRU   } obj-item ]}
  {                  {THROUGH}           }
  { < obj-item                           }
  { IS LESS THAN obj-item                }
  { <= obj-item                          }
  { IS LESS THAN OR EQUAL TO obj-item    }
  { = obj-item                              }
  { IS EQUAL TO obj-item                    }
  { EQUALS obj-item                         }
  { > obj-item                              }
  { IS GREATER THAN obj-item                }
  { EXCEEDS obj-item                        }
  { >= obj-item                             }
  { IS GREATER THAN OR EQUAL TO obj-item    }
  { <> obj-item                             }
  { IS UNEQUAL TO obj-item                  }

Syntax Rules

  1. subject may be a literal, data item, arithmetic expression, or conditional expression.
  2. cond-obj is a conditional expression.
  3. obj-item may be a literal, data item, or arithmetic expression.
  4. statement-1 and statement-2 are imperative statements.
  5. Before the first WHEN phrase, subject and the words TRUE and FALSE are called subjects, and all the subjects together are called the subject set.
  6. The operands and the words TRUE, FALSE, and ANY which appear in a WHEN phrase are called objects, and the collection of objects in a single WHEN phrase is called the object set.
  7. The words THROUGH and THRU are equivalent. Two obj-items connected by a THROUGH phrase must be of the same class. They are treated as a single object.
  8. The number of objects within each object set must match the number of subjects in the subject set.
  9. Each object within an object set must correspond to the subject having the same ordinal position as in the subject set. For each pair:
    1. obj-item must be a valid operand for comparison to the corresponding subject.
    2. TRUE, FALSE, or cond-obj as an object must correspond to TRUE, FALSE, or a conditional expression as the subject.
    3. ANY may correspond to any type of subject.

General Rules

  1. The EVALUATE statement operates as if each subject and object were evaluated and assigned a value or range of values. These values may be numeric, nonnumeric, truth values, or ranges of numeric or nonnumeric values. These values are determined as follows:
    1. Any subject or object that is a data item or literal, without either the THROUGH or the NOT phrase, is assigned the value and class of that data item or literal.
    2. Any subject or object that is an arithmetic expression, without either the THROUGH or the NOT phrase, is assigned a numeric value according to the rules for evaluating arithmetic expressions.
    3. Any subject or object that is a conditional expression is assigned a truth value according to the rules for evaluating conditional expressions.
    4. Any subject or object specified by the words TRUE or FALSE is assigned a truth value corresponding to that word.
    5. Any object specified by the word ANY is not evaluated.
    6. If the THROUGH phrase is specified for an object, without the NOT phrase, the range of values includes all permissible values of the corresponding subject that are greater than or equal to the first operand and less than or equal to the second operand, according to the rules for comparison.
    7. If the NOT phrase is specified for an object, the values assigned to that object are all permissible values of the corresponding subject not equal to the value, or range of values, that would have been assigned had the NOT phrase been omitted.
  2. The EVALUATE statement then proceeds as if the values assigned to the subjects and objects were compared to determine if any WHEN phrase satisfies the subject set. Each object within the object set for the first WHEN phrase is compared to the subject having the same ordinal position within the subject set. The comparison is satisfied if one of the following is true:
    1. If the items being compared are assigned numeric or nonnumeric values, the comparison is satisfied if the value (or one of the range of values) assigned to the object is equal to the value assigned to the subject.
    2. If the items being compared are assigned truth values, the comparison is satisfied if the truth values are the same.
    3. If the object is the word ANY, the comparison is always satisfied.
  3. If the comparison is satisfied for every object within the object set, the corresponding WHEN phrase is selected.
  4. If the comparison is not satisfied for one or more objects within the object set, the procedure repeats for the next WHEN phrase. This is repeated until a WHEN phrase is selected or all the object sets have been tested.
  5. If a WHEN phrase is selected, the corresponding statement-1 is executed.
  6. If no WHEN phrase is selected and a WHEN OTHER phrase is specified, statement-2 is executed. If no WHEN OTHER phrase is present, control transfers to the end of the EVALUATE statement.
  7. The WHEN verb is accepted as an implied END-IF or END-PERFORM for any and all preceding IF and PERFORM statements that do not have corresponding END- statements.
  8. The scope of execution of the EVALUATE statement is terminated when the end of statement-1 or statement-2 is reached, or when no WHEN phrase is selected and no WHEN OTHER phrase is specified.

Code Example 1:

EVALUATE AGE
   WHEN 56 THRU 99  PERFORM  SENIOR_PROSPECT
   WHEN 40 THRU 55  PERFORM  MATURE_PROSPECT
   WHEN 21 THRU 39  PERFORM  YOUNG_PROSPECT
   WHEN OTHER       PERFORM  NOT_A_PROSPECT
END-EVALUATE.

Code Example 2:

EVALUATE INCOME ALSO TRUE
   WHEN  20000 THRU 39999  ALSO RISK_CLASS = "A"
      PERFORM LOW_INCOME_PROSPECT
   WHEN  40000 THRU 59999  ALSO RISK_CLASS = "A"
      PERFORM  MID_INCOME_PROSPECT
   WHEN  60000 THRU 999999 ALSO RISK_CLASS = "A"
      PERFORM  HIGH_INCOME_PROSPECT
   WHEN  60000 THRU 999999 ALSO NOT RISK_CLASS = "A"
      PERFORM  HIGH_INCOME_HIGH_RISK_PROSPECT
   WHEN  OTHER
      PERFORM UNCLASSIFIED_PROSPECT
END-EVALUATE.

Highlights for First-time Users

  1. Statement subjects (associated with the EVALUATE phrase) and statement objects (associated with the WHEN phrase) must be equal in number, correspond by position and be valid operands for comparison. Note the number and order of subjects in example 2 and the correspondent number and position of WHEN objects.
  2. If all of the conditions in a WHEN phrase match, the associated imperative statement is executed. None of the remaining WHEN phrases is evaluated. Program execution then falls through to the end of the EVALUATE statement.
  3. The WHEN OTHER phrase is an optional phrase for the handling of all remaining cases (the set of possible conditions not explicitly tested for by the preceding WHEN phrases). The WHEN OTHER phrase, if present, must be the last WHEN phrase in the statement.
  4. The words TRUE and FALSE may be used in the subject or object phrase to specify a literal truth condition.
  5. The word ANY may be used in the WHEN phrase to specify an unconditional match with the corresponding item in the subject phrase.
  6. The word NOT may be used in the WHEN phrase to negate its associated condition.
  7. The word THROUGH or THRU may be used in the WHEN phrase to describe a range of values. When combined with NOT, THRU describes an excluded set of values. For example, NOT 10 THRU 20 means that any object holding a value from 10 to 20, including the numbers 10 and 20, will result in a FALSE, or no match evaluation.
Parent topic: Procedure Division Statements


EXHIBIT Statement

The EXHIBIT statement causes an (optionally conditional) display of the literals, and/or variables (optionally preceded by the variable name) specified in the statement. This statement is only supported when a program is compiled in IBM OSVS compatibility mode (-Cv or -Cv=OSVS).

General Format

EXHIBIT [NAMED] [CHANGED] {literal | variable} ...

General Rules

  1. If neither NAMED nor CHANGED is used, each literal and variable value is displayed.
  2. If only NAMED is used, each literal is displayed, and each variable is displayed. Variables are preceded by variable-name= (where variable-name is replaced with the name of the variable in the EXHIBIT statement).
  3. If only CHANGED is used, each literal is displayed, and each variable is displayed if its value is different from the last time this EXHIBIT verb was executed.
  4. If both NAMED and CHANGED are used, each literal is displayed, and each variable is displayed if its value is different from the last time this EXHIBIT verb was executed. In addition, each variable is preceded by variable-name= (where variable-name is replaced with the name of the variable in the EXHIBIT statement).
  5. As a compatibility issue, its recommended that you modify your source code to use actual DISPLAY statements, and that you not add new EXHIBIT statements to your COBOL program.
Parent topic: Procedure Division Statements


EXIT Statement

The EXIT statement returns control to a calling program or provides a common logical end point for a series of procedures.

Format 1

EXIT

Format 2

EXIT PROGRAM [ {RETURNING} return-value ]
               {GIVING   }

Format 3

EXIT PERFORM [ CYCLE ]

Format 4

EXIT  {PARAGRAPH}
      {SECTION  }

Syntax Rules

  1. A Format 1 EXIT statement must be in a sentence by itself, and that sentence must be the only sentence in its paragraph.
  2. return-value must be a numeric literal or data item.
  3. An EXIT PERFORM statement must occur within the scope of an in-line PERFORM statement.
  4. An EXIT SECTION statement must be contained within a section.

Format 1 General Rules

A Format 1 EXIT statement associates a paragraph name with a point in the program. It has no effect on program execution. A paragraph containing a Format 1 EXIT statement is equivalent to an empty paragraph.

Format 2 General Rules

  1. An EXIT PROGRAM statement has no effect if executed in a program that is the first program of a thread or any program that was not called by another. Neither does it have any effect if it is executed within the scope of an EVENT procedure, unless the return point is also within the scope of the EVENT procedure.
  2. In a called program, the EXIT PROGRAM statement causes the current program to exit, and execution resumes at the next executable statement after the CALL statement in the calling program.
  3. If the exiting program has the initial attribute, it is immediately canceled. If it does not have the initial attribute, it retains its current state the next time it is called.
  4. If return-value is specified, then it is assigned to the special register RETURN-CODE before the program is exited. This special register is defined as:
    77  RETURN-CODE SIGNED-LONG, EXTERNAL.

    It is implicitly shared by all programs of a run unit and is automatically created by the compiler. The final value of RETURN-CODE is returned to the host operating system when the run unit completes. The compiler also creates an unsigned version of the return code called RETURN-UNSIGNED. It has the following implied definition:

77  RETURN-UNSIGNED
          REDEFINES RETURN-CODE UNSIGNED-LONG, EXTERNAL.

Format 3 General Rules

  1. An EXIT PERFORM statement causes control to pass to a point just past the END-PERFORM that matches the innermost PERFORM statement containing the EXIT PERFORM. This causes the program to jump out of the innermost in-line PERFORM.
  2. If the CYCLE option is given, then control is passed to a point just prior to the matching END-PERFORM instead. For PERFORM constructs that imply looping, this will cause control to pass to the next iteration of the loop (note that the loop-terminating condition will be tested).

Format 4 General Rules

  1. An EXIT PARAGRAPH statement causes control to pass to an imaginary CONTINUE statement placed at the end of the current paragraph.
  2. An EXIT SECTION statement causes control to pass to an imaginary CONTINUE statement placed at the end of the last paragraph in the current section.
Parent topic: Procedure Division Statements


GOBACK Statement

The GOBACK statement exits the current program regardless of whether or not it is a called program.

General Format

GOBACK { [ {RETURNING} return-value] }
           {GIVING   }

Syntax Rules

  1. If a GOBACK statement is in a consecutive sequence of imperative statements in a sentence, it must be the last statement in that sentence.
  2. return-value must be a numeric literal or data item.

General Rules

  1. The GOBACK statement is equivalent to the statement sequence
    EXIT PROGRAM; STOP RUN
This causes the current program to return to the caller if it is a called program or causes the run unit to halt if the program is not a called program.
  2. If return-value is specified, then it is assigned to the special register RETURN-CODE before the program is exited. This special register is defined as:
    77  RETURN-CODE  SIGNED-LONG, EXTERNAL.

    It is implicitly shared by all programs of a run unit and is automatically created by the compiler. The final value of RETURN-CODE is returned to the host operating system when the run unit completes. The compiler also creates an unsigned version of the return code called RETURN-UNSIGNED. It has the following implied definition:

    77 RETURN-UNSIGNED
      REDEFINES RETURN-CODE UNSIGNED-LONG, EXTERNAL.
Parent topic: Procedure Division Statements


GO TO Statement

The GO TO statement provides for a direct transfer of control in the Procedure Division.

Format 1

GO TO procedure-name

Format 2

GO TO {procedure-name} ... DEPENDING ON depend-item

Syntax Rules

  1. procedure-name is the name of a paragraph or section in the program.
  2. depend-item is an integer elementary numeric data item.
  3. A Format 1 GO TO that is in a consecutive sequence of imperative statements in a sentence must be the last statement in that sentence.

Format 1 General Rules

The GO TO statement transfers control to procedure-name. No return mechanism is implied.

Format 2

  1. The GO TO DEPENDING statement transfers control to one of the procedure-names depending on the value of depend-item. A depend-item value of 1 refers to the first procedure-name, a value of 2 refers to the second, and so on.
  2. If depend-item is less than or equal to zero, or is greater than the number of procedure-names, no control transfer occurs. In this case, the GO TO statement has no effect.
Parent topic: Procedure Division Statements


IF Statement

The IF statement provides for conditional action by the program.

General Format

IF condition THEN { {statement-1} }
                  { NEXT SENTENCE }

    [ ELSE {statement-2 } [END-IF] ]
    [ ELSE NEXT SENTENCE           ]
    [ END-IF                       ]

Syntax Rules

  1. statement-1 and statement-2 are imperative or conditional statements. An imperative statement can precede a conditional statement.
  2. condition is any conditional expression.
  3. The ELSE NEXT SENTENCE phrase is optional if it immediately precedes a period ending a sentence.
  4. If END-IF is specified, NEXT SENTENCE must not be specified.

General Rules

  1. The IF statement provides a method for selecting alternate sets of statements to execute depending on the truth value of condition.
  2. The scope of an IF statement ends when one of the following is encountered:
    1. A period ending a sentence.
    2. An END-IF phrase at the same nesting level.
    3. An ELSE phrase associated with an IF statement at a higher nesting level.
  3. If condition is true, then statement-1 executes. statement-2 is not executed. If NEXT SENTENCE is used instead of statement-1, control immediately passes to the next executable sentence. Note that the ANSI standard states that "NEXT SENTENCE is an archaic feature and its use should be avoided."
  4. If condition is false, statement-2 executes. statement-1 is not executed. If the ELSE NEXT SENTENCE phrase is used, control immediately passes to the next executable sentence. If the ELSE phrase is not present, then control passes to the end of the IF statement.
  5. OTHERWISE is a synonym for ELSE in the IBM DOS/VS COBOL -Cv compatibility mode. See IBM DOS/VS COBOL Conversions in Transitioning to ACUCOBOL-GT for more information.
Parent topic: Procedure Division Statements


INITIALIZE Statement

The INITIALIZE statement sets selected types of elementary data items to chosen values.

General Format

INITIALIZE { destination } ... [ WITH FILLER ]

[ REPLACING { {ALPHABETIC         } DATA BY value }...]
              {ALPHANUMERIC       }
              {NUMERIC            }
              {ALPHANUMERIC-EDITED}
              {NUMERIC-EDITED     }

Syntax Rules

  1. destination is a data item.
  2. value is a literal or a data item. It must be a legal source for a MOVE to the corresponding category of data. For example, a value appearing in a REPLACING ALPHABETIC BY clause must have a category of alphabetic, alphanumeric, or alphanumeric-edited.
  3. The same category cannot be repeated in a REPLACING phrase.
  4. destination may not be an index data item.
  5. destination may not contain a RENAMES clause.

General Rules

  1. Whether destination references an elementary item or a group item, all operations are performed as if a series of MOVE statements had been written, each of which has an elementary item as its receiving field according to the following rules:
    1. If destination is a group item, any elementary item contained in destination is initialized only if it belongs to a category specified by the REPLACING phrase.
    2. If destination is an elementary item, that item is initialized only if it belongs to a category specified in the REPLACING phrase.
    3. Each data item that is initialized is treated as the receiving operand of an implicit MOVE statement with the corresponding value as the sending field.
    4. All elementary receiving fields, including all table occurrences, are affected, except as specified in the following rules.
  2. Index data items and elementary FILLER data items are not affected by the INITIALIZE statement, unless the optional WITH FILLER phrase is specified, in which case FILLER data items are initialized.
  3. Any item that is subordinate to destination and which contains a REDEFINES clause, or any item that is subordinate to such an item, is excluded from this operation. Destination itself, however, may be subordinate to a REDEFINES clause.
  4. If no REPLACING phrase is specified, alphabetic, alphanumeric, and alphanumeric-edited data items are initialized to SPACES; numeric and numeric-edited data items are initialized to ZEROS.
  5. If multiple destinations are specified, they are initialized in the order written.
  6. destinations that are or contain OCCURS DEPENDING ON items will use the maximum number of occurrences when being initialized.
Parent topic: Procedure Division Statements


INQUIRE Statement

The INQUIRE verb allows you to retrieve information from a control, or retrieve the dimensions of a window.

General Format

INQUIRE { control-item } [ ( {index-1} ... ) ]
        { CONTROL      }

Remaining phrases are optional, can appear in any order.

AT screen-loc   [CELL  ]
                [CELLS ]
                [PIXEL ]
                [PIXELS]

AT LINE NUMBER line-num   [CELL  ]
                          [CELLS ]
                          [PIXEL ]
                          [PIXELS]

AT {COLUMN  } NUMBER col-num   [CELL  ]
   {COL     }                  [CELLS ]
   {POSITION}                  [PIXEL ]
   {POS     }                  [PIXELS]

AT CLINE NUMBER cline-num   [CELL ]
                            [CELLS]

AT CCOL NUMBER ccol-num   [CELL ]
                          [CELLS]

TITLE {IN} title
      {= }

VALUE {IN} [ MULTIPLE ] value [ LENGTH {IN} length-1 ]
      {= } [ TABLE    ]                {= }

STYLE {IN} style-flags
      {= }

HELP-ID {IN} help-id
        {= }

{{property-name         } [({param-expr}...)] {IN} property-value ...
 {PROPERTY property-name}                     {= }
 {object-expression     }
     [ LENGTH {IN} length-1 ] }
              {= }
SYSTEM HANDLE {IN} system-handle
              {= }

POP-UP MENU {IN}  {menu-1}
            {= }

LINE NUMBER {IN} line-num
            {= }

{COLUMN  } NUMBER {IN} col-num
{COL     }        {= }
{POSITION}
{POS     }

SIZE {IN} width
     {= }

LINES {IN} height
      {= }

MAX-HEIGHT {IN} max-height
           {= }

MAX-WIDTH  {IN} max-width
           {= }

MIN-HEIGHT {IN} min-height
           {= }

MIN-WIDTH  {IN} min-width
           {= }
ID {IN} id
   {= }

CLASS {IN} class-code
      {= }

EXCLUDE-EVENT-LIST {IN} list-state
                   {= }

LAYOUT-DATA {IN} layout-data
            {= }
ENABLED {IN} enabled-state
        {= }

VISIBLE {IN} visible-state
        {= }

where param-expr is one of the following:

{ param                               } [ AS type_num ]

{ {BY} NAME parameter-name {IS} param }
{                          {= }       }

{ parameter-name {IS} param           }
{                {= }                 }

object-expression has the following format:

{ {^} property-1 [ (param-expr ... ) ]
  [ :: property-2 [ ( param-expr ... ) ] ... }

Format 2

INQUIRE { window-handle           }
        { WINDOW [generic-handle] }

Remaining phrases are optional, can appear in any order.

LINE NUMBER {IN} line-no
            {= }

{COLUMN  } NUMBER {IN} col-num
{COL     }        {= }
{POSITION}
{POS     }

TITLE {IN} title
      {= }

SCREEN LINE NUMBER {IN} screen-line
                   {= }

SCREEN {COLUMN  } NUMBER {IN} screen-col
       {COL     }        {= }
       {POSITION}
       {POS     }

SIZE {IN} width
     {= }

LINES {IN} height
      {= }

SYSTEM HANDLE {IN} system-handle
              {= }

LAYOUT-MANAGER {IN} layout-manager
               {= }
VISIBLE {IN} visible-state
        {= }

POP-UP MENU {IN} menu-1
            {= }

Syntax Rules

  1. control-item is a USAGE HANDLE data item that identifies the control to be inquired. If it is a typed handle, then it must be associated with a control. control-item can also be an elementary Screen Section item that describes a control.
  2. index-1 is a numeric expression. The parentheses surrounding index-1 are required.
  3. The AT, LINE, COLUMN, CLINE, and CCOL phrases must appear in conjunction with the CONTROL phrase.
  4. screen-loc is an integer data item or literal that contains exactly 4, 6, or 8 digits.
  5. line-num, col-num, cline-num, and ccol-num are numeric data items or literals. Note that they may contain non-integer values, except when pixels are specified.
  6. title is an alphanumeric data item.
  7. value may be any data item.
  8. style-flags is a numeric data item capable of holding 10 or more digits.
  9. help-id is a numeric data item.
  10. property-name is the name of a property specific to the type of control being inquired. If control-item refers to a generic handle, or if the CONTROL option is specified, then property-name cannot be used. Use the PROPERTY phrase instead.
  11. property-type is a numeric literal or data item.
  12. property-value is a data item. Its data type should be appropriate for the specified property.
  13. In param-expr:
    1. param is a literal, data-item, or numeric expression used when inquiring the property value of an ActiveX control or COM object.
    2. type-num is a numeric data item or numeric literal.
  14. In object-expression:
    1. ^ can only be used in conjunction with a Format 5 USE verb for an ActiveX control or COM object.
    2. property-1 is the name of a property of the ActiveX control or COM object. property-1 cannot be a write-only property.
    3. property-2 is the name of a property of the ActiveX control or COM object that is the value of property-1. property-2 cannot be a write-only property.
  15. length-1 is a numeric data item. The LENGTH phrase may be specified only if the value or property-value immediately preceding it is an alphanumeric data item.
  16. window-handle is a USAGE HANDLE OF WINDOW or PIC X(10) data item.
  17. generic-handle is a USAGE HANDLE, HANDLE OF WINDOW, or PIC X(10) data item.
  18. line-no, col-no, screen-line, screen-col, width, height, max-height, max-width, min-height, and min-width are numeric data items. line-no and col-no should be signed and have at least two digits after the decimal point to get the best results. screen-line and screen-col should be signed to get the best result.
  19. system-handle, visible-state, and layout-data are numeric data items.
  20. menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
  21. id, class-code, and enabled-state are numeric data items.
  22. list-state is a numeric data item.
  23. layout-manager is a HANDLE or HANDLE OF LAYOUT-MANAGER data item.
  24. In Format 1, the LINE IN phrase and the COLUMN IN phrase may be used only if the control-item option is specified.

Format 1 General Rules

  1. The INQUIRE CONTROL statement retrieves some or all of a control's current properties, and stores them as data items. It can also be used to retrieve property data from ActiveX controls, COM objects, and .NET controls (also known as assemblies). control-item identifies the control to inquire. If the CONTROL phrase is used instead, the runtime inquires the control located at the screen position specified by the AT, LINE, and COLUMN phrases in the current window (on non-graphical systems, the CLINE and CCOL phrases also apply). The runtime system maintains a list of controls in each window. When you are attempting to inquire from a control at a specific location, the runtime searches this list, inquiring the first control it finds that exactly matches the given location. The list is maintained in the order in which the controls are created.
  2. If control-item does not refer to a valid control, or if the runtime cannot locate a control at the specified screen location, the INQUIRE statement has no effect.
  3. If index-1 is specified, then certain properties in the control being inquired are modified to match the value of index-1. This modification occurs before any inquiry occurs. The exact set of properties modified depends on the control's type. Three controls have properties that are modified in this way:
    Control Type | Properties Affected
    List Box | QUERY-INDEX
    Grid | Y, X
    Tree View | ITEM

    Each occurrence of index-1 modifies one property. The first occurrence modifies the first property in the list presented in the preceding table. The second occurrence modifies the second property. For example, the statement fragment

    INQUIRE grid-1(2, 3)

    Would have the effect of setting the grid property Y to 2 and X to 3. Supplying more index values than the control supports has no additional effect. You may omit trailing indexes; this leaves the corresponding properties unchanged. This feature can be used to simplify inquiry on specific elements of controls that hold multiple values. For example, you can retrieve the contents of row 2, column 3 in a grid with the statement:

    INQUIRE grid-1(2, 3), CELL-DATA IN data-1

    This is exactly equivalent to the more cumbersome:

    MODIFY grid-1, Y = 2, X = 3
INQUIRE grid-1, CELL-DATA IN data-1
  4. When the runtime is storing data items, the rules for the MOVE statement are applied. The source for the title is alphanumeric. The type of control determines the source format of the value. The source format for a property is either numeric or alphanumeric depending on the specific property.
  5. When used with an ActiveX control or COM object, INQUIRE gets the value of a property or gets the style flags.
  6. When the PROPERTY phrase is used to set an ActiveX control or COM object, the runtime automatically converts parameters to the appropriate styles.
  7. When the LENGTH option is specified, length-1 gives you the exact number of characters that were placed by the control in value or property-value. This option is useful in determining how long the logical data is in value or property-value, or if there are trailing spaces. If, for example, you inquired the SELECTION-TEXT property in an entry-field and specified the LENGTH option, you could tell if the user's selection contains trailing spaces. If you do not use the LENGTH option, your program will not distinguish between the trailing spaces in the selection and the trailing spaces added by the runtime.
  8. The SYSTEM HANDLE phrase retrieves the host graphical system's handle that corresponds to the control and stores this value in system-handle. This value is the way the host graphical system identifies the control. You usually need it if you want to affect the control from some other language such as C. There is no use for the host system's handle if you are using only ACUCOBOL-GT; the handle is useful only when you need to have another language interact with an ACUCOBOL-GT screen.
  9. Each host system defines its own technique for identifying graphical components. Under Windows, the Windows API uses the HWND type, which is a 32-bit unsigned value. You can use UNSIGNED-INT as an appropriate USAGE type for system-handle to cover these two cases portably.
  10. If the control does not have a corresponding host handle, then system-handle is set to zero. This indicates that either the host system does not have an underlying graphical system, or that the particular control does not use the host's notion of a control in its implementation.
  11. The POP-UP MENU option returns the handle of the pop-up menu associated with the control in menu-1. If the control has no pop-up menu, menu-1 is set to NULL.
  12. The LINE NUMBER IN and COLUMN NUMBER IN phrases return the location of the control in line-num and col-num respectively. The SIZE IN and LINES IN phrases return the dimensions of the control in width and height respectively. These values have the same meaning and units that they have in a DISPLAY or MODIFY statement.
    Note: In order for the LINES IN and SIZE IN phrases to return a value, the control must have been created with its LINE and SIZE dimensions specified. Then the value returned is in the units used to create the control. If the control was not given dimensions when it was created, the INQUIRE statement has no effect.
  13. The MAX-HEIGHT, MAX-WIDTH, MIN-HEIGHT, and MIN-WIDTH phrases return the value of the control's current maximum and minimum size restrictions in max-height, max-width, min-height, and min-width, respectively. These values have the same meaning and units that they have in a DISPLAY or MODIFY statement.
  14. The ID IN phrase returns the control's ID if it has one. If it does not (or the control does not exist), id is set to zero.
  15. The CLASS IN phrase returns the type of the control (label, entry field, etc). This is coded as a unique number for each class. The appropriate values can be found in the COPY library controls.def.
  16. The LAYOUT-DATA IN phrase sets layout-data to the current value of the control's LAYOUT-DATA property.
  17. The ENABLED IN phrase sets enabled-state to 1 if the control is enabled and 0 if the control is disabled.
  18. The VISIBLE IN phrase sets visible-state to 1 if the control is visible and 0 if it is invisible.
  19. You cannot use named parameters to avoid entering required parameters. You can omit optional parameters only.
  20. You must specify only unnamed parameters before the BY NAME clause, and only named parameters after the BY NAME clause.
  21. You can use one- and two-dimensional COBOL tables as property and method parameters for use in COM SAFEARRAYs. The runtime automatically converts the table to an COM SAFEARRAY, as long as it contains only one elementary item that is USAGE HANDLE or USAGE HANDLE OF VARIANT. See Properties Styles and Methods in A Guide to Interoperating with ACUCOBOL-GT.
  22. Use the AS type-num phrase in the parameter expression if you want to force the parameter to be converted to a particular VARIANT type before it is passed to a property or method of an ActiveX control or COM object. You can tell from the object's documentation and the name of the parameter whether the object expects a particular VARIANT type, such as boolean.

    Use the AS phrase if the ActiveX or COM object requires a method or property parameter to be something different from the default VARIANT type chosen by the runtime for the particular COBOL data item or literal. Specify the word AS followed by a numeric literal or level 78 numeric constant that indicates the variant type to which you want the parameter converted. The activex.def COPY file in the ACUCOBOL-GT sample/def directory contains predefined level 78 constants for each of the VARIANT types. See Properties Styles and Methods in A Guide to Interoperating with ACUCOBOL-GT for the rules that the runtime uses to determine the VARIANT type.

Format 2 General Rules

  1. The INQUIRE WINDOW statement returns one or more attributes of the window identified by window-handle or generic-handle. If the WINDOW phrase is used and generic-handle is omitted, information is retrieved from the current window.
  2. The LINE NUMBER and COLUMN NUMBER phrases return the position of the window relative to the interior of its parent. For the initial window, this will always be line 1, column 1. Note that the position returned can be negative, or larger than the parent window, indicating that the window's upper left corner is outside of its parent's interior.
  3. The TITLE phrase returns the title of the current window.
  4. The SCREEN LINE and SCREEN COLUMN phrases return the position of the window on the screen. This is an absolute position, not relative to any other window. The position is expressed in the screen's base units, with 1, 1 being the upper left corner of the screen. Screen base units are machine dependent. Under character systems, the base unit is a character cell, for graphical systems, the base unit is a pixel. A negative value indicates that the window's home location (the upper left corner) is off the screen.
  5. The SIZE and LINES phrases return the window's width and height, respectively.
  6. The SYSTEM HANDLE phrase retrieves the host graphical system's handle that corresponds to the window and stores this value in system-handle. This value is the way the host graphical system identifies the window. You usually need it if you want to affect the window from some other language such as C. There is no use for the host system's handle if you are using only ACUCOBOL-GT; the handle is useful only when you need to have another language interact with an ACUCOBOL-GT screen.
  7. Each host system defines its own technique for identifying graphical components. Under Windows, the Windows API uses the HWND type, which is a 32-bit unsigned value. You can use UNSIGNED-INT as an appropriate USAGE type for system-handle to cover these two cases portably.
  8. If the window does not have a corresponding host handle, then system-handle is set to zero. This indicates that either the host system does not have an underlying graphical system, or that the particular window does not use the host's notion of a control in its implementation.
  9. The LAYOUT-MANAGER phrase sets layout-manager to the handle of the layout manager currently attached to the window.
  10. The VISIBLE option returns in visible-state whether the window is visible or invisible. visible-state is set to 1 if the window is visible, or 0 if it is invisible.
    Note: A visible window may actually be hidden behind other windows on the screen, and thus may not actually be viewable by the user.
  11. The POP-UP MENU option returns the handle of the pop-up menu associated with the window in menu-1. If the window has no pop-up menu, menu-1 is set to NULL.
Parent topic: Procedure Division Statements


INSPECT Statement

The INSPECT statement supports counting and modification of single characters or groups of characters within a data item. INSPECT performs its operations on strings and requires that the source data item be designated USAGE DISPLAY.

INSPECT performs three basic functions: TALLYING, REPLACING, and CONVERTING. (CONVERTING is a specialized, shorthand form of REPLACING).

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

Format 1

INSPECT source

 [ TALLYING { counter FOR { { {ALL    } comp-val }
                            { {LEADING}          }
                            {     CHARACTERS     }

           [delim] } ... } ... ] ...

 [ REPLACING

    { CHARACTERS BY repl-char [delim]        }
    { {ALL    }                              }
    { {LEADING} { targ BY repl [delim] } ... }
    { {FIRST  }                              }
                      ... ]

Format 2

INSPECT source
    CONVERTING comp-chars TO conv-chars  [delim]

delim has the following format:

    { {BEFORE} INITIAL delimiter } ...
      {AFTER }

Format 3

INSPECT source

    [ TALLYING counter FOR TRAILING comp-value ]
    [ REPLACING TRAILING target BY replace ]

Syntax Rules

  1. source is a data item with USAGE DISPLAY.
  2. counter is an elementary numeric data item.
  3. comp-val is a nonnumeric literal (other than an ALL literal) or an elementary alphabetic, alphanumeric, or numeric data item with USAGE DISPLAY.
  4. repl-char is a one-character item with the same restrictions as comp-val.
  5. targ, delimiter, repl, comp-chars, and conv-chars have the same restrictions as comp-val.
  6. In Formats 1 and 3, at least one of the TALLYING or REPLACING phrases must be specified.
  7. Any delim phrase may have no more than one AFTER and one BEFORE phrase in it.
  8. The sizes of the data referred to by targ and repl must be the same. If repl is a figurative constant, its size is set equal to the size of targ.
  9. When the CHARACTERS phrase of the REPLACING clause is used, delimiter (if specified) must have a data size of one character.
  10. The sizes of the data referred to by comp-chars and conv-chars must be the same. When conv-chars is a figurative constant, its size equals that of comp-chars.
  11. The same character cannot appear more than once in the data referred to by comp-chars.
  12. comp-value, target, and replace are nonnumeric literals or single-character alphanumeric data items.

General Rules

  1. Inspection starts at the leftmost character of source and proceeds character by character until it reaches the rightmost character.
  2. source, comp-val, delimiter, targ, repl, repl-char, comp-chars, and conv-chars are treated as if they were redefined by an alphanumeric elementary data item. The data referred to by these items is treated as a character string.
  3. If the size of source is zero characters, no inspection occurs.
  4. If the size of comp-val or targ is zero characters, no match in source by these items is successful.
  5. comp-val and targ are matched in the source string according to the following rules:
    1. Comparison starts at the leftmost character and proceeds character by character until the rightmost character of source is reached.
    2. The first comp-val or targ item is checked at the current character location for a match. A match occurs if every character of comp-val or targ is the same as the corresponding characters in source starting at the current character position.
    3. If no match occurs, successive comp-val or targ items are checked at the current character position until a match occurs or the list of items is exhausted. The next character position is then checked and the process repeats.
    4. When a match occurs, the specified tallying or replacement is performed. Further checking for matching items at this character position is not performed. The new next character position to use for matching is set to be the character to the immediate right of the rightmost character position that matched in the preceding comparison.
    5. Inspection halts when the rightmost character of source has served as the current matching character position or has been successfully matched in the preceding rule.
    6. When the CHARACTERS phrase is present, inspection proceeds as if a single-character value were being compared and it successfully matches every character in source.
  6. The BEFORE phrase modifies the character position to use as the rightmost position in source for the corresponding comparison operation. Comparisons in source occur only to the left of the first occurrence of delimiter. If delimiter is not present in source, then the comparison proceeds as if there were no BEFORE phrase.
  7. The AFTER phrase modifies the character position to use as the leftmost position in source for the corresponding comparison operation. Comparisons in source occur only to the right of the first occurrence of delimiter. This character position is the one immediately to the right of the rightmost character of the delimiter found. If delimiter is not found in source, the INSPECT statement has no effect (no tallying or replacement occurs).
  8. If both the TALLYING and REPLACING phrases are present, the TALLYING option is performed first, and then the REPLACING option is performed as if it were written as a separate INSPECT statement.
TALLYING Option
  1. The INSPECT statement does not initialize counter.
  2. If the ALL phrase is present, counter is incremented by one for each occurrence of comp-value in source.
  3. If the LEADING phrase is present, counter is incremented by one for each contiguous occurrence of comp-value in source. These occurrences must start at the position in source where comparison begins. Otherwise, no tallying occurs.
  4. If the CHARACTERS phrase is present, counter is incremented by one for each character in source that is matched (see General Rule 5f above).
  5. If the FOR TRAILING phrase is present, counter is incremented by one for each contiguous occurrence of comp-value in source, starting at the rightmost (trailing) character and scanning leftwards. If the rightmost character is not comp-value, then counter is not incremented.
REPLACING Option
  1. The adjectives ALL, LEADING, and FIRST apply to succeeding compare items until the next such adjective appears.
  2. If the CHARACTERS phrase is used, each character matched in source is replaced by the single character repl-char.
  3. When the ALL phrase is present, each occurrence of targ matched in source is replaced by repl.
  4. If the LEADING phrase is present, each contiguous occurrence of targ matched in source is replaced by repl. These occurrences must begin at the leftmost position in source used for comparison.
  5. When the FIRST phrase is present, the leftmost occurrence of targ matched in source is replaced by repl.
  6. If the TRAILING phrase is present, the REPLACING option causes all contiguous occurrences of target to be replaced by replace, provided that these occurrences end in the rightmost character position of source.
  7. It is possible for a size mismatch between the INSPECT and REPLACING data items to occur during program execution. This could happen when reference modification is used, because in that case the length of a data item is not known at compile time. If such a mismatch occurs, the runtime generates the INSPECT REPLACING size mismatch error. This error belongs to the intermediate class of runtime errors which call installed error procedures. See CBL_ERROR_PROC in Appendix I. Library Routines for details.
CONVERTING Option
  1. The CONVERTING form of the INSPECT statement has the effect of replacing every character in source found in comp-chars with the corresponding character in comp-chars. This is done according to the following rules:
    1. The INSPECT statement is treated as if it were specified with the REPLACING option containing a series of ALL phrases, one for each character of comp-chars.
    2. The targ item in each ALL phrase refers to a single character of comp-chars.
    3. The repl item in each ALL phrase refers to a single character of conv-chcomp-charsars.
    4. The individual characters of comp-chars and conv-chars correspond by ordinal position.
  2. INSPECT CONVERTING is usually more efficient than the corresponding INSPECT REPLACING statement.

Code Example 1

Use INSPECT to count the number of occurrences of a character or string:

01  CHAR-COUNT  PIC 99 VALUE 0.

*count all "b"s
INSPECT INPUT-ITEM
   TALLYING CHAR-COUNT FOR ALL "B".
Value of INPUT-ITEM | CHAR-COUNT
#BB44@#AL23#AL88#xx#CC12 | 2
#BB@#BBBB#CCCC#xxDD | 6
BB@#BB#BB | 6
*count all "#"s found after the first "@"
*and before the first "x"
INSPECT INPUT-ITEM
  TALLYING CHAR-COUNT FOR ALL "#":
     AFTER "@" BEFORE "x".
Value of INPUT-ITEM | CHAR-COUNT
#BB44@#AL23#AL88#xx#CC12 | 3
#BB@#BBBB#CCCC#xxDD | 3
BB@#BB#BB | 2
*count all characters
INSPECT INPUT-ITEM
   TALLYING CHAR-COUNT FOR CHARACTERS.
Value of INPUT-ITEM | CHAR-COUNT
#BB44@#AL23#AL88#xx#CC12 | 24
#BB@#BBBB#CCCC#xxDD | 19
BB@#BB#BB | 9

Code Example 2

Use INSPECT to replace matching characters or strings:

INSPECT NAME-LIST REPLACING
*if the first characters in the string are "a"
*replace the "a"s with "A"s
   LEADING "a" BY "A"
*replace all "T"s found after the first "/"
*with "t"
   ALL "T" BY "t" AFTER "/"
*replace all "/"s with ":"
   ALL "/" BY ":"
*after the first "-" replace all characters
*in the string with "Z"
   CHARACTERS BY "Z" AFTER "-".
Input value NAME-LIST | Output value NAME-LIST
TED/TRAVIS/UREY/VENNEY | TED:tRAVIS:UREY:VENNEY
aVERY/BLAZE/TERI | AVERY:BLAZE:tERI
MAVIS-GUS-HAL-WESTON | MAVIS-ZZZZZZZZZZZZZZ

Code Example 3

Use INSPECT to both tally and replace characters or strings:

INSPECT PART-LIST
*count all "P-"
   TALLYING P-COUNT FOR ALL "P-"
*replace all "xx" by "__"
   REPLACING ALL "xx" BY "__".

Value of PART-LIST | P-COUNT
P-BOLTxxP-WASHERxxP-NUT | 3
Input value PART-LIST | Output value PART-LIST
P-BOLTxxP-WASHERxxP-NUT | P-BOLT__P-WASHER__P-NUT

Code Example 4

Use INSPECT/CONVERT to convert every occurrence of the specified characters in the input string (equivalent to a series of REPLACE ALL phrases). The list of characters following the words CONVERT and TO is not a string, but, rather, a list of individual characters. INSPECT/CONVERT replaces every occurrence of each character in the CONVERT list with the character in the matching ordinal position of the TO list. AFTER and BEFORE can be used to bracket a portion of the source string.

*convert all occurrences of:
*"-" to "0", "l" to "L",
*"a" to "A" and "/" to ":"
INSPECT PART-LIST
   CONVERTING "-la/" TO "0LA:".

This INSPECT/CONVERT statement is equivalent to:

INSPECT PART-LIST
   REPLACING ALL "-" BY "0"
             ALL "l" BY "L"
             ALL "a" BY "A"
             ALL "/" BY ":".
Input value PART-LIST | Output value PART-LIST
Yla-1/Yla-2/Yla-3/Yla21 | YLA01:YLA02:YLA03:YLA21

Highlights for First-time Users

  1. How the matching process works:

    In all formats of the INSPECT statement there must be a set of specified match values. The match values may be single characters or strings, or a mix of both. The match values are the arguments specified after the TALLYING/FOR, REPLACING, or CONVERTING key words, and before the BY or TO key words (for further clarification see the example that follows).

    INSPECT attempts to locate the match values in the source data item. The match values are searched for, in order of appearance in the code, at each position in the source string. Inspection starts at the leftmost character of the source data item and proceeds, character by character, to the rightmost character.

    Match process example:

    INSPECT source-data-item
  REPLACING "cd" BY "QP"
            "e"  BY "T"
            "f"  BY "V".

    Source data item: "abcdefg"

    Set of match values: "cd", "e", "f"

    The search begins at the leftmost character:

    "abcdefg"
 ^

    The first value in the match set is "cd". The first element, "c", is compared to the value "a" for a match. No match. The second value in the match set is "e". "e" is tested for a match with "a". No match. The third value in the match set is "f". "f" is tested for a match with "a". No match. There are no untested values remaining in the match set. The current position in the source data item is advanced one position to the right.

    "abcdefg"
  ^

    The sequential testing of the members of the match set to the value of the current position in the source data item is repeated. None matches. The current position in the source data item is advanced one position to the right.

    "abcdefg"
   ^

    The first match value is "cd". "c" is tested for a match with the current position in the source data item and there is a match. "d" is tested against the value of 1 + the current position ("d") and, again, there is a match. There are no more characters in the match value ("cd"). The first value in the match set results in a complete match at the current position in the source data item. Remaining values in the match set are not tested. The specified REPLACING action is performed. The current position in the source data item is advanced the length of the match value ("cd"), two places to the right.

    "abQPefg"
     ^

    Sequential testing of the members of the match set to the value of the current position in the source data item is repeated. The second member of the match set, "e", is a match. The REPLACING action is performed and the current position in the source data item is advanced the length of the match value, one position to the right.

    "abQPTfg"
      ^

    Notice that, if we had replaced "cd" with "ef" instead of "QP", the "e" and "f" would not be subsequently replaced with "T and "V". Sequential testing of the members of the match set to the value of the current position in the source data item is repeated. The third member of the match set, "f", is a match. The REPLACING action is performed and the current position in the source data item is advanced the length of the match value, one position to the right.

    "abQPTVg"
       ^
    Sequential testing of the members of the match set to the value of the current position in the source data item is repeated. None matches. The current position in the source data item is the rightmost character; therefore, the inspection halts. For a more concise description of the matching process, see General Rule 5 above.
  2. All replacement actions must replace the same number of characters as matched. The source data item may not change in size.
  3. Use AFTER and BEFORE to bracket (define) a substring in the source data item.
  4. Use ALL to match all occurrences of the specified value in the string.
  5. Use CHARACTERS to match every character in the source data item that hasn't already been matched. Because CHARACTERS matches all elements of the source data item, CHARACTERS usually appears as the last phrase in the statement.
  6. Use LEADING to find the leading occurrence, or set of leading contiguous occurrences, in the source data item.
  7. Use TRAILING (ACUCOBOL-GT extension) to find the rightmost occurrence, or set of contiguous occurrences, in the source data item. If a TRAILING occurrence is found, a right to left scan of the source data item is made to find contiguous occurrences.
  8. Use FIRST to specify a match of the first occurrence only.
  9. Many COBOL programming texts caution against writing involved and complicated INSPECT statements, because complex statements are difficult to understand and maintain.
Parent topic: Procedure Division Statements


LOCK Statement

The LOCK THREAD statement prevents other threads from running.

General Format

LOCK THREAD

General Rules

  1. The LOCK THREAD statement prevents other threads from running. The thread that executes the LOCK statement is the only thread allowed to run until an UNLOCK THREAD statement is executed, or the thread terminates. Locking a thread ensures that other threads will not modify a critical piece of data or other shared resource.
  2. A thread can be locked multiple times. Each time a thread executes a LOCK THREAD statement, the number of locks held by the thread increases by one. In order to unlock a thread with multiple locks, an equal number of UNLOCK THREAD statements must execute.

    This allows a thread to lock itself, call a subroutine that also locks itself, and remain locked when that subroutines unlocks itself. See UNLOCK THREAD.

Parent topic: Procedure Division Statements


MERGE Statement

The MERGE statement combines two or more identically ordered files by selected ASCENDING or DESCENDING key fields.

Unlike SORT, MERGE doesn't allow you to manipulate the records before they are merged. Like SORT, MERGE does allow you to modify records after they are merged via the OUTPUT PROCEDURE phrase.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format

MERGE merge-file

    { KEY AREA IS key-table       }

    { ON {ASCENDING } KEY {key-name}  } ...
         {DESCENDING}

    [ COLLATING SEQUENCE IS alpha-name ]

      USING {in-file} ...

    { OUTPUT PROCEDURE IS proc-name  }
    { GIVING {out-file} ...          }

proc-name has the following format:

    start-proc [ {THRU   } end-proc ]
                 {THROUGH}

Syntax Rules

  1. merge-file names a sort file described by an SD entry in the Data Division.
  2. key-table must name a data item that is not located in the record for merge-file. key-table may not be subordinate to an OCCURS clause, nor may it be reference modified.
  3. key-table must reference a data item whose size is an even multiple of 7. key-table is processed as if it had the following structure:
    01  KEY-TABLE.
    03  MERGE-KEY OCCURS N TIMES.
        05  KEY-ASCENDING   PIC X  COMP-X.
        05  KEY-TYPE        PIC X  COMP-X.
        05  KEY-OFFSET      PIC XX COMP-X.
        05  KEY-SIZE        PIC XX COMP-X.
        05  KEY-DIGITS      PIC X  COMP-X.

    Typically, programs will declare key-table with a similar format.

  4. key-name is a data item in the record description associated with merge-file. It may not be subordinate to an OCCURS clause, nor may it be a group item containing variable occurrence data items. The maximum number of keys allowed is 23.
  5. alpha-name is an alphabet-name defined in the SPECIAL-NAMES paragraph of the Environment Division.
  6. in-file and out-file are files described by FD entries in the Data Division. They may not be sort files. The maximum number of input and output files allowed is 25.
  7. start-proc and end-proc are paragraph or section names in the Procedure Division.
  8. A MERGE statement may not appear in Declaratives or in the input or output procedure of a SORT or MERGE statement.
  9. If merge-file contains variable length records, in-file records must not be smaller than the smallest record in merge-file nor larger than the largest. If merge-file contains fixed length records, in-file records may not be larger than the size of merge-file's records.
  10. If out-file contains variable length records, merge-file records must not be smaller than the smallest record in out-file nor larger than the largest. If out-file contains fixed length records, merge-file records may not be larger than the size of out-file's records.
  11. If merge-file contains more than one record description, key-name need appear in only one of them. The character positions referenced by key-name are used as the key for all the file's records.
  12. If out-file is an indexed file, the first key-name must be ASCENDING and must specify the same character positions in its record as the primary record key for out-file.
  13. THRU is an abbreviation for THROUGH.

General Rules

  1. The MERGE statement merges all the records in the in-file files into merge-file and then either writes these records to each out-file or makes these records available to the specified OUTPUT PROCEDURE.
  2. If merge-file contains fixed length records, any shorter in-file records are space-filled on the right to match the record size.
  3. If out-file contains fixed length records, any shorter merge-file records are space-filled on the right to match the record size.
  4. The first key-name is the major key, and the next key-name is the next most significant key. This pattern continues for each key-name specified.
  5. The ASCENDING phrase specifies that key values are to be ordered from lowest to highest. The DESCENDING phrase specifies the reverse ordering. Once ASCENDING or DESCENDING is specified, it applies to each key-name until another ASCENDING or DESCENDING adjective is encountered.
  6. Use the KEY AREA option when you do not know the specifics of the merge key until the program is run. You can use this to allow users to enter merge key specifications, typically in conjunction with some form of data dictionary.
  7. Your program must fill in a table of information that describes the merge keys. This table, key-table, should have the format described by Syntax Rule 3 above. The number of merge keys is determined by the number of occurrences in the table. The keys are listed in order of precedence: table entry 1 describes the highest precedence key, table entry 2 the second highest, and so on. If you need to process a variable number of keys, use a variable-size table (by using OCCURS DEPENDING ON).
  8. For each key, you must specify the following information:
    KEY-ASCENDING: This should be 0 or 1. Enter 1 to have an ascending merge sequence, 0 for descending.
    KEY-TYPE: Describes the underlying data format. The allowed values are listed in the next rule.
    KEY-OFFSET: Describes the distance (in standard character positions) from the beginning of the merge record to the beginning of the key field. The first field in a merge record is at offset 0.
    KEY-SIZE: Describes the size of the key field in standard character positions.
    KEY-DIGITS: This is used only for numeric keys. It describes the number of digits contained in the key (counting digits on both sides of the decimal point).
  9. The KEY-TYPE field uses a code to describe the type and internal storage format of the data item. Select from the following values:
    0 | Numeric edited
    1 | Unsigned numeric (DISPLAY)
    2 | Signed numeric (DISPLAY, trailing separate)
    3 | Signed numeric (DISPLAY, trailing combined)
    4 | Signed numeric (DISPLAY, leading separate)
    5 | Signed numeric (DISPLAY, leading combined)
    6 | Signed COMP-2
    7 | Unsigned COMP-2
    8 | Unsigned COMP-3
    9 | Signed COMP-3
    10 | COMP-6
    11 | Signed binary (COMP-1, COMP-4, COMP-X)
    12 | Unsigned binary (COMP-1, COMP-4, COMP-X)
    13 | Signed native (COMP-5, COMP-N)
    14 | Unsigned native (COMP-5, COMP-N)
    15 | Floating point (FLOAT, DOUBLE)
    16 | Alphanumeric
    17 | Alphanumeric (justified)
    18 | Alphabetic
    19 | Alphabetic (justified)
    20 | Alphanumeric edited
    22 | Group

    This coding is the same one used by the C interface, and is also used by Acu4GL. When specifying the key type, you may safely use "alphanumeric" for all nonnumeric keys. (The merge rules are the same for each of these types). For numeric data, however, you must specify the correct type or you may get merging errors.

  10. The results are undefined if you provide invalid data in the key-table. If you fail to specify any keys (by specifying a table whose size is zero), you receive a file error on merge-file. Under the default file status codes, this is file error 94 with a secondary status of 63.
  11. For nonnumeric keys, the COLLATING SEQUENCE phrase establishes the ordering. If this phrase is omitted, the NATIVE collating sequence is used. For numeric keys, the ordering is specified by the algebraic value of the key.
  12. When the contents of all key fields in one input record equal the contents of the key fields in another, the order of return:
    1. follows the order of the associated in-files in the MERGE statement
    2. causes all records with equal key values from one input file to be returned before any are returned from another
  13. The MERGE statement transfers all records from each in-file to merge-file. When the MERGE statement executes, in-file must not be open. The results of the MERGE statement are undefined if the in-file records are not ordered according to the KEY clause of the MERGE statement.
  14. For each in-file, the MERGE statement:
    1. opens the file as if it had been the object of an OPEN INPUT statement with no options. This occurs before any associated output procedure executes.
    2. retrieves the records of the file and releases them to the merge operation. The retrieval is performed as if the program had executed a READ statement with the NEXT and AT END phrases.
    3. closes the file as if it were the object of a CLOSE statement with no options. This occurs after any associated output procedure has finished execution.

      These actions cause any associated USE procedures to execute if an exception condition occurs.

  15. The OUTPUT PROCEDURE, if specified, is executed by the MERGE statement when the records are ready to be processed in merged order. The statements in the range of the output procedure must contain one or more RETURN statements to retrieve the merged records. Control is passed to the output procedure by the MERGE statement according to the rules of the PERFORM statement. When the last statement of the output procedure is executed, control returns to the MERGE statement. The MERGE statement then closes the in-files and terminates.
  16. If the MERGE statement is in a fixed segment, the range of the output procedure must be contained completely in the fixed segments and no more than one independent segment. If the MERGE statement is in an independent segment, the range must be completely contained in the fixed segments and the same independent segment.
  17. If the GIVING phrase is used, the MERGE statement writes all merged records to each out-file. Out-file must not be open when the MERGE statement executes.
  18. The MERGE statement writes records to out-file with the following steps:
    1. out-file is opened as if it were the object of an OPEN OUTPUT statement with no options.
    2. Each merged record is retrieved and written to out-file as if it were the object of a WRITE statement.
    3. out-file is closed as if it were the object of a CLOSE statement with no options.
  19. The implicit OPEN, WRITE, and CLOSE operations cause associated USE procedures to execute if an exception condition occurs. If the MERGE statement tries to write beyond the boundaries of out-file, the applicable USE procedure executes. If that procedure returns, or no USE procedure is specified, the processing of that out-file terminates with an implied CLOSE operation.
  20. If out-file is a relative file, the value of the RELATIVE KEY data item is updated to contain the record number of each record after it is written.
  21. The MERGE statement updates the value of the FILE STATUS data item associated with merge-file.
  22. If a MERGE statement is executed in a wrong context, the runtime displays the error Illegal MERGE. This error belongs to the class of intermediate runtime errors that, upon occurrence, call installed error procedures. See CBL_ERROR_PROC in Appendix I. Library Routines for details.

Code Example 1

*Merge sales prospects lists.
   MERGE NATIONAL-MERGE-FILE
      ON ASCENDING KEY PROSPECT-CLASS
                       SALES-REP-NUMBER
      USING  WESTERN-REGION-FILE,
             EASTERN-REGION-FILE,
             SOUTHERN-REGION-FILE
      GIVING NATIONAL-PROSPECT-FILE.

Code Example 2

*Merge sales prospects lists and use an
*OUTPUT PROCEDURE to do processing on the list
*before writing it to the output file.
   MERGE NATIONAL-MERGE-FILE
      ON ASCENDING KEY PROSPECT-CLASS
                       SALES-REP-NUMBER
      USING  WESTERN-REGION-FILE,
             EASTERN-REGION-FILE,
             SOUTHERN-REGION-FILE
      OUTPUT PROCEDURE IS PROCESS-PROSPECT-LIST.

(An extended code sample of this example may be found at the end of this page.)

Highlights for First-time Users

  1. MERGE can be thought of as a specialized version of SORT that has been optimized to give better processing performance than can be achieved using SORT. Bear in mind, however, that MERGE, like SORT, does all of its I/O on disk files and will, therefore, take a variable amount of time to complete, depending on the size of the input files, the number of records in the files and the speed of the disk subsystems.
  2. MERGE does not allow the use of an input procedure for manipulating records before they are merged.
  3. The files to be merged must have identical record formats and be identically ordered by the same key fields.
  4. The result of the merge may be written directly to an output file or made available to an output procedure.
  5. The output procedure may not reference any of the input files or their records. You can access the records contained in the input files, in merged order, by using RETURN to fetch records from the merge file.
  6. The KEY AREA phrase is a means for defining the merge keys at runtime. When you use KEY AREA, it is not required that the merge file record descriptor contain entries for potential sort keys. Definition of the sort key(s) in the merge file is handled internally by the MERGE routine, using the key table. See syntax rules 2 and 3 and general rules 6 through 10.
  7. Summary of the merge process:
    1. At the beginning of the MERGE process all input files (in-files) and the temporary merge file (merge-file) are opened and positioned at the head of the file. The input files cannot already be open when the MERGE statement begins.
    2. The records of each input file are sequentially READ and released to the merge operation.
    3. When all of the records in all of the input files have been read, the input files are closed and MERGE completes its merging process.
    4. Following merge processing, if OUTPUT PROCEDURE is specified, control is passed to the output procedure. In the output procedure, each record in the merge file is fetched, in sort order, by the RETURN verb for processing. When the last statement of the output procedure is executed, control returns to the MERGE statement.
    5. If the GIVING phrase is used, the merged records are written to the specified output file(s).

Extended code example 2:

IDENTIFICATION DIVISION.
PROGRAM-ID.  SAMPLE-FILE-MERGE.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
   SELECT WESTERN-REGION-FILE
      ASSIGN TO ....
   SELECT EASTERN-REGION-FILE
      ASSIGN TO ....
   SELECT SOUTHERN-REGION-FILE
      ASSIGN TO ....
   SELECT NATIONAL-PROSPECT-FILE
      ASSIGN TO ....
   SELECT NATIONAL-MERGE-FILE
      ASSIGN TO ....
DATA DIVISION.
FILE SECTION.
FD  WESTERN-REGION-FILE.
01  W-REGION-RECORD        PIC X(30).
FD  EASTERN-REGION-FILE.
01  E-REGION-RECORD        PIC X(30).

FD  SOUTHERN-REGION-FILE.

01  S-REGION-RECORD        PIC X(30).

SD  NATIONAL-MERGE-FILE.

01  SORT-DATA.
    05  PROSPECT-NUMBER    PIC X(5).
    05  PROSPECT-NAME      PIC X(7).
    05  PROSPECT-CLASS     PIC X.
    05  ESTIMATED-VALUE    PIC 9999V9.
    05  SALES-REP-NUMBER   PIC X(3).
    05  SALES-REP-NAME     PIC X(7).
    05  FILLER             PIC XX.
FD  NATIONAL-PROSPECT-FILE.
01  NATIONAL-RECORD        PIC X(30).
WORKING-STORAGE SECTION.
01  FLAGS.
    05   MERGE-LIST-EMPTY   PIC X VALUE "N".
         88 NO-MORE-RECORDS       VALUE "Y".
...
PROCEDURE DIVISION.
PROSPECT-LIST-MERGE-PROCEDURE.
    MERGE NATIONAL-MERGE-FILE
       ON ASCENDING KEY PROSPECT-CLASS
                        SALES-REP-NUMBER
       USING  WESTERN-REGION-FILE,
              EASTERN-REGION-FILE,
              SOUTHERN-REGION-FILE
       OUTPUT PROCEDURE IS PROCESS-PROSPECT-LIST.

PROCESS-PROSPECT-LIST SECTION.
CREATE-NATIONAL-PROSPECT-FILE.
   OPEN OUTPUT NATIONAL-PROSPECT-FILE.
   RETURN NATIONAL-MERGE-FILE
      AT END MOVE "Y" TO MERGE-LIST-EMPTY.
   PERFORM UPDATE-PROSPECT-DATA
      UNTIL NO-MORE-RECORDS.
   CLOSE NATIONAL-PROSPECT-FILE.
   GO TO EXIT-MERGE-OUTPUT-PROCESSING.

UPDATE-PROSPECT-DATA.
*do not write records tagged "TestRep"
   IF SALES-REP-NAME NOT = "TestRep"
*write the record to the output file
      WRITE NATIONAL-RECORD FROM SORT-DATA.
   END-IF.
*fetch the next record
   RETURN NATIONAL-MERGE-FILE
      AT END MOVE "Y" TO MERGE-LIST-EMPTY.

EXIT-MERGE-OUTPUT-PROCESSING.
   EXIT.
Parent topic: Procedure Division Statements


MODIFY Statement

The MODIFY verb is used to change the characteristics of an existing screen control item or window. It acts on control handles, elementary Screen Section control items, and window handles.

Format 1

MODIFY {control-item} [ ( {index-1} ... ) ]
       {CONTROL     }

Remaining phrases are optional, can appear in any order.

AT screen-loc   [CELL  ]
                [CELLS ]
                [PIXEL ]
                [PIXELS]

AT LINE NUMBER line-num   [CELL  ]
                          [CELLS ]
                          [PIXEL ]
                          [PIXELS]

AT {COLUMN  } NUMBER col-num   [CELL  ]
   {COL     }                  [CELLS ]
   {POSITION}                  [PIXEL ]
   {POS     }                  [PIXELS]

AT CLINE NUMBER cline-num [CELL ]
                          [CELLS]

AT CCOL NUMBER ccol-num [CELL ]
                        [CELLS]

SIZE    {IS} length  [CELL  ]
        {= }         [CELLS ]
                     [PIXEL ]
                     [PIXELS]

LINES   {IS} height  [CELL  ]
        {= }         [CELLS ]
                     [PIXEL ]
                     [PIXELS]

CSIZE   {IS} clength  [CELL ]
        {= }          [CELLS]

CLINES  {IS} cheight  [CELL ]
        {= }          [CELLS]

MAX-HEIGHT {IS} max-height
           {= }

MAX-WIDTH  {IS} max-width
           {= }

MIN-HEIGHT {IS} min-height
           {= }

MIN-WIDTH  {IS} min-width
           {= }
TITLE {IS} title
      {= }

{COLOR } IS color-val
{COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{BACKGROUND-HIGH}
{BACKGROUND-LOW}
{BACKGROUND-STANDARD}

STYLE {IS} style-flags
      {= }

{ [NOT] style-name } ...

VALUE {IS} [ MULTIPLE ] value [ LENGTH {IS} length-1 ]
      {= } [ TABLE    ]                {= }

LAYOUT-DATA {IS} layout-data
            {= }
FONT  {IS} font-handle
      {= }

ENABLED  {IS} {TRUE         }
         {= } {FALSE        }
              {enabled-state}

VISIBLE  {IS} {TRUE         }
         {= } {FALSE        }
              {visible-state}

POP-UP MENU {IS} {menu-1}
            {= } {NULL  }

EVENT-LIST    {IS} ( event-value { event-value ... } )
              {= }

AX-EVENT-LIST {IS} ( ax-event-value { ax-event-value ... } )
              {= }

EXCLUDE-EVENT-LIST {IS} list-state
                   {= }

EVENT PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
                              {THRU   }
                   { NULL                        }

{ property-name          } {IS } { prop-option
                                     [GIVING result-1] }...
{ PROPERTY property-type } {ARE}
{ method-name            } {=  }
{ object-expression      }

prop-option is one of the following:

{ property-value [ LENGTH {IS} length-1 ] }
{                         {= }            }
{                                         )
{ ( {property-value} ... )                }
{                                         }
{ { MULTIPLE } property-table             }
{ { TABLE    }                            }
{                                         }
{ parameter-expression                  }
{                                         }
{ ( { parameter-expression } ... )      }

parameter-expression is one of the following:

{ parameter                               } [ AS type-num ]
{                                         }
{ {BY} NAME parameter-name {IS} parameter }
{                          {= }           }
{ parameter-name {IS} parameter           }
{                {= }                     }

object-expression has the following format:

{ {^} property-1 [ (param-expr ... ) ]
  [ :: property-2 [ ( param-expr ... ) ] ... }

Format 2

MODIFY {window-handle           }
       {WINDOW [generic-handle] }

Remaining phrases are optional, can appear in any order.

AT screen-loc

LINE NUMBER line-num

{COLUMN  } NUMBER col-num
{COL     }
{POSITION}
{POS     }

SCREEN LINE NUMBER screen-line

SCREEN {COLUMN  } NUMBER screen-col
       {COL     }
       {POSITION}
       {POS     }

SIZE width

LINES height

TITLE title

ON EXCEPTION statement-1

NOT ON EXCEPTION statement-2

VISIBLE  {IS} {TRUE         }
         {= } {FALSE        }
              {visible-state}

POP-UP MENU {IS} {menu-1}
            {= } {NULL  }

ENABLED  {IS} {TRUE         }
         {= } {FALSE        }
              {enabled-state}

EVENT PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
                              {THRU   }
                   { NULL                        }

ACTION  {IS} action
        {= }

END-MODIFY

Syntax Rules

  1. control-item is a USAGE HANDLE data item or elementary Screen Section item that describes a control.
  2. index-1 is a numeric expression. The parentheses surrounding index-1 are required.
  3. window-handle is a USAGE HANDLE OF WINDOW or PIC X(10) data item.
  4. generic-handle is a USAGE HANDLE, HANDLE OF WINDOW or PIC X(10) data item.
  5. screen-loc is an integer data item or literal that contains exactly 4, 6, or 8 digits, or a group item of 4, 6, or 8 characters.
  6. line-num, col-num, cline-num, ccol-num, length, height, width, clength, and cheight are numeric data items or literals. They can be non-integer values, except when pixels are specified.
  7. screen-line and screen-col are numeric expressions. They should be integer values.
  8. If the CELLS option is used with either the SIZE or CSIZE phrase, then it must be present in both phrases if both are specified. The same is true for use of the CELLS option in the LINES and CLINES phrases.
  9. max-height, max-width, min-height, and min-width are numeric data items, literals, or expressions.
  10. color-val is an integer data item or literal.
  11. fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. See FOREGROUND-COLOR and BACKGROUND-COLOR Phrases for a more detailed discussion of color settings and values.
  12. If you use the AT phrase, you may not use the LINE, COLUMN, SCREEN LINE, or SCREEN COLUMN phrases.
  13. The SCREEN LINE and SCREEN COLUMN phrases must be used together. If used, the AT, LINE, and COLUMN phrases may not be used.
  14. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  15. style-flags is a numeric expression.
  16. style-name is the name of a style associated with the class of control being described. The style-name phrase adds the named style to the control. If control-handle refers to a generic handle, or if the CONTROL phrase is used, you may not use the style-name phrase. Use the STYLE phrase instead. If the NOT option is used with the style-name phrase, the named style is removed from the control instead. When a style is added, any conflicting styles are removed first. For example, if you add the FRAMED style to a button, then the UNFRAMED style is removed first.
  17. value is a literal or data item. If the MULTIPLE option is specified, then value must be a one-dimensional table. In this case, value is not subscripted.
  18. length-1 is a numeric literal or data item. The LENGTH phrase may be specified only if the value or property-value immediately preceding it is an alphanumeric literal or data item, and not a figurative constant. In addition, the MULTIPLE option may not be specified along with the LENGTH phrase.
  19. title is an alphanumeric literal or data item.
  20. layout-data is an integer literal, data item, or expression.
  21. font-handle is a USAGE HANDLE data item that identifies a font.
  22. enabled-state and visible-state are integer numeric literals or data items.
  23. menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
  24. event-value and ax-event-value are numeric literals or data items that identify an event type. List elements must be enclosed by parentheses. Elements must be separated by a space. If the list contains a single element, the parentheses can be omitted.
  25. list-state is an integer literal or numeric data item. Valid values are 0 and 1.
  26. proc-1 and proc-2 are procedure names.
  27. You must allow recursive paragraphs in order to specify the EVENT PROCEDURE phrase. Compiling for recursive paragraphs is allowed by default, but you can turn it off if you use the -Zr0 option.
  28. property-name is the name of a property specific to the type of control being referenced. If the type of control is unknown to the compiler (as in a DISPLAY OBJECT object-1 statement), then property-name may not be used. You must use the PROPERTY property-type option instead.
  29. property-type is a numeric literal or data item. It identifies the property to modify. The numeric values that identify the various control properties can be found in the COPY library controls.def.
  30. method-name is the name of method specific to the type of ActiveX control or COM object being referenced. If the type of the control or object is unknown to the compiler, then method-name cannot be used. You must use the PROPERTY property-type option instead.
  31. property-value is a literal or data item. In the Procedure Division, property-value may also be a numeric expression (however, only the first property-value in a phrase may be an expression, subsequent values must be literals or data items). Note that the parentheses are required.
  32. property-table is a data item that appears in a one-dimensional table. No index should be specified.
  33. result-1 is a numeric data item.
  34. In parameter-expression:
    1. parameter is a literal, data-item, or numeric expression used when invoking methods or setting properties of an ActiveX control or COM object.
    2. type-num is a numeric data item or numeric literal.
  35. In object-expression:
    1. ^ can only be used in conjunction with a Format 5 USE verb for an ActiveX control or COM object.
    2. property-1 is the name of a property of the ActiveX control or COM object. property-1 cannot be a write-only property.
    3. property-2 is the name of a property of the ActiveX control or COM object that is the value of property-1. property-2 cannot be a write-only property.
  36. statement-1 and statement-2 are imperative statements.
  37. action is a numeric literal or a data item.

Format 1 General Rules

  1. A Format 1 MODIFY statement updates an existing control or invokes a method on an ActiveX control, COM object, or .NET control (also known as an assembly). control-item should contain a handle returned by a DISPLAY control-Type statement, or the name of an elementary Screen Section control item. If control-item does not refer to a valid control, the MODIFY statement has no effect. Note that controls referenced in the Screen Section are not valid until they have been created via a DISPLAY statement. If control-item refers to a valid control, the effect of the statement is to update the specified properties of the control and to redisplay it.
  2. If index-1 is specified, then certain properties in the control being modified are changed to match the value of index-1. This occurs before any modification occurs. The exact set of properties changed by the index-1 depends on the control's type. Currently, two controls have properties that are changed in this way:
    Control Type | Properties Affected
    List Box | QUERY-INDEX
    Grid | Y, X

    Each occurrence of index-1 changes one property. The first occurrence changes the first property in the list presented in the preceding table. The second occurrence changes the second property. For example, the statement fragment

    MODIFY grid-1(2, 3), color is red

    would have the effect of setting the grid property Y to 2 and X to 3 before changing the cell color to red. Supplying more index values than the control supports has no additional effect. You may omit trailing indexes; this leaves the corresponding properties unchanged. This feature can be used to simplify modification of specific elements of controls that hold multiple values. For example, you can modify the contents of row 2, column 3 in a grid with the statement:

    MODIFY grid-1(2, 3), CELL-DATA = data-1

    This is exactly equivalent to the more cumbersome:

    MODIFY grid-1, Y = 2, X = 3
MODIFY grid-1, CELL-DATA = data-1
  3. The meaning of each of the phrases is the same as for a Format 14 DISPLAY statement. Note that you can move a control by changing its row or column property.
  4. MODIFY simply locates the corresponding control and makes the specified modifications. This process does not examine any phrases specified in the Screen Section.

    This capability is particularly convenient when you want to make one or two changes to a Screen Section control. For example, if you want to add an item to a list box, you can simply modify the list box specifying the item-to-add property. For example:

    * Screen Section
01  list-box-1, list-box, value list-item, line 5,
       column 15, size 20, lines 6.

* Procedure Division
modify list-box-1, item-to-add = new-list-item.

    By using the MODIFY verb, you do not need to specify an item-to-add property in the Screen Section, and thus you do not need to closely manage the item-to-add variable.

  5. If the CONTROL phrase is used, the runtime modifies the control located at the screen position specified by the AT, LINE, and COLUMN phrases in the current window (on non-graphical systems, the CLINE and CCOL phrases also apply). The runtime maintains a list of controls in each window. When attempting to modify a control at a specific location, the runtime searches this list, using the first control it finds that exactly matches the location. The list is maintained in the order in which the controls are created. If the runtime does not find a control at the specified location, then the statement has no effect.
  6. Note that you cannot move a control with a MODIFY statement if it includes the CONTROL phrase. This is due to the fact that the AT, LINE, and COLUMN phrases are used to find the control instead of specifying its new position. To move a control, you must use the control-handle phrase instead. Also note that when you use the CONTROL phrase, the compiler does not know the type of control being modified. This means that the compiler will not recognize any control-type specific style and property names. If you need to specify these, you will need to use their numeric equivalents found in the controls.def COPY library.

    The following example creates an anonymous list box and adds two items to it. Note the use of the PROPERTY phrase in the MODIFY statement: the compiler does not know that the control is a list box so it does not recognize the list-box specific property names. As a result, the generic PROPERTY phrase is used in the example, specifying the level 78 data name that corresponds to the ITEM-TO-ADD property (found in controls.def).

    COPY "controls.def".

DISPLAY LIST-BOX, LINE 5, COL 30, LINES 5.
MODIFY CONTROL, LINE 5, COL 30,
   PROPERTY LBP-ITEM-TO-ADD =
            ( "Item 1", "Item 2" ).
  7. The style-name phrase adds the named style to the control. If the NOT option is used with the style-name phrase, the named style is removed from the control instead. When a style is added, any conflicting styles are removed first. For example, if you add the FRAMED style to a button, then the UNFRAMED style is removed first.
  8. When the LENGTH option is specified, length-1 establishes the exact size of the value or property-value. The text value presented to the control may have no trailing spaces or may have trailing spaces added. When you specify the LENGTH option, the control uses exactly length-1 characters of data with or without trailing spaces. However, when length-1 is a value larger than the size of the data item it is modifying, then the size of the data item is used instead. If length-1 is negative, it is ignored and the default handling occurs.
  9. The POP-UP MENU option changes the pop-up menu for the control. If menu-1 is specified, then the corresponding menu becomes the new pop-up menu. If NULL is specified, any existing pop-up menu is removed (but not destroyed).
  10. The EVENT PROCEDURE phrase adds, changes, or removes a control's event procedure. Specifying NULL removes any event procedure. Otherwise, proc-1 (through proc-2, if specified) becomes the control's new event procedure.
  11. When properties return specific values, these values are placed in result-1 of the GIVING phrase. If the property does not have a pre-defined return value, result-1 is set to 1 if the property is set successfully, otherwise, result-1 is set to 0. When a property is being given multiple values in a single assignment, as shown here,
    DISPLAY COLUMNS = ( 1, 10, 30 )

    then result-1 is set in response to the last value assigned. In the example above, result-1 is set to 30. Because the meaning of each value depends on the property being set, you should consult the documentation on the specific property for the exact meaning.

  12. You can also change the properties of most controls described in the Screen Section with a Format 2 DISPLAY statement. You must use MODIFY to change special properties of an ActiveX or .NET control.
  13. To invoke (call) a method, you use the MODIFY verb in much the same way as you set a property or style. Note that unlike common properties and styles, you cannot use the DISPLAY statement to invoke an ActiveX method specified in the Screen Section. You must use the MODIFY verb. ActiveX methods can take any number of parameters or no parameters. They can also take optional parameters (i.e., parameters that can be omitted). You specify the parameters in COBOL by enclosing them in parentheses. The optional parameters are always last. To invoke a method with no parameters, use empty parentheses ().
  14. Each property or method name can be followed by '::' and then another property or method name to invoke methods in-line. MethodName1::MethodName2 means invoke the method "MethodName1" of the current object and set the current object to the return value. When a property or method name is followed by a token other than '::', then it means to actually invoke the method on the current object passing the specified arguments or set the property to the specified value and reset the current object to null.
  15. The MODIFY verb takes a control's home position (upper left corner), its handle, the name of an elementary Screen Section item, or '^', as its first parameter. Only the properties of the control that are specified in the MODIFY statement are updated.
  16. The runtime automatically converts parameters to the appropriate types.
  17. If a method has a return value, the runtime converts and moves it to the item specified in the GIVING clause.
  18. You cannot use named parameters to avoid entering required parameters. You can omit optional parameters only.
  19. You must specify only unnamed parameters before the BY NAME clause, and only named parameters after the BY NAME clause.
  20. You can use one- and two-dimensional COBOL tables as property and method parameters for use in COM SAFEARRAYs. The runtime automatically converts the table to an COM SAFEARRAY, as long as it contains only one elementary item that is USAGE HANDLE or USAGE HANDLE OF VARIANT.
  21. Use the AS type-num phrase in the parameter expression if you want to force the parameter to be converted to a particular VARIANT type before it is passed to a property or method of an ActiveX control or COM object. You can tell from the object's documentation and the name of the parameter whether the object expects a particular VARIANT type, such as boolean.

    Use the AS phrase if the ActiveX or COM object requires a method or property parameter to be something different from the default VARIANT type chosen by the runtime for the particular COBOL data item or literal. Specify the word AS followed by a numeric literal or level 78 numeric constant that indicates the variant type to which you want the parameter converted. The activex.def COPY file in the ACUCOBOL-GT sample/def directory contains predefined level 78 constants for each of the VARIANT types.

Format 2 (MODIFY WINDOW)

  1. A Format 2 MODIFY statement changes one or more attributes of an existing FLOATING or INITIAL WINDOW (not a subwindow). Attributes that are not specifically changed remain unchanged, except when a window is made larger, in which case it may also be repositioned in order to keep it on the screen. window-handle or generic-handle identify the window to modify. If the WINDOW phrase is used and generic-handle is omitted, the current window is modified.
  2. The LINE and COLUMN phrases specify the location of the window on the screen. The coordinates are relative to the interior space of the parent window. If the window being modified is the initial window, the coordinates are relative to its own interior. If either phrase is omitted, the corresponding row or column position is unchanged.
  3. The AT phrase specifies both the row and column position. The first two or three digits of screen-loc, depending on the size of screen-loc, specify the row position. The remaining digits specify the column position. The values are treated in the same manner as in the LINE and COLUMN phrases. If either half of screen-loc is zero, the corresponding coordinate remains unchanged.
  4. The SCREEN LINE and SCREEN COLUMN phrases set the location of the window. The coordinates indicate the absolute position desired on the screen. screen-line and screen-col are given in the screen's base units. Base units are machine dependent. For character systems, the base unit is a character cell. For graphical systems, the base unit is a pixel. The upper left corner of the screen is position 1,1. The SCREEN LINE and SCREEN COLUMN phrases cannot be used if the LINE, COLUMN, or AT phrases are used.
  5. The SIZE and LINES phrases change the size of the window. The dimensions indicate the interior of the window. The requested size must fit on the screen. If it does not, the size is not changed. After resizing the window, the runtime ensures that the window is fully visible on the screen. Resizing a window that has the RESIZABLE property will not change the window's physical dimensions if that window is not maximized. Note that only the window's logical dimensions are changed (thus increasing the scrolling region). The user will see the new size only if he or she later maximizes the window.
  6. The TITLE phrase specifies a new title for the window. For this phrase to have an effect, the window must have a title area.
  7. statement-1 executes if any part of the operation fails. An exception may be caused by one of the following situations:
    • The specified window size does not fit the screen. Note that this error occurs only on a non-Windows host. Because Windows allows you to have a desktop that is larger than the physical screen, you do not get an exception in this instance on Windows. You should use ACCEPT FROM TERMINAL-INFO to determine the maximum physical window size on a Windows host.
    • The window cannot be created, either because of an out-of-memory situation or the operating system fails to create it.
    • A window that has no input is activated.
    • An external window error occurs. For example, the window does not exist or cannot be created for some reason.
    • An illegal instruction is used.
  8. statement-2 executes if the MODIFY statement succeeds.
  9. The VISIBLE option makes a window visible or invisible. If the TRUE phrase is used, or visible-state is non-zero, then the window is made visible. Otherwise, it is made invisible.
  10. The POP-UP MENU option changes the pop-up menu for the window. If menu-1 is specified, then the corresponding menu becomes the new pop-up menu. If NULL is specified, any existing pop-up menu is removed (but not destroyed).
  11. The Format 2 ENABLED phrase can be used to disable or enable a window. A user cannot interact with a disabled window.
  12. The Format 2 EVENT PROCEDURE phrase changes the window's event procedure to proc-1 (through proc-2, if specified). If the NULL option is used, then the window's event procedure, if any, is removed from the window. Additional information can be found in the DISPLAY Statement above and in PROCEDURE Clause.
  13. The ACTION phrase allows you to programmatically maximize, minimize, or restore a window. To use ACTION, assign it one of the following values (these names are found in acugui.def):
    ACTION-MAXIMIZE | maximizes the window. It has the same effect as if the user clicked the maximize button. Allowed only for windows that have RESIZABLE or AUTO-RESIZE specified or implied for them.
    ACTION-MINIMIZE minimizes the window. Allowed only with INDEPENDENT windows that have the AUTO-MINIMIZE property set to true. It is not supported with other types of floating windows; if set, it is ignored by the runtime.

    ACTION-MINIMIZE has the same effect as if the user clicked the minimize button.

    ACTION-RESTORE | If the window is currently maximized or minimized, restores the window to its previous size and position; otherwise, it has no effect. Allowed only for windows that can be maximized or minimized.

    If you assign an ACTION value that is not allowed, then there is no effect other than to trigger the ON EXCEPTION phrase of the MODIFY statement (if present). Note that you can use the ACTION phrase to create a window that is initially maximized or minimized.

Parent topic: Procedure Division Statements


MOVE Statement

The MOVE statement transfers data to data items.

Format 1

MOVE source-item TO {dest-item} ...

Format 2

MOVE {CORRESPONDING} source-group TO dest-group
     {CORR         }

Format 3

MOVE alpha-item TO dest-item WITH {CONVERSION}
                                  {CONVERT   }

    [ ON EXCEPTION statement-1 ]

    [ NOT ON EXCEPTION statement-2 ]

    [ END-MOVE ]

Syntax Rules

  1. source-item is a literal or data item that represents the sending area.
  2. dest-item is a data item that receives the data.
  3. source-group and dest-group must be group items.
  4. alpha-item is a literal or data item of class alphanumeric.
  5. CORR is an abbreviation for CORRESPONDING.
  6. If dest-item is numeric or numeric edited, source-item may not be HIGH-VALUES, LOW-VALUES, SPACES, or QUOTES.
  7. source-item and dest-item must be of a compatible category. See General Rule 9 below.
  8. statement-1 and statement-2 are imperative statements.

General Rules

  1. A Format 1 MOVE statement moves source-item to each dest-item in the same order in which they appear in the statement.
  2. Subscript evaluation for source-item occurs once before the move to the first dest-item.
  3. Subscript evaluation for dest-item occurs immediately before the move to that item.
  4. The length of source-item is computed once immediately before the move to the first dest-item. The compiler option -Dz modifies size checking rules for numeric moves.
  5. The length of dest-item is computed immediately before the MOVE to that item.
  6. Reference modification is allowed on source-item and dest-item.
  7. source-item and dest-item should not overlap (reference the same location in memory). The compiler does not detect this condition. The results of such a move are undefined. One possible outcome is a memory access violation. For example:
    MOVE myStr(2:myLen - 1) to myStr(1:myLen)

    attempts to move part of myStr to myStr, which gives undefined results. Another mistake is to create an overlap by moving the value of an item to a REDEFINES of the same item.

  8. When the CORRESPONDING phrase is used, selected elementary items in source-group are moved to corresponding items in dest-group. This is treated as a series of Format 1 MOVE statements, one for each corresponding pair of data items.
  9. The effects and legality of a MOVE statement depend on the category of the source-item and dest-item. Data items are assigned a category according to their PICTURE clause. Literals are assigned a category based on the following rules:
    1. Numeric literals are numeric. Nonnumeric literals are alphanumeric.
    2. The figurative constant ZERO is numeric when dest-item is numeric or numeric edited, otherwise it is alphanumeric.
    3. The figurative constant SPACE is alphabetic.
    4. All other figurative constants are alphanumeric.
  10. Any Format 1 MOVE statement that has a group item as either a source or destination item is treated as a simple alphanumeric to alphanumeric move. (No implied conversion is implied.) Any category of data may be the source or destination of a group item MOVE.
  11. The following table outlines the combinations of source-item and dest-item that are allowed by the MOVE statement. The numbers in the table are the General Rules numbers in this section where each combination is described:
    Sending Category: Receiving Item Category:
    Alphabetic | Alphanumeric/Alphanumeric Edited | Numeric /Numeric Edited
    Alphabetic | Yes (12) | Yes (13) | No (15)
    Alphanumeric | Yes (12) | Yes (13) | Yes (14)
    Alphanumeric Edited | Yes (12) | Yes (13) | No (15)
    Numeric Integer | No (15) | Yes (13) | Yes (14)
    Numeric

    Non-integer

            No (15) No (15) Yes (14)
    Numeric Edited | No (15) | Yes (13) | Yes (14)
  12. When dest-item is alphabetic, justification and space filling occur according to the standard alignment rules.
  13. When dest-item is alphanumeric or alphanumeric edited, justification and space filling occur according to the standard alignment rules. If source-item is signed numeric, the operational sign is not moved. If the sign occupies a separate character position, that sign character is not moved, and the size of source-item is treated as being one less.
  14. When dest-item is numeric or numeric edited, decimal point alignment and zero filling occur according to the standard alignment rules. If source-item is unsigned, it is treated as being positive. If dest-item is unsigned, the absolute value of source-item is moved. If dest-item is signed, its sign is set to the sign of source-item. If source-item is numeric edited, it is de-edited first such that dest-item receives the same numeric value.
  15. The following moves are illegal:
    1. An alphabetic or alphanumeric edited data item may not be moved to a numeric or numeric edited data item.
    2. A numeric or numeric edited data item may not be moved to an alphabetic item.
    3. A non-integer numeric data item cannot be moved to an alphanumeric or alphanumeric edited data item.
  16. A Format 3 MOVE statement performs a logical conversion of alpha-item into the format of dest-item. dest-item may be any type of data item. This is normally done to convert a character representation of a number into the corresponding numeric value. The rules of conversion are the same as the rules used by the CONVERT option of the ACCEPT statement. For a detailed description of these rules, see section Common Screen Options, under the subheading CONVERT phrase.
  17. If the ON EXCEPTION phrase is specified, then statement-1 executes when a conversion error occurs. If a conversion error occurs, then the value assigned to dest-item is the value determined by ignoring the illegal characters in alpha-item. If the NOT ON EXCEPTION phrase is specified, then statement-2 executes when no conversion error occurs.
Parent topic: Procedure Division Statements


MULTIPLY Statement

The MULTIPLY statement performs arithmetic multiplication.

Format 1

MULTIPLY source BY { result [ROUNDED] } ...

    [ ON SIZE ERROR statement ]

    [ NOT ON SIZE ERROR statement ]

    [ END-MULTIPLY ]

Format 2

MULTIPLY source BY source

      GIVING { result [ROUNDED] } ...

    [ ON SIZE ERROR statement ]

    [ NOT ON SIZE ERROR statement ]

    [ END-MULTIPLY ]

Syntax Rules

  1. source is a numeric literal or numeric data item.
  2. result is a numeric or numeric edited data item. In Format 1, result may not be numeric edited.
  3. statement is an imperative statement.

General Rules

  1. In Format 1, each result is multiplied by source. The product is stored back in result.
  2. In Format 2, the two source operands are multiplied together. The product is stored in each result variable.
  3. Additional information can be found in Arithmetic Operations, Multiple Receiving Fields, ROUNDED Option, and SIZE ERROR Option.
Parent topic: Procedure Division Statements


NEXT SENTENCE Statement

The NEXT SENTENCE statement causes control to be transferred to the next COBOL sentence (following the next period). This is distinct from the logically next COBOL verb, which is the result of a CONTINUE statement. Note that the ANSI standard states that NEXT SENTENCE is an archaic feature and its use should be avoided.

General Format

NEXT SENTENCE

Syntax Rules

A NEXT SENTENCE statement is allowed anywhere a conditional statement or imperative-statement is allowed.

General Rules

A NEXT SENTENCE statement transfers the flow of execution to the logically next COBOL verb following the next period.

Parent topic: Procedure Division Statements


OPEN Statement

The OPEN statement initiates processing of a file.

General Format

OPEN [EXCLUSIVE]

    { {INPUT } { file [WITH NO REWIND] } ... } ...
      {OUTPUT}        [lock-option   ]
      {I-O   }
      {EXTEND}

lock-option may be either of these formats:

    { ALLOWING {NO OTHERS} }
               {READERS  }
               {WRITERS  }
               {UPDATERS }
               {ALL      }

    { {WITH}   {LOCK         }   }
      {FOR }   {MASS-UPDATE  }
               {BULK-ADDITION}

Syntax Rules

  1. File is the name of a file described in the Data Division. It may not be a sort file.
  2. The I-O phrase can be specified only for files that reside on disk.
  3. The MASS-UPDATE and BULK-ADDITION phrases may be specified only for indexed files and may not be specified along with the INPUT phrase.
  4. The WITH NO REWIND phrase may be specified only for sequential files opened with the INPUT or OUTPUT phrase.
  5. If EXCLUSIVE is specified, then lock-option may not be specified.

General Rules

  1. A successful OPEN statement prepares the file for further processing by other I/O statements and puts the file in its open mode.
  2. An OPEN may not be performed on a file that is already open. A file is not open when the program is in its initial state or when the last I/O statement on the file was a successful CLOSE statement.
  3. Except for the OUTPUT option, and as noted in rule 19 below, a file's organization and data description must match those used when the file was created.
  4. The following table indicates the effects of the various OPEN types on files that are and are not available. A file is not available if it does not exist on the host computer. Note that different results occur for missing files if the file's SELECT contains the OPTIONAL phrase.
    Mode | Available | Unavailable
    INPUT | Open succeeds | Open fails
    - Optional | Open succeeds | Open succeeds
    I-O | Open succeeds | Open fails
    - Optional | Open succeeds | Open creates file
    OUTPUT | Open recreates file | Open creates file
    EXTEND | Open succeeds | Open fails
    - Optional | Open succeeds | Open creates file
  5. The different OPEN types allow for different I/O statements to be used. This is summarized in the following chart.
    Statement | Input | Output | I-O | Extend
    READ | X | X
    WRITE | X | X | X
    REWRITE | X
    START | X | X
    DELETE | X
    UNLOCK | X | X
  6. After a successful OPEN statement, the file is positioned at its first logical record. (The only exception to this rule is that a sequential access file opened with the EXTEND phrase is positioned after its last record. Records written to such a file are appended to the file.)
  7. A file opened with the OUTPUT phrase is logically recreated. This is equivalent to physically removing the file (if it exists) and creating it anew.
  8. If a file is not available, the OPTIONAL phrase is specified in the file's SELECT and the file is opened with the INPUT phrase, then the first READ on the file will return an end-of-file status condition.
  9. The execution of the OPEN statement causes the I-O status associated with file to be updated. Note that opening an OPTIONAL file when that file does not exist will return a different status code than opening it if it does exist.
  10. An OPEN statement with multiple files is equivalent to a series of OPEN statements referencing the files in the order named.
  11. The open state of a file is not affected by other instances of the same file in other run units or other programs of the same run unit. These other files may be opened or closed without affecting the ability of the current program to open the same file, except as modified by the file locking rules below.
  12. The EXCLUSIVE, WITH, and ALLOWING phrases allow for various forms of file locking. There are three forms of file locking: ALLOWING ALL, ALLOWING READERS, and ALLOWING NO OTHERS. File locking is enforced for all file types residing on disk but may not be enforced for non-disk files for some operating systems.
    Note: The -Fn compiler option specifies file locking as the default behavior for files that do not have locking or sharing already specified or implied from within the program. See File Options for details on this and other options related to file locking.
  13. The following phrases imply the ALLOWING ALL form of file locking:
    1. No lock-option specified
    2. ALLOWING ALL
    3. ALLOWING WRITERS
    4. ALLOWING UPDATERS

    This file locking mode indicates that other programs can access the file without restriction except that another program may not execute an OPEN OUTPUT while this program keeps the file open.

  14. The following phrases imply the ALLOWING READERS form of file locking:
    1. ALLOWING READERS
    2. EXCLUSIVE or WITH LOCK specified with the INPUT phrase

    A file open in this mode does not allow any other program to open this file other than with the INPUT phrase. Furthermore, this OPEN will fail if any other programs currently have the file open unless the INPUT phrase was used by all of these other programs.

  15. These phrases imply the ALLOWING NO OTHERS form of file locking:
    1. ALLOWING NO OTHERS
    2. EXCLUSIVE or WITH LOCK specified with the OUTPUT, I-O, or EXTEND phrases
    3. WITH MASS-UPDATE
    4. BULK-ADDITION

    This form of file locking does not allow any other programs to open the file, and this OPEN will fail if any other programs currently have the file open.

  16. The WITH MASS-UPDATE phrase is equivalent to the WITH LOCK phrase with some additional effects. It may be specified only for indexed files. This phrase indicates to the runtime system that the file in question will be heavily updated by this program. The runtime system may be able to use this information to access the file more efficiently. See Indexed File Considerations for more information about the effects of this phrase and advice on when it should be specified.
  17. The BULK-ADDITION phrase is equivalent to the MASS-UPDATE phrase with some additional effects. For Vision files, the BULK-ADDITION phrase opens the file in bulk addition mode, which substantially increases efficiency when you are writing a large number of new records to the file. BULK-ADDITION has several significant effects, including some changes to standard COBOL file handling rules. For host file systems other than Vision, specifying BULK-ADDITION has the same effect as specifying MASS-UPDATE. In this case, none of the special handling dictated by BULK-ADDITION applies. See Bulk Addition Mode for Vision for more information.
  18. A file with a LOCK MODE IS EXCLUSIVE phrase in its SELECT treats all OPEN statements as if they were written with the EXCLUSIVE option.
  19. The configuration variable EXTRA_KEYS_OK allows you to open an indexed file without specifying all of that file's alternate keys. For more information, see the listing for EXTRA_KEYS_OK.
  20. Note that the IBM DOS/VS COBOL -Cv compatibility mode supports Reversed File Reads.
Parent topic: Procedure Division Statements


PERFORM Statement

The PERFORM statement executes a procedure with optional loop control.

Format 1

PERFORM [ IN THREAD ]

      [ procedure-1 [ {THROUGH} procedure-2 ] ]
                      {THRU   }

      [ HANDLE IN handle-1 ]

      [ statement END-PERFORM ]

Format 2

PERFORM [ IN THREAD ]

      [ procedure-1 [ {THROUGH} procedure-2 ] ]
                      {THRU   }

      [ HANDLE IN handle-1 ]

        number TIMES
      [ statement END-PERFORM ]

Format 3

PERFORM [ IN THREAD ]

      [ procedure-1 [ {THROUGH} procedure-2 ] ]
                      {THRU   }

      [ HANDLE IN handle-1 ]

      [ WITH TEST {BEFORE} ] UNTIL condition
                  {AFTER }

      [ statement END-PERFORM ]

Format 4

PERFORM [ IN THREAD ]

      [ procedure-1 [ {THROUGH} procedure-2 ] ]
                      {THRU   }

      [ HANDLE IN handle-1 ]

      [ WITH TEST {BEFORE} ]
                  {AFTER }

        VARYING counter FROM starting-val

            BY increment UNTIL condition

      [ AFTER counter FROM starting-val

            BY increment UNTIL condition ] ...

      [ statement END-PERFORM ]

Syntax Rules

  1. handle-1 is a HANDLE or HANDLE OF THREAD data item.
  2. procedure-1 and procedure-2 are paragraph or section names in the Procedure Division.
  3. statement is an imperative statement.
  4. number is an integer numeric literal or data item. The value of number cannot exceed 2,147,483,647.
  5. condition is a conditional expression.
  6. counter is a numeric data item.
  7. starting-val is a numeric literal or data item.
  8. increment is a non-zero numeric literal or data item.
  9. A PERFORM statement must have exactly one of the procedure-1 or the statement END-PERFORM phrases specified or a period (".") for an implied END-PERFORM.
  10. The words THRU and THROUGH are interchangeable.

General Rules

  1. A PERFORM statement that contains procedure-1 is an out-of-line PERFORM. When statement is used instead, then it is an in-line PERFORM.
  2. An in-line PERFORM statement functions according to the same rules for an otherwise identical out-of-line PERFORM except that statement is executed in place of the statements in the range of procedure-1 (through procedure-2 if specified).
  3. When the PERFORM executes, control transfers to the first statement of procedure-1. Control might not transfer, however, depending on the evaluation of condition (if specified). The PERFORM statement also establishes an implicit transfer of control to the end of the PERFORM statement according to the following rules:
    1. If procedure-1 is a paragraph name, and procedure-2 is not specified, the return is after the last statement of procedure-1
    2. If procedure-1 is a section name, and procedure-2 is not specified, the return is after the last statement of the last paragraph of procedure-1
    3. If procedure-2 is specified and is a paragraph name, the return is placed after the last statement of procedure-2.
    4. If procedure-2 is specified and is a section name, the return is placed after the last statement of the last paragraph of procedure-2.
    5. If an in-line PERFORM is specified, an execution of the PERFORM statement is completed after statement has executed.
  4. procedure-1 and procedure-2 are not necessarily related except that control starts at procedure-1 and returns when it reaches the end of procedure-2. In particular, GO TO and PERFORM statements may occur between procedure-1 and the end of procedure-2.
  5. Control can pass to statements that are inside the range of procedure-1 through procedure-2 by mechanisms other than PERFORM. In this case, the implicit return to the PERFORM referencing these statements is not made. An implicit return occurs only for an active PERFORM.
  6. The range of a PERFORM statement consists of those statements that are executed as a result of executing that PERFORM. This includes statements that are executed as the result of GO TO and PERFORM statements included in the range of the PERFORM statement.
  7. If that range of a PERFORM statement includes another PERFORM statement, the range of the included PERFORM must be either totally included in or totally excluded from the logical sequence of the first PERFORM statement. Thus an active PERFORM included in the range of another active PERFORM may not allow control to pass to the return point of the first PERFORM. Furthermore, two or more active PERFORM statements may not have a common return point.
  8. Within a thread, a paragraph under the control of a PERFORM statement may (directly or indirectly) PERFORM itself only if the compile-time option -Zr1 is specified (this option is specified by default).
  9. If the TEST phrase is not specified, TEST BEFORE is implied.
  10. When the THREAD option is used, a new thread is created by the PERFORM statement. Once control returns to the end of the PERFORM statement, the thread is terminated. Note that all of the statements contained in the scope of the PERFORM are executed in the new thread. This includes any loop control operations implied by the PERFORM. For example, the statement:
      PERFORM THREAD, PARA-1 5 TIMES

    creates a single thread the performs PARA-1 five times (as opposed to creating five separate threads, each of which executes PARA-1 once).

  11. If handle-1 is specified, the new thread's unique ID is stored in handle-1.

Format 1 General Rules

A Format 1 PERFORM statement executes its range exactly once.

Format 2 General Rules

A Format 2 PERFORM statement executes its range a fixed number of times. If number is zero or negative, control passes to the end of the PERFORM statement. Otherwise the range of the PERFORM statement executes number times. Changing the value of number during the execution of the PERFORM statement does not change the number of times that range is executed.

Format 3 General Rules

A Format 3 PERFORM statement executes its range until condition evaluates true. If TEST BEFORE is specified or implied, the evaluation of condition occurs prior to any executions of the PERFORM range. Thus if condition is true when the PERFORM starts, the range will not be executed. If TEST AFTER is specified, the evaluation of condition does not occur until after the first execution of the PERFORM range.

Format 4 General Rules

  1. A Format 4 PERFORM statement executes its range a variable number of times while systematically changing the value of one or more variables.
  2. If TEST BEFORE is specified or implied and only one counter is specified:
    1. counter is set to the value of starting-val when the PERFORM statement begins.
    2. If condition is false, the PERFORM range executes once. Then increment is added to counter and condition is evaluated again. This cycle repeats until condition is true.
    3. If condition is true when the PERFORM statement begins executing, control is passed to the end of the statement after counter is set to starting-val..
  3. If TEST BEFORE is specified or implied and two or more counters are used:
    1. Each counter is set to the value of the corresponding starting-val.
    2. If the first condition is true, control transfers to the end of the PERFORM statement.
    3. If the last condition is false, the range of the PERFORM executes once. The final counter is incremented by the corresponding increment and the last condition is evaluated again. This cycle continues until the last condition is true.
    4. When the last condition is true, the last counter is set again to the corresponding starting-val.. The preceding counter is then incremented by the corresponding increment and the preceding condition is evaluated. If the condition is false, step (c) is performed again.
    5. When the condition in step (d) is true, the cycle repeats for the next higher-level counter. These cycles continue repeating in this hierarchical manner until the topmost (VARYING) counter is cycled. For each level, all levels underneath it are reinitialized and run through a full cycle each time the corresponding counter is incremented.
    6. The PERFORM statement ends when the uppermost (the first) condition evaluates true.
  4. At the end of a PERFORM with the TEST BEFORE phrase, the value of the first counter exceeds the last-used value by one addition of increment. The values of all other counters are equal to their corresponding starting-val..
  5. If the TEST AFTER phrase is specified and only one counter is used:
    1. counter is set to the value of starting-val.
    2. The range executes once. Then condition is evaluated. If it is false, increment is added to counter and the range executes again. This cycle continues until condition is true.
  6. If the TEST AFTER phrase is specified and two or more counters are used:
    1. Each counter is set to its corresponding starting-val.
    2. The PERFORM range executes once. The last condition is then evaluated. If it is false, the last counter is incremented by its corresponding increment and the PERFORM range executes again. This continues until the last condition evaluates true.
    3. When the last condition is true, the preceding condition is evaluated. If it is false, the value of the corresponding counter is incremented by its increment, the last counter is set to its corresponding starting-val, and step (b) is performed through another cycle.
    4. When the condition in step (c) is true, the cycle repeats for the next higher-level counter. These cycles continue repeating in this hierarchical manner until the topmost (VARYING) counter is cycled. For each level, all levels underneath it are reinitialized and run through a full cycle each time the corresponding counter is incremented.
    5. The PERFORM statement ends when the topmost (VARYING) condition is true.
  7. At the end of a PERFORM statement with the TEST AFTER phrase, the value of each counter is the same as at the end of the most recent execution of the PERFORM range.
Parent topic: Procedure Division Statements


READ Statement

The READ statement makes records available to the program from the program's data files.

Format 1

READ file-name  [NEXT    ] RECORD
                [PREVIOUS]
                [BACKWARD]

          [ WITH [NO  ] LOCK ]
                 [KEPT]

          [ INTO dest ]

          [ ALLOWING UPDATERS ]

          [ AT END statement-1 ]

          [ NOT AT END statement-2 ]

          [ END-READ ]

Format 2

READ file-name RECORD

     [ WITH [NO  ] LOCK ]
            [KEPT]

     [ INTO dest ]

     [ ALLOWING UPDATERS ]

     [ KEY IS key-name ]

     [ INVALID KEY statement-1 ]

     [ NOT INVALID KEY statement-2 ]

     [ END-READ ]

Syntax Rules

  1. file-name is the name of a file described in the Data Division. It may not be a sort file.
  2. dest is a data item.
  3. key-name is the name of a data item specified as a record key for file-name.
  4. statement-1 and statement-2 are imperative statements.
  5. Format 1 must be used for sequential access files.
  6. The KEY phrase can be used only for indexed files.
  7. dest may not occupy any of the storage area used by the record area of file-name.
  8. BACKWARD and PREVIOUS are equivalent.
  9. The NEXT or PREVIOUS phrase must be specified for a Format 1 READ for dynamic access mode files.
  10. The PREVIOUS phrase may not be specified for a sequential organization file.
  11. The word KEPT is treated as commentary.
  12. The LOCK, INTO and ALLOWING phrases may appear in any order.

General Rules

  1. The file referenced by a READ statement must be open in the INPUT or I-O mode when the statement executes.
  2. For sequential access mode files, if neither NEXT nor PREVIOUS is used, NEXT is implied.
  3. A successful READ statement causes the file's record area to be filled with the record retrieved from the file.
  4. If the record read is smaller than the record area, the excess characters are left unmodified unless the file has automatic trailing space removal specified. In this case, the record is padded with spaces.
  5. The READ statement updates the value of the associated FILE STATUS variable.
  6. A successful Format 1 READ statement retrieves a record from the file according to the following rules:
    1. The last OPEN, READ, or START verb used for the file determines which record is retrieved. Other file operations do not affect which record is retrieved.
    2. If an OPEN verb was the last verb to affect the file position, then the first record is retrieved if the NEXT phrase is used (or implied). If the PREVIOUS phrase is used, an end-of-file condition occurs.
    3. If the last verb to affect the file position was a successful START statement, then the record selected by that START statement is returned, regardless of whether the NEXT or PREVIOUS phrase was used.
    4. If the last verb to affect the file position was a successful READ statement, then the following or the preceding record is retrieved, depending on the NEXT or PREVIOUS phrase used.
    5. For sequential and relative files, the record ordering is based on the physical ordering of the records in the file (relative files are physically ordered by ascending record numbers).
    6. For indexed files, the record ordering is based on the logical ordering of the current Key of Reference. The Key of Reference is set by the last successful OPEN, READ, or START statement executed for the file.
  7. When a Format 1 READ statement executes, the preceding rule may indicate that no next logical record exists. When this happens, the following occurs:
    1. The at-end condition is set and the appropriate FILE STATUS is set.
    2. If the AT END phrase is specified, statement-1 executes. Control does not proceed to a USE AFTER EXCEPTION statement.
    3. If no AT END phrase is specified, but an appropriate USE AFTER EXCEPTION procedure exists, that procedure is executed with an implied return to the end of the READ statement.
    4. If neither case (b) nor (c) applies, then an error message is printed and the program halts.
  8. If the at-end condition does not occur, and no other exception causes the USE AFTER EXCEPTION procedure to execute, the NOT AT END phrase (if any) is used and statement-2 is executed.
  9. For a relative file, a Format 1 READ updates the contents of the file's RELATIVE KEY data item to reflect the record number of the returned record.
  10. When the program is sequentially accessing records from an indexed file that contains records with duplicated alternate key values, those records are returned in the same order in which they were created. These duplicate values can be created by WRITE or REWRITE statements. (These records may be reordered in the process of rebuilding the file on another key.)

    For sites using the RMS file system, please note that when a set of records having duplicate keys is encountered, RMS returns only the first record in the set.

  11. A Format 2 READ statement provides you with the ability to read records in random order by specifying appropriate key values. A Format 2 READ statement on a relative file retrieves the record whose record number is specified by the file's RELATIVE KEY data item.
  12. For indexed files, a Format 2 READ statement retrieves the record that contains the same key value as the corresponding data item in the file's record area. The key used is the one named in the KEY phrase of the READ statement. If no KEY phrase is used, the file's primary key is implied. The key used becomes the file's current Key of Reference for future Format 1 READ statements. For key values that are duplicated, the record that corresponds to the first of the sequence of duplicated values (as described in General Rule 10 above) is returned.
  13. After successfully retrieving a record, a Format 2 READ statement sets the file's File Position Indicator to the next logical record according to General Rule 6.
  14. If a Format 2 READ cannot find a record with the appropriate key value, the invalid-key condition exists. When this happens the following occurs:
    1. If the INVALID KEY phrase is specified, statement-1 executes. Control does not proceed to a USE AFTER EXCEPTION statement.
    2. If no INVALID KEY phrase is specified, but an appropriate USE AFTER EXCEPTION procedure exists, that procedure is executed with an implied return to the end of the READ statement.
    3. If neither case (a) nor (b) applies, then an error message is printed and the program halts.
  15. If the NOT INVALID KEY phrase is used and the invalid-key condition does not exist, and no other condition causes a USE AFTER EXCEPTION procedure to execute, statement-2 is executed.
  16. If an applicable USE AFTER EXCEPTION procedure exists, it executes whenever a condition occurs that results in a non-zero file status. However, it does not execute if the condition is invalid-key and an INVALID KEY phrase is used, or if the condition is at-end and an AT END phrase is used.
  17. If a READ statement is unsuccessful, the current file position and the current Key of Reference are both set to be undefined. See General Rules 22 and 23 for exceptions.
  18. The INTO phrase causes the contents of the file's record area to be moved to dest according to the rules of the MOVE statement. This move occurs after the record is retrieved, but only if the statement is successful.
  19. The WITH NO LOCK and ALLOWING UPDATERS phrases are equivalent. They both cause the record to be read without record locking. In the default mode, any successful READ on a file open in the I-O mode causes the retrieved record to be locked. A locked record may not be read (with lock) or updated by another program. Once locked, a record remains locked until any other I/O statement in the program that locked it is executed for the file. (An exception to this is files that hold multiple record locks--see File-Control Paragraph for details.) Once another I/O statement is executed for the file, the currently locked record becomes unlocked, even if the I/O is unsuccessful.
  20. The WITH NO LOCK and ALLOWING UPDATERS phrases are implied for a file open in the INPUT mode, and thus have no effect.
  21. For files with manual record locking mode the WITH NO LOCK phrase is implied. For such a file to place a record lock, it must specify WITH LOCK on the READ statement. See File-Control Paragraph for more information.
  22. Normally, a read that fails due to a record lock will return the appropriate FILE STATUS. In RM/COBOL compatibility mode, however, if the file has no applicable USE AFTER EXCEPTION procedure available, the program will wait until the record becomes unlocked. It will then read the record and proceed normally. Note that this can result in deadlock. This feature is provided for RM/COBOL compatibility. Because of the danger in using it, it is not recommended.
  23. The current Key of Reference and current file position are not modified by a record locked condition. This allows a program to wait an appropriate amount of time for the record to become unlocked and then try executing the same READ statement without having to re-establish the current file position. Because of the nature of RMS, this rule is not followed for a program running under the VMS operating system. In this case, the File Position Indicator is undefined.
  24. If the end of a file is reached by a READ NEXT statement, a subsequent READ PREVIOUS statement will return the last record in the file. Similarly, if the beginning of a file is reached by a READ PREVIOUS statement, a READ NEXT statement will retrieve the first record of the file.
  25. If the NEXT SENTENCE option is used, control passes to the next executable sentence. Note that the ANSI standard states that NEXT SENTENCE is an archaic feature and its use should be avoided.
  26. The IBM DOS/VS COBOL -Cv compatibility mode supports Reversed File Reads.
Parent topic: Procedure Division Statements


RECEIVE Statement

The RECEIVE statement retrieves messages sent by other threads.

General Format

RECEIVE dest-item FROM { THREAD thread-1 }
                       { LAST THREAD     }
                       { ANY THREAD      }

Remaining phrases are optional, can appear in any order.

{ BEFORE TIME timeout }
{ WITH NO WAIT        }

THREAD IN thread-2

SIZE   IN size-item

STATUS IN status-item

[ ON EXCEPTION statement-1 ]

[ NOT ON EXCEPTION statement-2 ]

[ END-RECEIVE ]

Syntax Rules

  1. dest-item is any data item.
  2. thread-1 and thread-2 are usage HANDLE or HANDLE OF THREAD data items. thread-2 may not be indexed or reference modified.
  3. timeout is a numeric literal or data item.
  4. size-item is a numeric data item. It may not be indexed or reference modified.
  5. status-item is a two-character group item, PIC XX, or PIC 99 data item. It may not be indexed or reference modified.
  6. statement-1 and statement-2 are any imperative statements.

General Rules

  1. The RECEIVE statement returns the next available message into dest-item. Only messages from the proper source are allowed as follows:
    1. FROM THREAD thread-1 specifies that only messages from the thread identified by thread-1 are allowed.
    2. FROM LAST THREAD specifies that only messages from the last thread are allowed. See Thread Fundamentals for more information.
    3. FROM ANY THREAD specifies that all messages are allowed.
  2. Messages are received in the order sent. If a message is available when the RECEIVE statement executes, the RECEIVE statement finishes immediately. Otherwise, the RECEIVE statement waits for a message to become available. This provides an efficient method for threads to synchronize with each other.
  3. When BEFORE TIME is specified, the RECEIVE statement will time out after the specified (timeout) number of hundredths of seconds. If the RECEIVE statement times out before receiving a message, it terminates with an exception condition and does not modify dest-item, thread-2, or size-item. If timeout is zero, then the RECEIVE statement times out immediately if a message is not available. Specifying NO WAIT is equivalent to specifying a timeout value of zero.
  4. If no message is available and the sending thread (as specified by rule1 above) does not exist or terminates before sending a message, the RECEIVE statement terminates with an exception condition and does not modify dest-item or size-item. This condition is reflected in the status placed in status-item. Note that the test occurs before the time-out test in the case that timeout is zero or NO WAIT is specified.
  5. The RECEIVE statement places the thread ID of the sending thread in thread-2.
  6. The size of the message sent is placed in size-item. The size is expressed in standard character positions (bytes). If the message is longer than dest-item, it is truncated. If the message is shorter than dest-item, it is padded on the right with spaces.
  7. The status of the RECEIVE statement is placed in status-item. The following values are possible (these approximate the standard file status codes):
    "00" | Success - message received
    "04" | Success - message received, but it was truncated
    "10" | Exception - sending thread does not exist or terminated
    "99" | Exception - timed out
  8. If the RECEIVE statement is successful (as indicated in rule 7 above), statement-2 executes. If an exception condition is returned, statement-1 executes.
Parent topic: Procedure Division Statements


RELEASE Statement

The RELEASE statement makes records available to the initial phase of a sort operation.

General Format

RELEASE record  [ FROM source-rec ]

Syntax Rules

  1. record is the name of a record of a sort file described in an SD entry in the File Section.
  2. source-rec is a data item.
  3. A RELEASE statement can appear only in an input procedure to a SORT verb.
  4. record and source-rec may not have overlapping storage.

General Rules

  1. The RELEASE statement makes record available to the input phase of a sort operation. See SORT Statement for more information.
  2. The RELEASE statement may be executed only while the program is executing an input procedure for a SORT verb that is sorting the file associated with record. Any other use causes a runtime error.
  3. If the FROM phrase is used, source-rec is moved to record according to the rules of the MOVE statement before record is released to the sort operation.
  4. The size of the record released to the sort operation is determined by the size of record.
  5. If a RELEASE statement is executed in a wrong context, e.g., outside an input procedure, the runtime displays the error Illegal RELEASE." This error belongs to the class of intermediate runtime errors that, upon occurrence, call installed error procedures.
Parent topic: Procedure Division Statements


RETURN Statement

The RETURN statement retrieves records from sort or merge operations.

General Format

RETURN file-name RECORD [ INTO dest-record ]

      AT END statement-1

    [ NOT AT END statement-2 ]

    [ END-RETURN ]

Syntax Rules

  1. file-name is the name of a sort file described by an SD entry in the Data Division.
  2. dest-record is a data item.
  3. statement-1 and statement-2 are imperative statements.
  4. A RETURN statement may appear only in an output procedure associated with a SORT or MERGE statement. A RETURN statement may not be placed in Declaratives.
  5. The record area associated with file-name and dest-record may not have overlapping storage.

General Rules

  1. The RETURN statement returns the next record from the output phase of a SORT or MERGE statement and places this record in the record area associated with file-name. The RETURN statement may be executed only while the program is executing an output procedure of a SORT or MERGE statement.
  2. Any area in the record area associated with file-name that is beyond the end of the returned record is left unchanged.
  3. If the INTO phrase is specified, the record area associated with file-name is moved to dest-record according to the rules of the MOVE statement. This move occurs after the record is retrieved, but only if the statement is successful.
  4. When no more records are available from the SORT or MERGE operation, statement-1 is executed. Otherwise, statement-2, if specified, is executed.
  5. The RETURN statement does not update the FILE STATUS variable associated with file-name.
  6. If a RETURN statement is executed in a wrong context, the runtime displays the error Illegal RETURN. This error belongs to the class of intermediate runtime errors that, upon occurrence, call installed error procedures. See CBL_ERROR_PROC in Appendix I. Library Routines for more information.
Parent topic: Procedure Division Statements


REWRITE Statement

The REWRITE statement logically replaces a record in a file.

General Format

REWRITE record [ FROM source-field ]

    [ INVALID KEY statement-1 ]

    [ NOT INVALID KEY statement-2 ]

    [ END-REWRITE ]

Syntax Rules

  1. record must be the name of a logical record in the Data Division File Section. The associated file may not be a sort file.
  2. source-field is a data item or literal.
  3. statement-1 and statement-2 are imperative statements.
  4. The INVALID KEY and NOT INVALID KEY phrases may not be specified for sequential files or relative files with sequential access.
  5. record and source-field may not share any storage area.

General Rules

  1. The file associated with record must be a mass storage file and must be open in the I-O mode.
  2. For files with sequential access mode, the preceding I/O statement executed for the file must have been a successful READ statement. The REWRITE statement replaces the last record read by the contents of record. If the file is an indexed file, the primary key must not have been changed since the last READ.
  3. For random or dynamic access mode files, the REWRITE statement replaces the record specified by the file's key.

    For relative files, this is the record specified by its RELATIVE KEY data item. For indexed files, the record identified by the primary key is replaced.

  4. For an indexed file with alternate keys, the order in which duplicated keys are subsequently returned is affected as follows:
    1. If the value of an alternate key has not changed, its order of retrieval is unchanged.
    2. If the value is changed, and the new value is a duplicated value, the record's logical position is unpredictable within the set of records with that value.
  5. The REWRITE statement does not affect the current file position.
  6. The following occurrences cause the invalid-key condition:
    1. The access mode is sequential and an indexed file's primary key is not identical to the value returned from the preceding READ statement.
    2. The record being replaced does not exist in the file.
    3. The value of an alternate key that does not allow duplicates equals that of another record already in the file.

    The invalid-key condition causes the REWRITE to fail and does not update the file.

  7. If the invalid-key condition occurs, and there is an INVALID KEY phrase, statement-1 executes. If there is no INVALID KEY phrase, but there is an appropriate USE AFTER EXCEPTION procedure, that procedure executes. Otherwise, an invalid-key condition causes a message to be printed and the program halts.
  8. If the NOT INVALID KEY phrase is specified, statement-2 executes if the REWRITE statement is successful.
  9. For a sequential file, the size of the record must be the same as the one it is replacing. The size of the record written is determined by the size of record.
  10. The REWRITE statement updates the value of the FILE STATUS data item for the file.
  11. If the FROM phrase is specified, it is identical to first moving the value of source-field to record using the rules of the MOVE statement and then performing the REWRITE as if there were no FROM phrase.
Parent topic: Procedure Division Statements


ROLLBACK Statement

The ROLLBACK TRANSACTION verb causes a transaction to be rolled back or canceled.

General Format

ROLLBACK TRANSACTION

General Rules

The following rules describe how transaction management operates with Vision and relative files. For other file systems linked with the runtime, each system's native mechanism for transaction management is invoked. See the Acucorp interface document for the specific file system for more details.

  1. ROLLBACK locks the log file, checks its integrity, then writes a ROLLBACK notation to the log file and unlocks it.
  2. When ROLLBACK is enabled in the FILE-CONTROL entry for a file, the record and file locking rules are extended for that file. Every record updated as part of a transaction is locked until that transaction is committed or rolled back. The ROLLBACK verb removes these locks. Record locks applied when reading the file are also kept until the end of the transaction.
  3. During a transaction involving Vision or relative files, a CLOSE of a file that is locked, or that has locked or deleted records, is postponed until the transaction is committed or rolled back. If the same physical file is opened again within the transaction, even if the program is using a different logical file (different SELECT), the postponed CLOSE is canceled. Note that the mode of the original OPEN is retained. (For example, if the file were originally OPEN I-O, and if the CLOSE were canceled, then an OPEN OUTPUT on the same file within the same transaction would not recreate the file.) When the second OPEN is encountered, the file position is reset to the beginning so that a READ NEXT would read the first file in the record. CLOSE is handled in this special way so that record locks are held—these locks are necessary for rollback.
  4. If the runtime system is killed by the user or encounters a fatal error prior to completing a transaction, an automatic rollback occurs.
  5. Unless the LOGGING configuration variable is set to 0, file operations that occur in transactions are logged and recoverable regardless of whether the files have rollback capability.
  6. Temporary files used for rollback are created in the working directory, or in the directory specified by the LOCK_DIR configuration variable of the runtime.
  7. The first write or rewrite on a sequential access mode file after a ROLLBACK TRANSACTION will be successful even if the primary key was written out of sequence, and even if the primary key on a rewrite does not match the last record read. No file error 22 will occur. This allows the program to continue where it left off after a rollback.
  8. If the STOP_RUN_ROLLBACK configuration variable is set to 1, an implicit ROLLBACK occurs before a STOP RUN or before the end of the program.
Parent topic: Procedure Division Statements


SEARCH Statement

The SEARCH statement searches an indexed table for a specific table entry. The search may be sequential or binary (SEARCH or SEARCH ALL). The search terminates when either a match is found (first match), or when the entire table has been searched.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

Format 1

SEARCH table-name [ VARYING index-item ]

 [ AT END statement-1 ]

 { WHEN srch-cond {statement-2   }   } ...
                  {NEXT SENTENCE }

 [ END-SEARCH ]

Format 2

SEARCH ALL table-name

 [ AT END statement-1 ]

 WHEN { tbl-item   {IS EQUAL TO} value    }
      {            {IS =       }          }
      { cond-name                         }

      [ AND { tbl-item   {IS EQUAL TO} value } ] ...
            {            {IS =       }       }
            { cond-name                      }

            { statement-2   }
            { NEXT SENTENCE }

 [ END-SEARCH ]

Syntax Rules

  1. table-name is a data item that must contain an OCCURS clause including an INDEXED BY phrase. table-name must not be subscripted in the SEARCH statement. In Format 2, table-name must also contain the KEY IS phrase in its OCCURS clause.
  2. index-item is a numeric integer data item or an index name. It may not be subscripted by the first index name in the INDEXED BY phrase in the OCCURS clause of table-name.
  3. srch-cond is a conditional expression.
  4. statement-1 and statement-2 are imperative statements.
  5. value may be a data item, a literal, or an arithmetic expression. It must be legal to compare value with tbl-item. No data item in value may be referenced in the KEY IS phrase in the OCCURS clause of table-name, nor may it be subscripted by the first index-name associated with table-name.
  6. cond-name is a condition-name (level 88) that must be defined as having only a single value. The condition-variable associated with cond-name must appear in the KEY IS phrase in the OCCURS clause of table-name.
  7. tbl-item must be subscripted by the first index-name associated with table-name along with other subscripts as required. It must be referenced in the KEY IS phrase in the OCCURS clause of table-name. tbl-item may not be reference modified.
  8. In Format 2, when a tbl-item or a cond-name is referenced, all preceding data-names in the KEY IS phrase in the OCCURS clause of table-name (or their associated condition-names) must also be referenced.

Format 1 General Rules

  1. The Format 1 SEARCH statement searches a table serially starting with the current index setting.
    1. If the index-name associated with table-name contains a value that is higher than the highest occurrence number for table-name, the search terminates immediately. If the AT END phrase is specified, statement-1 executes. Control then passes to the end of the SEARCH statement.
    2. If the index-name associated with table-name contains a valid occurrence number, the SEARCH statement evaluates the WHEN conditions (srch-cond) in the order they appear. If no condition is satisfied, the index-name associated with table-name is set to the next occurrence number. The evaluation process is then repeated. This process ends when a condition is satisfied or an occurrence number outside of the range of table-name is generated. In this second case, processing continues as in step (1a) above.
    3. When a srch-cond is satisfied, the SEARCH terminates and the associated statement-2 executes (or control passes to the next sentence if NEXT SENTENCE is used). The index-name associated with table-name remains set at its current value. Control then passes to the end of the SEARCH statement.
  2. If there is no VARYING phrase specified, the index-name used for the search is the first index-name in the INDEXED BY phrase associated with table-name. Other index-names associated with table-name remain unchanged.
  3. If the VARYING phrase is specified, and index-item names an index-name associated with table-name, then that index-name is used for the search operation. If index-name names some other index-name or a numeric data item, that item is incremented by 1 every time the index-name associated with the search operation is incremented. The index-name specified in rule 2 is used for the search procedure.

Format 2

  1. A Format 2 SEARCH performs a binary search of an ordered table. It yields predictable results only when:
    1. the data in the table has the same order as specified by the KEY IS phrase associated with table-name
    2. the contents of the keys in the WHEN phrase identify a unique table element
  2. The initial value of the table-name index-name is ignored. It is varied in a non-linear manner by the SEARCH operation until the WHEN conditions are satisfied or the table has been searched.
  3. If the WHEN phrase conditions are not satisfied for any index setting, control passes to the AT END phrase statement-1, if any, or to the end of the SEARCH statement. The setting of the table-nameindex-name is not predictable in this case.
  4. If all of the WHEN phrase conditions are satisfied for an index setting, control passes either to the associated statement-2 or to the next sentence, whichever is specified. The table-nameindex-name indicates the occurrence number that satisfied the conditions.
  5. The index-name used for the search is the first index-name listed in the INDEXED BY phrase associated with table-name. Other index-names remain unchanged.

Code Example 1

In this example SEARCH is used to conduct a sequential search of the table for the first match. The index data item must be assigned an initial value by the program. Note that subsequent searches of the table for additional matches may be made if the value of the search index is saved after a match.

Assume the following table data item:

01  FRUIT-TREE-INVENTORY.
    05  FRUIT-TREE-TABLE
        OCCURS 100 TIMES
        INDEXED BY FTT-INDEX.
        10  FT-NAME    PIC X(25).
        10  FT-CODE    PIC X(5).
        10  FT-PRICE   PIC 9(5)V99.
        10  FT-COUNT   PIC 999.
*05 table name is specified by SEARCH
*OCCURS and INDEXED BY required for SEARCH

Assume that FRUIT-TREE-TABLE has been loaded.

*use SET to initialize the index
SET FTT-INDEX TO 1.
SEARCH FRUIT-TREE-TABLE
*handle no match in table
   AT END DISPLAY "Variety not found."
*test for match
   WHEN FT-NAME (FTT-INDEX) = TREE-NAME
*match found, perform action
      PERFORM DISPLAY-INVENTORY-ITEM
END-SEARCH.

Example 2

In this example a WHEN clause is used in a sequential search to test for an end of table (AT END equivalent) condition. Note that when the table being searched is not full (has table elements at the end that have not been filled), searching the table into the unfilled space will give unpredictable results. You can search a partially filled table by determining the position of the last valid entry in the table and then using a WHEN clause in the SEARCH statement to test for when the search process traverses past the last valid entry.

Assume the same table declaration as in example 1. Assume, also, that the program has verified the table entries and has saved the subscript value of the last valid entry in a variable named LAST-VALID-ENTRY.

*initialize the search index
SET FTT-INDEX TO 1.
SEARCH FRUIT-TREE-TABLE
*test for match
   WHEN FT-NAME (FTT-INDEX) = TREE-NAME
*match found, perform action
      PERFORM DISPLAY-INVENTORY-ITEM
*test for indexing into unfilled table space
   WHEN FTT-INDEX > LAST-VALID-ENTRY
*exit the SEARCH statement
      NEXT SENTENCE.

if ftt-index > last-valid-entry
      display " variety not found".

Code Example 3

In this example SEARCH ALL is used to conduct a binary search of an ordered table. Binary searches require sequential, ordered tables. The table definition must include an ASCENDING or DESCENDING KEY clause. The search terminates upon first match, and there is no way to continue the search to find a second match. Binary searches are best suited to large tables (typically 50 records or more). When used to search large tables, the binary search method will, on average, find a table record much more quickly than will a sequential search. For example, a table containing 1000 records will need to perform no more than ten comparisons to find a match.

Assume the following table data item:

01  FRUIT-TREE-INVENTORY.
    05 FRUIT-TREE-TABLE
*OCCURS required for SEARCH
      OCCURS 100 TIMES
*ASCENDING/DESCENDING KEY required
*for SEARCH ALL
      ASCENDING KEY IS FT-NAME
*INDEXED BY required for SEARCH
      INDEXED BY FTT-INDEX.
      10  FT-NAME    PIC X(25).
      10  FT-CODE    PIC X(5).
      10  FT-PRICE   PIC 9(5)V99.
      10  FT-COUNT   PIC 999.

Assume the table has been loaded.

*FTT-INDEX is initialized by SEARCH ALL
SEARCH ALL FRUIT-TREE-TABLE
*Handle no match in table.
    AT END DISPLAY "Variety not found"
*Test for match
    WHEN FT-NAME (FTT-INDEX) = TREE-NAME
*Match found, perform action
    PERFORM DISPLAY-INVENTORY-ITEM
END-SEARCH.

Code Example 4

This example demonstrates how to use SEARCH or SEARCH ALL to search multi-dimensional tables:

SEARCH is not, by itself, equipped to perform multi-dimensional table searches. One approach to accomplishing multi-dimensional table searches is to use SEARCH in conjunction with PERFORM/VARYING (as the following example will illustrate). When used together, SEARCH handles lookups at the innermost level (dimension) of the table structure and PERFORM/VARYING is used to manage stepping through the outer levels of the table.

Assume the following table data item:

01  TREE-INVENTORY.
    05  NURSERY-YARD                   |inventory location,
            OCCURS 10 TIMES            |"outer" table
            INDEXED BY YARD-IDX.
            10  TREE-TABLE             |tree type,
                   OCCURS 100 TIMES    |"inner" table
                   INDEXED BY TT-IDX.
                15  FT-NAME       PIC X(25).
                15  FT-CODE       PIC X(5).
                15  FT-PRICE      PIC 9(5)V99.
                15  FT-COUNT      PIC 999.

Assume the table has been loaded.

MOVE "N" TO TREE-FOUND.
PERFORM SEARCH-TREE-INVENTORY
*step through the outer table
   VARYING YARD-IDX FROM 1 BY 1
      UNTIL YARD-IDX > 10 OR TREE-FOUND = "Y".

IF TREE-FOUND = "N"            |note that this code
    PERFORM NO-TREE-FOUND.     |executes after the
END-IF.                        |search is complete
{ . . . }
SEARCH-TREE-INVENTORY.
   SET TT-IDX TO 1.
   SEARCH TREE-TABLE
      WHEN TREE-TABLE(YARD-IDX,TT-IDX) = TREE-NAME

*note that both the inner and outer table
*indexes are required
         PERFORM DISPLAY-INVENTORY-ITEM
         MOVE "Y" TO TREE-FOUND
   END-SEARCH.

If the inner table is ordered and large enough to benefit from a binary search, use SEARCH ALL.

Highlights for First-time Users

  1. The table name identifier used in SEARCH must be the table name specified in the OCCURS phrase of the table declaration. You cannot use the 01 table label that starts the table declaration.
  2. If END-SEARCH is used NEXT SENTENCE cannot be used. Where possible it is best to use the sentence terminator, END-SEARCH. Unintended logic errors are often introduced by the use of NEXT SENTENCE and are easily avoided by the use of END-SEARCH.
Sequential Searches (SEARCH)
  1. A sequential search is conducted as follows:
    1. The search cycle begins by verifying that the value of the index data item falls within the range of the table size (the range is from 1 to the value specified in the OCCURS clause of the record definition).
    2. If the index value is valid, then each WHEN condition phrase is evaluated until either a match is found or until all WHEN conditions have been tested.
    3. If there is no match, the value of the index is incremented by one, validated (as in step a), and the WHEN condition evaluation cycle is repeated.
    4. Steps a - c iterate until either a match is found or the value of the index exceeds the table range, indicating that the entire table has been searched.
    5. If a match is found, the search terminates and the imperative statement associated with the WHEN clause is executed. Program execution then resumes immediately after the SEARCH statement. Note that the value of the index data item remains set to the value of the subscript of the matched entry.
    6. If the value of the search index ever becomes less than one or greater than the table size, the search terminates, the optional AT END statement, if present, is executed, and program execution continues immediately after the SEARCH statement.
  2. The index data item named in the INDEXED BY clause is used to index the table in the sequential search and must be explicitly initialized in the program. Use SET to assign the initial value. When the search results in a match, the index data item remains set to the table subscript of the matching entry. Saving or preserving this value makes it possible to make another search of the table for a subsequent match.

    Initializing the index data item:

    1. If the entire table is to be searched, the index data item should be assigned, using SET, the value 1, thereby starting the search with the first record.
    2. If the search is to begin with an entry other than the first, then the index data item should be assigned the value of the position of the first table entry to be checked. For example, to start the search at table entry 10, assign the value 10 to the index data item.
    3. If, after a search finds a match, you want to make an additional search of the table to find a subsequent match, the value of the index data item should be preserved and then reassigned so that the next search begins at 1 + index-item.
  3. When searching tables that are not full (do not contain valid entries for every occurrence in the table), use a WHEN clause to test for the actual end-of-table condition. If the search is allowed to proceed into the unused portion of the table, garbage values in the unfilled table space will give unpredictable results. See code example 2.
  4. The relational match conditions associated with each WHEN clause may be connected with the logical connectors AND or OR thereby specifying multiple or alternate match conditions. For example:
    WHEN NAME = SEARCH-NAME OR SIZE < MAX-SIZE
  5. Use of the VARYING phrase: The VARYING phrase allows alternate or multiple indexes to be incremented by the search loop. If VARYING is omitted, the first index-item defined in the INDEXED BY phrase of the OCCURS clause (for the table) is incremented.

    If the VARYING phrase is included, the index item named after VARYING is incremented, as well as the first named index in the INDEXED BY phrase, with one exception. If the index named after VARYING is also named in the INDEXED BY phrase, then it is the only index incremented.

Binary Searches (SEARCH ALL):
  1. The binary search is conducted as follows:
    1. The search begins at the midpoint of the table (for example, 50 of 100) and compares the value of the table entry with the search item to determine if there is a match.
    2. If there is no match, SEARCH determines whether the search item is logically located in the upper or lower half of the table (0-49, or 51-100).
    3. SEARCH then finds the midpoint of the half that logically contains the search item and determines if the table element at the midpoint matches the search item.
    4. If there is no match, SEARCH again determines whether the search item is logically located in the upper or lower half of the remaining range.
    5. This process iterates until the search item is found or until it is determined that the table does not contain the search item (the remaining table range becomes null).
    6. If at any time a match is found, the search immediately terminates and the imperative statement associated with the WHEN clause is executed. Program execution then resumes immediately after the SEARCH statement.
  2. Binary searches require sequential, ordered tables (via use of the ASCENDING/DESCENDING KEY phrase). The table must be ordered as specified by the KEY IS phrase of the table definition.
  3. The matching conditions of the WHEN clause must identify a unique table entry.
  4. Binary searches are best suited to large tables (typically 50 records or more) where the binary search algorithm significantly reduces the average number of lookups per match.
  5. Unlike a sequential search, the binary search format permits only one WHEN clause.
  6. Because only one WHEN clause is permitted and because the index value is automatically set by the program, it is not possible to SEARCH partially full tables.
  7. The SEARCH ALL match conditions are very restrictive. Match condition evaluation is restricted to evaluation of a condition-name, which can represent only a single value (no range or sequence of values permitted), or a condition which tests for equality.
  8. The table data item and the index must be on the left side of the condition statement.
  9. Multiple condition tests are permitted but can be connected only with an AND (no OR).
  10. Any table item or condition-name referenced must be named in the KEY IS phrase of the OCCURS clause of the table definition.
  11. The VARYING option is not permitted.
  12. When a match is found, the index retains the value of the table subscript of the matched entry. If no match is found the value of the index is unpredictable.
Parent topic: Procedure Division Statements


SEND Statement

The SEND statement sends a message to other threads.

General Format

SEND src-item TO { { THREAD dest-thread } ... }
                 { LAST THREAD                }
                 { ALL THREADS                }

Syntax Rules

  1. src-item is a literal or data item.
  2. dest-thread is a USAGE HANDLE or HANDLE OF THREAD data item.

General Rules

  1. The SEND statement sends a message containing the data in src-item to one or more threads. Which threads receive the message depends on the following:
    1. THREAD dest-thread causes the message to be sent to the thread identified by dest-thread. More than one dest-thread can be specified.
    2. LAST THREAD causes the message to be sent to the last thread. See Thread Fundamentals in the ACUCOBOL-GT User's Guide for a discussion of the last thread.
    3. ALL THREADS causes the message to be sent to all currently existing threads, except the sending thread.
  2. The size of the message is equal to the size of src-item.
  3. The THREAD dest-thread and LAST THREAD options create a directed message. Directed messages are sent to the specified threads or last thread and are guaranteed to be delivered to the specified threads. Directed messages are held in a queue. If there is not enough space in the queue to place the message (because of other messages that have not yet been received), the sending thread suspends until space becomes available in the queue. Messages are received in the order sent. See the listing for MESSAGE_QUEUE_SIZE runtime configuration variable located in Appendix H for options on setting the queue size.
  4. The ALL THREADS option creates a broadcast message. Broadcast messages can be picked up by any thread. Receiving a broadcast message does not remove it from the message queue, it remains queued to be received by other threads. Broadcast messages are removed from the queue when either
    • all threads have received it, or
    • there is not enough space to hold the next broadcast message. In this case, broadcast messages are removed from the queue (oldest first) until there is enough space to place the new message in the queue. This allows the queue to empty when there are threads that never look for messages. It also means that a broadcast message may not be delivered to a particular thread if other broadcast messages are sent before the first is received. To avoid this problem, use broadcast messages sparingly.
  5. Broadcast messages can be missed under certain circumstances. To track which messages a thread has read, each thread remembers the number of the last broadcast message it has read. Messages are numbered sequentially starting at one. If a thread skips an earlier broadcast message (because the message does not meet the thread's delivery requirements) and then receives a later broadcast message, the earlier message will never be received because it has an earlier message number. For example, MESSAGE-1 will be missed in the following sequence of events:
    SEND MESSAGE-1 TO ALL THREADS    (in thread A)
SEND MESSAGE-2 TO ALL THREADS    (in thread B)
RECEIVE MSG-2 FROM THREAD B      (in thread C)
RECEIVE MSG-1 FROM ANY THREAD    (in thread C)

    The last RECEIVE in this example does not receive MESSAGE-1 because it was sent earlier than the last broadcast message it received (MESSAGE-2 in this case). This is caused by the first RECEIVE which picked up a broadcast message while asking for messages from a particular thread. To avoid this, pick up broadcast messages with the RECEIVE FROM ANY THREAD phrase. This will prevent you from skipping a message.

Parent topic: Procedure Division Statements


SET Statement

The SET statement sets the values of various types of data items, allows you to control the current and active windows, and allows you to set the priority of a thread.

Format 1

SET {result} ... TO value

Format 2

SET {result} ... {UP  } BY value
                 {DOWN}

Format 3

SET { {cond-name} ... TO {TRUE } } ...
                         {FALSE}

Format 4

SET { {switch-name} ... TO {ON } } ...
                           {OFF}

Format 5

SET FILE-PREFIX TO file-prefix

Format 6

SET {CONFIGURATION} { env-name TO env-value } ...
    {ENVIRONMENT  }

Format 7

SET pointer TO { ADDRESS OF data-item }
               { NULL                 }

Format 8

SET result-item TO SIZE OF data-item

Format 9

SET ADDRESS OF linkage-item TO { pointer             }
                               { ADDRESS OF data-item}
                               { NULL                }

Format 10

SET {INPUT       } WINDOW TO window-1
    {INPUT-OUTPUT}
    {I-O         }
    {OUTPUT      }

Format 11

SET {handle-1} ... TO HANDLE OF {screen-1       }
                                {CONTROL ID id-1}

Format 12

SET THREAD {thread-id} PRIORITY TO priority

Format 13

SET EXCEPTION {VALUE } { exc-value TO {ITEM-HELP           } } ...
              {VALUES}                {HELP-CURSOR         }
                                      {CUT-SELECTION       }
                                      {COPY-SELECTION      }
                                      {PASTE-SELECTION     }
                                      {DELETE-SELECTION    }
                                      {UNDO                }
                                      {SELECT-ALL-SELECTION}

Syntax Rules

  1. result is a numeric data item or index name.
  2. value is a numeric literal, a numeric data item, or an index name.
  3. file-prefix is a nonnumeric literal or alphanumeric data item.
  4. cond-name is any condition-name (level 88 item). If the FALSE option is used, then cond-name must have a WHEN SET TO FALSE phrase in its definition.
  5. switch-name must be a mnemonic name associated with an external switch in the SPECIAL-NAMES section of the Environment Division.
  6. env-name is a nonnumeric literal or data item.
  7. env-value is a USAGE DISPLAY numeric or nonnumeric literal or data item. If numeric, it must be an integer.
  8. CONFIGURATION and ENVIRONMENT are equivalent.
  9. pointer must be a data item with USAGE POINTER.
  10. result-item must be a numeric data item.
  11. linkage-item must be declared in the Linkage section.
  12. window-1 is a USAGE HANDLE or PIC X(10) data item that refers to a floating window or the main application window.
  13. handle-1 is a USAGE HANDLE data item. When the control is an ActiveX, COM, or .NET control, handle-1 must be a typed handle that matches the control; i.e., handle-1 must be declared with the USAGE HANDLE OF control-type syntax. See USAGE Clause for more information.
  14. screen-1 must refer to an elementary Screen Section item that describes a graphical control.
  15. id-1 and priority are numeric literals or data items.
  16. thread-id is a USAGE HANDLE or HANDLE OF THREAD data item.
  17. exc-value is an integer literal or data item.

Format 1 General Rules

Each result is set to value. This assignment is done such that the numeric values of result and value will be the same.

Format 2 General Rules

value is either added to (UP BY) or subtracted from (DOWN BY) each result item. No size error checking is done.

Format 3 General Rules

  1. When the TRUE phrase is used, the literal in the VALUE clause for cond-name is moved to its associated condition-variable. If the VALUE clause contains more than one literal, the first one is used.
  2. When the FALSE phrase is used, the literal defined in the WHEN SET TO FALSE phrase of cond-name is moved to its associated condition-variable.

Format 4 General Rules

Format 4 of the SET statement alters the on/off status of external switches. These switches are initially off unless otherwise specified when the program is run.

Format 5 General Rules

  1. The FILE-PREFIX is a special register maintained by ACUCOBOL-GT to aid in translating COBOL ASSIGN names to actual file names on the host computer. See File Name Interpretation, in the ACUCOBOL-GT User's Guide for a complete description of its function.
  2. A Format 5 SET statement is equivalent to this Format 6 SET statement:
    SET ENVIRONMENT "FILE-PREFIX" TO file-prefix

Format 6 General Rules

  1. ACUCOBOL-GT maintains a set of configuration variables that can affect various aspects of the runtime system. These variables can be initially set in the ACUCOBOL-GT runtime configuration file described in Compiler and Runtime in the ACUCOBOL-GT User's Guide. The Format 6 SET statement can be used to modify these values at runtime.
  2. env-name is the name of the configuration variable to set. In it, lower-case characters are treated as upper case, and underscores are treated as hyphens. The first space character delimits the name. env-name may specify either the literal name of the variable or a data-item whose value is the name of the variable. If you specify the actual name of the variable, such as COMPRESS-FILES, then you must enclose the name in quotes. env-value is the value to set the variable to. If it is a numeric data item, then it is treated as if it were redefined as an alphanumeric data item.
  3. If env-name does not match the name of one of the runtime system's configuration variables, then env-name and env-value are placed in the runtime system's local environment. These entries are used to do file name translations. See File Name Interpretation in the ACUCOBOL-GT User's Guide for more information. .
  4. The complete list of environment variables used by ACUCOBOL-GT can be found in ACUCOBOL-GT Appendices, Appendix H.

Format 7 General Rules

If the ADDRESS OF option is used, then the address of data-item is stored in pointer. If the NULL option is used, then pointer is set to point to no data item.

Note that the -Zm compiler option Causes the compiler to generate code that tells the runtime the size of a data item specified in the SET statement. See Miscellaneous Options for details on the -Zm option.

Format 8 General Rules

The number of standard character positions occupied by data-item is stored in result-item.

Format 9 General Rules

  1. If pointer is specified, then the address of the linkage-item is set to pointer. If the ADDRESS OF option is used, then the address of the linkage-item is set to the address of data-item. If the NULL option is used, then the address of the linkage-item is set to point to no data item.
  2. The level of linkage-item must be either 01 or 77.
  3. If the linkage-item is not listed in the PROCEDURE DIVISION USING phrase and is referenced before the SET ADDRESS OF statement, then the runtime will abort with the message, Use of a LINKAGE data item not passed by the caller.

Format 9 is helpful if you want to allocate a sizable piece of memory for temporary use, access this memory via a COBOL table, and then free the memory. For example:

  • Use the library routine M$ALLOC to allocate the memory.
  • SET the address of a Linkage section table to the pointer returned from M$ALLOC.
  • Complete the desired procedures.
  • Free the memory with M$FREE.

The code sample that follows shows how Format 9 works.

identification division.

program-id.     sample-program.

data division.

working-storage section.

linkage section.

* item-a and ptr-a are passed in by the calling
* program

    01 item-a    pic x(10).

* ptr-a is set to the address of item-a
* in the calling program

    01 ptr-a   usage pointer.

* item-b is used in the SET Statement.
* It is not passed in by the calling program.

    01 item-b   pic x(10).

procedure division using item-a, ptr-a.
main-logic.

* Assuming item-a has a value of "ABCDEFGHIJ",
* and ptr-a points to item-a,
* the following will display "ABCDEFGHIJ" three
* times

    display item-a.

* "ABCDEFGHIJ" is displayed

    set address of item-b to ptr-a.
    display item-b.

* "ABCDEFGHIJ" is displayed

    set address of item-b to address of item-a.
    display item-b.

* "ABCDEFGHIJ" is displayed

    stop run.

Format 10 General Rules

  1. Format 10 of the SET verb makes window-1 the current, or current and active window. The current window is the window to which DISPLAY statements refer. The active window is the window that is highlighted and the one to which user input is directed. window-1 must be a handle to a valid floating window. If window-1 does not refer to a valid floating window, the SET statement has no effect.
  2. INPUT, INPUT-OUTPUT, and I-O are synonymous. They cause window-1 to become both the current and active window.
  3. OUTPUT causes window-1 to become the current window.

Format 11 General Rules

A Format 11 SET statement retrieves the handle to the control described by screen-1 or Id-1 and stores it in handle-1. Id-1 must specify a value greater than zero. If a matching control is found, handle-1 is set to the handle of that control. If no matching control is found, handle-1 is set to NULL. If more than one control has a matching ID, then handle-1 is arbitrarily set to one of those controls. Note that the handle can be used in any statement that can use control handles. One reason you might want this handle is if you need to pass a control to a subprogram. You cannot pass Screen Section names to subprograms, but you can pass the handle instead.

Format 12 General Rules

  1. A Format 12 SET statement sets the execution priority of a thread. Execution switches between threads at various points in the program. Each opportunity to change the active thread is called a switch point. The execution priority determines which thread gets control at each switch point.
  2. The execution priority is an integer. The higher the priority, the more often that thread gets control at a switch point. By default, threads start with a priority value of 100. Threads receive control in proportion to their priority. Thus, a thread with a priority of 50 gains control half as often as a thread with a priority of 100. Of course, if a thread is paused for any reason (waiting for input, for example), then it does not gain control.
  3. If thread-id is specified, then the priority for the thread identified by thread-id is set to priority. Otherwise, the current thread's priority is set to priority. If thread-id does not correspond to an existing thread, then the SET statement has no effect.
  4. The minimum priority for a thread is 1. The maximum is 32767.

Format 13 General Rules

A Format 13 SET statement associates the exception value specified in exc-value with an automated action that the runtime can perform. Any keystroke, menu item, or control that produces the exc-value exception value will automatically cause the associated action to be performed (you do not have to code the action; it happens automatically). If the runtime handles the exception in this way, then the exception is not passed on to the COBOL program.

The ITEM-HELP action produces context-sensitive help for the control with the current input focus. The HELP-CURSOR action places the mouse into help mode. For a description of the ITEM-HELP and HELP-CURSOR actions, see The Help Processor in ACUCOBOL-GT User Interface Programming.

The remaining actions take effect if the current control is an entry field (otherwise, they have no effect). These actions cause the entry field to do the following:

CUT-SELECTION | Cuts the current selection to the clipboard
COPY-SELECTION | Copies the current selection to the clipboard
PASTE-SELECTION | Pastes the clipboard into the entry field at the current location (replaces any existing selection)
DELETE-SELECTION | Deletes the current selection
UNDO | Undoes the last change
SELECT-ALL-SELECTION | Selects all the text in the entry field. In a multi-line entry field, this includes the text in all lines.

The cut, copy, paste, delete, and undo effects are accomplished automatically via the ACTION property of entry fields. Usually, you will want to assign these exception values to various menu items and toolbar push buttons. When you are setting up a push button to correspond to one of these actions, you should ensure that you make the push button a SELF-ACT button (otherwise the act of pushing the button makes the button the current control, not the entry field).

Parent topic: Procedure Division Statements


SORT Statement

The SORT statement sorts records according to selected key fields. Record content can be modified before and after the actual sort process using INPUT PROCEDURE and OUTPUT PROCEDURE.

ACUCOBOL-GT also including a sorting utility called AcuSort. See Graphical Controls in the ACUCOBOL-GT User's Guide for details on this utility. There is also a runtime configuration variable that instructs the runtime to use the system's Quicksort algorithm (if present) instead of the built-in algorithm specified by the SORT statement. See USE_SYSTEM_QSORT in Appendix H for more information.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section. In the highlights list, item four discusses ways to improve SORT performance.

General Format

SORT sort-file

  { KEY AREA IS key-table }
  { ON {ASCENDING } KEY {key-name} } ...
       {DESCENDING}

  [ WITH DUPLICATES IN ORDER ]

  [ COLLATING SEQUENCE IS alpha-name ]

  { INPUT PROCEDURE IS proc-name  }
  { USING {in-file} ...           }

  { OUTPUT PROCEDURE IS proc-name }
  { GIVING {out-file} ...         }

Note that proc-name has the following format:

  start-proc [ {THRU   } end-proc ]
               {THROUGH}

Syntax Rules

  1. sort-file names a sort file described by an SD entry in the Data Division.
  2. key-table must name a data item that is not located in the record for sort-file. key-table may not be subordinate to an OCCURS clause, nor may it be reference modified.
  3. key-table must reference a data item whose size is an even multiple of 7. key-table is processed as if it had the following structure:
    01 KEY-TABLE.
   03 SORT-KEY OCCURS N TIMES.
      05 KEY-ASCENDING PIC X COMP-X.
      05 KEY-TYPE PIC X COMP-X.
      05 KEY-OFFSET PIC XX COMP-X.
      05 KEY-SIZE PIC XX COMP-X.
      05 KEY-DIGITS PIC X COMP-X.

    Typically, programs will declare key-table with a similar format.

  4. key-name is a data item in the record description associated with sort-file. It may not be subordinate to an OCCURS clause, nor may it be a group item containing variable occurrence data items. It may not be reference modified. The maximum number of keys allowed is 23.
  5. alpha-name is an alphabet-name defined in the SPECIAL-NAMES paragraph of the Environment Division.
  6. in-file and out-file are files described by FD entries in the Data Division. They may not be sort files. The maximum number of input and ouput files is 25.
  7. start-proc and end-proc are paragraph or section names in the Procedure Division.
  8. A SORT statement may not appear in Declaratives or in the input or output procedure of a SORT or MERGE statement.
  9. If sort-file contains variable length records, in-file records must not be smaller than the smallest record in sort-file nor larger than the largest. If sort-file contains fixed length records, in-file records may not be larger than the size of sort-file’s records.
  10. If out-file contains variable length records, sort-file records must not be smaller than the smallest record in out-file nor larger than the largest. If out-file contains fixed length records, sort-file records may not be larger than the size of out-file's records.
  11. If sort-file contains more than one record description, key-name need appear in only one of them. The character positions referenced by key-name are used as the key for all the file’s records.
  12. If out-file is an indexed file, the first key-name must be ASCENDING and must specify the same character positions in its record as the primary record key for out-file.
  13. THRU is an abbreviation for THROUGH.

General Rules

  1. The SORT statement sorts records received from the INPUT PROCEDURE or found in the in-files. It then either makes these sorted records available to the OUTPUT PROCEDURE or writes them to each out-file.
  2. Sort records must be at least six bytes in size.
  3. If sort-file contains fixed length records, any shorter in-file records are space-filled on the right to match the record size.
  4. If out-file contains fixed length records, any shorter sort-file records are space-filled on the right to match the record size.
  5. The first key-name is the major key, and the next key-name is the next most significant key. This pattern continues for each key-name specified.
  6. The ASCENDING phrase specifies that key values are to be ordered from lowest to highest. The DESCENDING phrase specifies the reverse ordering. Once ASCENDING or DESCENDING is specified, it applies to each key-name until another ASCENDING or DESCENDING adjective is encountered.
  7. Use the KEY AREA option when you do not know the specifics of the sort key until the program is run. You can use this to allow users to enter sort key specifications, typically in conjunction with some form of data dictionary.
  8. Your program must fill in a table of information that describes the sort keys. This table, key-table, should have the format described by Syntax Rule 3 above. The number of sort keys is determined by the number of occurrences in the table. The keys are listed in order of precedence: table entry 1 describes the highest precedence key, table entry 2 the second highest, and so on. If you need to process a variable number of keys, use a variable-size table (by using OCCURS DEPENDING ON).
  9. For each key, you must specify the following information:
    KEY-ASCENDING: This should be 0 or 1. Enter 1 to have an ascending sort sequence, 0 for descending.
    KEY-TYPE: Describes the underlying data format. The allowed values are listed in the next rule.
    KEY-OFFSET: Describes the distance (in standard character positions) from the beginning of the sort record to the beginning of the key field. The first field in a sort record is at offset 0.
    KEY-SIZE: Describes the size of the key field in standard character positions.
    KEY-DIGITS: This is used only for numeric keys. It describes the number of digits contained in the key (counting digits on both sides of the decimal point).
  10. The KEY-TYPE field uses a code to describe the type and internal storage format of the data item. Select from the following values:
    0 | Numeric edited
    1 | Unsigned numeric (DISPLAY)
    2 | Signed numeric (DISPLAY, trailing separate)
    3 | Signed numeric (DISPLAY, trailing combined)
    4 | Signed numeric (DISPLAY, leading separate)
    5 | Signed numeric (DISPLAY, leading combined)
    6 | Signed COMP-2
    7 | Unsigned COMP-2
    8 | Unsigned COMP-3
    9 | Signed COMP-3
    10 | COMP-6
    11 | Signed binary (COMP-1, COMP-4, COMP-X)
    12 | Unsigned binary (COMP-1, COMP-4, COMP-X)
    13 | Signed native (COMP-5, COMP-N)
    14 | Unsigned native (COMP-5, COMP-N)
    15 | Floating point (FLOAT, DOUBLE)
    16 | Alphanumeric
    17 | Alphanumeric (justified)
    18 | Alphabetic
    19 | Alphabetic (justified)
    20 | Alphanumeric edited
    21 | Not used
    22 | Group

    This coding is the same one used by the C interface, and is also used by Acu4GL to interface to relational DBMSs. When specifying the key type, you may safely use "alphanumeric" for all nonnumeric keys. (The sort rules are the same for each of these types). For numeric data, however, you must specify the correct type or you may get sorting errors.

  11. The results are undefined if you provide invalid data in the key-table. If you fail to specify any keys (by specifying a table whose size is zero), you receive a file error on sort-file. Under the default file status codes, this is file error 94 with a secondary status of 63.
  12. For nonnumeric keys, the COLLATING SEQUENCE phrase establishes the ordering. If this phrase is omitted, the NATIVE collating sequence is used. For numeric keys, the ordering is specified by the algebraic value of the key.
  13. The DUPLICATES phrase affects the return order for records whose key-name values are equal.
    1. When there is a USING phrase, the return order is the same as the order of appearance of in-file names in the SORT statement. Within a given in-file, the order is that in which the records are accessed from that file.
    2. When there is an INPUT PROCEDURE, the return order is the same as the order in which records were released. If the DUPLICATES phrase is not used, the return order for records with equal key values is unpredictable.
  14. The execution of a SORT statement consists of three distinct phases. These are:
    1. Records are made available to the sort-file. This is achieved either by executing RELEASE statements in the input procedure or by implicit execution of READ statements for each in-file. When this phase starts, in-file must not be open. When it finishes, in-file will not be open.
    2. The sort-file is sequenced according to the KEY phrase and the DUPLICATES clause. No processing of in-files or out-files takes place during this phase.
    3. The records in sort-file are made available in sorted order. The sorted records are either written to the out-files or are made available to an output routine through execution of a RETURN statement. When this phase starts, out-file must not be open. When it finishes, out-file will be closed.
  15. If the INPUT PROCEDURE phrase is used, the named procedure is executed by the SORT statement according to the rules for the PERFORM verb. This procedure must make records available to the input phase of the sort operation by executing RELEASE statements. When this procedure returns, the sort operation proceeds to the sequencing phase. The range of the input procedure may not cause the execution of a MERGE, RETURN, or SORT statement.
  16. If the USING phrase is specified, all records in each in-file are transferred to sort-file. For each in-file, the following actions occur:
    1. The file is opened as if it were the object of an OPEN INPUT statement with no options.
    2. The records are obtained and released to the sort operation. Each record is obtained as if a READ statement with the NEXT and AT END phrases had been executed. For relative files, the RELATIVE KEY data item is undefined at the end of this phase.
    3. The file is closed as if it were the object of a CLOSE statement with no options. This occurs prior to the sequencing of sort-file.

      These implicit functions are performed such that any associated USE procedures are executed. These USE procedures must not access in-file or its record area.

  17. If an output procedure is specified, control passes to it after the sort-file has been sequenced. Control passes to the output procedure according to the rules of the PERFORM statement. The output procedure must execute RETURN statements to retrieve the sorted records. When the output procedure returns, the SORT statement terminates and control passes to the next executable statement. The range of the output procedure must not execute any MERGE, RELEASE, or SORT statements.
  18. If the GIVING phrase is used, all the sorted records are written to each out-file. For each of these files, the following steps occur:
    1. out-file is opened as if it were the object of an OPEN OUTPUT statement with no options.
    2. The sorted records are returned and written to the file. The records are written as if a WRITE statement without any options had been executed. For a relative file, the value of the RELATIVE KEY data item is updated to reflect the record number written.
    3. The file is closed as if it were the object of a CLOSE statement without any options.

    These implicit functions are performed such that any associated USE procedures are executed. Such a USE procedure may not refer to out-file or its record area. On the first attempt to write beyond the externally defined boundaries of the file, any applicable USE procedure is executed. If control is returned from that USE procedure, or no USE procedure is applicable, the processing of that out-file is terminated.

  19. If the SORT statement is in a fixed segment, the range of any input and output procedures must be contained completely in the fixed segments and no more than one independent segment. If the MERGE statement is in an independent segment, the range must be completely contained in the fixed segments and the same independent segment.
  20. The SORT statement updates the value of the sort-file's FILE STATUS data item.
  21. Only one SORT may be active at a time. See also CANCEL SORT.
  22. If a SORT statement is executed in a wrong context, the runtime displays the error Illegal SORT. This error belongs to the class of intermediate runtime errors that, upon occurrence, call installed error procedures. See CBL_ERROR_PROC for details.
  23. For compatibility with other COBOLs, ACUCOBOL-GT includes special registers known as SORT-RETURN and SORT-MESSAGE. SORT-RETURN can be used for two purposes.
    1. To determine the status of a SORT that's just finished. You can determine the success or failure of a SORT by examining this variable after the SORT returns. A value of 0 indicates success, and a non-zero value indicates failure.
    2. To interrupt a SORT that is currently running. By setting this variable in an input or output procedure, you stop SORT processing immediately after the next RELEASE or RETURN statement is performed. By setting this variable in a DECLARATIVES paragraph (if you are not using input or output procedures), you stop SORT processing immediately after the next implicit RELEASE or RETURN is performed.

    The special register SORT-RETURN is of type SIGNED-INT. Please note that this register is primarily for compatibility purposes, and there are better ways to perform these functions in ACUCOBOL-GT. For instance, to get status on a SORT, use the FILE STATUS variable of the SORT file. This gives more information than just success or failure. And if you are using input procedures, you can halt a SORT more simply by returning from the procedure as if you had reached the end of file.

    When compiling for IBM compatibility (-Cv), the SORT-MESSAGE behaves just like it is declared in every program, for example:

    01  SORT-MESSAGE PIC X(8) EXTERNAL.

    This variable is used in mainframe environments to help control the SORT operation. In ACUCOBOL-GT, the variable has no particular effect.

  24. The SORT statement can be used to sort elements of a working-storage table. The syntax is:
    SORT data-name-2 [ ON ASCENDING/DESCENDING KEY data-name-1 ... ]
   [ WITH DUPLICATES IN ORDER ]
   [ COLLATING SEQUENCE IS alphabet-name ]

Code Examples

SORT PRODUCT-SORT-FILE             |temporary SD file
   ON ASCENDING KEY MODEL-TYPE,    |major sort key
                    MODEL-NUMBER   |minor sort key
   USING ATHLETIC-SHOES-LIST,      |input data file
         DRESS-SHOES-LIST          |input data file
   GIVING PRODUCT-LIST.            |permanent output data file

(An extended version of this example appears after the Highlights for First-Time Users section.):

SORT PRODUCT-SORT-FILE                 |temporary SD file
*duplicates sorted in the order acquired
   ON ASCENDING  KEY MODEL-TYPE        |major sort key
   ON DESCENDING KEY MODEL-NUMBER      |minor sort key
   WITH DUPLICATES IN ORDER
   INPUT  PROCEDURE IS WEED-PRODUCT-LIST
   OUTPUT PROCEDURE IS UPDATE-PRODUCT-LIST.

Highlights for first-time users

  1. SORT is used to order records according to a set of key fields (sort keys). Records may be stored in sequential, relative, or indexed files, or records may be acquired by use of an INPUT PROCEDURE. Once ordered, the record set may be further processed by use of an OUTPUT PROCEDURE, or the records may be written directly to the named output file(s).
  2. SORT is most often used to order records stored in disk files. However, by using an INPUT PROCEDURE you can acquire records from other input sources such as output from batch processes, internal application data structures, or screen input.
  3. SORT creates a special temporary disk file (the sort file) as a work space for collecting, sorting, and holding ordered records. The sort file is defined by an SD entry in the DATA DIVISION. The sort file record definition must immediately follow the SD entry and must include definitions for each sort key used, except when the KEY AREA phrase is used. You can place temporary files used by the SORT verb in a specified directory. The sort file is removed when the SORT statement completes. See SORT_DIR for more information.

  4. Runtime performance: Most SORT procedures involve the reading, sorting, and writing of records stored in disk files. These disk I/O processes can be relatively slow and, therefore, the SORT process can take a lot of time. However, you can tune performance. To get the best runtime performance, give the process as much memory as possible, without adversely affecting other processes running on the system. Ideally, you should allocate enough memory, using the SORT_MEMORY configuration variable, so that all records fit into the allocated memory; this way, the records are sorted and moved to the output phase without requiring the use of temporary files. Determining the optimal value depends on the number and size of the records being sorted, the amount of available memory, and the needs of other processes on the system. Some experimentation may be necessary.

    For larger SORT operations, you will more than likely not be able to allocate enough memory in which all records can fit, and so the SORT operation will use temporary sort files. Use the A_SORT_REGIONS, A_SORT_REGIONS_FINAL and A_SORT_FILE_MEMORY configuration variables to fine-tune the use of temporary files.

    By default, the SORT routine uses a built-in sort function. Alternatively, if your system has a qsort() function, you can specify its use by setting the runtime configuration variable called USE_SYSTEM_QSORT to the value of 1. Some systems have qsort() functions that perform better than the built-in function. Consider experimenting with this variable to determine if this option yields better performance on your system. Pay particular attention to the number of comparisons done during the sort, which can be seen in the runtime trace output.

  5. The three basic steps of the SORT procedure are:
    1. Acquiring and placing the records to be sorted in the sort file:

      When the USING phrase is used, SORT opens each named input file, reads the data records, one at a time, into the sort file and closes the input file. Input files must not be open before the SORT statement begins.

      When an INPUT PROCEDURE is used the RELEASE verb is used to pass records to the sort file. If records are acquired from disk files, it is the responsibility of the input procedure to open, read, process, RELEASE each individual record, and close the files. For more information, see the RELEASE StatementRELEASE Statement .

    2. Sorting the records:

      Using the sort file, and a set of temporary files, records are sorted according to the key phrase, the DUPLICATES clause, and the COLLATING clause. See SORT_DIR and SORT_MEMORY for more information.

    3. Disposition of the sorted records:

      When the GIVING phrase is used, the sorted records are written to the named permanent output file(s).

      When an OUTPUT PROCEDURE is used, the sorted records are made available to the output procedure for processing and writing to a permanent file(s). The output procedure uses the verb RETURN to acquire the ordered records from the sort file. It is the responsibility of the output procedure to open, write, and close the output file(s). For more information see the description of the RETURN Statement.

  6. A SORT statement may not appear in a DECLARATIVES section or in an INPUT or OUTPUT PROCEDURE that is part of a SORT statement (nesting of SORT statements is not permitted).
  7. The KEY AREA phrase is a means for defining the sort keys at runtime, as the application is running. When you use KEY AREA, it is not required that the sort file record descriptor contain entries for potential sort keys. Definition of the sort key(s) in the sort file is handled internally by the SORT routine using the key table. See syntax rules 2 and 3 and general rules 6 through 10.
  8. If the KEY AREA phrase is not used, the sort keys must be defined in the record description of the sort file.
  9. Use of INPUT PROCEDURE or OUTPUT PROCEDURE requires that all file I/O operations and record disposition be handled by the input or output procedure. This means that the input and output procedures must explicitly perform the OPEN, READ, RELEASE (input), RETURN (output), WRITE, and CLOSE actions. As with any I/O management, the procedure should consider and account for the handling of all I/O related errors.
  10. Use the DUPLICATES phrase when you want duplicate records to be sequenced in the same order that they are read in or RELEASEd. Duplicate records are those that have identical key values. In the absence of the DUPLICATES phrase sequencing of duplicate records is not predictable (see General Rule 12).
  11. Use the COLLATING SEQUENCE phrase to alter the ordering of nonnumeric keys. The named collating sequence must be defined in the SPECIAL-NAMES paragraph of the ENVIRONMENT DIVISION. In the SPECIAL-NAMES paragraph the user may define a unique character order, or the user may select one of the four predefined character sequences: STANDARD-1, STANDARD-2, NATIVE, and EBCDIC. See Special-Names Paragraph for more information.

    If no COLLATING SEQUENCE phrase is used, the default collating sequence is used. The default collating sequence is whatever is native to the operating system (usually the same as the predefined type NATIVE).

  12. Use the STATUS variable to hold the execution status of the SORT operation. The status variable is named in the SELECT/ASSIGN phrase of the FILE-CONTROL paragraph of the INPUT-OUTPUT SECTION. See Special-Names Paragraph for more information.

    For a complete list and description of file status codes, see Appendix E, in ACUCOBOL-GT Appendices.

  13. To specify the disk directory in which SORT will place any temporary files, set the SORT_DIR runtime configuration variable, located in the runtime configuration file.

For simplicity, only one input file will be used.

IDENTIFICATION DIVISION.
PROGRAM-ID.  SAMPLE-FILE-SORT.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
*SORT input file
SELECT ATHLETIC-SHOES-LIST
      ASSIGN TO ....
*SORT output file
   SELECT PRODUCT-LIST
      ASSIGN TO ....
*sort file (SD)
   SELECT PRODUCT-SORT-FILE
      ASSIGN TO ....
DATA DIVISION.
FILE SECTION.
FD  ATHLETIC-SHOES-LIST.
01  A-SHOE-RECORD            PIC X(38).
FD  PRODUCT-LIST.
01  B-SHOE-RECORD            PIC X(38).
SD  PRODUCT-SORT-FILE.
01  SORT-DATA.
    05  MODEL-NAME         PIC X(10).
    05  MODEL-TYPE         PIC X(3).
    05  MODEL-NUMBER       PIC X(3).
    05  STOCK-NUMBER       PIC X(7).
    05  DESIGN-YEAR        PIC 99.
    05  UNIT-COST          PIC 999V99.
    05  UNIT-PRICE         PIC 999V99.
    05  FACTORY-NUM        PIC 999.
WORKING-STORAGE SECTION.
01   FLAGS.
     05   SHOE-LIST-EMPTY  PIC X  VALUE "N".
          88 NO-MORE-SHOE-RECORDS VALUE "Y".
     05   SORT-FILE-EMPTY  PIC X  VALUE "N".
          88 NO-MORE-SORT-RECORDS VALUE "Y".
01   HONG-KONG-NUMBER      PIC 99.
01   TAIWAN-NUMBER         PIC 99.
...
PROCEDURE DIVISION.
PRODUCT-LIST-SORT.
*temporary SD file used by sort
   SORT PRODUCT-SORT-FILE
  *major sort key
     ON ASCENDING  KEY MODEL-TYPE
*minor sort key
     ON DESCENDING KEY MODEL-NUMBER
 *duplicates sorted in the order acquired
      WITH DUPLICATES IN ORDER
         INPUT  PROCEDURE IS WEED-PRODUCT-LIST
         OUTPUT PROCEDURE IS UPDATE-PRODUCT-LIST.

WEED-PRODUCT-LIST SECTION.
OPEN-LIST-FILE.
   OPEN INPUT ATHLETIC-SHOES-LIST.
   PERFORM WEED-LIST
      UNTIL NO-MORE-SHOE-RECORDS.
   CLOSE ATHLETIC-SHOES-LIST.
   GO TO EXIT-WEED-PRODUCT-LIST.

WEED-LIST.
   READ ATHLETIC-SHOES-LIST NEXT
      AT END MOVE "Y" TO SHOE-LIST-EMPTY
      NOT AT END
*stock numbers beginning with "X" are obsolete
*do not RELEASE
        IF STOCK-NUMBER(1:1) = "X" THEN
           NEXT SENTENCE
        ELSE
*otherwise release the record to SORT
           RELEASE SORT-DATA
        END-IF.

EXIT-WEED-PRODUCT-LIST.
   EXIT.

UPDATE-PRODUCT-LIST SECTION.
CREATE-PRODUCT-LIST.
   OPEN OUTPUT PRODUCT-LIST.
   PERFORM UPDATE-RECORD
      UNTIL NO-MORE-SORT-RECORDS.
   CLOSE PRODUCT-LIST.
   GO TO EXIT-UPDATE-PRODUCT-LIST.

UPDATE-RECORD.
   RETURN PRODUCT-SORT-FILE INTO SORT-DATA
      AT END MOVE "Y" TO SORT-FILE-EMPTY
      NOT AT END
         IF FACTORY-NUM = HONG-KONG-NUMBER THEN
             MOVE TAIWAN-NUMBER TO FACTORY-NUM
         END-IF
         WRITE B-SHOE-RECORD FROM SORT-DATA.

EXIT-UPDATE-PRODUCT-LIST.
   EXIT.
Parent topic: Procedure Division Statements


The SORT Statement (for SORT TABLE)

The SORT statement creates a sort file by executing input procedures or by transferring records from another file, sorts the records in the sort file on a set of specified keys, and in the final phase of the sort operation, makes available each record from the sort file, in sorted order to some output procedures or to an output file.

The SORT statement can also be used to sort the elements of a table.

General Formats for Format 1

General Formats for Format 2

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • CALLSORT - specifies the program to be used to handle SORT and MERGE operations.

Syntax Rules for All Formats

  1. A Format 1 SORT statement cannot appear in the declaratives portion of the Procedure Division, or in an input or output procedure associated with a SORT or MERGE statement.

    A Format 2 SORT can appear in the declaratives portion.

  2. Data-name-1 is a KEY data-name and is subject to the following rules:
    1. KEY data-names can be qualified.
    2. The data items identified by KEY data-names must not be variable length items.
    3. KEY data items can be floating-point items.
    4. If the KEY is an external floating-point item, the Compiler treats the data item as character data, rather than numeric data. The sequence in which the records are sorted depends on the collating sequence used.
    5. If the KEY data item is internal floating-point, the records are sorted in numeric order of key values.

Syntax Rules for Format 1

  1. File-name-1 must be described in a Sort-Merge File Description entry in the Data Division.
  2. Data-name-1 is a KEY data-name and is subject to the following rules:
    1. The data items identified by KEY data-names must be described in records associated with file-name-1.
    2. If file-name-1 has more than one record description, then the data items identified by KEY data-names need be described in only one of the record descriptions.
    3. None of the data items identified by KEY data-names can be described by an entry which either contains an OCCURS clause or is subordinate to an entry which contains an OCCURS clause.
    4. If the file referenced by file-name-1 contains variable-length records, all the data items identified by key data-names must be contained within the first x character positions of the record, where x equals the minimum record size specified for the file referenced by file-name-1.
  3. The words THRU and THROUGH are equivalent.
  4. File-name-2 and file-name-3 must be described in file description entries, not in sort-merge file description entries, in the Data Division.
  5. The files referenced by file-name-2 and file-name-3 can reside on the same multiple file reel.
  6. If file-name-3 references an indexed file, the first specification of data-name-1 must be associated with an ASCENDING phrase and the data item referenced by that data-name-1 must occupy the same character positions in its record as the data item associated with the prime record key for that file.
  7. No pair of file-names in the same SORT statement can be specified in the SAME SORT AREA or SAME SORT-MERGE AREA clause. File-names associated with the GIVING phrase cannot be specified in the same SAME clause.
  8. If the GIVING phrase is specified and the file referenced by file-name-3 contains variable-length records, the size of the records contained in the file referenced by file-name-1 must not be less than the smallest record nor larger than the largest record described for file-name-3. If the file referenced by file-name-3 contains fixed-length records, the size of the records contained in the file referenced by file-name-1 must not be larger than the largest record described for the file referenced by file-name-3.

    If the data descriptions of the elementary items that make up these records are not identical, it is the programmer's responsibility to describe the corresponding records in such a manner as to cause equal amounts of character positions to be allocated for the corresponding records.

  9. If the USING phrase is specified and the file referenced by file-name-1 contains variable-length records, the size of the records contained in the file referenced by file-name-2 must not be less than the smallest record nor larger than the largest record described for file-name-1. If the file referenced by file-name-1 contains fixed-length records, the size of the records contained in the file referenced by file-name-2 must not be larger than the largest record described for the file referenced by file-name-1.
  10. Procedure-name-1 represents the name of an input procedure. Procedure-name-3 represents the name of an output procedure.
  11. Procedure-name-1, procedure-name-2, procedure-name-3 and procedure-name-4 must be section-names.

    This restriction is removed.

  12. If you want to specify more than 10 file-names in the USING or GIVING clause, you must use the Compiler directive CALLSORT"EXTSM"; this allows you to specify up to 255 files.

Syntax Rules for Format 2

  1. Data-name-2 can be qualified and must have an OCCURS clause in the data description entry.
  2. The data item referenced by data-name-1 must be the same as the data item referenced by data-name-2, or an entry subordinate to the data item referenced by data-name-2.
  3. Unless data-name-1 and data-name-2 are the same, the data item referenced by data-name-1 must not be described by an entry containing an OCCURS clause. The data item referenced by data-name-1 must not be subordinate to an entry containing an OCCURS clause that is also subordinate to data-name-2.
  4. The KEY phrase can be omitted only if the description of the table referenced by data-name-2 contains a KEY phrase.
  5. If data-name-2 references a data item subordinate to a data item that contains an OCCURS clause, an index-name must be associated with each data item containing an OCCURS clause to which the data item referenced by data-name-2 is subordinate.

Syntax Rules for Format 1

  1. File-name-1 must be described in a Sort-Merge File Description entry in the Data Division.
  2. Data-name-1 is a KEY data-name and is subject to the following rules:
    1. The data items identified by KEY data-names must be described in records associated with file-name-1.
    2. If file-name-1 has more than one record description, then the data items identified by KEY data-names need be described in only one of the record descriptions.
    3. None of the data items identified by KEY data-names can be described by an entry which either contains an OCCURS clause or is subordinate to an entry which contains an OCCURS clause.
    4. If the file referenced by file-name-1 contains variable-length records, all the data items identified by key data-names must be contained within the first x character positions of the record, where x equals the minimum record size specified for the file referenced by file-name-1.
  3. The words THRU and THROUGH are equivalent.
  4. File-name-2 and file-name-3 must be described in file description entries, not in sort-merge file description entries, in the Data Division.
  5. The files referenced by file-name-2 and file-name-3 can reside on the same multiple file reel.
  6. If file-name-3 references an indexed file, the first specification of data-name-1 must be associated with an ASCENDING phrase and the data item referenced by that data-name-1 must occupy the same character positions in its record as the data item associated with the prime record key for that file.
  7. No pair of file-names in the same SORT statement can be specified in the SAME SORT AREA or SAME SORT-MERGE AREA clause. File-names associated with the GIVING phrase cannot be specified in the same SAME clause.
  8. If the GIVING phrase is specified and the file referenced by file-name-3 contains variable-length records, the size of the records contained in the file referenced by file-name-1 must not be less than the smallest record nor larger than the largest record described for file-name-3. If the file referenced by file-name-3 contains fixed-length records, the size of the records contained in the file referenced by file-name-1 must not be larger than the largest record described for the file referenced by file-name-3.

    If the data descriptions of the elementary items that make up these records are not identical, it is the programmer's responsibility to describe the corresponding records in such a manner as to cause equal amounts of character positions to be allocated for the corresponding records.

  9. If the USING phrase is specified and the file referenced by file-name-1 contains variable-length records, the size of the records contained in the file referenced by file-name-2 must not be less than the smallest record nor larger than the largest record described for file-name-1. If the file referenced by file-name-1 contains fixed-length records, the size of the records contained in the file referenced by file-name-2 must not be larger than the largest record described for the file referenced by file-name-1.
  10. Procedure-name-1 represents the name of an input procedure. Procedure-name-3 represents the name of an output procedure.
  11. Procedure-name-1, procedure-name-2, procedure-name-3 and procedure-name-4 must be section-names.

    This restriction is removed.

  12. If you want to specify more than 10 file-names in the USING or GIVING clause, you must use the Compiler directive CALLSORT"EXTSM"; this allows you to specify up to 255 files.

Syntax Rules for Format 2

  1. Data-name-2 can be qualified and must have an OCCURS clause in the data description entry.
  2. The data item referenced by data-name-1 must be the same as the data item referenced by data-name-2, or an entry subordinate to the data item referenced by data-name-2.
  3. Unless data-name-1 and data-name-2 are the same, the data item referenced by data-name-1 must not be described by an entry containing an OCCURS clause. The data item referenced by data-name-1 must not be subordinate to an entry containing an OCCURS clause that is also subordinate to data-name-2.
  4. The KEY phrase can be omitted only if the description of the table referenced by data-name-2 contains a KEY phrase.
  5. If data-name-2 references a data item subordinate to a data item that contains an OCCURS clause, an index-name must be associated with each data item containing an OCCURS clause to which the data item referenced by data-name-2 is subordinate.

General Rules for All Formats

  1. The words ASCENDING and DESCENDING are transitive across all occurrences of data-name-1 until another word ASCENDING or DESCENDING is encountered.
  2. The data items referenced by the specifications of data-name-1 are the key data items which determine the order in which records are returned from the file referenced by file-name-1 or the order in which the table elements are stored after sorting takes place. The order of significance of the keys is the order in which they are specified in the SORT statement, without regard to their association with ASCENDING or DESCENDING phrases.
  3. If the DUPLICATES phrase is specified and the contents of all the key data items associated with one data record or table element are equal to the contents of the corresponding key data items associated with one or more other data records or table elements, the order of return of these records is:
    1. The order of the associated input files as specified in the SORT statement, or by means of an RTS switch. Within a given input file the order is that in which the records are accessed from that file.
    2. The order in which these records are released by an input procedure, when an input procedure is specified.
    3. The relative order of the contents of these table elements before sorting takes place.
  4. If the DUPLICATES phrase is not specified and the contents of all the key data items associated with one data record or table element are equal to the contents of the corresponding key data items associated with one or more other data records or table elements, the order of return of these records or the relative order of the contents of these table elements is undefined.
  5. The collating sequence that applies to the comparison of the nonnumeric key data items specified is determined at the beginning of the execution of the SORT statement in the following order of precedence:
    1. First, the collating sequence established by the COLLATING SEQUENCE phrase, if specified, in the SORT statement.
    2. Second, the collating sequence established as the program collating sequence.

General Rules for Format 1

  1. The SORT statement releases all the records in the file referenced by file-name-2 or released by an input procedure to the file referenced by file-name-1, and returns them to an output procedure, or to the file referenced by file-name-3, in an order determined by the ASCENDING and DESCENDING phrases and the values of the data items referenced by the specifications of data-name-1.
  2. To determine the relative order in which two records are returned from the file referenced by file-name-1, the contents of corresponding key data items are compared according to the rules for comparison of operands in a relation condition, starting with the most significant key data item:
    1. If the contents of the corresponding key data items are not equal and the key is associated with the ASCENDING phrase, the record containing the key data item with the lower value is returned first.
    2. If the contents of the corresponding key data items are not equal and the key is associated with the DESCENDING phrase, the record containing the key data item with the higher value is returned first.
    3. If the contents of the corresponding key data items are equal, the determination is made on the contents of the next most significant key data item.
  3. The execution of the SORT statement consists of three distinct phases as follows:
    1. Records are made available to the file referenced by file-name-1. This is achieved either by the execution of RELEASE statements in the input procedure or by the implicit execution of READ statements for file-name-2. When this phase commences, the file referenced by file-name-2 must not be in the open mode. When this phase terminates, the file referenced by file-name-2 is not in the open mode.
    2. The file referenced by file-name-1 is sequenced. No processing of the files referenced by file-name-2 and file-name-3 takes place during this phase.
    3. The records of the file referenced by file-name-1 are made available in sorted order. The sorted records are either written to the file referenced by file-name-3, or, by the execution of a RETURN statement, are made available for processing by the output procedure. When this phase commences, the file referenced by file-name-3 must not be in the open mode. When this phase terminates, the file referenced by file-name-3 is not in the open mode.
  4. The input procedure can consist of any procedure needed to select, modify or copy the records that are made available one at a time by the RELEASE statement to the file referenced by file-name-1. The range includes all statements that are executed as a result of a transfer of control by CALL, EXIT without the optional PROGRAM or METHOD phrase, GO TO and PERFORM statements in the range of the input procedure. The range of the input procedure must not cause the execution of any MERGE, RETURN or SORT statement.
  5. If an input procedure is specified, control is passed to the input procedure before the file referenced by file-name-1 is sequenced by the SORT statement. The compiler inserts a return mechanism at the end of the last statement in the input procedure and when control passes the last statement in the input procedure, the records that have been released to the file referenced by file-name-1 are sorted.
  6. If the USING phrase is specified, all the records in the file(s) referenced by file-name-2 are transferred to the file referenced by file-name-1. For each of the files referenced by file-name-2 the execution of the SORT statement causes the following actions to be taken:
    1. The processing of the file is initiated. The initiation is performed as if an OPEN statement with the INPUT and the WITH LOCK phrases had been executed .
    2. The logical records are obtained and released to the sort operation. Each record is obtained as if a READ statement with the NEXT and AT END phrases had been executed. If the file referenced by file-name-1 contains fixed-length records, any record in the file referenced by file-name-2 containing fewer character positions than that specified for file-name-1 is space-filled on the right, beginning with the first character position after the last character in the record, when that record is released to the file referenced by file-name-1. If the file referenced by file-name-1 is described with variable-length records, the size of any record written to file-name-1 is the size of that record when it was read from file-name-2 or file-name-3, regardless of the contents of the data item referenced by a RECORD VARYING DEPENDING ON or OCCURS DEPENDING ON clause specified in the File Description entry for file-name-1.
    3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed. This termination is performed before the file referenced by file-name-1 is sequenced by the SORT statement.

      For a relative file, the content of the relative key data item is undefined after the execution of a SORT statement if file-name-2 is not referenced in the GIVING phrase.

      These implicit functions are performed such that any associated USE AFTER EXCEPTION procedures are executed; however, the execution of such a USE procedure must not cause the execution of any statement manipulating the file referenced by file-name-2 or accessing the record area associated with file-name-2.

      The value of the data item referenced by a RECORD VARYING DEPENDING ON clause specified in the File Description entry for file-name-2 is undefined upon completion of the SORT statement.

  7. The output procedure can consist of any procedure needed to select, modify or copy the records that are made available one at a time by the RETURN statement in sorted order from the file referenced by file-name-1. The range includes all statements that are executed as a result of a transfer of control by CALL, EXIT without the optional PROGRAM or METHOD phrase, GO TO and PERFORM statements in the range of the output procedure, as well as all statements in the declarative procedures that are executed as a result of the execution of statements in the range of the output procedure. The range of the output procedure must not cause the execution of any MERGE, RELEASE or SORT statement.
  8. If an output procedure is specified, control passes to it after the file referenced by file-name-1 has been sequenced by the SORT statement. The compiler inserts a return mechanism at the end of the last statement in the output procedure and when control passes the last statement in the output procedure, the return mechanism provides for termination of the sort and then passes control to the next executable statement after the SORT statement. Before entering the output procedure, the sort procedure reaches a point at which it can select the next record in sorted order when requested. The RETURN statements in the output procedure are the requests for the next record.
  9. If the GIVING phrase is specified, all the sorted records are written to the file referenced by file-name-3 as the implied output procedure for the SORT statement. For each of the files referenced by file-name-3, the execution of the SORT statement causes the following actions to be taken:
    1. The processing of the file is initiated. The initiation is performed as if an OPEN statement with the OUTPUT phrase had been executed. This initiation is performed after the execution of any input procedure.
    2. The logical records are returned and written to the file. The records are written as if a WRITE statement without any optional phrases had been executed. If the file referenced by file-name-3 is described with fixed-length records, any record in the file referenced by file-name-1 containing fewer character positions than that specified for file-name-3 is space-filled on the right, beginning with the first character position after the last character in the record, when that record is returned to the file referenced by file-name-3. If the file referenced by file-name-3 is described with variable-length records, the size of any record written to file-name-3 is the size of that record when it was read from file-name-1, regardless of the contents of the data item referenced by a RECORD VARYING DEPENDING ON or OCCURS DEPENDING ON clause specified in the File Description entry for file-name-3.

      For a relative file, the relative key data item for the first record returned has the value 1; for the second record returned, the value 2, and so on. The content of the relative key data item is undefined after execution of a SORT statement.

    3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed.

      These implicit functions are performed such that any associated USE AFTER EXCEPTION procedures are executed; however, the execution of such a USE procedure must not cause the execution of any statement manipulating the file referenced by file-name-3 or accessing the record area associated with file-name-3. On the first attempt to write beyond the externally-defined boundaries of a file, the USE AFTER EXCEPTION procedure, if any, associated with the file is executed; if control is returned as specified by the rules of the USE statement, no additional implicit write operations are executed for that file and the processing of the file is terminated as specified in this part.

    The value of the data item referenced by a RECORDING VARYING DEPENDING ON clause specified in the File Description entry for file-name-1 is undefined upon completion of the SORT statement for which the GIVING phrase is specified.

  10. Segmentation, as defined in the topic Segmentation, can be applied to programs containing the SORT statement. However, the following restrictions apply:
    1. If a SORT statement appears in a section that is not in an independent segment, then any input procedures or output procedures referenced by that SORT statement must be contained either:
      • Totally within non-independent segments
      • Wholly contained in a single independent segment.
    2. If a SORT statement appears in an independent segment, then any input procedures or output procedures referenced by that SORT statement must be contained either:
      • Totally within non-independent segments
      • Wholly within the same independent segment as that SORT statement.
  11. The SORT-RETURN special register is available to SORT runtime elements. It contains a return code of 0 (successful) or 16 (unsuccessful) at the completion of a sort operation. You can set the SORT-RETURN special register to 16 in an error declarative or input/output procedure to terminate a sort operation before all records are processed. The operation is terminated on the next RETURN or RELEASE statement.

General Rules for Format 2

  1. The SORT statement sorts the table referenced by data-name-2 and presents the sorted table in data-name-2 either in the order determined by the ASCENDING or DESCENDING phrases, if specified, or in the order determined by the KEY phrase associated with data-name-2.
  2. To determine the relative order in which the table elements are stored after sorting, the contents of the corresponding key data items are compared according to the rules for comparison of operands in a relation condition, starting with the most significant key data item.
    1. If the contents of the corresponding key data items are not equal and the key is associated with the ASCENDING phrase, the table element containing the key data item with the lower value has the lowest occurrence number.
    2. If the contents of the corresponding key data items are not equal and the key is associated with the DESCENDING phrase, the table element containing the key data item with the higher value has the lowest occurrence number.
    3. If the contents of the corresponding key data items are equal, the determination is based on the contents of the next most significant key data item.
  3. The number of occurrences of table elements referenced by data-name-2 is determined by the rules in the OCCURS clause.
  4. If data-name-2 references a data item which is subordinate to a data item which contains an OCCURS clause, the first or only index-name associated with each such superordinate table must be set to the desired occurrence number before the SORT statement is executed.
  5. If the KEY phrase is not specified, the sequence is determined by the KEY phrase in the Data Description entry of the table referenced by data-name-2.
  6. If the KEY phrase is specified, it overrides any KEY phrase specified in the Data Description entry of the table referenced by data-name-2.
  7. If the key phrase is specified but data-name-1 is omitted, the data item referenced by data-name-2 is the KEY data item.
  8. The sorted table elements of the table referenced by data-name-2 are placed in the table referenced by data-name-2.
  9. SORT procedures should not be invoked by multiple threads simultaneously.

Examples

Examples of using the SORT verb are provided in the topics SORT a File Using Input and Output Procedures and SORT Table Entries.

Parent topic: Procedure Division Statements


START Statement

The Format 1 START statement modifies the current file position for a relative or indexed file. It defines a beginning point for retrieval of records from a file.

The Format 2 START statement identifies the beginning of a transaction.

General Format

START file-name

[KEY IS { EQUAL TO                 } key-name ]
[       { =                        }          ]
[       { GREATER THAN             }          ]
[       { >                        }          ]
[       { NOT LESS THAN            }          ]
[       { NOT <                    }          ]
[       { GREATER THAN OR EQUAL TO }          ]
[       { >=                       }          ]
[       { LESS THAN                }          ]
[       { <                        }          ]
[       { NOT GREATER THAN         }          ]
[       { NOT >                    }          ]
[       { <=                       }          ]
[       { LESS THAN OR EQUAL TO    }          ]

[ WITH SIZE key-size ]

[ INVALID KEY statement-1 ]

[ NOT INVALID KEY statement-2 ]

[ END-START ]

Format 2

START TRANSACTION

Syntax Rules

  1. file-name is the name of a relative or indexed file with sequential or dynamic access mode.
  2. For a relative file, key-name is the name of the RELATIVE KEY for the file. For an indexed file, key-name must either be the name of one of the file's record keys or the name of a data item that starts at the beginning of one of the file's record keys and is not longer than that key.
  3. statement-1 and statement-2 are imperative statements.
  4. key-size is a numeric literal or data item that specifies the maximum number of characters of the key to be examined when setting the new current file position. With this phrase, the program uses only the first n characters of the key to find a matching record. If n is zero or greater than the key size, then the entire key is used. If n is less than zero, the results are undefined.
  5. START and TRANSACTION are required words.

Format 1 General Rules

  1. The START statement changes the current file position for a file in sequential or dynamic access mode. This allows a subsequent READ NEXT or READ PREVIOUS statement to access a different record.
  2. file-name must be open in INPUT or I-O mode when the START statement executes.
  3. If the KEY phrase is missing, the implied operation is EQUAL and the implied key-name is the primary record key for the file (or the RELATIVE KEY for relative files).
  4. The START statement changes the current file position and updates the FILE STATUS data item for file-name. It does not modify the record area for file-name.
  5. The comparison specified by the KEY phrase occurs between the contents of key-name and the records in the file. The current file position is set according to the following rules:
    1. For EQUAL, "=", NOT LESS, NOT "<", GREATER OR EQUAL, ">=", GREATER, and ">", the current file position is set to the record with the smallest key that satisfies the given condition.
    2. For LESS, "<", NOT GREATER, NOT ">", LESS OR EQUAL, and "<=", the current file position is set to the record with the largest key that satisfies the given condition.
  6. For relative files, the comparison uses the relative record numbers of the records in the file and the current value of the RELATIVE KEY data item.
  7. For indexed files, the comparison uses the current value of key-name and the values of the corresponding data area for the records in the file.
  8. If no record is found that satisfies the comparison:
    1. The invalid key condition exists.
    2. The START statement is unsuccessful.
    3. The current file position is undefined.
  9. If the invalid-key condition exists, then one of the following actions occurs:
    1. If the INVALID KEY phrase is specified, statement-1 executes.
    2. Otherwise, if an appropriate USE AFTER EXCEPTION procedure exists, it is executed.
    3. Otherwise, a message is printed and the program halts.
  10. If the NOT INVALID KEY phrase is specified and the START statement is successful, statement-2 executes.
  11. If the START statement is not successful, the current file position and the current Key of Reference are undefined.
Note: The ability to START LESS, "<", NOT GREATER, NOT ">", LESS OR EQUAL, or "<=" is dependent on the host file system. Some file systems cannot process records in reverse order. These KEY phrases are all used to initiate reverse processing. If you execute one of these START statements on a machine that does not support READ PREVIOUS, you will get a file error 9B. You can test whether or not a machine has the ability to process files in this manner with the ACCEPT FROM SYSTEM-INFO verb. See ACCEPT Statement for more information.

Format 2

  1. The START TRANSACTION statement identifies the beginning of a transaction. The following rules describe how transaction management operates with Vision and relative files. For other file systems linked with the runtime, each system's native mechanism for transaction management is invoked. See the Acucorp interface document for the specific file system for more details.
  2. The first START TRANSACTION in a program attempts to open the log file for appending. If the log file does not exist, it is created. START TRANSACTION locks the log file, checks its integrity, then writes a START TRANSACTION notation to the log file and unlocks it.
  3. After the START TRANSACTION, each Vision or relative file update operation is recorded until the next COMMIT or ROLLBACK. At that point, the record of changes is either written to the log file (COMMIT) or discarded (ROLLBACK).
  4. If you compile with the -Fs option, an implied START TRANSACTION is in effect. Therefore, if you use this option, and then issue a START TRANSACTION, the compiler will report an error.

For more information on transaction management, see Transaction Management in the ACUCOBOL-GT User's Guide.

Parent topic: Procedure Division Statements


STOP Statement

The STOP statement terminates or suspends the program.

Format 1

STOP RUN [ {RETURNING} return-value ]
           {GIVING   }

Format 2

STOP literal

Format 3

STOP THREAD [ thread-id ]

Syntax Rules

  1. return-value must be a numeric literal or data item.
  2. literal is a numeric or alphanumeric literal.
  3. thread-id must be a USAGE HANDLE or HANDLE OF THREAD data item.
  4. If a STOP RUN statement is in a consecutive sequence of imperative statements in a sentence, it must be the last statement in that sequence. Any statements after STOP RUN in a sentence will not execute.
  5. The optional word GIVING or RETURNING may be specified before the return value in a STOP RUN statement. In this context, GIVING and RETURNING are merely commentary.

General Rules

  1. A Format 1 STOP RUN statement terminates the program. Any files in the open mode are closed. This is done just as if they were the object of a CLOSE statement with no options.
  2. A Format 2 STOP literal statement suspends execution of the program and passes control to the ACUCOBOL-GT debugger. The debugger prints the literal on the screen before accepting debugging commands. Note, however, that you cannot do source level debugging unless you compiled with the -Zd option and run with the -d option.
  3. If return-value is specified, then it is assigned to the special register RETURN-CODE before the program is exited. This special register is defined as:
    77   RETURN-CODE SIGNED-LONG, EXTERNAL.

    It is implicitly shared by all programs of a run unit and is automatically created by the compiler. The final value of RETURN-CODE is returned to the host operating system when the run unit completes.

  4. A Format 3 STOP THREAD statement cancels (destroys) a thread. thread-id identifies the thread to cancel. If thread-id is omitted, the currently executing thread is canceled. If the current thread is the only thread, the STOP THREAD statement behaves like STOP RUN, except that it shuts down the runtime even if there are nested run units (see CALL RUN).
Parent topic: Procedure Division Statements


STRING Statement

The STRING statement concatenates data items.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format

STRING { {source} ... [DELIMITED BY {delimiter}] } ...
                      [             {SIZE     }]

     INTO destination

   [ WITH POINTER ptr-var ]

   [ ON OVERFLOW statement-1 ]

   [ NOT ON OVERFLOW statement-2 ]

   [ END-STRING ]

Syntax Rules

  1. Source and delimiter are nonnumeric literals or data items with USAGE DISPLAY. The ALL literal construct may not be used.
  2. The compiler allows source to be a numeric literal, in which case it treats source as a string literal, displaying the following Warning at compilation time:
    Warning: Literal is numeric - treated as alphanumeric

    In such cases, leading zeros are stripped from the numeric literal to form the string literal.

  3. Destination is a data item with USAGE DISPLAY. It may not be JUSTIFIED or edited, but may be reference modified.
  4. ptr-var is an integer numeric data item.
  5. statement-1 and statement-2 are imperative statements.
  6. The size of ptr-var must allow it to contain a value one greater than the size of destination.
  7. The DELIMITED phrase may be omitted only immediately before the INTO phrase. If omitted, DELIMITED BY SIZE is implied.

General Rules

  1. The STRING statement concatenates the source values and places the result in destination. There are no limitations (other than available memory) on the number of source items allowed.
  2. The STRING statement moves characters from source to destination according to the rules for alphanumeric to alphanumeric moves. However, no space filling occurs.
  3. The contents of each source item are moved to destination in the order they appear. Data is moved from the left, character by character, until the end of source is reached. The end point of each source item is determined by the DELIMITED phrase according to the following rules:
    1. Transfer stops when the end of source is reached.
    2. Transfer stops when the end of destination is reached.
    3. If delimiter is specified, transfer stops when the characters specified by delimiter are found in source. The delimiter is not included in the characters transferred.
    4. If the SIZE option is used, transfer ends only when the end of source or destination is reached.
    5. When source or delimiter is a figurative constant, it represents a size of one character.
    6. If source is a variable size item, the current size is used to determine the end of source. If the current size is zero characters, no transfer occurs for that source item.
  4. When the POINTER phrase is specified, ptr-var must be set by the program to a value greater than zero before the STRING statement executes. The transfer to destination starts at the character position in destination indicated by ptr-var. The leftmost character of destination is position 1. If no POINTER phrase is used, an implied pointer is created and set to the value 1.
  5. ptr-var (or the implied pointer) is incremented by one for each character transferred to destination. The transfer to destination always occurs at the character position indicated by the current pointer value.
  6. When the STRING statement ends, only those parts of destination referenced during execution change.
  7. Before moving each character to destination, the STRING statement tests the value of ptr-var (or the implied pointer if ptr-var is not specified). If this value is less than one or greater than the size of destination, the overflow condition is set and the following happens:
    1. No more data is transferred to destination.
    2. If the ON OVERFLOW phrase is used, statement-1 executes.
    3. The STRING statement ends.
  8. If the NOT ON OVERFLOW phrase is specified, statement-2 executes after the STRING statement is finished if the overflow condition has not occurred (see general rule 7).
  9. Subscripting for source and delimiter occurs just before the corresponding item is used.
  10. Subscripting for ptr-var and destination occurs just before the STRING statement executes.

Code Example

Assume the following data items:

01  CLAIM-CODE   PIC X(20).  |destination data item,
                             |initialize before use
01  CUSTOMER-ID  PIC X(8).   |source data item
01  ORDER-NO     PIC X(10).  |source data item
01  ORDER-DATE   PIC 9(6).   |source data item
01  STRING-PTR   PIC 99.     |concatenation pointer,
                             |initialize before use

Assume the program assigns the following values before the STRING statement executes:

CLAIM-CODE  = SPACES
(destination item gets space filled)
CUSTOMER-ID = C077/W12
(customer number "/" region code)
ORDER-NO    = W12-A00234
(region code "-" order number)
ORDER-DATE  = 060199
(mmddyy)

Use the STRING statement to concantenate:

STRING ORDER-DATE DELIMITED BY SIZE
       ORDER-NO   DELIMITED BY SIZE
       INTO CLAIM-CODE
END-STRING.
*CLAIM-CODE = "060199W12-A00234    "
*spaces appear at the end of concatenated string
*because CLAIM-CODE was assigned SPACES before the
*STRING concatenation statement executed

Use POINTER to coordinate multiple STRING statements into a common concatenation object.

SET STRING-PTR TO 1.
MOVE SPACES TO CLAIM-CODE.
STRING ORDER-DATE DELIMITED BY SIZE
    INTO CLAIM-CODE
    POINTER STRING-PTR
END-STRING.
*CLAIM-CODE now contains: "060199"
*Reassign the value of STRING-PTR so as to
*eliminate the year digits by overwriting
*positions 5 & 6 in the destination string
SUBTRACT 2 FROM STRING-PTR.
...
*build the remainder of the string
*start by adding a hyphen delimiter,
*add all characters before "/" in CUSTOMER-ID
*add another hyphen delimiter
*add all of ORDER-NO
STRING "-",
       CUSTOMER-ID DELIMITED BY "/",
       "-",
       ORDER-NO    DELIMITED BY SIZE
   INTO CLAIM-CODE
   POINTER STRING-PTR
   ON OVERFLOW
      DISPLAY "Claim-Code OVERFLOW"
   NOT ON OVERFLOW
      PERFORM PROCESS-CLAIM-CODE
END-STRING.
*CLAIM-CODE = "0601-C077-W12-A00234"

Highlights for First-time Users

  1. A clear, concise description of the concatenation transfer process is contained in entry 3 of the preceding General Rules section.
  2. Use DELIMITED BY to concatenate a portion of the source item up to, but not including, the delimiter. The delimiter may be a single character or a string.
  3. Use OVERFLOW to do special processing in the event that the size of the concatenation overflows the destination data item. The OVERFLOW phrase should always be included when an overflow condition is possible.
  4. Use NOT ON OVERFLOW to do special processing in the event that the concatenation succeeds (does not result in an overflow).
  5. Use POINTER to place data into a common destination when concatenation requires multiple STRING statements. See code example 2, above.
  6. The STRING statement does not space fill the target data item. You must initialize the destination data item. For example:
    01 CLAIM-CODE  PIC X(20)  VALUE ALL SPACES.
Parent topic: Procedure Division Statements


SUBTRACT Statement

The SUBTRACT statement performs arithmetic subtraction.

Format 1

SUBTRACT {number} ... FROM { result [ROUNDED] } ...

   [ ON SIZE ERROR statement-1 ]

   [ NOT ON SIZE ERROR statement-2 ]

   [ END-SUBTRACT ]

Format 2

SUBTRACT {number} ... FROM number

     GIVING { result [ROUNDED] } ...

   [ ON SIZE ERROR statement-1 ]

   [ NOT ON SIZE ERROR statement-2 ]

   [ END-SUBTRACT ]

Format 3

SUBTRACT {CORRESPONDING} group-1 FROM group-2 [ROUNDED]
         {CORR         }

   [ ON SIZE ERROR statement-1 ]

   [ NOT ON SIZE ERROR statement-2 ]

   [ END-SUBTRACT ]

Format 4

SUBTRACT TABLE src-table FROM dest-table [ROUNDED]

   [ FROM INDEX src-start TO src-end ]

   [ DESTINATION INDEX dest-start ]

   [ ON SIZE ERROR statement-1 ]

   [ NOT ON SIZE ERROR statement-2 ]

   [ END-SUBTRACT ]

Syntax Rules

  1. number is a numeric literal or elementary numeric data item.
  2. result is an elementary numeric data item or, in Format 2, an elementary numeric edited data item.
  3. group-1 and group-2 are group items containing one or more elementary numeric data items.
  4. statement-1 and statement-2 are imperative statements.
  5. CORR is an abbreviation of CORRESPONDING.
  6. src-table and dest-table are numeric data items that are table elements. The low-order subscript of these items must be omitted. For example, if SRC-1 was an element of a one-dimensional table, you would use SRC-1 in the statement. If SRC-2 was an element of a two-dimensional table, and you wanted to add all the elements in row 2, you would use SRC-2( 2 ).
  7. src-start, src-end and dest-start are numeric literals or data items. These items may not be subscripted.

General Rules

  1. In Format 1, the numbers are added together and the result is then subtracted from each result in turn.
  2. In Format 2, the numbers before the word FROM are added together and the result is subtracted from the number following the word FROM. The results are then moved to each result item.
  3. In Format 3, elementary numeric items in group-1 are subtracted from the corresponding items in group-2. The values are then stored in group-2.
  4. Additional information can be found in Arithmetic Operations, Multiple Receiving Fields, the ROUNDED Option, the SIZE ERROR Option, and the CORRESPONDING Option.
  5. A Format 4 SUBTRACT statement subtracts a range of src-table elements from a range of dest-table elements. The results are stored in dest-table. The first element of the src-table range is subtracted from the first element of the dest-table range, the second element from the second, and so on.
  6. src-start indicates the first element of the source range. If omitted, it defaults to 1. src-end indicates the last element of the range (inclusive). If omitted, it is set to the current upper bound of the source table. In a multidimensional table, the range of elements varies over the innermost OCCURS.
  7. dest-start indicates the first element of the destination range. If omitted, it defaults to 1. Note that the last element of the destination range is dest-start + src-end - 1.
  8. If the SIZE ERROR phrase is used, elements for which the size error condition exists are not updated, while the remaining elements are. If any element gets a size error, then statement-1 executes, otherwise statement-2 executes.
Note: SUBTRACT TABLE is usually substantially faster than the equivalent PERFORM loop. The degree of improvement depends on the size of the range (larger ranges show better improvement). The runtime always performs table boundary checking in SUBTRACT TABLE, even if you do not compile with -Za. The boundaries are tested only at the end points (this is a fast test and there is nothing to be gained from not performing it).
Parent topic: Procedure Division Statements


UNLOCK Statement

The UNLOCK statement removes file record locks.

Format 1

UNLOCK file-name ALL {RECORD }
                     {RECORDS}

Format 2

UNLOCK ALL RECORDS

Format 3

UNLOCK THREAD

Syntax Rule

file-name is a relative or indexed file described in the Data Division.

Format 1 General Rules

  1. file-name must be in the open mode when the UNLOCK statement executes.
  2. When the UNLOCK statement executes, the currently locked records (if any) for file-name are unlocked and made available to other users. The statement has no effect if there are no records locked for file-name.
  3. The UNLOCK statement will fail only when the file is not open. The UNLOCK statement updates the file's associated FILE STATUS data item.
  4. During a transaction, the UNLOCK statement affects only those files for which rollback has not been enabled. In the case where the UNLOCK statement is ineffective because rollback has been enabled for the file, the file status will be set to 00 (success).

Format 2

  1. A Format 2 UNLOCK statement releases all records locked by all of the open files in the program.
  2. A Format 2 UNLOCK always succeeds. No file status data items are updated by this verb and no Declarative procedures are ever executed.

Format 3 General Rules

A Format 3 UNLOCK THREAD statement removes the last lock applied to the thread. If the thread has only one lock (only one LOCK THREAD statement has executed in the thread), then the UNLOCK THREAD statement has the effect of allowing other threads to run. If more than one lock has been applied to the thread, then the UNLOCK THREAD statement removes the last lock applied to the thread and the thread remains locked until it has been unlocked as many time as it was locked. This allows a thread to lock itself, call a subroutine that also locks itself, and remain locked when that subroutine unlocks itself. See the entry in this section for LOCK THREAD.

If the current thread is not locked, the UNLOCK THREAD statement has no effect.

Parent topic: Procedure Division Statements


UNSTRING Statement

The UNSTRING statement separates a data item into one or more receiving fields. Delimiters may be used to specify the ends of fields. Substring values are assigned to unique destination data items.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format

UNSTRING source

   [ DELIMITED BY [ALL] delim

                  [ OR [ALL] delim ] ... ]

     INTO { dest [ DELIMITER in delim-dest ]

                 [ COUNT IN counter ] } ...

   [ WITH POINTER ptr-var ]

   [ TALLYING IN tally-var ]

   [ ON OVERFLOW statement-1 ]

   [ NOT ON OVERFLOW statement-2 ]

   [ END-UNSTRING ]

Syntax Rules

  1. Source is an alphanumeric data item. Source may be reference modified.
  2. dest is a USAGE DISPLAY data item. It may not be edited.
  3. delim is a nonnumeric literal or an alphanumeric data item. The ALL literal construct may not be used.
  4. The compiler allows source and delim to be numeric literals, in which case it treats them as string literals, displaying the following Warning at compile time:
    Warning: Literal is numeric - treated as alphanumeric

    In such cases, leading zeros are stripped from the numeric literal to form the string literal.

  5. delim-dest is an alphanumeric data item.
  6. counter, ptr-var, and tally-var are integer numeric data items.
  7. statement-1 and statement-2 are imperative statements.
  8. ptr-var must be large enough to contain a value one greater than the size of source.
  9. The DELIMITER IN and COUNT IN phrases can appear only if there is a DELIMITED BY phrase.

General Rules

  1. UNSTRING breaks up source into the various dest fields. source is the sending field and dest is the receiving field. Up to 50 dest items are allowed.
  2. counter represents the count of the number of characters within source isolated by the delimiters for the move to dest. This does not include a count of the delimiter characters.
  3. ptr-var represents the relative character position within source to move from. The leftmost position is position "1. If no POINTER phrase is specified, examination begins with the leftmost character position.
  4. tally-var is a counter which is incremented by 1 for each dest item accessed during the UNSTRING operation.
  5. Neither ptr-var nor tally-var is initialized by the UNSTRING statement.
  6. Each delim represents one delimiter. When a delimiter contains two or more characters, all the characters must be present in contiguous positions in source to be recognized as a delimiter. When delim is a figurative constant, it stands for a single nonnumeric literal.
  7. When the ALL phrase is specified, one or more contiguous occurrences of delim in source are treated as if they were only one occurrence for the remaining General Rules. Only one occurrence of delim is moved to delim-dest in this case.
  8. When two or more delimiters are specified, an OR condition exists between them. Each delimiter is compared to the sending field in the order written. If a match occurs, the characters in the sending field are considered to be a single delimiter. No characters in source can be considered a part of more than one delimiter.
  9. When an examination encounters two contiguous delimiters, the current receiving area is space-filled if it is alphabetic or alphanumeric, or zero-filled if it is numeric.
  10. When the UNSTRING statement initiates, the current receiving area is the first dest item. Data is transferred from source to the receiving area according to the following rules:
    1. Examination starts at the character position indicated by ptr-var, or the leftmost position if ptr-var is not specified.
    2. If the DELIMITED BY phrase is specified, the examination proceeds left-to-right until a delimiter is encountered. If the DELIMITED BY phrase is not specified, the number of characters examined is equal to the size of the receiving area. The sign character of the receiving item (if any) is not included in the size. If the end of source is encountered before the delimiting condition is met, the examination stops with the last character of source.
    3. The characters examined (excluding the delimiting characters, if any) are treated as an elementary alphanumeric item. These characters are moved to the current receiving field according to the rules for the MOVE statement, including space filling.
    4. If the DELIMITER IN phrase is specified, the delimiting characters are moved to delim-dest as if they were the alphanumeric source of a MOVE statement. If the delimiting condition is the end of source, then delim-dest is space-filled.
    5. If the COUNT IN phrase is specified, the number of characters examined (excluding the delimiter) is moved to counter as if the count were the numeric source of a MOVE statement.
    6. If the DELIMITED BY phrase is specified, the source item is further examined beginning with the first character to the right of the delimiter found. If the DELIMITED BY phrase is not specified, the source item is further examined beginning with the character to the right of the last character examined.
    7. The current receiving area is then set to the next dest item and the cycle specified in steps (b) through (g) is repeated until either all the characters in source are examined or there are no more dest items.
  11. The ptr-var (if any) is incremented by 1 for each character in source examined.
  12. An overflow condition occurs in either of the following situations:
    1. The value of ptr-var is less than one or greater than the size of source when the UNSTRING statement starts.
    2. During execution, all dest items have been acted upon and source contains unexamined characters.
  13. When the overflow condition exists, statement-1 (if any) executes and the UNSTRING statement terminates.
  14. If statement-2 is specified, it executes after the UNSTRING statement has finished if the overflow condition has not occurred.

Code Examples

Use UNSTRING to decompose strings containing multiple data elements. For example, a string data item might contain a person's name, using commas to separate the name fields: last-name,first-name,middle-initial. Using UNSTRING, and specifying "," (comma) as the delimiter, you could separate the name string into three data items, each containing an element of the full name.

Example 1

Assume the following data items:

01  CUSTOMER-NAME    PIC X(40)  VALUE ALL SPACES.
01  LAST-NAME        PIC X(25)  VALUE ALL SPACES.
01  FIRST-NAME       PIC X(14)  VALUE ALL SPACES.
01  MIDDLE-I         PIC X      VALUE ALL SPACES.
{ . . . }
PROCEDURE DIVISION.
{ . . . }
 DISPLAY 'Enter name: LAST,FIRST,MIDDLE-INITIAL'.
 DISPLAY 'Use a comma to separate each name entry'.
    ACCEPT CUSTOMER-NAME.

{ . . . }

UNSTRING CUSTOMER-NAME
   DELIMITED BY ","
   INTO LAST-NAME,   |characters to first comma
        FIRST-NAME,  |characters to second comma
        MIDDLE-I     |gets only the first character
                     |of the remaining string.  No
                     |overflow is raised.
                     |See general rule 12.
   ON OVERFLOW
      DISPLAY 'OVERFLOW on UNSTRING'
END-UNSTRING.

For code examples 2 and 3 assume the following data items:

01  COLOR-LIST  PIC X(22) VALUE "RED:BLUE/GREEN  YELLOW".
01  COLOR-1     PIC X(6)  VALUE ALL SPACES.
01  COLOR-2     PIC X(6)  VALUE ALL SPACES.
01  COLOR-3     PIC X(6)  VALUE ALL SPACES.
01  COLOR-4     PIC X(6)  VALUE ALL SPACES.
01  DELIMIT-1   PIC X(3)  VALUE ALL SPACES.
01  COUNT-1     PIC 9     VALUE 0.

Example 2

UNSTRING COLOR-LIST
   DELIMITED BY ":" OR "/" OR ALL SPACE
*ALL SPACE treats contiguous spaces
*as one delimiter.
   INTO COLOR-1,
        COLOR-2,
        COLOR-3,
        COLOR-4
END-UNSTRING.
*COLOR-1 = "RED   "
*COLOR-2 = "BLUE  "
*COLOR-3 = "GREEN "
*COLOR-4 = "YELLOW"

Example 3

MOVE 0 TO COUNT-1.

UNSTRING COLOR-LIST
   DELIMITED BY ":" OR "/" OR ALL SPACE
*DELIMIT-1 and COUNT-1 will hold only
*the values associated with COLOR-1.
   INTO COLOR-1
         DELIMITER IN DELIMIT-1
         COUNT IN COUNT-1,
         COLOR-2,
         COLOR-3,
         COLOR-4
   ON OVERFLOW
      DISPLAY "overflow: unstring colors"
   NOT ON OVERFLOW
*do when UNSTRING succeeds.
      PERFORM SORT-COLORS
END-UNSTRING.
*COLOR-1 = "RED   "
*COLOR-2 = "BLUE  "
*COLOR-3 = "GREEN "
*COLOR-4 = "YELLOW"
*DELIMIT-1 = ":  "
*COUNT-1 = 3 count-1 holds the number of characters in RED

Example 4

When the string does not contain delimiters between the data elements, but the size and position of each string data element is known, the string can be deconstructed without a DELIMITED BY phrase.

Assume the following data items:

01  COLOR-LIST   PIC X(7) VALUE "REDBLUE".
01  COLOR-1      PIC X(3) VALUE ALL SPACES.
01  COLOR-2      PIC X(4) VALUE ALL SPACES.
{ . . . }
PROCEDURE DIVISION.
{ . . . }
UNSTRING COLOR-LIST
   INTO COLOR-1,
*first substring must be three characters.
        COLOR-2
*second substring must be four characters.
END-UNSTRING.
*COLOR-1 = "RED"
*COLOR-2 = "BLUE"

Example 5

Use POINTER and a PERFORM loop to extract and process string elements.

Assume the following data items:

01  COLOR-LIST       PIC X(21)  VALUE "RED BLUE GREEN YELLOW".
01  COLOR-LIST-SIZE  PIC 999.
01  COLOR-1          PIC X(6)   VALUE SPACES.
01  STRING-PTR       PIC 99.
01  FLAGS.
    05  COLOR-STRING-EMPTY   PIC X VALUE "N".
        88 NO-MORE-COLORS          VALUE "Y".
{ . . . }
PROCEDURE DIVISION.
{ . . . }
*string pointer must be initialized
MOVE 1 TO STRING-PTR.
SET COLOR-LIST-SIZE TO SIZE OF COLOR-LIST.
PERFORM PROCESS-COLOR UNTIL NO-MORE-COLORS.
{ . . . }
PROCESS-COLOR.
   UNSTRING COLOR-LIST
      DELIMITED BY ALL SPACE
      INTO COLOR-1
      POINTER STRING-PTR
      ON OVERFLOW
*An OVERFLOW condition will be raised every time
*through the loop, except when extracting the last
*substring.  When the overflow is the result of
*having unexamined characters at the end of the
*input string, take no action.  When the overflow
*is due to the pointer value exceeding the length
*of the string, set COLOR-STRING-EMPTY.
         IF STRING-PTR > COLOR-LIST-SIZE THEN
            MOVE "Y" TO COLOR-STRING-EMPTY
         END-IF
*process the value
   PERFORM STORE-COLOR-1
*initialize COLOR1 before fetching the next color
   MOVE SPACES INTO COLOR-1
   END-UNSTRING.

Highlights for first-time users

  1. UNSTRING is best suited for separating string components that share a common delimiter. The delimiter must not appear as an element of the components' values.
  2. DELIMITED BY is optional. If it's omitted, each destination data item is completely filled. Effectively, the respective size of each destination data item is the respective delimiter.
  3. Assignment to the destination data item is done with an implied MOVE. The MOVE operation will truncate the substring or space fill the destination data item, as required. Truncation of the substring, or space filling of the destination data item resulting from the implicit MOVE, does not raise an OVERFLOW condition.
  4. The OVERFLOW condition is raised if: (a) all destination data items are used and characters still remain in the source data item; or (b) POINTER is used and the value of the pointer variable is less than 1 or greater than the length of the source data item.
  5. Use the ALL option to treat contiguous occurrences of a delimiter, such as spaces, as a single occurrence.
  6. Use DELIMITER IN to place the delimiting character(s) of the current substring into the named data item.
  7. Use the COUNT IN option to save the length of the current substring into the named data item.
  8. Use TALLYING to tally the number of destination data items assigned by the UNSTRING statement.
  9. Use the POINTER option to specify a numeric holder (ptr-var) for the current position in the source data item. By pre-assigning a value to the pointer variable you can start the examination of the source data item at any position in the string. ptr-var is incremented by one for each character in the source data item that is examined. POINTER allows the programmer to use multiple UNSTRING statements to process the source data item. Note, however, that an overflow condition will be raised if the value of ptr-var is less than the length of the string when the UNSTRING statement terminates.

    You must initialize the tallying and pointer variables or results are unpredictable.

  10. Use the OVERFLOW option to do special processing when the UNSTRING process does not examine every character in the source data item, or when the pointer variable has a value of less than one or more than the length of the source data item. When the overflow condition exists, the associated imperative statement (if any) executes and program execution continues immediately after the UNSTRING statement.
  11. Use the NOT ON OVERFLOW option to do special processing when the UNSTRING statement processes the entire source data item.
Parent topic: Procedure Division Statements


USE Statement

The USE statement specifies procedures for handling Input/Output errors and other errors. USE is a comprehensive error handling construct. The USE statement locates all error routines centrally within the DECLARATIVES section of the PROCEDURE DIVISION when used to specify I/O error handling routines. USE is a valuable supplement to the AT END and INVALID KEY I/O error handling phrases.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

Format 1

USE AFTER STANDARD {EXCEPTION} PROCEDURE ON { {file}...   }
                   {ERROR    }              { INPUT       }
                                            { OUTPUT      }
                                            { I-O         }
                                            { EXTEND      }
                                            { TRANSACTION }

Format 2

USE AFTER STANDARD {EXCEPTION} PROCEDURE ON OBJECT
                   {ERROR    }

Format 3

USE FOR REPORTING ON {index-file} ...

Format 4

USE AFTER STANDARD ERROR PROCEDURE ON file-name GIVING
       data-name-1  [ data-name-2 ]

Format 5

USE { active-x-control-item }
    { com-object-item  }
    { property-1 [ ( param-1 ... ) ]
      [ :: property-2 [ ( param2 ... ) ] ] ... }
    { statement }
[END-USE]

Format 6

USE AT PROGRAM {START}
               {END  }

Syntax Rules

  1. file is a file described in the Data Division. It may be a sort file.
  2. index-file is a file described in the Data Division. It must be an indexed file.
  3. data-name-1 is an eight-byte data item of the type PICTURE 9(8) USAGE DISPLAY. A compile-time error message is generated if data-name-1 is not of that type.
  4. data-name-2 may be of any type but must be at least as long as the file buffer. A compile-time error message is generated if this is not the case.
  5. When used, a USE statement must immediately follow a section header in the Declaratives portion of the Procedure Division and must appear in a sentence by itself. The remainder of the section must consist of zero, one, or more paragraphs that define the exception procedure to be used.
  6. ERROR and EXCEPTION are interchangeable.
  7. The INPUT, OUTPUT, I-O, and EXTEND and TRANSACTION phrases may each be specified in only one USE statement in a Procedure Division.
  8. A particular file may not appear in more than one Format 1 USE statement in a program.
  9. A particular index-file may not appear in more than one Format 3 USE statement in a program.
  10. Active-x-control-item and com-object-item must be USAGE HANDLE OF class-name, where class-name is defined as an ActiveX control or an COM object in SPECIAL-NAMES.
  11. statement is an imperative statement.
  12. property-1 is the name of a property of the ActiveX control or COM object. property-1 must not be a write-only property.
  13. property-2 is the name of a property of the ActiveX control or COM object which is the value of property-1. property-2 must not be a write-only property.
  14. param-1 and param-2 are literals, data items, or numeric expressions.

General Rules

  1. The USE statement is not executed; it merely defines the conditions calling for the execution of the USE procedure. The USE procedure consists of all the paragraphs contained in the section the USE statement appears in.
  2. The procedure associated with a Format 1 USE statement is executed after the unsuccessful execution of an I/O operation unless an AT END or INVALID KEY phrase takes precedence. It also executes during an I/O operation when a duplicate key error is detected for a file open for BULK-ADDITION. The following rules apply:
    1. If file is specified, the associated procedure is executed when an unsuccessful I/O operation occurs for that file.
    2. If the INPUT phrase is specified, the procedure executes when the OPEN operation is unsuccessful for a file being opened in INPUT mode, unless that file is specified by file in another USE statement. This also applies to a file being opened for INPUT.
    3. The OUTPUT, I-O, and EXTEND phrases operate as described in rule b), except that they apply to files opened in the corresponding mode.
    4. If TRANSACTION is specified, the procedure executes when an error occurs during a START TRANSACTION, COMMIT, ROLLBACK, or call to C$RECOVER. Note that the status-code will be in the TRANSACTION-STATUS variable.
  3. After the USE procedure executes, control is returned to the next executable statement after the I/O statement that caused the USE procedure to execute. If the USE procedure executed during a file operation, the control returns to that file operation instead.
  4. Within a USE procedure, no statement may be executed that would result in the execution of a USE procedure that has been invoked but has not yet returned.
  5. The procedure associated with a Format 2 USE statement is executed after an object exception occurs.
  6. After the Format 2 USE statement executes, control is returned to the next executable statement after the statement that caused the USE procedure to execute.
  7. A Format 2 USE statement executes when an object exception is "raised" during a CREATE, DISPLAY, MODIFY, INQUIRE or calls to C$GETEVENTDATA, C$SETEVENTDATA, C$GETEVENTPARAM or C$SETEVENTPARAM.

    An object exception can either be raised by the object itself or by the runtime to indicate that an error has occurred. ActiveX controls and COM objects are currently the only objects that can raise exceptions. These are called COM exceptions in Microsoft terminology.

    Information about an object exception can be retrieved with the C$EXCEPINFO routine.

  8. Within a Format 2 USE statement, no statement can be executed that would result in the execution of a USE procedure that has been invoked but has not yet returned.
  9. A Format 3 USE statement executes at periodic times for files opened with the BULK-ADDITION phrase. The purpose of this procedure is to report to the user the progress of writing keys for a large number of records written to indexfile.
  10. When a Format 1 USE procedure executes due to a duplicate key error for a file open with BULK-ADDITION, no file I/O statements may be executed. This also applies to Format 3 USE procedures. In addition, no run units may be started or stopped, and the program containing the declarative may not perform an EXIT PROGRAM.
  11. A Format 4 USE procedure is valid only when the -Cv option is in effect. When an error handler introduced by this statement is invoked, the runtime puts special error codes into the eight-byte data item data-item-1. See IBM DOS/VS COBOL Conversions, in Transitioning to ACUCOBOL-GT for complete information on DOS/VS COBOL compatibility mode.
  12. If data-name-2 is present, when the error handler is invoked, it will also load data-name-2 with the contents of the file buffer. ACUCOBOL-GT always loads data-name-2, and if the data-item is larger than the file buffer, the excess bytes at the right end are left unchanged.
  13. The Format 5 USE verb sets up a context for more efficient coding and processing of MODIFY and INQUIRE statements that operate on ActiveX controls or objects. It allows you to execute a series of MODIFY and INQUIRE statements on a specified object without respecifying the object. For example, to change a number of different properties on a single object, place the MODIFY statement within the USE statement, referring to the object once instead of referring to it in each MODIFY clause.
    USE MyChart Legend::Font
MODIFY    ^Size = 10
          ^Name = "Courier"
          ^Bold = 1
END-USE
  14. param-1 is the first parameter passed when getting the value of property-1.
  15. param-2 is the first parameter passed when getting the value of property-2.
  16. Runtime errors announced as Use of a LINKAGE data item not passed by the caller and Passed USING item smaller than corresponding LINKAGE item belong to the class of intermediate runtime errors that, upon occurrence, call installed error procedures.
  17. When placed in a program's Declarative section, a Format 6 USE statement creates a START or END procedure for the program. Each program may contain no more than one START and one END procedure. Every program in a run unit may contain such procedures.
    1. A START procedure executes immediately before the first normal COBOL statement in the Procedure Division when the program is in its initial state. The START procedure executes only once regardless of the number of times the program is entered, until the program is returned to its initial state (e.g. via CANCEL). A START procedure executes regardless of which entry point is used to start the program when a program contains multiple entry points (see the ENTRY statement).
    2. An END procedure executes immediately before a program is placed into its initial state or it is about to leave memory, providing the program has been entered at least once. An END procedure executes before open files are closed as part of the shutdown process.
    3. You can call the C$EXITINFO library routine from an END procedure to obtain information about the program exit. For example, you can determine if the exit is the result of a STOP RUN or a fatal error. Refer to Appendix I in ACUCOBOL-GT Appendices for detailed information about this library routine.
    4. It is normal for an END procedure to execute when the program that contains it is inactive. For example, if a program is canceled, its END procedure will execute when the program is otherwise inactive. For this reason, an END procedure should not reference data passed to the program through Linkage. This data will not be defined in many cases.
    5. END procedures are executed during abnormal shutdown when possible. However, certain operating system errors (such as a fatal memory error) cannot be caught in some operating environments, and in these cases the END procedures will not be able to execute. If a fatal error occurs during an END procedure, that procedure stops, but other unprocessed END procedures execute where possible.
    6. When multiple END procedures execute (e.g. STOP RUN when several programs are in memory), the order of their execution is arbitrary.

Code Example

PROCEDURE DIVISION.
DECLARATIVES.
NAMED-FILE-IO-ERROR-HANDLING SECTION.
   USE AFTER STANDARD ERROR PROCEDURE ON
      REPORT-FILE.
NAMED-FILE-IO-ERROR-HANDLER.
{ . . . }
IO-INPUT-ERROR-HANDLING SECTION.
   USE AFTER STANDARD ERROR PROCEDURE ON INPUT.
IO-INPUT-ERROR-HANDLER.
{ . . . }
IO-OUTPUT-ERROR-HANDLING SECTION.
   USE AFTER STANDARD ERROR PROCEDURE ON OUTPUT.
IO-OUTPUT-ERROR-HANDLER.
{ . . . }
END DECLARATIVES.
MAIN-PROGRAM SECTION.
{ . . . }

Highlights for first-time users

  1. The USE statement can be used to handle program file I/O errors. USE is not executed, but, rather, describes the conditions under which the contained procedures are to be executed.
  2. The USE statement is located in a DECLARATIVES section in a program's PROCEDURE DIVISION. The USE statement may contain one or many error handling procedures. Each USE statement may specify a file, set of files or OPEN mode for which the enclosed procedures apply. No file name or OPEN mode (INPUT, OUTPUT, I-O, EXTEND) may be named more than once in the DECLARATIVES section of that PROCEDURE DIVISION. If an I/O error raises an ambiguity between an error handling procedure that names the file and an error handling procedure with a matching OPEN mode description, the procedure naming the file takes precedence.
  3. Detecting and handling I/O errors:

    Every I/O operation returns a two-digit status code that indicates the result of the operation. A status code that begins with 0 indicates a successful operation. A status code that begins with a number other than 0 indicates that the I/O operation failed.

    When an I/O operation takes place, the file status code is set and sent back to the calling statement.

    • If the status code begins with the number 1, an AT END error has occurred.
    • If the status code begins with a 2, an INVALID KEY error has occurred.
    • If the programmer has included a corresponding AT END or INVALID KEY phrase in the I/O statement (where supported), the respective clause is executed and the program, if not terminated, continues after the I/O statement that raised the error.
    • If the status code begins with any other number (except "0"), or there is no AT END or INVALID KEY phrase, the system searches for an applicable USE statement in the DECLARATIVES section.
    • If an applicable USE statement is found, the search stops, the applicable error handler is executed, and if the program has not been terminated, program execution continues after the I/O statement that raised the error.
    • If no applicable USE statement is found, the runtime determines the action. Usually, a message is presented and the program halts.

    For more about file status and the AT END, and INVALID KEY phrases, see AT END and INVALID KEY Phrases.

  4. The set of I/O verbs that return a status code includes: CLOSE, DELETE, OPEN, READ, REWRITE, START, UNLOCK, WRITE.
  5. There are five different standards specifying the values of file status codes: ANSI85, ANSI74, DG ICOBOL, VAX COBOL, and IBM DOS/VS COBOL. By default, ACUCOBOL-GT uses the ANSI85 status code standard. You can change to any of the alternate standards by changing the setting of the FILE_STATUS_CODES runtime configuration variable.

    The ANSI85 (default) definitions of the major error classes are:

    Status Code | Status
    0x | I/O operation succeeded
    1x | AT END ERROR
    2x | INVALID KEY ERROR
    3x | PERMANENT ERROR
    4x | LOGIC ERROR
    9x | ACUCOBOL-GT DEFINED
    Note: Some errors such as 30, 98, and 9D also return additional information in the secondary or tertiary file codes. These may be retrieved with the library routine C$RERR.
Parent topic: Procedure Division Statements


WAIT Statement

The WAIT statement synchronizes operations between threads.

General Format

WAIT FOR { THREAD thread-ID         }
         { LAST THREAD              }
         { ANY THREAD               }

Remaining phrases are optional, can appear in any order.

{ BEFORE TIME timeout }
{ TEST ONLY }

THREAD IN thread-2

SIZE IN size-item

STATUS IN status-item
[ ON EXCEPTION statement-1 ]

[ NOT ON EXCEPTION statement-2 ]

[ END-WAIT ]

Syntax Rules

  1. thread-ID and thread-2 are usage HANDLE or HANDLE OF THREAD data items. Thread-2 may not be indexed or reference modified.
  2. timeout is a numeric literal or data item.
  3. size-item is a numeric data item. It may not be indexed or reference modified.
  4. status-item is a two-character group item, PIC XX, or PIC 99 data item. It may not be indexed or reference modified.
  5. statement-1 and statement-2 are any imperative statements.

General Rules

  1. The WAIT statement waits for a thread to terminate or send a message. The thread waited on is determined as follows:
    1. FOR THREAD thread-ID specifies the thread identified by thread-ID.
    2. FOR LAST THREAD specifies the last thread. See Thread Fundamentals in the ACUCOBOL-GT User's Guide for a discussion of the last thread.
    3. FOR ANY THREAD specifies all threads. The first one to terminate or send a message satisfies the WAIT statement.
  2. If a message is available when the WAIT statement executes, then WAIT statement finishes immediately.
  3. When BEFORE TIME is specified, the WAIT statement will time-out after the specified (timeout) number of hundredths of seconds. If the WAIT statement times out before receiving a message, it terminates with an exception condition and it does not modify thread-2 or size-item. If timeout is zero, then the WAIT statement times-out immediately if a message is not available. Specifying TEST ONLY is equivalent to specifying a timeout value of zero.
  4. If the thread waited for does not exist or terminates before sending a message, then the WAIT statement terminates with an exception condition and does not modify size-item. Such a condition is reflected in the status code placed in status-item. Note that the test occurs before the time-out test in the case that timeout is zero or TEST ONLY is specified.
  5. The WAIT statement places the thread ID of the sending or terminating thread in thread-2.
  6. The size of the message sent is placed in size-item. The size is expressed in standard character positions (bytes).
  7. The status of the WAIT statement is placed in status-item. The following values are possible (these approximate the standard file status codes):
    "00" | Success - message received
    "10" | Exception - thread does not exist or terminated
    "99" | Exception - timed-out
  8. If the WAIT statement is successful (as indicated in rule 7), it executes statement-1. If an exception condition exists, it executes statement-2 instead.
Parent topic: Procedure Division Statements


WRITE Statement

The WRITE statement adds a record to a file.

Format 1

WRITE record-name [ FROM source ]

   [ {BEFORE} ADVANCING { number [LINE ] } ]
     {AFTER }           {        [LINES] }
                        {      PAGE      }
                        { mnemonic-name  }         (HP COBOL)

   [ AT {END-OF-PAGE} statement-1 ]
        {EOP        }

   [ NOT AT {END-OF-PAGE} statement-2 ]
            {EOP        }

   [ END-WRITE ]

Format 2

WRITE record-name [ FROM source ]

   [ INVALID KEY statement-1 ]

   [ NOT INVALID KEY statement-2 ]

   [ END-WRITE ]

Format 3

WRITE record-name [ FROM source ] WITH NO { CONTROL    }
                                          { CONVERSION }

Syntax Rules

  1. record-name is the name of a record associated with a file described in the File Section of the Data Division. The associated file may not be a sort file.
  2. source is a data item or literal. It may not share any storage area with record-name.
  3. number is an integer numeric literal or data item. It must be non-negative.
  4. Mnemonic-name is a user-defined word that may be assigned to Special Names in the ADVANCING clause of the WRITE statement. (This is a feature of HP COBOL. See Special-Names Paragraph in Transitioning to ACUCOBOL-GT for more information.
  5. statement-1 and statement-2 are imperative statements.
  6. A Format 1 WRITE statement must be associated with a sequential file. A Format 2 WRITE statement must be associated with a relative or indexed file.
  7. The words END-OF-PAGE and EOP are equivalent.
  8. If the END-OF-PAGE phrase is used, the file description entry containing record-name must have a LINAGE clause.
  9. The ADVANCING PAGE and END-OF-PAGE phrases cannot both be used in the same WRITE statement.
  10. A Format 3 WRITE statement must be associated with a sequential file.

General Rules

  1. The file associated with record-name must be open when the WRITE statement executes. For sequential access mode files, the file must be open in the OUTPUT or EXTEND modes. For random and dynamic access mode files, the file must be open in the OUTPUT, I-O, or EXTEND mode.
  2. The WRITE statement adds the contents of record-name to the file according to the following rules:
    1. For sequential access mode files, the record is added to the end of the file. If the file is indexed, the record's primary key must contain a value that is larger than all of the primary keys currently in the file. If a relative file has a RELATIVE KEY data item specified for it, the record number of the added record is moved to this data item when the WRITE statement completes.
    2. For random and dynamic access mode files, the record is inserted into the file according to its key value. For relative files, the record is placed at the record number described by the file's RELATIVE KEY data item. For indexed files, the values of record-name's key items are used to insert the record in the file to maintain the correct key orderings.
  3. If the FROM phrase is used, the source item is moved to record-name according to the rules of the MOVE statement before record-name is written to the file.
  4. The FILE STATUS data item is updated by the WRITE statement.
  5. Some sequential files are considered to be print files. A print file has page positioning information specified in it along with the record data. A file with the PRINT option of the ASSIGN clause specified for it is a print file. A file that is referenced by any WRITE statement that contains an ADVANCING phrase is also a print file.
  6. If the ADVANCING phrase is specified, the file is treated as a print file and the following occurs:
    1. If number is positive, the representation of the printed page is advanced a number of lines equal to that value.
    2. If number is zero, no repositioning of the representation of the printed page is performed.
    3. If the PAGE phrase is used, the representation of the printed page is advanced to the next page boundary. If the associated file has a LINAGE clause specified for it, this is done by spacing the appropriate number of lines. Otherwise this is done by physically advancing the device to the top of the next physical page.
    4. If the BEFORE phrase is specified, the page advancement specified occurs after record-name is added to the file.
    5. If the AFTER phrase is used, the page advancement specified occurs before record-name is added to the file.
    6. If no ADVANCING phrase is specified, and the file is a print file, AFTER ADVANCING 1 LINE is implied.
  7. The invalid key condition exists when any of the following occur:
    1. A relative file record is written in the random or dynamic access modes, and the record number indicated by the RELATIVE KEY data item is already used by another record.
    2. An indexed file record is written and the primary key value in record-name is used by another record already in the file.
    3. An alternate key value in record-name is already being used by a record in the file, and that alternate key does not allow for duplicates.
  8. When the invalid-key condition exists, the WRITE statement is unsuccessful and the following occurs:
    1. If the INVALID KEY phrase is specified, statement-1 executes; otherwise
    2. If an appropriate USE AFTER EXCEPTION procedure exists, that error procedure executes; otherwise
    3. A message is printed and the program halts.
  9. If the WRITE statement is successful and the NOT INVALID KEY phrase is specified, statement-2 is executed.
  10. The ordering of indexed file keys for alternate keys that allow duplicates is the order in which the records are written to the file for those duplicated values.
  11. The current file position is not modified by the WRITE statement.
  12. The logical size of the record written to the file is the size of record-name. The physical size may be different due to physical characteristics of the file.
  13. If the file associated with record-name has a LINAGE clause, the following rules apply:
    1. An automatic page overflow condition occurs when the WRITE statement cannot be fully accommodated in the page body. This occurs when the WRITE statement would cause the LINAGE-COUNTER to exceed the number of lines in the page body specified by the LINAGE clause. When this happens, the line is presented before or after (depending on the phrase used) the device is positioned to the first line of the next logical page.
    2. An end-of-page condition occurs when the WRITE statement causes printing or spacing in the footing area of the page body. This occurs when the WRITE statement causes the LINAGE-COUNTER to equal or exceed the value of the FOOTING phrase of the associated LINAGE clause. If no FOOTING phrase is present, then the end-of-page condition cannot occur. Note that the end-of-page condition does not imply any automatic device positioning.
    3. If the END-OF-PAGE phrase is used, then statement-1 executes if either an automatic page overflow or an end-of-page condition exists. Otherwise statement-2 executes (if specified).
  14. The WRITE statement removes trailing spaces from record-name if the file specifies trailing-space suppression. For related information, see:
    • General Rule number 7b (above)
    • section File-Control Paragraph
    • section File Types under Text Records
    • STRIP_TRAILING_SPACES
  15. A Format 3 WRITE statement writes the data in record-name to its file without any additional carriage-control information. In addition, if the NO CONVERSION option is specified, no trailing spaces are removed from the record, even if they otherwise would be. Use this to send information to devices when carriage-control is inappropriate, for example, when sending a form to a laser printer.
  16. Depending on the host environment, it is possible that records written with a Format 3 WRITE statement cannot later be retrieved with a READ statement.

For configuration variables related to the WRITE statement, see:

  • COMPRESS_FACTOR
  • FLUSH_COUNT
  • FLUSH_ON_ACCEPT
  • MIN_REC_SIZE
  • PAGE_EJECT_ON_CLOSE
  • STRIP_TRAILING_SPACES
  • V_BUFFERS
  • V_BUFFER_DATA
Parent topic: Procedure Division Statements


XML GENERATE Statement

The XML GENERATE statement generates an XML document from existing, COBOL data (i.e., it translates COBOL data to XML format). It is an implementation of the IBM Enterprise COBOL verb of the same name and is provided to simplify IBM migrations; however, any customer wishing to write XML data can use this verb. See Working with Non-Vision Data in A Guide to Interoperating with ACUCOBOL-GT for additional information on working with XML data.

General Format

XML GENERATE identifier-1 FROM identifier-2 [COUNT [IN] identifier-3]
  [[ON] EXCEPTION imperative-statement-1]
  [NOT [ON] EXCEPTION imperative-statement-2]
  [END-XML]

Syntax Rules

  1. identifier-1 is the receiving area for the XML document. It must be an alphanumeric data item, and it must not overlap identifier-2 or identifier-3.
  2. identifier-1 must be large enough to contain the generated XML document. Typically, it should be from five to eight times the size of identifier-2, depending on the length of the data-name or data-names within identifier-2. If identifier-1 is not large enough, an error condition exists at the end of the XML GENERATE statement.
  3. identifier-2 is the source of the data to be converted to an XML document. It must not overlap with identifier-1 or identifier-3.
  4. identifier-3 is a numeric data item. It may not overlap with identifier-1 or identifier-2.

General Rules

  1. XML GENERATE ignores certain data items when they are specified by identifier-2. These include:
    • Unnamed elementary data items or elementary FILLER items.
    • Slack bytes inserted for SYNCHRONIZED items.
    • Data items subordinate to identifier-2 that are described by the REDEFINES clause, or that are subordinate to such a redefining item.
    • Data items subordinate to identifier-2 that are described with the RENAMES clause.
    • Group data items whose subordinate data items are all ignored.
  2. All data items specified by identifier-2 that are not ignored as defined above must satisfy the following conditions:
    • Each elementary data item must either have class alphabetic, alphanumeric, numeric, or be an index data item.
    • There must be at least one such elementary item.
    • Each non-FILLER data name must be unique within any immediately superordinate group data item.
  3. The COUNT IN phrase indicates that the count of generated XML characters (in bytes) should be stored in identifier-3, the data count field. identifier-3 must be an integer data item without the symbol "P" in its picture string. identifier-3 must not overlap identifier-1 or identifier-2.
  4. ON EXCEPTION phrase. When an error occurs during XML document generation, an exception condition exists. An example of this is when identifier-1 is not large enough to contain the generated XML document. In this case, XML generation stops and the content of the receiver, identifier-1, is undefined. If the COUNT IN phrase was specified, identifier-3 contains the number of character positions that were generated. This can range from zero to the length of identifier-1.

    If the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1. If it is not specified, NOT ON EXCEPTION phrases are ignored, and control is transferred to the end of the XML GENERATE statement.

    At termination of an XML GENERATE statement, special register XML-CODE contains either 0, indicating successful completion of XML generation, or a non-zero error code, indicating that an exception occurred during XML generation. Following are the possible exception codes that you may encounter:

    Code | Description
    400 | The receiver was too small to contain the generated XML document. The COUNT IN data item, if specified, contains the count of character positions that were actually generated.
    600 â€“ 699 | Internal error. Please report the error to your customer support analyst.
  5. NOT ON EXCEPTION phrase. If no exception conditions arise during generation of the XML document, control is passed to imperative-statement-2, if specified, or to the end of the XML GENERATE statement. If an ON EXCEPTION phrase is specified, it is ignored. Special register XML-CODE contains a zero after the XML GENERATE statement has finished executing.
  6. The END-XML phrase is an explicit scope terminator that delimits the scope of both XML GENERATE and XML PARSE statements. With END-XML, conditional XML GENERATE or XML PARSE statements can be nested in other conditional statements. Conditional XML GENERATE or XML PARSE statements specify the ON EXCEPTION or NOT ON EXCEPTION phrase.

    The scope of a conditional XML GENERATE or XML PARSE statement is terminated by:

    • An END-XML phrase at the same level of nesting
    • A separator period

Operation of XML GENERATE

Eligible elementary data items in identifier-2 are converted to character format. (See Data conversion and Data trimming for details.) Only the first definition of each storage area is processed. Redefinitions are not included, nor are data items that are effectively defined by the RENAMES clause.

Once the data content is converted, it is inserted as element character content in XML markup. The XML element names are derived from the data-names in identifier-2. (See Element naming for more information.) The names of group items that contain the selected elementary items are retained as parent elements. No extra white space is inserted to make the generated XML more readable. An XML declaration is not generated.

If the receiving area specified by identifier-1 is not large enough to contain the resulting XML document, an error condition arises. See the ON EXCEPTION phrase, General Rule #4, for details.

CAUTION:
If identifier-1 is longer than the generated XML document, only the initial part of identifier-1 changes. The rest of identifier-1 contains the data that was present before this execution of the XML GENERATE statement. To avoid referring to that data, either initialize identifier-1 to spaces before the XML GENERATE statement or specify the COUNT IN phrase.

Use the COUNT IN phrase to determine the total number of character positions, in bytes, that were generated. identifier-3 will then contain this information after XML GENERATE executes. You can use identifier-3 as a reference modification length field to refer to the part of identifier-2 that contains the generated XML document.

After execution of the XML GENERATE statement, special register XML-CODE contains either zero, indicating successful completion, or a non-zero exception code.

Please note that the XML PARSE statement also uses special register XML-CODE. Therefore, if you code an XML GENERATE statement in the processing procedure of an XML PARSE statement, save the value of XML-CODE before that XML GENERATE statement executes and restore the saved value after the XML GENERATE statement terminates.

Data Conversion

How elementary data items are converted to character format depends on the type of data item:

  • Alphabetic, alphanumeric, alphanumeric-edited, external floating-point, and numeric-edited items are not converted.
  • Fixed-point numeric data items are converted as if they were moved to a numeric-edited item that has:
    • An explicit decimal point, if the numeric item has at least one decimal position
    • The same number of decimal positions as the numeric item
    • A leading '-' picture symbol if the data item is signed and has an S in its PICTURE clause

    For COMPUTATIONAL-5 (COMP-5) binary data items, the number of integer positions depends on the number of '9' symbols in the picture character string. If the data item has one to four '9' picture symbols, the number of integer positions is five minus the number of decimal places. If the data item has five to nine '9' picture symbols, the number of integer positions is ten minus the number of decimal places. If the data item has 10 to 18 '9' picture symbols, the number of integer positions is 20 minus the number of decimal places.

    All other fixed-point numeric data items will have as many integer positions as the numeric item, but with at least one integer position.

  • Internal floating-point data items are converted as if they were moved to a data item as follows:
    • For COMP-1: an external floating-point data item with PICTURE -9.9(8)E+99
    • For COMP-2: an external floating-point data item with PICTURE -9.9(17)E+99 (illegal because of the number of digit positions)
  • Index data items are converted as if they were declared USAGE COMP-5 PICTURE S9(9). After conversion, leading and trailing spaces and leading zeroes are removed, as described under Data trimming.

After conversion, if a data item contains characters that are illegal in XML, the value in the data item before conversion or trimming is represented in hexadecimal, and an element tag name with the prefix "hex." is substituted for the regular tag name. For example, if data item Customer-Name is found at run time to contain LOW-VALUES, the XML element tag name 'hex.Customer-Name' is used instead of the normal 'Customer-Name', and the content is represented as a string of pairs of zero digits.

Any remaining instances of the five characters & (ampersand), ' (apostrophe), > (greater-than sign), < (less-than sign), and " (quotation mark) are converted into the equivalent XML references '&amp;', '&apos;', '&gt;', '&lt;', and '&quot;', respectively.

Data Trimming

Data values are trimmed after they are converted to character format. (Conversion is described under Data conversion.) Values converted from signed numeric values have their leading space removed if the value is positive. Values converted from numeric items have leading zeroes eliminated (after any initial minus sign). This is up to but not including the digit immediately before the actual or implied decimal point. Trailing zeroes after a decimal point are retained. For example:

  • 012.340 becomes -12.340.
  • 0000.45 becomes 0.45.
  • 0013 becomes 13.
  • 0000 becomes 0.

Character values from alphabetic, alphanumeric data items have either trailing or leading spaces removed, depending on whether the corresponding data items have left or right justification, respectively--left being the default. Trailing spaces are removed from values whose corresponding data items do not specify the JUSTIFIED clause. Leading spaces are removed from values whose data items do specify the JUSTIFIED clause. If a character value consists solely of spaces, all spaces are removed but one.

Element Naming

The element tag names in the XML documents generated from identifier-2 are derived from the name of the data item specified by identifier-2 and from any eligible data-names that are subordinate to identifier-2. The following rules apply:

  • The exact mixed-case spelling of data-names from the data description entry is retained. The spellings from any references to that data item (for example, in an OCCURS DEPENDING ON clause) are not used.
  • data-names beginning with a digit are prefixed by an underscore. For example, the data-name 4C becomes XML tag name _4C.
  • Names of data items that contain characters that are illegal in XML version 1.0 are prefixed by hex., and the content itself is expressed in hexadecimal.

Nested XML GENERATE Statements

When a given XML GENERATE statement appears as imperative-statement-1 or imperative-statement-2, or as part of imperative-statement-1 or imperative-statement-2 of another XML GENERATE statement, that given XML GENERATE statement is a nested XML GENERATE statement.

Nested XML GENERATE statements are considered to be matched XML GENERATE and END-XML combinations proceeding from left to right. For this reason, when END-XML phrases are encountered, they are matched with the nearest preceding XML GENERATE statements that have not already been terminated.

Parent topic: Procedure Division Statements


XML PARSE Statement

The XML PARSE statement parses an XML document so that it can be processed by the COBOL program. It is an implementation of the IBM Enterprise COBOL verb of the same name and is provided to simplify IBM migrations; however, any customer wishing to read XML data can use this verb.

XML PARSE is similar to C$XML in that you parse (read) the XML data and move it into the appropriate working storage item. The difference is that with C$XML, if you know that the data lies in a certain element or attribute, you can retrieve that attribute directly. With XML PARSE, you set up a processing procedure so that when you encounter a new element or attribute, you can specify how and where you want to store that data.

See Working with Non-Vision Data in A Guide to Interoperating with ACUCOBOL-GT for additional information on working with XML data.

General Format

XML PARSE identifier-1 PROCESSING PROCEDURE [IS]
  procedure-name-1 [THROUGH procedure-name-2]
                    THRU
  [[ON] EXCEPTION imperative-statement-1]
  [NOT [ON] EXCEPTION imperative-statement-2]
  [END-XML]

Syntax Rules

  1. identifier-1 is an alphanumeric data item that contains the XML document character stream.
  2. The PROCESSING PROCEDURE phrase specifies the name of a procedure to handle the various events that the XML parser generates.
  3. procedure-name-1, procedure-name-2 names a section or paragraph in the procedure division. Procedure-name-1 and procedure-name-2 must not name a procedure name in a declarative section.
  4. procedure-name-1 specifies the first (or only) section or paragraph in the processing procedure.
  5. procedure-name-2 specifies the last section or paragraph in the processing procedure.

General Rules

  1. For each XML event, the parser transfers control to the first statement of the procedure named procedure-name-1. Control is always returned from the processing procedure to the XML parser. The point from which control is returned is determined as follows:
    • If procedure-name-1 is a paragraph name and procedure-name-2 is not specified, the return is made after the last statement of the procedure-name-1 paragraph is executed.
    • If procedure-name-1 is a section name and procedure-name-2 is not specified, the return is made after the last statement of the last paragraph in the procedure-name-1 section is executed.
    • If procedure-name-2 is specified and it is a paragraph name, the return is made after the last statement of the procedure-name-2 paragraph is executed.
    • If procedure-name-2 is specified and it is a section name, the return is made after the last statement of the last paragraph in the procedure-name-2 section is executed.

    This procedure is the same as if the COBOL program executed the PERFORM verb on the same paragraph(s).

  2. procedure-name-1 and procedure-name-2 must define a consecutive sequence of operations to execute, beginning at the procedure named by procedure-name-1 and ending with the execution of the procedure named by procedure-name-2.

    If there are two or more logical paths to the return point, then procedure-name-2 can name a paragraph that consists of only an EXIT statement; all the paths to the return point must then lead to this paragraph.

  3. The processing procedure consists of all the statements at which XML events are handled. The range of the processing procedure includes all statements executed by CALL, EXIT, GO TO, GOBACK, MERGE, PERFORM, and SORT statements that are in the range of the processing procedure, as well as all statements in declarative procedures that are executed as a result of the execution of statements in the range of the processing procedure.

    The range of the processing procedure must not cause any GOBACK or EXIT PROGRAM statement to be executed, except to return control from a program to which control was passed by a CALL statement that is executed in the range of the processing procedure.

    The range of the processing procedure must not cause an XML PARSE statement to be executed, unless the XML PARSE statement is executed in an outermost program to which control was passed by a CALL statement that is executed in the range of the processing procedure.

    A program executing on multiple threads can execute the same XML statement or different XML statements simultaneously. However, the compiler generates LOCK THREAD / UNLOCK THREAD statements immediately before or after the XML PARSE statement, so effectively only a single thread is executing during the entire execution of the XML PARSE.

    The processing procedure can terminate the run unit with a STOP RUN statement.

    For more details about the processing procedure, see Control Flow.

  4. ON EXCEPTION phrase. The ON EXCEPTION phrase specifies imperative statements to be executed when an exception condition is raised by XML PARSE.

    An exception condition exists when the XML parser detects an error while processing an XML document. The parser first signals the exception by passing control to the processing procedure with special register XML-EVENT containing the word, 'EXCEPTION'. The parser also provides a numeric error code in special register XML-CODE. Error codes are listed in the special register section.

    An exception condition also exists when the processing procedure sets XML-CODE to -1 before returning to the parser for a normal XML event. This is done by the user to deliberately terminate parsing. In this case, the parser does not signal an XML exception event. If the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1. If it is not specified, NOT ON EXCEPTION phrases are ignored, and control is transferred to the end of the XML PARSE statement. Special register XML-CODE contains the numeric error code for the XML exception or -1 after execution of the XML PARSE statement.

    If the processing procedure handles the XML exception event and sets XML-CODE to zero before returning control to the parser, the exception condition no longer exists. If no other unhandled exceptions occur prior to the termination of the parser, control is transferred to imperative-statement-2 of the NOT ON EXCEPTION phrase, if specified.

  5. NOT ON EXCEPTION phrase. The NOT ON EXCEPTION phrase specifies imperative statements to be executed when no exception conditions exist at the conclusion of XML PARSE processing.

    When no exception conditions exist, control is transferred to imperative-statement-2, if specified, or to the end of the XML PARSE statement. If an ON EXCEPTION phrase is specified, it is ignored. Special register XML-CODE contains a zero after the XML PARSE statement has finished executing.

  6. END-XML phrase. The END-XML phrase is an explicit scope terminator that delimits the scope of both XML GENERATE and XML PARSE statements. With END-XML, conditional XML GENERATE or XML PARSE statements can be nested in other conditional statements. Conditional XML GENERATE or XML PARSE statements specify the ON EXCEPTION or NOT ON EXCEPTION phrase.

    The scope of a conditional XML PARSE statement is terminated by:

    • An END-XML phrase at the same level of nesting
    • A separator period

  7. Parsing XML documents one segment at a time. You can parse XML documents by passing one segment (or record) of XML text at a time. Processing very large documents, or processing XML documents that reside in a file, are two possible major applications.

    One can parse an XML document a segment at a time by initializing the parse data item to the first segment of the XML document, and then executing the XML PARSE statement. The parser processes the XML text and returns XML events to your processing procedure as usual.

    At the end of the text segment, the parser signals an END-OF-INPUT XML event, with XML-CODE set to zero. If there is another segment of the document to process, in your processing procedure move the next segment of XML data to the parse data item, set XML-CODE to one, and return to the parser. To signal the end of XML segments to the parser, return to the parser with XML-CODE still set to zero.

    The length of the parse data item is evaluated for each segment, and determines the segment length.

  8. Variable-length segments. If the XML document segments are variable length, specify a variable-length item for the parse data item. For example, for variable-length XML segments, you can define the parse data item as one of the following items:

    • A variable-length group item that contains an OCCURS DEPENDING ON clause.
    • A reference-modified item.
    • An FD record that specifies the RECORD IS VARYING DEPENDING ON clause, where the depending-on data item is used as the length in a reference modifier or ODO object for the FD record.

Nested XML PARSE Statements

When a given XML PARSE statement appears as imperative-statement-1 or imperative-statement-2, or as part of imperative-statement-1 or imperative-statement-2 of another XML PARSE statement, that given XML PARSE statement is a nested XML PARSE statement.

Nested XML PARSE statements are considered to be matched XML PARSE and END-XML combinations proceeding from left to right. For this reason, when END-XML phrases are encountered, they are matched with the nearest preceding XML PARSE statements that have not already been terminated.

Control Flow

When the XML parser receives control from an XML PARSE statement, it analyzes the XML document and transfers control to procedure-name-1 at the following points:

  • At the start of the parsing process
  • When a document fragment is found
  • When the parser detects an error in parsing the XML document
  • At the end of processing the XML document

Control returns to the XML parser when the end of the processing procedure is reached.

The exchange of control between the parser and the processing procedure continues until either:

  • The entire XML document has been parsed, ending with the END-OF-DOCUMENT event.
  • The parser detects an exception and the processing procedure does not reset special register XML-CODE to zero prior to returning to the parser.
  • The processing procedure terminates parsing deliberately by setting XML-CODE to -1 prior to returning to the parser.

Then, the parser terminates and returns control to the XML PARSE statement with the XML-CODE special register containing the most recent value set by the parser or the processing procedure.

The XML-CODE, XML-EVENT, and XML-TEXT special registers contain information about each XML event passed to the processing procedure. The content of XML-CODE is defined during and after execution of an XML PARSE statement. The contents of all other XML special registers are undefined outside the range of the processing procedure.

For normal XML events, XML-CODE contains zero when the processing procedure receives control. For exception events, XML-CODE contains one of the exception codes specified later in this document. XML-EVENT is set to the event name, such as START-OF-DOCUMENT. XML-TEXT contains the piece of the document corresponding to the event, as described in XML-EVENT. For more information about the XML special registers, see "Special Registers" below.

For all kinds of XML events, if XML-CODE is not zero when the processing procedure returns control to the parser, the parser terminates without a further EXCEPTION event. Setting XML-CODE to -1 before returning to the parser for an event other than EXCEPTION forces the parser to terminate with a user-initiated exception condition. For some EXCEPTION events, the processing procedure can handle the event, then set XML-CODE to zero to force the parser to continue, although subsequent results are unpredictable. When XML-CODE is zero, parsing continues until the entire XML document has been parsed or an exception condition occurs.

Special Registers

XML-CODE

When used in the XML PARSE statement, the XML-CODE special register is used to communicate status between the XML parser and the processing procedure.

For each event, the XML parser sets XML-CODE before transferring control to the processing procedure. It also does this at parser termination. You can reset XML-CODE before returning control to the parser.

The XML-CODE special register has the implicit definition:

01  XML-CODE PICTURE S9(9) USAGE BINARY VALUE 0.

When the XML parser encounters an XML event, it sets XML-CODE and then passes control to the processing procedure. For all events except EXCEPTION, XML-CODE contains zero when the processing procedure receives control.

For an EXCEPTION event, the parser sets XML-CODE to an exception code that indicates the nature of the exception. Exception codes are listed below. Note that these are different than IBM COBOL's exception codes.

XML PARSE Exception Code | Description
101 | Out of memory
102 | Syntax error in XML
103 | No elements
104 | Invalid token
105 | Unclosed token
106 | Partial character
107 | Tag mismatch
108 | Duplicate attribute
109 | Junk after the doc element
110 | Error in the parameter entity reference
111 | Undefined entity
112 | Recursive entity reference
113 | Asynchronous entity
114 | Bad character reference
115 | Binary entity reference
116 | Attribute external entity reference
117 | Misplaced XML processing instructions
118 | Unknown encoding
119 | Incorrect encoding
120 | Unclosed cdata section
121 | External entity handling required
122 | Not standalone
123 | unexpected error
124 | entity declared in wrong place

If you want the parser to terminate after normal events without causing an EXCEPTION, set XML-CODE to -1 before returning control to the parser. If you set XML-CODE to any other value, results are undefined. IBM customers should note that ACUCOBOL-GT ignores XML-CODEs of 0. This is because unlike the IBM COBOL parser, there are no exceptions that allow continuation of parsing in ACUCOBOL-GT. Our XML parser cannot continue once it has detected an error.

In ACUCOBOL-GT, no further events are returned from the parser. Control is passed to the statement that you specify in the ON EXCEPTION phrase, or to the end of the XML PARSE statement if you did not code an ON EXCEPTION phrase.

When the parser returns control to the XML PARSE statement, XML-CODE contains the most recent value set either by the parser or by the processing procedure.

XML-EVENT

The XML parser uses the XML-EVENT special register to communicate event information to the processing procedure. The information that is communicated is identified in the XML PARSE statement. Before passing control to the processing procedure, the XML parser sets XML-EVENT to the name of the XML event, as described in Table 1 at the end of this topic.

XML-EVENT has the implicit definition:

01  XML-EVENT USAGE DISPLAY PICTURE X(30) VALUE SPACE.

XML-EVENT cannot be used as a receiving data item.

XML-TEXT

The XML-TEXT special register is defined during XML parsing to contain document fragments that are of class alphanumeric. XML-TEXT is an elementary alphanumeric data item of the length of the contained XML document fragment. The length of XML-TEXT can vary from 0 through 16,777,215 bytes. There is no equivalent COBOL data description entry.

The parser sets XML-TEXT to the document fragment associated with an event before transferring control to the processing procedure when the operand of the XML PARSE statement is an alphanumeric data item.

Use the LENGTH function for XML-TEXT to determine the number of bytes that XML-TEXT contains.

XML-TEXT cannot be used as a receiving item.

XML event (content of XML-EVENT) | Content of XML-TEXT
ATTRIBUTE-CHARACTERS | The value within quotes or apostrophes. If the value includes an entity reference, this can be a substring of the attribute value.
ATTRIBUTE-NAME | The attribute name; the string to the left of "=".
COMMENT | The text of the comment between the opening character sequence "<!--" and the closing character sequence "-->".
CONTENT-CHARACTER | The single character corresponding with the predefined entity reference in the element content.
CONTENT-CHARACTERS | The element content between start and end tags. This can be a substring of the element content if the content contains an entity reference or another element.
DOCUMENT-TYPE-DECLARATION | The entire document type declaration including the opening and closing character sequences, "<!DOCTYPE" and ">".
ENCODING-DECLARATION | The value, between quotes or apostrophes, of the encoding declaration in the XML declaration.
END-OF-CDATA-SECTION | Always contains the string "]]>".
END-OF-DOCUMENT | Null, zero-length.
END-OF-ELEMENT | The name of the end element tag or empty element tag.
EXCEPTION | The part of the document successfully scanned, up to and including the point at which the exception was detected. Special register XML-CODE contains the unique error code identifying the exception.
PROCESSING-INSTRUCTION-DATA | The rest of the processing instruction, not including the closing sequence, "?>", but including trailing, not leading, white space characters.
PROCESSING-INSTRUCTION-TARGET | The processing instruction target name that occurs immediately after the processing instruction opening sequence, "<?".
STANDALONE-DECLARATION | The value between quotes or apostrophes of the stand-alone declaration in the XML declaration
START-OF-CDATA-SECTION | Always contains the string "<![CDATA[".
START-OF-DOCUMENT | The entire document.
START-OF-ELEMENT | The name of the start element tag or empty element tag, also known as the element type.
VERSION-INFORMATION | The value between quotes or apostrophes of the version declaration in the XML declaration.
Parent topic: Procedure Division Statements


Appendices

  • Appendix A. Specifications
  • Appendix B. Reserved Words
  • Appendix C. Changes Affecting Previous Versions
  • Appendix D. Compiler Error Messages
  • Appendix E. File Status Codes
  • Appendix F. Intrinsic Functions
  • Appendix G. Reserved for Future Use
  • Appendix H. Configuration Variables
  • Appendix I. Library Routines
Parent topic: ACUCOBOL-GT Version 10.2.0 Documentation Set


Appendix A. Specifications

  • COBOL Modules
  • Limits and Ranges
  • Extensions
  • Restrictions
Parent topic: Appendices


COBOL Modules

ACUCOBOL-GT is an ANSI-85 COBOL compiler and runtime system (ANSI X3.23-1985 and the ANSI X3.23-1989 supplement). ANSI COBOL is divided into a series of required and optional modules, each of which has various levels of implementation. ACUCOBOL-GT conforms to the following levels for each of the required modules (range of levels in parentheses):

Nucleus (1-2) | Level 2
Sequential I-O (1-2) | Level 2
Relative I-O (0-2) | Level 2
Indexed I-O (0-2) | Level 2
Inter-Program Communication (1-2) | Level 2
Sort-Merge (0-1) | Level 1
Source Text Manipulation (0-2) | Level 2
Segmentation (0-2) | Level 1

ACUCOBOL-GT does not support the optional modules: Report Writer, Communication, or Debug.

The following sections summarize various extensions and limitations ACUCOBOL-GT has with respect to the standard.

Parent topic: Appendix A. Specifications


Limits and Ranges

ACUCOBOL-GT has the following limits:

Maximum Program Size: (compilation unit) | 16 MB code, 2 GB data
Maximum Program Size: (run unit) | Limited only by machine memory
Maximum Record Size: | 64 MB (67,108,864)
Maximum Number of Records Written (Vision files only): | 4,294,967,295 Note: The unique record counter and percentage indicator (towards the limit) is display in vutil -info -x.
Number of Indexed Keys: | Primary + 119 alternates
Number of Segments per Key: | 16
Maximum Indexed Key Size: | 250 bytes
Maximum Sort Key Size: | 32767 bytes
Maximum Number Sort Keys: | 255
Maximum duplicate keys: | No limit (Vision)
Maximum File Size: | Host system dependent Logical limit: 128TB, if Vision Version 4, 5 or 6 is used; for all other Vision versions, the logical limit is 2048 MB
Maximum Data Item Size - Alphanumeric: - Numeric: - Edited | 2 GB 31 digits (default is 18, but can be set to 31 by using the -Dd31 compiler option. See Data Storage Options of the ACUCOBOL-GT User's Guide for details). 255 bytes
Maximum Table Indexes: | 15
Maximum Open Files/Process: | 32767
Maximum Literal Size: | 32767 characters
Maximum Paragraph Size: | 32767 bytes
Maximum Picture String: | 100 Characters
SPECIAL-NAMES Switches: | 26
Maximum number of OCCURS: | 2,147,483,647
Maximum recursive CALL depth: | 32767
Maximum number of parameters in a CHAIN statement | 50
Maximum number in a PERFORM number TIMES statement | 2,147,483,647
Maximum number of Linkage Section level-01 data items per program | 255
Maximum number of ENTRY points per program | 65536
Maximum number of characters in an alphanumeric data item used in a DISPLAY statement | 2048
Parent topic: Appendix A. Specifications


Extensions

ACUCOBOL-GT contains many extensions to the ANSI standard. These are summarized below:

  • Terminal-oriented source format
  • Compile-time modification of source by Identification Area flags
  • The Identification Division is optional
  • IS RESIDENT PROGRAM clause
  • An index item may subscript a table other than the one it is associated with. Index data items may be used any place a numeric data item is allowed
  • Apostrophes may be used to delimit nonnumeric literals. Hexadecimal literals are allowed
  • A procedure name may be the same as a data item name
  • Initial paragraph name not required
  • Paragraph names allowed in Area B
  • Multiple-word SOURCE-COMPUTER and OBJECT-COMPUTER names
  • Data Division FILE SECTION header is optional
  • The word ALPHABET is optional when you are declaring an alphabet-name in the SPECIAL-NAMES paragraph
  • The ASSIGN TO clause may have a data item specified for the external file name. Also, the external file name is optional in the clause
  • An optional device type may be specified in an ASSIGN clause
  • WITH COMPRESSION, WITH ENCRYPTION added to ASSIGN clause
  • LINE and BINARY options in ORGANIZATION clause
  • COLLATING SEQUENCE clause
  • COMPRESSION CONTROL clause
  • LOCK MODE clause
  • LENGTH OF clause for data literals
  • RECORD-POSITION clause for data items
  • RESERVE clause with the NO or ALTERNATE options
  • Split key specification for indexed files
  • FILE STATUS clause for sort files
  • REDEFINES can reference an item that is itself a redefinition of an area
  • Additional SPECIAL-NAMES clauses: CONSOLE IS CRT, CRT STATUS, CURSOR IS, EVENT STATUS, and NUMERIC SIGN SEPARATE
  • SEGMENT-LIMIT clause (level 2 segmentation feature)
  • VALUE OF FILE-ID clause
  • USAGE COMP-1, COMP-2, COMP-3, COMP-4, COMP-5, COMP-6, COMP-N, COMP-X, FLOAT, DOUBLE, and HANDLE
  • USAGE types:
    SIGNED-SHORT | UNSIGNED-SHORT
    SIGNED-INT | UNSIGNED-INT
    SIGNED-LONG | UNSIGNED-LONG
  • ADDRESS OF phrase in arithmetic expressions
  • Tables may contain up to 15 dimensions
  • A PICTURE string may contain up to 100 characters
  • Level 78 constant names
  • WHEN SET TO FALSE phrase for level 88 condition-names. A FALSE phrase added to the SET statement
  • SCREEN SECTION
  • SCREEN SECTION BEFORE, AFTER, and EXCEPTION embedded procedures
  • SCREEN SECTION EVENT procedures
  • IS SPECIAL-NAMES phrase in record description entry
  • CHAINING phrase added to Procedure Division header
  • Non-display data items may be specified in a NUMERIC class condition
  • USE statements may reference sort files
  • RETURN-CODE special register
  • ACCEPT with screen control
  • ACCEPT FROM SYSTEM-INFO, TERMINAL-INFO, INPUT STATUS, LINE NUMBER, COMMAND-LINE, ESCAPE KEY, CENTURY-DATE, CENTURY-DAY, STANDARD OBJECT, and WINDOW HANDLE
  • ACCEPT FROM SCREEN
  • ACCEPT CONTROL statement
  • ACCEPT ALLOWING messages phrase
  • ACCEPT external-form-item statement
  • ADD TABLE statement
  • CALL RUN statement
  • CALL PROGRAM statement
  • CALL THREAD statement
  • Literals allowed in the USING portion of a CALL statement. Also, non-level 01 group items may be listed in the USING phrase
  • BULK-ADDITION phrase for OPEN statement
  • BY VALUE phrase for CALL statement
  • OMITTED/NULL phrase for CALL statement
  • NOT ON OVERFLOW accepted for CALL statement
  • ALL option for CANCEL statement
  • CHART option for CANCEL statement
  • CHAIN statement
  • CLOSE WINDOW statement
  • COMMIT statement
  • COPY RESOURCE statement
  • CREATE statement
  • DELETE FILE statement
  • DESTROY statement
  • DISPLAY with screen control
  • DISPLAY SUBWINDOW/WINDOW statement
  • DISPLAY FLOATING WINDOW statement
  • DISPLAY SCREEN statement
  • DISPLAY LINE statement
  • DISPLAY BOX statement
  • DISPLAY UPON WINDOW TITLE statement
  • DISPLAY UPON COMMAND-LINE statement
  • DISPLAY INITIAL WINDOW statement
  • DISPLAY INDEPENDENT WINDOW statement
  • DISPLAY TOOL-BAR statement
  • DISPLAY control-type statement
  • DISPLAY MESSAGE BOX statement
  • DISPLAY external-form-item statement
  • DRAW CHART statement
  • ENTER CHART DATA statement
  • ENTRY statement
  • GOBACK statement
  • INQUIRE CONTROL statement
  • INQUIRE WINDOW statement
  • LOCK THREAD statement
  • TRAILING option on INSPECT statement
  • MODIFY statement
  • NEXT SENTENCE statement
  • WITH LOCK and ALLOWING phrases added to OPEN statement
  • MASS-UPDATE option on OPEN statement
  • WITH NO LOCK and ALLOWING phrases on READ statement
  • PERFORM THREAD statement
  • PREVIOUS option on READ statement
  • Literal allowed in FROM phrase of REWRITE and WRITE statements
  • SEND message statement
  • RECEIVE message statement
  • SET CHART ATTRIBUTE statement
  • SET FILE-PREFIX statement
  • SET ENVIRONMENT statement
  • SET EXCEPTION statement
  • SET TO ADDRESS OF statement
  • SET TO SIZE OF statement
  • SET HANDLE statement
  • SET THREAD statement
  • SET WINDOW statement
  • STOP THREAD statement
  • SUBTRACT TABLE statement
  • LESS THAN and LESS THAN OR EQUAL options on START statement
  • UNLOCK statement
  • DECLARATIVE procedures may reference procedures outside of DECLARATIVES
  • Recursive CALLs
  • Dynamically determined SORT keys
  • EXIT PERFORM, EXIT PARAGRAPH and EXIT SECTION
  • ROLLBACK clause for LOCK MODE phrase, on SELECT statement in FILE-CONTROL paragraph
  • COMMIT statement may indicate end of transaction and cause changes to be written to transaction log file
  • ROLLBACK statement
  • SET statement with ADDRESS OF clause sets address of linkage data item to specified value
  • START TRANSACTION statement
  • SUPPRESS clause for the COPY statement
  • USE active_x_control_item and USE ole_object_item statements
  • USE FOR REPORTING statement
  • UNLOCK THREAD statement
  • WAIT statement
Parent topic: Appendix A. Specifications


Restrictions

The current version of ACUCOBOL-GT has the following restrictions with respect to the standard. Many of these will be lifted in future versions of ACUCOBOL-GT.

  • The Procedure Division is required.
  • The ENTER statement is unsupported (obsolete feature).
  • The RERUN clause is unsupported (obsolete feature).
  • The COMMON clause of the PROGRAM-ID is unsupported.
  • Nested source programs are unsupported.
Parent topic: Appendix A. Specifications


Appendix B. Reserved Words

  • Conventions
  • Reserved Word List
Parent topic: Appendices


Conventions

This appendix lists all the reserved words used by ACUCOBOL-GT. Words that are reserved by ACUCOBOL-GT but not by the 1985 standard are indicated as follows:

(a) | Indicates that the word is reserved by a special feature of ACUCOBOL-GT
(b) | Indicates that the word is reserved by IBM DOS/VS. They are treated as reserved words by ACUCOBOL-GT only if you compile with the -Cv compiler option.
(h) | Indicates that the word is reserved by HP COBOL. They are treated as reserved words by ACUCOBOL-GT only if you compile with the -Cp compiler option.
(i) | Indicates that the word is reserved by both ACUCOBOL-GT and Data General ICOBOL
(r) | Indicates that the word is reserved by both ACUCOBOL-GT and RM/COBOL
(s) | Indicates that the word is reserved by ACUCOBOL-GT for use in the Screen Section
(v) | Indicates that the word is reserved by both ACUCOBOL-GT and VAX COBOL
(8) | Indicates that the word is reserved by the 1985 standard, but not by the 1974 standard
(*) | Indicates that the word is reserved by the 1985 standard but not used by ACUCOBOL-GT. These words are treated as user symbols by the compiler. They may become reserved in the future as more features of the 1985 standard are implemented, so their use is not advised.
Parent topic: Appendix B. Reserved Words


Reserved Word List

The topics in this section lists each reserved word in alphabetical order.

  • A
  • B
  • C
  • D
  • E
  • ACUCOBOL-GT Reserved Words - F
  • G
  • H
  • I
  • ACUCOBOL-GT Reserved Words - J
  • K
  • ACUCOBOL-GT Reserved Words - L
  • M
  • N
  • O
  • P
  • Q
  • R
  • S
  • T
  • U
  • V
  • W
  • Y
  • Z
Parent topic: Appendix B. Reserved Words


A

ACCEPT | ACCESS
ACTUAL(b,h) | ADD
ADDRESS(a) | ADVANCING
AFTER | ALL
ALLOWING | ALPHABET(8)
ALPHABETIC | ALPHABETIC-LOWER(8)
ALPHABETIC-UPPER(8) | ALPHANUMERIC(8)
ALPHANUMERIC-EDITED(8) | ALSO
ALTER | ALTERNATE
AND | ANY(8)
APPLY(v) | ARE
AREA | AREAS
ASCENDING | ASSEMBLY-NAME(a)
ASSIGN | AT
ATTRIBUTE(a) | AUTHOR
AUTO(i,s) | AUTO-MINIMIZE(a)
AUTO-RESIZE(a) | AUTO-SKIP(s)
AUTOMATIC(a) | AUTOTERMINATE(v)
Parent topic: Reserved Word List


B

BACKGROUND-COLOR(s) | BACKGROUND-COLOUR(s)
BACKGROUND-HIGH(a) | BACKGROUND-LOW(a)
BACKGROUND-STANDARD(a) | BACKWARD(i)
BEEP(r,s) | BEFORE
BELL(v,s) | BIND(a)
BINARY(8,r) | BLANK
BLINK(i,r,s) | BLINKING(v)
BLOCK | BOLD(v)
BOTTOM | BOX(a)
BOXED(a) | BULK-ADDITION(a)
BY |
Parent topic: Reserved Word List


C

CALL | CANCEL
CCOL(a) | CD(*)
CELL(a) | CELLS(a)
CENTERED(a) | CENTURY-DATE(a)
CENTURY-DAY(a) | CF(*)
CH(*) | CHAIN(a)
CHAINING(a) | CHARACTER
CHARACTERS | CHART(a)
CLASS(8) | CLASS-NAME(a)
CLINE(a) | CLINES(a)
CLOCK-UNITS(*) | CLOSE
COBOL(*) | CODE(*)
CODE-SET | COL(i,s)
COLLATING | COLOR(a)
COLOUR(a) | COLUMN
COM-REG | COMMA
COMMAND-LINE(a) | COMMIT(a)
COMMUNICATION(*) | COMP
COMP-1(r,v) | COMP-2(a)
COMP-3(r,v) | COMP-4(r)
COMP-5(a) | COMP-6(r)
COMP-N(a) | COMP-X(a)
COMPRESSION(a) | COMPUTATIONAL
COMPUTATIONAL-1(r,v) | COMPUTATIONAL-2(a)
COMPUTATIONAL-3(r,v) | COMPUTATIONAL-4(r)
COMPUTATIONAL-5(a) | COMPUTATIONAL-6(r)
COMPUTATIONAL-N(a) | COMPUTATIONAL-X(a)
COMPUTE | CONFIGURATION
CONSOLE(s) | CONSTRUCTOR(a)
CONTAINS | CONTENT(8)
CONTINUE(8) | CONTROL
CONTROLS(a) | CONVERSION(v)
CONVERT(r) | CONVERTING(8)
COPY | CORE-INDEX(b)
CORR | CORRESPONDING
COUNT | CREATE(a)
CRT(s) | CSIZE(a)
CULTURE(a) | CURRENCY
CURRENT-DATE(b,h) | CURSOR(r)
CYCLE(a) | CYL-INDEX(b)
CYL-OVERFLOW(b) |
Parent topic: Reserved Word List


D

DATA | DATE
DATE-COMPILED | DATE-WRITTEN
DATE YYYYMMDD(a) | DAY
DAY-OF-WEEK(8) | DAY YYYYDDD(a)
DE(*) | DEBUG-CONTENTS(*)
DEBUG-ITEM(*) | DEBUG-LINE(*)
DEBUG-NAME(*) | DEBUG-SUB-1(*)
DEBUG-SUB-2(*) | DEBUG-SUB-3(*)
DEBUGGING | DECIMAL-POINT
DECLARATIVES | DEFAULT(v)
DELETE | DELIMITED
DELIMITER | DEPENDING
DESCENDING | DESCRIPTOR(v)
DESTINATION(8) | DESTROY(a)
DETAIL(*) | DISABLE(*)
DISPLAY | DISPLAY-ST(b)
DIVIDE | DIVISION
DOUBLE(a) | DOWN(a)
DRAW(a) | DUPLICATES
DYNAMIC |
Parent topic: Reserved Word List


E

ECHO(r,v) | EGI(*)
EJECT(b) | ELSE
EMI(*) | EMPTY-CHECK(s)
ENABLED | ENCRYPTION(a)
END | END-ACCEPT(a,r,v)
END-ADD(8) | END-CALL(8)
END-CHAIN(a) | END-COMPUTE(8)
END-DELETE(8) | END-DISPLAY(a)
END-DIVIDE(8) | END-EVALUATE(8)
END-IF(8) | END-MODIFY(a)
END-MOVE(a) | END-MULTIPLY(8)
END-OF-PAGE | END-PERFORM(8)
END-READ(8) | END-RECEIVE(8)
END-RETURN(8) | END-REWRITE(8)
END-SEARCH(8) | END-START(8)
END-STRING(8) | END-SUBTRACT(8)
END-UNSTRING(8) | END-USE(a)
END-WAIT(a) | END-WRITE(8)
ENDING(a,b) | ENTER
ENTRY(a, b) | ENVIRONMENT
EOL(r,s) | EOP
EOS(r,s) | EQUAL
ERASE(r,v) | ERROR
ESCAPE(i,s) | ESI(*)
EVALUATE(8) | EVENT(a)
EVERY(*) | EXAMINE(b,h)
EXCEPTION | EXCLUSIVE(h,i)
EXIT | EXTEND
EXTENDED-SEARCH(r) | EXTERNAL(8)
EXTERNAL-FORM(a) |
Parent topic: Reserved Word List


ACUCOBOL-GT Reserved Words - F

FALSE(8) | FD
FILE | FILE-CONTROL
FILE-ID(v) | FILE-LIMIT(r)
FILE-LIMITS(r) | FILE-PATH(a)
FILE-PREFIX(a) | FILLER
FINAL(*) | FIRST
FLOAT(a) | FLOATING(a)
FONT(a) | FOOTING
FOR | FOREGROUND-COLOR(s)
FOREGROUND-COLOUR(s) | FREE(h)
FROM | FULL(i,s)
FUNCTION |
Parent topic: Reserved Word List


G

GENERATE(*) | GIVING
GLOBAL(8) | GO
GOBACK(r) | GRAPHICAL(a)
GREATER | GRID(s)
GROUP(*) |
Parent topic: Reserved Word List


H

HANDLE(a) | HEADING(*)
HEIGHT(a) | HELP-ID(a)
HIGH | HIGH-VALUE
HIGH-VALUES | HIGHLIGHT(s)
Parent topic: Reserved Word List


I

I-O | I-O-CONTROL
ICON(a) | ID
IDENTIFICATION | IDENTIFIED(a)
IF | IN
INDEPENDENT(a)` | INDEX
INDEXED | INDICATE(*)
INITIAL | INITIALIZE(8)
INITIATE | INPUT
INPUT-OUTPUT | INQUIRE(a)
INSPECT | INSTALLATION
INTO | INVALID
IS |
Parent topic: Reserved Word List


ACUCOBOL-GT Reserved Words - J

JUST JUSTIFIED
Parent topic: Reserved Word List


K

KEPT(a) KEY
Parent topic: Reserved Word List


ACUCOBOL-GT Reserved Words - L

LABEL | LAST
LAYOUT-DATA(a) | LAYOUT-MANAGER(a)
LEADING | LEFT
LEFTLINE(s) | LENGTH
LENGTH-CHECK(s) | LESS
LIMIT(*) | LIMITS(*)
LINAGE | LINAGE-COUNTER
LINE | LINE-COUNTER(*)
LINES | LINK(a)
LINKAGE | LOCK
LOCK-HOLDING(v) | LOW(r)
LOW-VALUE | LOW-VALUES
LOWER(a) | LOWLIGHT(s)
Parent topic: Reserved Word List


M

MANUAL(a) | MASS-UPDATE(a)
MASTER-INDEX(b) | MEMORY
MENU(a) | MERGE
MESSAGE(a) | MESSAGES(a)
MODAL(a) | MODE
MODELESS(a) | MODIFY(a)
MODULE(a) | MODULES
MOVE | MULTIPLE
MULTIPLY |
Parent topic: Reserved Word List


N

NAMESPACE(a) | NATIONAL
NATIONAL-EDITED | NATIVE
NEGATIVE | NEXT
NO | NO-ECHO(s)
NOLIST(h) | NOMINAL(b)
NOT | NOTE(b)
NULL(a) | NULLS(a)
NUMBER | NUMERIC
NUMERIC-EDITED(8) | NUMERIC-FILL(a)
Parent topic: Reserved Word List


O

OBJECT(a) | OBJECT-COMPUTER
OCCURS | OF
OFF | OMITTED
ON | ONLY(a)
OPEN | OPTIONAL(8)
OR | ORDER(8)
ORGANIZATION | OTHER(8)
OTHERS(v) | OTHERWISE(b)
OUTPUT | OVERFLOW
OVERLAPPED(a) | OVERLINE(s)
Parent topic: Reserved Word List


P

PACKED-DECIMAL(8) | PADDING(8)
PAGE | PAGE-COUNTER(*)
PARAGRAPH(a) | PASSWORD(b)
PERFORM | PF(*)
PH(*) | PIC
PICTURE | PIXEL(a)
PIXELS(a) | PLUS
POINTER | POP-UP(a)
POS(s) | POSITION
POSITIONING(b) | POSITIVE
PREVIOUS(a,i) | PRINT-CONTROL(v)
PRINTING(*) | PRIORITY(a)
PROCEDURE | PROCEDURES(*)
PROCEED | PROCESSING(b)
PROGRAM | PROGRAM-ID
PROMPT(r,s) | PROPERTY(a)
PROTECTED(i,v) | PURGE(*)
Parent topic: Reserved Word List


Q

QUEUE(*) | QUOTE
QUOTES |
Parent topic: Reserved Word List


R

RANDOM | RD(*)
READ | READERS(v)
RECEIVE | RECORD
RECORD-POSITION(a) | RECORDING(i)
RECORDS | REDEFINES
REEL | REFERENCE(8)
REFERENCES(*) | RELATIVE
RELEASE | REMAINDER
REMARKS(a) | REMOVAL
RENAMES | REPLACE(8)
REPLACING | REPORTING
REQUIRED(i,s) | REPORT(*)
REPORTING(*) | REPORTS(*)
RERUN(*) | RESERVE
RESET(*) | RESIDENT(a)
RESIZABLE(a) | RETURN
RETURNING | RETURN-CODE
RETURN-UNSIGNED | REVERSE(r)
REVERSE-VIDEO(s) | REVERSED
REWIND | REWRITE
RF(*) | RH(*)
RIGHT | ROLLBACK
ROUNDED | RUN
Parent topic: Reserved Word List


S

SAME | SCREEN(i,s,v)
SCROLL(a) | SD
SEARCH | SECTION
SECURE(i,s) | SECURITY
SEEK(r,h) | SEGMENT(*)
SEGMENT-LIMIT | SELECT
SEND | SENTENCE
SEPARATE | SEQUENCE
SEQUENTIAL | SET
SHADOW(a) | SIGN
SIGNED-INT(a) | SIGNED-LONG(a)
SIGNED-SHORT(a) | SIZE
SKIP1(b) | SKIP2(b)
SKIP3(b) | SORT
SORT-CORE-SIZE(b) | SORT-FILE-SIZE(b)
SORT-MERGE | SORT-MODE-SIZE(b)
SORT-RETURN(b) | SOURCE(*)
SOURCE-COMPUTER | SPACE
SPACES | SPECIAL-NAMES
STANDARD | STANDARD-1
STANDARD-2(8) | START
STATUS | STOP
STRING | STRONG-NAME(a)
STYLE(a) | SUB-QUEUE-1(*)
SUB-QUEUE-2(*) | SUB-QUEUE-3(*)
SUBTRACT | SUBWINDOW(a)
SUM(*) | SUPPRESS(b)
SYMBOLIC(8) | SYNC
SYNCHRONIZED | SYSTEM(a)
SYSTEM-INFO(a) |
Parent topic: Reserved Word List


T

TAB(r) | TABLE(a)
TALLY(a) | TALLYING
TAPE | TERMINAL(*)
TERMINAL-INFO(a) | TERMINATE(*)
TEST(8) | TEXT
THAN | THEN(8)
THREAD(a) | THREADS(a)
THROUGH | THRU
TIME | TIME-OF-DAY(b,h)
TIMES | TITLE(a)
TITLE-BAR(a) | TO
TOOL-BAR(a) | TOP
TRACK-AREA(b) | TRACKS(b)
TRAILING | TRANSACTION(a)
TRANSACTION-STATUS(a) | TRANSFORM(b)
TRUE(8) | TYPE(a,*)
Parent topic: Reserved Word List


U

UN-EXCLUSIVE(h) | UNDERLINE(s)
UNDERLINED(v) | UNIT
UNLOCK(i,r,v) | UNSIGNED-INT(a)
UNSIGNED-LONG(a) | UNSIGNED-SHORT(a)
UNSTRING | UNTIL
UP | UPDATE(r,v)
UPDATERS(v) | UPON
UPPER(a) | USAGE
USE | USING
Parent topic: Reserved Word List


V

VALUE | VALUES
VARYING | VERSION(a)
VISIBLE(a) |
Parent topic: Reserved Word List


W

WAIT(a) | WHEN
WHEN-COMPILED(b) |
WIDTH(a) | WIDE(a)
WITH | WINDOW(a)
WORKING-STORAGE | WORDS
WRITE | WRAP(a)
WRITE-VERIFY(b) | WRITE-ONLY(b)
WRITERS(v) |
Parent topic: Reserved Word List


Y

YYYYDDD(8) YYYYMMDD(8)
Parent topic: Reserved Word List


Z

ZERO | ZERO-FILL(s)
ZEROES | ZEROS
Parent topic: Reserved Word List


Appendix C. Changes Affecting Previous Versions

  • Changes Affecting Version 10.2.0
  • Changes Affecting Version 10.1.1
  • Changes Affecting Version 10.1.0
  • Changes Affecting Version 10.0
  • Changes Affecting Version 9.0.0
  • Changes Affecting Version 8.1.2
  • Changes Affecting Version 8.1.1
  • Changes Affecting Version 8.1
  • Changes Affecting Version 8.0
  • Changes Affecting Version 7.2
  • Changes Affecting Version 7.1
  • Changes Affecting Version 7.0
  • Changes Affecting Version 6.2
  • Changes Affecting Version 6.1
  • Changes Affecting Version 6.0
  • Changes Affecting Version 5.2
  • Changes Affecting Version 5.1
  • Changes Affecting Version 5.0
  • Changes Affecting Version 4.3
  • Changes Affecting Version 4.2
  • Changes Affecting Version 4.1
  • Changes Affecting Version 4.0
  • Changes Affecting Version 3.2
  • Changes Affecting Version 3.1
  • Changes Affecting Version 2.4
  • Changes Affecting Version 2.3
  • Changes Affecting Version 2.1
  • Changes Affecting Version 2.0
  • Changes Affecting Version 1.5
  • Changes Affecting Version 1.4
  • Changes Affecting Version 1.3
Parent topic: Appendices


Changes Affecting Version 10.2.0

If you are updating from a version of the extend Interoperability Suite prior to version 10.2.0, you need to be aware of the following changes that may affect your existing applications:

Vision 2 file format support discontinued

Support for the Vision 2 file format is discontinued in this version of the extend Interoperability Suite. The Vision 2 file format was not portable between systems with different architectures, and was superseded by the Vision 3 file format over 24 years ago. Use of the Vision 2 file format has not been recommended for a very long time.

Any remaining Vision 2 files should be rebuilt to a newer Vision file format; see Rebuilding Files for more details. Vision 3 is a portable single-file format containing the index and records in a single file, and is limited to file sizes less than 2GB; Vision 4 and Vision 5 are portable dual file formats using multiple segments to support large files; and Vision 6 is a portable dual file format supporting files larger than 2GB. Vision 6 is the default Vision file format, and for best results use this file format where possible.

Keyboard input

If you use the KBD-DATA-RANGE-HIGH and KBD-DATA-RANGE-LOW configuration variables to set the range of keyboard input (see DATA-RANGE=value), you must set these variables to integer values. Previously, it was also possible to set a byte value; this is no longer permitted.

Parent topic: Appendix C. Changes Affecting Previous Versions
Related reference
Rebuilding Files
DATA-RANGE=value


Changes Affecting Version 10.1.1

If you are updating from a version of the extend Interoperability Suite prior to version 10.1.1, you need to be aware of the following changes that may affect your existing applications:

Translating OEM character sets

In the previous release, Unicode support was introduced for user input and output, and as part of the implementation, a new configuration variable (COBOL-CHARACTER-SET) was introduced, and the TRANSLATE-TO-ANSI configuration variable was removed. If your data was represented by an OEM character set, you would either need to determine the correct Microsoft OEM code page, then set COBOL-CHARACTER-SET to its identifier number or to OEM (or 1).

For ease of updating, we have reintroduced the TRANSLATE-TO-ANSI configuration variable, with the same semantics as in prior versions. However, it should be noted that having COBOL-CHARACTER-SET set to the default of ANSI, and TRANSLATE-TO-ANSI to TRUE, is less efficient than setting TRANSLATE-TO-ANSI to FALSE, and setting COBOL-CHARACTER-SET to OEM. The reason is that, in the former case, the runtime first translates OEM data to ANSI, then translates the ANSI date to UTF-16 to display it; and when accepting data, the runtime receives UTF-16 data, translates it to ANSI, and then translates again to OEM to return to the COBOL program. While in the latter case, the runtime translates the OEM data to UTF-16 directly (to display), and UTF-16 to OEM directly (to accept).

Parent topic: Appendix C. Changes Affecting Previous Versions
Related reference
COBOL_CHARACTER_SET
TRANSLATE_TO_ANSI


Changes Affecting Version 10.1.0

If you are updating from a version of the extend Interoperability Suite prior to version 10.1.0, you need to be aware of the following changes that may affect your existing applications.

TRANSLATE_TO_ANSI configuration variable
This variable has been superceded by the COBOL_CHARACTER_SET configuration variable, and should be replaced in your applications. See the COBOL_CHARACTER_SET details for more information. (Important: This decision was reversed in extend 10.1.1, where you can continue to use this variable for your translations.)
W$FONT library routine
W$FONT may load slower than in the past, due to the new Unicode support.
The runtime now checks to see if a chosen font has a width that seems too large, and if so, every character is validated. With ANSI fonts, this is about 250 characters. With Unicode fonts, this can be up to 65,000 characters, meaning that the test can take considerably longer to load.
If you encounter W$FONT loading slower than in previous versions and you do not plan to use the Unicode support, set V71-FONT-WIDTHS to TRUE to skip the width validation.
Parent topic: Appendix C. Changes Affecting Previous Versions
Related reference
COBOL_CHARACTER_SET
W$FONT


Changes Affecting Version 10.0

New Samples Directory

On Windows, the samples supplied with your products are installed in the following location:

%PUBLIC%\Documents\Micro Focus\extend x.x.x\sample
where %PUBLIC% is a Windows variable that on most Windows versions defaults to c:\users\public, and x.x.x is the version number of your extend installation.

A copy of the definition files and XML Extensions COPY files can also be found at this location, but they are also still installed in their previous location (the \sample sub-directory of the installation directory), so as to minimize changes required to your source code.

AcuBench uses a new environment variable %sampledir% in order to reference the new location.

Updating from AcuBench 4.3

Some conversion .dll files have been removed from the current installation. If you are updating from AcuBench 4.3 or earlier, you will need to request a temporary version of AcuBench 9.2, so that you can update your project files, after which you can use AcuBench 10.0 with your projects.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 9.0.0

New Installation Location on Windows

The Windows installation directory structure for all extend products has changed. In particular the former directory Acucorp has been renamed to Micro Focus.

For example, version 8.x of ACUCOBOL-GT is installed here:

C:\Program Files\Acucorp\Acucbl800\AcuGT

Now, version 9.0.0 and higher is installed here:

C:\Program Files\Micro Focus\Acucbl900\AcuGT

Windows License File Location Changes

Version 9.0 now follows the Microsoft guidelines for license file locations.

When using a standard ACUCOBOL-GT installation and License Activator you should see no change in behavior. However, license files are no longer created in the installation directory (C:\Program Files\Acucorp\Acucbl900, by default on Windows XP). Instead, license files are created in an application-specific location, which changes depending on the version of Windows in use.

On Windows Vista and Windows 7, the location is:

C:\Documents and Settings\All Users\Application Data\Micro
Focus\extend\9.0.0\x86\product-license.alc)

The activator writes the license to this location, and all extend applications (compiler, runtime, acuserve, etc.) search for the license file in this location first. If the license file is not in the new location, then the old logic is followed - the executable will search for the license in the same directory as the executable.

We determine the location of the license files by examining the value of the environment variable ALLUSERSPROFILE. For versions prior to Windows Vista, we append the directory name Application Data. We then append Micro Focus/extend/9.0.0. For 32-bit programs, we then append x86.

Windows Registry Key Changes

The Windows registry key is changed from:

SOFTWARE\\Acucorp, Inc.\\

To:

SOFTWARE\\Micro Focus\\

SHARED_LIBRARY_EXTENSION Default Value Change

The default value of the SHARED_LIBRARY_EXTENSION configuration value has been changed to match the standard value for the host system.

The old default value was fixed as .so. Some systems use a different shared library extension. The new default value will match the extension used on the shared libraries in the lib directory.

You may need to update the value of the SHARED_LIBRARY_EXTENSION configuration variable if you were relying on it always being set to .so.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 8.1.2

Compiler - Decimal math now the default behavior

In version 7.2, a new math package called Binary Math (--bin) was added to the compiler and became the default behavior over the previous Decimal Math (--dec). See Changes Affecting Version 7.2 for details.

Starting with Version 8.1.2, the compiler's default behavior is reverted back to decimal math.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 8.1.1

XFD format and -Fe compiler option

By default the compiler will now generate XFDs in XML format, as opposed to standard flat text, which was the default prior to Version 8.1.1. This change also affects the -Fe compiler option. This option will now direct the compiler to create XFDs in flat text format, as opposed to XML format, which was the case in versions prior to 8.1.1.

Read-only entry fields

In Version 8.1, read-only entry fields were changed to conform to standard Windows behavior in that the background color is always gray (regardless of the COBOL program's Color setting). This is still the case in Version 8.1.1; however, this behavior is now configurable. If you need the ability to change the color of read-only entry fields, set the runtime configuration variable ECN_3699 to 0.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 8.1

$ Symbol in source code

In Version 8.1, COBOL source code can now contain lines with a dollar sign ($) in the indicator area, which may be used with the IF, ELSE, END, DISPLAY, and SET statement to support conditional compiling.

The $ symbol is also a valid comment character. If a program uses $ as a comment, and it is immediately followed by IF, ELSE, END, DISPLAY an error will most likely be generated.

Read-only text fields

As of Version 8.1, read-only entry fields were changed to conform to standard Windows behavior in that the background color is always gray (regardless of the COBOL program's Color setting). If you need the ability to change the color of read-only entry fields, set the runtime configuration variable ECN_3699 to 0.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 8.0

Compiler

In previous versions, an END-PERFORM was required when the PERFORM was nested in an EVALUATE statement. With Version 8.0, the compiler accepts the WHEN verb as an implied END-PERFORM.

Interoperability

Comments in C$XML no longer include the expression:

 '.* - generated by ACUCOBOL-GT v.*\n*'

If you depend on having those comments, you will need to rework your application in some way.

For .NET, the type checking rules for using overloaded methods in a COBOL program are more stringent now. You must use COBOL types that match the NETDEFGEN COPY file method declaration.

SIGNED-INT   - int32.
   UNSIGNED-INT   - uint32.
   SIGNED-LONG    - long.
   SIGNED-SHORT   - int16.
   UNSIGNED-SHORT  - uint16.
  PIC X(nn)  - BSTR
  pic 9    - BOOLEAN
  PIC X    - BYTE
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 7.2

Compiler Changes

In previous versions, ACUCOBOL-GT has performed the majority of its arithmetic operations using a 40-digit decimal format (68 digits if using the -Dd31 compiler option). Starting with Version 7.3, ACUCOBOL-GT uses a binary math package as its default. The decimal package remains in place to handle certain high-precision cases and to maintain compatibility with existing programs. Users of ACUCOBOL-GT can choose which package they use: the binary package for enhanced performance or the decimal one for compatibility with prior compilers. Use the decimalMath (or dec) compiler option to use the decimal math format. See Miscellaneous Options in the ACUCOBOL-GT User's Guide for more information about these compiler options.

Prior to Version 7.3, cblutil produced instructions that ran under both POWER and PowerPC architectures when generating PowerPC native code. Starting with Version 7.3, this is no longer true. The reason is that the code generator started using multiply and divide instructions in some important cases, and some of these instructions changed. The existing --ppc compiler option now produces 32-bit PowerPC code that is also compatible with POWER3, POWER4, and POWER5 processors. This code does not run correctly on POWER- or POWER2-based machines. A new --power option produces code that is compatible with POWER and POWER2 processors, as well as PowerPC and later POWER series processors. This code can be significantly slower than code generated with --ppc, but it does run on a wider range of machines. See Native Code Options in the ACUCOBOL-GT User's Guide for more information about native code generation.

Two compilation switches provide compatibility with Version 7.2:

-C72 | Causes the compiler to generate code according to the rules used by Version 7.2.
-Z72 | Creates object code that can be run with a Version 7.2 runtime.
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 7.1

Compiler and Runtime Changes

Beginning with Version 7.2, the wheel mouse can be used for scrolling in a center- or right-aligned entry field. To preserve the pre-7.2 behavior and prevent scrolling in these situations, set the V71_ALIGNED_ENTRY_FIELD configuration variable to 1 (on, true, yes) or compile your code for compatibility with a version older than Version 7.2. The default value of this variable is 0 (off, false, no).

In Version 7.2, the runtime uses a different font measuring algorithm when it computes font widths in Windows. With this change, the runtime now validates the data returned by the Windows GetTextMetrics function and corrects it when it is too large. The V71_FONT_WIDTHS configuration variable setting allows you to use the pre-Version 7.2 rules. This variable can have one of the following values:

-1 | (default) The change is enabled for programs using Version 7.2 or later semantics. In other words, the program has been compiled with Version 7.2 or later and the command line does not contain a compiler option for pre-7.2 semantics.
0 | The change is enabled.
1 | The change is disabled and the Version 7.1 and earlier font measuring code is used.

Two compilation switches provide compatibility with Version 7.1:

-C71 | Causes the compiler to generate code according to the rules used by Version 7.1.
-Z71 | Creates object code that can be run with a Version 7.1 runtime.
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 7.0

The following sections describe changes that can affect programs originally written with ACUCOBOL-GT Version 7.0.

Compiler and Runtime Changes

Two compilation switches provide compatibility with Version 7.0:

-C70 | Causes the compiler to generate code according to the rules used by Version 7.0.
-Z70 | Creates object code that can be run with a Version 7.0 runtime.

In Version 7.1, the total size of parameters passed BY CONTENT is increased to 2GB. For Version 7.0 and earlier, the total size limit is 64K. If you compile with -Z70, your program has the 64K limit for parameters passed BY CONTENT.

The maximum number of REPLACING elements in an INSPECT statement is increased to 256. For Version 7.0 and earlier, the limit is 30.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 6.2

The following sections describe changes that can affect programs originally written with ACUCOBOL-GT Version 6.2.

UNIX: New Default Installation Directory

On UNIX systems, the ACUCOBOL-GT development system (compiler, runtime, utilities, etc.) has a new default directory location. The new location is: /opt/acucorp/720. This change has been made to conform with the Version 2.3 Filesystem Hierarchy Standard (FHS). Installing into the FHS standard location provides consistency and improves system integration. For more information about the FHS standard, please visit www.pathname.com/fhs/pub/fhs-2.3.html.

Initialization of External Data Items

Versions of ACUCOBOL-GT prior to Version 7.0 had the behavior of initializing external data items to LOW-VALUES, even when the rest of Working-Storage was initialized to spaces. Beginning with Version 7.0, all Working-Storage data items are initialized to spaces or the value specified with the -Dv compile option. This includes external data items.

To maintain compatibility with programs that rely on the old behavior, you can compile for semantic compatibility with Version 6.2 or earlier. Use the -C## compile option to do this (for example, -C62 for Version 6.2 compatibility). When you compile for compatibility with Version 6.2 or earlier, external data items are initialized to null bytes, regardless of how the rest of Working-Storage is initialized.

C Functions

Starting with Version 7.0, ACUCOBOL-GT has added significant new features to the C interface, allowing you greater flexibility for calling COBOL programs from C and C++.

For existing programs, this means:

  • The cobol() and cobol_no_stop() functions are still supported but have been deprecated. The new function, acu_cobol(), extends the options available in the C interface.
  • Information on the deprecated cobol() and cobol_no_stop() functions is not documented in Version 7.0. See Appendix F in previous versions of the ACUCOBOL-GT documentation set for this information.

Compiler Changes

Two compilation switches provide compatibility with Version 6.2:

-C62 | Causes the compiler to generate code according to the rules used by Version 6.2.
-Z62 | Creates object code that can be run with a Version 6.2 runtime.

Runtime Changes

  • The runtime now automatically corrects most reference modification range errors. It applies the following rules:
    1. A start reference less than 1 is treated as 1. For example, var(0:3) is treated as var(1:3).
    2. A length reference less than 0 is treated as 0. Moving a zero-byte item is equivalent to moving spaces to the destination item. A zero-byte destination is not affected by the move. In a STRING statement, a length of zero for a string source is treated as 1, not 0.
    3. A start plus length reference that is past the end of the item is treated as meaning to the end of the item. For example, if the var is a PIC X(5) item, var(4:23) is treated as var(4:2).

    The WARNINGS runtime configuration variable provides some control over how reference modification range errors are handled. See its entry in Appendix H.

  • The behavior of the character-based tree view control has changed. In previous versions, the MSG-TV-SELCHANGE message was not sent if the COBOL program deleted an item. Nor was it sent when the COBOL program first ACCEPTed a tree view control. Beginning with Version 7.0, the MSG-TV-SELCHANGE message is now sent in both cases.
  • Beginning with Version 7.0, when the runtime reduces the size of a window to fit the screen, it includes any fractional lines and columns that fit, provided the COBOL program attempted to create a window with fractional lines and columns. For example, if the program creates a 70.0 line window, but only a 66.4 line window fits on the display, the runtime detects that no fractional lines were attempted, and truncates the number of lines to 66.0. However, if you attempt to create a 70.1 line window, the runtime recognizes the fractional measurement and displays a 66.4 line window. In prior versions, the runtime always reduced the size of the window to a whole number. To preserve the old behavior, set the configuration variable V62_MAX_WINDOW to 1 (on, true, yes).
  • Beginning with Version 7.0, the Web runtime uses ANSI_FIXED_FONT as the standard font. Because some systems may depend on the old font, this change is configurable. To use the font standard from Versions 6.2 and earlier (SYSTEM_FIXED_FONT), adjust the setting of the configuration variable STD_FIXED_FONT, described in Appendix H.
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 6.1

The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 6.1.

Compiler Changes

Programs that will be deployed on 64-bit Windows systems and that have USAGE POINTER data items must be recompiled with Version 6.1.1 or later. This is because, beginning with Version 6.1.1 (the introduction of ACUCOBOL-GT for 64-bit Windows), the compiler and runtime differentiate between USAGE LONG and USAGE POINTER data items. This is necessary for 64-bit Windows.

Two compilation switches provide compatibility with Version 6.1:

-C61 | Causes the compiler to generate code according to the rules used by Version 6.1.
-Z61 | Creates object code that can be run with a Version 6.1 runtime.

Runtime Changes

  • Beginning with Version 6.2, on the HP e3000, if a program is compiled with the -Cp option, OPEN OUTPUT statements create temporary files. This is consistent with the behavior of native HP COBOL on the platform. Prior to Version 6.2, OPEN OUTPUT statements created permanent files.
  • Beginning with Version 6.2, C$OPENSAVEBOX makes use of the OPNSAV-FLAGS field of OPENSAVE-DATA. Prior versions ignored the field.
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 6.0

The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 6.0.

Compiler Changes

Two compilation switches provide compatibility with Version 6.0:

-C60 | Causes the compiler to generate code according to the rules used by Version 6.0.
-Z60 | Creates object code that can be run with a Version 6.0 runtime.

Alignment of Literals

The compiler uses a new algorithm for aligning literals in memory. The alignment is the smaller of the alignment specified by the -Da option (which has a default value of 4) or the largest power of 2 that is less than or equal to the literal's size. For example, a literal that requires 3 bytes of memory will have an alignment of 2. You can use the --noAlignLit option to turn off the new algorithm. See Data Storage Options in the ACUCOBOL-GT User's Guide, for additional information on --noAlignLit.

Runtime Changes

  • In Version 6.0 and earlier, the WIN$PRINTER functions WINPRINT-PRINT-BITMAP, WINPRINT-SET-CURSOR, and WINPRINT-GRAPH-DRAW, ignored the form feed status of a pending print job, causing images or text to print on the wrong page. In Version 6.1 and later, calls to these functions automatically test for a pending form feed before printing.
  • In Version 6.1, when a program is compiled with the -Cp switch and run on an HP e3000, all OPEN OUTPUT statements create MPE files. In prior versions, byte stream files were created.
  • In Version 6.0 and earlier, if a program argument was preceded by a double dash (two dashes) it was effectively treated as if preceded by a single dash. For example, runcbl --dle errfile iobench was executed as if it were runcbl -dle errfile iobench. Beginning with Version 6.1, an argument preceded by two dashes generates a runtime startup error, unless you specifically modify exam_args (in sub.c) to ignore command-line errors.
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 5.2

The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 5.2.

Vision Version 5

Version 6.0 introduces a new Vision file format: Vision Version 5. Vision Version 5 supports records up to 64 megabytes in size, block sizes up to 8192 bytes, very large pre-allocate and extension factors, and a virtually unrestricted number of records that allow duplicates. Version 5 files cannot be read by ACUCOBOL-GT Version 5.2.1 or earlier runtimes. See Indexed Files Vision in ACUCOBOL-GT User's Guide the for a complete description of Vision Version 5.

Windows Console Runtime

Version 6.0 introduces a new runtime for the Windows operating environment that may be used to run applications originally deployed in the Extended DOS environment, as well as other character-based applications. The new runtime is called the console runtime. The name of the executable is crun32.exe. The console runtime uses the Windows Console API and runs in a virtual DOS window. The console runtime replaces the Extended DOS runtime and is sold separately.

The console runtime can run ACUCOBOL-GT applications developed for the Extended DOS environment provided that some minor changes are made. For example, the console runtime supports printing capabilities based on the Windows model. Program code that relies on DOS printing functions must be modified.

The following runtime configuration variables are MS DOS-specific and are not supported in Version 6.0:

  • 132_MODE
  • A_WAIT_FOR_LICENSE
  • AUTO_BUFFER
  • DOS_OUTPUT_METHOD
  • DOS_WATCOM_10
  • LOCKED_RECORD_DELAY
  • USE_MOUSE

Web Plug-in Discontinued

The browser industry has shifted away from its support of Internet plug-ins in favor of ActiveX controls. For this reason, we developed and released an ActiveX-based Web Runtime in ACUCOBOL-GT Version 5.2.1. Due to lack of browser support, the ACUCOBOL-GT Web Plug-in is not offered or supported in Version 6.0. See Migrating from the Web Plug-in to the Web Runtime in A Programmer's Guide to the Internet for information on migrating from the Web Plug-in to the Web Runtime.

List Box and Combo Box Handling of VALUE

In Version 5.2 and earlier, setting the VALUE of a combo box or list box caused the first item in the list that started with the value of VALUE to be selected, regardless of case. Beginning with Version 6.0, when a box's VALUE is set, the list is searched for an exact, case sensitive match with the specified value. If the value is found, it is selected. If an exact match is not found, the list is searched for an exact match regardless of case. If a match is still not found, the list is searched again, this time for the first string that contains the passed VALUE as a leading substring, regardless of case.

This change could affect the behavior of an existing application. The configuration variable V60_LIST_VALUE allows you to select which search algorithm, new or old, to use. See V60_LIST_VALUE in Appendix H.

Area A in RM COBOL Compatibility Mode

Starting with Version 6.0, when you compile for RM COBOL compatibility (-Cr), in the Identification Division, Area A can start in either column 8 or 9 (ANSI format) or column 1 or 2 (terminal format). In prior versions, Area A in the Identification Division started precisely in column 8 (ANSI format) or column 1 (terminal format).

This change may cause warnings in programs that previously compiled without warnings. To revert to the old rule, you can use the --noRmMargin compiler option.

Image Rendering for BITMAP Controls

The image processing code used by Version 6.0 (and later) for BITMAP controls is device-dependent. This may affect image rendering in some programs, written for Version 5.2 or earlier, which rely on device-independent bitmaps. If BITMAP controls are displaying incorrectly, adjust the setting of the configuration variable, V52_BITMAPS V52_BITMAPS, described in Appendix H.

Bitmap Push Button Behavior Change

If some event in the system forces the focus away from a text-based push button after a click has been initiated but not finished, the click is voided. Starting with Version 6.0, bitmap push buttons void the click just like a text-based push button. This change applies only to programs compiled for 6.0 semantics or later.

Changes to Data Items Used by C$REDIRECT

The definitions of the HANDLER-PRE-ALLOCATE-AMOUNT, HANDLER-EXTENSION-AMOUNT, HANDLER-MAX-LREC-SIZE, HANDLER-MIN-LREC-SIZE, and HANDLER-SEGMENT-OFFSET data items in sample/handler.cpy have changed.

Changes to Data Items Used by I$IO

The definitions of the PRE-ALLOCATION-AMOUNT, EXTENSION-AMOUNT, MAX-REC-SIZE, MIN-REC-SIZE, and KEY-OFFSET data items in "sample/def/filesys.def" have changed.

Compiler Changes

  • Two compilation switches provide compatibility with Version 5.2:
    -C52  | Causes the compiler to generate code according to the rules used by Version 5.2.
    -Z52 | Creates object code that can be run with a Version 5.2 runtime.
  • When compiling for Version 6.0 or later format, table indexes and USAGE INDEX data items are treated as 32-bit signed native binary data items. In versions prior to 6.0, the default for indexes is to act as 16-bit unsigned portable binary data items. In rare cases, this change from 16-bit to 32-bit indexes may cause problems with an existing program. One case where this could be a problem is if you place USAGE INDEX items in a data file. Another case would be if you rely on undefined overflow behavior with arithmetic on 16-bit indexes.

    If you need to preserve indexes as 16-bit items, you can either compile for an object format prior to Version 6.0, or you can compile using the --nodata32bit option. This option inhibits the new data addressing features of 6.0 and causes indexes to be kept as 16-bit data items.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 5.1

The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 5.1.

Licensing Changes

The licensing mechanism changed with the release of Version 5.0. In Version 5.2, this mechanism has been simplified:

  • Node IDs are no longer used.
  • When the license is installed, the Windows version of the Activator creates a separate license file for each product, in the same manner as UNIX.
  • The Activator utility is not backwards compatible. You must use the version of the Activator utility that corresponds to the version of the product you are installing in order to create a proper license file.

A complete description of the current licensing mechanism is available in Getting Started with ACUCOBOL-GT.

Compiler Changes

  • Two compilation switches provide compatibility with Version 5.1:
    -C51  | Causes the compiler to generate code according to the rules used by Version 5.1.
    -Z51 | Creates object code that can be run with a Version 5.1 runtime.
  • Compiler switch -Zt is not supported in Version 5.2.
  • In versions prior to 5.2, the grid would not pass a MSG-GOTO-CELL-MOUSE event to the program when the user clicked on the cell containing the grid cursor. This was done to prevent extraneous messages from being sent to the program. However, this message can be useful in some cases, for example, to allow a user to deselect something that is already selected. Therefore, in Version 5.2 and later, the runtime no longer filters out MSG-GOTO-CELL-MOUSE messages just because the destination cell is the same as the current cell.
    Note: This change is active only for programs compiled for Version 5.2 or later. This means that the Version 5.2 runtime will use the old behavior when executing programs compiled with versions prior to 5.2, or compiled with the C51 or the Z51 switch. You can disable the new behavior by setting the configuration variable V52_GRID_GOTO to 0.
  • Version 5.2 introduces ENTRY as a new reserved word in ACUCOBOL-GT. A program that compiled with a previous version of the compiler will not compile with Version 5.2 if it uses entry in certain places. For example:

    If entry appears in a paragraph name in your program, the compiler returns the error:

    Identifier expected, ENTRY found

    If entry appears in a variable in your program, the compiler returns the error:

    syntax error scanning ENTRY

    See the ENTRY Statement in Procedure Division Statements, for usage syntax and rules.

Runtime Changes

  • The ACUCOBOL-GT Version 5.2 runtime on SCO UNIX systems runs in the ELF binary format. Prior to Version 5.2, the runtime ran in the COFF format, but COFF does not support calling shared libraries so it was changed to ELF. If you have your own C routines that you used to link to the runtime, you will need to recompile those C routines to create ELF objects to link to the 5.2 runtime. For details on calling shared library routines in UNIX environments, see Working with C and C++ Programs in A Guide to Interoperating with ACUCOBOL-GT.
  • In versions prior to 5.2, the runtime would eliminate requests to resize a screen control if the new size and position matched the control's current size and position on the screen. With the current version, the runtime optimizes the control resize request using the SIZE and LINES indicated (or implied) by your program instead of the current size and position.

    These two ways of optimizing control resize requests produce nearly identical results. However, there are a few cases where the results can differ. For example, if you change the size of the subwindow that contains the control in such a way that the control would crop differently, then a comparison of the "actual" size shows a difference, while a comparison of the "requested" size does not. In this case, earlier versions of the runtime would resize the control, while the current version will not.

    This change was made to provide more predictable behavior and to improve efficiency when the display service is on a remote machine.

    If necessary, you can disable this behavior by setting OPTIMIZE_CONTROL_RESIZE to "0" (off, false, no). This prevents any optimization of control resizing operations. Note that this can result in additional screen painting (in which controls may appear to flicker) and should be used only as a short-term fix while any required coding changes are made.

  • The way the runtime handles mouse click events in COBOL programs that contain both bitmap push buttons and multiple windows under the control of a single thread has changed.

    In Version 5.1 and earlier, in some cases, simply clicking down on the mouse button when a bitmap push button was selected, generated a CMD-CLICK event. This was not consistent with the way Microsoft Windows handles these events.

    In Version 5.2 and later, clicking down on a bitmap pushbutton on a non-active window running in the same thread will cause the current ACCEPT to terminate with CMD-ACTIVATE event. The pushbutton is not considered clicked until the COBOL program performs some action that allows it to activate, such as ACCEPTing some control in the newly activated window. For self-activating pushbuttons, this allows the pushbutton to self activate. For non-self-activating pushbuttons, the new ACCEPT will terminate with a CMD-GOTO so that the COBOL program can ACCEPT the correct control.

    This change is only available in COBOL objects compiled for Version 5.2 or later and run with a Version 5.2 or later runtime. COBOL objects compiled with Versions 5.1 or earlier will still exhibit the old behavior, even if they are run with a Version 5.2 or later runtime.

  • The resolution of the ACCEPT BEFORE TIME timer has been substantially increased in Version 5.2. In rare cases, this could affect existing programs. To forestall any such problems, the runtime automatically uses the pre-5.2 resolution when running pre-5.2 objects and objects compiled for pre-5.2 compatibility (e.g. -C51).
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 5.0

The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 5.0.

Compiler Changes

Two compilation switches provide compatibility with Version 5.0:

-C50 | Causes the compiler to generate code according to the rules used by Version 5.0.
-Z50 | Creates object code that can be run with a Version 5.0 runtime.

Runtime Changes

  • In versions prior to 5.1, a CMD-ACTIVATE event would be generated only if there was an active ACCEPT statement running to receive it. Under some (unusual) circumstances, this could cause the runtime to enter a state where it believed the wrong window was active.

    In Version 5.1, this rule is modified so that CMD-ACTIVATE events are generated unless the window generating the event is in the process of being built. It no longer matters whether or not an ACCEPT statement is running. The new rule is needed to prevent the first ACCEPT in each window from immediately terminating due to a queued CMD-ACTIVATE event (generated by the window's own creation).

    Note: This is a change in the rules for when CMD-ACTIVATE is generated. As a result, it is possible for CMD-ACTIVATE events to occur in cases where they did not previously. In order to prevent this change from adversely affecting a working program, the new rule is used only for programs compiled for 5.1 semantics. This means that the 5.1 runtime will not behave any differently in this regard when executing programs compiled with 5.0 or earlier (or compiled with the -C50 switch). You can explicitly enable this rule by setting the configuration variable ECN1660 to 1 or disable it by setting it to 0. When the variable is set to -1 (the default), the program semantics apply as described above.
  • In Version 5.1, you can assign pop-up menus to labels. This change has the side-effect that labels are now aware of mouse-clicks where previously they were not. This matters only if you happen to have a label and another control (like a push button) that overlap. Previously, the push button would always get all the mouse events. In Version 5.1, the label could start getting them. This can prevent the push button from working (because it is not "seeing" the mouse clicks). Normally, you would not overlap controls, but it can happen unintentionally if the label contains only spaces.

    To correct this situation, make the controls not overlap or make label invisible instead of setting it to spaces if you want to hide it. You can inhibit this change by compiling for 5.0 or earlier semantics (this also means that you must compile for 5.1 or later semantics if you want to attach a pop-up menu to a label).

  • The configuration variable V42_TRANSPARENT is now obsolete. Transparent labels always appear transparently. If this variable is set in your environment or in the runtime configuration file, it is simply ignored.
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 4.3

Version 5.0 of ACUCOBOL-GT contains significant changes in the internal workings of both the compiler and runtime. The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 4.3.

Licensing Changes

With the Version 5.0 release, the licensing procedure for extendproducts has been changed. All products still require a license file, but you no longer need a separate license disk to install your products. Instead, you will receive a pair of alphanumeric strings (keys) that must be entered to activate your software. See Getting Started with ACUCOBOL-GT for more information.

Compiler Changes

Two compilation switches provide compatibility with Version 4.3:

-C43 | Causes the compiler to generate code according to the rules used by Version 4.3.
-Z43 | Creates object code that can be run with a Version 4.3 runtime.
  • Prior to Version 5.0, the width of a printer cell was based on the average width of the selected printer font. Now, the width of a printer cell is computed in the same way that cells are computed for the screen, based on the width of the "0" (zero) character. Note that proportional fonts may contain wider characters. This may affect the horizontal placement of a bitmap on the page, the width of bitmaps and margins if they are specified in cells, and the number of columns reported by the WINPRINT-GET-PAGE-LAYOUT call. See the WIN$PRINTERin Appendix I, Library Routines, for details.
  • The Arial font shipped with Windows 98 Version 2 is different from the Arial font shipped with earlier versions of Windows and Windows NT. The new font has a character width of 35 pixels, instead of the previous 23 pixel width. This can cause field overlap or screen distortions in programs that rely on the size of the Arial font. If you do not want to adjust your applications to accommodate the new wider version of the Arial font, a new configuration variable, OLD_ARIAL_DIMENSIONS will force the runtime to use the 23 pixel measurement. See Appendix H Configuration Variables for details.
  • In previous versions, the command-line option for the logutil utility date filter d had problems comparing dates when the specified 2-digit year was 00 or greater. Now, logutil requires that years be specified in a 4-digit format. If you enter a year less than 1900, logutil will report logutil: use 4 digit year specification.
  • Starting with ACUCOBOL-GT 5.0 release, the compiler no longer automatically assigns the "MULTILINE" style to an entry field with LINES value of 2 or greater. Although Version 5.0 correctly handles cases compiled with 4.x versions, in order for that to happen you need to specify an appropriate source-compatibility flag (such as -Z43). Note that the flag is not required if you had explicitly set the MULTILINE style in your 4.x-version program.

Runtime Changes

  • In previous versions, the UNIX runtime would use the name of the user that started a runtime process to identify the user to acushare and count the number of processes a user was executing simultaneously. In Version 5.0, the user is defined as a unique terminal name. Each terminal is counted as a unique user and requires one user license. Background processes adopt the name of the terminal which started them. There are 1024 processes per user allowed for each terminal name.

    acushare 5.0 can be used with older runtimes and will report the maximum processes and processes per user settings for those runtimes as long as they have different serial numbers from the 5.0 runtime installed on the machine. If a Version 4.3 and a Version 5.0 runtimes on the same machine have the same serial number, acushare 5.0 supports both but does not report maximum processes or processes per user.

  • Microsoft has changed standard input stream handling in Internet Information Server 4.0. When you are running with the -f option or when the A_CGI environment variable is set, the runtime reads only the number of bytes set in the CONTENT_LENGTH environment variable by the web server. The runtime no longer waits for an end of file condition.
  • The runtime no longer differentiates between UNIX-4 and UNIX-V in the OPERATING-SYSTEM field of the SYSTEM-INFORMATION structure. Instead, it reports UNIX for all UNIX operating systems.
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 4.2

The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 4.2.

Compiler Changes

Two compilation switches provide compatibility with Version 4.2:

-C42 | Causes the compiler to generate code according to the rules used by Version 4.2.
-Z42 | Creates object code that can be run with a Version 4.2 runtime.

The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 4.2.

  • The default ACCEPT size for a numeric-edited field now includes a space for the sign only if the field is signed. You can set the program to include a space for an implied sign by compiling for semantic compatibility with an earlier version of ACUCOBOL-GT using a compilation switch in the command line.
  • One of the general rules for screen control entry has been modified: Prior to Version 4.3, an ACCEPT statement used to set ACCEPT-CONTROL to 1 if the event was a "message" ("MSG...") event. Starting with version 4.3, if the reason for entry is a "notify" ("NTF...") event, ACCEPT-CONTROL is set to 1; otherwise it defaults to 0).
  • The -Fo option has replaced the -Zo option. Both compiler options produce the same results, but the -Zo option should be considered obsolete.
  • The compiler option - Rw has been expanded to allow, in addition to reserved words, the suppression of some non-reserved words, such as control names (e.g., entry-field, label) or property names (e.g., max-text, bitmap-number). If you tell the compiler to suppress a non-reserved word, however, it will do so with the following warning: Unknown reserved word: non-reserved word.

Runtime Changes

The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 4.2.

  • If a program is in the event procedure for an active control, and the control activates and subsequently destroys another control, the control whose event procedure is executing is reactivated. In previous versions, the "active" control was left in an undefined state.
  • When using the library routine WIN$PRINTER with the 32-bit runtime, the newer Windows PageSetup dialog box will appear by default. If you wish to use the old 16-bit PrintSetup dialog box, you must use the operation code WINPRINT-SETUP-OLD.
  • In all releases up to and including the ACUCOBOL-GT 4.2 release, anytime you created an Entry-Field control with a LINES value of 2 or greater, it was treated as a multiline entry field. In version 4.3, this rule is modified so that a LINES value of 2 or greater implies MULTILINE only if the CELLS phrase is not also used or implied.

Calling COBOL from Other Languages

  • Windows 95/98 and NT sites that are calling COBOL routines from C with the "cobol" routine need to be aware of a change to the calling convention. The calling convention has changed from __cdecl (the C calling convention) to __stdcall (the Pascal calling convention, used by Windows API routines). This was done to make integration with Visual Basic and Delphi more straightforward.

    Programs that call the "cobol" routine must be sure to include sub.h (included with ACUCOBOL-GT in the lib directory). This includes a declaration of the "cobol" routine for all platforms. This ensures that you use the correct calling convention when calling the "cobol" routine. If you have established routines that call "cobol", these must be recompiled in order to use the new calling convention.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 4.1

Two compilation switches provide compatibility with Version 4.1:

-C41 | Causes the compiler to generate code according to the rules used by Version 4.1.
-Z41 | Creates object code that can be run with a Version 4.1 runtime.
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 4.0

Two compilation switches provide compatibility with Version 4.0:

-C40 | Causes the compiler to generate code according to the rules used by Version 4.0.
-Z40 | Creates object code that can be run with a Version 4.0 runtime.

The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 4.0.

  • The compiler option -Zx (while still supported) has been replaced with -Fx. Both options cause the compiler to generate XFD files in a new format (XFD Version 4). Version 4 XFD files include a list of all of the fields contained in a file's record description, including group items and REDEFINES items. Items that are excluded from use by the rules of XFD generation are marked with a condition number of 999. Versions of Acu4GL and alfred prior to Version 4.1 require the old format of XFD files. If you want to generate XFDs in the old format, use the new compiler option -Fx3 or use -Z40.
  • The compiler option -Za now causes the compiler to test table indexes against the upper bound of the current table size when you compile for Version 2.4 or later semantics. Thus, if you have an OCCURS DEPENDING ON table that could hold 20 elements physically, but whose current size is 10 elements, the runtime will produce an error if you access elements 11--20 when compiling with -Za.

    Compiling for Version 2.3 or earlier (-C23) causes the compiler to test against the physical upper bound.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 3.2

Two compilation switches provide compatibility with Version 3.2:

-C32 | Causes the compiler to generate code according to the rules used by Version 3.2.
-Z32 | Creates object code that can be run with a Version 3.2 runtime.

The following paragraphs describe changes that can affect programs originally written with ACUCOBOL-GT Version 3.2.

  • Under 32-bit Windows, the user name returned in ACCEPT FROM SYSTEM-INFO is now retrieved from the system instead of from the USER environment setting. The name retrieved is the user's login name. This change could affect installed programs in that a user's name may appear differently than it did with earlier runtimes. The runtime does not provide a way to override this change, because doing so would present a security hole under Windows NT.
  • The default compile output file has been changed from cbl.out to {source-name}.acu. This could affect the behavior of scripts used to compile programs. Also, if no CODE-SUFFIX is specified, the runtime tries a suffix of .acu before trying a blank suffix. This could affect programs if you happen to use a blank suffix for objects and have files named with the .acu extension in the same directory as your objects. To work around this, simply set CODE-SUFFIX explicitly in your configuration file. To specify a blank extension, simply add CODE-SUFFIX with no value.
  • AUTO termination on a graphical screen now acts as if the Tab key had been pressed.

    Suppose a user is interacting with a screen that has an entry field followed by a radio button group. Normally, when the user tabs to the radio button group, control passes to the group leader (that is, the button that is selected, or the first button in the group, if none is selected). Prior to Version 4.0, if the entry field were defined with the AUTO style, then when the field was full, control passed to the very next item in the Screen Section. This might be a radio button that was not the group leader.

    The Version 4.0 runtime has been enhanced to treat this AUTO termination case as if the "Tab" key had been pressed, so that control passes to the "group leader" when the entry field becomes full.

    If the program is compiled with the -C## option, where ## is a number less than 40 (such as -C32 or -C31), this enhancement is disabled, and the behavior reverts to that of earlier versions.

  • Starting with Version 4.0, the compiler uses a new rule when moving LOW-VALUES or HIGH-VALUES to a numeric item.

    Under standard COBOL, a MOVE of LOW-VALUES or HIGH-VALUES to a numeric item has undefined effects. Prior to Version 3.0, ACUCOBOL would treat these items as if they had legal numeric values, convert them accordingly, and move the result. This often results in a meaningless value, but can be useful for some numeric data items.

    USAGE DISPLAY types, for example, would end up with LOW-VALUES in their storage. Non-DISPLAY types ended up with odd values. Some other COBOL systems would produce a value of zero in binary numeric items when LOW-VALUES were moved to them.

    In order to improve compatibility with these systems, ACUCOBOL-GT was changed in Version 3.0 so that a MOVE of LOW-VALUES to a numeric item moved ZERO to that item. There were two concerns with this: (a) the compiler did not do this in every case, and (b) this changed the behavior of some programs that were functioning under prior versions of the runtime.

    Starting with Version 4.0, the compiler uses the following rule when moving LOW-VALUES or HIGH-VALUES to a numeric item:

    When the constant LOW-VALUES or HIGH-VALUES is the source of a MOVE statement whose destination is numeric, the move is treated as if the destination were defined as class alphanumeric. This results in the memory occupied by the numeric item being filled with LOW/HIGH-VALUES.

    This rule tends to produce the best results of both the pre-3.0 and post-3.0 behavior -- the useful cases work out the same. Also, this rule expresses what most programmers believe should happen.

    This new rule is used only for programs compiled for 4.0 semantics (this is the default). If you use the -C## or -Z## option to compile for earlier semantics, the compiler does not use this rule, and the runtime adjusts to use the semantics that were in place for version ##. For example, if you compile with -C24, then the runtime will use the pre-3.0 semantics for the meaning of MOVE LOW-VALUES to a numeric item.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 3.1

Two compilation switches provide compatibility with Version 3.1:

-C31 | Causes the compiler to generate code according to the rules used by Version 3.1.
-Z31 | Creates object code that can be run with a Version 3.1 runtime.

The following section describes changes that can affect programs originally written with ACUCOBOL-GT Version 3.1.

  • The Vision Version 4 indexed file system uses a dual file format. Version 4 files cannot be read by ACUCOBOL-GT Version 3.1 or earlier runtimes. For a complete description of Vision, see Indexed Files Vision in the ACUCOBOL-GT User's Guide. Note that runtimes beginning with Version 3.2 are able to read any version of Vision file. To continue to use Vision Version 3 indexed files, see the entry for the V_VERSION configuration variable in Appendix H.
  • Recursive PERFORMs are automatically enabled when you compile your programs with Version 3.2 or later. Recursive PERFORMs are required for the use of EVENT PROCEDURES. In very rare cases, this can affect the flow of control in a program. A program would be affected, for example, if it performs paragraph "A", which performs paragraph "B" and then returns from "A" before returning from "B". If you want, you can disable recursive PERFORMs with either the -C31 (or earlier) flag or the -Zr0 flag.
  • Beginning with Version 3.2, data in a list box column can no longer overflow into the adjacent column (causing all columns to shift to the right). Instead, the data is truncated if it doesn't fit in the allotted space for that column. There is no way to prevent this change.
  • Beginning with Version 3.2, list box columns have a small buffer between them, so that the columns do not merge together when they are full. This can cause partial loss of the last character in a column if your columns are very close together. To correct this, set the configuration variable COLUMN-SEPARATION to zero.
  • Beginning with Version 3.2, in environments that use system messages, such as Microsoft Windows, message processing during file I/O operations is no longer performed by default. This is due to problems that can occur in programs that use multithreading, modeless windows, or event procedures. To restore the old behavior, use the FILE-IO-PROCESSES-MESSAGES configuration variable. Enabling message processing should only be done under certain conditions. For a complete description, see the entry for FILE_IO_PROCESSES_MESSAGES in Appendix H.
  • The IS NUMERIC test for COMP-3 fields is more rigorous beginning with Version 3.2. In prior versions, any bit pattern was allowed in the sign field. The runtime treated any bit pattern, other than 0x0D, as indicating a positive value. Starting with Version 3.2, only signs of 0x0C, 0x0D and 0x0F are treated as legal values in the IS NUMERIC test. These values are the normal values for signs (there are two positive values to match various other COBOLs). You can suppress this change by compiling for compatibility with Version 3.1 (i.e. -C31).
  • Beginning with Version 3.2, the DESTROY handle-1 statement now sets the value of handle-1 to NULL if the statement succeeds. In prior versions the value of handle-1 was not changed. You can prevent the setting of handle-1 to NULL by compiling for compatibility with Version 3.1 (i.e. -C31).
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 2.4

The following section details changes that can affect programs originally written with ACUCOBOL-85 Version 2.4.

  • Support for 16-bit MS-DOS compilers and runtimes has been eliminated. Support remains for 32-bit (Extended) DOS systems and for 32-bit and 16-bit Windows systems. This change does not affect the formal capabilities of ACUCOBOL-GT, but it does have some practical consequences.

    Primary among these is that ACUCOBOL-GT no longer supports the dynamic loading and linking of assembly language routines. Version 2.4 runtimes (and earlier) for 16-bit MS-DOS provided support for calling assembly language routines directly with the CALL verb. In ACUCOBOL-GT Version 3.1 and later, if you want to use an assembly language routine you must link it directly into the ACUCOBOL-GT runtime in the same way that C routines are included.

    Users who require 16-bit DOS support should use Version 2.4.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 2.3

The following section details changes that can affect programs originally written for the Version 2.3 ACUCOBOL-85 compiler.

Compiler Changes

Beginning with Version 3.0, a new directory structure is created when you load your media. See the READ_ME file for the location of all extendfiles. Note that the new directory structure may not be compatible with scripts you have in use at your site.

Runtime Changes

If you relink the runtime, be aware that the Makefile in the "lib" subdirectory leaves the rebuilt runtime in the "lib" subdirectory. This change allows you to rebuild the runtime system and test it without overwriting the original runtime, and without renaming it. However, be sure to move the rebuilt runtime to the "bin" subdirectory, or move it to a directory in your path.

Check the RELEASE notes to verify the compatibility of older versions of extendinterfaces to alternate file systems such as Btrieve and INFORMIX.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 2.1

The following section details changes that can affect programs originally written for the Version 2.1 ACUCOBOL-85 compiler.

Compiler Changes

For machines using MS-DOS, ACUCOBOL-GT Version 3.0 requires MS-DOS version 3.0 or later. ACUCOBOL-85 Version 2.1 required only MS-DOS version 2.0.

Beginning with Version 3.0, ACUCOBOL-GT fully supports 64-bit machines without restriction. At the current time, the only machine that fits this classification is the DEC Alpha machine running OSF (Open/VMS also runs on the Alpha machine, but it runs in 32-bit mode). Version 2.1 of ACUCOBOL-85 also runs on 64-bit machines, but it contains some restrictions.

In Version 2.1, the following items are restricted:

  • Since RETURN-CODE is only 32 bits in size, it cannot hold a long value properly. This makes it inappropriate for receiving pointer or long return values from a C subroutine.
  • USAGE POINTER data items are also 32 bits, and so cannot actually hold a real machine address.
  • The direct C interface cannot be used for pointer or long parameters since the 2.1 compiler does not allow you to pass a 64-bit item BY VALUE.

Beginning with Version 3.0, these restrictions do not apply. We made certain changes to the rules of ACUCOBOL-85, beginning with Version 2.3. These changes affect only a few existing COBOL programs, but they have the potential of causing a working program to stop working. Because of this, there is a method available to inhibit these changes. See the -Dw option in Data Storage Options.

The specific changes are:

  • USAGE POINTER data items now occupy 8 bytes instead of 4 bytes. This allows a USAGE POINTER item to hold a full address on any machine architecture. On a machine that is smaller than 64 bits, only the first 32 bits of the POINTER item are used. The rest of the item is treated as FILLER.

    This is the change that is most likely to affect existing programs. You can be affected if you have POINTER data items as part of a group item, since the group item's size will change. If you have this case, then either allow the size of the group to change and adjust any external references or redefinitions of it, or use the option described below to keep POINTER items in 4 bytes.

  • The special register RETURN-CODE was changed from PIC S9(9) COMP-5 to USAGE SIGNED-LONG. See USAGE Clausein the ACUCOBOL-GT Reference Manual for a description of SIGNED-LONG. This change allows RETURN-CODE to hold 64-bit values on 64-bit machines, and so it can be used to hold any return value from a called routine. This change should not affect any existing program.
  • You may now pass 8-byte data items BY VALUE to a called routine. If you are on a 16- or 32-bit machine, then only the low-order 32 bits are actually passed. On a 64-bit machine, all 64 bits are passed. This provides a portable solution to the problem of passing long data. This change does not affect any existing programs.

For related topics, see

  • Data Storage Options in the ACUCOBOL-GT User's Guide.
  • USAGE Clause in the ACUCOBOL-GT Reference Manual.
  • CALL RETURNING syntax in the entry for the CALL statement in Procedure Division Statements of the ACUCOBOL-GT Reference Manual.
  • RETURN-CODE Changes below.

RETURN-CODE Changes

As discussed in the previous section, the special register RETURN-CODE has changed. In versions of ACUCOBOL-85 prior to 2.3, RETURN-CODE was implicitly defined as:

77  RETURN-CODE   PIC S9(9)  COMP-5, EXTERNAL.
In Version 2.3 and later, it is defined as:
77  RETURN-CODE   SIGNED-LONG, EXTERNAL.

This change should have no noticeable effect on existing code, but it allows RETURN-CODE to be used sensibly on 64-bit machines. This change is inhibited if you compile for compatibility with a prior version of ACUCOBOL-85. For example, if you use -C21 to maintain source compatibility with Version 2.1, then this change does not take place.

There is also a special register that redefines RETURN-CODE called RETURN-UNSIGNED. Its definition is:

77  RETURN-UNSIGNED
    REDEFINES RETURN-CODE  UNSIGNED-LONG, EXTERNAL.

You should use RETURN-UNSIGNED when handling pointer or unsigned long data types that are returned from an external routine. If you use RETURN-CODE in these cases, you can get errors if the value is large enough to set the high-order bit of RETURN-CODE. The problem is that these values are negative when interpreted as signed values, therefore COBOL will remove the sign if you move them to an unsigned destination.

The RETURN-UNSIGNED special register is not defined if you compile for compatibility with prior versions of ACUCOBOL-85.

Runtime Changes

For machines using MS-DOS, ACUCOBOL-GT Version 3.1 and later versions do not run under standard 16-bit DOS but do support 32-bit Extended DOS. Version 3.0 requires MS-DOS version 3.0 or later. ACUCOBOL-85 Version 2.1 required only MS-DOS version 2.0.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 2.0

The following section details changes that can affect programs originally written for the Version 2.0 ACUCOBOL-85 compiler.

Compiler Changes

The -Ca compiler flag was still available in Version 2.0, but was not documented. (It was synonymous with the -Va flag.) Since Version 2.1, -Ca has a new and different meaning. So, you must now use -Va to cause opposite video intensities to be used for ACCEPT and DISPLAY statements.

Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 1.5

The following sections detail changes that can affect programs compiled with the Version 1.5 ACUCOBOL-85 compiler.

Compiler Changes

Note: All of the changes described in this section can be inhibited with the -C5 compile-time option, which causes the compiler to use ACUCOBOL-85 Version 1.5 semantics. The -Z5 option (which produces object files compatible with Version 1.5) will also inhibit these changes.
  • Since the release of Version 2.0, indexed, relative, and binary sequential files can have variable-length records. You might have syntax in your existing programs that implies variable-length records, even though your files on disk are fixed-length. If this is the case, you will receive error 39 when you try to open your existing files after recompiling your programs. This type of error will occur most frequently with files that have multiple records declared for them (more than one 01 entry in the file's FD). In order to prevent the error, compile with either the -C5 or -Cf compile-time option. The -Cf option causes the compiler to assume fixed-length records for these kinds of files.
  • The function of the RETURN-CODE special register was expanded in Version 2.0. This register is used to return a status value to the operating system or calling program. The return status of the SYSTEM library routine is also stored here. This can cause an existing program to behave differently if you set RETURN-CODE to a particular value and then call the SYSTEM routine. This can also cause programs that return zero to the operating system (the default value of RETURN-CODE) to return a non-zero value if they call SYSTEM. Note that this change affects programs only after they have been recompiled with Version 2.0 or later. You can inhibit the change with the -C5 compile-time option.
  • The CALL PROGRAM verb behaves differently since Version 2.1. If you used CALL PROGRAM under Version 1.5, use the -C5 option to maintain compatibility when you compile with Version 3.0. Also note, that since Version 2.1 the -Ci option implies the recursive PERFORM switch -Zr.
  • Under Version 1.5, the-Vc compile-time option caused ACCEPT statements that entered numeric fields to be treated as if the CONVERT phrase were specified for them. Since Version 2.1, this option also implies the CONVERT phrase for numeric edited fields.
  • Under Version 1.5, the WRITE and REWRITE verbs did not check the length of the record for legality. Since Version 2.1, an illegally sized record returns error 44.
  • The option -Zz causes spaces in a USAGE DISPLAY numeric item to be treated as the value zero. Because this action was formerly handled by the SPACES-ZERO runtime option, if you have a mix of object files from Version 3.0 or later and from any versions prior to Version 2.0, then you should use -Zz to create the new objects and should also add the SPACES-ZERO option to your runtime configuration file to handle prior versions.

Runtime Changes

The changes described in this section take effect when you install the latest runtime system.

  • Important: Beginning with Version 2.0 and continuing through Version 3.1, the ACUCOBOL-GT runtime was delivered with Version 3 of the Vision file system. Version 3.2 and later versions are delivered with Vision Version 4. The Vision file system is used on all ACUCOBOL-GT implementations except VAX systems running VMS and Alpha Micro systems running AMOS. Vision Version 3 introduced a new file format that is portable across all machines, and is (generally) smaller. Vision Version 4 introduced a dual file format, in which the indexes are kept in a separate file from the data. When you are installing the latest version of the runtime system, you have three choices:
    1. You can leave your existing data files in place. ACUCOBOL-GT will continue to use them. However, any new data files created by Version 3.2 or later will have the new Vision Version 4 format. This is the default behavior.
    2. You can convert all of your files to the new format with the rebuild option of vutil. In particular, running vutil -rebuild -3 on your data files will convert them to the Vision Version 3 format, and running vutil -rebuild -4 on your data files will convert them to the Vision Version 4 format.
    3. You can continue to use the old format for all of your data files, including any newly created ones. To do this, add the line:
      V-VERSION 2

      to your cblconfig file. This will ensure that any newly created files use the old format.

  • The default method of editing numeric and numeric edited fields on the screen changed slightly when Version 2.0 was released. In Version 1.5, when a user was editing an existing value, the user could type over the value. This left any trailing digits in place, and sometimes caused confusion. Beginning with Version 2.0, if the user starts typing over an existing field, the current contents are erased first. If the user instead starts by editing the field (by using an arrow key or an editing key), then the default value remains on the screen and the user can modify it.

    This behavior is controlled by the NUMERIC-UPDATES and EDITED-UPDATES configuration options. If you already have the following entries in your configuration file, then the default change will not affect you. If you do not have these entries and want to maintain exact compatibility with Version 1.5, then you should add the following to your configuration file:

    SCREEN  Numeric-Updates=Converted
Edited-Updates=Converted
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 1.4

The following sections describe changes that can affect programs compiled with the Version 1.4 ACUCOBOL-85 compiler. These are the same changes that occur when you move from Version 1.4 to Version 1.5.

Compiler Changes

The following changes can affect programs when they are re-compiled. Note that all of these changes can be suppressed by the -C4 compile-time option, which causes the compiler to use Version 1.4 semantics. Also note, that the -Z4 compile-time option (which produces 1.4 compatible object files) will also inhibit these changes. Note that there are several important changes, especially if you are using VAX COBOL compatibility mode. You should use -C4 until you can evaluate the extent to which these changes affect your programs.

  • Note: Under Version 1.4, USAGE BINARY data items are treated as identical to USAGE COMP-1 data items. Since Version 2.1, USAGE BINARY items are treated as defined by the ANSI standard. This results in data items that are different except for data items described as PIC S9, S9(2), S9(3) or S9(4). If you have any USAGE BINARY data items in files, you will need to specify "-C4" to maintain compatibility with your existing files until you can change your programs.
  • Note: The internal format of COMPUTATIONAL data items is different under the following circumstances:
    1. You are using VAX COBOL compatibility mode; or
    2. You use the -Zb or -Db compile-time options.

    Under previous versions, a data item that fit one of these conditions is stored as a COMP-1 data item if it is small enough (PIC S9(4) or smaller), otherwise, it is stored as a COMP-2 data item. Since Version 2.1, these items are stored as BINARY. This is the same as COMP-1 for the small data items, but is different for the larger ones. If either of these cases applies to your programs, and you store COMPUTATIONAL data items in files, then you should use -C4 to maintain compatibility with your files until you can modify your programs.

  • In previous versions of ACUCOBOL-85, COMP-3 data items are always treated as signed. They are also rounded up to an odd number of digits. Beginning with Version 2.0, they act as described by their picture clauses.
  • In Version 1.4, COMP-6 data items always have an even number of digits. Since Version 2.1, they have the number of digits specified in their picture clauses.
  • Since the release of Version 2.1, specifying CONVERT on a DISPLAY of a numeric edited data item causes that item to have its leading spaces stripped and causes the item to be justified according to the rules applied to numeric data items. Under Version 1.4, output conversion of numeric edited items has no effect.
  • In Version 1.4, specifying the CONTROL KEY phrase or the ON EXCEPTION Key-Name phrase for an ACCEPT statement implies automatic termination of a field when that field is filled. Since the release of Version 2.1, this behavior is specified by the AUTO phrase. Because of the nature of the ACCEPT rules, this change does not affect programs using RM/COBOL compatibility mode.
  • Versions of ACUCOBOL-85 prior to 2.1 do not support file errors 14 or 24 for relative files when the relative key data item is too small to hold the relative record number. Version 2.1 and all later versions return the appropriate error in this case.
  • Since Version 2.1, assigning a file to the device name PRINTER without explicitly assigning an external file name causes the file to be assigned to "PRINTER" when you are using VAX COBOL compatibility mode. Under previous versions, the file is assigned to the same name as its internal file name.
  • In Version 1.4, the SYNCHRONIZED clause has no effect. Since Version 2.1, data item synchronization occurs.
  • The rules for the meaning of the ON EXCEPTION phrase of the ACCEPT statement have changed. For versions prior to Version 2.0, this phrase catches numeric conversion errors. If the Key-Name option is used, it also catches exception keys. Since Version 2.0, it always catches exception keys and does not catch numeric conversion errors (these errors are handled automatically by the terminal manager). Specifying -C4 or -Ve2 retains the original meaning of this phrase. Programs using RM/COBOL compatibility mode are unlikely to be affected by this change.
  • Since Version 2.0, closing a window moves the cursor to the position it occupied when that window was created. Before Version 2.0, the cursor moved to the home position of the restored window.
  • Many new reserved words have been added since Version 2.0. Most of these can be treated as user-defined words through use of the new -Rs and -Ri compile-time options. A few new words not covered by these options have also been added. If they conflict with your current programs, you can individually treat them as user-defined words with the -Rw option.
  • Several compile-time options were renamed in Version 2.0. The original names are still supported, however, so this change does not affect existing programs or compile scripts, except for the -Ca option described earlier.

Runtime Changes

The following changes occur when the latest runtime is installed.

  • The default meaning of the Tab key has changed. Under Version 1.4, the Tab key is an exception key that has a key value of 9. Beginning with Version 2.0, the Tab key is a termination key with a key value of 9. The only difference is that under the previous version, the Tab key is allowed only when exception keys are allowed and it causes the ON EXCEPTION phrase to execute. If you depend on this behavior, you can add the following line to your configuration file:
         KEYSTROKE Exception=9 ^I

    This change was made so that the Tab key could function as a next field key when you are using the Screen Section.

  • Several other keys were redefined in Version 2.0 for use with the Screen Section. These changes do not affect existing programs, however, because the new defaults have the same effects as the old ones when used with field-level ACCEPT statements.
  • The maximum number of files that can be opened by the runtime was reduced from 64 to 32 in Version 2.0. This was done to save memory. If you need more than 32 files, you can set the maximum to any value you want (up to 255) with the MAX_LOCKSconfiguration option. See Appendix H for details.
  • A subtle change has been made in the processing of the user's environment. In previous versions, an entry in the user's environment always takes precedence over an entry in the runtime's local environment. Beginning with Version 2.0, an entry in the user's environment takes precedence at the time the local environment is initially created. This change allows the SET ENVIRONMENT verb to have an affect on an entry initially defined in the user's environment.
  • Since Version 2.1 the cursor does not leave the field when the field is filled. Instead, it stays in the last character position and inhibits further data entry. This difference is cosmetic, but if you prefer the method used by previous versions, you can add the following line to your configuration file:
    KEYBOARD  Cursor-Past-End=Yes
Parent topic: Appendix C. Changes Affecting Previous Versions


Changes Affecting Version 1.3

If you are updating directly from Version 1.3, then several changes affect you. These changes are the same as those you encounter when you move from Version 1.3 to Version 1.4, except that the current runtime does not support linked object files produced by the Version 1.3 compiler.

Compiler Changes

The following changes affect programs when they are re-compiled. You can specify the -C3 option to suppress these differences. Note that specifying -C3 also implies the -C4 flag discussed above. You can also produce Version 1.3 object files with the -Z3 compile-time option.

  • Under Version 1.3, a line sequential file accessed by a program compiled with RM/COBOL compatibility mode automatically has short records padded with spaces to fill the record area. Beginning with Version 2.0, only line sequential files with automatic trailing space removal have their records padded with spaces. This change was made to accommodate the behavior of RM/COBOL-85.
  • A numeric data item that is the object of a DISPLAY statement with the CONVERT option is left-justified when RM/COBOL compatibility mode is used under any version since 2.1. In Version 1.3, the data item is right-justified. This change was made to accommodate the behavior of RM/COBOL-85.
  • Under Version 1.3, the default SIZE of an ACCEPT field is always equal to the number of assignable character positions in the data item, plus 1 if the data item is signed, and plus another 1 if the data item contains digits to the right of the decimal point. Beginning with Version 2.0, this amount is used only if the destination is numeric or edited and the CONVERT phrase is used. Otherwise, the default SIZE is the physical size of the receiving field. The difference is subtle and is unlikely to affect any current programs. This change was made to better simulate the behavior of RM/COBOL.
  • In RM/COBOL compatibility mode, a field accepted with the ECHO phrase is redisplayed in a converted form only if the UPDATE phrase is also used. In Version 1.3, the field is redisplayed in a converted form only if the CONVERT phrase is used. This change was made to better simulate the behavior of RM/COBOL.
  • Certain line sequential files now have automatic trailing-space removal applied to them. This depends on the device type specified in the file’s ASSIGN clause. This will generally not affect existing programs except that files with automatic trailing space removal may not be opened for I/O (due to the unpredictable record size). This affects only those programs that do REWRITEs on sequential files. If you have a program that does REWRITEs on a sequential file, you should check to make sure that the device type is not one that specifies automatic trailing space removal. See File-Control Paragraph in the ACUCOBOL-GT Reference Manual for more information.

Runtime changes

The following changes occur when the latest runtime is installed. These changes can generally be compensated for by various configuration options.

  • Since Version 3.0, the runtime does not support linked object files produced by the Version 1.3 compiler. If you have any linked object files, then you must convert them to the library format introduced in Version 1.4. Note that the normal object files produced by the 1.3 compiler are still supported.
  • The default keyboard configuration has changed. The new default is very similar to the default RM/COBOL configuration. Also, the KEY-MAP and EDIT-MODE configuration variables are no longer supported. These have been replaced by the more powerful KEYBOARD and KEYSTROKE entries. Most users of Version 1.3 ACUCOBOL-85 reconfigured the keyboard with the KEY-MAP variable to simulate the RM/COBOL keyboard. Most will not need to make any changes since this is the new default.
  • Users who used the default ACUCOBOL-85 keyboard under Version 1.3 will have to reconfigure the keyboard to meet the Version 1.3 standard. Other users may need to make minor changes to match their previous configuration. See Redefining the Keyboard in the ACUCOBOL-GT User’s Guide for details on the new default configuration and the KEYBOARD and KEYSTROKE variables. Also, see the sample configuration file supplied with the compiler.
  • Under Version 1.3, files opened with the EXTEND phrase are automatically created if they do not exist. Beginning with Version 2.1, they are not. This change was made to match the ANSI standard. You can maintain the Version 1.3 behavior by setting the configuration variable EXTEND-CREATES to 1 in the configuration file.
  • In VAX COBOL compatibility mode, a missing file opened for I/O is not automatically created. Under Version 1.3, it was. This change was made because the most recent release of the VAX COBOL compiler was changed this way.
  • Several VAX COBOL file status codes have been changed. This change was made to match changes made to the VAX COBOL compiler.
  • When you are using the RM/COBOL-85 or RM/COBOL version 2 file status codes, a corrupted indexed file is now returned as file error 98 instead of file error 30.
  • A single DISPLAY may now wrap around more than one screen row. Under Version 1.3, lines are truncated. If the 1.3 behavior is desired, set the configuration variable WRAP to the value 0.
  • An ACCEPT or DISPLAY statement that references a row past the bottom edge of the window now causes that window to scroll. Under Version 1.3, the statement is (largely) ignored. You can cause a similar effect by setting the configuration variable SCROLL to 0.
  • The syntax of the COLOR-MAP configuration variable has changed slightly. See Adding Color in the ACUCOBOL-GT User’s Guide for more information.
  • Object files produced by versions of ACUCOBOL-85 prior to Version 1.3 may not be executed by the latest runtime system. These programs must be recompiled with a 1.3 (or later) compiler. This change was made to reduce the size of the runtime system and to improve its performance. You can use the -info option of ccbl to locate object files created by a pre-1.3 version of ACUCOBOL-85. These will be object files that contain a vers value of 2 or less.
Parent topic: Appendix C. Changes Affecting Previous Versions


Appendix D. Compiler Error Messages

  • Introduction
  • List of Errors
Parent topic: Appendices


Introduction

The ACUCOBOL-GT compiler produces a wide range of informative messages, including both Errors and Warnings. An Error message is more severe than a Warning and, unlike a Warning, inhibits production of an object file by the compiler.

The following list contains the Error messages produced by the compiler. In many cases, the meaning of an error message is clear from the message itself. Where this is not the case, a brief explanation follows the message. In this listing, the term %s represents some string that will replace the %s before you see the message. In most cases, the string will be a user-defined value, such as a file name, a record name or an item name.

The listing is in alphabetical order. Note, however, that the first few pages list messages that begin with dynamically generated strings. The alphabetical ordering ignores the string (which replaces the %s in the listings). Therefore, if an error message starts with a dynamic string, look it up in this list by using the generic portion of the message that follows the string.

Parent topic: Appendix D. Compiler Error Messages


List of Errors

$

$ELSE without a corresponding $IF
$END without a corresponding $IF

Either $ELSE or $END was encountered, and there is no corresponding $IF.

%

%s: a section and a paragraph have the same name

A section name may be the same as a data name, but must otherwise be a unique user-defined word.

%s and %s must be the same size
%s cannot be moved to ALPHABETIC
%s cannot be moved to ALPHANUMERIC
%s cannot be moved to ALPHANUMERIC EDITED
%s cannot be moved to NUMERIC
%s cannot be moved to NUMERIC EDITED
%s contains no input fields

You have attempted to ACCEPT a screen item that includes no TO or USING phrase.

%s: Data item > 64K illegal here
%s: data item exceeds 2GB

The maximum data item size in ACUCOBOL-GT is 2 GB. See Large Data Handling, in the ACUCOBOL-GT Reference Manual. For a list of compiler limits, see Limits and Ranges.

%s expected, %s found
%s: File record exceeds 64MB

The maximum record size allowed in ACUCOBOL-GT programs compiled to Version 6.0 object format or later is 64 megabytes. See Limits and Ranges for more information.

%s: File record exceeds 32K

The maximum record size allowed in ACUCOBOL-GT programs compiled to Version 5.2 or earlier object format is 32 kilobytes.

%s ignored for OPEN INPUT
%s: illegal level 77

Level-number 77 entries may not have subordinate items except for level 88 items.

%s: incorrect number of arguments
%s: incorrect size for KEY AREA

The KEY AREA must be in multiples of seven.

%s is ambiguous

The name here could be interpreted to be more than one thing.

'%s' is an invalid destination

Data cannot be stored in a literal value.

%s is not a KEY of %s

SEARCH ALL requires that the compared item be referenced in the KEY IS phrase in the OCCURS clause of the searched table.

'%1' is not a property or method of 'CLASS %2'
%s is not a START key of %s
%s is not numeric
%s: key must not be in a table

The data item specified in the KEY phrase of a SORT or MERGE statement may not be subordinate to an OCCURS clause.

%s may not be used as a CODE-SET

A Format 2 Alphabet entry may be used in a COLLATING SEQUENCE phrase, but not in a CODE SET phrase.

%s may not belong to %s

Key-table of the KEY AREA phrase of the SORT verb must name a data item that is not located in the record for sort-file.

In an INSPECT CONVERTING statement, the convert-string must be the same length as the compare-string.

'%1' must be a 'get' property of '%2'
'%1' must be a 'put' property or method of '%2'
%s must belong to %s

The data item specified in the KEY phrase of a SORT or MERGE statement must be a data item in the record description associated with sort-file.

%s: must have only one value for SEARCH ALL

A level 88 referenced in a SEARCH ALL statement may not specify a series or a range in its VALUE clause.

%s: needs INDEXED BY phrase in declaration

The subject of a SEARCH statement must be a data item that contains an OCCURS clause including an INDEXED BY phrase.

%s: no FALSE value defined

You cannot SET cond-name TO FALSE unless cond-name has a WHEN SET TO FALSE phrase associated with its defining level 88 entry.

%s not a key of %s
%s: not a table

The subject of a SEARCH statement must be a data item that contains an OCCURS clause including an INDEXED BY phrase.

%s not allowed here
%s not an ALPHABET name

You have attempted to use something in a place where an ALPHABET name must be specified. It has not been defined to be an ALPHABET name.

%s: not defined
%s was used in a $IF, but is not defined either with a level 78 item or
     with a "/CONSTANT" compile switch.
%s not unique in first 18 characters

You have compiled with the -Fx option. The object file was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

This message occurs if a field name is not unique within the first 18 characters. The "%s" is the name found. You can either change the field name or apply the NAME directive.

%s: Procedure name not unique

The paragraph or section you are trying to ALTER, GO TO, or PERFORM has been defined more than once in the program.

%s record larger than %s record

In the USING phrase of the SORT or MERGE statement, in-file records may not be larger than sort-file records. In the GIVING phrase, sort-file records may not be larger than out-file records.

%s: requires version %s runtime

Some compiler options (like -Z4 and -Z5) cause the compiler to generate an object file that can be run on a version of the runtime that is older than the compiler you are using. These compiler options won't allow you to compile new features that the old runtime can't handle. When you attempt to compile such features into an object file for an older runtime, this error will be produced.

%s: Screen name not allowed in this context

You have attempted to use a form of the ACCEPT or the DISPLAY verb that does not allow the use of a screen name from the Screen Section.

%s subject to DEPENDING ON phrase

If the source or receiving item for a screen entry has an OCCURS clause, it may not include the DEPENDING phrase.

%s: unknown XFD directive

You have compiled with the -Fx option. The object file was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

The compiler did not recognize the directive you used. The %s is the directive found. Check for a typographical error.

*** %s overflow ***

This table currently allows %s entries

Sorry, you cannot make this table any bigger!

or

You can increase this with the "-T%s" option

For example, you might try "-T%s %s"

The compiler uses several internal tables to which it has given an arbitrary maximum size. Your code requires a greater table size than the default. This message tells you which table maximum has been exceeded and whether you can try recompiling with an increased size. The tables are:

Table | Compile Flag | Default Value
Identifiers/statement - the maximum number of items in each statement | td | 4096
Subscripts/statement - the maximum size for OCCURS | te | 256

The compiler always suggests double the default value in the error message. Because higher values increase table size (using more memory), the values should not be set any bigger than they need to be.

A

ACCEPT FROM DATE only returns two-digit year data
ACCEPT FROM DAY only returns two-digit year data
ALL expected
ALL ignored here
ALL index not allowed here
alphanumeric value expected
ALTER para must start with GO TO: %s
Ambiguous identifier: %s

The identifier here could be interpreted to be more than one thing. If two group items use the same field name and the field is referred to in the program, the field name must be qualified by the name of the next higher group item with a unique name.

Ambiguous symbol: %s
Arithmetic expression expected
AT value must be 4 or 6 digits

B

Bad CHART STATUS definition
Bad CRT STATUS definition
Bad CURSOR definition
Bad picture
Bad picture for DATE: keyname

You have compiled with the -Fx option. The object file was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

The PICTURE in a DATE directive must be six or eight bytes in length, either alphanumeric or numeric with no sign.

Bad SCREEN CONTROL definition
Badly formed condition
Badly formed ID: %s

See User-defined Words in the ACUCOBOL-GT Reference Manual for information on rules for COBOL Words.

Badly formed number: %s

See User-defined Words for information on the rules for Numeric literals.

BY CONTENT parameters exceed maximum size

For Version 7.0 and earlier, the maximum parameter size is 64K. For later versions, the maximum limit is 2GB.

BY expected

The REPLACE statement and the REPLACING phrase require the word BY.

BY VALUE parameter %s illegal size
BY VALUE parameter %s illegal type
BY VALUE parameter %s mis-aligned
BY VALUE parameter may not be a literal
BY VALUE parameter must be an integer

C

Can't recover from earlier error, Good bye!
CELL phrase used inconsistently

The CELL phrase appears in either the LINE or CLINE phrase, but not in both. Or, the CELL phrase appears in either the COL or CCOL phrase, but not in both. The CELL phrase must be specified in each of the LINE/CLINE or COL/CCOL phrases (or omitted from the pair).

Class already specified

The same category of data may not be specified more than once in the REPLACING phrase of an INITIALIZE statement.

Class name not allowed here: %s
Clause repeated
COMP-X/N item too large
Compilation aborted
Compiled screen description too large
Compiler error: Picture
Condition name not allowed here: %s
Conditional expression expected
Configuration: %s

D

Data item exceeds 2GB

The maximum data item size allowed in ACUCOBOL-GT programs is 2 GB. See Limits and Ranges for a list of compiler limits, .

Data item exceeds 64K

The maximum data item size allowed in ACUCOBOL-GT programs compiled to Version 5.2 or earlier object format is 32 kilobytes.

Data item not allowed here: %s
Data-item: Redefined data item with value moved

The compiler generates this error when it detects that a data item with value, already written into the object code, is being redefined too large for the current data segment. If compiled, the resulting COBOL object would attempt to force the runtime to write to memory it has not allocated, likely resulting in a crash.

Data missing from key segment keyname

You have compiled with the -Zx option. The object file was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

Some part of the named key could not be placed in the dictionary. This usually occurs because of filler. For example:

01  my-record.
    03  my-key.
        05  filler    pic xx.
        05  field-1   pic xx.

If my-key is declared as a record key, you will receive this error because the area of the key described by filler is not included in the dictionary. To correct this error, ensure that every character that is part of the key is included in some field that is part of the dictionary. Use an XFD to give a field name to each filler, to ensure that fillers are included.

01  my-record.
    03  my-key.
*(( xfd name=myfiller ))
        05  filler   pic xx.
        05  field-1  pic xx.
Dest may not be edited: %s
Different number of SYMBOLIC names and values

There must be a one-to-one correspondence between occurrences of name and number in the SYMBOLIC CHARACTERS clause of the SPECIAL-NAMES paragraph.

Directive word too long: keyname

You have compiled with the -Fx option. The object file was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

With one exception, the words contained in a directive, including field names, cannot exceed 30 characters. The value of a WHEN directive may consist of up to 50 characters. You have exceeded the limit.

Disk full
Duplicate ACCESS
Duplicate ASSIGN
Duplicate ENTRY point name: %s

The ENTRY point name has already been used in this program.

Duplicate interface '%s'
Duplicate NOT %s phrase

Various NOT phrases may be used in the context of specific statements (READ ... NOT AT END, COMPUTE ... NOT ON SIZE ERROR). The compiler has encountered more than one such NOT phrase in a statement.

Duplicate ORGANIZATION
Duplicate paragraph name: %s

The paragraph or section you are trying to ALTER, GO TO, or PERFORM has been defined more than once in the section.

Duplicate RECORD KEY
Duplicate STATUS

E

edited item too large

The maximum edited data item size in ACUCOBOL-GT is 255 bytes.

ELSE, END-IF or '.' required after NEXT SENTENCE
END-PERFORM required

The compiler has encountered code in which a scope delimiter is required for a PERFORM statement.

Entry for product 'compiler' in file '%2' is corrupt

The license file contains garbled information about the compiler product. The compiler cannot be executed until the license file has been repaired. Contact Technical Support.

Error file name is the same as the source name

Your ccbl command has instructed the compiler to name one of its output files with the same name you've given for the source code file.

Error: input file is Vision format

You have specified a Vision format file as input to vutil -load. The source file must be the name of the binary, relative, or line sequential file. See Loading a File for more information.

Errors found, size information suppressed
EVALUATE nesting level exceeded

The maximum depth of EVALUATE statement nesting is 10 levels.

Evaluation version - expires %1/%2/%3
Exception handlers require recursion (-Zr)
EXIT SECTION outside of SECTION

EXIT SECTION must be used within a SECTION.

Expecting condition after NOT
EXTERNAL file in SAME AREA illegal
EXTERNAL in REDEFINES

The REDEFINES clause and the EXTERNAL clause may not be applied to the same data item.

EXTERNAL name must be unique

The same name may not be given to more than one file or data item that is declared EXTERNAL within a program.

Extra segment exceeds 64K

The extra segment is that part of the object file that contains descriptors and other miscellaneous elements. This category is restricted to 64 KB. The main factor here is the number of different items that are referenced in the Procedure division.

F

FD already defined for file
Field xxx causes duplicate database data

This is a warning message that can appear if you compiled with the -Fx option. The data dictionary was built, and the interface will operate correctly. The warning informs you that your record definition should be restructured. Your current definition is set up in such a way that:

  • you have overlapping key fields, and
  • both keys must be represented in the database as separate items.

The interface will handle this situation correctly. It will keep the overlapping keys updated simultaneously, so that they always have the same value. However, the warning alerts you that you have the same data represented twice in the database. This is dangerous, because someone at the site might access the database via SQL and accidentally change only one of the keys.

Here's an example of the problem, and a description of how to correct it (the example assumes that both key-1 and key-2 have been declared as keys):

01 order-record.
   03  key-1.
       05  field-a         pic x(5).
       05  field-b         pic 9(5).
       05  key-2
       redefines field-b   pic x(3).

This example will generate the warning message.

Because key-2 is a key, it must also be represented in the XFD. It doesn't correspond exactly to any other data field, so it must be entered as a separate field in the XFD. In the COBOL view of the file, key-1 and key-2 overlap. But the requirements of XFD storage force the same data (known to COBOL as field-b) to be physically represented twice in the XFD. Any updates to the data from any ACUCOBOL-GT program will correctly update both fields. Updates from outside of ACUCOBOL-GT carry no such guarantee.

In this example, you can correct the situation by breaking field-b into two columns, so that key-2 corresponds exactly to another data field:

01 order-record.
   03  key-1.
       05  field-a           pic x(5).
       05  field-b.
           07  field-b1      pic x(3).
           07  field-b2      pic 9(2)
       05  key-2
          redefines field-b  pic x(3).
Figurative constant not allowed: %s

A figurative constant (zero, space, quote, etc.) cannot be used in this context.

Figurative constant not allowed here: %s
File %s in multiple areas

The named file appears in more than one SAME RECORD AREA clause.

File %s undefined

A file named in the I-O-CONTROL paragraph must be defined by a SELECT clause in the FILE-CONTROL paragraph.

File must be a SORT file
FILLER cannot be EXTERNAL
Floating-point literal not allowed here
Floating-point VALUE not allowed here
FOOTING larger than page size
FOOTING must be > 0
FROM/TO/USING error

FROM, TO, and USING can be used only once each in a particular screen item description. USING cannot be used with either FROM or TO in the same description.

Function argument %s must be alphanumeric
Function argument %s must be numeric

G

GIVING data item for file %s is too small
GROUP expected after USE

You have compiled with the -Fx option. The object file was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

The use group directive must include both words.

I

ID greater than 60 characters: %s...

%s is truncated to 60 characters.

Identifier expected, %s found
Identifier unresolved: %s OF %s

An attempt to qualify an identifier, as in "field of record", failed. Check the spelling of the qualifier.

Illegal ACCESS

SEQUENTIAL is the only ACCESS MODE legal with ORGANIZATION SEQUENTIAL.

Illegal arithmetic expression
Illegal BLANK ZERO

The BLANK WHEN ZERO clause can be used only for numeric or numeric edited elementary items. The picture of the item may not include "*" or "s".

Illegal class condition
Illegal clause(s) for sort file
Illegal color value

The FOREGROUND-COLOR and BACKGROUND-COLOR phrases take a literal in the range 0-7.

Illegal COMPRESSION value

The COMPRESSION factor may not be greater than 100.

Illegal condition
Illegal hex literal

Hexadecimal literals must consist of the digits "0"-"9" or "A"-"F".

Illegal indicator: '%s'

The indicator area of a COBOL line may contain " ", "-", "*", "$", "/", "D", or, in Terminal mode, "\D".

Illegal INITIALIZE item: %s

The destination may not contain a RENAMES clause.

Illegal JUSTIFIED clause

The JUSTIFIED clause can be applied only to alphabetic and alphanumeric data items. It must be applied to an elementary item, rather than to the group item.

Illegal KEY phrase

The KEY phrase of a READ statement can be used only with ORGANIZATION INDEXED files and cannot be used with a READ NEXT or a READ PREVIOUS.

Illegal level for OCCURS

The OCCURS clause may not be used on a level 01 or a level 88 item.

Illegal level number

A level 77 item cannot be included in the File Section or in the Screen Section. The Screen Section allows only levels 1-49 and level 78.

Illegal level number: %s
Illegal OCCURS value

In a Format 1 OCCURS, the table-size must be more than zero. Illegal or missing ASSIGN variable of %s

Illegal or missing BOTTOM variable of %s
Illegal or missing DEPENDING ON variable of %s
Illegal or missing FOOTING variable of %s
Illegal or missing KEY variable of %s
Illegal or missing LINAGE variable of %s
Illegal or missing PADDING variable of %s
Illegal or missing STATUS variable of %s
Illegal or missing TOP variable of %s
Illegal parameter: %s
Illegal parameter: literal

Generated by the compiler if low-values or other figurative constants are passed to ActiveX or COM methods or properties as parameters where the method or property expects a by reference parameter: This is the same error message you get when passing a figurative constant as a USING parameter in a CALL statement. One way to tell that the ActiveX/COM method expects a by reference parameter is by viewing the entry in the COPY file for that control or object. If the type has BYREF or if the numeric value divided by 16384 is odd, then you may not pass a figurative constant.

Illegal picture: %s
Illegal POINTER: %s
Illegal receiver for source type: %s

The compiler has encountered an illegal MOVE.

Illegal REDEFINES
Illegal RENAMES
Illegal replacement size: %s

In an INSPECT REPLACING statement, the replace-string must be the same length as the target-string.

Illegal SD clause: %s
Illegal sign condition

The sign condition can be applied only to an arithmetic expression.

Illegal SIGN/USAGE for file with CODE-SET
Illegal source type for CONVERSION
The compiler will allow MOVE WITH CONVERSION only of alphanumeric items.

Illegal statement in current declarative

Occurs when a program attempts to execute a disallowed statement in the context of a USE FOR REPORTING declarative or a file declarative that has been triggered by a status 22 for a file open with BULK-ADDITION. In both of these cases, the declarative is triggered as part of the file operation (instead of after the operation completes) and several restrictions apply. The program may not perform any file operations or start or stop any run units (including chaining). In addition, the program that contains the declarative may not perform an EXIT PROGRAM.

Note: The program continues running after printing this statement (halting the program at this point would corrupt the data file).

This error message indicates a programming error that should be corrected. There is no way to disable the error message. You can find the offending statement by running the program under the debugger. When the statement executes, the runtime will break to the debugger with this message and place the cursor at the statement.

Illegal table size: %s

Your compiler command line has specified an illegal value for a user-resizable table ( -ta, -tb, etc.). See the internal table list near the beginning of this topic.

illegal USAGE
Inconsistent picture
INDEXED key not in record: %s

The key to an Indexed record must be defined within the record.

INDEXED key outside of smallest record: %s

In an Indexed file with variable record size, the offset of the end of the key must be within the bounds of the smallest possible record size. Multiple record definitions (01 levels) within a file description may generate a variable length record file.

Indexing not allowed in this context
INSPECT TRAILING syntax error
Interface definition '%s' not found
*** Internal error #%s ***

The compiler has encountered a syntax error for which it does not have a useful descriptive message. Anytime you get such a message from the compiler, notify Technical Support. If we are already aware of your particular syntax problem, we can tell you what to fix in your source. We may even have a more recent version of the compiler that detects the error more elegantly. If we have not been made aware of this oversight, your call will allow us to find and correct it.

INTO identifier may not be reference modified

In a STRING ... INTO statement, the destination may not be in the form "... INTO dest-field ( 2 : 4 )". If you want to start modifying the destination field at a position other than the leftmost, use the POINTER phrase.

Invalid CODE-SET file type

CODE-SET may be specified in the FD of sequential files only.

Invalid CLSID '%s'
Invalid directive syntax
The $SET directive was used incorrectly.
Invalid GIVING data item for file %s
INVALID KEY illegal in this context

The INVALID KEY phrase of the DELETE statement may not be used with a file declared ACCESS MODE SEQUENTIAL. The INVALID KEY phrase of the REWRITE statement may not be used for ORGANIZATION SEQUENTIAL or ORGANIZATION RELATIVE files if either uses ACCESS MODE SEQUENTIAL.

Invalid switch number: %s

The switch named in the SPECIAL-NAMES paragraph must be one of SWITCH-1 through SWITCH-26, SWITCH 1 through SWITCH 26, or SWITCH "A" through SWITCH "Z".

Invalid syntax in COPY statement

K

Key bigger than 250 bytes: %s

The maximum indexed key size in ACUCOBOL-GT is 250 bytes.

KEY must be first: %s

More than one KEY IS phrase is allowed in each OCCURS clause. If one KEY IS phrase references the data-name of the entry that contains the OCCURS clause, it must be the first KEY IS phrase in the clause.

KEY not found in table: %s

The key named in the KEY IS phrase of the OCCURS clause must be contained within the table.

L

Large REDEFINES of a regular variable with a value: %1 redefines %2
LENGTH ignored in this context
License file '%s' inaccessible

The license file cannot be located. The message displays the name of the license file that the compiler is trying to locate. The compiler cannot execute without a valid license file.

License file '%s' is invalid
LINAGE must be > 0
LINAGE required for END-OF-PAGE processing
LINAGE requires SEQUENTIAL organization
LINAGE-COUNTER is a reserved data item
LINKAGE not listed in USING: %s

An item defined in the Linkage Section is not referenced in the USING phrase of the Procedure Division statement.

Listing file name is the same as the source name

Your ccbl command has instructed the compiler to name one of its output files with the same name you've given for the source code file.

literal expected
Literal must be alphanumeric
Literal too long

Prior to version 1.5, an ALL literal not associated with another data item had to be a single character.

M

May not be a SEQUENTIAL file

A Format 1 DELETE statement may not be used on a file with ORGANIZATION SEQUENTIAL. May not be alphanumeric: %s

May not be alphanumeric edited: %s
May not be edited: %s
May not be floating-point: %s
May not be numeric: %s
May not be numeric edited: %s
May not INQUIRE on style %s

You may not use a style name in the INQUIRE statement. You can only inquire the value of an element of a control. Because styles do not have values, using a style name with INQUIRE is not meaningful.

May not modify or invoke ActiveX Controls in DISPLAY
May not specify both LINES and SIZE

While it is acceptable to specify both height and length for a BOX, a LINE can have only one dimension.

meaningless WHEN phrase
MERGE illegal in DECLARATIVES
Mismatching OCCURS structure

If an OCCURS clause applies to a screen entry with TO or USING, the receiving item must have an OCCURS of the same number. With FROM, the source item must have an OCCURS of the same number or no OCCURS at all.

Missing ')'
Missing ASSIGN clause
Missing closing quote

A quoted string must have both opening and closing quotes.

Missing continuation line quote

If a continued line ends with a nonnumeric literal without a closing quotation mark, the first non blank character in Area B of the continuation line must be a quotation mark.

Missing COPY file: '%s'

The filename specified after the word COPY is not found in the directory in which it is expected. Consider whether it is spelled correctly, or check your COPYPATH environment variable.

Missing COPY filename

The filename specified after the word COPY is not found. Consider putting the file name in quotes.

Missing directive
The $SET directive was used incorrectly.
Missing END-%s

Several statements in COBOL, among them IF, SEARCH, PERFORM, and EVALUATE, can have their scope delimited by the END- (END-IF, END-SEARCH, END-PERFORM) phrase. The compiler has encountered code in which such a scope delimiter is required.

Missing exponent

A digit in the range 0-9 must follow the E in a floating point literal.

Missing field name after WHEN

You have compiled with the -Fx option. The object file was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

A valid field name, or the word OTHER, must be specified with the when directive.

Missing KEY phrase in definition: %s
Missing library filename

The OF phrase of the COPY statement has no pathname specified.

Missing operand
Missing or invalid object expression
Missing PARA/SECTION" "Can't recover, good bye!
Missing period
Missing RECORD KEY clause
Missing SELECT for this file
Missing switch number

The switch named in the SPECIAL-NAMES paragraph must be one of SWITCH-1 through SWITCH-26, SWITCH 1 through SWITCH 26, or SWITCH "A" through SWITCH "Z".

Missing value
Missing WHEN phrase

The SEARCH statement and the EVALUATE statement always require a WHEN phrase.

Missing '=' in XFD directive

You have compiled with the -Fx option. The object file was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

The name directive requires an "=" sign. The when directive requires a comparison operator.

Mnemonic name required

Each system-name in the SPECIAL-NAMES paragraph must be associated with a mnemonic name.

Modification of %s not allowed

LINAGE-COUNTER may never be explicitly modified by the program.

Modification of screen item

It is not legal to ACCEPT or DISPLAY an item defined in the Screen Section using reference modification.

More subscripts needed: %s

An item subordinate to an OCCURS clause has been referenced with a number subscripts or indexes less than its level of nesting.

More than 64K of parameters illegal for this CALL
Multiple pictures
Multiple USE for %s mode

The INPUT, OUTPUT, I-O, and EXTEND phrases may each be specified in only one USE statement in a Procedure Division.

Multiple USE for file: %s

A particular file may not appear in more than one USE statement in a program.

Multiple USE for OBJECT
Must be a GROUP item: %s

Both the source and the destination of a MOVE CORRESPONDING statement must be group items.

Must be alphanumeric: %s
Must be in Working-Storage or Linkage: %s
Must be INDEXED file: %s
Must be integer: %s
Must be level 01 WORKING-STORAGE for EXTERNAL

A data item can be declared EXTERNAL only if it is defined in the Working Storage section. The item must be at level 01 or level 77. (Except for the ability to take subordinate items, level 77 is often implied where level 01 is specifically mentioned.)

Must be SEQUENTIAL

A file must be ORGANIZATION SEQUENTIAL to CLOSE REEL, CLOSE UNIT, CLOSE NO REWIND, WRITE NO CONTROL, or WRITE ADVANCING.

Must be size 1 in this context: %s
Must be USAGE DISPLAY: %s
Must not be subscripted: %s

N

Native character specified twice, ordinal value = %s

When you specify an ALPHABET in the SPECIAL-NAMES paragraph, each character may appear only once.

Needs DELIMITED BY to use COUNT
Needs DELIMITED BY to use DELIMITER
NEXT/PREVIOUS illegal for RANDOM ACCESS
No entry for product 'compiler' in file '%2'

The license file does not contain an entry for the compiler product. The compiler cannot be executed until the license file is corrected. Contact Technical Support.

No FD for %s
No records defined for file
No SELECT for file: %s
Non-native object file produced
Not a condition-name: %s

Only level 88 items may be SET to TRUE or FALSE.

Not a file: %s

The USE statement must include INPUT, OUTPUT, I-O, and EXTEND or the name of a file described in the Data Division.

Not a record of a file: %s
Not a record of a SORT file: %s

The RELEASE statement may act only on the records of sort files.

NOT, END-ACCEPT or '.' required after NEXT SENTENCE
Null ENTRY point name

The program has used "" as an ENTRY point name.

number too large

The maximum numeric data item size in ACUCOBOL-GT is 18 digits.

Number too large: %s
Numeric literal not allowed here
NUMERIC test is constant, because of the type of variable being
     tested

The compiler issues this warning in cases where the item being tested is a binary item. This test should always return TRUE for binary items, since binary items can't be non-numeric. You can optimize your COBOL program by removing constant tests.

numeric value expected
Numeric VALUE not allowed here

O

Object file name is the same as the source name

Your ccbl command has instructed the compiler to name one of its output files with the same name you've given for the source code file.

Object wrong type for subject

If the subject of an EVALUATE statement is, or can be evaluated to be, TRUE or FALSE, the object must be a phrase that is, or can be evaluated to be, TRUE or FALSE (e.g., EVALUATE TRUE WHEN a = b ..., or EVALUATE a > b WHEN FALSE ...). Otherwise, the object must be something that would balance the subject in a conditional expression (e.g., EVALUATE field1 WHEN "a" ...).

OCCURS DEPENDING illegal in Screen Section
OCCURS DEPENDING in OCCURS illegal
OCCURS DEPENDING must be last in group: %s
Offset too large: %s

When you are using a subscript of the form (data-item + integer), the integer can be no greater than 32767.

Only 1 level of OCCURS allowed

Nested OCCURS are not permitted in the Screen Section.

Operation has no effect
ORGANIZATION clash
*** Out of Main Memory! ***

P

Pic 'V' illegal in COMP-X/N

COMP-X and COMP-N items can be defined with only '9' or only 'X' symbols.

PICTURE and/or VALUE clash in Screen Section

The PICTURE and VALUE clauses may not both be specified for the same screen description entry, either explicitly or implicitly by the use of FROM, TO, or USING.

Picture required for floating-point in this context

A screen item must have a picture. If you are using a FLOAT item with USING or FROM, give it a picture within the Screen Section.

Picture too long

The maximum picture string in ACUCOBOL-GT is 100 characters.

Pixel AT value must be 8 digits

When using the AT verb together with the PIXEL verb, 8 digits are mandatory to specify the position, or the variable being used must be a PIC 9(8).

Positive integer required

The value for this field must be greater than zero and include no decimal fraction. A subscript or index must be a positive integer.

PREVIOUS illegal for sequential file

This refers to ORGANIZATION SEQUENTIAL.

Procedure name not allowed here: %s
Procedure name required

GO TO must always be followed by a paragraph or section name.

Program code exceeds 1MB

The maximum size of the code portion of an ACUCOBOL-GT object file is 1 MB. The size of the program code is largely determined by the size of the Procedure division of the program. If you cannot streamline the instructions in the Procedure division to fit within this restriction, you might split the logic into two programs, one called by the other.

Program data exceeds 32 segments

The 1 MB restriction on the program data is monitored in terms of segments. The factors determining this size are as described above.

Program data exceeds 64K

The maximum size of the data portion of an ACUCOBOL-GT object file for any version prior to 1.5 is 64 KB. Thus, this restriction might be encountered when you are using the -Z4 compiler option. Starting with Version 1.5, the maximum program data size is 1 MB. The size of the data is basically the sum of the sizes of the items in the data division (including File Descriptions) and of the literal strings used within the program (including the Procedure Division).

Program-wide CURSOR already defined

The CURSOR phrase of the ACCEPT statement may not be specified if a CURSOR phrase is specified in the program's Configuration Section.

R

Radio Buttons cannot have array elements in a VALUE or USING phrase

This error is generated at the occurrence of a radio button control in the screen section whose VALUE (or USING) is an array. This is not allowed due to the internal functionality of how data is copied to COBOL data items once the screen section terminates.

Record belongs to SORT file: %s

WRITE and REWRITE statements may not apply to records of files described with an SD rather than an FD in the File Section.

REDEFINES not allowed in Screen Section
REDEFINES of an OCCURS item illegal under ANSI
Reference modification of numeric function is illegal
Reference modifier illegal in this context
Reference modifier out of range

Using reference modification, either the start position is beyond the end of the referenced item, or the calculated end position would be.

RELATIVE key in record: %s

The key to a Relative record must be defined outside of the record.

RELATIVE Key is required

A relative key must be indicated if ACCESS DYNAMIC or ACCESS RANDOM MODE is specified.

RELATIVE key must be PIC 9: %s
REMAINDER may not be used if any operand is External Floating-Point
Repeated OCCURS
REPLACING LEADING/TRAILING requires literals
REPLACING not allowed on nested COPY
RETURN-CODE is a reserved data item

S

Screen item subject to OCCURS

It is not legal to ACCEPT or DISPLAY an item defined in the Screen Section with or subordinate to an OCCURS clause.

SEARCH ALL must have only one WHEN
SEARCH statement missing WHEN phrase
A SEARCH statement must have a WHEN phrase.
SECTION required

The use of Declaratives is part of a Format 1 Procedure Division. The Format 1 Procedure Division requires the use of Sections.

Segment %s exceeds 64K

When you are using segmentation, an individual segment may not be larger than 64 KB.

Segments must be in order

When segment numbers are used on the SECTION header, they must be used in ascending order.

SELECT for this file inconsistent with a SORT file
SIZE or LINES phrase required

A DISPLAY LINE statement requires that either the length or height be specified.

Sorry, multiple TALLYING counters not supported
Sorry, this compiler may not be used on a stand-alone basis

Some of our customers are licensed to include a limited-use version of the ACUCOBOL-GT compiler in their software application for sale to their own customers. Any attempt to activate such a compiler from the command line, rather than from inside the application, will produce an error.

SORT file not allowed here

A Sort file is a file described with an SD rather than an FD in the File Section.

SORT illegal in DECLARATIVES
Source name too long: %s
Special name not allowed here: %s
START illegal for RANDOM ACCESS files
START illegal for SEQUENTIAL files
Statement too large at code address %s

The maximum Paragraph size in ACUCOBOL-GT is 32767 bytes. (A statement cannot be larger than the maximum paragraph.)

Status name not allowed here: %s
STATUS variable %s should be X(2)
String must be 1 character in context: '%s'
Style name not allowed here
Subscript may not be table item: %s

A data item used as a subscript may not itself be subordinate to an OCCURS clause.

Subscript out of bounds: %s

The subscript or index on a table entry is less than 1 or greater than the number in the OCCURS that defines the table.

Subscript required: %s

An item subordinate to an OCCURS clause has been referenced without a subscript or index.

Symbol not in LINKAGE: %s
Symbol not in WORKING-STORAGE: %s
SYMBOLIC name expected

The SYMBOLIC CHARACTERS clause of the SPECIAL-NAMES paragraph must include at least one "name" naming a symbolic character.

SYMBOLIC value must be between 1 and %s

The number in the SYMBOLIC CHARACTERS clause of the SPECIAL-NAMES paragraph must be in the range of ordinal positions in the alphabet being referenced.

SYNC not allowed in Screen Section
Syntax error
Syntax error: %s
syntax error scanning %s

T

This constant not allowed: %s
This evaluation copy of ACUCOBOL has expired!
Please call customer support if you would like to upgrade to a full
     version or if you wish to extend your evaluation period.
TO value too small in OCCURS

The maximum value cannot be less than the minimum value for a Format 2 OCCURS clause.

Too few parameters: %1 required, %2 found
Too many ALPHABETS (max 100)
Too many delimiters (max 30)
Too many destinations (max 30)
Too many destinations (max 50)
Too many ENTRY points (max 65536)
The program has more than 65536 ENTRY statements.
Too many ENTRY point pages (max 65536)

It would take more than 65536 object file pages to write out the ENTRY point table.

Too many errors, compilation aborted

The compiler has a limit on the number of errors it will track on any one compile cycle. Please correct some of the errors encountered to this point, and try again.

Too many EXTERNAL items (max 256)
Too many files open by the current process

Vision returns this system error (30) when its attempt to create an additional file segment is stopped because the limit imposed by MAX_FILES has been reached. Error code is one of the following: 94,10; 97; or 97,10; depending on the setting of FILE-STATUS-CODES.

Too many INITIALIZE destinations (max 50)
Too many key segments (max 6)
Too many keys (max 120)
Too many level 01 linkage items (max 255)

The program has more than 255 level 01 linkage items.

Too many operands (max 60)
Too many parameters: %1 is the maximum, %2 found
Too many REPLACING operands (max %s)

For Version 7.0 and earlier, the maximum number is 30. For later versions, the maximum limit is 256.

Too many sending items (max 100)
Too many source items (max 50)
Too many subscripts: %s

An item subordinate to an OCCURS clause has been referenced with a number of subscripts or indexes greater than its level of nesting.

Too Many <symbols> (max <symbols>))

Generated if compiling for debug and the number of symbols is larger than 65535, or the number of bytes in all symbols is larger than 1048560. This latter limit only happens if compiling with -Znn with nn < 80.

Too many SYMBOLIC CHARACTERS in this clause (max 100)
Too many table dimensions (max 15)
Too many USING parameters (max 255)

U

Unable to find ''%s''
Undefined data item: %s

The data item referred to has not been defined in the Data Division.

Undefined procedure: %s

The paragraph or section you are trying to ALTER, GO TO, or PERFORM has not been defined in the program.

Undefined procedure: %s OF %s

The paragraph or section you are trying to ALTER, GO TO, or PERFORM does not exist in the program within the qualifier you have specified for it.

Unknown mode: %s

As part of our compatibility with other dialects of COBOL, the ACUCOBOL-GT compiler allows the use of the RECORDING MODE clause. Only "F", "V", "S" and "U" modes are permitted.

Unknown reserved word: %s
Unknown special name: %s

The mnemonic-name in a Format 6 ACCEPT statement or in a Format 9 DISPLAY statement has not been defined in the Special-Names paragraph.

Unknown switch: %s

The switch named in the SPECIAL-NAMES paragraph must be one of SWITCH-1 through SWITCH-26, SWITCH 1 through SWITCH 26, or SWITCH "A" through SWITCH "Z".

Unmatched ELSE

The ELSE phrase must always be used in a one-to-one relationship with IF in an IF statement.

Unmatched END-%s

Several statements in COBOL, among them IF, SEARCH, PERFORM, and EVALUATE, can have their scope delimited by the END- (END-IF, END-SEARCH, END-PERFORM) phrase. Such END- phrases must exist in matched pairs with their companion verbs. The compiler has encountered such a scope delimiter, but found no matching verb preceding it.

Unmatched NOT %s phrase

Various NOT phrases may be used in the context of specific statements (READ ... NOT AT END, COMPUTE ... NOT ON SIZE ERROR). The compiler has encountered such a NOT phrase outside of its proper statement.

Unsupported operation
USAGE conflict
USAGE must be DISPLAY
USE statement missing
USING parameter <name> not aligned and may cause problems in the
     called subprogram

This is a warning message that can be generated if compiling with the -Wa option. This warns that a passed parameter is a group or is binary, and whose alignment is not an even multiple of the alignment specified by the -Da# option.

USING parameter <name> is not an 01-level item

This is a warning message that can be generated if compiling with the -W1 option. The ANSI COBOL standard requires that parameters passed to subprograms be 01-level items. ACUCOBOL-GT does restrict them as such; however, there are valid reasons for restricting their use. See Compiler and Runtime in the ACUCOBOL-GT User's Guidefor details on this warning message.

V

VALUE illegal on item > 64K
VALUE in EXTERNAL

External data items may not have a VALUE phrase.

VALUE in REDEFINES

A Format 1 VALUE clause may not appear on a data item that is subordinate to a REDEFINES clause.

Value must be 80 or 132

The DISPLAY SCREEN SIZE statement must specify either an 80-column or a 132-column display.

Value should be a name: %s

You have compiled with the -Fx option. The object code was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

This error occurs when the item to the right of an "=" should be a name and it isn't. For example, it would be an error to use a quoted string with the "name" directive: $XFD NAME="some text".

The "%s" in the message is the value found.

Value should be numeric: %s

You have compiled with the -Fx option. The object code was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

This error occurs when the item to the right of an "=" should be numeric and it isn't. The "%s" in the message is the value found.

Value should be a literal: %s

You have compiled with the -Fx option. The object code was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

This error occurs when the item to the right of an "=" should be a literal and it isn't. The %s in the message is the value found. A literal is either a quoted string or a numeric integer.

VALUE size error: %s

All literals used in a VALUE clause must have a value which falls within the range of allowed values for the item's PICTURE clause. Nonnumeric literals may not exceed the size of the item. Numeric items must have numeric literals. Alphabetic, alphanumeric, group, and edited items must have nonnumeric literals.

VALUE specified for group

When a VALUE clause is applied to a group item, no subordinate item may contain a VALUE clause.

Value too large for context: %s

The number you are using is too large. There are many cases in which 64 KB is the maximum size.

VALUE too long: %s

The maximum length for a floating point literal is 30.

VALUE type error: %s

All literals used in a VALUE clause must have a value within the range of allowed values for the item's PICTURE clause. Nonnumeric literals may not exceed the size of the item. Numeric items must have numeric literals. Alphabetic, alphanumeric, group, and edited items must have nonnumeric literals.

Variable file name requires "File" directive

You have compiled with the -Fx option. The object code was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

This message occurs when the compiler cannot assign a name to the .xfd file because the ASSIGN phrase for the file names a variable file name. In this case, you must use a file directive to name the .xfd file.

Verb expected, %s found

W

Warning: -Dcm ignored when using -Z%s

The data storage option -Dcm is being ignored because you are generating object code for a runtime version that does not support that storage convention.

Warning: -Dcn ignored when using -Z%s

The NCR sign coding convention indicated by -Dcn requires a Version 2.4 or later runtime. The -Dcn flag has been ignored by the compiler.

Warning: cannot generate native code from pre-5.0 object, '-Z%1' flag
     ignored
Warning: COLLATING SEQUENCE ignored for non-INDEXED files
Warning: Implicitly terminated verb: verb-name found with no END-verb-name

An explicit scope terminator is missing. This warning affects the following verbs: ACCEPT, ADD, CALL, COMPUTE, DELETE, DISPLAY, DIVIDE, EVALUATE, IF, MODIFY, MOVE, MULTIPLY, PERFORM, READ, RECEIVE, RETURN, REWRITE, SEARCH, START, STRING, SUBTRACT, UNSTRING, USE, WAIT, WRITE, and XML GENERATE and PARSE.

Warning: native code not supported on current host, '-n' ignored
Warning: PADDING CHARACTER ignored for non-SEQUENTIAL files
Warning: Paragraph Name found in Area B.
WHEN OTHER must be last

No other WHEN phrase may follow WHEN OTHER in an EVALUATE statement.

WHEN subject may not be reference modified

SEARCH ALL does not allow the compared item to be reference modified.

WHEN unexpected
WHEN variable xxx not found in record

You have compiled with the -Fx option. The object code was generated, but a data dictionary could not be built, for the reason listed below. Remove the error condition and recompile to obtain a data dictionary.

This happens if you have a when directive that mentions a variable that doesn't exist in the record.

WHEN, END-SEARCH or '.' required after NEXT SENTENCE
Writing %s code
Wrong number of parameters: %1 expected, %2 found
Parent topic: Appendix D. Compiler Error Messages


Appendix E. File Status Codes

  • Introduction
  • Table of Codes
  • Vision Secondary Error Codes for Error 98s
  • Transaction Error Codes
  • IBM DOS/VS Error Codes
Parent topic: Appendices


Introduction

ACUCOBOL-GT conforms to five different standards regarding the values of file status codes. These codes are those used by RM/COBOL-85 (ANSI 85), RM/COBOL version 2 (ANSI 74), Data General ICOBOL, VAX COBOL, and IBM DOS/VS COBOL. By default, ACUCOBOL-GT uses the RM/COBOL-85 set. You can change the current set by changing the configuration variable FILE_STATUS_CODES. See File Status Codes in the ACUCOBOL-GT User's Guide for more information.

The Table of Codes describes the various file status codes returned by each condition. Some of the status values in the table have a second two-character code listed. This code distinguishes between different causes for the same FILE STATUS code. You can obtain this second code value by calling the C$RERR ACUCOBOL-GT library routine. Where a second code is not listed, its value is 00.

For file systems that support READ PREVIOUS, wherever READ NEXT is mentioned, you may assume that READ PREVIOUS is also implied. An end of file for READ NEXT is analogous to a beginning of file for READ PREVIOUS.

Parent topic: Appendix E. File Status Codes
Parent topic: File Status Codes


Table of Codes

Regardless of which set of status codes is being used:

  • Any code that starts with a 0 is considered successful.
  • Any code that starts with a 1 is considered to be an at end condition.
  • Any code that starts with a 2 is considered to be an invalid key condition.
85 | 74 | Vax | DG | IBM | Condition
00 | 00 | 00 | 00 | 00 | Operation successful.
02 | 02 | 00 | 00 | 00 | The current key of reference in the record just read is duplicated in the next record. (read next)
02 | 02 | 02 | 00 | 00 | The operation added a duplicate key to the file where duplicates were allowed. (write, rewrite)
05 | 00 | 05 | 00 | 10 | Optional file missing. If the open mode is I-O or EXTEND, then the file has been created. This is also returned by DELETE FILE if the file is not found. (open, delete file)
07 | 00 | 07 | 00 | 00 | A CLOSE UNIT/REEL statement was executed for a file on a non-reel medium. The operation was successful.
0M | 0M | 0M | 0M | 00 | The operation was successful, but some optional feature was not used. For example, if you opened a file that specified an alternate collating sequence, but the host file system did not support that feature, then the open would succeed, but it would return this status.
10 | 10 | 13 | 10 | 10 | End of file. (read next)
14 | 00 | 14 | 00 | 00 | A sequential READ statement was attempted for a relative file, and the number of digits in the relative record number is larger than the size of the relative key data item. (read next)
21 | 21 | 21 | 21 | 21 | Primary key was written out of sequence, or the primary key on a rewrite does not match the last record read. This error occurs only for an indexed file open with the sequential access mode. (write, rewrite)
22 | 22 | 22 | 22 | 22 | Duplicate key found but not allowed. (write, rewrite)
23 | 23 | 23 | 23 | 23 | Record not found.
24 | 24 | 24 | 24 | 24 | Disk full for relative or indexed file. (write)
24/ 01 | 00 | 24/ 01 | 00 | 24 | A sequential WRITE statement was executed for a relative file, and the number of digits in the relative record number was larger than the size of the relative key data item. (write)
30/ xx 30/ xx 30/ xx 30/ xx 30 Permanent error. This is any error not otherwise described.

The secondary code value is set to the host system's status value that caused the error. See your operating system user manual for an explanation, and C$RERR in Appendix I.

34 | 34 | 34 | 34 | 34 | Disk full for sequential file or sort file. (write, sort)
35 | 94/ 20 | 35 | 91 | 93 | File not found. (open, sort)
37/ 01 | 95/ 01 | 37/ 01 | 91/ 01 | 93 | The file being opened is not on a mass-storage device which is required for the file type or the requested open mode. (open)
37/ 02 | 95/ 02 | 37/ 02 | 91/ 02 | 93/ 02 | Attempt to open a sequential file with fixed-length records as a Windows spool file.
37/ 07 | 90/ 07 | 39/ 07 | 91/ 07 | 93 | User does not have appropriate access permissions to the file. (open)
37/ 08 | 95/ 08 | 37/ 08 | 91/ 08 | 93 | Attempt to open a print file for INPUT. (open)
37/ 09 | 95/ 09 | 37/ 09 | 91/ 09 | 93 | Attempt to open a sequential file for I/O and that file has automatic trailing space removal specified. (open)
37/ 99 | 95/ 99 | 37/ 99 | 91/ 99 | 93/ 99 | A Windows or Windows NT runtime that is not network-enabled tried to access a file on a remote machine.
38 | 93/ 03 | 38 | 92 | 93 | File previously closed with LOCK by this run unit. (open)
39/ xx 94/ xx 39/ xx 9A/ xx 95 Existing file conflicts with the COBOL description of the file. (open)

The secondary error code may have any of these values:

  • 01 - mismatch found but exact cause unknown (this status is returned by the host file system)
  • 02 - mismatch found in file’s maximum record size
  • 03 - mismatch found in file’s minimum record size
  • 04 - mismatch found in the number of keys in the file
  • 05 - mismatch found in primary key description
  • 06 - mismatch found in first alternate key description
  • 07 - mismatch found in second alternate key description

The list continues in this manner for each alternate key.

41 | 92 | 41 | 91 | 93 | File is already open. (open)
42 | 91 | 42 | 92 | 92 | File not open. (close)
42 | 91 | 94 | 91 | 92 | File not open. (unlock)
43 | 90/ 02 | 43 | 92 | 23 | No current record defined for a sequential access mode file. (rewrite, delete)
44 97 44 92 21 Record size changed. The record being rewritten is a different size from the one existing in the file, and the file's organization does not allow this. (rewrite)

This status code can also occur if the record is too large or too small according to the RECORD CONTAINS clause for the file. (write, rewrite)

46 | 96 | 46 | 92 | 21 | No current record. This usually occurs when the previous operation on the file was a START that failed, leaving the record pointer undefined. (read next)
47/ 01 | 90/ 01 | 47/ 01 | 92/ 01 | 13 | File not open for input or I-O. (read, start)
47/ 02 | 91/ 02 | 47/ 02 | 92/ 02 | 13 | File not open. (read, start)
48/ 01 | 90/ 01 | 48/ 01 | 92/ 01 | 13 | A file that is defined to be access mode sequential is open for I-O, or the file is open for INPUT only. (write)
48/ 02 | 91/ 02 | 48/ 02 | 92/ 02 | 13 | File not open. (write)
49/ 01 | 90/ 01 | 49/ 01 | 92/ 01 | 13 | File not open for I-O. (rewrite, delete)
49/ 02 | 91/ 02 | 49/ 02 | 92/ 02 | 13 | File not open. (rewrite, delete)
93 | 93 | 91 | 94 | 93 | File locked by another user. (open)
94/ 10 | 94/ 10 | 97 | 97/ 10 | 93 | Too many files open by the current process. (open)
94/ 62 | 94, 62 | 39/ 62 | 92/ 62 | 93 | One of the LINKAGE values for this file is illegal or out of range. (open, write)
94/ 63 | 94/ 62 | 39/ 62 | 92/ 62 | 93 | Key not specified (specifying a table whose size is zero) in a SORT or MERGE statement
98/ xx | 98/ xx | 30/ xx | 9B/ xx | 93 | Indexed file corrupt. An internal error has been detected in the indexed file. The secondary status code contains the internal error number. The file should be reconstructed with the appropriate utility.
99 | 99 | 92 | 94 | 23 | Record locked by another user.
9A | 9A | 9A | 9A | 23 | Inadequate memory for operation. This most commonly occurs for the SORT verb, which requires at least 64K bytes of free space. (any)
9B 9B 9B 9B 23 The requested operation is not supported by the host operating system. For example, a deferred file system initialization failed, or a READ PREVIOUS verb was executed and the host file system does not have the ability to process files in reverse order. (any)

If you are using AcuXML, this error results when the program tries to open a file EXTEND or I-O. With AcuXML, programs are able to open files INPUT or OUTPUT only.

9C 9C 9C 9C 23 There are no entries left in one of the lock tables. The secondary error code indicates which table is full:
  • 01 - operating system lock table
  • 02 - internal global lock table (see the MAX_LOCKS configuration variable)
  • 03 - internal per-file lock table (see the LOCKS_PER_FILE configuration variable)
9D/ xx 9D/ xx 9D/ xx 9D/ xx 92 This indicates an internal error defined by the host file system. The xx is the host system's error value. This is similar to error 30, except that xx is specific to the host file system instead of the host operating system. For example:

  • 02 - In Acu4GL or AcuXML, 9D,02 indicates that an XFD file is corrupt. This could be the result of a parsing error.

  • 03 - In Acu4GL or AcuXML, 9D,03 indicates that an XFD file is missing. This could be the result of a parsing error.
  • 05 - In AcuXML, 9D,05 indicates that there was an XFD parsing error, so AcuXML was unable to read a record.

Refer to the specific product documentation for more details on the host file system's error codes.

9E/ xx | 9E/ xx | 9E/ xx | 9E/ xx | 92 | This indicates an error occurred in the transaction system. The exact nature of the error is shown by the contents of TRANSACTION-STATUS. See Transaction Error Codes for more information.
9Z | 9Z | 9Z | 9Z | 92 | This indicates that you are executing the program with a runtime that has a restriction on the number of records it can process. You have exceeded the record limit.
Parent topic: Appendix E. File Status Codes
Parent topic: File Status Codes


Vision Secondary Error Codes for Error 98s

Following is a brief description of the secondary error codes for error 98s for the Vision file system.

01 | The file size listed in the file's header does not match the actual file size.
02 | The header's next record pointer points to an area that is invalid.
03 | Unique ID used to distinguish duplicate keys has already been used and cannot be used with a new key.
04 | Missing tree terminator key.
05 | An error was detected while performing a bulk read of a record.
06 | The key being deleted from the tree was not found in the tree.
07 | A child node was not found in its parent.
08 | An I/O error occurred when the runtime was trying to read key information out of the file's header.
09 | A pointer in a node points past the end of the file.
12 | A node in the free node list was not marked as a free node.
13 | A record in the deleted record list was not marked as a deleted record.
20 | Non-zero key prefix on first key in node.
21 | Key prefix larger than key size.
22 | Key prefix or key size larger than maximum key size.
23 | An invalid value was found while reading the key parameters in the header.
31 | A record pointer in a Vision Version 3 file points to a record-chain value. In a Version 3 file, record pointers should always point to the start of a record, never to a record-chain value.
42 | The unique record counter has been exhausted. Rebuild the file to correct the error.
68 | A Vision 4 or 5 data segment is not found during an open.
69 | A Vision 4 or 5 index segment is not found during an open.
81 | Invalid data found in record header when a compressed record was read.
82 | Invalid data found in record header when a non-compressed record was read.
83 | When a record was read, an I/O error occurred or the record was too short.
84 | When a record link was read, an I/O error occurred or the link was too small.
85 | Record contains invalid record compression codes--the record would uncompress into a record that was larger than the maximum record size.
86 | During a record write, a read of a record-chain value failed, probably due to an end-of-file condition.
87 | Vision Version 4 or 5 detects that it is about to write a record to an area of a file that does not contain an appropriate record header. An appropriate record header indicates that a record currently does not exist at this address.
89 | In Vision Version 4 or 5, on open, a data segment's internal revision number does not match the internal revision number stored in the header of the first data segment.
90 | In Vision Version 4 or 5, on open, an index segment's internal revision number does not match the internal revision number stored in the header of the first data segment.
97 | A vutil -key operation did not complete successfully.
99 | Vision Version 4 or 5 has tried to open the 65,537th data or index segment for this file. Vision can only support 65,536 data segments and 65,536 index segments per logical file.
Parent topic: Appendix E. File Status Codes
Parent topic: File Status Codes


Transaction Error Codes

A transaction management error is one that follows a START TRANSACTION, COMMIT, ROLLBACK or call to C$RECOVER, or one that occurs during some other file operation within a transaction (resulting in an error 9E). Error codes associated with these are stored in the TRANSACTION-STATUS register. This topic lists and describes the primary and secondary transaction error codes.

Primary Error Codes

Following is a list of the primary error codes for the transaction management system.

01 | This is returned from a ROLLBACK statement or call to C$RECOVER when an error occurs in an external routine.
02 | An attempt to open the log file failed because the maximum number of files per process would be exceeded. This is returned from a START TRANSACTION or call to C$RECOVER.
03 | An attempt to open the log file failed because some element of the specified directory path is non-existent. This is returned from a START TRANSACTION statement or call to C$RECOVER.
04 | An attempt to open the log file failed because the user has insufficient access privileges for the file. This is returned from a START TRANSACTION statement or call to C$RECOVER.
05 | This indicates an operating system error that is not otherwise covered by one of the standard error conditions. You can determine the exact nature of this error by examining the value of the secondary error code.
06 | This indicates that the log file is corrupted. The error is returned when the program encounters an unexpected end of file, or when an invalid transaction type code is found during recovery.
07 | An attempt to open the log file failed because the file is locked (MS-DOS only). This is returned from a START TRANSACTION statement or a call to C$RECOVER.
08 | This indicates that the system ran out of dynamic memory.
09 | This indicates that a write failed because the disk is full.
10 | This is returned from a START TRANSACTION statement or call to C$RECOVER when no log file was specified in the LOG-DIR configuration variable.
11 | This is returned from a ROLLBACK or COMMIT statement when an unexpected end of file is reached while the rollback log file is being read.
12 | A START TRANSACTION, ROLLBACK or COMMIT failed because the last transaction in the log file is incomplete.
13 | This error is returned in the TRANSACTION-STATUS register from a WRITE, REWRITE, CLOSE, or DELETE if the file was not opened within a transaction. Note that, if the FILE-CONTROL paragraph for the file contains the WITH ROLLBACK phrase, all OPENs are automatically performed within a transaction.
14 | This is a file-system specific error that is not one of the standard errors, and not an error returned by the operating system. The secondary and tertiary error codes indicate the exact meaning, which is file-system dependent.
16 | This error is returned when the runtime is executing a START TRANSACTION while another transaction is already active.
99 | This warning indicates that the requested transaction operation is not supported by a host file system. The transaction operation is still attempted for other file systems. For example, the runtime includes the RMFM (RM/COBOL) file handler, which does not support transactions. You can remove the RMFM file handler from the runtime by setting the RMFM_DETACH 1 configuration variable. Whether you remove RMFM or not, the Vision file handler will continue to process transactions as expected.

Secondary Error Codes for Error 01

The following is a list of the secondary error codes for transaction error 01.

 | Secondary Error | Corresponding file-status error
01 | operating system error (see tertiary code for system-specific error code) | 30
02 | illegal parameter | 39/01
03 | attempt to open more files than system allows | 94/10
04 | open mode does not allow operation | 48/01 or 49/01
05 | requested record is locked | 99
06 | index file is corrupt | 98/xx
07 | duplicate key where duplicates not allowed | 22
08 | requested record not found | 23
10 | disk became full while adding a new record | 24
11 | file locked against requested open mode | 93
12 | record size mismatch during rewrite | 44
14 | out of dynamic memory | 9A
15 | requested file does not exist | 35
16 | inadequate access permissions to file | 37/07
17 | requested operation not supported | 9B
18 | out of lock-table entries | 9C
19 | file-system specific error | 9D
Parent topic: Appendix E. File Status Codes
Parent topic: File Status Codes
Related information
Transaction Error Handling
filesystem_DETACH


IBM DOS/VS Error Codes

IBM DOS/VS COBOL has a form of the USE statement in the DECLARATIVES section that is not normally recognized by ACUCOBOL-GT:

USE AFTER STANDARD ERROR PROCEDURE ON file-name GIVING
       data-name-1 [data-name-2]

This form is accepted by ACUCOBOL-GT when the -Cv option is in effect.

When an error handler introduced by this statement is invoked, the runtime puts special error codes into the eight-byte data item data-name-1. See IBM DOS/VS COBOL Conversions in Transitioning to ACUCOBOL-GT for more information and the list of codes.

Parent topic: Appendix E. File Status Codes
Parent topic: File Status Codes


Appendix F. Intrinsic Functions

  • Introduction to Intrinsic Functions
  • Function Definitions and Returned Values
  • ABSOLUTE-VALUE (ABS) Function
  • ACOS Function
  • ANNUITY Function
  • ASIN Function
  • ATAN Function
  • CHAR Function
  • COS Function
  • COUNT-LEADING Function
  • COUNT-TRAILING Function
  • CURRENT-DATE Function
  • DATE-OF-INTEGER Function
  • DAY-OF-INTEGER Function
  • FACTORIAL Function
  • INTEGER Function
  • INTEGER-OF-DATE Function
  • INTEGER-OF-DAY Function
  • INTEGER-PART Function
  • INTERVAL-TIMER Function
  • LENGTH Function
  • LOG Function
  • LOG10 Function
  • LOWER-CASE Function
  • MAX Function
  • MEAN Function
  • MEDIAN Function
  • MIDRANGE Function
  • MIN Function
  • MOD Function
  • NUMVAL Function
  • NUMVAL-C Function
  • ORD Function
  • ORD-MAX Function
  • ORD-MIN Function
  • PRESENT-VALUE Function
  • RANDOM Function
  • RANGE Function
  • REM Function
  • REVERSE Function
  • SIN Function
  • SQRT Function
  • STANDARD-DEVIATION Function
  • SUM Function
  • TAN Function
  • TRIM Function
  • UPPER-CASE Function
  • VARIANCE Function
  • WHEN-COMPILED Function
Parent topic: Appendices


Introduction to Intrinsic Functions

Intrinsic functions are subprograms that are built into the ACUCOBOL-GT library. They save time by simplifying common tasks that your COBOL programs might need to perform. For example, intrinsic functions can perform statistical calculations, convert strings from upper to lower case, compute annuities, derive values for trigonometric functions such as sine and cosine, and perform general utility tasks such as determining the compile date of the current object file.

Intrinsic functions are sometimes called built-in or library functions.

To access an intrinsic function, you include it inside a COBOL statement (typically a MOVE or COMPUTE statement). Here's an example of a statement that uses the min intrinsic function:

move function min(3,8,9,7) to my-minimum.

This COBOL statement can be translated into: move the result derived from performing the min function on the literals "3, 8, 9, and 7" to the variable my-minimum.

Note the presence of the required word function, followed by the name of the function (min) and then its parameters. This required word can be replaced by a $ sign, as shown in the following example.

Each intrinsic function is evaluated to a data value. This value is stored in a temporary storage area that you cannot access directly in your program. The only way to get the derived value of an intrinsic function is to provide the name of a data item into which the resulting value should be placed. In the example shown above, the variable my-minimum receives the derived value of the min function.

In the example above, the parameters passed to the min function are literals. It is also permissible to pass data items, as shown here:

compute my-sine = $sin(angle-a).
Note: When the return value of a function is a double, the precision of the return value is limited to that supported by the underlying hardware.

However, if your COBOL program is compiled for 31-digit support (-Dd31), numeric functions are computed using special floating point arithmetic that is accurate to approximately 33 digits, regardless of the floating-point representation on the host machine.

The functions that return a double include: ABS, ABSOLUTE-VALUE, ACOS, ANNUITY, ASIN, ATAN, COS, LOG, LOG10, MEAN, MEDIAN, MIDRANGE, NUMVAL, NUMVAL-C, PRESENT-VALUE, RANDOM, REM, SIN, SQRT, STANDARD-DEVIATION, TAN, and VARIANCE.

Parent topic: Appendix F. Intrinsic Functions


Function Definitions and Returned Values

The definition of a function identifies the following:

  • For alphanumeric functions, the size of the returned value
  • For numeric and integer functions, the sign of the returned value and whether the function is an integer
  • For some other cases, the value returned

Data item functions are elementary data items and return alphanumeric, numeric, or integer values. Data item functions are treated as elementary data items and cannot be receiving operands. Types of data item functions are as follows:

  • Alphanumeric functions - these are of the class and category alphanumeric. The number of character positions in this data item is specified in the function definition. Alphanumeric functions have an implicit usage of DISPLAY.
  • Numeric functions - these are of the class and category numeric. A numeric function is always considered to have an operational sign.
  • A numeric function may be used only in an arithmetic expression.
  • A numeric function may not be referenced where an integer operand is required, even though a particular reference may yield an integer value.
  • Integer functions - these are of the class and category numeric. A numeric function is always considered to have an operational sign.
  • An integer function may be used only in an arithmetic expression.
  • An integer function can be referenced where an integer operand is required and where a signed operand is allowed.
  • Function Definitions
Parent topic: Appendix F. Intrinsic Functions


Function Definitions

The table below summarizes the functions that are now available.

The Arguments column defines the type and number of arguments as follows:

A | alphabetic
I | integer
N | numeric
X | alphanumeric

The Type column defines the type of the function as follows:

I | integer
N | numeric
Z | alphanumeric
Function-name | Arguments | Type | Value returned
ABSOLUTE-VALUE (or ABS) | N1 | N | Absolute value of the argument passed
ACOS | N1 | N | Arccosine of N1
ANNUITY | N1, N2 | N | Ratio of annuity paid for I2 N2 periods at interest rate of N1 to initial investment of one
ASIN | N1 | N | Arcsine of N1
ATAN | N1 | N | Arctangent of N1
CHAR | I1 | X | Character in position I1 of program collating sequence
COS | N1 | N | Cosine of N1
COUNT-LEADING | A1, [A2] | I | Returns number of consecutive times A2 appears at the beginning of A1
COUNT-TRAILING | A1, [A2] | I | Returns number of consecutive times A2 appears at the end of A1
CURRENT-DATE | None | X | Current date and time and difference from Greenwich Mean Time
DATE-OF-INTEGER | I1 | I | Standard date equivalent (YYYYMMDD) of integer date
DAY-OF-INTEGER | I1 | I | Julian date equivalent (YYYYDDD) of integer date
FACTORIAL | I1 | I | Factorial of I1
INTEGER | N1 | I | The greatest integer not greater than N1
INTEGER-OF-DATE | I1 | I | Integer date equivalent of standard date (YYYYMMDD)
INTEGER-OF-DAY | I1 | I | Integer date equivalent of Julian date (YYYYDDD)
INTEGER-PART | N1 | I | Integer part of N1
INTERVAL-TIMER | None | N | Arbitrary time interval (in seconds)
LENGTH | A1 or N1 or X1 | I | Length of argument
LOG | N1 | N | Natural logarithm of N1
LOG10 | N1 | N | Logarithm to base 10 of N1
LOWER-CASE | A1 or X1 | X | All letters in the argument are set to lowercase
MAX | A1... or I1... or N1... or X1... | Depends on arguments* | Value of maximum argument
MEAN | N1... | N | Arithmetic mean of arguments
MEDIAN | N1... | N | Median of arguments
MIDRANGE | N1... | N | Mean of minimum and maximum arguments
MIN | Al... or I1... or N1... or X1... | Depends on arguments* | Value of minimum argument
MOD | I1, I2 | I | I1 modulo I2
NUMVAL | X1 | N | Numeric value of simple numeric string
NUMVAL-C | X1, X2 | N | Numeric value of numeric string with optional commas and currency sign
ORD | A1 or X1 | I | Ordinal position of the argument in collating sequence
ORD-MAX | A1... or N1... or X1... | I | Ordinal position of maximum argument
ORD-MIN | A1... or N1... or X1 | I | Ordinal position of minimum argument
PRESENT-VALUE | N1, N2... | N | Present value of a series of future period-end amounts, N2n at a discount rate of N1
RANDOM | I1 | N | Random number
RANGE | I1... or N1... | Depends on arguments | Value of maximum argument minus value of minimum argument
REM | N1, N2 | N | Remainder of N1/N2
REVERSE | A1 or X1 | X | Reverse order of the characters of the argument
SIN | N1 | N | Sine of N1
SQRT | N1 | N | Square root of N1
STANDARD- DEVIATION | N1... | N | Standard deviation of arguments
SUM | I1... or N1... | Depends on arguments | Sum of arguments
TAN | N1 | N | Tangent of N1
TRIM | A1, [A2] | Z | Copy of A1 with all leading and trailing A2 trimmed
UPPER-CASE | A1 or X1 | X | All letters in the argument are set to uppercase
VARIANCE | N1... | N | Variance of argument
WHEN-COMPILED | None | X | Date and time program was compiled

*A function that has only alphabetic arguments is type alphanumeric.

Parent topic: Function Definitions and Returned Values


ABSOLUTE-VALUE (ABS) Function

The ABSOLUTE-VALUE (or ABS) function returns a single numeric value which is the absolute value of the argument passed.

Usage

FUNCTION ABSOLUTE-VALUE (argument-1)

or

FUNCTION ABS (argument-1)

Parameter

argument-1 Must be class numeric.

Returned Value

The returned value is a single numeric value which is the absolute value of argument-1.

Parent topic: Appendix F. Intrinsic Functions


ACOS Function

The ACOS function returns a numeric value in radians that approximates the arccosine of argument-1. The type of this function is numeric.

Usage

FUNCTION ACOS (argument-1)

Parameter

argument-1 Must be class numeric. The value of argument-1 must be greater than or equal to -1 and less than or equal to +1.

Returned Value

The returned value is the approximation of the arccosine of argument-1 and is greater than or equal to zero and less than or equal to pi. This function will produce results accurate to only about 17 digits, even when argument-1 contains more than 18 digits (for example, if you have compiled your program for 31-digit support.)

Parent topic: Appendix F. Intrinsic Functions


ANNUITY Function

The ANNUITY function (annuity immediate) returns a numeric value representing the amount of each payment in a series of equal periodic payments whose total value is 1.0, where argument-1 is the interest rate per period, argument-2 is the number of periods (usually 12), and each payment is applied at the end of its period. The type of this function is numeric.

a numeric value that approximates the ratio of an annuity paid at the end of each period for the number of periods specified by argument-1 and is applied at the end of the period before the payment. The type of this function is numeric.

Usage

FUNCTION ANNUITY (argument-1 argument-2)

Parameters

argument-1 | Must be class numeric. The value of argument-1 must be greater than or equal to zero.
argument-2 | Must be a positive integer.

Returned Values

When the value of argument-1 is zero, the value of the function is the approximation of:

1 / argument-2

When the value of argument-1 is not zero, the value of the function is the approximation of:

argument-1 / (1 - (1 + argument-1) ** (- argument-2))

Note: This function will produce results accurate to only about 17 digits, even when argument-1 contains more than 18 digits (for example, if you have compiled your program for 31-digit support.)
Parent topic: Appendix F. Intrinsic Functions


ASIN Function

The ASIN function returns a numeric value in radians that approximates the arcsine of argument-1. The type of this function is numeric.

Usage

FUNCTION ASIN (argument-1)

Parameters

  1. argument-1 must be class numeric.
  2. The value of argument-1 must be greater than or equal to -1 and less than or equal to +1.
Note: This function will produce results accurate to only about 17 digits, even when argument-1 contains more than 18 digits (for example, if you have compiled your program for 31-digit support.)

Returned Value

The returned value is the approximation of the arcsine of argument-1 and is greater than or equal to -pi/2 and less than or equal to +pi/2.

Parent topic: Appendix F. Intrinsic Functions


ATAN Function

The ATAN function returns a numeric value in radians that approximates the arctangent of argument-1. The type of this function is numeric.

Usage

FUNCTION ATAN (argument-1)

Parameter

argument-1 Must be class numeric.

Returned Value

The returned value is the approximation of the arctangent of argument-1 and is greater than -pi/2 and less than +pi/2".

Parent topic: Appendix F. Intrinsic Functions


CHAR Function

The CHAR function returns a one-character alphanumeric value that is a character in the program collating sequence having the ordinal position that corresponds to the value of argument-1. The type of this function is alphanumeric.

Usage

FUNCTION CHAR (argument-1)

Parameters

  1. argument-1 must be an integer.
  2. The value of argument-1 must be greater than zero and less than or equal to the number of positions in the collating sequence.

Returned Values

  1. If more than one character has the same position in the program collating sequence, the character returned as the function value is that of the first literal specified for that character position in the ALPHABET clause.
  2. If the current program collating sequence was not specified by an ALPHABET clause, the value returned will be the character in the ASCII character set occupying the ordinal position of the argument.
Parent topic: Appendix F. Intrinsic Functions


COS Function

The COS function returns a numeric value that approximates the cosine of an angle or arc, expressed in radians that is specified by argument-1. The type of this function is numeric.

Usage

FUNCTION COS (argument-1)

Parameter

argument-1 Must be class numeric.

Returned Value

The returned value is the approximation of the cosine of argument-1 and is greater than or equal to -1 and less than or equal to +1.

Parent topic: Appendix F. Intrinsic Functions


COUNT-LEADING Function

The COUNT-LEADING function returns the number of consecutive times that a character appears at the beginning of a string. The type of this function is integer.

Usage

FUNCTION COUNT-LEADING (argument-1, [argument-2])

Parameters

argument-1 | Must be alphanumeric.
argument-2 | Must be alphanumeric
  1. argument-1 represents the string that is to be interrogated.
  2. argument-2 represents the character to be counted at the start of argument-1. Only the first character of argument-2 is used; if omitted, the function assumes a space as argument-2.

Returned Value

The returned value is the number of times that argument-2 appears at the start of argument-1.

Parent topic: Appendix F. Intrinsic Functions
Related reference
TRIM Function
COUNT-TRAILING Function


COUNT-TRAILING Function

The COUNT-TRAILING function returns the number of consecutive times that a character appears at the end of a string. The type of this function is integer.

Usage

FUNCTION COUNT-TRAILING (argument-1, [argument-2])

Parameters

argument-1 | Must be alphanumeric.
argument-2 | Must be alphanumeric
  1. argument-1 represents the string that is to be interrogated.
  2. argument-2 represents the character to be counted at the end of argument-1. Only the first character of argument-2 is used; if omitted, the function assumes a space as argument-2.

Returned Value

The returned value is the number of times that argument-2 appears at the end of argument-1.

Parent topic: Appendix F. Intrinsic Functions
Related reference
TRIM Function
COUNT-LEADING Function


CURRENT-DATE Function

The CURRENT-DATE function returns a 21-character alphanumeric value that represents the calendar date, time of day, and local time differential factor provided by the system on which the function is evaluated. The type of this function is alphanumeric.

Usage

FUNCTION CURRENT-DATE

Returned Values

  1. The character positions returned, numbered from left to right, are described in the table below.
    Character Position | Contents
    1-4 | Four numeric digits of the year in the Gregorian calendar.
    5-6 | Two numeric digits of the month of the year, in the range 01 through 12.
    7-8 | Two numeric digits of the day of the month, in the range 01 through 31.
    9-10 | Two numeric digits of the hours past midnight, in the range of 00 through 23.
    11-12 | Two numeric digits of the minutes past the hour, in the range 00 through 59.
    13-14 | Two numeric digits of the seconds past the minute, in the range 00 through 59.
    15-16 | Two numeric digits of the hundredths of a second past a second, in the range 00 through 99. The value 00 is returned if the system on which the function is evaluated does not have the facility to provide the fractional part of a second.
    17 | The character '0'. This is reserved for future use.
    18-19 | The characters '00'. This is reserved for future use.
    20-21 | The characters '00'. This is reserved for future use
  2. If the system does not have the facility to provide fractional parts of a second, the value 00 is returned in character positions 15 and 16.
  3. If the system does not have the facility to provide the local time differential factor, the value 00000 is returned in character positions 17 through 21.
  4. Currently, we do not support the information contained in positions 17- through 21. These fields will contain 0.
  5. The returned value can be reference modified. For example:
       MOVE FUNCTION CURRENT-DATE (1:4) TO YEARDATE.
Parent topic: Appendix F. Intrinsic Functions


DATE-OF-INTEGER Function

The DATE-OF-INTEGER function converts a date in the Gregorian calendar from integer date form to standard date form (YYYYMMDD). The type of this function is integer.

Usage

FUNCTION DATE-OF-INTEGER (argument-1)

Parameter

argument-1 A positive integer that represents a number of days succeeding December 31, 1600 in the Gregorian calendar.

Returned Values

  1. The returned value represents the ISO standard date equivalent to the integer specified in argument-1.
  2. The returned value is in the form YYYYMMDD, where YYYY represents a year in the Gregorian calendar; MM represents the month of that year; and DD represents the day of that month.
Parent topic: Appendix F. Intrinsic Functions


DAY-OF-INTEGER Function

The DAY-OF-INTEGER function converts a date in the Gregorian calendar from integer date form to Julian date form (YYYYDDD). This type of function is integer.

Usage

FUNCTION DAY-OF-INTEGER (argument-1)

Parameter

argument-1 A positive integer that represents a number of days succeeding December 31, 1600, in the Gregorian calendar.

Returned Values

  1. The returned value represents the Julian equivalent of the integer specified in argument-1.
  2. The returned value is an integer of the form YYYYDDD, where YYYY represents a year in the Gregorian calendar, and DDD represents the day of that year.
Parent topic: Appendix F. Intrinsic Functions


FACTORIAL Function

The FACTORIAL function returns an integer that is the factorial of argument-1. The type of this function is integer.

Usage

FUNCTION FACTORIAL (argument-1)

Parameter

argument-1 Must be an integer greater than or equal to zero.

Returned Values

  1. If the value of argument-1 is zero, the value 1 is returned.
  2. If the value of argument-1 is positive, its factorial is returned.
Parent topic: Appendix F. Intrinsic Functions


INTEGER Function

The INTEGER function returns the greatest integer value that is less than or equal to the argument.

Usage

FUNCTION INTEGER (argument-1)

Parameter

argument-1 Must be class numeric.

Returned Values

  1. When standard arithmetic is specified, argument-1 is not rounded.
  2. The returned value is the greatest integer less than or equal to the value of argument-1. For example, if the value of argument-1 is -1.5, -2 is returned. If the value of argument-1 is +1.5, +1 is returned.
Parent topic: Appendix F. Intrinsic Functions


INTEGER-OF-DATE Function

The INTEGER-OF-DATE function converts a date in the Gregorian calendar from standard date form (YYYYMMDD) to integer date form. The type of this function is integer.

Usage

FUNCTION INTEGER-OF-DATE (argument-1)

Parameter

argument-1 must be an integer of the form YYYYMMDD, whose value is obtained from the calculation (YYYY * 10,000) + (MM * 100) + DD.
  • YYYY represents the year in the Gregorian calendar. It must be an integer greater than 1600.
  • MM represents a month, and must be a positive integer less than 13.
  • DD represents a day, and must be a positive integer less than 32 provided that it is valid for the specified month and year combination.

Returned Value

The returned value is an integer that is the number of days the date represented by argument-1 succeeds December 31, 1600 in the Gregorian calendar.

Parent topic: Appendix F. Intrinsic Functions


INTEGER-OF-DAY Function

The INTEGER-OF-DAY function converts a date in the Gregorian calendar from Julian date form (YYYYDDD) to integer date form. The type of this function is integer.

Usage

FUNCTION INTEGER-OF-DAY (argument-1)

Parameter

argument-1 must be an integer of the form YYYYDDD, whose value is obtained from the calculation (YYYY * 1000) + DDD.
  • YYYY represents the year in the Gregorian calendar. It must be an integer greater than 1600.
  • DDD represents the day of the year. It must be a positive integer less than 367 provided that it is valid for the year specified.

Returned Value

The returned value is an integer that is the number of days the date represented by argument-1 succeeds December 31, 1600 in the Gregorian calendar.

Parent topic: Appendix F. Intrinsic Functions


INTEGER-PART Function

The INTEGER-PART function returns an integer that is the integer portion of argument-1. The type of this function is integer.

Usage

FUNCTION INTEGER-PART (argument-1)

Parameter

argument-1 Must be class numeric.

Returned Values

  1. If the value of argument-1 is zero, the returned value is zero.
  2. If the value of argument-1 is positive, the returned value is the greatest integer less than or equal to the value of argument-1. For example, if the value of argument-1 is +1.5, then +1 is returned.
  3. If the value of argument-1 is negative, the returned value is the least integer greater than or equal to the value of argument-1. For example, if the value of argument-1 is -1.5, then -1 is returned.
Parent topic: Appendix F. Intrinsic Functions


INTERVAL-TIMER Function

The INTERVAL-TIMER function returns the number of seconds starting from an arbitrary point in time. Typically, you will want to use the function twice or more in order to take differences between the return values in order to time something.

Another potential use would be to obtain a higher-resolution timestamp to distinguish items with identical keys.

Usage

FUNCTION INTERVAL-TIMER

Parameters

None.

Returned Value

The return value is not an integer. The exact precision varies widely between systems, but should be at minimum one microsecond (higher for most machines). A variable with at least four digits after the decimal point is recommended to hold the result (though that is not required). Floating point would also be a recommended variable type.

The return value by itself has no preset meaning; it is just an arbitrary number of seconds, measuring real time (as opposed to CPU-only time). Compare it to a second return value for meaning. If the host system does not have an appropriate timer available, then the function will always return a value of zero.

Normally, the timer will only increase in value for any one process. In some implementations, the timer may reset to zero at midnight.

Example

The following example shows how, by setting an arbitrary starting point (the result of the something-long section), you can use the interval-timer function to measure time elapsed.

         working-storage section.

         77  start-time        double.
            77  elapsed-time      double.

         77  display-time      pic zzzz.9(4).
         77  dummy             pic 9(3)9(6).

         procedure division.
         main-logic.

                display standard window.
                display "Running..."

                   move function interval-timer to start-time

                   perform something-long

                   compute elapsed-time = function interval-timer
                                       - start-time

                   move elapsed-time to display-time
                   display "Something-Long took ", display-time,
                             " seconds to run"
                   accept omitted.

                   stop run.

         something-long.
                   perform 1000000 times
                     compute dummy = function sqrt(123)
                   end-perform.
Parent topic: Appendix F. Intrinsic Functions


LENGTH Function

The LENGTH function returns an integer equal to the length of the argument in character positions. This type of function is integer.

Usage

FUNCTION LENGTH (argument-1)

Parameters

  1. argument-1 may be a non-numeric literal or a data item of any class or category.
  2. If argument-1 (or any data item subordinate to argument-1) is described with the DEPENDING phrase of the OCCURS clause, the contents of the data item referenced by the data-name specified in the DEPENDING phrase are used at the time the LENGTH function is evaluated.

Returned Values

  1. If argument-1 is a non-numeric literal or an elementary data item, or if argument-1 is a group data item that does not contain a variable occurrence data item, the value returned is an integer equal to the length of argument-1 in character positions.
  2. If argument-1 is a group data item containing a variable occurrence data item, the returned value is an integer determined by evaluation of the data item specified in the DEPENDING phrase of the OCCURS clause for that variable occurrence data item. This evaluation is accomplished according to the rules in the OCCURS clause dealing with the data item as a sending data item.
  3. The returned value includes implicit FILLER characters, if any.
    Note: This function is similar in functionality to the Format 8 Set SET statement: SET result-item TO SIZE OF data-item.
Parent topic: Appendix F. Intrinsic Functions


LOG Function

The LOG function returns a numeric value that approximates the logarithm to the base e (natural log) of argument-1. The type of this function is numeric.

Usage

FUNCTION LOG (argument-1)

Parameters

  1. argument-1 must be class numeric.
  2. The value of argument-1 must be greater than zero.

Returned Value

The returned value is the approximation of the logarithm to the base e of argument-1.

Parent topic: Appendix F. Intrinsic Functions


LOG10 Function

The LOG10 function returns a numeric value that approximates the logarithm to the base 10 of argument-1. The type of this function is numeric.

Usage

FUNCTION LOG10 (argument-1)

Parameters

  1. argument-1 must be class numeric.
  2. The value of argument-1 must be greater than zero.

Returned Value

Returned value is the approximation of the logarithm to the base 10 of argument-1.

Parent topic: Appendix F. Intrinsic Functions


LOWER-CASE Function

The LOWER-CASE function returns a character string that is the same length as argument-1 with each uppercase letter replaced by the corresponding lowercase letter. The type of this function is alphanumeric.

Usage

FUNCTION LOWER-CASE (argument-1)

Parameter

argument-1 Must be class alphabetic or alphanumeric, and must be at least one character in length.

Returned Values

  1. The same character string as argument-1 is returned, except that each uppercase letter is replaced by the corresponding lowercase letter.
  2. The character string returned has the same length as argument-1.
  3. If the computer character set does not include lowercase letters, no changes take place in the character string.
  4. This function only translates characters with a numeric value of 0-128. Anything above that (such as é with a value of 130) must be mapped to its associated upper- or lower-case character using the configuration variable UPPER-LOWER-MAP.
    Note: This function is similar to the library routine C$TOLOWER except that the original data is not modified, and the entire string is converted.
  5. The returned value can be reference modified. For example:

    MOVE FUNCTION LOWER-CASE(FILE-NAME)(1:4) TO TMP-STRING.

Parent topic: Appendix F. Intrinsic Functions


MAX Function

The MAX function returns the content of the argument-1 that contains the maximum value. The type of this function depends upon the argument types as follows:

Argument Type | Function Type
Alphabetic | Alphanumeric
Alphanumeric | Alphanumeric
All arguments integer | Integer
Numeric | Numeric (some arguments may be integer)

Usage

FUNCTION MAX ({argument-1} ... )

Parameters

If more than one argument-1 is specified, all arguments must be of the same class.

Returned Values

  1. The returned value is the content of the argument-1 having the greatest value. The comparisons used to determine the greatest value are made according to the rules for simple conditions.
  2. If more than one argument-1 has the same greatest value, the content of the argument-1 returned is the leftmost argument-1 having that value.
  3. If the type of the function is alphanumeric, the size of the returned value is the same as the size to the selected argument-1.
Parent topic: Appendix F. Intrinsic Functions


MEAN Function

The MEAN function returns a numeric value that is the arithmetic mean (average) of its arguments. The type of this function is numeric.

Usage

FUNCTION MEAN ({argument-1} ... )

Parameters

argument-1 Must be class numeric.

Returned Values

  1. The returned value is the arithmetic mean of the argument-1 series.
  2. The returned value is defined as the sum of the argument-1 series divided by the number of occurrences referenced by argument-1.
Parent topic: Appendix F. Intrinsic Functions


MEDIAN Function

The MEDIAN function returns the content of the argument whose value is the middle value in the list formed by arranging the arguments in sorted order. The type of this function is numeric.

Usage

FUNCTION MEDIAN ({argument-1} ... )

Parameter

argument-1 Must be class numeric.

Returned Values

  1. The returned value is the content of the argument-1 having the middle value in the list formed by arranging all the argument-1 values in sorted order.
  2. If the number of occurrences referenced by argument-1 is odd, the returned value is such that at least half of the occurrences referenced by argument-1 are greater than or equal to the returned value, and at least half are less than or equal. If the number of occurrences referenced by argument-1 is even, the returned value is the arithmetic mean of the values referenced by the two middle occurrences.
  3. The comparisons used to arrange the argument-1 values in sorted order are made according to the rules for simple conditions.
Parent topic: Appendix F. Intrinsic Functions


MIDRANGE Function

The MIDRANGE (middle range) function returns a numeric value that is the arithmetic mean (average) of the values of the minimum argument and the maximum argument. The type of this function is numeric.

Usage

TION MIDRANGE ({argument-1} ... )

Parameter

argument-1 Must be class numeric.

Returned Value

The returned value is the arithmetic mean of the greatest argument-1 value and the least argument-1 value. The comparisons used to determine the greatest and least values are made according to the rules for simple conditions.

Parent topic: Appendix F. Intrinsic Functions


MIN Function

The MIN function returns the content of the argument-1 value that contains the minimum value. The type of this function depends upon the argument types as follows:

Argument Type | Function Type
Alphabetic | Alphanumeric
Alphanumeric | Alphanumeric
All arguments integer | Integer
Numeric (some arguments may be integer) | Numeric

Usage

FUNCTION MIN ({argument-1} ... )

Parameters

If more than one argument-1 is specified, all arguments must be of the same class.

Returned Values

  1. The returned value is the content of the argument-1 having the least value. The comparisons used to determine the least value are made according to the rules for simple conditions.
  2. If more than one argument-1 has the same least value, the content of the argument-1 returned is the leftmost argument-1 having that value.
  3. If the type of the function is alphanumeric, the size of the returned value is the same as the size of the selected argument-1.
Parent topic: Appendix F. Intrinsic Functions


MOD Function

The MOD function returns an integer value that is argument-1 modulo argument-2. The type of this function is integer.

Usage

FUNCTION MOD (argument-1 argument-2)

Parameters

argument-1 | Must be an integer.
argument-2 | Must be an integer. The value of argument-2 must not be zero.

Returned Values

  1. The returned value is argument-1 modulo argument-2. The returned value is defined as:

    argument-1 - (argument-2 * FUNCTION INTEGER (argument-1 / argument-2))

  2. The following illustrates the expected results for some values of argument-1 and argument-2:
    argument-1 | argument-2 | Return
    11 | 5 | 1
    -11 | 5 | 4
    11 | -5 | -4
    -11 | -5 | -1
Parent topic: Appendix F. Intrinsic Functions


NUMVAL Function

The NUMVAL function returns the numeric value represented by the character string specified by argument-1. Leading and trailing spaces are ignored. The type of this function is numeric.

Usage

FUNCTION NUMVAL (argument-1)

Parameters

argument-1 Must be a non-numeric literal or alphanumeric data item whose content has one of the following two formats:
[space] [+] [space] {digit [ . [digit]]} [space]
        [-]         {. digit           }

or:

[space] {digit [ . [digit]]} [space] [+ ] [space]
        {. digit           }         [- ]
                                     [CR]
                                     [DB]

where space is a string of zero or more spaces, and digit is a string of one to 18 digits.

The total number of digits in argument-1 must not exceed 18. If your program has been compiled for 31-digit support ("-Dd31"), argument-1 must not exceed 31.

If the DECIMAL-POINT IS COMMA clause is specified in the SPECIAL-NAMES paragraph, a comma must be used in argument-1 rather than a decimal point.

Returned Values

  1. The returned value is the numeric value represented by argument-1.
  2. NUMVAL returns a 64-bit floating point value (normally 16 digits) and a 128-bit floating point value when compiled for 31-digit support ("-Dd31").
Parent topic: Appendix F. Intrinsic Functions


NUMVAL-C Function

The NUMVAL-C function returns the numeric value represented by the character string specified by argument-1. Any optional currency sign specified by argument-2 and any optional commas preceding the decimal point are ignored. The type of this function is numeric.

Usage

FUNCTION NUMVAL-C (argument-1 [argument-2])

Parameters

argument-1 Must be a non-numeric literal or alphanumeric data item whose content has one of the following formats:
[space] [+] [space] [cs] [space] {digit [, digit] ... [. [digit]]}
     [space]
  [-] {. digit }

or:

[space] [cs] [space] {digit [, digit] ... [. [digit]]} [space] [+ ]
     [space]
  {. digit } [- ]
  [CR]
  [DB]

where space is a string of zero or more spaces, cs is the string of one or more characters specified by argument-2, and digit is a string of one or more digits.

If the DECIMAL-POINT IS COMMA clause is specified in the SPECIAL-NAMES paragraph, the functions of the comma and decimal point in argument-1 are reversed.

The total number of digits in argument-1 must not exceed 18. If your program has been compiled for 31-digit support (-Dd31), argument-1 must not exceed 31.

argument-2 If specified, must be a non-numeric value represented by argument-1. If argument-2 is not specified, the character used for cs is the currency symbol specified for the program.

Returned Values

  1. The returned value is the numeric value represented by argument-1.
  2. NUMVAL-C returns a 64-bit floating point value (normally 16 digits) and a 128-bit floating point value when compiled for 31-digit support ("-Dd31").
Parent topic: Appendix F. Intrinsic Functions


ORD Function

The ORD function returns an integer value that is the ordinal position of argument-1 in the collating sequence for the program. The lowest ordinal position is 1. The type of this function is integer.

Usage

FUNCTION ORD (argument-1)

Parameter

argument-1 Must be one character in length, and must be class alphabetic or alphanumeric.

Returned Value

The returned value is the ordinal position of argument-1 in the collating sequence for the program.

Parent topic: Appendix F. Intrinsic Functions


ORD-MAX Function

The ORD-MAX function returns a value that is the ordinal number of the argument-1 that contains the maximum value. The type of this function is integer.

Usage

FUNCTION ORD-MAX ({argument-1} ... )

Parameters

argument-1 If more than one argument-1 is specified, all arguments must be of the same class.

Returned Values

  1. The returned value is the ordinal number that corresponds to the position of the argument-1 having the greatest value in the argument-1 series.
  2. The comparisons used to determine the greatest valued argument are made according to the rules for simple conditions.
  3. If more than one argument-1 has the same greatest value, the number returned corresponds to the position of the leftmost argument-1 having that value.
Parent topic: Appendix F. Intrinsic Functions


ORD-MIN Function

The ORD-MIN function returns a value that is the ordinal number of the argument that contains the minimum value. The type of this function is integer.

Usage

FUNCTION ORD-MIN ({argument-1} ... )

Parameters

argument-1 If more than one argument-1 is specified, all arguments must be of the same class.

Returned Values

  1. The returned value is the ordinal number that corresponds to the position of the argument-1 having the least value in the argument-1 series.
  2. The comparisons used to determine the least valued argument-1 are made according to the rules for simple conditions.
  3. If more than one argument-1 has the same least value, the number returned corresponds to the position of the leftmost argument-1 having that value.
Parent topic: Appendix F. Intrinsic Functions


PRESENT-VALUE Function

The PRESENT-VALUE function returns a value that approximates the present value of a series of future period-end amounts specified by argument-2 at a discount rate specified by argument-1.

Usage

FUNCTION PRESENT-VALUE (argument-1 {argument-2} ... )

Parameters

argument-1 | Must be of the class numeric. The value of argument-1 must be greater than -1.
argument-2 | Must be of the class numeric.

Returned Value

The returned value is an approximation of the summation of a series of calculations with each term in the following form:

argument-2 / (1 + argument-1) ** n

There is one term for each occurrence of argument-2. The exponent, n, is incremented increased from one by in increments of one for each term in the series.

Example

COMPUTE RSULT = FUNCTION PRESENT-VALUE (DISCOUNT-RATE, 2000).
Note: In this example, DISCOUNT-RATE and RSULT are numeric data items. If DISCOUNT-RATE has the value 0.08, the value returned and stored in RSULT is approximately 1851.85.
Parent topic: Appendix F. Intrinsic Functions


RANDOM Function

The RANDOM function returns a numeric value that is a pseudo-random number (one of a sequence of numbers generated by an algorithm so as to have an even distribution over a range of values and minimal correlation between successive values) from a rectangular distribution. The type of this function is numeric.

Usage

FUNCTION RANDOM [(argument-1)]

Parameters

  1. If argument-1 is specified, it must be zero or a positive integer. It is used as the seed value to generate a sequence of pseudo-random numbers.
  2. If a subsequent reference specifies argument-1, a new sequence of pseudo-random numbers is started.
  3. If the first reference to this function in the run unit does not specify argument-1, a seed value will be provided by the runtime.
  4. In each case, subsequent references without specifying argument-1 return the next number in the current sequence.

Returned Values

  1. The returned value is greater than or equal to zero and less than one.
  2. For a given seed value on a given implementation, the sequence of pseudo-random numbers will always be the same.

Example

   77  random_num  pic s9(4)v99.
...
   move function random() to random_num.
Parent topic: Appendix F. Intrinsic Functions


RANGE Function

The RANGE function returns a value that is equal to the value of the maximum argument minus the value of the minimum argument. The type of this function depends on the argument types as follows:

Argument Type | Function Type
All arguments integer | Integer
Numeric (some arguments may be integer) | Numeric

Usage

FUNCTION RANGE ({argument-1} ... )

Parameters

argument-1 Must be class numeric.

Returned Value

The returned value is equal to the greatest value of argument-1 minus the least value of argument-1. The comparisons used to determine the greatest and least values are made according to the rules for simple conditions.

Parent topic: Appendix F. Intrinsic Functions


REM Function

The REM function returns a numeric value that is the remainder of argument-1 divided by argument-2. The type of this function is numeric.

Usage

FUNCTION REM (argument-1 argument-2)

Parameters

  1. argument-1 must be class numeric.
  2. argument-2 must be class numeric. The value of argument-2 must not be zero.

Returned Value

The returned value is the remainder of argument-1 / argument-2. It is defined as the expression:

argument-1 - (argument-2 * FUNCTION INTEGER-PART (argument-1 / argument-2))

Parent topic: Appendix F. Intrinsic Functions


REVERSE Function

The REVERSE function returns a character string of exactly the same length as argument-1 and whose characters are exactly the same as those of argument-1, except that they are in reverse order. The type of this function is alphanumeric.

Usage

FUNCTION REVERSE (argument-1)

Parameter

argument-1 Must be class alphabetic or alphanumeric, and must be at least one character in length.

Returned Value

If argument-1 is a character string of length n, the returned value is a character string of length n such that for 1< j < n, the character in position j of the returned value is the character from position n-j+1 of argument-1.

Parent topic: Appendix F. Intrinsic Functions


SIN Function

The SIN function returns a numeric value that approximates the sine of an angle or arc, expressed in radians, that is specified by argument-1. The type of this function is numeric.

Usage

FUNCTION SIN (argument-1)

Parameter

argument-1 Must be class numeric.

Returned Value

The returned value is the approximation of the sine of argument-1 and is greater than or equal to -1 and less than or equal to +1.

Parent topic: Appendix F. Intrinsic Functions


SQRT Function

The SQRT function returns a numeric value that approximates the square root of argument-1. The type of this function is numeric.

Usage

FUNCTION SQRT (argument-1)

Parameters

  1. argument-1 must be class numeric.
  2. The value of argument-1 must be zero or positive.

Returned Value

The returned value is the absolute value of the approximation of the square root of argument-1.

Parent topic: Appendix F. Intrinsic Functions


STANDARD-DEVIATION Function

The STANDARD-DEVIATION function returns a numeric value that approximates the standard deviation of its arguments. The type of this function is numeric.

Usage

FUNCTION STANDARD-DEVIATION ({argument-1} ... )

Parameter

argument-1 Must be class numeric.

Returned Values

  1. The returned value is the approximation of the standard deviation of the argument-1 series.
  2. The returned value is calculated as follows:
    1. | The difference between each argument-1 value and the arithmetic mean of the argument-1 series is calculated and squared.
    2. | The values obtained are then added together. This quantity is divided by the number of values in the argument-1 series.
    3. | The square root of the quotient obtained is then calculated. The returned value is the absolute value of the square root.
  3. If the argument-1 series consists of only one value, or if the argument-1 series consists of all variable occurrence data items and the total number of occurrences for all of them is one, the returned value is zero.
Parent topic: Appendix F. Intrinsic Functions


SUM Function

The SUM function returns a value that is the sum of the arguments. The type of this function depends upon the argument type as follows:

Argument Type | Function Type
All arguments integer | Integer
Numeric (some arguments may be integer) | Numeric

Usage

FUNCTION SUM ({argument-1} ... )

Parameter

argument-1 Must be class numeric.

Returned Values

  1. The returned value is the sum of the arguments.
  2. If the argument-1 series are all integers, the value returned is an integer.
  3. If the argument-1 series are not all integers, a numeric value is returned.
Parent topic: Appendix F. Intrinsic Functions


TAN Function

The TAN function returns a numeric value that approximates the tangent of an angle or arc, expressed in radians, that is specified by argument-1. The type of this function is numeric.

Usage

FUNCTION TAN (argument-1)

Parameter

argument-1 Must be class numeric.

Returned Value

The returned value is the approximation of the tangent of argument-1.

Parent topic: Appendix F. Intrinsic Functions


TRIM Function

The TRIM function trims a particular character from the start and end of an alphanumeric string. The type of this function is alphanumeric.

Usage

FUNCTION TRIM (argument-1, [argument-2])

Parameters

argument-1 | Must be alphanumeric.
argument-2 | Must be alphanumeric
  1. argument-1 represents the string that is to be trimmed.
  2. argument-2 represents the character to be trimmed from the start and end of argument-1. Only the first character of argument-2 is used; if omitted, the function assumes a space as argument-2.

Returned Value

The returned value is argument-1 with the leading and trailing argument-2 characters trimmed.

Parent topic: Appendix F. Intrinsic Functions
Related reference
COUNT-LEADING Function
COUNT-TRAILING Function


UPPER-CASE Function

The UPPER-CASE function returns a character string that is the same length as argument-1 with each lowercase letter replaced by the corresponding uppercase letter. The type of this function is alphanumeric.

Usage

FUNCTION UPPER-CASE (argument-1)

Parameter

argument-1 Must be class numeric or alphanumeric and must be at least one character in length.

Returned Values

  1. The same character string as argument-1 is returned, except that each lowercase letter is replaced by the corresponding uppercase letter.
  2. The character string returned has the same length as argument-1.
  3. This function only translates characters with a numeric value of 0-128. Anything above that (such as é, with a value of 130) must be mapped to its associated upper- or lower-case character using the configuration variable UPPER-LOWER-MAP.
    Note: This function is similar to the library routine C$TOUPPER except that the original data is not modified, and the entire string is converted.
  4. The returned value can be reference modified. For example:
    MOVE FUNCTION UPPER-CASE(FILE-NAME)(1:4) TO TMP-STRING.
Parent topic: Appendix F. Intrinsic Functions


VARIANCE Function

The VARIANCE function returns a numeric value that approximates the variance of its arguments. The type of this function is numeric.

Usage

FUNCTION VARIANCE ({argument-1} ... )

Parameters

argument-1 Must be class numeric.

Returned Value

  1. The returned value is the approximation of the variance of the argument-1 series.
  2. The returned value is defined as the square of the standard deviation of the argument-1 series.
  3. If the argument-1 series consists of only one value, or if the argument-1 series consists of all variable occurrence data items and the total number of occurrences for all of them is one, the returned value is zero.
Parent topic: Appendix F. Intrinsic Functions


WHEN-COMPILED Function

The WHEN-COMPILED function returns the date and time the program was compiled as provided by the system on which the program was compiled. The type of this function is alphanumeric.

Usage

FUNCTION WHEN-COMPILED

Returned Values

  1. The character positions returned, numbered from left to right, are described in the table below.
    Character Positions | Contents
    1-4 | Four numeric digits of the year in the Gregorian calendar.
    5-6 | Two numeric digits of the month of the year, in the range 01 through 12.
    7-8 | Two numeric digits of the day of the month, in the range 01 through 31.
    9-10 | Two numeric digits of the hours past midnight, in the range of 00 through 23.
    11-12 | Two numeric digits of the minutes past the hour, in the range 00 through 59.
    13-14 | Two numeric digits of the seconds past the minute, in the range 00 through 59.
    15-16 | Two numeric digits of the hundredths of a second past a second, in the range 00 through 99. The value 00 will be returned for all systems
    17 | The character '0'. This field is reserved for future implementation.
    18-19 | The characters '00'. This field is reserved for future implementation.
    20-21 | The characters '00'. This field is reserved for future implementation.
  2. The returned value is the date and time of compilation of the source program that contains this function. If the program is a contained program, the returned value is the compilation date and time associated with the separately compiled program in which it is contained.
    Note: The returned value must denote the same time as the compilation date and time if provided in the listing of the source program and in the generated object code for the source program, although their representations and precisions may differ.
  3. The returned value can be reference modified. For example:
    MOVE FUNCTION WHEN-COMPILED (1:4) TO YEARDATE.
Parent topic: Appendix F. Intrinsic Functions


Appendix G. Reserved for Future Use

As a convenience to long-time ACUCOBOL-GT programmers and users, we have retained this empty appendix so that Appendix H, "Runtime Configuration Entries", and Appendix I, "ACUCOBOL-GT Library Routines" can continue to be located in their historic positions.
Parent topic: Appendices


Appendix H. Configuration Variables

  • Introduction
  • Configuration Variables
Parent topic: Appendices


Introduction

Many aspects of the runtime system can be controlled through runtime configuration variables. This mechanism provides a great deal of flexibility, because these variables can be modified by each runcbl site as well as directly by an ACUCOBOL-GT program.

  • Variable Syntax
  • Variable Usage
  • Configuration Filename Resolution
  • Nested Configuration Files
Parent topic: Appendix H. Configuration Variables
Parent topic: Runtime Configuration File


Variable Syntax

Configuration variables are maintained in a runtime configuration file. This standard text file can be modified by the host system's text editor. Each entry in the run-time configuration file consists of a single line. All entries start with a keyword, followed by one or more spaces or tabs, and then one or more values.

Some examples of runtime configuration variables are:

AUTO_PROMPT   0
BELL   1
COMPRESS_FACTOR   70
CURSOR_TYPE   3
MENU_ITEM   Edit=Delete   200
SCROLL   on

For all runtime configuration variables, "=" placed between the keyword and the first value is optional and is interchangeable with a space.

For the following configuration variables, a colon (:) may be used instead of an equals sign (=) in the value portion of the entry:

COLOR-TABLE | COLOR-MAP
FILE-CONDITION | KEYBOARD
KEYSTROKE | SCREEN
MENU-ITEM | MOUSE
HOT-KEY |

In the above cases, allowing a colon instead of an equals sign in the value portion of the entry makes it possible to specify these values in environment variables. This accommodates systems that do not allow an equals sign in the environment variable.

For some runtime configuration variables, the words on, true, and yes are synonyms for 1, and the words off, false, and no are synonyms for 0. The entry for each variable in this appendix indicates when these synonyms are allowed.

In the keyword, all lower-case characters are treated as upper-case and all hyphens are treated as underscores. Keywords longer than 60 characters are truncated to 60 characters.

Parent topic: Introduction


Variable Usage

The configuration file is optional, as are all of its contents. For this reason, no errors in the configuration file are ever reported. The -l runtime option can help debug configuration file problems.

In the descriptions of some runtime configuration variables, you will find comments about behavior under the Windows environment; unless otherwise noted, these comments apply to all 32-bit versions of the Windows operating system.

Runtime configuration variables may be placed in either the runtime configuration file or the machine's environment. When they are placed in the runtime configuration file, upper- and lower-case names are equivalent, as are hyphens and underscores. When placed in the machine's environment, the keywords must be all upper case and must use underscores instead of hyphens. See Runtime Configuration in the ACUCOBOL-GT User’s Guide for more details about the configuration process.

All configuration variables that have a default value are used by and affect the runtime system in the same way that they would if they were in the configuration file. That is to say, a configuration variable that has a default value is treated as if it appears in the configuration file set to the default value.

The values of many runtime configuration variables may be changed at run time with the SET ENVIRONMENT verb. The syntax is:

SET ENVIRONMENT env-name TO env-value

env-name may specify either the literal name of the variable or a data-item whose value is the name of the variable. If you specify the actual name of the variable, such as CODE_CASE, you must enclose the name in quotes. env-value is the value to which env-name will be set. If it is a numeric data item, it is treated as if it were redefined as an alphanumeric data item.

Most configuration variables can be read with the ACCEPT FROM ENVIRONMENT statement. If the variable to be read is numeric, the receiving field must be defined either as a numeric field or as an alphanumeric field of five or more characters. If it is defined as alphanumeric and is longer than five characters, the value that is read from the environment will occupy the leftmost five characters of the field and the remainder will be space-filled.

Parent topic: Introduction


Configuration Filename Resolution

The runtime system uses the following rules to decide what the configuration file is called:

  1. If the -c runtime option is used, the configuration file is the one named by that option
  2. If the operating system environment variable A_CONFIG is defined, its value is the name of the configuration file
  3. The configuration file is named according to the host operating system. This depends on the operating system used by the machine, as outlined in the following table
System | Configuration File
Windows | \etc\cblconfi
UNIX/Linux | /etc/cblconfig
CAUTION:
Don't give a data file a name that is the same as a configuration variable name. Doing so can cause problems if you map the data filename through a configuration entry. For example, if you have a data file named CURRENCY, the runtime system may confuse the data file with the configuration variable of the same name, inadvertently changing the default currency character.
Parent topic: Introduction


Nested Configuration Files

It is possible to use multiple configuration files by nesting one inside another. Within the configuration file, you can specify another file to process with the following syntax:

!COPY filename

No name expansion is performed on filename (for example FILE_PREFIX is not applied), so you must specify a file that the runtime can find. You can include remote name syntax if you are using AcuServer® or AcuConnect®. Otherwise, the file must be an absolute path or a path relative to the current directory

For example, if you have some configuration variables in a global place such as /etc/cblconfi, individual users can execute the runtime system using this configuration file instead of the usual one. The settings in the usual configuration file take effect also, because their settings are copied in with !COPY:

#Get all the standard variables
!copy /etc/cblconfi

#Now set personal settings
COMPRESS_FILES 1
Parent topic: Introduction


Configuration Variables

This section contains an alphabetical list of the run time configuration file variables. Many of these variables are also described in other parts of the help.

Note:

Configuration variables can generally be set and changed during run time. The following lists the configuration variables that can not be set and changed during run time:

  • AGS_BLOCK_SLEEP_TIME
  • AGS_RECEIVE_BUFFER_SIZE
  • AGS_RETRY_COUNT
  • AGS_SEND_BUFFER_SIZE
  • AGS_SOCKET_COMPRESS
  • AGS_SOCKET_ENCRYPT
  • AGS_TCP_NODELAY
  • ANSI_OUTPUT_IN_DEBUG
  • MESSAGE_QUEUE_SIZE
  • PROFILE_TYPE
  • 3D_LINES
  • 7_BIT
  • A_CHECKDIV
  • A_DEBUG
  • A_DISPLAY
  • A_EXTFH_FUNC
  • A_EXTFH_LIB
  • A_EXTFH_SIMPLE_OPEN_OUTPUT
  • A_EXTFH_VARIABLE_IDX, A_EXTFH_VARIABLE_REL, A_EXTFH_VARIABLE_SEQ
  • A_JAVA_CHARSET
  • A_JAVA_GC_COUNT
  • A_JAVA_TRACE_FILENAME
  • A_JAVA_TRACE_VALUE
  • A_LICENSE_RETRIES
  • A_MESSAGE
  • A_OPERATING_SYSTEM
  • A_REMOVE_EMPTY_ERROR_FILE
  • A_RETRY_DELAY
  • A_SEQ_DEFAULT_BLOCK_SIZE
  • A_SORT_FILE_MEMORY
  • A_SORT_REGIONS
  • A_SORT_REGIONS_FINAL
  • A_SYSLOG_HOSTNAME
  • A_SYSLOG_ON_RUNTIME_ERROR
  • A_TMPDIR
  • A_XMLIF_ENCODING
  • A_XMLIF_EXPORT_EMPTY_ARRAY
  • A_XMLIF_EXPORT_OUTLINE
  • A_XMLIF_ICONV_NAME
  • ACCEPT_AUTO
  • ACCEPT_TIMEOUT
  • ACTIVE_BORDER_COLOR
  • ACU_DUMP, ACU_DUMP_FILE, ACU_DUMP_WIDTH, ACU_DUMP_TABLE_LIMIT
  • ACU_USER_DIR
  • ACUCOBOL
  • ACUGTPLUGIN
  • ACUTOWEB_TAB_TITLE
  • AGS_BLOCK_SLEEP_TIME
  • AGS_MAX_SEND_SIZE
  • AGS_RECEIVE_BUFFER_SIZE
  • AGS_RETRY_COUNT
  • AGS_SEND_BUFFER_SIZE
  • AGS_SOCKET_COMPRESS
  • AGS_SOCKET_ENCRYPT
  • AGS_TCP_NODELAY
  • AGS_USE_IPV6
  • alfred Configuration variables
  • ALLOW_FS_OVERRIDE
  • ANSI_OUTPUT_IN_DEBUG
  • APPLY_CODE_PATH
  • APPLY_FILE_PATH
  • ASQL_AUTO_DATE_FORMAT
  • AUTO_DECIMAL
  • AUTO_PROMPT
  • AUTOFILL_NEEDS_XFD
  • AXML_CREATE_SCHEMA
  • AXML_CREATE_STYLE
  • AXML_ENCODING
  • AXML_EXACT_TABLE_MATCH
  • AXML_IGNORE_EMPTY_DATA
  • AXML_SCHEMA_DOC
  • AXML_SCHEMA_NAME
  • AXML_SCHEMA_NAMESPACE_DATA
  • AXML_STYLESHEET_HREF and AXML_STYLESHEET_TYPE
  • BACKGROUND_INTENSITY
  • BELL
  • BOXED_FLOATING_WINDOWS
  • BT_CHECK_OPEN
  • BTRV_FAST_OPEN
  • BTRV_MASS_UPDATE
  • BTRV_NOWRITE_WAIT
  • BTRV_USE_REPEAT_DUPS
  • BUFFERED_SCREEN
  • CALL_HASH_SIZE
  • CANCEL_ALL_DLLS
  • CARRIAGE_CONTROL_FILTER
  • CBLHELP
  • CELL_SEPARATION
  • CGI_AUTO_HEADER
  • CGI_CLEAR_MISSING_VALUES
  • CGI_CONTENT_TYPE
  • CGI_NO_CACHE
  • CGI_STRIP_CR
  • CHAIN_MENUS
  • CHECK_USING
  • CISAM_COMPRESS_KEYS
  • CISAM_IFM_REWRITE
  • CISAM_LOG_FILE
  • CLOSE_ON_EXIT
  • COBLPFORM
  • COBOL_CHARACTER_SET
  • CODE_CASE
  • CODE_MAPPING
  • CODE_PREFIX
  • CODE_SUFFIX
  • CODE_SYSTEM
  • COLOR_MAP
  • COLOR_MODEL
  • COLOR_TABLE
  • COLOR_TRANS
  • COLUMN_SEPARATION
  • COMPRESS_FACTOR
  • COMPRESS_FILES
  • CONTROL_CREATION_EVENTS
  • CONVERT_WINDOW_DEFAULT
  • CURRENCY
  • CURRENT_DATE
  • CURSOR_MODE
  • CURSOR_TYPE
  • DEBUG_NEWCOPY
  • DECIMAL_POINT
  • DEFAULT_FILESYSTEM
  • DEFAULT_FONT
  • DEFAULT_HOST
  • DEFAULT_MAP_FILE
  • DEFAULT_PROGRAM
  • DEFAULT_TIMEOUT
  • DEFER_EVENTS
  • DEFER_WHEEL_EVENTS
  • DISABLED_CONTROL_COLOR
  • DISPLAY_SWITCH_PERIOD
  • DLL_CONVENTION
  • DLL_SUB_INTERFACE
  • DLL_USE_SYSTEM_DIR
  • DOS_BOX_CHARS
  • DOS_SYS_EMULATE
  • DOUBLE_CLICK_TIME
  • DUPLICATES_LOG
  • DYNAMIC_FUNCTION_CALLS
  • DYNAMIC_MEMORY_LIMIT
  • ECN-3699
  • ECN-3975
  • ECN-4159
  • ECN-4273
  • ECN-4296
  • ECN-4315
  • EDIT_MODE
  • EF_UPPER_WIDE
  • EF_WIDE_SIZE
  • EOF_ABORTS
  • EOL_CHAR
  • ERRORS_OK
  • EXIT_CURSOR
  • EXPAND_ENV_VARS
  • EXTEND_CREATES
  • EXTFH_KEEP_TRAILING_SPACES
  • EXTERNAL_SIZE
  • EXTRA_KEYS_OK
  • F10_IS_MENU
  • FAST_ESCAPE
  • FAST_SIGN_DECODE
  • FIELDS_UNBOXED
  • FILE_ALIAS_PREFIX
  • FILE_CASE
  • FILE_CONDITION
  • FILE_IO_PEEKS_MESSAGES
  • FILE_IO_PROCESSES_MESSAGES
  • FILE_PREFIX
  • FILE_STATUS_CODES
  • FILE_SUFFIX
  • FILE_TRACE
  • FILE_TRACE_FLUSH
  • FILE_TRACE_TIMESTAMP
  • filename
  • filename_DATA_FMT
  • filename_FILESYSTEM
  • filename_HOST
  • filename_INDEX_FMT
  • filename_LOG
  • FILENAME_SPACES
  • filename_VERSION
  • filesystem_DETACH
  • FLUSH_ALL
  • FLUSH_COUNT
  • FLUSH_ON_ACCEPT
  • FLUSH_ON_CLOSE
  • FLUSH_ON_COMMIT
  • FLUSH_ON_OPEN
  • FONT
  • FONT_AUTO_ADJUST
  • FONT_SIZE_ADJUST
  • FONT_WIDE_SIZE_ADJUST
  • FOREGROUND_INTENSITY
  • FREEZE_AX_EVENTS configuration
  • FULL_BOXES
  • GRID_BUTTONS_CAUSE_GOTO
  • GRID_ENFORCE_DATATYPE
  • GRID_NO_CELL_DRAG
  • GRID_SORT_INDICATOR
  • GUI_CHARS
  • HELP_PROGRAM
  • HINTS_OFF
  • HINTS_ON
  • HOT_KEY
  • HP_TERMINAL_ATTRIBUTE_HANDLING
  • HTML_TEMPLATE_PREFIX
  • ICOBOL_FILE_SEMANTICS
  • ICON
  • IMPORT_USES_CELL_SIZE
  • INACTIVE_BORDER_COLOR
  • INCLUDE_PGM_INFO
  • INPUT_STATUS_DEFAULT
  • INSERT_MODE
  • INTENSITY_FLAGS
  • IO_CREATES
  • IO_FLUSH_COUNT
  • IO_READ_LOCK_TEST
  • IO_SWITCH_PERIOD
  • ISOLATE_FILE_CREATES
  • JAVA_LIBRARY_NAME
  • JAVA_OPTIONS
  • JUSTIFY_NUM_FIELDS
  • KBD
  • KEISEN_CLEAR_MODE
  • KEY_MAP
  • KEYBOARD
  • KEYSTROKE
  • LARGE_FILE_LIMIT_1TB
  • LARGE_FILE_LIMIT_2TB
  • LC_ALL
  • LICENSE_ERROR_MESSAGE_BOX
  • LINE_OUTPUT
  • LISTS_UNBOXED
  • LITERAL_ENTRY
  • LOCK_DIR
  • LOCK_OUTPUT
  • LOCK_SORT
  • LOCKING_RETRIES
  • LOCKS_PER_FILE
  • LOG_BUFFER_SIZE
  • LOG_DEVICE
  • LOG_DIR
  • LOG_ENCRYPTION
  • LOG_EXCLUDE_PATTERN
  • LOG_FILE
  • LOG_INCLUDE_PATTERN
  • LOG_RECOVER_REPORT
  • LOGGING
  • LOGICAL_CANCELS
  • MAKE_ZERO
  • MASS_UPDATE
  • MAX_ERROR_AND_EXIT_PROCS
  • MAX_ERROR_LINES
  • MAX_FILES
  • MAX_LOCKS
  • MENU_ITEM
  • MESSAGE_BOX_COLOR
  • MESSAGE_QUEUE_SIZE
  • MIN_REC_SIZE
  • MONOCHROME
  • MOUSE
  • MOUSE_FLAGS
  • NESTED_AX_EVENTS
  • NET_FILE_TRACE
  • NO_BARE_KEY_LETTERS
  • NO_CONSOLE
  • NO_LOG_FILE_OK
  • NO_TRANSACTIONS
  • NT_OPP_LOCK_STATUS
  • NUMERIC_VALIDATION
  • OEM_CHARACTER_SET
  • OLD_ARIAL_DIMENSIONS
  • OPEN_FILES_ONCE
  • OPTIMIZE_CONTROL_RESIZE
  • OPTIMIZE_INDIVIDUAL_LINKAGE
  • PAGE_EJECT_ON_CLOSE
  • PAGED_LIST_SCROLL_BAR
  • PARAGRAPH_TRACE
  • PDF_FONT_NAME
  • PDF_FONT_SIZE
  • PDF_FONT_TRUETYPE_TTC
  • PDF_FONT_TRUETYPE_TTC_INDEX
  • PDF_FONT_TRUETYPE_TTF
  • PDF_FONT_TYPE
  • PDF_FONT_TYPE1_PFB
  • PDF_FONT_TYPE1_AFM
  • PDF_MARGIN_BOTTOM
  • PDF_MARGIN_LEFT
  • PDF_MARGIN_RIGHT
  • PDF_MARGIN_TOP
  • PDF_PAGE_DIRECTION
  • PDF_PAGE_SIZE
  • PERFORM_STACK
  • PRELOAD_JAVA_LIBRARY
  • PROFILE_TYPE
  • PROMPTING
  • QUERY_TIMEOUT
  • QUEUE_READERS
  • QUIT_MODE
  • QUIT_ON_FATAL_ERROR
  • QUIT_TO_EXIT
  • RECURSION
  • RECURSION_DATA_GLOBAL
  • REL_DELETED_VALUE
  • REL_LOCK_READ_THROUGH
  • RENEW_TIMEOUT
  • RESIZE_FRAMES
  • RESIZE_FREELY
  • RESTRICTED_VIDEO_MODE
  • RMS_NATIVE_KEYS
  • SCREEN
  • SCREEN_COL_PLUS_BASE
  • SCREEN_TRACE
  • SCRIPT_STATUS
  • SCRN
  • SCROLL
  • server_MAP_FILE
  • server_PASSWORD
  • server_port_PASSWORD
  • SHARED_CODE
  • SHARED_LIBRARY_EXTENSION
  • SHARED_LIBRARY_LIST
  • SHARED_LIBRARY_PREFIX
  • SHUTDOWN_DESTROYS_GUI
  • SHUTDOWN_FREES_PROGRAMS
  • SHUTDOWN_MESSAGE_BOX
  • SHUTDOWN_TESTS
  • SINGLE_STATUS_BAR
  • SORT_DIR
  • SORT_FILES
  • SORT_MEMORY
  • SPACES_ZERO
  • SPOOL_FILE
  • STD_FIXED_FONT
  • STOP_RUN_ROLLBACK
  • STRENGTHEN_LOCKS
  • STRIP_TRAILING_SPACES
  • SWITCH_PERIOD
  • SYSINTR_NAME
  • SYSPUNCH
  • TC_AUTO_UPDATE_FAILED_MESSAGE
  • TC_AUTO_UPDATE_FAILED_TITLE
  • TC_AUTO_UPDATE_NOTIFY_FAIL thin client
  • TC_AUTO_UPDATE_QUERY
  • TC_AUTO_UPDATE_QUERY_MESSAGE
  • TC_AUTO_UPDATE_QUERY_TITLE
  • TC_AX_EVENT_LIST
  • TC_CHECK_ALIVE_INTERVAL
  • TC_CHECK_INSTALLER_TIMESTAMP
  • TC_CONTINUITY_WINDOW
  • TC_CONTROL_SYNC_LEVEL
  • TC_DELAY_ACTIVATE
  • TC_DELAY_PRE_EVENT_OPS
  • TC_DISABLE_AUTO_UPDATE
  • TC_DISABLE_SERVER_LOG
  • TC_DOWNLOAD_CANCEL_MESSAGE
  • TC_DOWNLOAD_DESCRIPTION
  • TC_DOWNLOAD_DIALOG
  • TC_DOWNLOAD_DIALOG_TITLE
  • TC_EVENT_LIST
  • TC_EXCLUDE_EVENT_LIST
  • TC_INSTALLER_ARGS
  • TC_INSTALLER_CLIENT_FILE
  • TC_INSTALLER_RUN_ASYNC
  • TC_INSTALLER_SERVER_FILE
  • TC_INSTALLER_TARGET_DIR
  • TC_INSTALLER_UI_LEVEL
  • TC_MAP_FILE
  • TC_NESTED_AX_EVENTS
  • TC_QUIT_MODE
  • TC_REQUIRES_BUILD_NUMBER
  • TC_RESTRICT_AX_EVENTS
  • TC_SERVER_LOG_FILE log
  • TC_SERVER_TIMEOUT
  • TC_TV_SELCHANGING
  • TEMP_DIR
  • TEST_CHAR
  • TEMPORARY_CONTROLS
  • TEXT
  • THAI
  • TRACE_STYLE
  • TRANSLATE_TO_ANSI
  • TREE_ROOT_SPACE
  • TREE_TAB_SIZE
  • TRX_HOLDS_LOCKS
  • TV_EDITLABELS
  • UPPER_LOWER_MAP
  • USE_BASE_HOSTNAME
  • USE_CICS
  • USE_EXECUTABLE_MEMORY
  • USE_EXTSM
  • USE_LARGE_FILE_API
  • USE_LOCAL_SERVER
  • USE_MPE_REDIRECTION
  • USE_MQSERIES
  • USE_SYSTEM_QSORT
  • USE_UNICODE_FONTS
  • USE_WINSYSFILES
  • V_BASENAME_TRANSLATION
  • V_BUFFERS
  • V_BUFFER_DATA
  • V_BULK_MEMORY
  • V_FORCE_OPEN
  • V_INDEX_BLOCK_PERCENT
  • V_INTERNAL_LOCKS
  • V_LOCK_METHOD
  • V_MARK_READ_CORRUPT
  • V_NO_ASYNC_CACHE_DATA
  • V_OPEN_STRICT
  • V_READ_AHEAD
  • V_SEG_SIZE
  • V_STRIP_DOT_EXTENSION
  • V_VERSION
  • V23_GRAPHICS_CHARACTERS
  • V24_SCREEN_SECTIONS
  • V30_MEASUREMENTS
  • V31_FLOATING_POINT
  • V31_MEASUREMENTS
  • V311_NT_CALL_SYSTEM
  • V32_MEASUREMENTS
  • V42_FLOATING_POINT
  • V43_PRINTER_CELLS
  • V52_BITMAP_BUTTONS
  • V52_BITMAPS
  • V52_GRID_GOTO
  • V60_LIST_VALUE
  • V62_MAX_WINDOW
  • V71_ALIGNED_ENTRY_FIELD
  • V71_FONT_WIDTHS
  • V80_3D_ENTRY_SIZE
  • VMS COBOL
  • VMS_SYSTEM_MODIFIER
  • W_PROGRESS_PARENT
  • WAIT_FOR_ALL_PIPES
  • WAIT_FOR_FILE_ACCESS
  • WAIT_FOR_LOCKS
  • WARNINGS
  • WARNING_ON_RECURSIVE_ACCEPTS
  • WHITE_FILL
  • WIN_ERROR_HANDLING
  • WIN_F4_DROPS_COMBOBOX
  • WIN_SPOOLER_PORT
  • WIN3_CLIP_CONTROLS
  • WIN3_EF_PADDED
  • WIN3_GRID
  • WIN32_3D
  • WIN32_CTL_INPUT_STATUS
  • WIN32_FRAMES_AS_ON_TABS
  • WIN32_NATIVECTLS
  • WIN32_WIDE_CHARS
  • WINDOW_INTENSITY
  • WINDOW_TITLE
  • WINPRINT_NAMES_ONLY
  • WRAP
  • XFD_DIRECTORY
  • XFD_PREFIX
  • XML_KEEP_WHITESPACE
  • XTERM_PROGRAM
Parent topic: Appendix H. Configuration Variables
Parent topic: Runtime Configuration File


3D_LINES

This variable has meaning only on graphical systems such as Windows. Set this variable to 1 (on, true, yes) to cause the runtime system to display lines and boxes with 3-D shading. This makes the lines appear to be inscribed into the surface of the screen. The variable is especially helpful in giving a 3-D look to a program originally designed on a character system. Only black lines on a non-black background are shown with shading. Other lines are displayed normally.

The set of colors available to ACUCOBOL-GT significantly impacts how effective the shading will be. Normally, the shading is most effective when the background is low-intensity white. The other low-intensity colors are next best.

The shading is only marginally effective with a high-intensity background. For this reason, the 3D_LINES setting is not used when a high-intensity background is drawn. Note that, by default, Net Express shows background colors in high-intensity, so you will need to use at least one other configuration variable to arrange for a low-intensity background color. For example, the BACKGROUND_INTENSITY variable could be set to 1 to force a low-intensity background.

You may freely change the way lines are displayed in COBOL by using the SET ENVIRONMENT verb to set 3D-LINES prior to displaying a line or a box:

  • Setting this verb to 1 (on, true, yes) gives you the 3-D effect
  • Setting it to 0 (off, false, no) gives you normal lines

The runtime system remembers which lines are drawn with 3-D, so you don't need to keep track of this yourself. Note, however, that if you attach a 3-D line to a non-3-D line, the intersection will use the 3D-LINES setting currently in effect.

The default value is 0.

Parent topic: Configuration Variables


7_BIT

When this configuration variable is set to 1 (on, true, yes), ACUCOBOL-GT supports 7-bit communications instead of 8-bit. This variable is designed specifically for machines that use 7-bit communications with parity enabled. When 7_BIT is set to the default of 0 (off, false, no), 8-bit communications are used.

Parent topic: Configuration Variables


A_CHECKDIV

This variable allows you to specify an alternate runtime response to a divide by zero condition when the statement does not include a SIZE ERROR clause.

In COBOL, a division by zero produces a size error condition. The SIZE ERROR clause allows the programmer to specify actions to take when this condition occurs. If there is no SIZE ERROR clause, by default in ACUCOBOL-GT the results are undefined. You can use the A_CHECKDIV configuration variable to specify alternate handling.

A_CHECKDIV can be set to:

NONE | "0" | The default setting. This setting retains the default behavior of the runtime: the results are undefined.
ABEND | "1", STOP, ABORT | This setting causes the runtime to catch the divide by zero condition and exit with the error message: Attempt to divide by zero.
MOVE_ZERO | "2", ZERO_RESULT, MOVE_ZEROS | This setting causes the runtime to move zeroes to the destination item(s) and continue.
Parent topic: Configuration Variables


A_DEBUG

This variable is available for applications such as online transaction servers that call ACUCOBOL-GT through the C API. The default value is 0. With the default setting, the debugger launches when the debug_method flag in the C interface is set to 1. See Working with C and C++ Programs of A Guide to Interoperating with ACUCOBOL-GT for more information.

Set this variable to 1 to turn on the ACUCOBOL-GT debugger in an xterm window the first time you call the C interface. The debugger shuts down when the program that caused it to launch shuts down.

Parent topic: Configuration Variables


A_DISPLAY

This variable is available for applications such as online transaction servers that call COBOL through the C API. The value of A_DISPLAY overrides the value of the DISPLAY environment variable. Set A_DISPLAY to the value of your X server host name or IP address in the runtime configuration file (or /etc/cblconfig). For example:

A_DISPLAY myvpn123.myhostname.com:0
Parent topic: Configuration Variables


A_EXTFH_FUNC

The value of this variable is an EXTFH function name needed for the EXTFH interface. If you are using a library that contains an EXTFH function name other than cics_xfh, cobol_extfh, or EXTFH, you also need to set one or more of these variables to specify the function name:

A_EXTFH_FUNC | Specifies a function to be used by all file types (indexed, relative, and sequential).
A_EXTFH_IDX_FUNC | Specifies a function name to be used by indexed file types.
A_EXTFH_REL_FUNC | Specifies a function name to be used by relative file types.
A_EXTFH_SEQ_FUNC | Specifies a function name to be used by sequential file types.

For example, to specify a function name to use for all file types:

A_EXTFH_FUNC=myExtfh
Or, to specify a different function for indexed, relative, and sequential files:
A_EXTFH_IDX_FUNC=myIdxExtfh
A_EXTFH_SEQ_FUNC=mySeqExtfh
A_EXTFH_REL_FUNC=myRelExtfh

If the library is a DLL, you can specify both the name of the DLL and the calling convention to use. Any calling convention specified this way overrides the DLL_CONVENTION variable setting. For information about specifying DLLs and calling conventions, see the topic Loading DLLs with Configuration Variables, in A Guide to Interoperating with ACUCOBOL-GT.

Parent topic: Configuration Variables


A_EXTFH_LIB

The value of this variable is an EXTFH shared library or DLL file name. You can use this variable to dynamically load an EXTFH library without relinking the ACUCOBOL-GT runtime. For example:

A_EXTFH_LIB libraryname.so

You can also use the following variables to specify library names for indexed, relative, and sequential files. The ACUCOBOL-GT runtime uses A_EXTFH_LIB as the default EXTFH library for all three file types. If one or more of these three variables is also set, the runtime uses its value instead of A_EXTFH_LIB for the corresponding file type.

A_EXTFH_IDX_LIB | Specifies the EXTFH library to use for indexed files.
A_EXTFH_REL_LIB | Specifies the EXTFH library to use for relative files.
A_EXTFH_SEQ_LIB | Specifies the EXTFH library to use for sequential files.

You can specify these variables in the runtime configuration file or as operating system environment variables.

If the library is a DLL, you can specify both the name of the DLL and the calling convention to use. Any calling convention specified this way overrides the DLL_CONVENTION variable setting. For information about specifying DLLs and calling conventions, see Loading DLLs with Configuration Variables.

See Working with an EXTFH Interface the topic for information on specifying EXTFH library and function names to use with the EXTFH interface.

Parent topic: Configuration Variables


A_EXTFH_SIMPLE_OPEN_OUTPUT

This variable is used only in UniKix environments, and the UniKix application automatically sets this variable to 1 (TRUE). When set to 1 (TRUE), an OPEN OUTPUT statement will cause the EXTFH functions to bypass the "make" process, and will open the file as OUTPUT. When set to 0 (FALSE), or not set at all, the EXTFH functions will execute the "make" process, and will open the file as EXTEND.

Parent topic: Configuration Variables


A_EXTFH_VARIABLE_IDX, A_EXTFH_VARIABLE_REL, A_EXTFH_VARIABLE_SEQ

These variables indicate whether the filesystem you are accessing with the the EXTFH interface can or cannot handle variable length files. Setting this variable to the default of 1 (on, true, yes) causes the EXTFH interface to pass the minimum and maximum record lengths to the file system for variable length files as defined in the COBOL program. Setting this variable to 0 (off, false, no) causes the EXTFH interface to ignore the variable record length defined in the COBOL program and instead pass a record length equal to the maximum record length.
You can specify the variable separately for indexed, relative, and sequential files. For example:
A_EXTFH_VARIABLE_IDX=0
A_EXTFH_VARIABLE_REL=0
A_EXTFH_VARIABLE_SEQ=1

When the file system does not process variable length files, set these configuration variables to "0" and the EXTFH interface treats variable length records as fixed lengths.

If the file system does process variable length files, set the configuration variables to 1 (or do not set them at all).

Parent topic: Configuration Variables


A_JAVA_CHARSET

This variable specifies the character set that the runtime should use when mapping Java strings or PIC X data items containing characters outside of the ISO-8859-1 range. The default setting is IS0-8859-1. If you have data outside the IS0-8859-1 range (e.g.an umlaut or Euro symbol) specify a different character set that contains those characters.

Be aware of a common misconception that ISO-8859-1 is equivalent to Windows-1252. This is mostly true, but there are characters in the range 0x80 - 0x9F that differ. Windows-1252 uses these numbers for letters and punctuation while the ISO-8859-1 uses these for control codes.

Parent topic: Configuration Variables


A_JAVA_GC_COUNT

A_JAVA_GC_COUNT is a 32-bit value that determines how often the runtime calls the JVM garbage collector. The JVM garbage collector will run at unknown times, in order to deallocate memory which is no longer being used. Setting this to a non-zero value allows you to be a little more intentional about running the garbage collector. The value is the number of times C$JAVA is called before the runtime calls the JVM garbage collector. The default value is 9883, so every 9883 calls to C$JAVA will explicitly call the JVM garbage collector. (For more info on the JVM garbage collector, see your JVM documentation.)

Parent topic: Configuration Variables


A_JAVA_TRACE_FILENAME

A_JAVA_TRACE_FILENAME is the name of the file where the trace information is sent. This filename can include all of the format specifiers that the runtime error file can include. If this file can't be opened for writing (for any reason), no trace information is collected.

Parent topic: Configuration Variables


A_JAVA_TRACE_VALUE

To track calls to the JVM made on behalf of the COBOL program, you can set one of the following three configuration variables: A_JAVA_TRACE_VALUE, A_JAVA_TRACE_FILENAME, and A_JAVA_GC_COUNT.

A_JAVA_TRACE_VALUE is a 32-bit value that determines the types of calls to trace. Add any of the following values together to create a single value to set.

1 - Show calls that return simple types (boolean, byte, character, short, integer, long, float, double).

2 - Show method calls that return simple types.

4 - Show string calls that return string references (that must be released).

8 - Show string calls that return simple types.

16 - Show calls that return references to a Java object (that must be released).

32 - Show method calls that return references to a Java object (that must be released).

64 - Show calls that return references to a Java array or array elements (that must be released).

128 - Show calls that return other array information.

256 - Show calls to the exception routines (some of which must be released).

512 - Show calls to get IDs (Method Identifiers or Field Identifiers).

1024 - Show calls to field functions that return references to a Java object (that must be released).

2048 - Show calls to field functions that return simple types.

4096 - Show other types of calls that return references to a Java object (that must be released).

8192 - Show calls to release a reference to a Java object.

16384 - Show other calls to the Java runtime.

Note for there to be no memory leaks, any call that returns a reference to a Java object (that must be released) needs to be paired with a call to release that reference. If the COBOL program gets that reference, it is responsible for releasing the reference. If the runtime gets the reference for internal purposes, the runtime is responsible for releasing the reference.

For example, setting A_JAVA_TRACE_VALUE to 13684 shows all calls to the JVM that obtain or release a reference to a Java object. Setting A_JAVA_TRACE_VALUE to -1 is equivalent to setting it to 32767 (which is the sum of all the above values), and has the added benefit of tracing new options that may be added in the future. However, for finding memory leaks, this may be too much information.

Parent topic: Configuration Variables


A_LICENSE_RETRIES

This variable affects UNIX networks with multiple-user licenses for the runtime. When set to a positive, non-zero value, this entry causes the runtime to retry (value times) any failed attempt to register with the network license manager, acushare. The configuration variable A_RETRY_DELAY specifies how many seconds the runtime will wait between retries.

The default value is 0 (no retries).

Parent topic: Configuration Variables


A_MESSAGE

This configuration variable specifies the name of the message file to use. The default is acuauth.txt.

This configuration variable only applies to Japanese message text.

Parent topic: Configuration Variables


A_OPERATING_SYSTEM

As of Version 5.0, the runtime no longer differentiates between UNIX-V and UNIX-4 in the OPERATING-SYSTEM field of the SYSTEM-INFORMATION data item. Instead, the value UNIX is used for all UNIX platforms. If you have an existing program that depends on one of the older values, set A_OPERATING_SYSTEM to a value of UNIX-V or UNIX-4. Then, when an ACCEPT FROM SYSTEM-INFO statement is executed, this value overrides the value returned by the function. The default value is empty.

Parent topic: Configuration Variables


A_REMOVE_EMPTY_ERROR_FILE

Use this variable to prevent the accumulation of 0 byte files when using format specifiers such as %p (to include the process id) in the error file name. When this variable is set to 1 (on, true, yes), the runtime deletes its error file if the runtime has never written to that file. Note that on some operating systems, if your error file is shared by multiple processes (i.e., the file name does not include the process id or some other unique session information), setting A_REMOVE_EMPTY_ERROR_FILE to 1 may cause error messages to be lost. For example, on UNIX if the error file is empty when one runtime exits, that runtime would delete the file. The file will remain deleted even if another runtime process subsequently writes a message to it. The default value for this variable is 0 (off, false, no).

Parent topic: Configuration Variables


A_RETRY_DELAY

This variable affects UNIX networks with multiple-user licenses. If A_LICENSE_RETRIES is set to a positive integer value, then the value of A_RETRY_DELAY determines how many seconds the runtime will wait between repeated attempts to register itself with the network license manager, acushare.

The default value is 10.

Parent topic: Configuration Variables


A_SEQ_DEFAULT_BLOCK_SIZE

This configuration variable determines the size of the buffer to use when accessing a sequential file whose definition has no BLOCK CONTAINS clause. When set, A_SEQ_DEFAULT_BLOCK_SIZE specifies the size of the buffer in characters, rounded up to the nearest power of 2 that is greater than or equal to that value. The default value is 0, which sets the block size to one record. Note that this variable does not apply to print files or to files with names that start with a hyphen followed by D or P.

You can set A_SEQ_DEFAULT_BLOCK_SIZE in the environment to allow the vutil -load command to buffer the input file according to the variable's value. The maximum buffer size is 1 GB. If this variable is not set, the default buffer block size is 4096 bytes. If it is set to 0, vutil -load performs record-based I/O on a sequential file.

Parent topic: Configuration Variables


A_SORT_FILE_MEMORY

Use the A_SORT_FILE_MEMORY configuration variable to specify an amount of memory to be used for buffering file operations on the temporary SORT files. The amount of memory is specified in increments of 64KB (as it is for the SORT_MEMORY variable). The minimum value is 0, which disables the file buffer, but this is only recommended for troubleshooting purposes. The maximum value is 65535. The default value is 16.

The recommended setting for this variable will vary depending on your system. In general, more memory used for file buffering will result in less system calls and better performance. If your system has very good file system buffering already, you may get better or as-good performance by setting this variable to a small amount of memory.

If the SORT_MEMORY variable is set to a value larger than A_SORT_FILE_MEMORY (and A_SORT_FILE_MEMORY is set to a non-zero value), the memory previously used for SORT_MEMORY is used to improve file buffering.

The memory allocated by A_SORT_FILE_MEMORY only comes in effect when A_SORT_REGIONS=0, or A_SORT_REGIONS_FINAL is greater than 1.

Parent topic: Configuration Variables
Related reference
A_SORT_REGIONS
A_SORT_REGIONS_FINAL


A_SORT_REGIONS

This configuration variable can be used in conjunction with the A_SORT_REGIONS_FINAL configuration variable to configure sort operations to run using a process that uses significantly fewer I/O operations that other traditional sort operations. This method is suited to sort operations on large files.

Unless you can set the SORT_MEMORY variable to allocate enough memory in which to load all required records, a sort operation must use a temporary sort file. Within a temporary file, records are sorted and stored in regions. A_SORT_REGIONS determines how those sorted regions are merged together.

Set A_SORT_REGIONS to 0 for a sort method that passes through the temporary file once. This method performs less file I/O, because it only writes the records to the temporary file once. However, the file I/O is more random in nature and more CPU time is used in order to manage this file access. This method produces better results when the temporary sort file is stored on a relatively slow storage device, such as a mechanical disk drive.

The alternative is to set A_SORT_REGIONS to a value between 2 and 64, in which the sort process makes multiple passes through the regions, merging the number of regions set by this variable on each pass; the merge takes place in an additional temporary sort file. This method results in more I/O operations, but requires less CPU time because the operations are highly sequential. This method produces better results when the temporary sort files are stored on a relatively faster storage device, such as a solid-state disk drive.

The default for this variable is 4; therefore the 2nd method described here is the default method.

An additional variable can be set when using the default method; see A_SORT_REGIONS_FINAL for more information.

Parent topic: Configuration Variables
Related reference
A_SORT_FILE_MEMORY
A_SORT_REGIONS_FINAL


A_SORT_REGIONS_FINAL

This configuration variable can be used in conjunction with the A_SORT_REGIONS configuration variable.

If A_SORT_REGIONS is set to a value of 2 or more, you can set this variable to a value between 1 and the value of A_SORT_REGIONS. The default for this variable is 1; also, this variable has no effect if A_SORT_REGIONS is set to 0 (zero).

The value of this variable determines how many sorted regions remain in the temporary sort file before the sort process moves onto the output phase; for example, if A_SORT_REGIONS_FINAL is set to 1, then all the records are merged into a single sorted region before moving to the output phase. When set to a non-zero value, there will be up to that many sorted regions left in the temporary file before moving to the output phase. If there is more than one region left, the remaining regions will be merged during the output phase, similar to the way that the SORT is processed when A_SORT_REGIONS=0. If you are having acceptable performance with a non-zero A_SORT_REGIONS setting, then you can safely leave A_SORT_REGIONS_FINAL at its default setting of 1. This variable is mainly for experimentation, allowing you to increase or decrease the value until you find the best performance.

Parent topic: Configuration Variables
Related reference
A_SORT_FILE_MEMORY
A_SORT_REGIONS


A_SYSLOG_HOSTNAME

This variable applies only on Windows and works in conjunction with the A_SYSLOG_ON_RUNTIME_ERROR configuration variable. Set A_SYS_HOSTNAME to the server name or IP address on which the event log is located. Do not include any slashes with the server name. The default value for this variable is empty. Then set A_SYSLOG_ON_RUNTIME_ERROR to 1 (on, true, yes). Shutdown messages will be sent to the event log on the local machine.

Parent topic: Configuration Variables


A_SYSLOG_ON_RUNTIME_ERROR

When this variable is set to 1 (on, true, yes), on a fatal error, the runtime will send its shutdown error message to the UNIX syslog daemon, console, or Windows event log. The runtime uses the same logic as the C$SYSLOG routine. (See C$SYSLOG in Appendix I for more information). The error message also includes the name of the runtime error file so that the administrator can view it for more information. The default value for this variable is 0 (off, false, no).

Parent topic: Configuration Variables


A_TMPDIR

A_TMPDIR allows you to specify an alternative temporary directory exclusively for ACUCOBOL-GT temporary files. On UNIX systems, TMPDIR is the traditional variable for specifying a location for temporary files. On Windows, the run time also checks the TEMP and TMP environment variables.

In addition, the compiler opens a temporary file (and always has done); the location of that file can also be controlled by the A_TMPDIR configuration variable.

Parent topic: Configuration Variables


A_XMLIF_ENCODING

This variable affects the behavior of XML Extensions on UNIX (it is ignored on Windows). The value specifies the local encoding of data and is thus ignored when the XML SET ENCODING statement sets the encoding to UTF-8. The values XMLIF_LATIN_1 and XMLIF_LATIN_9 designate one of the built-in encodings corresponding to Latin-1 or Latin-9, respectively. The value is case insensitive and hyphens and underscores are optional in either of these two predefined values. The default is XMLIF_LATIN_9. The value can be something other than an equivalent of XMLIF_LATIN_1 or XMLIF_LATIN_9, in which case the name must be one recognized by a user provided iconv library (a shared object). See help for the configuration variable A_XMLIF_ICONV_NAME for information on specifying the iconv library location. See the Using XML Extensions documentation in A Guide to Interoperating with ACUCOBOL-GT > Working with Non-vision Data > Working with XML Data for information on character encoding in XML extensions.

Parent topic: Configuration Variables


A_XMLIF_EXPORT_EMPTY_ARRAY

This variable affects the behavior of XML Extensions when exporting an array (COBOL table) where the entire array is empty and all-occurrences has not been enabled. An empty array is one where all the numeric elementary items have a value of zero and all the nonnumeric elementary items have a value of spaces for every occurrence of the array.

When this variable is set to 1 (on, true, yes), one empty occurrence of the empty array is output. When this variable is set to 0 (off, false, no), the empty array is omitted in the exported output. When not set or set to a value that does not correspond to 0 (n, no, f, false, off) or 1 (y, yes, t, true, on), the default behavior depends on whether attributes are enabled or disabled; if attributes are enabled, no occurrences of the empty array are exported. When attributes are not enabled, one occurrence of the empty array is exported. When all occurrences is used, all occurrences of any array, including empty ones, are exported regardless of whether attributes are enabled or not enabled.

Parent topic: Configuration Variables


A_XMLIF_EXPORT_OUTLINE

This variable affects the behavior of XML Extensions during export. When set to 1 (on, true, yes), each nesting level of the output will be preceded by a newline and indented by two spaces for each level of the nesting depth.

When set to 0 (off, false, no), the exported data is written on a single line following the XML header line. Exporting in outline form makes the output more readable, but introduces additional characters in the output (which might be an issue when transferring the XML across a network). Some consumers of the XML might have issues with the inserted whitespace in the containing elements when the export is done with this configuration variable set to1 (on, true, yes). When XML Extensions is the consumer of the exported XML, newlines are stripped from the imported data and the additional spaces in containing elements are distributed to FILLER items, if any, in the import target data structure in the COBOL program; thus there is generally not an issue with outline export when XML Extensions is the consumer.

Parent topic: Configuration Variables


A_XMLIF_ICONV_NAME

This variable affects the behavior of XML Extensions on UNIX (it is ignored on Windows). Its value specifies the iconv library to use when converting local encoding to UTF-8 encoding (export) or UTF-8 encoding to local encoding (import) by giving the iconv library full path and filename, for example, /usr/local/lib/libiconv.so.

When not specified, the default behavior is to search the PATH environment variable for a directory containing iconv.so or libiconv.so, in that order. An iconv library is needed only when the encoding is local and the A_XMLIF_ENCODING configuration variable specifies a value that is not one of the built-in local encoding names. (Micro Focus does not supply an iconv library for use with XML Extensions. The user must acquire an appropriate iconv package and install it in the desired location.)

Parent topic: Configuration Variables


ACCEPT_AUTO

This configuration variable applies only when running in HP COBOL compatibility mode (with the -Cp compiler option). The ACCEPT_AUTO configuration variable causes the runtime to treat all Format 1 ACCEPT statements as if the AUTO phrase is used, whether or not AUTO appears in the statement. Set this variable to 1 (on, true, yes) to enable this behavior. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


ACCEPT_TIMEOUT

This variable causes all ACCEPT statements to time out just as if there was a BEFORE TIME phrase present in the ACCEPT statement. The value assigned to ACCEPT_TIMEOUT is the timeout period, in seconds. This timeout value is applied to every ACCEPT statement that can have a BEFORE TIME phrase specified for it. If a particular ACCEPT statement has a BEFORE TIME phrase explicitly coded for it, that phrase takes precedence and ACCEPT_TIMEOUT does not apply to that statement. The default value of ACCEPT_TIMEOUT is 0, which indicates no timeout value.

Parent topic: Configuration Variables


ACTIVE_BORDER_COLOR

This variable is used on character-based hosts to specify the color and video attributes of the characters used to form the border (box) around the active floating window. ACTIVE_BORDER_COLOR can be set to a variety of numeric values that express combinations of color and video attributes. See the documentation for the COLOR Phrase in the ACUCOBOL-GT Reference Manual.

If ACTIVE_BORDER_COLOR is set to 0, the active window's border is drawn with the colors and video attributes specified in the COBOL program when the window is initially created. The default value is 0.

Parent topic: Configuration Variables


ACU_DUMP, ACU_DUMP_FILE, ACU_DUMP_WIDTH, ACU_DUMP_TABLE_LIMIT

These configuration variables are used to enable and configure the Abend Diagnostic Report (ADR) facility. For a complete description of the ADR, see Abend Diagnostic Report in the ACUCOBOL-GT User’s Guide.

ACU_DUMP

This variable enables the Abend Diagnostic Report. The default value is 0 (off, false, no). Set ACU_DUMP to 1 (on, true, yes) to turn on the ADR.

ACU_DUMP_FILE

This variable specifies the name of the report file. It allows the following special parameters:

  • If the file name starts with a plus sign ("+"), the report is appended to the specified file. By default, a new report overwrites the specified file.
  • If the name contains the string %p, when the report is generated that string is replaced with the process ID (PID) of the runtime from which the report originates.
  • If the name contains the string %d, that string is replaced with the current date in the form YYYYMMDD where YYYY is the year, MM month and DD day.
  • If the name contains the string %t, that string is replaced with the current time in the form HHMMSSTTT where HH is the hour, MM minute, SS second and TTT milliseconds.
  • If the name contains the string %u, that string is replaced with the username.
  • If the name contains the string %h, that string is replaced with the hostname.

The default value for ACU_DUMP_FILE is acudump.%p.

ACU_DUMP_WIDTH

This variable controls the width of the report and has a default value of 80 characters. The minimum allowed value is 79 and the maximum is 2048. Note that because the report uses dynamically computed columns for its hexadecimal data, making the report very wide can reduce readability by introducing excessive white space.

ACU_DUMP_TABLE_LIMIT

This variable limits how many elements of each table item to list. The default value is 1000. Note that if you increase this value substantially, and if you have tables that allow for large numbers of elements, you may get very large reports.

In the following example, ACU_DUMP_TABLE_LIMIT is set to 5:

01 MY-TABLE-R                     = (group)
05 TABLE-ENTRY(1)                 =     1          h20202020 31
05 TABLE-ENTRY(2)                 =     2          h20202020 32
05 TABLE-ENTRY(3)                 =     3          h20202020 33
05 TABLE-ENTRY(4)                 =     4          h20202020 34
05 TABLE-ENTRY(5)                 =     5          h20202020 35
Remaining table items suppressed due to ACU-DUMP-TABLE-LIMIT setting
Parent topic: Configuration Variables


ACU_USER_DIR

The ACU_USER_DIR configuration variable specifies the default location of a user debugger settings file. In the past, the ACUCOBOL variable has been used for this purpose. When set, ACU_USER_DIR specifies the directory for the user's debugger settings (.adb) file. The default value is NULL, which causes the runtime to use the ACUCOBOL variable.

Parent topic: Configuration Variables


ACUCOBOL

This variable holds the full path to the ACUCOBOL-GT installation directory. For example, if the runtime is installed in C:\Program Files\Micro Focus\Acucbl9XX\AcuGT\bin, you would set this configuration variable to:

ACUCOBOL C:\Program Files\Micro Focus\Acucbl9XX\AcuGT

This variable is used to locate extensions to the runtime.

Parent topic: Configuration Variables


ACUGTPLUGIN

This configuration variable specifies the name of the Web run-time authorization file when using Web thin client. The Web run-rime can be installed as part of the ACUCOBOL-GT Development System.

The default is acuauth.txt which is the name of the authorization file as installed. When installed from the product, the file installs to \Program Files\Micro Focus\Acucbl900\AcuGT\bin\.

See the topic How the Authorization File Works for more information about using the Web run-time authorization file.

Parent topic: Configuration Variables


ACUTOWEB_TAB_TITLE

ACUTOWEB_TAB_TITLE provides the ability to set a title displayed in the browser or browser tab when an AcuToWeb session is running. You can set ACUTOWEB_TAB_TITLE in a configuration file or using the Set phrase in a COBOL program.

Parent topic: Configuration Variables


AGS_BLOCK_SLEEP_TIME

This variable is used to specify the amount of wait time before attempting to retry writing data to a socket. It can improve file I/O peformance times for large files (32K or larger). The value of this variable by default is 10 milliseconds. The default value should provide performance at par with pre 7.3 versions.

This variable only has impact on UNIX/Linux.

Parent topic: Configuration Variables


AGS_MAX_SEND_SIZE

This variable allows you to control the size of a basic socket packet exchanged between extend applications that use sockets to communicate. The default value is 16000. In the vast majority of cases, the default value provides excellent results. However, when performance problems are traced to packet size, you can change the size with AGS_MAX_SEND_SIZE. The value of this variable is checked every time that data is sent to the socket. When a program changes the value, the new value is applied the next time that data is sent to the socket.

Parent topic: Configuration Variables


AGS_RECEIVE_BUFFER_SIZE

This variable determines the size of the low-level receive buffer for a socket connection. For the value to have an affect, it must be set before any sockets have been created. The default value is 16384. The default value should be sufficient for most cases. The receive-buffer-size is passed directly to a call to setsockopt.

Note: The value of this variable is sent to a lower-level socket layer not controlled by ACUCOBOL-GT. It may not have any noticeable effect. Changes in this value are not seen in response to a U debugger command listing the memory usage of the runtime.
Parent topic: Configuration Variables


AGS_RETRY_COUNT

Use this variable to specify the number of retry attempts the run time makes to write data to a socket. This variable is useful when the run time closes a socket prematurely, causing acuthin to issue the following message:

Communication socket closed unexpectedly

The default value of AGS_RETRY_COUNT is 1000 (retries). If for some reason the run time performs more than 1000 retries, it closes the socket.

You can use AGS_BLOCK_SLEEP_TIME in addition to AGS_RETRY_COUNT. However, try not setting AGS_BLOCK_SLEEP_TIME so defaults are used.

  • AGS_BLOCK_SLEEP_TIME 10 (millisecond delay between retries)
  • AGS_RETRY_COUNT 1000 (retry attempts before closing socket)

This way if the run time has to do multiple retries it sleeps only 10 milliseconds between them. For example, if the run time performs 100 retries before being successful in data transmission:

Retries | AGS_BLOCK_SLEEP_TIME | Total sleep time
100 | 10 milliseconds | 1.6 seconds
100 | 100 milliseconds | 16 seconds
100 | 1000 milliseconds | 1.6 minutes
100 | 5000 milliseconds | 8.3 minutes

So if you have AGS_BLOCK_SLEEP_TIME set higher than 10 and you are experiencing long delays, try setting AGS_BLOCK_SLEEP_TIME to a smaller value.

Parent topic: Configuration Variables


AGS_SEND_BUFFER_SIZE

This variable determines the size of the low-level send buffer for a socket connection. For the value to have an affect, it must be set before any sockets have been created. The default value is 16384. The default value should be sufficient for most cases. The send-buffer-size is passed directly to a call to setsockopt.

Note: The value of this variable is sent to a lower-level socket layer not controlled by ACUCOBOL-GT. It may not have any noticeable effect. Changes in this value are not seen in response to a U debugger command listing the memory usage of the runtime.
Parent topic: Configuration Variables


AGS_SOCKET_COMPRESS

This variable determines the type of data compression performed at the internal socket layer. AGS_SOCKET_COMPRESS must be set before any socket communication is done, and cannot be changed via SET ENVIRONMENT. This variable has three possible values:

NONE | This is the default setting. When AGS_SOCKET_COMPRESS is set to this value, no compression is performed.
ZLIB | When AGS_SOCKET_COMPRESS is set to this value, socket data is compressed using the same algorithm as the gzip compression utility.
RUNLENGTH | When AGS_SOCKET_COMPRESS is set to this value, simple compression is done, based on counting repeated bytes of data.

RUNLENGTH compression tends to be very fast, while ZLIB compression tends to compress the data more, but is slower as a result.

Windows supports ZLIB compression, but not all UNIX machines do. For those machines that do not, RUNLENGTH compression will be used whether this variable is set to ZLIB or RUNLENGTH. When the compression algorithm is being negotiated with a server, the method that both machines support will be used.

Parent topic: Configuration Variables


AGS_SOCKET_ENCRYPT

To turn on encryption at the internal socket-layer, set the configuration variable AGS_SOCKET_ENCRYPT to 1 (on, true, yes). It must be set before any socket communication is performed, and cannot be changed via a SET ENVIRONMENT statement.

Note: If the variables AS_CLIENT_ENCRYPT and/or THIN_CLIENT_ENCRYPT are set to 1, AGS_SOCKET_ENCRYPT is also set to 1 automatically.
Parent topic: Configuration Variables


AGS_TCP_NODELAY

This variable determines whether the Nagle algorithm is used when sending socket buffer messages. This algorithm automatically delays sending small socket packets for a short period of time in order to increase network efficiency by sending them in a batch. Setting this variable to the default of 1 (on, true, yes) causes socket packets to be sent immediately (not using the algorithm), while setting this variable to "0" (off, false, no) causes socket packets to be delayed (using the algorithm). The TCP-NODELAY socket option is used as follows:

setsockopt(s, IPPROTO_TCP, TCP_NODELAY, &tcp_nodelay, sizeof(int));

The value of this variable is sent to a lower-level socket layer not controlled by ACUCOBOL-GT. It may not have any noticeable effect.

Parent topic: Configuration Variables


AGS_USE_IPV6

This variable enables the use of IPv6 addressing.

By default, this variable is set to 0, which means that IPv4 addressing is used. Set the variable to 1 to use IPv6 addressing instead. It may be possible to mix IPv4 and IPv6 addressing between client and server, but controlling that behavior is beyond the scope of ACUCOBOL-GT. Refer to your system documentation for more information on the effects of mixing addressing versions. For best results, unless otherwise necessary, use the same AGS_USE_IPV6 setting for all ACUCOBOL-GT programs or client/server environments.

If your program is not using a configuration file, you can set AGS_USE_IPV6 within the runtime environment; if your program does use a configuration file, you can set the variable in either. In some cases, such as acurcl -start , the variable must be set in the configuration file, because a child process is spawned that does not inherit the environment of the parent.

In ACUCOBOL-GT, you specify an IPv6 address in the same way as you would an IPv4 address:

SERVER_IP 1111:2222:3333:4444:5555:6666:7777:8888

However, when using one of the Acu utilities (for example, AcuConnect), if you are specifying a port number, you need to use brackets around the actual IP address, as shown below. This is also applicable if you are specifying an address that contains any other additional notation, so as to remove the ambiguity of where the IP address starts and ends:

CODE_PREFIX *[1111:2222:3333:4444:5555:6666:7777:8888]:/usr/acu/code
Note: You can specify the host name of an IPv6 address just as you would for an IPv4 address, without any further code changes necessary.
Parent topic: Configuration Variables


alfred Configuration variables

As of Version 8.0, Acucorp's Indexed File Record Editor (alfred) is provided as a sample program and is located in the sample folder under AcuGT. You can download detailed information on configuring alfred (as well as detailed user information) in PDF format from the Support > Examples & Utilities > Acucorp Samples > Acucorp Technical Articles and Tips on the Micro Focus website (www.microfocus.com).

Parent topic: Configuration Variables


ALLOW_FS_OVERRIDE

This variable enables you to determine if the actual EXTFH return status will be returned, or if the return status should be translated by the runtime. The default setting is True or 1 and will cause the actual EXTFH return status to be returned to the user. Setting this variable to False or 0 will cause the EXTFH return status to be translated by the runtime

Parent topic: Configuration Variables


ANSI_OUTPUT_IN_DEBUG

This variable prevents a COBOL program that uses ANSI-style DISPLAY statements from interfering with the runtime debugger window. This variable accepts two possible values: CANVAS or TERMINAL.

When set to CANVAS (the default setting) the runtime constructs a default canvas on which to place the ANSI output. This prevents the ANSI output from interfering with the debugger window. Note that if your COBOL program sends escape sequences to the terminal, this mode will cause those escape sequences to not have the intended result.

When set to TERMINAL, the runtime will send ANSI output to the terminal, possibly interfering with the view of the debugger window. This is how the runtime behaved before the implementation of this new feature.

Note that this configuration variable must be set before the runtime initializes the terminal manager, which means you cannot set this variable from a COBOL program.

Parent topic: Configuration Variables


APPLY_CODE_PATH

When set to 1 (on, true, yes), this variable causes the CODE_PREFIX variable to be applied to object files with full path names (those beginning with a "/" (forward slash). Otherwise, CODE_PREFIX is not applied to files with full path names. For example, if your application specifies the file:

/accounting/objects/payroll

and your CODE_PREFIX variable is set to:

CODE_PREFIX  /master_obj

and APPLY_CODE_PATH is set to on, the runtime will look for your file in:

/master_obj/accounting/objects/payroll

The default value of APPLY_CODE_PATH is 0 (off, false, no).

Parent topic: Configuration Variables


APPLY_FILE_PATH

When set to 1 (on, true, yes), this variable causes the FILE_PATH variable to be applied to data files with full path names (those beginning with "/", forward slash). Otherwise, FILE_PREFIX is not applied to files with full path names. For example, if your application specifies the file:

/accounting/data/ind.dat

and your FILE_PREFIX variable is set to:

FILE_PREFIX  /master_data

and APPLY_FILE_PATH is set to "on", the runtime will look for your file in:

/master_data/accounting/data/ind.dat

The default value of APPLY_FILE_PATH is 0 (off, false, no).

Parent topic: Configuration Variables


ASQL_AUTO_DATE_FORMAT

Inserting dates with an ODBC driver requires those dates to be in YYYY-MM-DD format. If your dates do not follow this format, an error can be produced, depending on the ODBC driver you are using: SQL Server Native Client 11.0 and later enforce this format (and so produce an error), whereas previous SQL drivers do not.

To mitigate the need to modify your programs, you can use this variable, which will update your dates to the required format before they are written to the SQL Server database. However, if possible, you should modify your COBOL programs so that date values are in YYYY-MM-DD format before being sent to the AcuSQL driver; thus, no relying on this variable.

When set to TRUE, this variable attempts to automatically format the inserts to a DATE column to the YYYY-MM-DD format. It is only used if:
  • Source is a PIC X(n) data type
  • Target is a DATE type
  • Length of the source (n) is not correct for a DATE column (which, at the time of writing, is 10)

For example, if these conditions are met, a value of 12345678 is modified to 1234-56-78. There is no mechanism to specify another format for the date (for example, YYYYMMDD vs DDMMYYYY).

The default value of this variable is FALSE, to preserve historical behavior.

Parent topic: Configuration Variables
Parent topic: Runtime Configuration Variables for SQL Server


AUTO_DECIMAL

When set to 1 (on, true, yes), this variable checks the data item descriptions of numeric entry fields with a decimal point for the number of digits that must be filled to the right of the decimal point. When all the digits after the decimal point are entered, the field will terminate if the AUTO_TERMINATE phrase is specified. The number of digits to the right of the decimal point can vary, depending on how many are indicated in the picture of each numeric entry field. You must specify AUTO_TERMINATE phrase for this feature to work.

The exception to this is when an entry field has an AUTO_DECIMAL property specified, in which case, the coded value will be used.

The default value of this variable is 0 (off, false, no).

Parent topic: Configuration Variables


AUTO_PROMPT

When set to 1 (on, true, yes), this variable causes all ACCEPT statements without a PROMPT clause to be treated as if they had a PROMPT SPACES clause. This causes the screen to be erased at the field position prior to the data's being entered. This variable is provided for compatibility with ACUCOBOL-85 Version 1.3 and earlier, which behaved this way. The default setting is 0 (off, false, no).

Parent topic: Configuration Variables


AUTOFILL_NEEDS_XFD

For entry field controls that use the AUTOFILL property, if you want the data file to be a database table (using Acu4GL), set AUTOFILL-NEEDS-XFD to TRUE, which results in an XFD file being created.

Parent topic: Configuration Variables


AXML_CREATE_SCHEMA

This variable is designed for use with AcuXML for instances when you want to include a schema or schema name with your XML output. In order for this variable to have an effect, AXML_CREATE_STYLE must be set to schema and AXML_SCHEMA_NAME must name the schema file. Once these conditions are met, this variable tells AcuXML whether to create a schema file with XML output, or simply include the name of a schema file in the output.

By default, when AXML_CREATE_STYLE is set to schema, AcuXML creates a schema file for all XML output. Because only one schema is typically required, you should set AXML_CREATE_SCHEMA to FALSE after the first time a schema is created. Then, only the name of the schema file will be included in the output XML file. Similarly, if you already have a schema file and don't want AcuXML to overwrite it, set this variable to FALSE.

Parent topic: Configuration Variables


AXML_CREATE_STYLE

This variable is designed for use with AcuXML. Use it to define the type of XML output that ACUCOBOL-GT should generate when it creates XML files. It can be set to DTD, SCHEMA or NONE. Set this variable to NONE if you want the resulting XML file to be raw XML. Set it to DTD if you want the output to include a Document Type Definition of the elements in the document. Often, the party with whom you trade data may require that your XML document include a DTD.

Set this variable to SCHEMA if you want ACUCOBOL-GT to create a schema to describe the XML documents that it writes. Schemas provide the highest level of detail about the contents of the associated XML document, and are typically required for development purposes. If you set this variable to SCHEMA, you must use the AXML_SCHEMA_NAME variable to name the schema file.

Please note that creating a schema for a file that was run through the xml2fd utility with a schema won't result in an identical schema. In addition, note that setting this variable to schema causes a schema to be created for every XML output file by default. Once the first schema is created, you should set AXML_CREATE_SCHEMA to FALSE to prevent schemas from being created on subsequent XML outputs.

Parent topic: Configuration Variables


AXML_ENCODING

This variable is designed for use with AcuXML. Use it when you want to specify a character encoding method for the XML files that ACUCOBOL-GT creates. By default, the XML output generated by ACUCOBOL-GT is mapped to the UTF-8 encoding system (compatible with the US-ASCII character set). If you want to use a different encoding system, for instance a European encoding system that includes the British pound character (>=), change this variable to reflect the new system name. For example:

AXML_ENCODING iso8859-1

This variable causes encoding information to be added to the header of XML files created by ACUCOBOL-GT. With the configuration file entry shown above, the following header would be included:

<?xml version="1.0" encoding="iso8859-1"?>

This header causes the ISO-8859-1 Latin encoding system to be applied to the data file as desired.

AcuXML supports the following encoding systems:

  • UTF-8, default [8-bit Unicode Transformation Format, backwards compatible with US-ASCII]
  • US-ASCII
  • UTF-16 [16-bit Unicode Transformation Format]
  • ISO-8859-1 [Latin 1, European encoding]
Parent topic: Configuration Variables


AXML_EXACT_TABLE_MATCH

This variable affects the behavior of AcuXML. By default, all tables in an FD must match data in the XML file with respect to the values of the indices. Therefore, AXML_EXACT_TABLE_MATCH is set to 1 (on, true, yes) by default. To disable this requirement, set AXML_EXACT_TABLE_MATCH to 0 (off, false, no).

Parent topic: Configuration Variables


AXML_IGNORE_EMPTY_DATA

Set this variable to TRUE to omit empty and zero-filled data from AcuXML's output file. In this case, AcuXML will not write tags for alphabetic data items that are all blank or numeric data items that are 0. When you set this variable from your COBOL program, it affects any records written via AcuXML from that point on. Note that setting this variable to TRUE could cause AcuXML to generate parts of an XML file that are not consistent with any DTD or schema associated with the file. As a result, use this variable with care.

The default value of FALSE causes AcuXML to generate tags for all data items in the file. If your records are mostly empty, this may be overkill.

Parent topic: Configuration Variables


AXML_SCHEMA_DOC

This variable is designed for use with AcuXML. Use it when you want to add a documentation element to the schema that ACUCOBOL-GT creates when it writes an XML file (such as whenever a sequential file is OPEN OUTPUT).

If you do not require specific documentation in the schema file, or if you did not request that schemas be created for XML output, you can omit this variable.

If this variable is set, its value is included in the documentation element of the resulting schema. For example, if you set this variable as follows:

AXML_SCHEMA_DOC This is the documentation to be
included in the file...

The schema will include the following data:

   <xs:annotation>
     <xs:documentation>
       This is the documentation to be included in the file.
       Created by AcuXML version 6.0.0 on 2016/05/16
     </xs:documentation>
   </xs:annotation>
Note: For information on working with XML data, see Working with XML Data.
Parent topic: Configuration Variables


AXML_SCHEMA_NAME

This variable is designed for use with AcuXML. Use it to define the name of the schema file that ACUCOBOL-GT writes, if any, when it creates an XML file. If this variable is not set, or if it is set to a file name that cannot be created (for whatever reason), a schema is not created.

To tell ACUCOBOL-GT to create a schema, use the AXML_CREATE_STYLE and AXML_CREATE_SCHEMA variables.

Parent topic: Configuration Variables


AXML_SCHEMA_NAMESPACE_DATA

This variable is designed for use with AcuXML for instances when you want to include a schema or schema name with your XML output and you want precise control over the schema namespace string shown in the output. The default value of this variable is:

xmlns:xs=\"http://www.w3.org/2001/XMLSchema-instance\"
    xs:noNamespaceSchemaLocation=\"%s\"

By default, when ACUCOBOL-GT writes XML output (and a schema has been requested), it substitutes the "%s" in this variable with the name of the schema file specified with the AXML_SCHEMA_NAME configuration variable. For instance, if AXML_SCHEMA_NAME is set to myschema, ACUCOBOL-GT will include the following line in the XML output:

xmlns:xs=\"http://www.w3.org/2001/XMLSchema-instance\"
    xs:noNamespaceSchemaLocation=\"myschema.xsd\"

If you need something different than "myschema.xsd" written in the namespace output, add this variable to your configuration file and alter the namespace value in the quotes to meet your requirements.

Note: If you want to include a single "%" character in the namespace, add a second percent sign "%%" to the definition of this variable.

In general, the value of this variable is used in the standard C library printf() function as the first argument, and all printf() rules apply.

Parent topic: Configuration Variables


AXML_STYLESHEET_HREF and AXML_STYLESHEET_TYPE

These variables are designed for use with AcuXML. Use them when you want to associate an XML style sheet with the XML documents that ACUCOBOL-GT creates. When you set these variables to a non-blank value, ACUCOBOL-GT includes an XML-stylesheet comment in the beginning of the resulting XML files. For instance, the following entry:

AXML_STYLESHEET_TYPE text/css

causes the following comment to be added to the beginning of the XML file:

<?xml-stylesheet type="text/css"?>

If you set both of these variables, as in the following example,

AXML_STYLESHEET_TYPE text/css
AXML_STYLESHEET_HREF mystyle.css

then a comment like the following is added to the file:

<?xml-stylesheet type="text/css" href="mystyle.css"?>

If you do not require specific stylesheet data in the XML file, you can omit these variables.

These variables may be toggled on and off during program execution. If you have set these variables and want to generate a xml file without a xml style sheet association, you can do this by adding these statements before opening the xml file:

SET ENVIRONMENT "AXML_STYLESHEET_TYPE" TO ""
 SET ENVIRONMENT "AXML_STYLESHEET_HREF" TO ""
Note: Setting these variables to NULL or SPACE will NOT toggle the variable off.
Parent topic: Configuration Variables


BACKGROUND_INTENSITY

This variable is used to choose a background intensity. Use one of these values:

0 | The runtime uses the default intensity, which is based on your hardware and operating environment. Under Windows, the default background intensity is high-intensity. The default value is "0".
1 | The runtime uses low-intensity.
2 | The runtime uses high-intensity.

There are two important exceptions:

  • The runtime always assigns low-intensity to the background if the background color is black. Using high-intensity would cause the background to be dark gray, which tends to make the screen look muddy.
  • Many devices do not support a background intensity independent from the foreground intensity (most terminals, for example). When that is the case, the runtime declares the background intensity to be low-intensity.
Parent topic: Configuration Variables


BELL

When set to 0 (off, false, no), this variable will inhibit all bells generated by ACCEPT and DISPLAY statements. Note that this will override explicit WITH BELL clauses as well as implicit bells. The default setting is 1 (on, true, yes).

Parent topic: Configuration Variables


BOXED_FLOATING_WINDOWS

When this variable is set to 1 (on, true, yes) all floating windows displayed on character-based hosts are drawn with a border (box). If this variable is set to 0 (off, false, no), floating windows are drawn with a border only when the BOXED phrase appears in the statement that creates the window. The default value for this variable is 0 (off, false, no). This variable has an affect only on character-based host systems.

Parent topic: Configuration Variables


BT_CHECK_OPEN

When set to TRUE (ON, YES, 1), this configuration variable causes ACUCOBOL-GT to attempt to call the Btrieve server whenever ACUCOBOL-GT starts. When set to the default FALSE (OFF, NO, 0), the Btrieve server is assumed to be running, and no call is made. Note that failed communication with the server could result if the server is not running when communication attempts are made. The default is FALSE.

Parent topic: Configuration Variables


BTRV_FAST_OPEN

This configuration variable specifies the mode used by the Btrieve file system to open a file. When this variable is set to TRUE (ON, YES, 1), Btrieve opens files in accelerated mode. In accelerated mode, other applications are allowed to simultaneously open the file. When set to FALSE (OFF, NO, 0), files sent to Btrieve open in exclusive mode. This is equivalent to setting the BTRV_MASS_UPDATE variable to 1. The default is FALSE.

This configuration variable only affects files opened in the Btrieve interface.

See the help topic BTRV_MASS_UPDATE for more information.

Parent topic: Configuration Variables


BTRV_MASS_UPDATE

When this variable is set to 1 (on, true, yes), a Btrieve file is opened in exclusive mode. No other processes may open the file at the same time. When this variable is set to 0 (off, false, no), a Btrieve file is opened in accelerated mode, and other processes may open the file.

Parent topic: Configuration Variables


BTRV_NOWRITE_WAIT

When a user tries to write to a locked file, the Btrieve interface performs a 15-second wait and retry operation before it reports an error condition (99) to the runtime. Setting the BTRV_NOWRITE_WAIT configuration variable to TRUE (the default) prevents this operation from occurring, and the error condition is reported immediately. Setting BTRV_NOWRITE_WAIT to FALSE causes the interface to perform the wait and retry operation.

Parent topic: Configuration Variables


BTRV_USE_REPEAT_DUPS

This variable controls whether duplicate keys are created as LINKED duplicates (the Btrieve default) or REPEATING duplicates. When set to the default value of FALSE, the Btrieve interface creates all duplicate keys as LINKED duplicates. When set to TRUE, the Btrieve interface creates all duplicate keys as REPEATING duplicates.

In cases where a large number of users are accessing files, you may experience better performance if you set this variable to TRUE. See the Pervasive documentation for information on REPEATING duplicates and why you may want to use them.

Parent topic: Configuration Variables


BUFFERED_SCREEN

This variable controls how the Terminal Manager should buffer its output on UNIX systems. Normally, all queued output is sent to the screen after each DISPLAY statement. If this value is set to 1 (on, true, yes), then output is sent only when the internal buffer is full, an ACCEPT statement is executed, or an internal 1-second timer expires. This can speed up output on some systems by reducing the number of times the operating system is called. It will also cause a short delay before messages are seen. We recommend keeping this setting at the default 0 (off, false, no) unless you are experiencing poor screen performance.

Parent topic: Configuration Variables


CALL_HASH_SIZE

The setting of this variable controls the size of the hash table that tracks CALL statements to COBOL subprograms. Each CALL statement tracks its last resolution (target object, entry point, and owning thread). When the resolution is unchanged in a subsequent execution of the CALL statement, the CALL uses the saved information, contributing to improved performance. Each program contains its own copy of this table, so the size should generally be set to a small value.

The default value for CALL_HASH_SIZE is 31. The only reason to change this setting is if your programs contain hundreds of individual CALL statements that target distinct objects. In this case, you may see a small performance improvement by setting CALL_HASH_SIZE to a larger value. You can disable the tracking of these CALL statements by setting the value of CALL_HASH_SIZE to 0.

Note that this mechanism consumes a small amount of memory for each CALL statement. This memory is recovered when the calling object is removed from memory. The amount is machine-specific, but is normally well under 100 bytes per CALL.

Parent topic: Configuration Variables


CANCEL_ALL_DLLS

This variable is used to change the default behavior of a CANCEL ALL statement. The default behavior is for CANCEL ALL to free all DLLs and UNIX/Linux shared object libraries loaded with a prior CALL statement. Setting CANCEL_ALL_DLLS to "\0 (off, false, no) indicates that CANCEL ALL should not free any DLLs or shared object libraries. If you want to free a particular DLL or shared library when CANCEL_ALL_DLLS is set to 0, you must specify the DLL's name in a CANCEL statement.

The default value of CANCEL_ALL_DLLS is 1 (on, true, yes).

Parent topic: Configuration Variables


CARRIAGE_CONTROL_FILTER

The value of this variable affects how carriage control characters are treated when found in LINE SEQUENTIAL data files.

RM/COBOL version 2 handles carriage control characters in a line sequential file differently on different systems. By default, both ACUCOBOL-GT and RM/COBOL-85 remove carriage control characters from input records for line sequential files. This is the ANSI standard. RM/COBOL version 2, however, does not remove form-feed characters on MS-DOS machines and does not remove form-feed or carriage return characters on UNIX systems. Some existing RM/COBOL version 2 programs depend on this behavior.

You can retain any or all of these characters in the input record by setting CARRIAGE_CONTROL_FILTER to a value as follows:

1 | form-feed characters are retained
2 | carriage return characters are retained
4 | line-feed characters are retained

You can specify two or three characters to be retained by adding the appropriate values together. For example, a value of 6 retains carriage returns and line feeds (2 plus 4). Setting the variable to 0 causes the default action of removing all three characters.

The default value is 0.

Note: On VMS systems, carriage control information is not placed directly into data records and is instead maintained separately. For this reason, the CARRIAGE_CONTROL_FILTER setting has no effect on VMS systems and should not be considered portable to those machines.
Parent topic: Configuration Variables


CBLHELP

Define the CBLHELP configuration variable to the location of the cblhelp debugger help file. The definition must include the path and filename. For example:

CBLHELP /home/acucobol8/etc/cblhelp
Parent topic: Configuration Variables


CELL_SEPARATION

This configuration variable determines the vertical spacing when using DISPLAY LINE. For example DISPLAY … LINE + 1 (in pixels). Default value is 3.

Parent topic: Configuration Variables


CGI_AUTO_HEADER

This variable is used when you are writing a Common Gateway Interface (CGI) program in COBOL. It allows you to suppress the output of the HTML header.

Set CGI_AUTO_HEADER to 0 (off, false, no) if you want to suppress the output of the HTML header. This can be useful when you want to execute a CGI program and include its output into an existing flow of HTML text. For example, with server-side includes, or SSI, you can instruct the Web server to execute a subprogram in the manner of CGI and then incorporate its output right into the HTML document before sending it to the requesting client. The default value is 1 (on, true, yes).

For information about writing a CGI program in COBOL, see Launching Web Applications Through CGI in A Programmer's Guide to the Internet.

Parent topic: Configuration Variables


CGI_CLEAR_MISSING_VALUES

This variable is used when you are writing a Common Gateway Interface (CGI) program in COBOL. It allows you to control the behavior of the ACCEPT statement when CGI variables do not exist in the CGI input data.

By default, ACCEPT sets the value of numeric data items to zero and non-numeric data items to spaces if a CGI variable does not exist. Set the CGI_CLEAR_MISSING_VALUES configuration variable to 0 (off, false, no) if you do not want ACCEPT to change the value of the data item if the corresponding CGI variable is missing from the CGI input data.

Parent topic: Configuration Variables


CGI_CONTENT_TYPE

By default, the output generated by your CGI program is mapped as HTML content. To associate your CGI output with a MIME content type other than text/html, use the CGI_CONTENT_TYPE configuration variable. This variable lets you control the content type information in the header of output files created by ACUCOBOL-GT. Such information informs recipients of the type of content that they are about to receive.

Using this variable, you can configure your CGI program for many types of output, including eXtensible Markup Language (XML) or Wireless Markup Language (WML) for Wireless Application Protocol (WAP) devices like mobile phones.

character Whichever format you choose, the US-ASCII character set is applied to the output by default. If you want the CGI output to be mapped to an alternate character set such as ISO-8859-I (Western European), then you can specify the encoding set to use with the variable as well.

Include this variable in your runtime configuration file as follows:

CGI_CONTENT_TYPE contenttype; charset=encoding_set

Where contenttype is the MIME content type of the generated output, and encoding_set is the preferred character encoding set to use.

For example, the WML content type for WAP mobile phones is text/vnd.wap.wml. To associate your CGI output with WML, include the following in your configuration file:

CGI_CONTENT_TYPE text/vnd.wap.wml

If you want your WML output to be mapped to the Western European character set, include the following:

CGI_CONTENT_TYPE text/vnd.wap.wml; charset=iso-8859-I

The content type for eXtensible Markup Language (XML) documents is "text/xml". If your program generates XML data, include the following:

CGI_CONTENT_TYPE text/xml
CAUTION:
To avoid overriding other Content-Type associations, we suggest that you create a different configuration file for each of the MIME Content-Type associations that you make in your Web server setup.

Note that if you use this variable, the external forms indicated in your program's DISPLAY syntax must contain the appropriate content. In other words, if you associate your program with the text/xml content type, the forms must be .xml documents with XML syntax. If you associate it with text/vnd.wap.wml, the forms must be .wml documents with WML syntax. Your program can DISPLAY virtually any type of data, as long as the Content-Type ID corresponds to the external form file that you provide.

Be aware that if you do not use the proper file extension for your external form documents, the Web server will interpret the data as HTML and display the wrong data. WML and XML are also more sensitive to syntax errors than HTML.

In addition, note that the capabilities of the configuration entry CGI_NO_CACHE may be affected by the content type that you choose.

For information about writing a CGI program in COBOL, see Launching Web Applications Through CGI in A Programmer's Guide to the Internet.

Parent topic: Configuration Variables


CGI_NO_CACHE

This variable allows you to choose whether the HTML output of your Common Gateway Interface (CGI) program will be cached by the requesting client.

The default value is 1 (on, true, yes), which means there is no caching. By default, the runtime generates Pragma: no-cache in the HTML response header that gets sent to the standard output stream. If you set CGI_NO_CACHE to 0 (off, false, no), the runtime suppresses this line of the response header, and the requesting client caches the output.

For information about writing a CGI program in COBOL, see Launching Web Applications Through CGI in A Programmer's Guide to the Internet.

Parent topic: Configuration Variables


CGI_STRIP_CR

When this variable is set to 1 (on, true, yes), the runtime automatically removes carriage return characters from data entered in HTML TEXTAREAS (multiple line entry-fields). Stripping the carriage returns from this kind of input prevents double-spacing problems, as well as conflicts that may arise if the data is used in a context that does not expect a carriage return character to precede each line feed character. Some browsers send a carriage return line feed sequence to the CGI program, and when this sequence is written to a file on operating systems that terminate text lines with line feed characters only, the file may appear to be double spaced. The default value for this variable is 0 (off, false, no).

For example, if you enter the following three lines in a TEXTAREA for a field called thetext:

Sometext line 1
Sometext line 2
Sometext line 3

The browser sends the following to the CGI program:

thetext=Sometext+line+1%0D%0ASometext+line+2%0D%0ASometext+line+3%0D%0A

If the CGI_STRIP_CR is set to 1 (on, true, yes), the runtime strips the carriage return characters so that the input line is the following:

thetext=Sometext+line+1%0ASometext+line+2%0ASometext+line+3%0A

For information about writing a CGI program in COBOL, see Launching Web Applications Through CGI in A Programmer's Guide to the Internet.

Parent topic: Configuration Variables


CHAIN_MENUS

When this variable is set to 1 (on, true, yes), the runtime system automatically destroys any menu displayed by a program performing a CHAIN or CALL PROGRAM. This destruction is accomplished with the WMENU-DESTROY-DELAYED operation of the W$MENU library routine. The effect is that the menu is not actually destroyed until the chained-to program displays a new menu. Setting this variable to 0 (off, false, no) inhibits the destruction of the menu. The default value is off.

Parent topic: Configuration Variables


CHECK_USING

When this value is 1 (on, true, yes), the runtime system tests each use of a LINKAGE data item to make sure that the item passed by the calling program is at least as large as the item declared by the called program. This ensures that unallocated memory is not accidentally referenced.

Setting this value to 0 (off, false, no) inhibits the parameters size matching test. It also inhibits the runtime test that verifies that all parameters of a subprogram are passed by the caller.

The default value is 1. If you set this value to 0, you should test your programs carefully to avoid corrupting memory.

Note: It is common for programs in some OLTP environments to specify a data item length as a negative value. By default, this produces a runtime error. Set CHECK_USING to 0 to override the default behavior.
Parent topic: Configuration Variables


CISAM_COMPRESS_KEYS

This variable allows you to turn off key compression in CISAM files. By default, the ACUCOBOL-GT interface to CISAM uses the key compression feature of CISAM. But some CISAM emulators do not understand the compressed keys and cannot read the files created. This variable allows you to turn off the compression.

When the variable is set to 0 (off, false, no), key compression is not used. When it's set to the default of 1 (on, true, yes), key compression is used. Note that this value is examined each time a file is created, so its setting can be changed for each file. The setting is meaningful only when the file is created. After that, the file retains its compression mode.

Parent topic: Configuration Variables


CISAM_IFM_REWRITE

This configuration variable specifies whether ACUCOBOL-GT does a READ for records before performing a REWRITE. It is only used for the ACUCOBOL-GT interface to CISAM.

If this variable is TRUE (ON, YES, 1), then ACUCOBOL-GT first does a READ before a REWRITE. This has the effect of making sure the record is locked before trying to rewrite it. The default is FALSE (OFF, NO, 0)

Parent topic: Configuration Variables


CISAM_LOG_FILE

This configuration variable names the transaction log file. It is only used for the ACUCOBOL-GT interface to CISAM. Leaving the value for this variable blank causes any BEGIN TRANSACTION to fail.

Parent topic: Configuration Variables


CLOSE_ON_EXIT

When set to 1 (on, true, yes), this variable enables the automatic closing of all files except print files when a program performs an EXIT PROGRAM statement. When set to 2 it enables the automatic closing of all files when a program exits. When set to 0 (off, false, no), no files will be automatically closed. See File Handling Options in the ACUCOBOL-GT User's Guide, for more information. The default value is 0.

Parent topic: Configuration Variables


COBLPFORM

This configuration variable is used to define and print to printer channels C01-C12. Specify the line numbers for each channel with the COBLPFORM configuration variable. Null entries are ignored. Those channels that have line number zero, function-names S01-S052, CSP, or are undefined, are set to line 1.

Example 1:

COBLPFORM 1:3:5:7:9:11:13:15:17:19:21:23

In this example C01 equals 1, C02 equals 3, and so on.

Example 2:

COBLPFORM :3::5: :9

In this example, C01 equals 3, C02 equals 5, C03 equals 1, and C04 equals 9. You can specify only a single line number for each channel.

In example 2 above, channels C05 - C12 are undefined. If a print statement specifies channel C05 - C12, the line is printed at line 1. In addition, in the example shown, C03 equals 1 because its value is a space and therefore undefined.

Any WRITE BEFORE/AFTER PAGE statements cause positioning to be at line 1. Each line advance increases the line number by one. A request to skip to a line number less than or equal to the current line causes a new page to begin. The appropriate number of line feeds are then generated.

Parent topic: Configuration Variables


COBOL_CHARACTER_SET

The Windows runtime terminal manager includes built-in Unicode support. For all screen input and output, the data is dynamically converted from the system code page, using UTF-16 encoding. COBOL_CHARACTER_SET enables you to override this, and can take one of the following values:

ANSI
Note: This is only applicable to Windows platforms.
All data in the COBOL program is encoded in the current ANSI code page character set. This is the default, and is the equivalent of setting the variable to 0.
ASCII
Note: This is only applicable to UNIX or Linux platforms.
All data in the COBOL program is ASCII. This is the default, and is the equivalent of setting the variable to 0.
OEM
Note: This is only applicable to Windows platforms.
All data in the COBOL program is encoded in the OEM (DOS) character set. This is the equivalent of setting the variable to 1.
<code page identifier>
Note: This is only applicable to Windows platforms.
All data in the COBOL program is encoded using the character set relating to the code page identifier number. For example, COBOL_CHARACTER_SET=437 would use the OEM United States code page for conversions.

Visit the following web page for a list of supported code pages: https://msdn.microsoft.com/en-us/library/windows/desktop/dd317756(v=vs.85).aspx

UTF-8
All data in the COBOL program is encoded using the Unicode (UTF-8 format) code page. This is the equivalent of setting <code page identifier> to 65001 (Windows only).
Note: As this is a multi-byte character set, you may need to expand some of your data variables to account for the larger size.
ISO-8859-1
Note: This is only applicable to UNIX or Linux platforms.
All data in the COBOL program is encoded using the ISO-8859-1 code page.

You can use this variable to dynamically change the specified character set if your data uses a mixture of formats; for example, data read from an XML file might be in UTF-8 format, while the rest of the data in your program might be in ANSI format.

Parent topic: Configuration Variables


CODE_CASE

This configuration variable allows you to adjust the case of an object file name that is specified in a CALL statement. It has five possible values:

NONE | or | "0" | (the default) object file names are not translated
LOWER | or | "1" | object file names are translated to lower case, including directory (path) elements
UPPER | or | "2" | object file names are translated to upper case, including directory (path) elements
LOWER_BASE | or | "3" | object file names are translated to lower case, excluding directory (path) elements
UPPER_BASE | or | "4" | object file names are translated to upper case, excluding directory (path) elements

Translation occurs before the CODE_SUFFIX and CODE_PREFIX configuration options are applied. You should make sure that those variables specify the correct case. For a complete description of the runtime CALL handling procedure, see CALL in ACUCOBOL-GT User's Guide.

Parent topic: Configuration Variables


CODE_MAPPING

This configuration variable allows you to modify CALL, CHAIN, and CANCEL names at runtime. This can be particularly useful if you are using AcuServer or AcuConnect. When this variable is set to 1 (on, true, yes), every CALL, CHAIN, and CANCEL statement checks the current configuration for a name that matches the CALL name. This is handled in the same way that file name processing is done (the environment is checked for an uppercase version of the name, with any hyphens treated as underscores). If a matching name is found, its value is substituted. This is done recursively until no more matching names are found.

After this substitution occurs, the CALL name handling proceeds normally (and includes any effects of CODE_PATH, CODE_SUFFIX, and CODE_CASE).

For example, with CODE_MAPPING set to 1, if your configuration file had the following entry:

MYPROG  @sun:/app/myprog

Then CALL MYPROG would act the same as CALL @sun:/app/myprog.

Thin client applications may find the CODE_MAPPING mechanism useful for automatically adding the @[DISPLAY]: prefix to the name of the DLL to run on the display host. For example, if your configuration file includes the entry:

mylib.dll  @[DISPLAY]:mylib.dll

Then the statement

CALL  "mylib.dll"

is interpreted as

CALL "@[DISPLAY]:mylib.dll"

causing mylib.dll to run on the display host.

Those wanting to specify the DLL calling conventions will also find CODE_MAPPING useful. For example, if you use the following configuration entries:

funcA=funcA@__stdcall
funcB=funcB@__cdecl

then the statement

CALL "funcA"

calls funcA using the stdcall calling convention and

CALL "funcB"

calls funcB using the cdecl convention.

For more information about calling DLLs from thin client applications, see Thin Client Speial Topics in the AcuConnect User's Guide. For information on calling DLLs in general, see Working with Windows Technologies in A Guide to Interoperating with ACUCOBOL-GT.

The default value for this variable is 0 (off, false, no).

Parent topic: Configuration Variables


CODE_PREFIX

This variable defines a set of directories that the runtime searches to locate a program object file. The default value is "." (current working directory). Code and data file search paths are described in more detail in the ACUCOBOL-GT User's Guide.

Directories can be a mix of relative and absolute paths. Entries are separated by spaces. A space is a valid separator on all systems. Alternatively, on UNIX systems you can also separate entries with a colon. On Windows systems a semicolon can be used. On VMS systems a comma can be used.

Include a "^" (carat) to specify the directory containing the calling program. For example:

CODE_PREFIX . /cobbin ^

causes the runtime to search the current working directory, followed by the "cobbin" root directory, followed by the directory containing the calling program.

You can specify a directory path that contains embedded spaces if you surround the path with quotation marks. For example:

CODE_PREFIX C:\"program files" C:\Customers

Up to 4096 characters can be specified for the value of this variable.

Parent topic: Configuration Variables


CODE_SUFFIX

The value of this variable is automatically appended to the end of program filenames when those names do not contain explicit suffixes. A suffix is the portion of a filename that follows a period. For example, if CODE__SUFFIX is set to COB, then CALL "PGMFILE" causes the runtime to look for the file PGMFILE.COB. The default value is empty.

Parent topic: Configuration Variables


CODE_SYSTEM

The runtime configuration variable CODE_SYSTEM tells the runtime if double-byte character data is being accepted or displayed, and which code system (that is, which standard for encoding Japanese and other Asian character sets, for example) is being used. Each code system has a range of values that it allows within each byte of a two-byte character, so identifying the code system allows the runtime to recognize character boundaries when it is processing double-byte data for ACCEPT and DISPLAY statements.

Setting CODE_SYSTEM to the proper value allows your COBOL applications to handle input and display of double-byte character data without source program changes. The syntax is:

CODE_SYSTEM  setting

The table below shows the possible settings of the CODE_SYSTEM variable, the code system to which each setting refers, and some examples of operating systems to which the particular code system applies:

Setting | Code System | Op. System Examples
BIG5 | Big Five (placecountry-regionTaiwan) | Chinese DOS, Windows
DBC | Acucorp Generic Double-byte Coding Scheme | other double-byte machines
EUC | Extended UNIX | Most UNIX machines
GB | Code of Chinese Graphic Character Set (People's Republic of placecountry-regionChina) | Chinese DOS, Windows
KSC | Korean Character Standard | Korean DOS
SJC | Shift JIS Code (Japanese Industrial Standard) | DOS/V, Windows, some UNIX machines

The default 0 means ASCII or EBCDIC single-byte characters.

The following table shows the decimal values that the respective code systems allow for each byte of the two-byte character:

Code System Setting | 1st byte | 2nd byte
BIG5 (second format) | 161 - 254 161 - 254 | 64 - 126 161 - 254
DBC | 128 - 255 | 128 - 255
EUC (second format) | 142 161 - 254 | 161 - 223 161 - 254
GB and KSC | 161- 254 | 161 - 254
SJC (second format) | 129 - 159 224 - 239 | 64 - 252 (not 127) 64 - 252 (not 127)
Note: The first and second byte values are co-dependent; that is, both values must fall within the respective ranges shown in the table. If either value is not within its allowable range, then each byte will be treated as a single character.
Parent topic: Configuration Variables


COLOR_MAP

This variable can be used to assign colors to programs that do not contain explicit color settings. This is described in Adding Color of ACUCOBOL-GT User's Guide. The default value is empty.

This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.

Parent topic: Configuration Variables


COLOR_MODEL

This variable is typically used when a character-based application is moved to a graphical environment. Use the COLOR_MODEL setting to perform uniform changes to your program's color scheme. These changes are represented by rules that act on your colors. An example of a rule is "exchange the foreground and background colors". Use COLOR_MODEL to change your color scheme in a global way.

The default color model is model 0. It causes no changes to occur to your color scheme. The remaining 10 models are 1 through 10.

  • The odd-numbered models transform only those parts of your program that are entirely black and white. Any character position that contains any color is left unchanged.
  • The even-numbered models apply the changes regardless of color. When selecting a COLOR_MODEL, you can ignore the even-numbered models if you are satisfied with the color portions of your program.

Each color model is actually a composite; it's the equivalent of two or more configuration file variable settings:

COLOR_MODEL | Equivalent Configuration File Variable Settings
"1" | COLOR_TRANS "5" INTENSITY_FLAGS "34" BACKGROUND_INTENSITY "1"
"2" | COLOR_TRANS "4" INTENSITY_FLAGS "34" BACKGROUND_INTENSITY "1"
"3" | COLOR_TRANS "3" INTENSITY_FLAGS "34"
"4" | COLOR_TRANS "1" INTENSITY_FLAGS "34"
"5" | COLOR_TRANS "1" INTENSITY_FLAGS "129"
"6" | COLOR_TRANS "1" INTENSITY_FLAGS "129" BACKGROUND_INTENSITY "2"
"7" | COLOR_TRANS "3" INTENSITY_FLAGS "161"
"8" | COLOR_TRANS "1" INTENSITY_FLAGS "161"
"9" | COLOR_TRANS "3" INTENSITY_FLAGS "193"
"10" | COLOR_TRANS "1" INTENSITY_FLAGS "193"

For more information, see Color Mapping in ACUCOBOL-GT User Interface Programming.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


COLOR_TABLE

This variable is typically used when a character-based application is moved to a graphical environment. Use the COLOR_TABLE variable to cause transformations of individual color combinations. For example, a COLOR_TABLE entry might cause a red foreground on a black background to be translated to a white foreground on a blue background.

Follow the word COLOR_TABLE with the original foreground and background numbers, separated by a comma. Follow these by an equals sign and then the new foreground and background numbers, separated by a comma.

For example, to transform the color combination of foreground 5 on background 2, to foreground 13 on background 2, you would use:

COLOR_TABLE   5, 2 = 13, 2

These are the possible values for foreground and background settings:

Color | Color Value
low-intensity Black | 1
low-intensity Blue | 2
low-intensity Green | 3
low-intensity Cyan | 4
low-intensity Red | 5
low-intensity Magenta | 6
low-intensity Brown | 7
low-intensity White | 8
high-intensity Black | 9
high-intensity Blue | 10
high-intensity Green | 11
high-intensity Cyan | 12
high-intensity Red | 13
high-intensity Magenta | 14
high-intensity Brown | 15
high-intensity White | 16
Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


COLOR_TRANS

This variable is typically used when a character-based application is moved to a graphical environment. It determines how the initial colors in an application are transformed. By default, it is set to 0, which causes no transformation. It may be set to any of these values:

1 | This mode causes the foreground and background colors to be exchanged for each other. This is equivalent to running the entire program in reverse-video.
2 | This causes white to be exchanged for black and black to be exchanged for white. The foreground and background colors are transformed independently. For example, a green foreground on a black background would turn into a green foreground on a white background. This setting usually has the effect of transforming a black background into white while maintaining the general color scheme of the application.
3 | The foreground and background colors are exchanged for each other, but only if they are both black or white. If either the foreground or background contains a color other than black or white, then nothing happens. This is equivalent to running the monochrome parts of your program in reverse-video while maintaining the color portions unchanged.
4 | The foreground and background colors are exchanged for each other, but only if the background is black. This mode ensures that you never have a black background.
5 | If the colors are foreground white and background black, they are exchanged for each other. Otherwise, nothing happens.

Generally speaking, you could use the COLOR_TRANS variable as a starting point in converting an application to appear more natural under Windows. (It's easier to start with COLOR_MODEL instead.) Note that if your application is entirely black-and-white, then the first three COLOR_TRANS options are essentially identical. See Color Mapping in ACUCOBOL-GT User Interface Programming for color mapping suggestions.

Parent topic: Configuration Variables


COLUMN_SEPARATION

This configuration variable sets the default separation distance between columns in a list box. The value is expressed in 10ths of characters. For example, to place a 1/2 character space between list box columns, you would assign a value of 5. See the description of the list box SEPARATION property for more information. The default value of COLUMN_SEPARATION is 5.

Parent topic: Configuration Variables


COMPRESS_FACTOR

This variable is used to define the compression factor that is applied to indexed files (if the indexed file system supports compression; Vision does). COMPRESS_FACTOR is applied when a file is created with the WITH COMPRESSION phrase in the ASSIGN clause of the file's SELECT and the COMPRESSION CONTROL VALUE phrase is either omitted or specifies a value of 1. If the COMPRESS CONTROL VALUE phrase specifies a value other than one, that value is used and the value of COMPRESS_FACTOR is ignored.

COMPRESS_FACTOR can be set to any value within the range zero to 100. Zero specifies no compression. Values from 2-100 are treated as a percentage that specifies how much of the space saved by file compression is removed from the compressed records. A value of 1, the default, is a special case that causes the standard default compression factor of 70 to be applied. Note that a file's compression factor is set when the file is created and cannot later be changed except by recreating the file or rebuilding the file with vutil. For more information about Vision record compression, see Compression. in the ACUCOBOL-GT User's Guide.

Parent topic: Configuration Variables


COMPRESS_FILES

Setting this configuration variable to "1" (on, true, yes) causes ACUCOBOL-GT to treat all indexed files as if they had the WITH COMPRESSION phrase specified for them. This affects the status of newly created files only. When the configuration variable is set to the default value of 0 (off, false, no), only those files with the WITH COMPRESSION phrase specified will be compressed. You can specify the amount of compression with the COMPRESS_FACTOR configuration variable.

Parent topic: Configuration Variables


CONTROL_CREATION_EVENTS

This variable applies to those using ActiveX controls in their ACUCOBOL-GT programs. Use it if you want to allow events during the creation of an ActiveX control. By default, the runtime ignores events from all controls while it is creating an ActiveX control. If it did not, subsequent operations on the ActiveX control could fail.

If you are using a control that delivers significant information using events and you don't want to miss those events while you are creating a new control, set the CONTROL_CREATION_EVENTS variable to 1 (On, True, Yes). Alternatively, you could avoid creating an ActiveX control when you are expecting an event.

By default, this variable is set to 0 (Off, False, No).

Parent topic: Configuration Variables


CONVERT_WINDOW_DEFAULT

This configuration variable is used by the Japanese run-time to set up the IME window (for inputting Japanese characters). If set to TRUE (ON, YES, 1), the IME interface uses default values. If set to FALSE (OFF, NO, 0), values passed to the function (based on the cursor location) are used. The default is FALSE.

Parent topic: Configuration Variables


CURRENCY

This configuration variable can be used to set the desired currency character at runtime. It is followed with the desired character. The default is to use the character specified in the source program's CURRENCY phrase (or "$" if the CURRENCY phrase is absent).

Parent topic: Configuration Variables


CURRENT_DATE

This configuration variable is used by the run time when returning dates. If set to TRUE (ON, YES, 1), dates return in DD/MM/YY date format. If set to FALSE (OFF, NO, 0), dates return in MM/DD/YY format. The default is FALSE.

Parent topic: Configuration Variables


CURSOR_MODE

This configuration variable determines when the cursor should be visible. It has three values:

1 | always visible
2 | always invisible
3 | invisible except during ACCEPT statements, then visible

The default value is 3. Note that a change to the value does not take effect until the next ACCEPT or DISPLAY statement. The sample program MENUBAR.CBL contains examples of how to modify the cursor from within a program. The cursor is always set to Normal, Visible when the runtime exits or when the SYSTEM library routine is called.

Parent topic: Configuration Variables


CURSOR_TYPE

This configuration variable determines the way the cursor looks on character-based systems. It can be set to one of the following values (3 is the default):

1 | normal cursor (usually underscore)
2 | bright cursor (usually block)
3 | normal cursor except when in insert mode, then bright
4 | vertical bar (when available)
Parent topic: Configuration Variables


DEBUG_NEWCOPY

This variable determines whether a new copy of a COBOL program being debugged is loaded from disk whenever the debugger is active. By default, DEBUG_NEWCOPY is "True" so that you can continue to use the logical cancel and code caching feature while the debugger is active.

Set DEBUG_NEWCOPY to "False" if you want to keep caching enabled and have the debugger use the copy of the program in the cache instead of reading a new copy from disk. You must then do one of two things:

  • Start the debugger before the first execution of the program in the current process
  • In a transaction processing system, use the CICS command, CEMT SET PROGRAM(program_name) NEWCOPY, to load a new copy of the program to be debugged.
Note: The ACUCOBOL-GT debugger periodically reads source code from the object file on disk. When the program is cached (as the result of a logical cancel), the object file is closed and could be replaced or deleted. For the debugger to function correctly, it must keep the object file open and ensure that the object code in the disk file is identical to the code in memory. Therefore, if the program has been cached (using LOGICAL_CANCELS and DYNAMIC_MEMORY_LIMIT), the debugger unloads the program from the cache, reopens the object file, and reloads the object code from memory. See Memory Management for more information.
Parent topic: Configuration Variables


DECIMAL_POINT

This configuration variable sets the character to be used as the program's decimal point. Follow it with the desired character. If you use this variable to set the decimal point to a comma, then the place and function of the decimal point and comma are reversed (just like the phrase DECIMAL_POINT IS COMMA). The default is to use the decimal point specified by the program's source.

Note: You do not have to change the value of DECIMAL_POINT to match the decimal point used by floating point values received from external components. The runtime automatically makes the correct adjustment.
Parent topic: Configuration Variables


DEFAULT_FILESYSTEM

This variable determines the file system to be used if no filename_FILESYSTEM variable is set for a file and none of the other file system variables are set for the file type. The other variables you can use to specify a different file system for indexed, relative, or sequential files, are:

  • DEFAULT_IDX_FILESYSTEM
  • DEFAULT_REL_FILESYSTEM
  • DEFAULT_SEQ_FILESYSTEM

For example, setting:

DEFAULT_IDX_FILESYSTEM EXTFH

causes all indexed files to go through the EXTH interface. Unless another file system is specified, ACUCOBOL-GT uses its native file handler for relative and sequential files.

Note: The DEFAULT_IDX_FILESYSTEM variable is a synonym for the existing configuration variable, DEFAULT_HOST.

By default, all file access is handled by the ACUCOBOL-GT native file handler. For those file types you want to access using an EXTFH library, you need to set one or more of these configuration variables to EXTFH.

For example, to use the DB2 library to access indexed files, you would set the following two configuration variables:

A_EXTFH_LIB=/usr/lpp/cics/lib/libxfhdb2sa.a(libxfhdb2_shr.o)
DEFAULT_IDX_FILESYSTEM=EXTFH

For information on specifying EXTFH library and function names to use with the EXTFH interface, see the topic Working With an EXTFH Interface in A Guide to Interoperating with ACUCOBOL-GT.

Parent topic: Configuration Variables


DEFAULT_FONT

This variable defines which font to use for the DEFAULT_FONT. When DEFAULT_FONT is set to "0" (the normal setting), the font used depends on the host system as follows:

System | Font Used
Graphical system | MEDIUM-FONT
Non-graphical system | FIXED-FONT

You can set DEFAULT_FONT to one of the following values to use a different font. The following words are valid settings:

Setting | Font Used
TRADITIONAL | TRADITIONAL-FONT
FIXED | FIXED-FONT
LARGE | LARGE-FONT
MEDIUM | MEDIUM-FONT
SMALL | SMALL-FONT

Due to the way the runtime initializes the windowing subsystem, the DEFAULT_FONT setting is effective only when it is placed in the configuration file or the host system's environment. Setting DEFAULT_FONT from inside a COBOL program has no effect. See Format 3, ACCEPT Statement in the ACUCOBOL-GT Reference Manual) for more information.

Parent topic: Configuration Variables


DEFAULT_HOST

When the application program is opening an existing file or creating a new file, you need to tell the runtime which file system to use. You accomplish this with one of two configuration variables: DEFAULT_HOST or filename_HOST.

DEFAULT_HOST filesystem

designates the file system to be used for files that are not individually assigned. If this variable is not given a value, and if you have not individually assigned a file system (with filename_HOST), the Vision file system is used.

Note: The DEFAULT_IDX_FILESYSTEM variable is a synonym for DEFAULT_HOST.
Parent topic: Configuration Variables


DEFAULT_MAP_FILE

Use this variable to point to the character map file used for translating international character sets between machines that use differing character codes. The map file is a simple text file that you create with an editor of your choice. Each line in the map file must contain two values in either decimal or hexadecimal: the character code of the character on the client machine, and the character code of the same character on the remote machine. Use a # sign to indicate a comment.

The runtime first searches for the configuration variable server_MAP_FILE and, if it is found, uses that setting to locate the map file. If that variable is not set, the runtime searches for DEFAULT_MAP_FILE. If this variable is not set, then no character translation is done.

Example:

DEFAULT_MAP_FILE = c:\etc\pc_iso.txt
Parent topic: Configuration Variables


DEFAULT_PROGRAM

Use this variable to specify the name of the program to be run by default if no program name is specified on the command line. The name you give here is treated exactly as it would be if you had typed it on the command line. The default is cbl.out.

Parent topic: Configuration Variables


DEFAULT_TIMEOUT

This variable is used by the runtime and Web Runtime to define the length of time, in seconds, that they will wait for a response from acuserve before timing out. The default value for this variable is 25 seconds. Some networks have long connect times and the default value may not be long enough to allow the application to connect. For example, to change the timeout default of 25 seconds to one minute, you would set the following:

DEFAULT_TIMEOUT = 60

If the runtime or Web Runtime receives an error before the specified time, they will time out immediately. This variable only works with AcuServer client runtimes and AcuServer client Web Runtimes.

Parent topic: Configuration Variables


DEFER_EVENTS

Event procedures that are triggered recursively can cause application errors, for example processing a grid control while holding the Page Down key. If a control's event procedure is long running, it can fire a second time before the processing of the initial event procedure is completed, resulting in the procedure being recursively. This could modify variables that were in use when the procedure drops back to the original event's processing.

Set this configuration variable to 1 (True), to ignore events until processing returns from the control's event procedure. This is useful for applications that encounter difficulty processing events. The default value of this variable is FALSE.

Parent topic: Configuration Variables


DEFER_WHEEL_EVENTS

This variable lets you control the use of the MSG_PAGED_PREV_WHEEL and MSG_PAGED_NEXT_WHEEL events, providing finer control over mouse wheel movements, especially in grid controls.

Spinning the mouse wheel quickly in a grid control can cause errors if the event procedure can not respond quickly enough. Potential errors can include:

  • index out of bounds if the event procedure is recursively called from within a perform loop.
  • PERFORM stack overflow if the events procedures cause recursive calls to come in too quickly.

When DEFER_WHEEL_EVENTS is set to TRUE, the MSG_PAGED_PREV_WHEEL and MSG_PAGED_NEXT_WHEEL events are ignored until processing returns from the control's event procedure. The default value for this variable is TRUE.

Parent topic: Configuration Variables


DISABLED_CONTROL_COLOR

This variable allows character-based hosts to use color and video attributes to distinguish disabled screen controls from enabled controls. It can be set to a variety of numeric values that express combinations of attributes. When it is set to 0 (off, false, no), disabled controls appear the same as enabled ones. See COLOR Phrase in the ACUCOBOL-GT Reference Manual for a description of other numeric values that can be used.

Parent topic: Configuration Variables


DISPLAY_SWITCH_PERIOD

This variable helps to determine how frequently the program's threads will switch control. After a thread performs the value of DISPLAY_SWITCH_PERIOD display operations, the runtime switches control to another thread (if one exists). Note that because a single DISPLAY statement can compile into multiple display operations, and because thread switching is also affected by other program operations (such as file I/O), it is impossible to predict or control when a thread will change control based on the presence of DISPLAY statements in the source.

By setting DISPLAY_SWITCH_PERIOD to lower values, you cause windows that are updated by multiple threads to update more uniformly, but more time will be spent in the thread switching code. Setting DISPLAY_SWITCH_PERIOD to higher values will decrease the switching overhead, but will also cause the windows to update in blocks. In most cases, applications that use threads will run well with the default setting of 10.

Parent topic: Configuration Variables


DLL_CONVENTION

This variable allows you to specify the calling convention used to call DLLs. When this variable is set to 0, the cdecl (standard C) interface is used. When this variable is set to 1, the stdcall (Pascal/WINAPI) interface is used. The default for this variable is "0".

Note that there are a few ways to override the DLL_CONVENTION setting:

  • You can specify a list of DLL names and calling conventions in the SHARED_LIBRARY_LIST configuration variable. This variable can be set in the environment, in the runtime configuration file, or programmatically with the SET ENVIRONMENT statement.
  • You can specify the calling convention for individual library functions in the COBOL CALL statement.
  • You can set the CODE_MAPPING variable to 1, then use configuration entries to specify the calling convention for individual functions.
  • You can specify a list of DLL names and calling conventions using the -y runtime option. (see the -y listing in topic Runtime Options, ACUCOBOL-GT User's Guide.)

In all of these cases, the runtime uses the specified calling convention and ignores the value of the DLL_CONVENTION configuration variable. See Working with Windows Technologies in A Guide to Interoperating with ACUCOBOL-GT for more details about calling DLLs.

Parent topic: Configuration Variables


DLL_SUB_INTERFACE

This variable identifies the routine to be used as the sub interface routine within a DLL. It applies only to Windows systems. Set DLL_SUB_INTERFACE to the name of the routine you want to use. This name may be sub or any name you choose. The runtime checks DLL_SUB_INTERFACE when a DLL is loaded. You may change its value afterwards without any effect on DLLs that have already been loaded.

If DLL_SUB_INTERFACE is empty (default), the runtime does not look for a sub interface routine in a called DLL.

Parent topic: Configuration Variables


DLL_USE_SYSTEM_DIR

When a program calls an unloaded DLL, the value of this variable determines whether the runtime attempts to find the DLL in the Windows and System folders. When set to the default value 1 (on, true, yes), the runtime looks in the Windows and System folders. When set to 0 (off, false, no) the runtime does not look in the Windows and System folders. See Working with Windows Technologies in A Guide to Interoperating with ACUCOBOL-GT for more details about calling DLLs.

Parent topic: Configuration Variables


DOS_BOX_CHARS

This variable allows you to redefine the line drawing characters used with the Windows console (DOS-box) runtime. The value of DOS_BOX_CHARS is a list of characters that draw the line segments. It should be a list of 13 space-delimited characters that correspond, in order, to the line segments as listed below. To redefine the DOS line drawing characters, specify the characters you want in the following order:

  1. horizontal line
  2. vertical line
  3. upper left corner
  4. upper right corner
  5. lower left corner
  6. lower right corner

Four three-way intersections -

  1. missing bottom line
  2. missing left line
  3. missing top line
  4. missing right line

and -

  1. the four-way intersection
  2. upper-half block
  3. lower-half block

These line drawing characters may also be specified by decimal value. Characters that are not available on a particular machine should be specified with the decimal value 0.

The default value for DOS_BOX_CHARS depends on the CODE_SYSTEM configuration variable. If CODE_SYSTEM is not set, or is set to 0 (or ASCII or EBCDIC), the default is:

DOS_BOX_CHARS 196 179 218 191 192 217 193 195 194 180 197 223 220

If CODE_SYSTEM is set to a non-zero value, which is the case in the ACUCOBOL-GT JPN version, the default is:

DOS_BOX_CHARS 6 5 1 2 3 4 21 25 22 23 16 0 0
Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


DOS_SYS_EMULATE

When set to 1 (on, true, yes), this variable causes a program running in the Windows console runtime to run as if it's in a DOS environment. One of its effects is that it prevents such a program from attempting to display GUI screens. It is set to 0 (off, false, no) by default. This variable has meaning only in Windows environments.

Parent topic: Configuration Variables


DOUBLE_CLICK_TIME

This variable has meaning only on systems that support a mouse. It controls the double-click rate on systems that do not control it themselves.

Specify the maximum time (in hundredths of a second) allowed between two clicks that are to be interpreted as a double-click. For example, if DOUBLE_CLICK_TIME were set to 75 (three-quarters of a second), then any two clicks that occur at least that close together would be considered a double-click rather than two single clicks.

The default value is 50 (one-half of a second).

Parent topic: Configuration Variables


DUPLICATES_LOG

This variable is used during bulk addition of Vision files. It causes Vision to write files rejected for having illegal duplicate keys to a log file. Set DUPLICATES_LOG to the name of a file in which to store the records. If this log file already exists, it is overwritten. You should use a separate log file for each file opened with bulk addition. You can do this by changing the setting of DUPLICATES_LOG between OPEN statements, as follows:

SET ENVIRONMENT "DUPLICATES_LOG" TO "file1.rej"
OPEN OUTPUT FILE-1 FOR BULK-ADDITION

SET ENVIRONMENT "DUPLICATES_LOG" TO "file2.rej"
OPEN EXTEND FILE-2 FOR BULK-ADDITION

If no duplicate records are found, the log file is removed when the Vision file is closed. If DUPLICATES_LOG has not been set, or is set to spaces, no log file is created.

Note: The duplicate-key log file may not be placed on a remote machine using AcuServer. The log file must be directly accessible by the machine that is running the program.

See Bulk addition mode for Vision in the ACUCOBOL-GT User's Guide, for instructions on how to read the log file.

Parent topic: Configuration Variables


DYNAMIC_FUNCTION_CALLS

This variable allows you to specify a list of functions or function name prefixes that the runtime treats as dynamic functions and therefore searches first, before searching the disk for COBOL programs. This speeds the resolution of calls to functions in the current process or in a shared library.

The runtime checks call names for matches in the list specified in the variable. If a match is found, the runtime attempts to call the routine directly in the current process and in each of the loaded shared libraries. If these attempts fail, the runtime attempts to load a COBOL program with the specified name.

Set DYNAMIC_FUNCTION_CALLS to a space- or comma-delimited list of names of frequently called functions that are linked into the current process or in one of the loaded shared libraries.

The asterisk "*" character can be appended to the end of a name as a wild card. In this case, the characters before the asterisk are treated as a prefix and match any call name that begins with that prefix. A value of asterisk ("*") alone matches all function names. Use this to cause the runtime to treat all names as dynamic functions first before searching the disk or memory for a COBOL program with a matching name.

The value of DYNAMIC_FUNCTION_CALLS is case insensitive. The default value is empty.

DYNAMIC_FUNCTION_CALLS can be set in the environment, configuration file, or programmatically with the SET verb. Set it to spaces to clear the list.

When DYNAMIC_FUNCTION_CALLS is set in the configuration file, there is no limit on the number of function names or overall size of the value of the configuration variable. To specify a configuration file value on multiple lines, you must prepend each line after the first with "-". For example:

DYNAMIC_FUNCTION_CALLS =
-                       func1,
-                       func2,
-                       func3

The line continuation processing removes all leading and trailing spaces so in this case you must separate the values with a comma (that is, append a comma to each line).

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


DYNAMIC_MEMORY_LIMIT

The value of this variable indicates the maximum number of bytes of dynamic memory that the ACUCOBOL-GT runtime will use to cache canceled programs when the logical cancel mechanism is enabled. When the total amount of memory exceeds the value of DYNAMIC_MEMORY_LIMIT, the runtime releases all memory held by programs that have been logically canceled.

Valid values are:

-1 | (the default) no memory limit. In transaction processing systems, memory used by programs that have been logically canceled is released only by the CICS transaction, CEMT SET PROGRAM(program_name) NEWCOPY
0 | all cancels are physical; program memory is not cached
1 to 2147483647 | the maximum number of bytes of dynamic memory

Memory management and physical and logical cancels is in Memory Management, ACUCOBOL-GT Users Guide. DYNAMIC_MEMORY_LIMIT is used in conjunction with the LOGICAL_CANCELS configuration variable.

Parent topic: Configuration Variables


ECN-3699

This variable relates to read-only entry fields. As of Version 8.1, read-only entry fields were changed to conform to standard Windows behavior in that the background color is always gray (regardless of the COBOL program's Color setting). If you need the ability to change the color of read-only entry fields, set the runtime configuration variable ECN_3699 to 0.

The default behavior will not allow color changes and matches Windows behavior: read-only entry fields have gray backgrounds.

Parent topic: Configuration Variables


ECN-3975

This variable relates to a correction made in version 8.1.2. In a Thin Client setup, an INQUIRE on a control that had been acted upon by the Layout Manager would always return the starting size and position. This behavior has been corrected.

To apply this fix turn on the runtime configuration variable ECN_3975 by setting it to TRUE or 1. The Default behavior is FALSE or 0.

Turning on this variable fixes the inquire problem, but may affect display behavior that was incorrectly "working" based on the previous incorrect size and position.

For example, you may have defined controls that were affected by the layout manager and also had variables that specified the position of the controls.

You then DISPLAY the control immediately after the resize of the screen.

The expected behavior is for the control position to not change since the DISPLAY should override the effect of the Layout manager.

However, since the previous size and position on the application host side was not updated, the thin client would not redraw the control. Not redrawing the control nullifies the effect of the DISPLAY statement. Turning on this configuration variable will now redraw the control based on the values in the position variables.

Parent topic: Configuration Variables


ECN-4159

This configuration variable lets you turn off the actions of ECN-4159. The ECN-4159 configuration variable addresses an issue where Acuthin can stop responding in the debugger. To address the issue, when the run time sends a query to the thin client that requires an immediate response, any events that come through are only queued, and not acted upon until an ACCEPT statement is encountered.

If required, the ECN-4159 configuration variable can be set to OFF, which causes the run time to act as if this ECN is not implemented.

Parent topic: Configuration Variables


ECN-4273

This configuration variable allows you to turn off the actions of ECN-4273. This change was introduced to fix a problem where the Web thin client screen was occasionally not getting updated in some cases; however, in some of those cases, this fix introduced some screen flickering.

By setting this variable to 1 you are able to turn off that previous change if you find the screen flickering unacceptable.

Parent topic: Configuration Variables


ECN-4296

This configuration variable lets you turn on the actions addressed by ECN-4296. ECN-4296 prevents this error:

ACCEPT recursion limit reached!
Further execution may cause unpredictable results.

from occurring when running a COBOL program under the following conditions:

  • Using a remote desktop session
  • Sitting on an ACCEPT statement within an event procedure
  • Hiding and restoring the remote desktop session ten times or more.

The default for the ECN-4296 configuration variable is ON, but if required it can be set to OFF, which causes the run time to act as if the ECN is not implemented.

Parent topic: Configuration Variables


ECN-4315

When an ACCEPT statement can receive messages from other threads, and that ACCEPT statement also executes a HOT-KEY program, it would no longer receive messages until it was restarted. ECN-4315 was created to address this issue and allow ACCEPT to receive messages after executing a HOT-KEY program without restarting. This configuration variable lets you turn off the actions addressed by ECN-4315.

Set this configuration variable to OFF to turn off the ECN-4315 behavior.

ECN-4315 OFF

The default for this variable is ON.

Parent topic: Configuration Variables


EDIT_MODE

This is an obsolete entry that has been replaced by the KEYSTROKE configuration variable. Its setting is ignored.

Parent topic: Configuration Variables


EF_UPPER_WIDE

This variable determines which font measure is used to compute the width of an entry field with the UPPER style. If the value is 1 (on, true, yes), the entry field is sized with the wide font measure. The default value of EF_UPPER_WIDE is 1. See Entry Field for a description of how entry fields are measured.

Parent topic: Configuration Variables


EF_WIDE_SIZE

This variable sets the boundary size that determines whether an entry field is sized with the standard or wide font measure. An entry field that has a specified width greater than the value of EF_WIDE_SIZE is always sized with the standard font measure. Entry fields that are both non-numeric and not larger than EF_WIDE_SIZE are sized with the wide font measure. The default value of EF_WIDE_SIZE is 5. Setting this variable to 0 causes all entry fields to be sized with the standard font measure (exception: see EF_UPPER_WIDE above). Note that setting the value of this variable to a number larger than your largest entry field causes all entry fields to use the wide font measure. See Entry Field for a description of how entry fields are sized.

Parent topic: Configuration Variables


EOF_ABORTS

This configuration variable can be used to handle two unexpected loop conditions:

  1. a loop that results when the runtime has been started with -i and an input file terminates prematurely.
  2. a loop that results when a terminal emulator disconnects unexpectedly.

If the runtime is started with the -i option and a loop occurs when an input file terminates prematurely, you can set EOF_ABORTS to 1 (on, true, yes) to cause the runtime to shut down when an ACCEPT statement detects an end-of-file condition.

On UNIX/Linux systems, if the runtime enters a loop due to an unexpected disconnect from a terminal emulator, you can set EOF_ABORTS to a value of 2 to cause the runtime to generate a hangup signal (SIGHUP) when it detects an EOF on standard input (stdin).

The default value is 0 (off, false, no).

Parent topic: Configuration Variables


EOL_CHAR

This configuration variable determines the character that is used to mark the end of each line when a pre-existing line sequential file is read. This should be set to the ASCII value of the desired character. The default value is 10 (line-feed). This option may be useful if you must process a line-oriented file that has an unusual line terminator. This configuration variable has no effect under VMS (RMS does not support it).

Parent topic: Configuration Variables


ERRORS_OK

Normally, if a file error occurs and there is no AT END, INVALID KEY, or Declarative statement to handle it, the runtime system prints an error message and halts. You can cause the runtime to ignore file errors and continue processing by setting ERRORS_OK to either 1 (on, true, yes) or 2 (FILESTATUS).

By default, ERRORS_OK is set to 0 (off, false, no).

When ERRORS_OK is set to 1, if a file error occurs the runtime continues as if no error occurred.

When ERRORS_OK is set to 2, if a file error occurs and there are no Declaratives but a file status variable is defined, the runtime ignores the error and continues processing. However, if a file error occurs and there are no Declaratives and a file status variable is not defined, the runtime halts.

Note: In general, it is not recommended that you configure the runtime to ignore file errors.
Parent topic: Configuration Variables


EXIT_CURSOR

When a STOP RUN is executed, the ACUCOBOL-GT runtime system normally places the cursor on the last line of the screen and then scrolls the screen one line. This allows the operating system prompt to appear on a new blank line at the bottom of the screen. To inhibit this behavior, set EXIT_CURSOR to 0 (off, false, no). This causes the runtime system to leave the cursor in its current location when the program exits. The default value 1 (on, true, yes) causes the standard ACUCOBOL-GT cursor positioning.

This variable has no effect on Windows systems.

Parent topic: Configuration Variables


EXPAND_ENV_VARS

Setting this variable to 1 (on, true, yes) causes the runtime to expand environment variables in filename specifications. This is the last step of file name interpretation process. A file specification that includes a "$" character will have all the characters from "$" to the end of the name or to the next "/" or "\" replaced with the value of the matching environment variable. For example, if the program attempts to open $mydir/myfile, the environment and configuration file are searched for the variable mydir. If found, its value is substituted. If not found, the replacement is null. Referring to the preceding example, if mydir is not defined, the runtime attempts to open /myfile. See File Name Interpretation for more information.

The default value is 0 (off, false, no).

Note: The "$" character is a valid filename character in many file systems, including NTFS and most UNIX file systems. If you want to use dollar signs in your file names, you should not enable this option. In particular, if a user chooses the name of the file, you should keep this option disabled.

If you also use FILE_ALIAS_PREFIX configuration variables: FILE_ALIAS_PREFIX, note that when EXPAND_ENV_VARS is set to 1, FILE_ALIAS_PREFIX treats $FILE1 and FILE1 the same.

Parent topic: Configuration Variables


EXTEND_CREATES

Setting this configuration variable to 1 (on, true, yes), causes OPEN EXTEND statements to create a new file when the file being opened is not present. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


EXTFH_KEEP_TRAILING_SPACES

An EXTFH_KEEP_TRAILING_SPACES configuration variable allows you to preserve trailing spaces in line sequential file records when using our EXTFH module with EXTSM. Set this variable to 1 (on, true, yes) to retain the trailing spaces, which is the runtime's default behavior. With a default value of 0 (off, false, no), trailing spaces are removed.

Note that a related configuration variable is the STRIP_TRAILING_SPACESS variable.

Parent topic: Configuration Variables


EXTERNAL_SIZE

ACUCOBOL-GT manages external data items by allocating them in pools. The minimum size of each pool is set by the EXTERNAL_SIZE variable. When a new external data item is needed, it is allocated from an existing pool. If it doesn't fit in any of the allocated pools, a new pool is allocated. The size of this pool is the same as the size of the data item, but never smaller than the value specified by the EXTERNAL_SIZE configuration variable. Using this larger pool reduces memory fragmentation. Because external data items remain allocated after programs are canceled, it's best to allocate the external data items together so they don't break up the memory space. The default value for EXTERNAL_SIZE is 8192. The maximum value is 32767.

Parent topic: Configuration Variables


EXTRA_KEYS_OK

This configuration variable allows you to open an indexed file without specifying all of that file's alternate keys. When it is set to 1 (on, true, yes), you may open an indexed file that contains more keys than are described by your program, and no file error will occur. However, you will still receive a file error if you open a file that does not contain all of the keys described in your program. EXTRA_KEYS_OK is useful when you are adding new alternate keys to an existing file because you do not need to rework your existing programs. This configuration variable is ignored if you use a Version 1.4 or earlier ACUCOBOL-85 object file.

The default value is 0 (off, false, no).

Parent topic: Configuration Variables


F10_IS_MENU

By convention, the F10 key is used by Windows and Windows NT to activate program menus. This action is controlled automatically by the program. The F10_IS_MENU configuration variable allows you to set the runtime to handle the F10 key as a user defined-key. The default setting is 1 (on, true, yes). When you change the setting to 0 (off, false, no) you inhibit the menu activation capability. For example, action of Shift-Ctl-F10 may only be defined by the user if F10_IS_MENU is set to "0", otherwise this key combination activates context menus. This variable does not affect the behavior of the mouse. However, the mouse continues to work with the menu.

Parent topic: Configuration Variables


FAST_ESCAPE

This configuration variable determines how long the runtime will wait after receiving an escape key before deciding that the key is actually intended as an escape key, and not as the start of a function key sequence. (Increasing the number causes the runtime to wait longer.) The default setting varies with the machine. It is generally between 20 and 100.

This variable has no effect on Windows systems.

Parent topic: Configuration Variables


FAST_SIGN_DECODE

Version 7.3 introduced a new algorithm to decode sign bytes in USAGE DISPLAY (sign incorporated) data items. The new algorithm is 3-4 times faster than the previous one, but produces unexpected results for undefined or non-initialized numeric data items.

This configuration variable turns on this faster algorithm introduced in Version 7.3.

To use the Version 7.3 algorithm, set the FAST_SIGN_DECODE configuration variable to TRUE. If using this algorithm, numeric data items must be defined/initialized, otherwise incorrect results may occur.

The default value is FALSE which means the pre-7.3 version of the algorithm is used. The pre-7.3 version does not require numeric data items to be defined/initialized.

Parent topic: Configuration Variables


FIELDS_UNBOXED

On most GUI systems, including Microsoft Windows, entry fields are boxed by default. This can cause problems when you are converting applications that have fairly full screen displays, because the box adds roughly 50% to the height of the field. This can make it difficult to fit all the existing fields onto the user's screen.

FIELDS_UNBOXED provides a global method of removing boxes on entry fields. If this field is set to 1 (on, true, yes), the system does not display a box around entry fields. Technically this has three effects:

  1. If it is set when the entry field is initially created, the NO-BOX property is automatically implied.
  2. If it is set when a floating window is initially created, the window's LABEL-OFFSET property is given a default value of 0.
  3. When an entry field is measured by the CELL phrase of the DISPLAY FLOATING WINDOW statement, its height is measured without the box.

On character-based systems, setting this variable to 1 (on, true, yes) eliminates the display of the left and right delimiting symbols used in the textual emulation of entry fields. (See GUI_CHARS for more information about these delimiting symbols). Eliminating these symbols affects the location at which the entry fields are displayed on character-based systems.

The default value for this option is 0 (off, false, no).

This variable can be overridden for individual entry fields in the program with the BOXED style in the entry field definition.

Parent topic: Configuration Variables


FILE_ALIAS_PREFIX

This variable allows you to specify a list of strings to prefix to a file name before searching for that name in the configuration file or environment. Data and code file search paths are described in more detail in Code and Data File Search Paths.

When searching for a file alias:

  1. The runtime constructs the file alias name by prepending the first string listed in FILE_ALIAS_PREFIX to the file name and searches for that name in the environment or configuration file.
  2. If the name is not found, the runtime constructs a new name by prepending the second string in FILE_ALIAS_PREFIX to the file name and searches for that alias.

This process is repeated with each string in FILE_ALIAS_PREFIX until a file alias name is found or the end of the list is reached.

For example, with:

SELECT file1-name ASSIGN TO "FILE1".

by default, the runtime looks for a configuration or environment variable named "FILE1" and, if found, substitutes its value for the file name. If you specify:

FILE_ALIAS_PREFIX "":DD_

the runtime first looks for "FILE1" and, if not found, looks for "DD_FILE1".

The default value of FILE_ALIAS_PREFIX is an empty string (""). Specifying an empty string as an entry in FILE_ALIAS_PREFIX causes the runtime to search for the file name itself as an alias name. Up to 4096 characters can be specified for the value of this variable.

Note: Separate strings by one or more spaces. A space is a valid separator on all systems. On UNIX systems, you can also separate entries with a colon. On Windows systems, a semicolon can be used and on VMS systems, a comma can be used. Strings can be enclosed in quotation marks. You can specify an empty string using two consecutive quotation marks.

Note on using with EXPAND_ENV_VARS

If you use the EXPAND_ENV_VARS configuration variable and the file name includes a dollar sign ($), the FILE_ALIAS_PREFIX logic is applied to the environment variable name. For example, if EXPAND_ENV_VARS is set to 1 (on, true, yes), "$FILE1" and "FILE1" are treated the same.

For example, with:

EXPAND_ENV_VARS=1
FILE_ALIAS_PREFIX=DD_

the following statement,

SELECT file1-name ASSIGN TO "DIR1/$DIR2/FILE1".

causes the runtime to search for an environment or configuration variable named "DD_DIR2" (instead of "DIR2") and, if found, substitute its value for "$DIR2".

Parent topic: Configuration Variables


FILE_CASE

This configuration variable allows you to adjust the case of data file names. Possible values include:

NONE or "0" | (the default) data file names are not translated
LOWER or "1" | data file names are translated to lower case, including directory (path) elements
UPPER or "2" | data file names are translated to upper case, including directory (path) elements
LOWER_BASE or "3" | data file names are translated to lower case, excluding directory (path) elements
UPPER_BASE or "4" | data file names are translated to upper case, excluding directory (path) elements

Translation occurs before the FILE_PREFIX and FILE_SUFFIX configuration options are applied. You should make sure that those variables specify the correct case.

File name translation does not occur if the file name starts with -F, -D, or -P. See File Name Interpretation for more information.

Parent topic: Configuration Variables


FILE_CONDITION

This configuration variable can be used to alter the File Status value of an individual file status condition. We recommend that you use one of the four pre-defined file status code sets instead. If you need to change an individual status code, contact Technical Support for assistance.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


FILE_IO_PEEKS_MESSAGES

This configuration variable tells the Windows runtime to automatically call the Windows PeekMessage() API function between file operations. When the FILE_IO_PEEKS_MESSAGES configuration variable is set to 1 (on, true, yes), the runtime calls PeekMessage() with flags that tell it to simply check for messages without removing them from the message queue. This operation tells Windows that the application is alive and responding. The default value of the variable is 0 (off, false, no).

Parent topic: Configuration Variables


FILE_IO_PROCESSES_MESSAGES

This configuration variable can be used to control whether the runtime processes system messages while performing file I/O operations. When it is set to "1" (on, true, yes), the runtime will process system messages while doing file I/O operations. This was the default behavior prior to Version 3.2. Note that the processing of system messages during file I/O should only be enabled under special conditions, as described below.

To understand when it is appropriate to set this configuration variable, it is important to be familiar with system messages and how the ACUCOBOL-GT runtime and your program respond to them. For the purposes of this discussion, system messages are the mechanism used by graphical systems, such as Windows, to communicate with your program. They are what the operating system uses to facilitate the communication of user and system activity to the program. They are similar to ACUCOBOL-GT's events. Prior to Version 3.2, the runtime automatically processed system events during file operations. This allows the user to manipulate an application window (for example, minimizing it) while file I/O operations are performed. If the application suspends the processing of system messages, the system appears to the user to be frozen.

Starting with Version 3.2, this feature is turned off by default. This is because the processing of messages outside of an ACCEPT statement can cause flaws in a program that uses multithreading or modeless windows. It also creates a state where event procedures can be called at unexpected times. In addition, the controls of the application are not actually functional, though they appear to be working to the user.

Generally speaking, setting this variable is useful only when the application does not use multithreading, modeless windows, or event procedures.

Note: The proper way to process system messages while performing other operations is to start a second thread that performs an ACCEPT statement while the main thread continues with the work. This allows the system to process messages under control of an ACCEPT, which provides a well-defined point in your program from which event procedures can be called.
Parent topic: Configuration Variables


FILE_PREFIX

This variable defines a set of directories that the runtime searches to locate a data file. The default value is "." (current working directory). Data and code file search paths are described in more detail in Code and Data File Search Paths.

Directories can be a mix of relative and absolute paths. Entries are separated by one or more spaces. A space is a valid separator on all systems. Alternatively, on UNIX systems you can also separate entries with a colon. On Windows systems a semicolon can be used. On VMS systems a comma can be used.

You can specify a directory path that contains embedded spaces if you surround the path with quotation marks. For example:

FILE_PREFIX  C:\"Sales Data"  C:\"Customers"

Up to 4096 characters can be specified for the value of this variable.

Parent topic: Configuration Variables


FILE_STATUS_CODES

This variable determines which set of file status codes to use. The default value is 85. See File Status Codes for more information.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


FILE_SUFFIX

The value of this variable is automatically appended to data file names that do not contain an explicit suffix. A suffix is the portion of a file name that follows a period. For example, if FILE_SUFFIX is set to DAT, then opening a file called "EMPFILE" would actually open the file called EMPFILE.DAT. The default value is empty.

Parent topic: Configuration Variables


FILE_TRACE

This variable allows you to start file tracing without opening the debugger. Set this variable to a non-zero value to save information about all file OPENs, READs, and WRITES in the error file. This is equivalent to specifying "tf n" from the debugger (where n is an integer). The default is 0. See File Tracing for more information about the file trace feature.

Parent topic: Configuration Variables


FILE_TRACE_FLUSH

Set this variable to 1 (on, true, yes) to flush the error file after every WRITE statement. This is equivalent to using t flush from the debugger. The default is 0 (off, false, no). See File Tracing for more information about the file trace feature.

Parent topic: Configuration Variables


FILE_TRACE_TIMESTAMP

Set this variable to 1 (on, true, yes) to cause file trace timestamp information to be recorded in the error file. When this variable is enabled, a timestamp is placed at the beginning of every line in the trace file. The format of the timestamp is: HH:MM:SS.mmmmmm, where mmmmmm is the finest resolution that the runtime can obtain from the system. The default setting of this variable is 0 (off, false, no).

Timestamp information is included only when file trace information is directed to a file. Timestamp output can add significant I/O overhead and may have a noticeable impact on performance.

Parent topic: Configuration Variables


filename

This configuration variable allows you to map Vision 4 and 5 files to a different directory. Vision examines the name of each physical file it attempts to open to determine if the file should be mapped to a different directory. The configuration variable used is constructed from the file's base name and extension, with all letters converted to upper case and all non-alphanumeric characters converted to underscores.

For example, assume you open /usr/data/custfile.dat, and a configuration variable CUSTFILE_DAT has the value /usr2/data/custfile.dat. Vision treats this value as the actual file name to open, and custfile.dat ends up in the /usr2/data directory rather than /usr/data.

Because the extension is included in the configuration variable name, you can place different parts of a multi-segment file in different directories. If no name is found for a particular segment, then the segment name is used unchanged. Note that you can move parts of a file around by simply moving the segment and adding/modifying its corresponding configuration name. Name mapping is done directly by Vision (as opposed to, for example, FILE_PREFIX, which is handled by the runtime). As a result, all programs that use Vision (such as vutil and vio) use this variable when present. For programs other than the runtime, the variable must be set in the environment rather than the configuration file.

Two configuration variables can affect the value of this variable. They are: V_BASENAME_TRANSLATION and V_STRIP_DOT_EXTENSION.

This variable is similar to the filename_VERSION configuration variable.

The filename translation performed by this configuration variable is performed by Vision itself. The runtime can also perform filename translation. See File Name Assignments for more information.

Parent topic: Configuration Variables


filename_DATA_FMT

This configuration variable specifies a format for naming the data segments of Vision 4 and 5 files. (See filename_INDEX_FMT for details about naming the index segments, as both variables should be set to corresponding patterns). The configuration variable used is constructed from the file's base name and extension, with all letters converted to upper case and all non-alphanumeric characters converted to underscores, followed by the _DATA_FMT string. Note that by design, this variable does not modify the first specified data segment. The first data segment retains the originally specified name. The filenames of the additional segments of a Vision file are generated from the name of the initial data segment. The filename_DATA_FMT variable allows you to change the way the names of the following data segments are formed, but the names still originate from the name of the initial data segment. As long as the names are as expected (and you have set filename_DATA_FMT and filename_INDEX_FMT accordingly) the segments will be found properly.

Suppose that the regular name of your COBOL file is /usr1/gl.dat. The variable you would use to set the data segment naming format for this file is GL_DAT_DATA_FMT.

The variable must be set equal to a pattern that shows how to create the segment names. The pattern shows how to form the base name and extension for each segment. Part of this pattern is a special escape sequence (such as %d) that specifies how the segment number should be represented. Choices include %d (decimal segment numbers), %x (lowercase hexadecimal numbers), %X (uppercase hexadecimal numbers), and %o (octal numbers).

For example, setting the variable GL_DAT_DATA_FMT=gl%d.dat would result in data segments named /usr1/gl.dat (remember that the first data segment is not affected), /usr1/gl1.dat, /usr1/gl2.dat, and so forth.

Escape sequence definitions:

The %d in the value of the filename_DATA_FMT above is a printf-style escape sequence. Most reference books on the C language contain an in-depth explanation of these escape sequences, and UNIX systems typically have a man page (man printf) that explains them in detail. Here are the basics:

  • %d expands into the decimal representation of the segment number.
  • %x expands into the hexadecimal representation (with lower case a-f) of the segment number.
  • %X expands into the hexadecimal representation (with upper case A-F) of the segment number.
  • %o expands into the octal representation of the segment number.
  • You can add leading zeros to the number (to keep all the file names the same length) by placing a zero and a length digit between the percent sign and the following character. %02d would result in 00, 01, 02, and so forth, when expanded.
  • To embed a literal % in the file name, use %%.

The escape sequence can be positioned anywhere in the file name, including the extension.

Note: While the runtime checks for this segment naming variable in the runtime configuration file as well as in the environment, utilities such as vutil and vio check only the environment. Therefore, if you are using this variable with the runtime and vio or vutil, you must set the variable in the environment and not in the configuration file.

Two configuration variables affect the value of this variable: V_BASENAME_TRANSLATION and V_STRIP_DOT_EXTENSION.

The filename translation performed by this configuration variable is performed by Vision itself. The runtime can also perform filename translation. See File Name Assignments in the ACUCOBOL-GT User's Guide for more information.

Parent topic: Configuration Variables


filename_FILESYSTEM

filename_FILESYSTEM is a synonym for filename_HOST.

Parent topic: Configuration Variables


filename_HOST

Note: filename_FILESYSTEM is a synonym for filename_HOST.

If the program opens an existing file or creates a new one, you can tell the runtime the file system to use with that file. The Vision file interface is used by default. You specify the file system with one of two configuration variables: DEFAULT_FILESYSTEM, or filename_HOST (syn. filename_FILESYSTEM). DEFAULT_FILESYSTEM specifies the default file system for all files (see the entry for DEFAULT_FILESYSTEM). filename_HOST specifies the file system for an individual file. For example,

filename_HOST filesystem

assigns the specified data file to the named file system. Any file so assigned uses the designated file system and not the one specified by DEFAULT_FILESYSTEM. Filename must be the base name of the file and cannot include the path or the file extension (any part of the name that follows the first dot ("."). For example, to specify that data file IDX1.DAT be handled by the EXTFH interface, you would specify:

IDX1_HOST EXTFH

or

IDX1_FILESYSTEM EXTFH

You must specify only the base name of the file in filename.

To specify that the data file DXML1.DAT be handled by the XML interface, you could specify:

DXML1_HOST XML

Note that XML can be specified only with sequential files.

Parent topic: Configuration Variables


filename_INDEX_FMT

This configuration variable specifies a format for naming the index segments of Vision 4 and 5 files. (See filename_DATA_FMT for details about naming the data segments, as both variables should be set to corresponding patterns). The configuration variable used is constructed from the file's base name and extension, with all letters converted to upper case and all non-alphanumeric characters converted to underscores, followed by the "_INDEX_FMT" string. Note that by design, this variable does not modify the first specified index segment. The first index segment retains the originally specified name. The filenames of the additional segments of a Vision file are generated from the name of the initial index segment. The filename_INDEX_FMT variable allows you to change the way the names of the following data segments are formed, but the names still originate from the name of the initial index segment. As long as the names are as expected (and you have set filename_DATA_FMT and filename_INDEX_FMT accordingly) the segments will be found properly.

Suppose that the regular name of your COBOL file is /usr1/gl.dat. The variable you would use to set the format for naming the file's index segments is GL_DAT_INDEX_FMT.

The variable must be set equal to a pattern that shows how to create the segment names. The pattern shows how to form the base name and how to form the extension for each segment. Part of this pattern is a special character (such as %d) that specifies how the segment number should be represented. Choices include %d (decimal segment numbers), %x (lowercase hexadecimal numbers), %X (uppercase hexadecimal numbers), and %o (octal numbers).

For example, setting the variable GL_DAT_INDEX_FMT=gl%d.idx would result in index segments named /usr1/gl0.idx, /usr1/gl1.idx, /usr1/gl2.idx, and so forth.

Escape sequence definitions:

The %d in the value of the filename_INDEX_FMT above is a printf-style escape sequence. Most reference books on the C language contain an in-depth explanation of these escape sequences, and UNIX systems typically have a man page (man printf) that explains them in detail. Here are the basics:

  • %d expands into the decimal representation of the segment number.
  • %x expands into the hexadecimal representation (with lower case a-f) of the segment number.
  • %X expands into the hexadecimal representation (with upper case A-F) of the segment number.
  • %o expands into the octal representation of the segment number.
  • You can add leading zeros to the number (to keep all the file names the same length) by placing a zero and a length digit between the percent sign and the following character. %02d would result in 00, 01, 02, and so forth when expanded.
  • To embed a literal "%" in the file name, use %%.

The escape sequence can be positioned anywhere in the file name, including the extension.

While the runtime checks for this segment naming variable in the runtime configuration file as well as in the environment, utilities such as vutil and vio check only the environment. Therefore, if you are using this variable with the runtime and vio or vutil, you must set the variable in the environment and not in the configuration file.

Two configuration variables affect the value of this variable: V_BASENAME_TRANSLATION and V_STRIP_DOT_EXTENSION.

The filename translation performed by this configuration variable is performed by Vision itself. The runtime can also perform filename translation. See File Name Assignments for more information.

Parent topic: Configuration Variables


filename_LOG

This configuration variable specifies individual log files to be used by the transaction logging system. The format of the variable is:

     filename_LOG logfilename

where filename is the base name of the data file, and logfilename is the name of the log file. filename should not include any directory names nor a file extension. logfilename can include the absolute or relative directory path ending with the name of the log file. If the log file is not found, a new file is created with the specified name. Note that logfilename can have remote name notation.

Parent topic: Configuration Variables


FILENAME_SPACES

When this configuration variable is set to 1 (on, true, yes), filenames may contain embedded spaces and the runtime considers the last non-space character as the end of the name. The default is 1. When this configuration variable is set to 0 (off, false, no), then filenames may not contain embedded spaces and the name terminates at the first space character. For example:

C:\temp dir\my file name

is read as:

C:\temp

This affects the behavior of the library routines that take a filename as an argument:

  • C$CHDIR
  • C$COPY
  • C$DELETE
  • C$FILEINFO
  • C$FULLNAME
  • C$MAKEDIR
  • C$RESOURCE
  • CBL_COPY_FILE
  • CBL_CREATE_DIR
  • CBL_DELETE_DIR
  • CBL_DELETE_FILE
  • I$IO
  • RENAME
  • W$BITMAP
  • W$KEYBUF
  • $WINHELP
  • WIN$PLAYSOUND
Parent topic: Configuration Variables


filename_VERSION

This configuration variable sets the Vision file format on a file-by-file basis. The filename is replaced by the base name of the file (the filename minus directory and extension). The meaning of the variable is the same as for V_VERSION. This variable is useful if you want to have all your Vision files in one format, with a few exceptions. For example, you might want to maintain most of your files in Vision Version 3 format to conserve file handles, but have a few files in Version 6 format to take advantage of the larger file size. Note that this variable only affects the file format when it is created. You can always rebuild the file in another format later.

This variable (and the V_VERSION configuration variable) is most helpful when you are using transaction management. The transaction system does not record the format of the created file if an OPEN OUTPUT is done during a transaction, because the transaction system is not tied to any particular file system. If you need to recover a transaction, the system will recreate the OPEN OUTPUT files using the settings of the VERSION variables.

The behavior of this variable is affected by the settings of the configuration variables V_STRIP_DOT_EXTENSION and V_BASENAME_TRANSLATION.

  • If V_STRIP_DOT_EXTENSION is set to 0 (off, false, no), Vision does not remove any dot extension when replacing the base name of the file. This can be useful if you have two files that share a common name before their dot extension.
  • If V_BASENAME_TRANSLATION is set to 0 (off, false, no), Vision includes the entire path of the file in the base name. This can be useful if you have files with the same names stored in different directories.
Parent topic: Configuration Variables


filesystem_DETACH

This configuration variable detaches any file system from the runtime. The syntax is:

     filesystem_DETACH n

where filesystem corresponds to the first five letters of the file system name and n is a non-zero value. Examples of file systems that may be detached using this feature are:

Btrieve | BTRIE_DETACH
C-ISAM | C_ISA_DETACH
Informix | INFOR_DETACH
SQL Server | MSSQL_DETACH
ODBC | ODBC_DETACH
Oracle | ORACL_DETACH
RMFM | RMFM_DETACH
RMS | RMS_DETACH
Sybase | SYBAS_DETACH
Vision | VISIO_DETACH

The file systems may be detached only when the runtime is started, not during execution. If you detach all file systems, the runtime will terminate with an error message. For example, if you detach Vision with VISIO_DETACH on a standard runtime, the runtime will terminate with this message to std err: No file system available.

This feature automatically supports new file systems added to the runtime.

Parent topic: Configuration Variables


FLUSH_ALL

This configuration variable can be used to control the flushing of file buffers to disk. It is one of several variables that control buffer flushing. See the other entries in this appendix that begin with FLUSH.

This variable can take a combination of the following values:

  • 1 (on, true, yes, all)
  • 0 (off, false, no)
  • MASS_UPDATE
  • REMOTE

When this variable is set to 1, files opened for MASS-UPDATE are flushed along with other files. This means that the local cache used to hold the MASS-UPDATE buffers is flushed whenever the operating system cache is flushed.

When this variable is set to the default value of 0, files opened for MASS-UPDATE are not flushed.

Setting this variable to MASS_UPDATE causes the runtime to flush local files, including files opened with MASS-UPDATE.

Setting this variable to REMOTE causes the runtime to flush local files not opened with MASSUPDATE, as well as remote files.

You can also set this variable to a combination of values. For example,

FLUSH_ALL  MASS_UPDATE  REMOTE

causes the runtime to flush all local files, including those opened with MASSUPDATE, as well as remote files.

Note on Bitmask Integer Values

Internally, the value of this configuration variable is converted to a bitmask, and its bitmask integer value is determined by the keywords used to set it. Keywords translate into integer values as follows:

  • FALSE, NO and OFF are equivalent to 0
  • MASS_UPDATE is equivalent to 1
  • REMOTE is equivalent to 2
  • ALL, TRUE, YES and ON are equivalent to –1

When the runtime is started with the -l and -e errfile arguments, only the integer value of FLUSH_ALL is recorded in the error file.

Parent topic: Configuration Variables


FLUSH_COUNT

This configuration variable allows you to flush the disk buffers after a certain number of file updates has occurred. For example, if you set this configuration variable to 10, then the buffers will be flushed after every ten updates to disk files. Only indexed files are counted. When the buffers are flushed, the exact action depends on the operating system:

Windows | Buffers are written to disk and the file's directory information is updated. This is roughly equivalent to the action that occurs when a file is closed.
UNIX | The sync system routine is called. This causes all of UNIX's cache to be written to disk. This operation is only scheduled--it occurs when the system finds time to do it. Because the system does this every 30 seconds anyway, probably the only reason to request a call to sync is if you have unreliable power.
VMS | VMS does not have a system cache, so this configuration variable has no effect.
Note: Setting this variable to a low non-zero value will improve the chances of recovering a file after a power failure, but will decrease performance. If FLUSH_COUNT is set to 0, then the system buffers are flushed only when a file is closed. The default setting is 0.
Parent topic: Configuration Variables


FLUSH_ON_ACCEPT

This configuration variable causes the system's buffers to be flushed whenever a Format 1 or Format 2 ACCEPT statement is executed. You turn on this configuration variable by setting its value to 1 (on, true, yes). The default setting is 0 (off, false, no). Note that this variable is not recommended for multi-user systems because of the performance penalty.

Parent topic: Configuration Variables


FLUSH_ON_CLOSE

This configuration variable applies only to Windows systems. When this variable is set to 1 (on, true, yes), the cache buffers will be flushed to disk when the file is closed. Versions prior to 4.3.1 flushed the cache buffers for safety reasons. This, however, reduced system performance, significantly in some programs. This feature is turned "off" by default.

Parent topic: Configuration Variables


FLUSH_ON_COMMIT

When this configuration variable is set to 0 (off, false, no), the COMMIT verb will not request the host operating system to flush all buffers to disk.

If flushing is prevented, COMMIT and UNLOCK ALL have the same effect. The default setting is "0" (off, false, no).

Parent topic: Configuration Variables


FLUSH_ON_OPEN

This variable causes the system's buffers to be flushed on the first WRITE, REWRITE, or DELETE that occurs after an indexed file is opened for I/O. The purpose of this is to update the user count field in the file's header to keep it accurate. When this configuration variable is set to 1 (on, true, yes), this feature is turned on; when set to 0 (off, false, no), it's turned off. The default setting is "0".

Parent topic: Configuration Variables


FONT

Use the FONT variable to apply your own characteristics to one or more of the standard fonts. The characteristics you can control are the font-face, the pitch and whether the text is emboldened. The font in effect is determined by the DEFAULT_FONT variable.

Use the following syntax to specify the characteristics:

FONT std-font-name font-face font-pitch [BOLD]
where std-font-name can be one of:
  • TRADITIONAL or TRADITIONAL-FONT
  • FIXED or FIXED-FONT
  • LARGE or LARGE-FONT
  • MEDIUM or MEDIUM-FONT
  • SMALL or SMALL-FONT

For example:

FONT TRADITIONAL COURIER 10 BOLD

sets the TRADITIONAL font (when in effect) to 10pt Courier, in bold.

Also, If FONT is set to 2, a std-font-name of TRADITIONAL is used. If any other numerical value is set, a std-font-name of FIXED is used.

This variable has meaning only on graphical systems such as Windows, and must be set in the configuration file before you execute the program. Altering the value of FONT from inside your program has no effect.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement, nor can be used to update characteristics for user-defined fonts created using W$FONT.
Parent topic: Configuration Variables
Related reference
COBOL_CHARACTER_SET


FONT_AUTO_ADJUST

This variable allows you to disable an automatic font adjustment that is applied on Windows machines. The runtime attempts to adjust automatically for differences in the relative proportions between small fonts and large fonts. You can inhibit the adjustment by setting this variable to 0 (off, false, no).

The adjustment is provided because the internal scaling of fonts under Windows changes between small and large fonts. Under small fonts, digits are slightly wider than the average character. Under large fonts, digits have the same width as the average character. ACUCOBOL-GT uses the size of the font's width for many calculations. Thus, the change in relative proportion within a single font can cause problems for screens designed for the small fonts. For example, a frame may not be big enough to hold its contents. To prevent this problem, the runtime ensures that the "standard font measure" is always a bit larger than the average character width in a font. To disable this adjustment, set this variable to 0.

Note: This variable computes the width of a printer font in the same way that the width of a screen font is computed. You can suppress this behavior by compiling with the -C43 option.
Parent topic: Configuration Variables


FONT_SIZE_ADJUST

This variable allows you to adjust the size of the standard font measurement that is computed for graphical controls (applies to variable-pitch fonts only). The value of FONT_SIZE_ADJUST is added directly to the computed standard font size. For example, a setting of 1 adds one pixel to the computed width of the font. Because the standard font measure is used to compute the width of nearly all controls, any adjustment made by this variable will have a significant impact on the layout of your screens.

The adjustment to the standard font measure is made after the wide font measure is computed (this is important to note because the wide font measure depends on the standard font measure; to change the wide font measure, use the FONT_WIDE_SIZE_ADJUST configuration variable).

After applying the adjustment, the runtime checks and ensures that the computed font measure is not less than one (1) or greater than the widest character in the font. If you find that the default size of most controls is slightly smaller than you prefer, you might try setting FONT_SIZE_ADJUST to a small value (typically 1).

Generally, it is recommended that FONT_SIZE_ADJUST (and FONT_WIDE_SIZE_ADJUST) be left at its default value of 0. You can also use negative values, but there is rarely a need to do so.

To optimize performance, the runtime computes the font sizes only occasionally. Although you can change the variable dynamically at runtime, the exact time when the new setting will take effect is difficult to predict. For this reason, we recommend that you either set it in your program prior to constructing your initial screen, or directly in the configuration file.

Note: This variable computes the width of a printer font in the same way that the width of a screen font is computed. You can suppress this behavior by compiling with the -C43 option.
Parent topic: Configuration Variables


FONT_WIDE_SIZE_ADJUST

This variable allows you to adjust the size of the wide font measurement (applies to variable-pitch fonts only). The wide font measure is normally used when the runtime is measuring small or upper-case entry fields. The value of FONT_WIDE_SIZE_ADJUST is added directly to the computed wide font size.

After applying the adjustment, the runtime checks and ensures that the computed wide font measure is not smaller than the (adjusted) standard font measure or larger than the widest character in the font. If your upper-case fields are not quite as wide as you prefer, try setting this variable to a small value (typically 1 or 2).

Generally, it is recommended that FONT_WIDE_SIZE_ADJUST (and FONT_SIZE_ADJUST) be left at its default value of 0. You can also use negative values, but there is rarely a need to do so.

Note: In order to improve performance, the runtime computes the font sizes only occasionally. Although you can change the variable dynamically at runtime, the exact time when the new setting will take effect is difficult to predict. For this reason, we recommend that you either set it in your program prior to constructing your initial screen, or directly in the configuration file.
Parent topic: Configuration Variables


FOREGROUND_INTENSITY

Use this variable to set the default foreground intensity.

0 | The runtime uses the default intensity for the output device. For Windows the default is low-intensity.
1 | The runtime uses low-intensity.
2 | The runtime uses high-intensity.

If your program specifies a default intensity, then the runtime will never assign high-intensity if the foreground is black. As with the background, we do this to prevent a washed-out appearance. There's one exception to this rule. The runtime will assign high-intensity to a black foreground if the output device does not support independent background intensities. In this case, the device will typically show the background in high-intensity and keep the foreground black. Note that if your program explicitly sets high-intensity, then that will be used regardless of the foreground color. The default value for this variable is 0.

Parent topic: Configuration Variables


FREEZE_AX_EVENTS configuration

This variable applies only in a thin client environment. During the processing of an ActiveX event, the Windows and thin client runtimes attempt to suspend subsequent ActiveX events until the first event has completed. By default, the thin client runtime also attempts to suspend ActiveX events whenever the application is not processing an ACCEPT statement. To suspend and resume events, the runtime calls the ActiveX function IOleControl::FreezeEvents().

You might want to disable calls to "FreezeEvents" for ActiveX controls that discard events while in a FreezeEvents state. For example, if a user double-clicks in an ActiveX control, the control might generate three events: mouse-down, mouse-up, and double-click. If the COBOL program terminates an ACCEPT statement in response to the mouse-down event, the runtime calls FreezeEvents(), and the ActiveX control might discard the mouse-up and double-click events.

You can disable the FreezeEvents() logic by setting the FREEZE_AX_EVENTS runtime configuration variable to 0 (off, false, no) in the configuration file or programmatically with the SET verb. The default value of FREEZE_AX_EVENTS is 1 (on, true, yes).

Note: The FreezeEvents() logic protects against unexpected nesting of ActiveX events and against event procedures running unexpectedly during a CREATE, DISPLAY, MODIFY, INQUIRE, or other operation that waits for results from the thin client. Turning this feature off can cause unexpected behavior.

For more information about ActiveX controls in a thin client environment, refer to the AcuConnect User's Guide.

Parent topic: Configuration Variables


FULL_BOXES

This variable applies only in text-mode environments. When FULL_BOXES is set to 1 (on, true, yes) a full, four-sided box is drawn around boxed entry fields. By default, to save screen space on character-based systems, only the left and right edges of a box are drawn around boxed entry fields. The default value of FULL_BOXES is 0 (off, false, no).

Note: This variable requires that the boxed entry field be defined as MULTILINE.
Parent topic: Configuration Variables


GRID_BUTTONS_CAUSE_GOTO

This variable applies to graphical programs that include one or more paged grid controls. When GRID_BUTTONS_CAUSE_GOTO is set to 1 (on, true, yes) and a user clicks a scroll button on the side of a paged grid, the runtime checks to see if the grid has focus. If the grid does not have focus, the runtime gives the grid the focus, generating any events that result normally from that focus change. This usually means that a CMD-GOTO event is sent to the COBOL program. The default value for this variable is 0 (off, false, no).

Parent topic: Configuration Variables


GRID_ENFORCE_DATATYPE

GRID_ENFORCE_DATATYPE when set to the value TRUE will cause a MODIFY statement to use valid characters for the datatype of the cell. The default value is FALSE, so that version 10.0 acts like version 9.2.1 and prior in this respect.

Parent topic: Configuration Variables


GRID_NO_CELL_DRAG

This variable applies to graphical programs that include grid controls and sets the NO-CELL-DRAG style as the default behavior for all grid controls, as opposed to specifying NO-CELL-DRAG style individually for each grid control. To configure the NO-CELL-DRAG style as the default setting, set the GRID_NO_CELL_DRAG configuration variable to 1 (on, true, yes). The default value is 0 (off, false, no) and will enable the user to drag a cell in a GRID control unless you specify a NO-CELL-DRAG style on that particular grid control.

Parent topic: Configuration Variables


GRID_SORT_INDICATOR

A graphical representation is now used to indicate the sort method in effect for a sortable grid column (either ascending or descending). This configuration variable determines the graphic that is used.

The possible values are TRIANGLE and ARROW. The default is TRIANGLE.

This variable can be dynamically queried and set.

Parent topic: Configuration Variables


GUI_CHARS

This variable configures a character-based host runtime to substitute some specific characters when it is performing textual emulation of graphical controls. If the GF-GUI-MAP terminal database entry doesn't exist or has the character 0 (zero) in a particular character's position, the runtime examines the GUI_CHARS variable to determine what character to display. GUI_CHARS is used only by character-based host runtimes.

The value of GUI_CHARS is a list of 14 space delimited characters strictly ordered to correspond with the following graphical elements (defaults are in parentheses):

1. | System menu button | (*)
2. | Title left corner | (+)
3. | Title right corner | (+)
4. | Title fill character | (=)
5. | Minimizer | (.)
6. | Maximizer | (^)
7. | Scroll bar up button | (^)
8. | Scroll bar down button | (v)
9. | Scroll bar left button | (<)
10. | Scroll bar right button | (>)
11. | Scroll bar page area | ( )
12. | Scroll bar slider | (#)
13. | Left entry field box | ([)
14. | Right entry field box | (])

The characters may be specified in ASCII or decimal form. To specify an ASCII value, precede the value with a space. For example, to use "-" in place of "=" for the title fill character, make the following entry in the runtime configuration file:

GUI_CHARS  0 0 0 - 0 0 0 0 0 0 0 0 0 0

or

GUI_CHARS  0 0 0 -

The presence of a 0 (zero) following a space, causes the default character to be used.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


HELP_PROGRAM

If the program uses help automation, this variable should be assigned the name of the help processor program. The help processor's entry point is always a COBOL program. The program can be the help processor itself, or a shell to some other help processor, such as Windows Help. The default value of HELP_PROGRAM is AcuHelp.

Parent topic: Configuration Variables


HINTS_OFF

Controls how long the pop-up hint is displayed before being erased. The default value is 400 (four seconds). If you set this value to 0, the hint will remain displayed until some other event (such as using the button or typing) causes it to disappear. See Pop-up Hints in ACUCOBOL-GT User Interface Programming for a description of pop-up hints. Set this variable to the number of hundredths of seconds to display the hint.

Parent topic: Configuration Variables


HINTS_ON

Controls how long the mouse must remain stationary over a bitmap button before displaying its pop-up hint. For a description of pop-up hints, see Pop-up Hints in ACUCOBOL-GT User Interface Programming. Set this variable to the number of hundredths of a second that the mouse must be stationary. The default value is 75 (three-quarters of a second). If you set this variable to 0, pop-up hints will not be displayed. Setting this variable to 1 or 2 is not recommended because it may result in the pop-up hint being displayed while the mouse is moving across the button face (because the mouse motion events may occur less than 0.02 seconds apart).

Parent topic: Configuration Variables


HOT_KEY

ACUCOBOL-GT offers two methods for assigning hot keys--the HOT_KEY variable, and the KEYSTROKE hot-key format. See The KEYSTROKE Variable in the ACUCOBOL-GT User's Guidefor more information.

Using the HOT_KEY variable described below, you can easily assign a whole range of keys to a single hot-key program and determine which key activated the program. This lets you write a single program that handles an entire menu. Each menu item can act as a hot key to call this program.

This HOT_KEY format differs from the KEYSTROKE hot-key described in the User's Guide in three ways:

  • You assign a hot key by referencing its exception value instead of referencing its key code. Thus, if you assign the same exception value to several individual keys, you can associate these keys with the same hot-key program by making one COBOL configuration file entry.

    Similarly, menu items and individual keys can be assigned the same exception value, and then associated with the same hot-key program in a single configuration file entry.

  • You may assign a range of exception values to activate the same program. You could use this to write a menu handler by assigning all of your menu items to a unique range and then assigning that range to a single hot-key program.
  • A hot-key program activated using the HOT_KEY format is passed an additional parameter. This third parameter contains the value of the exception key that activated the program. This is passed as a COMP-1 data item.

Use this variable to associate an exception value, or range of values, with a program. HOT_KEY has the following format:

HOT_KEY  program = value1 [, value2]

where program is the name of the program to run, value1 is the lower (or only) exception value that activates the program, and value2 is the upper value of the activation range. Value2 may be omitted; if it's used it must include the separating comma. You must place program in single or double quotes if you require a lower-case program name.

For example, to assign a program called "mymenu" to exception values 100 through 200, use the following entry:

HOT_KEY  "mymenu" = 100, 200

A special exception value named TIMEOUT may be specified as the first exception value. When this value is used as the first exception value for a HOT_KEY program, the runtime will execute the named program whenever an ACCEPT BEFORE TIME times out. When that occurs, the second exception value is ignored.

Multiple HOT_KEY entries may reference the same program. This allows you to specify noncontiguous activation ranges. (Be aware that no more than 16 hot-key entries can be included in the COBOL configuration file. Using a contiguous range of exception values assigns many keys while counting as only one entry towards the limit.)

If you specify a value1 value of 0, then all hot-key references to program are removed. Within a given run unit, this is the only way to remove the assignment of an exception value to a hot-key program after it has been assigned. You will probably use SET ENVIRONMENT in your source code to do this.

If you assign multiple hot-key programs to the same exception value, the results are undefined.

You may assign different hot keys using both the HOT_KEY variable, described here, and the KEYSTROKE hot-key format. The results are undefined if you assign the same key using both formats. The total number of hot-key entries defined by both methods cannot exceed 16. See The KEYSTROKE Variable in the ACUCOBOL-GT User's Guide for more information.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


HP_TERMINAL_ATTRIBUTE_HANDLING

When set to 1 (on, true, yes), if the previous character was written to a line other than the current one this variable causes the runtime to set the attribute for the character to be written even if the attribute has not changed. When set to 0 (off, false, no), this variable causes the runtime to behave as it always has. For example, if the terminal attribute has not changed then it will not be set again. The default setting is 0 (off, false, no).

Parent topic: Configuration Variables


HTML_TEMPLATE_PREFIX

This variable is used to specify a series of directories for locating HTML template files. This variable is similar to FILE_PREFIX and CODE_PREFIX. It specifies a series of one or more directories to be searched for the desired HTML template file. The directories are specified as a sequence of space-delimited prefixes to be applied to the file name. All directories in the sequence must be valid names. The current directory can be indicated by a period (regardless of the host operating system). This is the default.

Note: Remote name notation is not allowed for the HTML_TEMPLATE_PREFIX variable, even if your runtime is client-enabled.
Parent topic: Configuration Variables


ICOBOL_FILE_SEMANTICS

This variable affects the behavior of indexed and relative files when reversing direction after reading past the beginning or end of a file. Normally, if you perform a series of READ NEXTs that reach to the end of the file (returning file status 10), a subsequent READ PREVIOUS will return the last record in the file. The file pointer's position after each READ NEXT is just past the end of the last record. Similarly, reading past the beginning of the file and then doing a READ NEXT will return the first record in the file.

Under ICOBOL, these conditions produce different results. The record returned by the READ PREVIOUS is the second-to-last record in the file, and the record returned by the READ NEXT is the second record in the file. Essentially, when a series of READs passes either end of the file, the record pointer remains on the first or last record.

Setting ICOBOL_FILE_SEMANTICS to 1 (on, true, yes) will cause the runtime to emulate ICOBOL's handling. This is useful when porting ICOBOL programs to ACUCOBOL-GT. This option is effective only in programs that have been compiled for ACUCOBOL-85 2.0, or later. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


ICON

This variable has meaning only on graphical systems such as Windows. Use this variable to designate a program's minimized icon. (By default, it uses the non-debugger icon provided with ACUCOBOL-GT.) Set ICON to the name of the file that contains the icon. This file should be an .ICO file that contains a 16-color icon. (Although the file may contain icons in other formats, the runtime accesses only the 16-color icon.) The icon should be created using an icon editor like the one in the Windows Software Development Kit.

For example, if your custom icon were contained in the file PAYROLL.ICO in the directory \ACCT\ICONS, you would add the following line to your COBOL configuration file:

ICON  \ACCT\ICONS\PAYROLL.ICO

The maximum icon size that can be used with the ICON variable is 32 x 32 bits. The runtime uses the first icon it finds in the icon file that fits its maximum. If that icon is larger than the maximum, a memory access violation may occur.

Note: The ICON configuration variable determines the icon used only when your application is minimized. It does not determine the icon displayed by the Program Manager.
Parent topic: Configuration Variables


IMPORT_USES_CELL_SIZE

This variable is used when importing graphical screens into the AcuBench Screen Designer using the screen import utility. IMPORT_USES_CELL_SIZE allows you to choose whether fields are measured using the actual cell size of the imported screen or measured in 10-pixel by 10-pixel cells. The runtime checks this variable only if you are importing screens. When IMPORT_USES_CELL_SIZE is set to the default value of 1 (on, true, yes), the screen import utility captures the actual cell size used to create windows. If this variable is set to "0" (off, false, no), the screen import utility outputs information based on 10-pixel by 10-pixel cells. Note that there is no need to set this variable when importing character screens, which should always import with a cell size of 10-pixel by 10-pixel cells. See the AcuBench documentation for more information on importing screens.

Parent topic: Configuration Variables


INACTIVE_BORDER_COLOR

This variable is used on character-based hosts to specify the color and video attributes of the characters that form the border (box) around an inactive floating window. INACTIVE_BORDER_COLOR can be set to a variety of numeric values that express combinations of color and video attributes. See Common Screen Options in the ACUCOBOL-GT Reference Manual for more information.

If INACTIVE_BORDER_COLOR is set to "0", the inactive window's border is drawn with the colors and video attributes specified in the COBOL program when the window is first created. The default value is 0.

Parent topic: Configuration Variables


INCLUDE_PGM_INFO

This variable causes additional program information to be added to the string passed to COBOL error procedures.

When INCLUDE_PGM_INFO is set to 1 (on, true, yes) the string passed to COBOL error procedures is prepended with the current program name and the address of the program failure. The address may not be exactly the same as that in the COBOL listing, but it will be very close. (The given address is the actual current program counter, which is typically slightly advanced from the line on which the fault occurred.) When INCLUDE_PGM_INFO is set to the default, 0 (off, false, no), the string contains only the text of the intermediate error message.

For more about COBOL error procedures, see the entry for the CBL_ERROR_PROC in Appendix I.

Parent topic: Configuration Variables


INPUT_STATUS_DEFAULT

The value of this variable is returned when an ACCEPT FROM INPUT STATUS statement is executed on a machine that cannot determine the input status of the terminal. This can be used to make a running program behave correctly on a new machine. The value must be a single digit. The default value is 0.

If the input is redirected (not attached to a terminal), the SCRIPT_STATUS configuration variable determines whether ACCEPT FROM INPUT STATUS returns the value of INPUT_STATUS_DEFAULT or returns the actual status of the input file.

Parent topic: Configuration Variables


INSERT_MODE

This variable determines whether or not keystrokes are inserted in front of any existing text when the user types an entry. Set this variable to 1 (on, true, yes) to enable insertion. The default value is 0 (off, false, no), which causes typing to replace existing text.

The user can change the state of INSERT_MODE with various key actions. For example, pressing <insert> can enable insertion. This variable has no affect on Windows controls.

Parent topic: Configuration Variables


INTENSITY_FLAGS

This variable takes effect only if you use COLOR_TRANS and only if it changes your color scheme. After any color transformation is completed, the runtime system then transforms the foreground and background intensities according to the setting of INTENSITY_FLAGS. The value for this variable is actually the sum of the values you choose from the list below. The default value is 0.

Set INTENSITY_FLAGS to a combination of the following options by adding their values together:

1 | Exchanges the foreground and background intensities for each other. This is useful if you are swapping a black background into the foreground and want to assign the foreground's intensity to the background.
2 | Causes the foreground intensity to be inverted. That is, if the foreground is high-intensity, it becomes low-intensity. Otherwise, it becomes high-intensity. This is useful if you are transforming the background to white and the foreground to black. Setting this will cause your low-intensity foreground to be shown as gray while your high-intensity item will show as black.
4 | Forces the foreground to high-intensity. This will not be applied to a black foreground.
8 | Forces the foreground to low-intensity. This may not be used if 4 is used.
16 | Causes the 4 or 8 setting to be used even if the COLOR_TRANS setting had no effect. This is an override switch that you can use to cause all foreground intensities to be set to high or low.
32 | Forces the background to high-intensity. This will not be applied to a black background.
64 | Forces the background to low-intensity. This may not be used if 32 is used.
128 | Forces the background to high-intensity, but only if it is black. This may be used in conjunction with setting 32 or 64 for special effects.
256 | Causes the 32, 64, or 128 setting to be used even if the COLOR_TRANS setting had no effect.

These transformations are performed in the order listed above. After this variable is applied, the COLOR_TABLE setting is applied to the program.

Parent topic: Configuration Variables


IO_CREATES

Setting this configuration variable to a 1 (on, true, yes) causes the runtime system to create a relative or indexed file when the program attempts to open a nonexistent file for I-O. This is provided for compatibility with some other COBOL systems. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


IO_FLUSH_COUNT

Use this variable to specify how often the runtime should flush pending screen output during file operations. When set to a positive value, the variable indicates the number of file operations to perform between each screen flush. By default, IO_FLUSH_COUNT is set to 20.

For optimal performance, set IO_FLUSH_COUNT to zero (0). When IO_FLUSH_COUNT is set to zero, COBOL file verbs will not automatically flush pending screen output.

To reduce unexpected screen behavior, however, leave this variable at its default setting. The overhead at the default setting is small.

Parent topic: Configuration Variables


IO_READ_LOCK_TEST

When this variable is set to 1 (on, true, yes), the runtime will cause a read with no lock to fail if the file is opened for I-O and the record is locked. This setting will work with Vision files only. The setting is provided for compatibility with some other COBOL systems. The default value is 0 (off, false, no). The default behavior is to allow the read to succeed.

Parent topic: Configuration Variables


IO_SWITCH_PERIOD

The value of this variable affects the frequency with which the program's threads change control based on file IO activity. After a thread performs the value of IO_SWITCH_PERIOD operations, the runtime switches control to another thread (if one exists). Note that because thread switching is also affected by other program operations (such as display I/O), it is impossible to predict or absolutely control when a thread will change control.

The default value of IO_SWITCH_PERIOD is 10. This value will provide good results with most applications. To produce behavior that more closely imitates that of Versions 6.1 and earlier, set IO_SWITCH_PERIOD to 1. Zero and negative values are invalid and will result in undefined behavior.

Parent topic: Configuration Variables


ISOLATE_FILE_CREATES

It is possible to experience unexpected file errors when trying to create a file if another process is simultaneously creating or removing the same file name. Setting ISOLATE_FILE_CREATES to 1 (on, true, yes) causes files to be created with temporary names and then renamed when they are fully formed. This prevents another process from interfering with the creation. This option is effective only with Vision, and has undefined effects when used with other file systems. We recommend that you use this option only if you are experiencing unexpected errors when trying to create a file.

Parent topic: Configuration Variables


JAVA_LIBRARY_NAME

This variable is designed for those calling a Java program from COBOL via the C$JAVA library routine. In this variable, specify the name of the DLL that exports the Java Native Interface (JNI) API for loading the JVM. In the case of JRE 1.4.2_04, the file is called jvm.dll or libjvm.so. If the path to the DLL is in the Path environment variable, the filename is sufficient here; otherwise, this name should be fully qualified with the path. See C$JAVA for more information.

See Calling the C$JAVA Routine for information on calling Java from COBOL using C$JAVA.

Parent topic: Configuration Variables


JAVA_OPTIONS

This variable is designed for those calling a Java program from COBOL via the C$JAVA library routine. In this variable, specify the command-line options that you want passed to the JVM when it is started.

Note that both CLASSPATH (java.class.path system property) and the java.library.path must be configured in order for C$JAVA to locate the Java class to run. The CLASSPATH is the location of .jar or .class files. The java.library.path is the location DLLs or shared objects that are required either by the runtime or by the Java Virtual Machine (JVM).

If these properties are not set in the environment, use JAVA_OPTIONS to set CLASSPATH and java.library.path. For example:

JAVA_OPTIONS="-Djava.library.path="c:\usr\lib" -Xms128m -Xmx128m -classpath /java/MyClasses/myclasses.jar"
Parent topic: Configuration Variables


JUSTIFY_NUM_FIELDS

When this variable is set to 1 (on, true, yes), all entry fields that have a numeric or numeric-edited VALUE data item associated with them are right justified (the same as if the RIGHT style were specified). You can inhibit this for a given field by specifying the LEFT style for the entry field. Note that this variable is examined only when each entry field is created and has no further effect. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


KBD

These variables can be used in conjunction with the KEYBOARD variable to set global terminal attributes. See The KEYBOARD Variable for more information.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


KEISEN_CLEAR_MODE

This configuration variable applies to Japanese only. Set this variable to TRUE (ON, YES, 1) to allow the run time to clear KEISEN characters from the screen when doing other types of erase.

Parent topic: Configuration Variables


KEY_MAP

This is an obsolete variable that has been replaced by the KEYSTROKE configuration variable. Its setting is ignored.

Parent topic: Configuration Variables


KEYBOARD

This variable sets global terminal attributes. See The KEYBOARD Variable for more information.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


KEYSTROKE

This variable redefines the action of a particular keystroke. It can also control mouse handling. See Redefining the Keyboard in the ACUCOBOL-GT User Guide for details on redefining keystrokes. See Using the Mouse in the User Interface Programming Guide. for information on mouse handling.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


LARGE_FILE_LIMIT_1TB

This variable is only effective on UNIX systems; otherwise it has no effect.

This configuration variable limits the file access locks that Vision places at the end of the file address space to be placed within the 1TB boundary. This is necessary on some systems (for example, HP-UX systems) that do not support full 64-bit file addressing on some file system types. Trying to use file offsets outside of the 1TB boundary will generate I/O errors, even though the large file access API is available. Therefore, for HP-UX ports, the default value of this variable is 1 (ON, true, yes).

To allow file access locks for larger files, set the variable's value to 0 (OFF).

If both this configuration variable and the LARGE_FILE_LIMIT_2TB configuration variable are set, this variable takes precedence.

Parent topic: Configuration Variables
Related reference
LARGE_FILE_LIMIT_2TB


LARGE_FILE_LIMIT_2TB

This variable is only effective on UNIX systems; otherwise it has no effect.

This configuration variable limits the file access locks that Vision places at the end of the file address space to be placed within the 1TB boundary. This is necessary on some systems such as HP-UX that do not support full 64-bit file addressing on some file system types. Trying to use file offsets larger than that generate I/O errors even though the large file access API is available. Therefore, for HP-UX ports, the default value of this variable is 1 (ON, true, yes).

To allow file access locks for larger files, set the variable's value to 0 (OFF).

If both this configuration variable and the LARGE_FILE_LIMIT_1TB configuration variable are set, the LARGE_FILE_LIMIT_1TB variable takes precedence.

Parent topic: Configuration Variables
Related reference
LARGE_FILE_LIMIT_1TB


LC_ALL

This variable supports the transfer of double-byte character variables and string literals and has meaning only on 32-bit Windows systems that support double-byte characters (e.g., Asian Windows machines). It should not be set in other environments and is needed only if you are passing data to a COBOL program from another language, such as Visual Basic, and are using C$GETVARIANT or C$SETVARIANT. By using the LC_ALL configuration variable, you cause the runtime to set the locale to a particular value. You do not need to set this variable on Japanese machines. The runtime automatically detects Japanese versions of Windows and automatically sets the locale, LC_ALL, to Japanese_Japan.932.

The default value for this variable is C. The C locale assumes that all characters are 1 byte and that their value is always less than 256. The value of LC_ALL is in the format:

language[_country[.code_page]]

or

.code_page

where language is one of the supported language strings, country is one of the supported country or region strings, and code_page is the Windows code page setting for the language and country. country and code_page are optional. For example, the following are all equivalent:

LC_ALL Japanese
LC_ALL Japanese_Japan
LC_ALL Japanese_Japan.932
LC_ALL .932

For Korean double-byte character support under Windows use:

LC_ALL Korean

For Chinese use:

LC_ALL Chinese

or

LC_ALL Chinese-simplified

or

LC_ALL Chinese-traditional

The following are the supported language strings:

Chinese | Chinese | "chinese"
Chinese | Chinese (simplified) | "chinese-simplified" or "chs"
Chinese | Chinese (traditional) | "chinese-traditional" or "cht"
Czech | Czech | "csy" or "czech"
Danish | Danish | "dan" or "danish"
Dutch | Dutch (Belgian) | "belgian", "dutch-belgian", or "nlb"
Dutch | Dutch (default) | "dutch" or "nld"
English | English (Australian) | "australian", "ena", or "english-aus"
English | English (Canadian) | "canadian", "enc", or "english-can"
English | English (default) | "english"
English | English (placecountry-regionNew Zealand) | "english-nz" or "enz"
English | English (placecountry-regionUK) | "eng", "english-uk", or "placecountry-regionuk"
English | English (placecountry-regionUSA) | "american", "american english", "american-english", "english-american", "english-us", "english-usa", "enu", "us", or "placecountry-regionusa"
Finnish | Finnish | "fin" or "finnish"
French | French (Belgian) | "frb" or "french-belgian"
French | French (Canadian) | "frc" or "french-canadian"
French | French (default) | "fra" or "french"
French | French (Swiss) | "french-swiss" or "frs"
German | German (Austrian) | "dea" or "german-austrian"
German | German (default) | "deu" or "german"
German | German (Swiss) | "des", "german-swiss", or "swiss"
Greek | Greek | "ell" or "greek"
Hungarian | Hungarian | "hun" or "hungarian"
Icelandic | Icelandic | "icelandic" or "isl"
Italian | Italian (default) | "ita" or "italian"
Italian | Italian (Swiss) | "italian-swiss" or "its"
Japanese | Japanese | "japanese" or "jpn"
Korean | Korean | "kor" or "korean"
Norwegian | Norwegian (Bokmal) | "nor" or "norwegian-bokmal"
Norwegian | Norwegian (default) | "norwegian"
Norwegian | Norwegian (Nynorsk) | "non" or "norwegian-nynorsk"
Polish | Polish | "plk" or "polish"
Portuguese | Portuguese (Brazilian) | "portuguese-brazilian" or "ptb"
Portuguese | Portuguese (default) | "portuguese" or "ptg"
Russian | Russian (default) | "rus" or "russian"
Slovak | Slovak | "sky" or "slovak"
Spanish | Spanish (default) | "esp" or "spanish"
Spanish | Spanish (Mexican) | "esm" or "spanish-mexican"
Spanish | Spanish (Modern) | "esn" or "spanish-modern"
Swedish | Swedish | "sve" or "swedish"
Turkish | Turkish | "trk" or "turkish"

The following are the supported country/region strings:

placecountry-regionAustralia | "aus" or "placecountry-regionaustralia"
placecountry-regionAustria | "placecountry-regionaustria" or "aut"
placecountry-regionBelgium | "bel" or "placecountry-regionbelgium"
placecountry-regionBrazil | "bra" or "placecountry-regionbrazil"
placecountry-regionCanada | "can" or "placecountry-regioncanada"
placePlaceNameCzech PlaceTypeRepublic | "cze" or "czech"
placecountry-regionDenmark | "placecountry-regiondenmark" or "dnk"
placecountry-regionFinland | "fin" or "placecountry-regionfinland"
placecountry-regionFrance | "fra" or "france"
placecountry-regionGermany | "deu" or "placecountry-regiongermany"
placecountry-regionGreece | "grc" or "placecountry-regiongreece"
placeHong Kong | "hkg", "hong kong", or "hong-kong"
placecountry-regionHungary | "hun" or "placecountry-regionhungary"
placecountry-regionIceland | "placecountry-regioniceland" or "isl"
placecountry-regionIreland | "placecountry-regionireland" or "irl"
placecountry-regionItaly | "ita" or "placecountry-regionitaly"
placecountry-regionJapan | "japan" or "jpn"
placecountry-regionMexico | "mex" or "placecountry-regionmexico"
placecountry-regionNetherlands | "nld", "holland", or "placecountry-regionnetherlands"
placecountry-regionNew Zealand | "placecountry-regionnew zealand", "new-zealand", "nz", or "nzl"
placecountry-regionNorway | "nor" or "placecountry-regionnorway"
PlaceNamePeoples PlaceTypeRepublic of placecountry-regionChina | "china", "chn", "pr china", or "pr-china"
placecountry-regionPoland | "pol" or "placecountry-regionpoland"
placecountry-regionPortugal | "prt" or "placecountry-regionportugal"
placecountry-regionRussia | "rus" or "placecountry-regionrussia"
placecountry-regionSingapore | "sgp" or "placecountry-regionsingapore"
placePlaceNameSlovak PlaceTypeRepublic | "svk" or "slovak"
placecountry-regionSouth Korea | "kor", "country-regionkorea", "placecountry-regionsouth korea", or "south-korea"
placecountry-regionSpain | "esp" or "placecountry-regionspain"
placecountry-regionSweden | "swe" or "placecountry-regionsweden"
placecountry-regionSwitzerland | "che" or "placecountry-regionswitzerland"
placecountry-regionTaiwan | "placecountry-regiontaiwan" or "twn"
placecountry-regionTurkey | "tur" or "turkey"
placecountry-regionUnited Kingdom | "britain", "england", "gbr", "great britain","uk", "united kingdom", or "united-kingdom"
placecountry-regionUnited States of America | "country-regionamerica", "country-regionunited states", "united-states", "us", or "placecountry-regionusa"
Parent topic: Configuration Variables


LICENSE_ERROR_MESSAGE_BOX

This configuration variable prevents acushare licensing errors from appearing in a message box, which requires a response from the user. The error messages will instead go to the error output (stderr, or an error file if one is specified). Set LICENSE_ERROR_MESSAGE_BOX to 0 to prevent these messages from appearing in a message box. The default value is 1, which allows these messages to appear in a message box.

Parent topic: Configuration Variables


LINE_OUTPUT

Use this configuration variable with character-based run-times. Set this configuration variable to TRUE (ON, YES, 1) to cause screen output files (-o argument) to be line-based files.

Parent topic: Configuration Variables


LISTS_UNBOXED

Meaningful only in character-based environments, this variable indicates whether list boxes should be boxed (set to a value of 0, off, false or no) or unboxed (set to a value of 1, on, true or yes). The default setting is 0.

Parent topic: Configuration Variables


LITERAL_ENTRY

This variable can be used to loosen the literal match restrictions of ENTRY point name matching logic. By default, the matching logic is case sensitive and distinguishes between hyphens and underscores. Setting LITERAL_ENTRY to "0" (off, false, no) causes the runtime to handle ENTRY point name matching with case insensitivity (upper and lower case equivalent) and to treat hyphens and underscores ("-", "_") as equivalent. The default value is "1" (on, true, yes).

Parent topic: Configuration Variables


LOCK_DIR

When set, this controls automatic device locking on UNIX systems. This is described in Device Locking Under UNIX of the ACUCOBOL-GT User's Guide. The default value is empty.

Parent topic: Configuration Variables


LOCK_OUTPUT

When set to a 1 (on, true, yes), this configuration variable causes all files open for OUTPUT to be locked for exclusive use. Setting this can dramatically improve performance on VMS machines. Some other COBOL systems lock files that are open for OUTPUT. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


LOCK_SORT

When this configuration variable is set to a 1 (on, true, yes), input files to the SORT verb are opened for INPUT ALLOWING READERS. This can improve the performance of the SORT verb slightly and also ensure that the data being sorted is not modified. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


LOCKING_RETRIES

This configuration variable is designed for Windows 98 systems. It gives you some control over situations where a user must wait for access to a shared file. The runtime will try repeatedly to acquire the file lock, up to 400 times by default. Set this variable to the number of attempts you would like the runtime to make to acquire the file lock.

Parent topic: Configuration Variables


LOCKS_PER_FILE

This value determines the maximum number of record locks that can be held on a file by a single process. This value affects only the files that are maintaining multiple record locks. The default setting is 10. The maximum value is 32767 for Vision files. Setting this variable to its maximum value can waste resources and is not recommended.

If you increase the value of LOCKS_PER_FILE, you may wish to increase the value of MAX_LOCKS as well.

Parent topic: Configuration Variables


LOG_BUFFER_SIZE

This sets the maximum buffer size, in bytes, for the transaction log file. Acceptable values are from 0 to 32767. LOG_BUFFER_SIZE is examined before each write to the log file. Its default value is 512. If LOG_BUFFER_SIZE is set to 0, then writes to the log file are synchronous (unbuffered). This value can also be set inside a COBOL program with the SET ENVIRONMENT verb.

Parent topic: Configuration Variables
Parent topic: Configuration Variables


LOG_DEVICE

Setting this value to 1 (on, true, yes) causes the transaction management system to assume that the log file is actually a device, rather than a file. This means that a special device locking method will be used on the log file. It also guarantees that the log file will be opened "append" and that no seeks will be performed on it. This allows for the use of a tape device for the log file on many systems. The default setting is 0 (off, false, no). See Device Locking Under UNIX for more information.

Parent topic: Configuration Variables
Parent topic: Configuration Variables


LOG_DIR

This variable allows you to specify a directory to be used for holding the temporary files generated by the transaction management system. The value of LOG_DIR is treated as a prefix, much like FILE_PREFIX. If no directory is specified, temporary files are placed in the current directory.

Note: In general, you should not use remote name notation in the LOG_DIR variable. Although remote name notation is allowed for the LOG_DIR variable, it is not advisable to place temporary files on a remote server.
Parent topic: Configuration Variables


LOG_ENCRYPTION

If this value is set to 1 (on, true, yes), record images are encrypted before they are written to the transaction log file. The default setting is 0 (off, false, no).

Parent topic: Configuration Variables
Parent topic: Configuration Variables


LOG_EXCLUDE_PATTERN

Use this variable to exclude certain files from being logged in the transaction log file.

If you want to exclude multiple patterns, specify each pattern on a separate line. The following example excludes all transactions from files within the temp directory from being logged in the transaction log file:

LOG_EXCLUDE_PATTERN /temp/*
Note: You can exclude files based on a glob pattern: use ? (single character) and * (any number of characters).

To reset the patterns in effect (i.e. remove them), use the SET verb within a COBOL program to set the variable to SPACES.

The LOG_EXCLUDE_PATTERN and LOG_INCLUDE_PATTERN variables are mutually exclusive. LOG_INCLUDE_PATTERN only has an effect when no exclude patterns are specified. By default, none of these variables are set, and all transactions for all files are recorded in the log file.

Parent topic: Configuration Variables
Related reference
LOG_INCLUDE_PATTERN


LOG_FILE

This identifies the name of the default log file for transaction management. The default log file is opened at the beginning of the first transaction unless NO_LOG_FILE_OK is set to 1. If it does not exist, it is created. This variable can be set programmatically with the SET ENVIRONMENT verb. The default setting is empty. Unless you have set NO_LOG_FILE_OK to 1, you must set the LOG_FILE variable if you want to use transaction management.

Parent topic: Configuration Variables
Parent topic: Configuration Variables


LOG_INCLUDE_PATTERN

Use this variable to only include certain files being logged in the transaction log file.

If you want to include multiple patterns, specify each pattern on a separate line. The following example only records transactions for the two specified files within the log file:
LOG_INCLUDE_PATTERN /usr/dats/accounts.dat
LOG_INCLUDE_PATTERN /usr/dats/staff.dat
Note: You can also include files based on a glob pattern: use ? (single character) and * (any number of characters).

To reset the patterns in effect (i.e. remove them), use the SET verb within a COBOL program to set the variable to SPACES.

The LOG_EXCLUDE_PATTERN and LOG_INCLUDE_PATTERN variables are mutually exclusive. LOG_INCLUDE_PATTERN only has an effect when no exclude patterns are specified. By default, none of these variables are set, and all transactions for all files are recorded in the log file.

Parent topic: Configuration Variables
Related reference
LOG_EXCLUDE_PATTERN


LOG_RECOVER_REPORT

Use this variable to specify a file in which the actions of the transaction recovery process, run using C$RECOVER, are written.

The value of this variable can contain a number of special parameters:

  • If the file name starts with a plus sign ("+"), the report is appended to the specified file. By default, a new report overwrites the specified file.
  • If the name contains the string %p, when the report is generated that string is replaced with the process ID (PID) of the runtime from which the report originates.
  • If the name contains the string %d, that string is replaced with the current date in the form YYYYMMDD where YYYY is the year, MM month and DD day.
  • If the name contains the string %t, that string is replaced with the current time in the form HHMMSSTTT where HH is the hour, MM minute, SS second and TTT milliseconds.
  • If the name contains the string %u, that string is replaced with the username.
  • If the name contains the string %h, that string is replaced with the hostname.

For example, the following value creates a recovery report in the current directory, appending the process ID to the file name:

LOG_RECOVER_REPORT recover-%p.txt
Note: If C$RECOVER is called multiple times from the same COBOL program, subsequent calls will append (not overwrite) details to the file, unless the program uses the SET ENVIRONMENT verb to change the value of LOG_RECOVER_REPORT.
Parent topic: Configuration Variables


LOGGING

Setting this variable to 0 (off, false, no) disables the logging of file updates to the log file. This means that the data file recovery process (using the library routine C$RECOVER) is impossible. However, because rollback information is maintained internally by the runtime, the program can still use the transaction management system to START, COMMIT, and ROLLBACK transactions. This variable can be set programmatically with the SET ENVIRONMENT verb. The default setting is 1 (on, true, yes).

Parent topic: Configuration Variables
Parent topic: Configuration Variables


LOGICAL_CANCELS

This variable is used to enable logical cancels. Logical cancels reduce CALL overhead and can, as a result, improve performance. Cancels, both logical and physical (the default), are initiated by the CANCEL verb or through a function of the C interface. See Memory Management for more information on memory management and physical and logical cancels. See CANCEL Statement for more information on CANCEL.

LOGICAL_CANCELS can be set to the following values:

-1 | (default) all cancels are physical cancels except for programs called from CICS that have the Resident attribute set to TRUE.
0 | all cancels are physical cancels. Cancels of programs called with the C interface are treated as physical cancels even if the "cache" field is set to 1.
1 | all cancels are logical cancels. Cancels of programs called with the C interface are treated as logical cancels even if the cache field is set to 0.

LOGICAL_CANCELS is used in conjunction with the DYNAMIC_MEMORY_LIMIT configuration variable, which specifies the size of the dynamic memory pool for programs. See its entry in this appendix.

Parent topic: Configuration Variables


MAKE_ZERO

When set to a 1 (on, true, yes), this configuration variable causes a numeric data item that contains non-numeric data to be treated as zero when that item is used in a numeric statement. Setting the value to 0 (off, false, no) causes the item to be treated as is with whatever effects that will have. The default value is 1 (on, true, yes).

Parent topic: Configuration Variables


MASS_UPDATE

When set to 1 (on, true, yes), this variable causes all OPEN...WITH LOCK statements to be treated as if they were written OPEN...WITH MASS_UPDATE. This does not apply to OPEN INPUT, however. Setting this configuration variable will improve file performance for applications that lock files, but may lead to file corruption if the program is killed before it completes. The default value is 0 (off, false, no). See Indexed File Considerations for more information.

Parent topic: Configuration Variables


MAX_ERROR_AND_EXIT_PROCS

This variable sets the maximum number of error and exit procedures that a program can install or call. The default is 64. If the limit is exceeded, program execution is aborted. For more information about error and exit procedures, see DISPLAY_REG_, CBL_ERROR_PROC, CBL_EXIT_PROC, and CBL_GET_EXIT_INFO in ACUCOBOL-GT Appendices.

Parent topic: Configuration Variables


MAX_ERROR_LINES

This variable sets the maximum number of lines that can be included in the error file. It's especially useful when you are using the file trace function of the debugger. When the size of the error file reaches the number of lines specified in this variable, the error file is rewound to its beginning, and subsequent lines of output overwrite existing lines in the file. For example, if you set the maximum to 300, then lines 301 and 302 would overwrite lines 1 and 2 in the file. Note that there is an upper limit of 32767, setting a larger number causes odd behavior. The default value is 0, which means do not limit the size of the file.

When using the -l run-time option (which causes the configuration settings to be logged in the trace file) the trace file wraps to the line below the MAX_ERROR_LINES entry. For this reason, MAX_ERROR_LINES should be the last entry in the run-time configuration file

To help you locate the end of the file, an *** End of log *** message outputs whenever the run time shuts down. Line numbers are included in each line of the file, in columns one through seven.

This variable is not available on VMS systems.

Parent topic: Configuration Variables


MAX_FILES

This variable sets the maximum number of files that can be opened by the runtime system. The default value is 32. Keeping this value small conserves memory. Many operating systems limit the number of files that can be opened by a single process, so you may have to make some adjustments there too. The maximum value of MAX_FILES is 32767. The new higher limit of MAX_FILES is only available for objects compiled to version 6.2 or later. If MAX_FILES > 255 is used, all objects in use must be compiled to object version 6.2 or later. Failing to do this may lead to undefined behavior.

Parent topic: Configuration Variables
Parent topic: Configuration Variables


MAX_LOCKS

This value sets the maximum number of record locks that can be held by the runtime system for all of the files together. The default value matches the setting of MAX_FILES. Many operating systems also have limits on the number of record locks that can be held, so you may have to make adjustments there too. The maximum value is 32767 for Vision files. Setting this variable to its maximum value can waste resources and is not recommended.

Note: If you change the value of MAX_LOCKS, you should consider changing the value of LOCKS_PER_FILE as well.
Parent topic: Configuration Variables
Parent topic: Configuration Variables


MENU_ITEM

This variable affects the behavior of pull-down menus.

The default action of a menu item is to return an exception value equal to the item's ID. You can change the default action of a particular item by using MENU_ITEM.

Use MENU_ITEM in the same fashion as the KEYSTROKE variable, except that the last entry on the line is the menu's ID, not the key code. For example, to cause a menu item whose ID is 200 to act the same as the Delete key, use the following:

MENU_ITEM  Edit=Delete  200

Alternately, you could cause menu item 200 to call the "notepad" sample program by using:

MENU_ITEM  Hot_Key="notepad" 200
Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


MESSAGE_BOX_COLOR

This variable is used on character-based hosts to specify the color and video attributes of characters displayed in a message box window. MESSAGE_BOX_COLOR can be set to a variety of numeric values that express combinations of color and video attributes. See Common Screen Options for more information.

If MESSAGE_BOX_COLOR is set to 0 (the default value), the message box is displayed with the default window colors and attributes.

Parent topic: Configuration Variables


MESSAGE_QUEUE_SIZE

This variable sets the initial size of the message queue, in bytes. The message queue is dynamically resized, as needed, to hold large messages. However, it is not resized to hold multiple messages (instead, the sending threads wait until the queue empties). Setting the value larger than the default will allow more messages to be queued. Setting it to a smaller value will allow fewer messages to be queued and conserves memory. The default size is 1024.

Parent topic: Configuration Variables


MIN_REC_SIZE

This configuration variable sets the minimum record size for print records, and for line sequential files for which trailing space removal has been specified. The default value is 1. If set to 0, then a record will be reduced to zero size (except for the line delimiter) if the line is blank. You may also set MIN_REC_SIZE to higher values to establish a minimum record size other than one.

Parent topic: Configuration Variables


MONOCHROME

When set to 1 (on, true, yes), this configuration variable disables color output for machines with graphics video cards. The default value is 0 (off, false, no).

ACUCOBOL-GT assumes that machines with graphics video cards are color machines. If you have a monochrome monitor attached to such a machine, some program screens may be difficult to see. You tell ACUCOBOL-GT to disable color output for these machines through the MONOCHROME configuration variable. When this variable is set to a 1, ACUCOBOL-GT will use only black and white.

Parent topic: Configuration Variables


MOUSE

This variable has meaning only on systems with a mouse. When the user selects a field in the Screen Section, the exact behavior depends on the field's underlying type. The runtime distinguishes between three classes of fields: numeric, numeric-edited, and all others. These are referred to respectively as NUMERIC, EDITED, and ALPHA.

You can control the behavior of the mouse with regard to each of these field types with the MOUSE configuration variable. This variable takes as its arguments one of the field-type names and two keywords. The first keyword defines how the field is selected when the user presses the left button. The second keyword indicates the shape that the mouse pointer should take while in the field. The first keyword can be one of the following:

None | Indicates that this type of field may not be selected with the mouse. When this keyword is used, then the second keyword (which defines the mouse's shape) is ignored. The mouse adopts the shape used for areas of the screen that are not part of any field.
Field | Indicates that pressing the left button anywhere in the field will cause the cursor to be positioned at the beginning of the field.
Character | Indicates that pressing the left button in the field will position the cursor at the character pointed to by the mouse. If this is past the last non-prompt character in the field, the cursor will be placed just after the last non-prompt character.

The second keyword indicates the shape that the mouse pointer should take while in the field. It can be one of the following:

Arrow | The mouse pointer appears in the default arrow shape.
Bar | The mouse appears as a vertical bar. This is the I-Bar shape typically used to indicate that the mouse can be positioned at a particular character.
Cross | The mouse appears as cross-hairs.

You may also define the shape that the mouse will take when it is used in the current field. Because the action of the mouse is the same for all field types once they become the current field, the mouse shape is the same for all three types. You set the desired shape using the Current keyword in the MOUSE configuration variable. The default shape is the Bar shape.

Configuring the MOUSE variable

Depending on where you are setting the MOUSE variable, there are three methods of setting its configuration:

  1. If you want to implement this variable in a configuration file, the variable can be set without using the equals sign. For example:
    MOUSE_NUMERIC_SHAPE     Bar
  2. If you are setting the variable in the Windows environment, the variable would look this:
    SET MOUSE_NUMERIC_SHAPE=Bar
  3. If you are setting the variable in your program using COBOL syntax, the variable would look like this:
    SET ENVIRONMENT "MOUSE_NUMERIC_SHAPE" TO "Bar"

The default configuration is as follows:

MOUSE_ALPHA_CHARACTER | Bar
MOUSE_NUMERIC_FIELD | Arrow
MOUSE_EDITED_FIELD | Arrow
MOUSE_CURRENT | Bar

You may place multiple entries on the MOUSE configuration line, but you are not required to do so.

The following configuration variables can also be used to set the behavior of the mouse:

To set field selection:

  • MOUSE_ALPHA_SELECT
  • MOUSE_EDITED_SELECT
  • MOUSE_NUMERIC_SELECT

To set cursor shape:

  • MOUSE_ALPHA_SHAPE
  • MOUSE_EDITED_SHAPE
  • MOUSE_NUMERIC_SHAPE
  • MOUSE_CURRENT_SHAPE

With these variables, you need to set the first and second keywords separately. For example, to change the defaults shown above for a numeric field, you would enter:

MOUSE_NUMERIC_SELECT  character
MOUSE_NUMERIC_SHAPE  bar
Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


MOUSE_FLAGS

This variable has meaning only on systems with a mouse. Indicate which mouse actions will return an exception value to your program by setting the value of the configuration variable MOUSE_FLAGS. Mouse actions that you don't want to deal with will be ignored. The value you set is actually one or more values added together. The possible values are:

1 | Causes ACUCOBOL-GT to use its automatic mouse handling facility. (default)
2 | Enables the "left button pushed" action.
4 | Enables the "left button released" action.
8 | Enables the "left button double-clicked" action.
16 | Enables the "middle button pushed" action.
32 | Enables the "middle button released" action.
64 | Enables the "middle button double-clicked" action.
128 | Enables the "right button pushed" action.
256 | Enables the "right button released" action.
512 | Enables the "right button double-clicked" action.
1024 | Enables the "mouse moved" action.
2048 | Forces the mouse pointer always to be the default arrow shape when you are using automatic mouse handling. If this is not set, then the shape of the mouse pointer varies depending on various other configuration options. See MOUSE above.
16384 | This causes all enabled mouse actions that occur within your application's window to return an exception value. If this is not set, then only mouse actions that occur within the current ACUCOBOL-GT window return a value. (The current ACUCOBOL-GT window is a window created by your program with the DISPLAY WINDOW verb.)

For example, if you wanted your program to receive an exception value whenever the user pressed either the left or right button, you would set:

MOUSE_FLAGS  130
Parent topic: Configuration Variables


NESTED_AX_EVENTS

When an application dialog contains an ActiveX control that is assigned an event procedure, the event handler sometimes triggers additional ActiveX events. This variable determines whether or not the event procedure will be nested.

Set this variable to 1 (on, true, yes) if you want the event procedure to be nested. (This is the default). When NESTED_AX_EVENTS is set to 1, the runtime allows events to trigger while it is processing other events. It is your responsibility to know when the event procedure is busy and reject events when this is the case, or to look for specific events and properly handle them. For example, consider this code:

AX-EVENT.
MOVE 1 TO MY-LOOP.
PERFORM UNTIL MY-LOOP = 10
* Do some stuff
ADD 1 TO MY-LOOP
END-PERFORM

When NESTED-AX-EVENTS is set to 1, it is possible that when your code is inside the event, possibly executing the loop for the fifth time, a new event triggers, setting MY-LOOP back to 1. The perform loop could execute simultaneously in two threads on the same data, and the runtime could crash. When you do not have reentrant events, MY-LOOP can only become 1 one time. This is the case when NESTED-AX-EVENTS are set to 0.

Set NESTED_AX_EVENTs to 0 (off, false, no) if you do not want the event procedure to be nested. Be aware, however, that this option may cause you to lose certain events (typically events triggered by modifications made in the event procedure).

When NESTED_AX_EVENTS is set to 0, once a program has entered an ActiveX control's event procedure, new events are ignored. This prevents the runtime from executing the same code, at the same time. However, events that are imperative for the code execution may be refused.

Note: NESTED_AX_EVENTS applies only to the local runtime and has no effect in thin client scenarios.
Parent topic: Configuration Variables


NET_FILE_TRACE

This variable is used to turn on tracing of the CLR Control Module as it relates to .NET support. To turn on tracing set NET_FILE_TRACE to 1. This creates NetTraceFile.txt in the directory where atermmgr.dll is located. The Default is 0 [off]. This option is ignored if using the - -a2n runtime option.
Parent topic: Configuration Variables


NO_BARE_KEY_LETTERS

This variable is related to the terminal manager KEYSTROKE EDIT=ALT method of requiring users to press the Alt key along with the key letter to move to a new control. In character mode and when accepting a push-button, check box, or radial button, the runtime's default behavior is to terminate the accept if the key letter of a control is pressed, and move to that control. See The KEYSTROKE Variable for more information.

This behavior can be changed by setting NO-BARE-KEY-LETTERS to TRUE. When set to TRUE, in order to move to these types of controls, users will be required to press the key set by the KEYSTROKE setting EDIT=ALT before pressing a key letter of that control. The default setting is FALSE, which uses the behavior described in the previous paragraph.

Parent topic: Configuration Variables


NO_CONSOLE

This variable has meaning only on graphical systems that create an application window, such as Windows. Set this variable to 1 (on, true, yes) to indicate that you've built your own user interface entirely in C or that you are using an interface created by a code-generating tool. This is equivalent to executing the runtime system with the -b command-line option. When this variable is set to 1, the runtime won't create its own application window. Instead, your C code must build its own window. When you provide your own user interface, you may not use ACCEPT or DISPLAY verbs in your COBOL program (except for those that don't interact with the screen or keyboard).

The default value is 0 (off, false, no).

Parent topic: Configuration Variables


NO_LOG_FILE_OK

Setting this variable to 1 (on, true, yes) eliminates the need to specify a default transaction log file with the LOG_FILE variable. When this variable is set, the runtime will write transaction recovery information only to the log files specified via the filename_LOG variables.

The default value is 0 (off, false, no).

Parent topic: Configuration Variables


NO_TRANSACTIONS

This variable allows you to disable ACUCOBOL-GT's built-in transaction management system. When NO_TRANSACTIONS is set to 1 (on, true, yes), all calls to ACUCOBOL-GT's built-in transaction management system return without doing any work. This affects all file systems in use. The value of NO_TRANSACTIONS is checked once, the first time a BEGIN, COMMIT, or ROLLBACK is attempted and it is not checked again. Therefore, although the variable can be set in the program, the effective setting cannot be changed after the first transaction management action has been attempted. The default value is 0 (off, false, no), meaning that the built-in transaction management facility is enabled.

Parent topic: Configuration Variables


NT_OPP_LOCK_STATUS

This configuration variable controls how files on a shared drive are opened if you are working in the Windows opportunistic locking mode. NT_OPP_LOCK_STATUS can take one of four values: CREATEFILE, SAFE, GETFILETYPE, or FAST. The default value is SAFE, which is a synonym for CREATEFILE.

If you set this variable to GETFILETYPE or FAST (synonyms for each other), the runtime uses the fast method of opening files.

Note: If your Windows installations are not completely up to date with all available patches from Microsoft, particularly those related to opportunistic locking, the GETFILETYPE or FAST setting may cause file corruption (error 98).
Parent topic: Configuration Variables


NUMERIC_VALIDATION

If this configuration variable is set to 1 (on, true, yes), the runtime checks for proper format when data is converted to a numeric type (via a MOVE, for example). When NUMERIC_VALIDATION is set to the default 0 (off, false, no), numeric conversion checking does not occur.

Parent topic: Configuration Variables


OEM_CHARACTER_SET

Setting this variable to ON(TRUE, YES) causes XDBC to call a function that will translate the ANSI character set to the OEM character set. Data being read will be translated from the OEM character set to the ANSI character set.

Parent topic: Configuration Variables


OLD_ARIAL_DIMENSIONS

The Arial font shipped with Windows 98 Version 2 has a character width of 35 pixels, while the Arial font shipped with earlier versions of Windows and Windows NT has a width of 23 pixels. This might cause field overlap or screen distortions in programs that rely on the smaller version of the Arial font. Setting this variable to 1 (on, true, yes) causes the runtime to use the 23-pixel measurement for fields, regardless of which version of Arial (35 or 23-pixel) is being used.

The default value of 0 (off, false, no) will cause fields to be sized according to the version of Arial used.

Note: Because the 35-pixel version of Arial is wider, uppercase characters may be truncated when their size is computed with the 23-pixel measurement. Use of this variable may not compensate for all possible character width sizing issues. Some reprogramming of your screens may be required.
Parent topic: Configuration Variables


OPEN_FILES_ONCE

This variable allows different logical files that access the same physical file to open the physical file only once. The default for this variable is 1 (on, true, yes). This variable is valid only for UNIX runtimes.

Parent topic: Configuration Variables


OPTIMIZE_CONTROL_RESIZE

This configuration variable determines how the runtime optimizes control resize requests. Prior to Version 5.2, the runtime would optimize away requests to resize a screen control if the new size and position matched the control's current size and position on the screen. In Version 5.2, or later, the runtime optimizes the control resize request using the SIZE and LINES indicated (or implied) by the program. Setting OPTIMIZE_CONTROL_RESIZE to 0 (off, false, no) prevents any optimization of control resizing operations. The default of 1 (on, true, yes) enables the new behavior. See Appendix C: Changes Affecting Previous Versions for more details.

Parent topic: Configuration Variables


OPTIMIZE_INDIVIDUAL_LINKAGE

This variable enables the runtime to perform address optimizations on each Linkage item individually. In versions prior to 8.1 this optimization was done either for all Linkage items or for none of them, which could result in scenarios where optimizations could have occurred on some items, but did not.

The default and recommended setting is 1 (on) because the main effect is improved CALL performance in a greater number of scenarios. Usually, the only reason to turn this variable off is if a flaw is suspected in the optimization.

Parent topic: Configuration Variables


PAGE_EJECT_ON_CLOSE

When set to 1 (on, true, yes), this variable will cause print files to print a page advance record when the file is closed, unless the close contains the NO REWIND phrase. This is provided for compatibility with RM/COBOL version 2. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


PAGED_LIST_SCROLL_BAR

This variable applies only in text-mode environments. PAGED_LIST_SCROLL_BAR can be set to -1, 0, or 1. The default value is -1. When set to -1, the vertical scroll bar is displayed to the right of a paged list box if the user interface configuration supports a mouse. Otherwise, the right border appears just like the left border. The appearance depends on whether the NO-BOX style is set and the values of the FULL_BOXES and LISTS_UNBOXED configuration variable settings.

The runtime internally calls the W$MOUSE library routine with the TEST-MOUSE-PRESENCE op-code to determine whether the user interface supports a mouse. Note that mouse support is available for X terminals only if the a_termcap entry includes the km function. See Mouse Support for X Terminals for more information.

When PAGED_LIST_SCROLL_BAR is set to 1, the vertical scroll bar is always displayed to the right of a paged list box. When set to 0, the vertical scroll bar is never displayed to the right of a paged list box.

Parent topic: Configuration Variables


PARAGRAPH_TRACE

This variable is used for debugging purposes and turns on paragraph tracing. Set this variable to 1 (on, true, yes) to turn on paragraph tracing from within the configuration file or the COBOL program. This is equivalent to the debugger tp command. The COBOL program must be compiled with symbols (-Gs, or anything that implies that option) to get any error output.

Parent topic: Configuration Variables


PDF_FONT_NAME

This configuration variable specifies the name of the font in use when using the -P PDF printing option.

If PDF_FONT_TYPE is set to BASE14, the font name defaults to Courier.

Permissible values are:

  • Courier
  • Courier-Bold
  • Courier-Oblique
  • Courier-BoldOblique
  • Helvetica
  • Helvetica-Bold
  • Helvetica-Oblique
  • Helvetica-BoldOblique
  • Times-Roman
  • Times-Bold
  • Times-Italic
  • Times-BoldItalic
  • Symbol
  • ZapfDingbats
Parent topic: Configuration Variables
Related reference
PDF_FONT_TYPE
Spooler Print Formatting


PDF_FONT_SIZE

This configuration variable specifies the size of the font in use when using the -P PDF printing option.

Defaults to: 11

Parent topic: Configuration Variables
Related reference
Spooler Print Formatting


PDF_FONT_TRUETYPE_TTC

This configuration variable specifies the path and file name of a TrueType Collection file (.ttc) from which to select a TrueType font (using PDF_FONT_TRUETYPE_TTC_INDEX) when using the -P PDF printing option.

The variable PDF_FONT_TYPE must be set to TRUETYPE for this setting to have an effect.

Note: If you specify both PDF_FONT_TRUETYPE_TTF and PDF_FONT_TRUETYPE_TTC, the PDF_FONT_TRUETYPE_TTF variable takes precedence.
Parent topic: Configuration Variables
Related reference
PDF_FONT_TRUETYPE_TTC_INDEX
Spooler Print Formatting
PDF_FONT_TYPE


PDF_FONT_TRUETYPE_TTC_INDEX

This configuration variable specifies the index number of a TrueType font from a TrueType Collection file (as specified by PDF_FONT_TRUETYPE_TTC) when using the -P PDF printing option.

The variable PDF_FONT_TYPE must be set to TRUETYPE for this setting to have an effect.

Note: If you specify both PDF_FONT_TRUETYPE_TTF and PDF_FONT_TRUETYPE_TTC, the PDF_FONT_TRUETYPE_TTF variable takes precedence.
Parent topic: Configuration Variables
Related reference
PDF_FONT_TRUETYPE_TTC
Spooler Print Formatting
PDF_FONT_TYPE


PDF_FONT_TRUETYPE_TTF

This configuration variable specifies the path and file name of a TrueType file (.ttf) when using the -P PDF printing option.

The variable PDF_FONT_TYPE must be set to TRUETYPE for this setting to have an effect.

Note: If you specify both PDF_FONT_TRUETYPE_TTF and PDF_FONT_TRUETYPE_TTC, the PDF_FONT_TRUETYPE_TTF variable takes precedence.
Parent topic: Configuration Variables
Related reference
Spooler Print Formatting
PDF_FONT_TYPE


PDF_FONT_TYPE

This configuration variable specifies the type of font when using the -P PDF printing option.

The default value for the font type is BASE14.

Permissible values are:

BASE14
Base 14 fonts are built into PDF, and all PDF viewer applications can display these. For a list of the Base 14 fonts you can specify, see PDF_FONT_NAME.
TYPE1
Type 1 is a format of outline fonts developed by Adobe. You need a Printer Font Binary file (.pfb) or Adobe Font Metrics file (.afm) to use this type of font, which you can specify using PDF_FONT_TYPE1_PFB or PDF_FONT_TYPE1_AFM respectively.
TRUETYPE
TrueType fonts use an external file to specify font characteristics. To specify the file, use PDF_FONT_TRUETYPE_TTF or PDF_FONT_TRUETYPE_TTC, depending on the type of file you have.
Parent topic: Configuration Variables
Related reference
PDF_FONT_NAME
Spooler Print Formatting
PDF_FONT_TRUETYPE_TTC
PDF_FONT_TRUETYPE_TTC_INDEX
PDF_FONT_TRUETYPE_TTF
PDF_FONT_TYPE1_PFB
PDF_FONT_TYPE1_AFM


PDF_FONT_TYPE1_PFB

This configuration variable specifies the path and file name of a Type 1 Printer Font Binary file (.pfb) when using the -P PDF printing option.

The PDF_FONT_TYPE variable must be set to TYPE1 for this setting to have an effect.

Parent topic: Configuration Variables
Related reference
Spooler Print Formatting
PDF_FONT_TYPE


PDF_FONT_TYPE1_AFM

This configuration variable specifies the path and file name of an Adobe Font Metrics file (.afm) when using the -P PDF printing option.

The PDF_FONT_TYPE variable must be set to TYPE1 for this setting to have an effect.

Parent topic: Configuration Variables
Related reference
Spooler Print Formatting
PDF_FONT_TYPE


PDF_MARGIN_BOTTOM

This configuration variable specifies the bottom margin setting when using the -P PDF printing option.

Defaults to: 0 .

Parent topic: Configuration Variables
Related reference
PDF_MARGIN_LEFT
PDF_MARGIN_RIGHT
PDF_MARGIN_TOP
Spooler Print Formatting


PDF_MARGIN_LEFT

This configuration variable specifies the left-hand margin setting when using the -P PDF printing option.

Defaults to: 0 .

Parent topic: Configuration Variables
Related reference
PDF_MARGIN_BOTTOM
PDF_MARGIN_RIGHT
PDF_MARGIN_TOP
Spooler Print Formatting


PDF_MARGIN_RIGHT

This configuration variable specifies the right-hand margin setting when using the -P PDF printing option.

Defaults to: 0 .

Parent topic: Configuration Variables
Related reference
PDF_MARGIN_BOTTOM
PDF_MARGIN_LEFT
PDF_MARGIN_TOP
Spooler Print Formatting


PDF_MARGIN_TOP

This configuration variable specifies the top margin setting when using the -P PDF printing option.

Defaults to: 0 .

Parent topic: Configuration Variables
Related reference
PDF_MARGIN_BOTTOM
PDF_MARGIN_LEFT
PDF_MARGIN_RIGHT
Spooler Print Formatting


PDF_PAGE_DIRECTION

This configuration variable specifies the page orientation when using the -P PDF printing option.

Defaults to: PORTRAIT.

Permissible values:

  • PORTRAIT
  • LANDSCAPE
Parent topic: Configuration Variables
Related reference
Spooler Print Formatting


PDF_PAGE_SIZE

This configuration variable specifies the size of the page when using the -P PDF printing option.

Defaults to: LETTER.

Permissible values:

Permissible values | Dimensions
LETTER | 8.5 x 11 inches | 216 x 280 mm
LEGAL | 8.5 x 14 inches | 216 x 356 mm
A3 | 11.7 x 16.5 inches | 297 x 420 mm
A4 | 8.3 x 11.7 inches | 210 x 297 mm
B4 | 9.8 x 13.9 inches | 250 x 353 mm
B5 | 6.9 x 9.8 inches | 176 x 250 mm
EXECUTIVE | 7 x 10 inches | 184 x 267 mm
US4x6 | 4 x 6 inches | 102 x 152 mm
US4x8 | 4 x 8 inches | 102 x 203 mm
US5x7 | 5 x 7 inches | 127 x 178 mm
COMM10 | 4.1 x 9.5 inches | 104 x 241 mm
Parent topic: Configuration Variables
Related reference
Spooler Print Formatting


PERFORM_STACK

This variable sets the depth to which PERFORM statements can be nested at runtime when the -Zr compile-time option is used. The default value is 128. The maximum value is 10916. Setting this variable to its maximum value can waste resources and is not recommended.

Parent topic: Configuration Variables


PRELOAD_JAVA_LIBRARY

This variable is designed for those calling a Java program from COBOL via the C$JAVA library routine. By default, the Java Virtual Machine (JVM) is loaded by the runtime the first time it executes a CALL C$JAVA statement. If you want to load the JVM when the runtime is started, set this configuration variable to 1. If you do not want to preload the JVM, set the variable to 0.

See C$JAVA and Calling the C$JAVA Routine for more information.

Parent topic: Configuration Variables


PROFILE_TYPE

This configuration variable provides an optional method of profiling ACUCOBOL-GT on Windows called COUNTER. The counter method uses the debugger to perform counting and appears to provide the most accurate results in Windows environments.

Set the PROFILE_TYPE configuration variable to either ASYNCH or COUNTER. When set to the default value of ASYNCH, the runtime performs profiling the way it historically has. When set to the value COUNTER, the runtime uses this method of profiling. Note that your COBOL programs must be compiled with -Gd as well as -Gs options to use the counter method.

The counter method is also available on UNIX and can be used if profiling your COBOL results in a message similar to profile timer expired. This method doesn't completely solve that problem, but does substantially mitigate it.

Parent topic: Configuration Variables


PROMPTING

This variable is used on character-based hosts to turn ENTRY-FIELD prompting off or on. When PROMPTING is set to 0 (off, false, no) prompting is not performed. The default value of PROMPTING is 1 (on, true, yes).

Parent topic: Configuration Variables


QUERY_TIMEOUT

A query through AcuXDBC has a default timeout of 2 seconds, but you can use the QUERY_TIMEOUT variable in your acuxdbc.cfg configuration file to change the timeout.

In the acuxdbc.cfg file, set QUERY_TIMEOUT to a value (in seconds), or set to 0 (zero) so that queries never time out.

Parent topic: Configuration Variables
Parent topic: Configuration Variables


QUEUE_READERS

This configuration variable evens out user access by modifying the rules Vision uses when several users are accessing a file. This variable applies to UNIX machines. Because of restrictions, it is recommended only for sites that are experiencing performance problems with updaters.

By default, the runtime allows multiple readers to access a file simultaneously, while updaters require exclusive access to the file. When a file has many readers, an updater can get blocked out of the file for a period of time while the runtime waits for a moment when there are no active readers. While this allows processes that read the file to have nearly immediate access, updaters may need to wait for a noticeable amount of time.

The QUEUE_READERS configuration variable lets you request that the runtime service each user in turn. This means a reader will have the same priority for accessing a file as an updater does. Each user is processed in turn so that access to files is evenly balanced among all the users.

By default, QUEUE_READERS is set to 0 (off, false, no). Set it to 1 (on, true, yes) to force the readers to take turns instead of having immediate access.

Because of technical limitations in the UNIX file system, if you use this configuration variable you must provide read-write access to all indexed and relative files that the runtime uses. This is true even for files that are open only for input--UNIX requires that the runtime have write access to the files in order to place the kind of lock that causes each user to take turns.

Parent topic: Configuration Variables


QUIT_MODE

This variable has meaning only on graphical systems such as Windows. It gives you control over the Close action that appears on the System menu in a graphical environment. You may use the QUIT_MODE variable with only the main application window. All other windows return the CMD-CLOSE event when they are closed. QUIT_MODE has no affect on windows created with the NO-CLOSE phrase. See formats 11 and 12 of the DISPLAY Statement, in the ACUCOBOL-GT Reference Manual for more information.

Many COBOL programs should not be shut down in an uncontrolled manner. This is especially true of any application that updates several files in a row. If the program is halted after updating the first file, but before updating the last, the files are left in an inconsistent state. For this reason, ACUCOBOL-GT allows you to control the Close action.

To do this, you set QUIT_MODE to a non-zero value. The value that you specify affects the Close action as follows:

-2 | Disable Close: disables the Close action entirely. The Close menu item will appear gray on the System menu, and the user will not be able to select it.
-1 | Close only on input: the runtime disables the Close action except when it is waiting for user input. This prevents the user from stopping the runtime in the middle of a series of file operations, but still allows the user to quit the application any time that the application is waiting for input.
0 | Always Close: the runtime halts the program whenever Close is selected from the system menu.
>0 | Program controlled Close: when a positive value is used, the Close item becomes a standard menu item with an ID equal to the value of QUIT_MODE. You may then handle the Close item just like any other menu item.

For example, if you set QUIT_MODE to 100, then your program will receive exception value 100 when the user selects the Close item. If you wanted to call a special shutdown program when the user selected Close, you could assign the Close action to a hot-key program:

MENU_ITEM  Hot_Key ="shutdown"  100

In this example, the "shutdown" program might pop up a small window to confirm that the user wanted to exit and, if so, do a STOP RUN.

If you start your program in safe mode with the -s runtime option, then QUIT_MODE will be initialized to -2 instead of 0. This prevents the user from using the Close menu item. A QUIT_MODE entry in the configuration file takes precedence over the default handling of -s.

If a user attempts to end the Windows session when it is not allowed, a pop-up message box asks the user to terminate the application first. You can customize the message that appears in the box by setting the TEXT configuration variable, message number 18.

Note: The QUIT_MODE setting affects only the main application window. All other windows always return the event CMD-CLOSE when the window is closed.
Parent topic: Configuration Variables


QUIT_ON_FATAL_ERROR

This configuration variable applies only when running in HP COBOL compatibility mode (with the -Cp compiler option). The QUIT_ON_FATAL_ERROR configuration variable causes the runtime to call the MPE QUIT intrinsic when an error occurs. The MPE job control word (JCW) is then set, and the MPE environment can determine if the program terminated with a fatal error. When set to 1 (on, true, yes), QUIT_ON_FATAL_ERROR calls the MPE QUIT intrinsic. The default setting is 0 (off, false, no).

Parent topic: Configuration Variables


QUIT_TO_EXIT

When this variable is set to 1 (on, true, yes), the user must press the close button on the title bar (or an alternate close mechanism provided by the window) after the program executes a STOP RUN. The default value is ".

Parent topic: Configuration Variables


RECURSION

ACUCOBOL-GT allows a program to call itself, directly or indirectly. A CALL statement that attempts to call an active program is termed a recursive call.

To use recursive calls, you must set the configuration variable RECURSION to 1 (on, true, yes). The default setting for RECURSION is 0 (off, false, no), which disallows recursive calls.

When you allow recursive calls, an active program may be called again. This causes a new copy of the program to be loaded into memory and executed, as if it were the first call of that program. Files and data described in that program are local to each copy of the program.

More specifically, the runtime assigns a recursion level to each recursively called program. The first time a program is called, it is assigned a recursion level of 0. If that program is still active and it is called again, it receives a recursion level of 1. The recursion level is incremented by 1 for each active copy of the same program.

When you call a program at a specific recursion level for the first time, it is freshly loaded from disk and its Working-Storage data items are given their initial values as defined by their VALUE clauses. Subsequent calls to a program at the same recursion level will find the files and data left in the same state that the program had when it last exited.

Files and data items are distinct between different recursion levels.

When you CANCEL a recursively called program, all of its inactive copies are removed from memory. Active copies are left alone. Subsequent calls to any of the canceled recursion levels will reload the program from disk and reinitialize the files and data items.

If you need to share data between different active copies of the same program, you can pass this data through the Linkage Section. Alternatively, you can share both files and data items by declaring them as EXTERNAL items. Yet another option is the RECURSION_DATA_GLOBAL configuration option.

The runtime system shares the program code for recursively called programs. Thus, while each recursion level has its own set of data, there is only one copy of the Procedure Division code in memory, regardless of how many active copies of the program there are. The runtime system does not, however, share overlays. Each copy of the program in memory has its own overlay area.

Parent topic: Configuration Variables


RECURSION_DATA_GLOBAL

This configuration variable allows you to configure the runtime so that each instance of a recursively called program shares the same data as the original instance of the program. The primary reason for configuring the runtime in this manner is if you are migrating code that relies on this behavior from another COBOL system, such as HP COBOL.

When RECURSION_DATA_GLOBAL is set to 1 (on, true, yes), files and data items in a recursive call of a program refer to the identical items in the original call of that same program. This is true regardless of the entry point into the program. Changes to data or file state made in any recursive instance of the program are seen by all other instances of that program in the same run unit.

Note that to use this feature, you must not only set the configuration variable RECURSION_DATA_GLOBAL to 1, you must also set the RECURSION configuration variable to 1 to allow recursion (which is not allowed under standard ANSI-85 COBOL rules).

The default is 0 (off, false, no).

Parent topic: Configuration Variables


REL_DELETED_VALUE

This configuration variable is helpful when you use relative files and need to have a valid record that contains binary zeros. However, because binary zeros are used as the deleted record marker, you have to be able to change this marker. REL_DELETED_VALUE can hold the ASCII character value for the new deleted record marker.

Parent topic: Configuration Variables


REL_LOCK_READ_THROUGH

This variable allows you to read through relative file record locks in Windows environments. This means that READs that do not assert a lock are allowed to READ a relative file record even if it is locked by another process. To turn on the read through capability, all processes accessing the relative file must set the configuration variable REL_LOCK_READ_THROUGH to 1 (on, true, yes). When this variable is turned on, the Vision library uses an alternate location for relative file record locks that does not block other processes from reading the records. This is necessary because Windows has "enforced" file locks that preclude all other access to the locked region. Failure to set the configuration variable to the same value on all processes accessing the relative file results in undefined behavior. This variable has no effect on UNIX platforms. See Handling Files for more information about relative files and record locking.

Parent topic: Configuration Variables


RENEW_TIMEOUT

This configuration variable determines the behavior when the BEFORE TIME time clause is specified on a format 2 ACCEPT statement.

0 (or OFF, FALSE, or NO)
The timer starts on commencement of the ACCEPT statement, but as soon as a key is pressed, the timer stops and the ACCEPT statement will not time out. Therefore, if BEFORE TIME 500 is specified, you have 5 seconds to start entering data into the field, otherwise the statement will time out. This is the default.
1 (or ON, TRUE, YES, or CONTINUE)
The timer starts on commencement of the ACCEPT statement, and continues regardless of keypresses. Therefore, if BEFORE TIME 500 is specified, you have 5 seconds to complete the field, otherwise the statement will time out.
2 (or RESTART)
The timer starts on commencement of the ACCEPT statement, but as soon as a key is pressed, the timer is restarted. Therefore, if BEFORE TIME 500 is specified, you have 5 seconds to start entering data into the field, and then 5 seconds between each keystoke, otherwise the statement will time out.
Parent topic: Configuration Variables


RESIZE_FRAMES

This variable is used to turn off the automatic resizing of frames that is performed on character-based hosts. By default, a character-based host runtime automatically resizes frames to visually surround all controls whose home coordinates are bounded by the frame. This makes it easier to maintain applications that run on both character and graphical systems. To turn automatic resizing off, set RESIZE_FRAMES to 0 (off, false, no). The default value is 1 (on, true, yes).

Parent topic: Configuration Variables


RESIZE_FREELY

Normally, under a graphical host (such as Windows), the runtime will not allow you to resize an AUTO-RESIZE window larger than its logical size (as determined by the number of rows and columns the program requested when it created the window). When the RESIZE_FREELY variable is set to 1 (on, true, yes), the user can resize the window to any size. Maximizing the window will cause the window to occupy the entire available screen. The region of the window that lies outside of the logical area will not be accessible by the program and will be shown as the background color of the logical window (defined as the last background color to be applied to the entire window). Setting this option is essentially a cosmetic change to the way your application looks when maximized. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


RESTRICTED_VIDEO_MODE

This value determines which rules will be followed when the program is positioning attribute characters for magic cookie terminals (terminals whose attributes occupy screen positions). The default is 0. See Restricted Attribute Handling for more information.

Parent topic: Configuration Variables


RMS_NATIVE_KEYS

This variable is for use only on VAX/VMS systems. When it is set to 1 (on, true, yes), it causes the runtime to specify a key type for numeric keys. In order to make use of this variable, you must also create XFD files at compile-time (-Fx), and you must set the configuration variable XFD_DIRECTORY to point to the directory containing those XFD files.

When these steps have been taken, the runtime will create RMS files with keys having either the packed decimal or integer attribute, under certain conditions dictated by the RMS file system. In particular, a key will have the packed decimal or integer attribute only if it is a single-segment key and only if there is a single field in the key. In this case, a USAGE COMP-3 data item in the key will receive the packed decimal attribute, and a USAGE COMP-5 data item (if it is 2, 4, or 8 bytes long) will receive the integer attribute.

One effect of having this attribute set on key fields is that the order of the data is changed. Without this attribute, a file that has records with keys -3, -2, -1, 0, 1, 2, 3 would have those records ordered in this way: 0, 1, -1, 2, -2, 3, -3. With this attribute, those records would be ordered in this way: -3, -2, -1, 0, 1, 2, 3. The default setting for this variable is 0 (off, false, no).

Parent topic: Configuration Variables


SCREEN

This configuration variable controls a variety of screen configuration options. See The SCREEN Option for more information.

This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.

Parent topic: Configuration Variables


SCREEN_COL_PLUS_BASE

This variable allows you to configure the COLUMN PLUS phrase in the Screen Section. This capability is provided to improve compatibility with other COBOLs. SCREEN_COL_PLUS_BASE allows you to choose the behavior that works best for your program. It takes the following values:

-1 | (default) This value causes the runtime to determine the behavior of the COLUMN PLUS phrase based on whether ICOBOL compatibility has been specified with the -Ci compile option. If so, "COLUMN + 1" produces a space between items, and "COLUMN + 0" creates adjacent items. If ICOBOL compatibility has not been specified, "COLUMN + 1" produces adjacent items. This matches the prior behavior of ACUCOBOL-GT.
0 | This value causes column adjustments to start counting at zero. In this case, "COLUMN + 0" produces adjacent items, and "COLUMN + 1" puts a space between items.
1 | This value causes column adjustments to start counting at one. In this case, "COLUMN + 1" produces adjacent items, and "COLUMN + 2" puts a space between items.
Parent topic: Configuration Variables


SCREEN_TRACE

This variable is used for debugging and turns on screen tracing. Set this variable to 1 (on, true, yes) to turn on screen tracing from within the configuration file or the COBOL program. This is equivalent to the debugger ts command.

Parent topic: Configuration Variables


SCRIPT_STATUS

This variable controls the behavior of ACCEPT FROM INPUT STATUS when the input is not attached to a terminal. If SCRIPT_STATUS has its default setting of 0 (off, false, no), an ACCEPT FROM INPUT STATUS statement will return a fixed value when the program has redirected input. The value returned is the value of the INPUT_STATUS_DEFAULT configuration variable.

When SCRIPT_STATUS is not 0, and input is redirected, then ACCEPT FROM INPUT STATUS will return the actual status of the script file (i.e., it will return "1" (on, true, yes) unless the script file has been exhausted).

Parent topic: Configuration Variables


SCRN

This variable can be used in conjunction with the SCREEN variable to control many attributes of the video sub-system. See The SCREEN Option for more information.

This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.

Parent topic: Configuration Variables


SCROLL

This variable affects when screen scrolling will occur. When it is set to 1 (on, true, yes), scrolling and cursor positioning occur normally. When it is set to 0 (off, false, no), screen scrolling will occur only as the result of a SCROLL phrase in an ACCEPT or DISPLAY statement, and any DISPLAY statement that references a line past the bottom of the current window will be ignored. ACCEPT statements that reference a line past the bottom of the current window will be placed in the home position of the window. The default setting is 1.

Parent topic: Configuration Variables


server_MAP_FILE

This variable is used to point to the character map file used for translating international character sets between a client machine and a specific server that uses different character codes. The map file is a simple text file that you create with an editor of your choice. Each line in the map file must contain two values in either decimal or hexadecimal: the character code of the character on the client machine, and the character code of the same character on the server. Use a # sign to indicate a comment.

The map file may be stored on either the client machine or the server machine.

The server specified in the configuration variable name must match the server specified in the remote name notation that points to the data files. For example, if you are using AcuServer to access remote files on a machine named sun3, you would use remote name notation to specify the directory that contains the data files. It might look like this:

@sun3:/user/acct/inventory

Then, create a map file and use this configuration variable to point to the map file:

sun3_map_file  @sun3:/user/acct/inventory/map.txt

If the map file is local, your value might look like this:

sun3_map_file  C:\user\utility\map.txt

If the map file is located on a server, you must have the AcuServer product on that server, to enable client access.

The runtime first searches for the configuration variable server_MAP_FILE and, if it is found, uses that setting to locate the map file. If that variable is not set, the runtime searches for DEFAULT_MAP_FILE. If that variable is also not set, then no character translation is done.

Parent topic: Configuration Variables


server_PASSWORD

Designed to be defined in the environment (rather than in the configuration file), server_PASSWORD and its mate serve make working with AcuServer easier when the compiler and cblutil are called repeatedly from the AcuBench integrated development environment. In this scenario, when one of these variable is used, the user never has to enter a password. When these variables are not used, if a password is required the user must provide it repeatedly.

Set server_port_PASSWORD to the value of the password. For example:

MERCURY_PASSWORD=we1rneB

where server is replaced by the name of the server.

The compiler checks the variable server_port_PASSWORD first. If it isn't defined, server_PASSWORD is checked. If server_PASSWORD is not defined, the user is prompted for a password. If either variable is defined, but the value does not match the value in the AcuAccess file, the connection attempt fails.

Parent topic: Configuration Variables


server_port_PASSWORD

Designed to be defined in the environment (rather than in the configuration file), server_port_PASSWORD and its mate server_PASSWORD make working with AcuServer easier when the compiler and cblutil are called repeatedly from the AcuBench integrated development environment. In this scenario, when one of these variable is used, the user never has to enter a password. When these variables are not used, if a password is required the user must provide it repeatedly.

Set server_port_PASSWORD when you want to connect to a server on a particular port. For example, to set a password to connect to a server named MERCURY that is listening on port 4330, you can set the following:

MERCURY_4330_PASSWORD=we1rneB

where server is replaced by the name of the server, and port is replaced by the port number that AcuServer is using.

The compiler checks the variable server_port_PASSWORD first. If it isn't defined, server_PASSWORD is checked. If server_PASSWORD is not defined, the user is prompted for a password. If either variable is defined, but the value does not match the value in the AcuAccess file, the connection attempt fails.

Parent topic: Configuration Variables


SHARED_CODE

For many UNIX machines, ACUCOBOL-GT supports the ability to have multiple users share the same copy of a COBOL program's object code in memory. This configuration variable indicates which programs you want to share code. Use of shared memory is recommended only if you have a problem with limited memory and excessive swapping. In this case, the advantage of reduced swapping will usually more than make up for the overhead added by sharing memory. To use shared code for all of your programs on UNIX, add the following line:

SHARED_CODE   1

This will cause all programs to attempt to share code. Every code segment loaded into memory will be placed into shared memory until shared memory is full. Further code segments will then be placed in conventional memory. If the system runs out of shared memory and the shared code requests start failing, each runtime will have its own copy of the program in its own memory space.

Since shared memory is a limited resource under UNIX, you will usually want to restrict the use of shared code to those programs where it will be most beneficial. This will ensure that other programs do not use up all of the available shared memory first. To do this, specify each program you want to share as follows:

SHARED_CODE  Program1
SHARED_CODE  Program2
SHARED_CODE  Program3

(The program name may also be enclosed in single or double quotes, for example, "Program1" or 'Program2'.) When you use this method, Program1, Program2, and so forth are the PROGRAM-IDs from the programs' Identification Divisions (note that a program's object file name is not used). If you use this method, then setting SHARED_CODE to 1 will have no effect.

See acushare Utility Program in the ACUCOBOL-GT User's Guide for more information.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


SHARED_LIBRARY_EXTENSION

This variable allows you to define the filename extension for UNIX/Linux shared object libraries. The default value matches the standard value for the host system. This variable has meaning only on systems that support UNIX shared libraries.

Note: Prior to version 9.0, the default value was fixed as .so. However, some systems use a different shared library extension so now the default value matches the extension used on the shared libraries in the lib directory. You may need to update the value of the SHARED_LIBRARY_EXTENSION configuration variable if you were relying on it always being to .so.
Parent topic: Configuration Variables


SHARED_LIBRARY_LIST

This variable allows you to specify the names of UNIX/Linux shared object libraries or Windows DLLs.

SHARED_LIBRARY_LIST can be set in one of three ways:

  1. In the environment
  2. In the runtime configuration file
  3. Programmatically with the SET ENVIRONMENT statement

The runtime loads the listed objects on program startup or as the result of a SET ENVIRONMENT statement. Names must be delimited by spaces, colons (UNIX/Linux), or semicolons (Windows).

With DLLs, you can specify both the name of the DLL and the calling convention to use. Any calling convention specified this way overrides the DLL_CONVENTION variable setting.

You can also list objects without path information and use the SHARED_LIBRARY_PREFIX configuration variable to specify a set of directories that the runtime will search when attempting to load a shared library.

Once loaded, functions exported by these libraries can be called directly.

The SET ENVIRONMENT statement can be used to set SHARED_LIBRARY_LIST any number of times during program execution. Each time it is set, the runtime loads the libraries listed. Previously loaded libraries remain loaded. Libraries loaded with SHARED_LIBRARY_LIST remain in memory until the process exits. The CANCEL statement cannot be used to unload the library.

On some systems, such as AIX, if the shared module is a member of an archive, you must specify the name of the member in parentheses after the name of the archive. For example:

SHARED_LIBRARY_LIST="/usr/opt/db2_08_01/lib/libdb2.a(shr.o)"

SHARED_LIBRARY_LIST is like the runtime -y option, except that it does not require setting the SHARED_LIBRARY_EXTENSION variable, and unlike -y, you can mix .a and .so libraries in the list.

Note: The SHARED_LIBRARY_LIST configuration variable does not load client-side DLLs for thin client applications that make calls using the CALL verb @[DISPLAY]: syntax. These applications must explicitly load the DLL by calling it with the CALL verb before calling a function within the DLL.
Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


SHARED_LIBRARY_PREFIX

This variable allows you to specify a set of directories that the runtime will search when attempting to locate a shared library. The format of the value is the same as that allowed for FILE_PREFIX. You can set SHARED_LIBRARY_PREFIX in the configuration file, environment, or programmatically with the SET verb.

The default value on Windows systems is empty.

The default value on UNIX and Linux systems is /opt/acucorp/730/lib /opt/acu/lib. This helps the runtime find libclnt.so (or libclnt.sl) when the operating system's shared library environment variable (e.g., LIBPATH, LD_LIBRARY_PATH, SHLIB_PATH, etc.) is not set.

Parent topic: Configuration Variables


SHUTDOWN_DESTROYS_GUI

This configuration variable causes the run time to destroy all canvases on shutdown. On character-based systems, this has the side effect of erasing the screen on shutdown.

Use this configuration variable to help diagnose the cause of a failure during the run time shutdown process.

Set to TRUE (ON, YES, 1) to destroy all canvases on shutdown. Set to FALSE (OFF, FALSE, 0) to shut down normally. The default is TRUE.

Parent topic: Configuration Variables


SHUTDOWN_FREES_PROGRAMS

This configuration variable causes the run time to free all memory associated with programs on shutdown. Use this configuration variable to help diagnose the cause of a failure during the run time shutdown process.

Set to TRUE (ON, YES, 1) to release associated program memory when the ACUCOBOL-GT run time shuts down. Set to FALSE to retain program memory upon shutting down the run time. The default is TRUE.

Parent topic: Configuration Variables


SHUTDOWN_MESSAGE_BOX

This variable allows you to specify whether or not you want the runtime's shutdown message to be displayed in a message box. If this variable is set to 0 (off, false, no), the runtime will display the shutdown message to the screen without a message box. The default value is 1 (on, true, yes).

Parent topic: Configuration Variables


SHUTDOWN_TESTS

Use this configuration variable to help diagnose the cause of a failure during the run time shutdown process.

Set this configuration variable to FALSE (OFF, NO, 0) to see whether certain tests performed during shutdown eliminate a shutdown failure. If a failure reproduces when this variable is set to FALSE, then the fix implemented by ECN-3431 might resolve that issue when it is applied to an earlier release of ACUCOBOL-GT. In other words, if the crash does not reproduce with release 8.0.0 or later, then try SHUTDOWN_TESTS=FALSE.

If the crash then reproduces, it probably means that the problem can be resolved in an earlier release by patching in ECN-3431.

You can also use this configuration variable in conjunction with SHUTDOWN_FREES_PROGRAMS. If this variable is set to TRUE (ON, YES, 1), then all program memory is freed only if the main program is a COBOL program.

Parent topic: Configuration Variables


SINGLE_STATUS_BAR

The SINGLE-STATUS-BAR configuration variable controls the behavior when a new STATUS-BAR control is created. If set to TRUE (which is the default), then displaying a status bar on a canvas that already has one results in the old STATUS-BAR control being destroyed before the new one is created.

When set to FALSE, a new STATUS-BAR control will be created and displayed, as in prior versions.

Parent topic: Configuration Variables


SORT_DIR

This variable allows you to place temporary files used by the SORT verb in another directory. By default these files are stored in the current directory. You can specify an alternate directory to hold the sort files by setting the configuration variable SORT_DIR to the desired directory. This value is treated as a prefix, much like FILE_PREFIX. You can improve the performance of the SORT verb by placing the temporary files on a fast device. Take care, however, that the device has enough free space to hold twice the size of the data to be sorted.

You may not use the SORT_DIR variable with AcuServer.

Parent topic: Configuration Variables


SORT_FILES

Note: As of extend 10, this variable is deprecated. Please use a combination of A_SORT_REGIONS, A_SORT_REGIONS_FINAL, and A_SORT_FILE_MEMORY to configure sort operations.

This configuration variable sets the number of temporary files used by SORT. The acceptable range is from 4 to 64. The default value is 8.

Increasing the number of files used will usually improve SORT performance, particularly for large sorts. Note that you must have enough available file handles to open all of the temporary files concurrently. In general, the number of files available is more important than the amount of memory used. If you are experiencing long sorts, try increasing the number of files before you increase the amount of sort memory.

The SORT verb removes all of its temporary files, except for one, prior to beginning its output phase.

Parent topic: Configuration Variables
Related reference
A_SORT_FILE_MEMORY
A_SORT_REGIONS
A_SORT_REGIONS_FINAL


SORT_MEMORY

This variable specifies the number of 64KB blocks of memory that the SORT statement will try to allocate when it executes. The acceptable range is from 1 to 16384. The default value is 32. This variable, SORT_MEMORY is no longer valid begginning in Version 10. Using a value lower than the default can be useful if memory is tight on the host machine. Using a higher value may enhance SORT performance.

Take care, when increasing the SORT_MEMORY setting, to ensure that you do not assign too much memory to the runtime. For most operating systems, the memory used by SORT is not returned to the system after the SORT completes. While the runtime may use the memory for other purposes, this memory is not available to other programs until the runtime exits. Because of this, you may want to isolate a large SORT operation into its own program, run by a temporary runtime process, so that once the process exits, the memory is returned to the operating system.

The SORT statement will attempt to allocate the amount of memory specified in SORT_MEMORY. If the requested amount is not available, the runtime will return an out of memory error.

Parent topic: Configuration Variables


SPACES_ZERO

This configuration variable applies only to object files generated with ACUCOBOL-85 Version 1.5 and earlier. For later object files, use the -Zz compiler option. When SPACES_ZERO is 1 (on, true, yes), it alters the method in which USAGE DISPLAY data items are used by the runtime system. The main effect is that, in most cases, a data item containing spaces will be treated as if it contained zeros. Note that this may not occur in all instances because the ACUCOBOL-GT compiler may construct code that directly acts on a data item without first converting it to a number. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


SPOOL_FILE

This configuration variable allows you to hold a pipe open when you close the named file with the CLOSE WITH NO REWIND verb. This enables you to gather multiple reports into a single job for the print spooler. See File Name Interpretation in the ACUCOBOL-GT User's Guide for more information about pipes and file name interpretation.

The value given to the SPOOL_FILE variable must be the ASSIGN name of a sequential file that has been attached to a pipe. The pipe must be attached to the ASSIGN name in the COBOL configuration file via the -P option. For example, suppose you have a file defined as follows:

SELECT PRINT_FILE
ASSIGN TO PRINT "PRINTER"

and that you have the following pipe defined in the COBOL configuration file:

PRINTER  -P  lp  -s

Then, to specify that you want to keep the pipe open when the file is closed WITH NO REWIND, you would add the following line to the COBOL configuration file:

SPOOL_FILE PRINTER

The name specified for SPOOL_FILE is processed in the same way as the external file name specified in the file's ASSIGN clause.

When the corresponding file is closed with a NO REWIND option, the pipe is not closed. Instead, if the file is later opened again, the same pipe is used. The pipe is not closed until a CLOSE verb without the NO REWIND option is executed on that file, or until the run unit finishes. Only one pipe can be held open in this manner.

Parent topic: Configuration Variables


STD_FIXED_FONT

This configuration variable allows you to set the standard font used by the Windows version of the runtime. It can be set in the configuration file to one of the following values:

-1 | (default) The web runtime uses ANSI_FIXED_FONT. Other instances of the runtime use SYSTEM_FIXED_FONT.
0 | All runtimes use ANSI_FIXED_FONT for the standard font.
1 | All runtimes use SYSTEM_FIXED_FONT for the standard font.
2 | All runtimes use OEM_FIXED_FONT for the standard font.

If this variable has not been set, or has an invalid value, it will default to -1.

Parent topic: Configuration Variables


STOP_RUN_ROLLBACK

When this variable is set to 1 (on, true, yes), the system performs an implied ROLLBACK rather than a COMMIT after a STOP RUN.

With a 0 (off, false, no) setting for this variable, the system performs an implied COMMIT after a STOP RUN. The default value for this variable is 0.

Parent topic: Configuration Variables


STRENGTHEN_LOCKS

Use this configuration variable when using some file systems that do not support READ LOCKS. If set to TRUE (ON, YES, 1), these file systems upgrade a READ LOCK to a WRITE LOCK. This causes ALLOWING READERS to be equivalent to EXCLUSIVE. Currently, only CISAM, Btrieve and Acu4GL for Oracle use this.

Parent topic: Configuration Variables


STRIP_TRAILING_SPACES

This variable provides an alternate method for determining which LINE SEQUENTIAL files will have trailing spaces removed from records written to them. At the time a LINE SEQUENTIAL file is opened, the value of this variable is examined. If this variable is 1 (on, true, yes), then automatic space suppression is applied to this file.

Otherwise, the file is processed according to the normal rules, as described in Sequential Files. The default value for this variable is 0 (off, false, no).

Note that a related configuration variable is the EXTFH_KEEP_TRAILING_SPACES variable.

Parent topic: Configuration Variables


SWITCH_PERIOD

This variable helps determine how frequently threads switch control. When a thread executes SWITCH_PERIOD number of selected operations, the threads switch control. The selected operations are generally comparisons. Comparison operations are used to cause compute-bound threads to switch.

Setting the value of SWITCH_PERIOD lower will increase the overhead spent switching threads, but increase the uniformity of thread execution. Setting the value very low can significantly hurt performance. The default value is 100.

Parent topic: Configuration Variables


SYSINTR_NAME

This variable defines the location of the SYSINTR file that may be used with HP e3000 emulation software. This variable must be specified with HFS syntax and set to the full path of the SYSINTR file. For example:

SYSINTR_NAME /opt/mpux/etc/sysintr.txt
Parent topic: Configuration Variables


SYSPUNCH

This configuration variable applies only when using DOSVSCOBOL mode when a DISPLAY is to SYSPUNCH. Use it to specify the name of the file where you want to write the data. If not specified, the default syspunch.txt is used.

Parent topic: Configuration Variables


TC_AUTO_UPDATE_FAILED_MESSAGE

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. If the thin client automatic update process fails for any reason, a message box may appear informing the user of the failure. The TC_AUTO_UPDATE_FAILED_MESSAGE configuration variable lets you specify the text in this message box. Its default value is

ACUCOBOL-GT Thin Client: Automatic update was unsuccessful

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_AUTO_UPDATE_FAILED_TITLE

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. If the thin client automatic update process fails for any reason, a message box may appear informing the user of the failure. The TC_AUTO_UPDATE_FAILED_TITLE configuration variable lets you set the title bar text for this message box. Its default value is

ACUCOBOL-GT Thin Client

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process..

Parent topic: Configuration Variables


TC_AUTO_UPDATE_NOTIFY_FAIL thin client

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. If the automatic update process fails for any reason, a message box may appear informing the user of the failure. If you do not want the thin client to inform the user that the automatic update has failed, set the TC_AUTO_UPDATE_NOTIFY_FAIL configuration variable to false (0, off, no). The default value of this variable is true (1, on, yes).

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_AUTO_UPDATE_QUERY

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. When an event triggers the update process, the thin client displays a message box informing the user that an update is required. The default setting of 1 (on, true, yes) for the TC_AUTO_UPDATE_QUERY configuration variable enables the display of that message box. Setting this variable to 0 (off, false, no) prevents the message box from appearing.

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_AUTO_UPDATE_QUERY_MESSAGE

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. When an event triggers the update process, the thin client displays a message box informing the user that an update is required. The value of the TC_AUTO_UPDATE_QUERY_MESSAGE configuration variable determines the message displayed in that message box. The default value of the variable depends on the circumstances that triggered the automatic update. For example, if the automatic update is initiated by a version or protocol number mismatch, the default message displayed is:

Incompatible server version
Server version: <srvvers>, client <clntvers>
Server protocol: <srvproto>, client <clntproto>
Press OK to automatically correct this problem

where <srvvers>, <clntvers>, <srvproto>, and <clntproto> are replaced by the server version, client version, server protocol number, and client protocol number, respectively.

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_AUTO_UPDATE_QUERY_TITLE

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. When an event triggers the update process, the thin client displays a message box informing the user that an update is required. You use the TC_AUTO_UPDATE_QUERY_TITLE configuration variable to specify the title bar text in that message box. The default value of this variable is

ACUCOBOL-GT Thin Client

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_AX_EVENT_LIST

In thin client deployments, this variable lets you control which events your program receives, giving you more control over the volume of network traffic. It must be set in the configuration file and cannot be changed programmatically with the SET verb. It contains the numeric value of a single .NET or ActiveX event type or a list of .NET or ActiveX event types separated by non-numeric characters like spaces or commas. Whether your program receives these events depends on the value of TC_EXCLUDE_EVENT_LIST. If its value is 0, then your program receives the events listed in TC_AX_EVENT_LIST. If TC_EXCLUDE_EVENT_LIST is set to 1, then the events listed in TC_AX_EVENT_LIST are not sent to your program.

Parent topic: Configuration Variables


TC_CHECK_ALIVE_INTERVAL

This variable allows you to set a time interval in seconds (a value between 1 and 32767) during which the server runtime checks for thin client activity. This activity can be either regular thin client user interaction or, if the user interface is inactive, two ping messages sent by the thin client during the defined interval. If no thin client activity of any kind occurs during a particular interval, the server runtime process exits. Setting this variable to 0 disables the client activity check feature. The default value is 300 (5 minutes).

For more information about the thin client, refer to the AcuConnect User's Guide.

Parent topic: Configuration Variables


TC_CHECK_INSTALLER_TIMESTAMP

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. The value of the TC_CHECK_INSTALLER_TIMESTAMP configuration variable determines whether the thin client compares the modification times of the installer files on the client and on the server. If this variable is set to 1 (on, true, yes) and the modification time of the client file is older than the time of the server file, the automatic update process is initiated. If the installer file does not exist on the client, then the comparison is made with the modification time of the thin client executable (acuthin) currently running. The default value for this variable is 0 (off, false, no).

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_CONTINUITY_WINDOW

If this configuration variable is set to 1 (on, true, yes), the Thin Client creates an invisible window after the next window is created by the COBOL application. This invisible window remains until the Thin Client shuts down. This variable must be set in the application's configuration file or in the initialization code of the application so that it is applied to the initial window created by the application.

The invisible window is needed because the GetMessage API routine behaves differently under Windows 2000 and Windows XP than in older versions of Windows. If an application has no open windows and it calls GetMessage, the focus is transferred to another application. Once transferred, the application cannot force the focus to return to the original application, even if it subsequently creates a window to receive the focus. This situation arises under the Thin Client if the COBOL application destroys all of its windows before creating a new one.

Since this variable applies to a very specific situation, the default setting for TC_CONTINUITY_WINDOW is 0 (off, false, no). You must set it explicitly if you want to use this feature.

For more information about the thin client, refer to the AcuConnect User's Guide.

Parent topic: Configuration Variables


TC_CONTROL_SYNC_LEVEL

This variable determines which VALUE data items in a Screen Section are updated when a BEFORE, AFTER or EXCEPTION procedure executes. (This variable only affects BEFORE, AFTER and EXCEPTION procedures. The values of all variables are made current anytime an ACCEPT terminates.) The possible values for TC_CONTROL_SYNC_LEVEL are:

1 | (default) Only the VALUE data item associated with the current field is updated when its AFTER or EXCEPTION procedure executes.
2 | Only the VALUE data item associated with the current field is updated when its BEFORE, AFTER or EXCEPTION procedure executes.
3 | All VALUE data items are updated when executing any BEFORE, AFTER or EXCEPTION procedure.

For best performance, Acucorp recommends leaving this variable at its default setting of "1" unless that causes your program to perform incorrectly. In which case, you can increase the setting of TC_CONTROL_SYNC_LEVEL to 2 or 3 to adjust for problems in the application behavior.

Note: Alternatively, you can directly INQUIRE the value of a control in an embedded procedure. This allows you to tune application performance more precisely than TC_CONTROL_SYNC_LEVEL will allow.

For more information about the thin client, refer to the AcuConnect User's Guide.

Parent topic: Configuration Variables


TC_DELAY_ACTIVATE

This variable determines precisely when the thin client sends CMD-ACTIVATE events to the server. Under the default setting of 1 (on, true, yes), the client delays sending the event until after the Windows notification routine receiving the event has completed. However, ActiveX events are never delayed. The alternate setting of 0 (off, false, no) sends the event to the server immediately when it is generated on the client.

Acucorp recommends leaving this variable at its default setting because the Windows API occasionally alters actions taken by the program when they occur within the scope of an activation notification. (For example, Windows will sometimes override a set focus call.) Delaying the COBOL program's response to the activation until after the Windows notification routine is complete avoids these alterations.

If you experience an unexplained difference in window activation when running under the thin client, try setting this variable to 0. If this produces the desired behavior, the handling of the CMD-ACTIVATE events by the program is unusual and may not be performing as intended. For example, the EVENT procedure that handles the CMD-ACTIVATE event may be destroying an unrelated window instead of transferring control to the window issuing the CMD-ACTIVATE event.

For more information about the thin client, refer to the AcuConnect User's Guide.

Parent topic: Configuration Variables


TC_DELAY_PRE_EVENT_OPS

This configuration variable applies only to the ACUCOBOL-GT Thin Client. Using this variable, you can direct the thin client to buffer some requests received from the server and process them later. When you set this variable to 1, the thin client buffers the requests received between the time that the client sends an event to the server and the time that the server informs the client that it has started the related event procedure. The events are processed only after the event procedure starts in order to prevent the thin client from processing requests that generate more events before the first event procedure has started. The default value of TC_DELAY_PRE_EVENT_OPS is 0.

The buffering behavior described for this configuration variable was introduced as the default behavior in Version 6.1. Beginning with Version 7.2, the buffering behavior is turned off by default.

Parent topic: Configuration Variables


TC_DISABLE_AUTO_UPDATE

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. You can disable the automatic update process by setting the TC_DISABLE_AUTO_UPDATE configuration variable to 1 (on, true, yes). The default value of this variable is 0 (off, false, no).

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_DISABLE_SERVER_LOG

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. If the thin client automatic update process fails for any reason, a log file may be created on the server. This file contains a log of the update operations and details about the failure. To prevent the creation of this log file, set the TC_DISABLE_SERVER_LOG configuration variable to true (1, on, yes). The default value of this variable is false (0, off, no).

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_DOWNLOAD_CANCEL_MESSAGE

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. During the automatic update installer file download process, a progress dialog appears. You can cancel the download at any time from this dialog box. Use the TC_DOWNLOAD_CANCEL_MESSAGE configuration variable to specify the message that appears when the download is cancelled. The default value for this variable is

Please wait while the download is being cancelled . . .

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_DOWNLOAD_DESCRIPTION

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. During the automatic update installer file download process, a progress dialog appears. You use the TC_DOWNLOAD_DESCRIPTION configuration variable to specify the text that appears in the middle of the download progress dialog. Its default value is

Downloading installation file. . .

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_DOWNLOAD_DIALOG

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. During the automatic update installer file download process, a progress dialog appears. The default value of 1 (on, true, yes) for the TC_DOWNLOAD_DIALOG configuration variable allows the appearance of this dialog box. If you set this variable to 0 (off, false, no), the progress dialog does not appear.

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_DOWNLOAD_DIALOG_TITLE

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. During the automatic update installer file download process, a progress dialog appears. The TC_DOWNLOAD_DIALOG_TITLE configuration variable is used to specify the title bar text in this dialog box. The default value of this variable is

ACUCOBOL-GT Thin Client Automatic Update

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_EVENT_LIST

This configuration variable lets you control which events your program receives, giving you more control over the rate of network traffic. It must be set in the configuration file and cannot be changed programmatically with the SET verb. It contains the numeric value of a single event type or a list of event types separated by non-numeric characters like spaces or commas. Whether your program receives these events depends on the value of TC_EXCLUDE_EVENT_LIST. If its value is 0, then your program receives the events listed in TC_EVENT_LIST. If TC_EXCLUDE_EVENT_LIST is set to 1, the events listed in TC_EVENT_LIST are not sent to your program.

Parent topic: Configuration Variables


TC_EXCLUDE_EVENT_LIST

The value of this variable determines whether the events listed in TC_AX_EVENT_LIST and TC_EVENT_LIST are sent to your program. A value of 1 means the specified events are not sent to your program. The default value is 0.

Parent topic: Configuration Variables


TC_INSTALLER_ARGS

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. The thin client uses the value of the TC_INSTALLER_ARGS configuration variable as the command-line options passed to the installer executable. For example, if you want msiexec.exe to log all of its operations to a file named msi.log, then you could set TC_INSTALLER_ARGS to /log msi.log. TC_INSTALLER_ARGS has no default value.

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_INSTALLER_CLIENT_FILE

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. You use the TC_INSTALLER_CLIENT_FILE configuration variable to specify the path and file name of the installer file that you want to create on the client. The default value of this variable is

<APPDATA>\ACUCOBOL-GT\<installer_server_filename>

where <APPDATA> is a special directory name for C:\Documents and Settings\<user>\Application Data and <installer_server_filename> is the file name specified in the TC_INSTALLER_SERVER_FILE configuration variable.

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_INSTALLER_RUN_ASYNC

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. You use the TC_INSTALLER_RUN_ASYNC configuration variable when you want to prevent the thin client from restarting after an automatic update or when your installer file handles the automatic update process to completion. When you set this variable to 1 (on, true, yes), the thin client starts the installer process asynchronously and then exits immediately. It does not wait for the automatic update process to complete and does not restart the application. The default value is 0 (off, false, no).

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_INSTALLER_SERVER_FILE

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. You set the TC_INSTALLER_SERVER_FILE configuration variable to the path and file name of the server installer file. Its default value is

<runtime_path>/acuthin.msi

where <runtime_path> is the directory that contains the runcbl runtime executable.

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_INSTALLER_TARGET_DIR

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. You use the TC_INSTALLER_TARGET_DIR configuration variable to specify the location where you want the updated thin client to be installed. This variable has no default value.

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_INSTALLER_UI_LEVEL

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. The keywords or numeric values in the TC_INSTALLER_UI_LEVEL configuration variable control the Windows installer interface. Set TC_INSTALLER_UI_LEVEL to NONE or 0 if you do not want the Windows installer to display a user interface. Set this variable to UNATTENDED or 1 if you want the Windows installer to display informational and progress messages but to execute unattended. Set the variable to INTERACTIVE, DEFAULT, or 2 if you want the Windows installer to prompt for and accept user input for the installation process. Set the variable to REDUCED or 3 if you want to use a reduced user interface.

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_MAP_FILE

In thin client deployments, set this variable to point to the character map file that defines the mapping of international characters between client and server systems. See International Character Handling in the AcuConnect User's Guide for more information.

Parent topic: Configuration Variables


TC_NESTED_AX_EVENTS

This variable determines how thin client handles nested ActiveX events. Because thin client processes Windows messages while waiting for responses from the server, it is possible for new ActiveX events to be sent while still waiting for an earlier event procedure to return, causing event procedures to be nested within event procedures. Because nested event procedures can cause unpredictable results, including memory access violations (MAVs), this variable is set to 0 (off, false, no) by default. If you want to enable it, set it to 1 (on, true, yes).

Parent topic: Configuration Variables


TC_QUIT_MODE

This variable lets you control how your COBOL application shuts down when no client activity occurs during the interval defined by TC_CHECK_ALIVE_INTERVAL. Setting TC_QUIT_MODE to -1 (the default value) shuts your program down according to the value chosen for the QUIT_MODE configuration variable. If you set this variable to 0, the runtime stops the program immediately.

When this variable is set to a value greater than 0 (up to 32767), your application has a program-controlled exit. When the runtime determines that the thin client is no longer responding (no user interaction and no pings during TC_CHECK_ALIVE_INTERVAL), the MSG-MENU-INPUT event is sent to the program's main window and EVENT-DATA-2 contains the value defined by TC_QUIT_MODE. Your program can detect this in the main window's event procedure and you can perform whatever code you desire. At this point there is no connection to the thin client, so user interface operations may not be performed. You must end your shutdown code with STOP RUN to terminate the runtime.

For more information about the thin client, refer to the AcuConnect User's Guide.

Parent topic: Configuration Variables


TC_REQUIRES_BUILD_NUMBER

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. When the thin client executes, it compares its build number with the value of the TC_REQUIRES_BUILD_NUMBER configuration variable. If the value of this variable does not match the client's build number, the automatic update process is initiated. Set this variable to the thin client build number required by the application. The default value of this variable is 0 (off, false, no).

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_RESTRICT_AX_EVENTS

This variable controls whether the application will ignore ActiveX events between ACCEPT statements (the termination of one ACCEPT and the beginning of the next). Setting this variable to 1 (on, true, yes) enables this behavior. The default value is "0" (off, false, no).

Ordinarily, the thin client runtime suspends all ActiveX events when the application is not processing an ACCEPT statement. However, some ActiveX controls do not support the ability to suspend and resume events when an application is not processing an ACCEPT statement. As a result, in a thin client environment, an event procedure may be run unexpectedly during a CREATE, DISPLAY, MODIFY, INQUIRE, or any other operation that waits for results from the thin client. Setting TC_RESTRICT_AX_EVENTS provides some control over these ActiveX events.

To determine if a particular ActiveX control supports suspending and resuming events, check the control's documentation or ask the control vendor. Note that the control must implement the IOleControl::FreezeEvents() function.

See Using ActiveX Controls and COM Objects in A Guide to Interoperating with ACUCOBOL-GT and Installing ActiveX Files in the AcuConnect User's Guide for more information about ActiveX control handling.

Parent topic: Configuration Variables


TC_SERVER_LOG_FILE log

This configuration variable applies only to the ACUCOBOL-GT Thin Client automatic update feature. If the thin client automatic update process fails for any reason, a log file may be created on the server. This file contains a log of the update operations and details about the failure. The TC_SERVER_LOG_FILE configuration variable can be used to configure the location and name of that file. The name can optionally include the hostname of the client machine and the process ID of the server runtime that was managing the automatic update at the time of the failure.

By default, this file is named autoupdate.%c.%p.log, where %c is replaced by the client hostname and %p is replaced by the process ID of the server runtime. The default location is the working directory specified in the alias on the server. Note that the directory must exist at the time of the failure for the log file to be created.

See Thin Client Automatic Update in the AcuConnect User's Guide for detailed information about the thin client automatic update process.

Parent topic: Configuration Variables


TC_SERVER_TIMEOUT

This variable lets you determine how many seconds (from 0 to 32767) the thin client waits for a response from the server. If the thin client receives no response from the server in the specified time period, the following message box appears:

   The remote host is not responding.
   Press OK to close this program.
   Press Cancel to wait another %s seconds.

where "%s" is the value of TC_SERVER_TIMEOUT. The default value is 20.

For more information about the thin client, refer to the AcuConnect User's Guide.

Parent topic: Configuration Variables


TC_TV_SELCHANGING

This variable is designed for thin client applications. It provides some control over when the runtime generates Msg-Tv-Selchanging events for tree view controls. Because most applications that use tree view controls do not process Msg-Tv-Selchanging events, the thin client suppresses its generation in some cases. This improves both performance and stability. TC_TV_SELCHANGING recognizes the following values:

0 | never generate Msg-Tv-Selchanging events
1 | (default) generate Msg-Tv-Selchanging events when the selection is about to change due to the user using the mouse or the keyboard to change to current selection
2 | always generate Msg-Tv-Selchanging events

The default setting of 1 allows you to detect user-initiated events in your program while filtering out many other causes of the event.

If you know your program doesn't handle any Msg-Tv-Selchanging events, you can set TC_TV_SELCHANGING to 0 to entirely inhibit generation of the event. This can slightly improve performance.

If TC_TV_SELCHANGING is set to 1 and your program experiences odd behavior with tree view controls under the thin client, you can try setting the variable to 2 to generate all Msg-Tv-Selchanging events. This setting can help you determine whether a Msg-Tv-Selchanging event is the cause of the odd behavior. If this setting eliminates the odd behavior, it indicates that your program relies on Msg-Tv-Selchanging events in cases other than the user initiating a selection change.

For more information about the thin client, refer to the AcuConnect User's Guide.

Parent topic: Configuration Variables


TEMP_DIR

This variable lets you specify where certain temporary files used by the ASSIGN clause will be created on VAX/VMS systems. These temporary files are created when you use the %TMP% option for assigning a file to a simulated pipe with -P. See File Name Interpretation in the ACUCOBOL-GT User's Guide for more information.

Parent topic: Configuration Variables
Parent topic: Configuration Variables


TEST_CHAR

This configuration variable specifies what to return in the TERMINAL_INFO structure for the HAS_GRAPHICAL_INTERFACE configuration variable.

If set to TRUE (ON, YES, 1), then HAS_GRAPHICAL_INTERFACE is always N. If set to FALSE (OFF, NO, 0) the value is based on the type of system (Y for Windows graphical, N otherwise).

Parent topic: Configuration Variables


TEMPORARY_CONTROLS

By default, graphical controls are created as permanent controls. By setting this configuration variable to 1 (on, true, yes), you cause controls to be created temporary by default. This is useful when you are converting older programs that assume that a screen update will overwrite any existing screen data. You can make individual controls permanent or temporary explicitly by using the PERMANENT and TEMPORARY styles. See Global Styles in ACUCOBOL-GT User Interface Programming for more information.

Parent topic: Configuration Variables


TEXT

This configuration variable controls the text of runtime messages. The ACUCOBOL-GT runtime system displays a number of informational and warning messages to the end user. Several of these messages can be customized via entries in the configuration file.

For each message that you want to change, place the word "TEXT" in your configuration file, followed by a message number from the list below, an "=" sign, and then the text you would like to use.

For example, the standard message #1 is "press return". You can change that message to "push enter" by placing this line in your configuration file:

TEXT  1=push enter
Note: There is no space before or after the equals sign, and the new message is not in quotes.

These are the standard runtime messages and their numbers:

Message Number | Text
1 | Press return
2 | Number required
3 | Entry required
4 | Field must be filled with data
5 | Too many hot keys active
6 | Program missing or inaccessible
7 | Not a COBOL program
8 | Corrupted program
9 | Inadequate memory available
10 | Unsupported version of object code
11 | Program already in use
12 | Too many external segments
13 | Large-model program not supported
18 | Please end this application first
19 Japanese objects not supported

This message is displayed when a standard runtime attempts to execute an object that contains Japanese COBOL extensions.

20 Too many lines

This message is displayed when the user exceeds the MAX-LINES setting for a multiline entry field.

21 License manager (acushare) not running

This message is displayed when acushare is not running and the runtime is unable to start it (e.g., because it is not in the path).

22 Data must fit this format:

This message is displayed when the user enters illegal data when using the NUMERIC_VALIDATION configuration option.

23 | &Ok
24 | &Yes
25 | &No
26 &Cancel

Messages 23, 24, 25, and 26 are used by character-based versions for the message box facility.

28 Unable to access the file "%s" due to heavy usage by other users. Would you like to continue waiting for it?

(See the configuration variable WAIT_FOR_FILE_ACCESS for more information about this message.)

30 | Connection refused - perhaps AcuConnect is not running
31 Please enter a value between %ld and %ld

This message is displayed when the user enters a value outside of the allowed range for an entry-field (see MIN-VAL/MAX-VAL in the entry-field reference). The first %ld is replaced by the MIN-VAL setting. The second %ld is replaced by the MAX-VAL setting. You may omit these if you desire. Note that the second character in the sequence is the letter l, and not the number one (1).

32 | Program contains object code for a different processor
33 | Incorrect serial number
34 | Connection refused - user count exceeded on remote server
35 | License error
36 The remote host is not responding.\nPress OK to close this program.\nPress Cancel to wait another %s seconds.

This message is displayed when Thin Client does not receive a response from the server in the number of seconds specified in TC_SERVER_TIMEOUT.

Use "\n" to separate lines and %s to substitute the number of seconds (value of TC_SERVER_TIMEOUT). If you don't want to display the number of seconds, omit the %s.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


THAI

This configuration variable is used by the run time to detect the Thai character set automatically. Set it to TRUE (ON, YES, 1) to detect the Thai character set. The default is FALSE (OFF, NO, 0).

Parent topic: Configuration Variables


TRACE_STYLE

This variable allows you to customize the format of error and trace messages. You can set it to the sum of one or more of the following values:

0 | The default. No ACU prefix, process ID, time, or date is included in the trace output.
1 | Adds ACU prefix to each line of the trace output.
2 | Adds the process ID.
4 | Adds the time.
8 | Adds the microseconds; has an effect only if 4 is also specified.
16 | Adds the date.

You can also set TRACE_STYLE to one of the following keywords, which correspond to the indicated numerical values:

NONE | 0
TIMESTAMP | 12 -- The TIMESTAMP style is 4+8; it outputs timestamps with microseconds.
APPSERVER | 23 -- The APPSERVER style is 1+2+4+16; at the beginning of each line of the error file it outputs "ACU" followed by the date, the process ID, and the time without microseconds.
Parent topic: Configuration Variables


TRANSLATE_TO_ANSI

This variable has meaning only on graphical systems such as Windows. It is used only if you:

  • use the graphical system's font to accept data, and
  • store your data using the OEM character set. (For example, Vision files may contain OEM characters if they were created with a DOS runtime.)

Set TRANSLATE_TO_ANSI to 1 (ON, TRUE, YES) to turn on a character set translator. Then, if you use the graphical system's font for accepting data, the runtime will translate from one character set to the other. Data that is accepted from the screen is translated into the OEM character set before it is stored on disk. Data stored in the OEM character set is translated to the ANSI character set before it is displayed on screen. This process is also applicable to printing through the Windows print spooler when the printer uses an ANSI font.

The default setting for this variable is TRANSLATE_TO_ANSI 0 (OFF, FALSE, NO), which turns off the translation process.

This variable can be set from within a COBOL program with the SET verb. For example:

SET ENVIRONMENT "TRANSLATE_TO_ANSI" TO "YES".

Note on ANSI and OEM characters:

The ANSI and OEM representations of the following standard English characters are identical:

ABCDEFGHIJKLMNOPQRSTUVWXYZ
Abcdefghijklmnopqrstuvwxyz
0123456789 <space>
! " # $ % & ' ( ) * + , - . / :
; < = > ? @ [ \ ] ^ _ ' { | }

Only the representations of accented vowels and other special or non-English characters are different.

Parent topic: Configuration Variables
Related reference
COBOL_CHARACTER_SET


TREE_ROOT_SPACE

This variable controls the number of screen columns between the left edge of the Tree-View control and the root level text. TREE_ROOT_SPACE is used only with the LINES-AT-ROOT property. If LINES-AT-ROOT is not specified, the root level item text will be displayed starting at the leftmost screen column inside the tree-view control.

For example, if TREE_ROOT_SPACE is set to 5, there will be 5 screen columns before the text of each root level item. The screen column where the root level line will be drawn is determined by this formula:

root level-line = (TREE_ROOT_SPACE - 1)/2 + 1

Taking off from the previous example, if TREE_ROOT_SPACE=5, the root level line will be drawn in screen column 3, counting from the left edge of the Tree-View control.

This has the effect of centering the vertical root level line in the space between the left edge of the Tree-View control and the last root level text.

The "+" or "-" button is displayed in the column to the right of this vertical line if the TREE_ROOT_SPACE is set to a value greater than or equal to 2. If the TREE_ROOT_SPACE is set to 1, the "+" or "-" button appears in the first screen column of the Tree-View control. The default value of TREE_ROOT_SPACE is 2.

Parent topic: Configuration Variables


TREE_TAB_SIZE

This configuration variable is one of two variables that affect the appearance of character-based Tree-View controls. TREE_TAB_SIZE controls the number of screen columns between each level in the visual representation of the tree. For example, if TREE_TAB_SIZE is set to 10, the horizontal distance between the first character of text in the first level and the first character of text in the succeeding levels of the tree will be 10 screen columns each. The default value of TREE_TAB_SIZE is 3.

See TREE_ROOT_SPACE variable.

Parent topic: Configuration Variables


TRX_HOLDS_LOCKS

This configuration variable allows you to control which locks are released at the end of a transaction. If this variable is set to 1 (on, true, yes), then locks set using the READ statement that are not specifically released or replaced by extended transaction locks (for example, by a REWRITE) are held at the end of the transaction. Locks are released during a transaction by any operation that would ordinarily release them, unless those locks were replaced by extended transaction locks.

If TRX_HOLDS_LOCKS is set to the default, 0 (off, false, no), then locks are released at the end of a transaction, and the UNLOCK verb has no effect during a transaction.

Parent topic: Configuration Variables


TV_EDITLABELS

This variable enables the user to change the text of a tree-view item. When this variable is set to "1" (on, true, yes) you can change the value of the tree-view item by clicking it with the mouse (just like with Windows Explorer). When the variable is set to "0" (off, false, no) text changes are not allowed. The default value of TV_EDITLABELS is "0".

To keep track of the changes, two additional messages are generated from the tree-view to the COBOL program: MSG_TV_BEGINEDITLABEL and MSG_TV_ENDEDITLABEL.

Parent topic: Configuration Variables


UPPER_LOWER_MAP

This variable allows you to define which upper-case characters correspond to which lower-case characters, for characters outside of the standard ASCII character set (those whose underlying decimal values are 128 or larger).

You might find this useful if you are experiencing problems with the UPPER or LOWER option of the ACCEPT statement when non-standard characters are entered (such as an "e" with an accent above it). The ACUCOBOL-GT runtime system relies heavily on C library routines to handle conversions between upper-case and lower-case characters. On many machines, these routines do not handle characters outside of the standard ASCII character set correctly.

To specify corresponding characters, use UPPER_LOWER_MAP followed by pairs of characters, where the first character is the upper-case version and the second character is the lower-case version. Separate the characters by a space. Describe the characters either by typing them at the keyboard or by entering the decimal value that represents them.

For example, on a standard IBM PC, the video card represents an upper-case "U" with an umlaut (Ü) as character 154, and the lower-case "u" with an umlaut (ü) as 129. The upper-case "E" with an accent character is 144 (É) and the lower-case "e" with an accent is 130 (é). To express this in the configuration file, you would add the following line:

UPPER_LOWER_MAP  154 129 144 130

This could be extended to include all of the character pairs available.

By default, Windows systems come with the UPPER_LOWER_MAP defined to be the character pairs available on the standard video cards produced by IBM. Note that using code pages can change this, so the default may not work in all cases for these machines. For other machines, the default is empty (which means that C library routines are used for conversion). If you experience difficulties, UPPER_LOWER_MAP allows you to define a mapping that reflects your hardware configuration.

Only characters whose decimal values are 128 or greater may be mapped by this technique.

Note: This variable cannot be read with the ACCEPT FROM ENVIRONMENT statement.
Parent topic: Configuration Variables


USE_BASE_HOSTNAME

This configuration variable specifies whether to remove the domain-specific part of a URL used when connecting to a server. So for example, www.myhost.com would just become www. This configuration variable is used by various clients, including when connecting to a AcuServer or AcuConnect server. Set it to TRUE (ON, YES, 1), to remove the domain-specific part of the URL. Set it to FALSE (OFF, NO, 0) to use the full domain name. The default is FALSE.

Parent topic: Configuration Variables


USE_CICS

Set this variable to indicate to the runtime that the program makes calls to the CICS interface. When USE_CICS is set to 1 (on, true, yes), the runtime attempts to pass calls to functions that begin with the string "CICS" to the CICS interface. If the named routine does not exist, the runtime uses the normal search sequence to find a matching function. When USE_CICS is set to the default value of 0 (off, false, no), the runtime does not perform any special handling.

Parent topic: Configuration Variables


USE_EXECUTABLE_MEMORY

When set to TRUE, this variable enables a COBOL program compiled for Native Code (-n compiler option) to run on a UNIX or Windows system that protects against executable code in normal memory. (On Windows, this is called Data Execution Protection (DEP).) The default value is TRUE.

Note: Prior to extend 10.0, the default value was FALSE.
Parent topic: Configuration Variables


USE_EXTSM

Set this variable to indicate that the runtime should use an external sort module. When USE_EXTSM is set to 1 (on, true, yes), the runtime uses the linked-in EXTSM function to perform the SORT or MERGE operation. When USE_EXTSM is set to the default value of 0 (off, false, no), the runtime does not perform any special handling for SORT and MERGE verbs.

Parent topic: Configuration Variables


USE_LARGE_FILE_API

Note: As of extend 10.1.0, this configuration variable is no longer available - large file support is permanently enabled.
Parent topic: Configuration Variables


USE_LOCAL_SERVER

This variable is used by the runtime and Web Runtime to specify whether or not you want to run client applications on the same machine as an AcuServer file server. When USE_LOCAL_SERVER is set to the default of 0 (off, false, no), AcuServer is bypassed when accessing local files that have remote name notation. The remote name is stripped off and the file I/O operation is handled by the runtime or Web Runtime. Set this variable to 1 (on true, yes) to use AcuServer to access local files that have remote name notation. This variable only works with AcuServer client runtimes and AcuServer client Web Runtimes.

Parent topic: Configuration Variables


USE_MPE_REDIRECTION

This configuration variable applies only when running in HP COBOL compatibility mode (with the -Cp compiler option) on machines that support the MPE environment. With the use of the USE_MPE_REDIRECTION configuration variable, input for an ACCEPT statement is read from the file specified by STDIN=, and output from a DISPLAY statement is written to the file specified by STDLIST= on the RUN command line. To enable this behavior, set USE_MPE_REDIRECTION to 1 (on, true, yes). The default value is 0 (off, false, no). In addition, when this variable is set, no terminal manager escape sequences are written to the redirected output file.

Parent topic: Configuration Variables


USE_MQSERIES

Use this variable to indicate to the runtime that the program makes calls to WebSphere MQ (formerly MQSeries). When USE_MQSERIES is set to 1 (on, true, yes), the runtime attempts to pass calls to functions that begin with the string "MQ" to the WebSphere MQ interface. If the named routine does not exit, the runtime uses the normal search sequence to find a matching function. When USE_MQSERIES is set to the default value of 0 (off, false, no), the runtime does not perform any special handling.

Parent topic: Configuration Variables


USE_SYSTEM_QSORT

This variable instructs the runtime SORT routine to use the system qsort() function, rather than the built-in sort function. Set USE_SYSTEM_QSORT to 1 if you want to use the system qsort() function. The default value is 0 and results in the use of the built-in sort function.

Some systems have qsort() functions that perform better than the built-in function. Consider experimenting with this variable's settings to determine if this option yields better performance on your system. Pay particular attention to the number of comparisons done during the sort, which can be seen in the runtime trace output.

Parent topic: Configuration Variables


USE_UNICODE_FONTS

When measuring fonts in order to ascertain the size of a control, the result of the default size calculation can differ between fonts that contain Unicode characters and those that do not. This difference in measurement can affect the displaying of the controls on a user interface.

If you are using non-Unicode fonts in your controls, you can leave the new USE_UNICODE_FONTS configuration variable at its default of FALSE.

If you are using Unicode fonts in your controls, set USE_UNICODE_FONTS to TRUE, so that the measurement is carried out using Unicode font functions; this will ensure that an accurate measurement of the font is calculated, and the control will be correctly sized.

Tip: In some circumstances when USE_UNICODE_FONTS is set to TRUE, the runtime will test every character in the font for its size to get a real maximum width. Because Unicode fonts can contain a large number of characters (up to 65,000), it could mean that calling W$FONT to create a font could take more time than it should; if that is the case, set USE_UNICODE_FONTS to FALSE, so that only ANSI character widths are calculated. It should ensure that the font is created quicker, but you may find that controls created in this way may not be large enough to display the full data item attached to it, and some truncation may occur.
Parent topic: Configuration Variables


USE_WINSYSFILES

This variable specifies whether the runtime should recognize calls to modules with the extensions .drv and .ocx as well as those with the extension dll. By default, it is set to 1 (on, true, yes).

For backwards compatibility, you can turn this feature off by setting it to 0 (off, false, no). Then, only calls to .dll files are supported.

Parent topic: Configuration Variables


V_BASENAME_TRANSLATION

This variable allows you to tell Vision whether to include full path information in the filename. By default, only the base name is included (the filename with no extension and no path information). Retaining the path information can be helpful in instances where Vision files of the same name are stored in different locations and you want to map one of the segments from one directory to a new location.

When V_BASENAME_TRANSLATION is set to 0 (off, false, no), Vision uses the entire path of the file. When it is set to 1 (on, true, yes), the default setting, Vision uses only the base name.

The setting of V_BASENAME_TRANSLATION affects the behavior of three configuration variables that handle Vision filename translation: filename, filename_DATA_FMT, and filename_INDEX_FMT. The following illustrates how the configuration variables interact.

For the file /user/data/record1.vix:

  • If V_BASENAME_TRANSLATION is set to on (the default), filename, filename_INDEX_FMT, and filename_DATA_FMT use "RECORD1_VIX" as the base name.
  • If V_BASENAME_TRANSLATION is set to off, filename, filename_INDEX_FMT, and filename_DATA_FMT use "_USER_DATA_RECORD1_VIX" as the base name (underscores replace instances of "/" and ".").

For a description of filename, filename_INDEX_FMT, and filename_DATA_FMT, see their respective entries in this appendix.

Parent topic: Configuration Variables


V_BUFFERS

This variable sets the number of indexed block buffers to allocate. These buffers are used to improve the performance of indexed files. Each buffer is 512 bytes plus some overhead. Increasing the number of buffers can improve file performance. Decreasing the number conserves memory. The value of V_BUFFERS has no effect on versions of ACUCOBOL-GT that do not use Vision files. The value of V_BUFFERS can range from zero (no buffering) to 2097152. The default value is 64.

Parent topic: Configuration Variables
Parent topic: Configuration Variables


V_BUFFER_DATA

The setting of this variable determines whether or not Vision indexed file data blocks (as opposed to key blocks) will be held in the memory-resident disk buffers. When it is set to 1 (on, true, yes), both data blocks and key blocks will use the buffers. When set to 0 (off, false, no), only key blocks will use the buffers. Setting this value to 1 will usually improve performance unless very few buffers are being used.

Note: Holding data blocks in the buffers slightly increases the chances of losing data if a file opened for MASS_UPDATE is not closed properly (power failure, etc.). The default setting of this variable is 1.
Parent topic: Configuration Variables


V_BULK_MEMORY

Vision allocates a memory buffer for each file opened for bulk addition. The size of this buffer is controlled by the V_BULK_MEMORY configuration option. The default size of this buffer is 1 MB.

Note: The default size is fairly large because it is assumed that only a few files will be open for bulk addition on a system at any one time. If this buffer cannot be allocated, the OPEN fails with a status indicating inadequate memory.

To change the size of the allocated memory buffer to, for example, 500 KB, you would enter:

V_BULK_MEMORY = 500 KB
Parent topic: Configuration Variables


V_FORCE_OPEN

This variable allows you to force the runtime to open broken files that would normally cause an error 98. This means you can write COBOL programs to recover these files in ways that are not available with vutil. Set V_FORCE_OPEN to 1 (on, true, yes) to open the files. The default is 0 (off, false, no).

Note: When this variable is set to 1, make sure you do not also have the V_OPEN_STRICT variable set to 1 because the settings conflict.
Parent topic: Configuration Variables


V_INDEX_BLOCK_PERCENT

This configuration variable allows you to specify index pre-allocate and extension factors as a percentage of the factors applied to the data segment. In Vision 4, 5, or 6 files, the index data contained in the index segments is often much smaller than the record data contained in the data segments. As a result, a large pre-allocate or extension factor typically allocates many more index blocks than are needed. This can be undesirable, especially if disk space is tight.

Setting V_INDEX_BLOCK_PERCENT to a number less than 100 causes fewer index blocks than data blocks to be created. Setting the variable to a number greater than 100 causes more index blocks than data blocks to be created. The valid range for V_INDEX_BLOCK_PERCENT is one through 1000. If the value specified is less than one, it will be promoted to one. V_INDEX_BLOCK_PERCENT is set to 100 by default (the default pre-allocate and extension factors for a file).

For example, if a file has an extension factor of 10, setting V_INDEX_BLOCK_PERCENT to 50 causes 10 new data blocks and five new index blocks to be created the next time the file is extended. Setting V_INDEX_BLOCK_PERCENT to 200 causes 10 new data blocks and 20 new index blocks to be created the next time the file is extended.

Note: The number of blocks pre-allocated will never be larger than that which can fit in the initial data and index segments. If the pre-allocation value specified or calculated from V_INDEX_BLOCK_PERCENT is larger than the segment size, the pre-allocation amount is automatically reduced to the segment size.
Parent topic: Configuration Variables


V_INTERNAL_LOCKS

This configuration variable allows you to control whether the runtime enforces internal record or file locking. When V_INTERNAL_LOCKS is set to 0 (off, false, no), Vision tracks locks but does not enforce internal record or file locking. As a result, the runtime does not return a record or file locked condition for a record or file that was previously locked by the same run unit. When V_INTERNAL_LOCKS is set to the default of 1 (on, true, yes), internal record and file locking are enforced.

Note: The Windows operating system enforces a single lock per process on a region of a file. This means that if your program opens the same physical file as two different logical files and then tries to lock the same record in both "files", the second lock will fail (with an error 99) even if V_INTERNAL_LOCKS is set to 0. So V_INTERNAL_LOCKS 0 practically affects programs running on UNIX operating systems only.
Parent topic: Configuration Variables


V_LOCK_METHOD

This variable selects which locking method Vision will use to control simultaneous access to indexed files. It affects only the Vision file system, and only files directly accessed by the runtime (it does not apply to files accessed via AcuServer).

The default setting of 0 (zero) causes Vision to lock the first byte of the file for every access to the file (both reads and updates). This ensures that the process is not interfered with by another process.

Setting this variable to 1 causes Vision to lock the first byte of the file for all operations except random READs or READ NEXTs. These two operations proceed without the lock. Instead they perform some additional reads of the file, to ensure that they get consistent results. If they get inconsistent results, they are retried, this time locking the first byte as other operations do. This locking method is available for Vision Versions 3 and later.

Note: This variable must have the same setting for all the runtimes accessing a file, whether they are reading or writing to it. For example, if a runtime set with V_LOCK_METHOD=1 is reading from a file, any runtimes that are writing to that same file must also have V_LOCK_METHOD set to 1.

Lock method 1 can produce better performance on some machines. These machines fall into two categories:

  • Machines that take a long time to place a lock.
  • Machines that do not queue lock requests, and are very busy. In this case, some users typically get good performance, while others get poor performance.

Setting V_LOCK_METHOD to 1 might help improve performance with files of Vision Version 3 or later. For example, setting V_LOCK_METHOD to 1 can be helpful on some Windows networks. A peer-to-peer network of Windows 98 machines can exhibit problems reading Vision files when a process performs a tight read loop. The problem usually surfaces as either an error 30,33 or an unexpected error 99. This occurs because the runtime is unable to place a lock on the header of the file after 400 attempts over a 20-second period. For other networks, setting V_LOCK_METHOD to 1 can substantially reduce the number of lock requests made by the runtime and can often resolve these problems.

To get statistics about header locks, select Trace Files level "3" in the debugger (for example, TF 3). These statistics print on the runtime's error output each time a Vision file is closed. They cover the operations in that file since it was last opened. You can also view these statistics (without the full trace) by adding "256" to the lock method chosen (for example, setting V_LOCK_METHOD to "257" selects method "1" and prints statistics).

Setting the V_LOCK_METHOD variable to 2 enables "asynchronous reads" of Vision files. This option is intended to further reduce the number of file locks required to perform random READs and READ NEXTs.

The advantage of the "2" setting is that it is less likely to require retrying a READ with a lock when a file is undergoing heavy modification. With V_LOCK_METHOD 1, the READ is retried with a lock whenever it detects that the file has been updated in any way; with V_LOCK_METHOD 2, the READ is retried only when Vision encounters inconsistent data while traversing the index tree or reading the record data. This leads to less locks and therefore greater performance for machines with slow locking functions.

V_LOCK_METHOD 2 works only for files of Vision Version 4 and later. A fundamental requirement for the V_LOCK_METHOD 2 feature to work properly is that the operating system must provide atomic write operations. That is, if one process is writing to a file, another process will always see the contents of the file as it exists either before or after the write operation, never the intermediate contents as the write operation runs.

Some file systems do not provide atomic file operations, and for those environments, V_LOCK_METHOD 2 is not recommended. Use the vutil -wtest option to check the compatibility of the file system housing the Vision files that you will access using the V_LOCK_METHOD 2 configuration; see Testing for Vision File Locking Compatibility for more information.

CAUTION:
Using V_LOCK_METHOD 2 on a file system that does not provide atomic file operations will likely cause spurious file errors or file corruption.

If any process reading a particular file is using V_LOCK_METHOD 2, all other processes (runtimes) updating that file must be ACUCOBOL Version 5.0.0 or greater. This is because Version 5.0.0 contains changes that affect the way Vision updates the tree structure of its files. These changes allow for greater consistency of the tree from the viewpoint of an asynchronous reader. This requirement is not enforced by Vision, however, so it is important for the users to pay careful attention to the versions of programs accessing their files to avoid receiving erroneous data. Therefore, before enabling this option, make sure that all runtimes updating files on which asynchronous reads are to be performed (V_LOCK_METHOD 2) are Version 5.0.0 or later.

As with V_LOCK_METHOD 1, adding 256 to the value of the V_LOCK_METHOD setting causes statistics about header locks to be printed to the runtime's error output each time a Vision file is closed. So, setting V_LOCK_METHOD 258 selects method 2 and turns on the header lock statistics.

Parent topic: Configuration Variables
Related reference
Testing for Vision File Locking Compatibility


V_MARK_READ_CORRUPT

This variable allows you to configure Vision so that it does not mark a file as broken if it encounters a corruption during a read or start operation. The effect is that the user is allowed to retry the program. This may be useful when the error is spurious (for example due to a network caching glitch). If the user retries the program and once again receives a file-corrupt message, then the file should be rebuilt or recovered normally. To enable this option, set the configuration option V_MARK_READ_CORRUPT to 0 (off, false, no). The default setting is 1 (on, true, yes).

Parent topic: Configuration Variables


V_NO_ASYNC_CACHE_DATA

Set this configuration variable to 1 to indicate that no processes accessing any Vision files in use by this process are using V_LOCK_METHOD=2. The default value is 0.

Using V_BUFFER_DATA=1 with V_LOCK_METHOD=2 may cause file corruption, and so this variable was introduced as a way to protect users from inadvertently turning on V_LOCK_METHOD=2 when they already have V_BUFFER_DATA turned on. In order to have Vision buffer data blocks, V_BUFFER_DATA and V_NO_ASYNC_CACHE_DATA must be set to 1 and you must not be using V_LOCK_METHOD=2 with any process accessing those files.

Parent topic: Configuration Variables


V_OPEN_STRICT

By default, Vision allows OPEN INPUT on files that are marked as broken. This behavior is intended to make it easier to recover records from broken files. If you want to receive an error status when opening a file marked as broken for INPUT, set V_OPEN_STRICT to 1 (on, true, yes). The default setting of 0 (off, false, no) allows open input on broken files.

Note: When this variable is set to 1, make sure you do not also have the V_FORCE_OPEN variable set to 1 because the settings conflict.
Parent topic: Configuration Variables


V_READ_AHEAD

Setting this configuration variable to 0 (off, false, no) turns off Vision's read-ahead logic. This may improve performance in cases where highly random file processing is being used. The default value is 1 (on, true, yes).

Parent topic: Configuration Variables


V_SEG_SIZE

This configuration variable sets the maximum size of a Vision 4 or 5 file segment in bytes. The default value is 2,147,482,112 (i.e., 2GB – 1536), except on older HP/UX machines where it is 1,073,740,288 (i.e., 1GB – 1536) due to an operating system limitation. You may not use larger values, but you can set smaller ones. The default value is the maximum allowed. The value specified will automatically be rounded down to a multiple of the block size of the file being created. For example, if the default V_SEG_SIZE value is used and a file with a block size of 1024 is created, the segment size for that file will be 2,147,481,600 (i.e., 2GB – 2048).

Using a smaller value for the segment size can help if you do not have 2GB free on any disk or for testing purposes. The minimum value allowed is 81,920 bytes. To minimize the number of files created, you should set this value as high as possible.

The segment size of a file is set at file creation time and cannot be modified without recreating the file (i.e., using vutil –rebuild with a different V_SEG_SIZE setting). vutil uses this variable, but since it does not use a configuration file, this variable must be set in the environment.

Parent topic: Configuration Variables


V_STRIP_DOT_EXTENSION

The V_STRIP_DOT_EXTENSION variable determines whether or not Vision strips a trailing "dot extension" (.dat) from the logical name of a data file when generating file names for index and data segments (other than the first data segment). Setting this variable to 0 prevents the extension from being removed. For example, by default, the first index segment name for the logical file file.one is file.vix (which would conflict with the index segment of file.two). When V_STRIP_DOT_EXTENSION is set to 0 (off, false, no), the index segment name is file.one.vix. The default value for this variable is 1 (on, true, yes).

Note: The setting of this variable affects the behavior of four configuration variables: filename, filename_DATA_FMT, filename_INDEX_FMT, and filename_VERSION. See their respective entries in this appendix for details.
Parent topic: Configuration Variables


V_VERSION

This variable specifies the version number of new Vision files that are created. The default value is 6, which produces Vision files in the format of the current version (Version 6). The value 5 produces Version 5 files. Version 5 and 4 files are generated in a dual file format, with data records filed in one segment and overhead key information filed in another. The value 3 produces Version 3 files, in which data and keys are stored in a single file. Any value other than 3, 4 or 5 produces Version 6 files.

Parent topic: Configuration Variables


V23_GRAPHICS_CHARACTERS

Programs written for and executed with UNIX versions of the runtime up to and including Version 2.4.0 use hex values 1-8 to display line drawing characters on the screen. Runtimes after Version 2.4.0 use hex values offset by one (1). When older programs are used with runtimes released after Version 2.4.0, line drawing characters do not display as expected. To use the old values for line drawing characters, set this variable to 1 (on, true, yes).

If the variable is set to 0 (off, false, no) or is not set at all, the runtime will use the newer offset values. This variable works only for UNIX systems.

Parent topic: Configuration Variables


V24_SCREEN_SECTIONS

ACUCOBOL-GT releases earlier than 3.0 have a bug in the Screen Section where exiting the last field via an arrow causes that field's EXCEPTION procedure to trigger instead of its AFTER procedure. All other fields in the Screen Section triggered AFTER procedures.

Some code may rely on this issue. This issue was addressed in ECN-703, which changes the behavior so the AFTER procedure triggers instead of the EXCEPTION procedure.

This configuration variable accommodates that code. Set it to TRUE (ON, YES, 1) to simulate the behavior in release 2.4 and earlier, so exiting the last field via an arrow in the Screen Section triggers the field's EXCEPTION procedure. Set to FALSE (OFF, NO, 0) to use the behavior implemented in ECN-702 for release 3.0 and later.

Because this behavior is considered a bug, using the -C24 option to simulate 2.4 semantics does not trigger this enhancement. You must use this configuration variable.

Note: In release 3.1.2, V24_SCREEN_SECTIONS also enables ECN-664. This ECN corrects a problem where using ARROW UP out of a Screen Section did not work. This change was not tested in the 3.1.2 beta release, so it depends on this configuration option in order to shield users from any unexpected side-effects.
Parent topic: Configuration Variables


V30_MEASUREMENTS

This configuration variable affects whether the runtime sizes certain controls according to the rules from Version 3.0 or from the current version. If the current measurement code is causing your application to display incorrectly, then setting this variable to " (on, true, yes) will use Version 3.0 sizing rules instead. When V30_MEASUREMENTS is set to the default "0" (off, false, no), then the current sizing rules are in effect.

The related configuration variables, V31_MEASUREMENTS and V32_MEASUREMENTS have the same effect of setting the sizing rules to that of their respective versions.

Parent topic: Configuration Variables


V31_FLOATING_POINT

This configuration variable allows you to disable a correction that was made to the way floating-point numbers are displayed. Because some loss of precision in the display of "USAGE DOUBLE" fields was possible in Version 3.1, an improvement was introduced. Setting this variable to 1 (on, true, yes) means that the Version 3.1 method of displaying floating-point numbers is used. When V31_FLOATING_POINT is set to the default 0 (off, false, no), then the correction is in effect.

Parent topic: Configuration Variables


V31_MEASUREMENTS

This configuration variable is used by the run time. If set to TRUE (ON, YES, 1), then ACUCOBOL-GT release 3.1 measurement rules are used when setting the width of frames. If set to FALSE (OFF, NO, 0) standard measurement rules are used when setting frame width. The default is FALSE.

Parent topic: Configuration Variables


V311_NT_CALL_SYSTEM

This configuration variable is used by the run time for compatibility on NT systems. Setting it to TRUE (ON, YES, 1), causes Windows to call the system() function, rather than the more usual CreateProcess() function. The default is FALSE (OFF, NO, 0).

Parent topic: Configuration Variables


V32_MEASUREMENTS

This configuration variable is used by the run time. If set to TRUE (ON, YES, 1), then ACUCOBOL-GT release 3.2 measurement rules are used when determining the size of a graphical window. If set to FALSE (OFF, NO, 0) standard measurement rules are used when determining graphical window size. The default is FALSE.

Parent topic: Configuration Variables


V42_FLOATING_POINT

This variable affects how floating-point arithmetic is performed. Starting with Version 4.3, floating-point arithmetic was enhanced to more closely reflect the way that floating-point values are determined on the host system. This enhancement can affect the behavior of existing programs. To revert to the computation method used prior to Version 4.3, set the value of V42_FLOATING_POINT to 1 (on, true, yes). By default, this variable is set to 0 (off, false, no).

Parent topic: Configuration Variables


V43_PRINTER_CELLS

This variable affects whether the runtime sets the width of a printer cell according to the rules from Version 4.3 or from the current version. Version 4.3 (and prior versions) computed the width of a printer cell based on the average width of a selected printer font. The width of a printer cell is currently computed in the same way that cells are computed for the screen, namely by the width of the "0" character. For fixed-width fonts, such as Courier, these values are the same for all characters. For proportional fonts, such as Times New Roman, some characters might be wider than the "0" character.

If the current computation is causing your application to print incorrectly, then setting this variable to 1 (on, true, yes) will use Version 4.3 rules instead. When V43_PRINTER_CELLS is set to the default 0 (off, false, no), then the current rules are in effect.

Parent topic: Configuration Variables


V52_BITMAP_BUTTONS

If some event in the system forces the focus away from a bitmap-based push button after a click has been started but not finished, this variable determines whether the click is voided. If you do not want the click to be voided, set this variable to 1 (on, true, yes). The default setting is 0 (off, false, no).

Parent topic: Configuration Variables


V52_BITMAPS

This variable determines whether your application uses device-dependent or device-independent bitmaps for image processing. The following settings are recognized:

1 | Use Version 5.2 and earlier image-processing code (device-independent) for bitmap controls.
0 | Use Version 6.0 and later image-processing code (device-dependent) for bitmap controls.
1 | (default) Dynamically apply the image-processing code based on the program's object semantics. For programs compiled for pre-Version 6.0 semantics, use the older imaging code. For programs compiled for Version 6.0 or later semantics, use the newer code.
Parent topic: Configuration Variables


V52_GRID_GOTO

This configuration variable determines how the runtime behaves when a user clicks in a grid control cell containing the cursor. Prior to Version 5.2, the runtime would not pass a MSG-GOTO-CELL-MOUSE event to the program when the user clicked in a grid cell containing the cursor. For programs compiled with Version 5.2, or later, this event is passed to the program. Setting V52_GRID_GOTO to 0 (off, false, no), maintains the pre-5.2 behavior. The default of 1 (on, true, yes) enables the new behavior, even for programs compiled with Versions 5.1 or earlier and run with Versions 5.2 or later. See Appendix C: Changes Affecting Previous Versions for more details.

Parent topic: Configuration Variables


V60_LIST_VALUE

This variable allows you to select the algorithm used by the runtime to match a list box or combo box VALUE with an item in the control's list.

Prior to Version 6.0, setting the VALUE of a combo box or list box caused the first item in the list that started with the value of VALUE to be selected, regardless of case. Beginning with Version 6.0, when a box's VALUE is set, the list is searched for an exact, case sensitive match with the specified value. If the value is found, it is selected. If an exact match is not found, the list is searched for an exact match regardless of case. If a match is still not found, the list is searched again, this time for the first string that contains the passed VALUE as a leading substring, regardless of case. V60_LIST_VALUE allows you to specify which algorithm to use. It accepts the following values:

1 | directs the runtime to use the Version 6.0 search algorithm
0 | directs the runtime to use the pre-6.0 search algorithm (substring search only)
-1 | (default) directs the runtime to use the 6.0 search algorithm on objects compiled for Version 6.0 or later, and to otherwise use the old search algorithm. This means that objects compiled for compatibility with versions prior to 6.0 that are run with a Version 6.0 runtime will not exhibit the new behavior.
Parent topic: Configuration Variables


V62_MAX_WINDOW

Starting with Version 7.0, when the runtime reduces the size of a window to fit the screen, it includes any fractional lines and columns that fit, provided the COBOL program attempts to create a window with fractional lines and columns. For example, if you create a 70.0 line window, but only a 66.4 line window fits on the display, the runtime detects that no fractional lines were attempted, and truncates the number of lines to 66.0. However, if you attempt to create a 70.1 line window, the runtime recognizes the fractional measurement and displays a 66.4 line window. To preserve the pre-7.0 behavior, set the configuration variable V62_MAX_WINDOW to 1 (on, true, yes) and fractional lines and columns are always removed. The default value is 0 (off, false, no).

Parent topic: Configuration Variables


V71_ALIGNED_ENTRY_FIELD

Starting with Version 7.2, the wheel mouse can be used for scrolling in a center- or right-aligned entry field. To preserve the pre-7.2 behavior, set the V71_ALIGNED_ENTRY_FIELD configuration variable to 1 (on, true, yes). The default value of this variable is 0 (off, false, no).

Parent topic: Configuration Variables


V71_FONT_WIDTHS

Windows has a function called GetTextMetrics that returns information about a font. This data is used by the runtime to compute the "maximum character width" and "wide character width" of a font. The "maximum width" amount is used to set a lower bound for how small an entry field can be (to ensure that at least one character is always visible). The "wide width" is used to scale small entry fields and uppercase entry fields. The "wide width" is computed by averaging the maximum and average character widths. Experimentation has shown that the "maximum character width" data returned may be inaccurate, sometimes by very large margins.

With the use of the V71_FONT_WIDTHS configuration variable, the runtime validates the data returned by the Windows function and corrects it when it is too large. The change does not affect programs until they are recompiled with Version 7.2 or later, or the change is specifically enabled through the V71_FONT_WIDTHS configuration option. The variable can have the following values:

-1 | (default) The change is enabled for programs using Version 7.2 or later semantics. In other words, the program has been compiled with Version 7.2 or later and the command line does not contain a compiler option for pre-7.2 semantics.
0 | The change is enabled.
1 | The change is disabled and the Version 7.1 and earlier font measuring code is used.

Note the following issues regarding the use of this variable:

  • The runtime's standard fonts are not affected by this configuration variable setting.
  • Entry fields defined by physical units (CELLS or PIXELS) and all screens created using the AcuBench Screen Designer will not change.
  • Entry fields will not grow larger due to this configuration variable setting. The majority will stay the same size, and a few might get smaller.
  • Fixed width fonts are not affected by this configuration variable setting.
Parent topic: Configuration Variables


V80_3D_ENTRY_SIZE

An issue in version 8.0 with calculating ENTRY-FIELD sizes for 3-D and native controls was addressed version in 9.0.1. However prior to the fix, some users modified their screens based on the buggy calculation to keep their screens unchanged from 8.0.

Use the V80-3D-ENTRY-SIZE configuration variable to indicate which size calculation should be used. Set to TRUE if you want size calculations for entry fields done as they were in 8.0. Set the value to FALSE (default) to have entry fields sized as they were in 7.0 and earlier.

Parent topic: Configuration Variables


VMS COBOL

When set to 1 (on, true, yes), this causes the VMS runtime to write to print files the same way that VMS COBOL does. When set to 0 (off, false, no), this variable causes the runtime to behave as it always has. The default setting is 0 (off, false, no).

Parent topic: Configuration Variables


VMS_SYSTEM_MODIFIER

This configuration variable applies only to VMS systems. Use it to specify a value to subtract from the standard system() function when returning a status code to the run time.

Parent topic: Configuration Variables


W_PROGRESS_PARENT

When using the WPROGRESSDIALOG-CREATE operation with the WPROGRESSDIALOG-MODAL flag, the resulting progress dialog might not be modal to the current window. It would be modal to the main application window, but if you had other windows open, you might be able to interact with them.

Set the configuration variable W_PROGRESS_PARENT to the default value of MAIN or 0, then W$PROGRESSDIALOG behaves as it always has. The parent window of the dialog is the main ACU window.

When set to the value of CURRENT, then the parent of the Progress dialog box is the current active window. The only difference is the parent window parameter passed to the Progress dialog box creation function. When the parent is the current window, then pressing the Cancel button on the dialog box sometimes causes the ACU application to go to the background, requiring you to bring it back to the foreground to continue to interact with the ACU application. This is a side effect of the Progress dialog box. Determine if this behavior is acceptable before using the value of CURRENT for this configuration variable.

Parent topic: Configuration Variables


WAIT_FOR_ALL_PIPES

This configuration variable determines if the runtime calls the wait system call each time a -P file is closed. When WAIT_FOR_ALL_PIPES is set to 0 (off, false, no), the runtime does not make this call until it is ready to close the last pipe it knows about. Setting this configuration variable to the default 1 (on, true, yes) means that the runtime calls the wait system call when a -P file is closed.

Parent topic: Configuration Variables


WAIT_FOR_FILE_ACCESS

This configuration variable is designed for Windows 98 systems. It gives you some control over situations where a user must wait for access to a shared file. The runtime will try repeatedly to acquire the file lock, up to 400 times. If it has been unable to obtain a file lock after 400 tries, it will (by default) display a message box, asking if the user would like to continue waiting. If the user clicks the Yes button, then the runtime will try again another 400 times (or the value of LOCKING_RETRIES). If the user clicks the No button, then the runtime will return an error to the COBOL program (such as file error 30,33 (system error) or file error 99 (record locked).

The WAIT_FOR_FILE_ACCESS variable lets you choose one of three behaviors: either the user will always see the message box and make a choice, or the program will always return an error code if it cannot acquire the lock, or the runtime will always behave as if the user answered yes to the message box.

You can modify the text shown to the user in the message box via the TEXT configuration variable. The message is number 28. To include the filename in your message, insert %s at the place where you want the name of the file to appear. You can introduce line breaks by including "\n" in the message.

Possible values for the WAIT_FOR_FILE_ACCESS variable are:

0 | No | Do not display message box if lock is not acquired. Send error to COBOL program.
1 | Ask | Show the message box and ask the user. (Default)
2 | Yes | Do not show the message box. Assume that the user wants to wait for the file. This ensures that the user eventually can access the file, but introduces a small risk of an infinite loop if the system's lock table becomes corrupt.

For programs running in background (-b runtime option), or programs with redirected input or output, the Ask option is treated the same as the Yes option.

Parent topic: Configuration Variables


WAIT_FOR_LOCKS

This determines how the runtime handles file status error 99 conditions on record reads. This variable is not checked on record write operations. It can have one of the following values:

0 | Do not wait for locked records, return error 99.
1 | Wait for the locked record if no Declarative is available for the file, otherwise return error 99.
2 | Always wait for the locked record, never return error 99.

Any other value (including the default value of -1) causes the runtime to wait for locked records only if you have compiled for RM/COBOL compatibility and the file does not have a Declarative.

Parent topic: Configuration Variables


WARNINGS

This configuration variable controls whether a warning message is printed and an error raised for the following conditions:

  1. when non-numeric data is used in a context where numeric data is required
  2. when there is a reference modification range error

By default, the runtime silently corrects reference modification range errors as follows:

  • A start reference less than 1 is treated as 1. For example, var(0:3) is treated as var(1:3).
  • A length reference less than 0 is treated as 0. Moving a zero-byte item is equivalent to moving spaces to the destination item. A zero-byte destination is not affected by the move. In a STRING statement, a length of zero for a string source is treated as 1, not 0.
  • A start plus length reference that is past the end of the item is treated as meaning to the end of the item. For example, if the var is a PIC X(5) item, var(4:23) is treated as var(4:2).

WARNINGS can take the following values:

0 | (off, false, no) No warning is printed.
1 | (on, true, yes) A warning is printed. This is the default.
2 | A warning is printed or sent to the error file. If you are in the debugger, an automatic breakpoint occurs.
3 | For a non-numeric error, a warning is printed, an intermediate error is generated that calls the installed error procedures, if any, and the runtime is halted. For more information on error procedures, see CBL_ERROR_PROC in Appendix I.
Note: The setting you select for WARNINGS applies to reference modifier range errors when the start plus length reference is past the end of the item. Reference modifiers that are equal to or less than zero are always silently corrected as described above.
Parent topic: Configuration Variables


WARNING_ON_RECURSIVE_ACCEPTS

An event procedure may CALL another procedure which may contain ACCEPT statements, which, in turn, may contain embedded procedures. Although this is handled in the same fashion as nested PERFORMs and is perfectly legal, doing this poses the danger of going from one ACCEPT to another uncontrollably. When the limit of 10 nested accepts is reached, the program starts overwriting memory. It is possible to warn the user when the limit is reached by giving this configuration variable a zero (0) value. This gives users the opportunity to continue at their own risk. Giving WARNING_ON_RECURSIVE_ACCEPTS a non-zero value suppresses the warning.

To avoid overwriting memory, you may choose to re-code affected programs to terminate the ACCEPT and perform the CALL after you exit from the ACCEPT. You may also use CHAIN or CALL PROGRAM instead of the regular CALL, if applicable.

Parent topic: Configuration Variables


WHITE_FILL

This variable has meaning only on graphical systems such as Windows. Some graphical systems (such as Windows) use a background brush when they resize a window. By default, the background brush color for ACUCOBOL-GT is black (0, off, false, no). If you have arranged your default background to be white, you will see a black flash when you resize the window. This does not affect the final appearance of the window, but is briefly noticeable while the window is being redrawn.

Set WHITE_FILL to 1 (on, true, yes) to cause ACUCOBOL-GT's background brush to be set to white instead of black. Doing this will also cause the initial screen that ACUCOBOL-GT paints to be white instead of black.

Note: This variable must be set in the configuration file to be effective. Modifying this variable with the SET ENVIRONMENT verb has no effect.
Parent topic: Configuration Variables


WIN_ERROR_HANDLING

This variable has meaning only on graphical systems such as Windows. Use WIN_ERROR_HANDLING to control how hardware errors are handled.

When this variable is set to the default of 1 (on, true, yes), certain errors are handled directly by the host environment, and do not automatically return a file error code. For these errors, a dialog box is displayed that describes the error and offers Cancel and Retry buttons. The user may correct the error and press Retry. If the user presses Cancel, then your program receives the file error that it would have normally received.

If you set WIN_ERROR_HANDLING to 0 (off, false, no), then the dialog box is not shown, and your program receives the error directly.

Parent topic: Configuration Variables


WIN_F4_DROPS_COMBOBOX

This configuration variable applies only to programs running under Windows.

If WIN_F4_DROPS_COMBOBOX is set to its default value of 1 (on, true, yes), then combo boxes use the standard Windows handling for the <F4> key. Pressing <F4> while a combo box is active causes it to drop its drop-down list, and the COBOL program is not notified of an exception.

When this variable is set to 0 (off, false, no), pressing <F4> with a combo box active causes the COBOL program to get the exception, but the combo box does not drop its drop-down list.

It is not possible to get both behaviors at the same time.

Parent topic: Configuration Variables


WIN_SPOOLER_PORT

This variable allows you to divert printer output to a file or port through the Windows print spooler. Files created in this way are stored in binary encoding. You may set the Windows print spooler with -P SPOOLER or -Q <printername> with or without the DIRECT option. However, if you omit the DIRECT option, the resulting file will include all the embedded control codes formatting the print job for the original target printer.

By default, the value of WIN_SPOOLER_PORT is undefined. Set WIN_SPOOLER_PORT to a valid filename or port. This can be done in a configuration file, in the environment, or in the program. For example:

WIN_SPOOLER_PORT  c:\mydir\myprint.prn
or
SET ENVIRONMENT "WIN_SPOOLER_PORT" TO "c:\mydir\myprint.prn".

This will affect all print jobs performed in the current instance of the runtime. Any graphics operations performed in the COBOL application, such as WINPRINT-BITMAP or WINPRINT-GRAPH-DRAW, are preserved in the file, and will print. However, these options may result in a very large binary file.

The resulting file can be copied directly to any printer that is compatible with the original target printer. For example, the following command:

COPY /B c:\mydir\myprint.prn LPT1

will send the file to LPT1, while the /B option tells the COPY command that the file contains binary encoding.

Parent topic: Configuration Variables


WIN3_CLIP_CONTROLS

This option is specific to the Windows versions of ACUCOBOL-GT. It affects the way in which updates to a window interact with graphical controls in a window. Normally, Windows allows updates to a parent window to show through any controls in that window. The controls are then updated to create the proper final appearance. This is very fast, but it can cause controls to flash when the background is being updated. When this option is set to 1 (on, true, yes), the controls are clipped from the update region in the parent window before the parent is repainted. This causes the controls to remain relatively stable; however, screen repaints can be significantly slower, particularly when the runtime is creating and destroying controls. The default setting for this option is 0 (off, false, no). We recommend that you experiment with both settings to see which you prefer. Note that this option is examined when a floating window is created. Once a window is created, changes to this option have no effect on that window.

Note: When turned on, this option causes the Windows WS_CLIPCHILDREN style to be used whenever floating windows are created.
Parent topic: Configuration Variables


WIN3_EF_PADDED

This configuration variable has meaning only on Windows systems. Under Windows, unboxed entry fields include a small amount of extra space so the cursor can be seen when it is placed after the last character position. This space can be a problem if you want to convert a program and align screen items. When WIN3_EF_PADDED is set to 0 (off, false, no), this extra space does not appear in unboxed entry fields, and the entry field has only enough space for its character positions. When this variable is set to the default 1 (on, true, yes), the extra space appears in unboxed entry fields.

Parent topic: Configuration Variables


WIN3_GRID

This option is specific to Windows. When set to a non-zero value, it causes a fine grid to be drawn in each floating window. The grid outlines the character cells in the windows. This is intended as a debugging tool, to help you see how various controls line up against the window's character cells. It can also help you adjust the layout of a screen.

The grid is drawn using the color number that WIN3_GRID is set to (see the COLOR phrase for the exact values). For example, setting WIN3_GRID to 4 will draw a cyan grid. The grid is drawn with dashed lines. Every fifth horizontal line and every tenth vertical line is drawn with a solid line.

Parent topic: Configuration Variables


WIN32_3D

This configuration variable causes the runtime to use the native 3-D features of Windows when drawing controls with the 3-D style. This has an effect only with the 32-bit Windows runtime. Turn this feature on by setting WIN32_3D to 1 (on, true, yes). When set to the default of 0 (off, false, no), the runtime supplies its own 3-D effects. The advantage of using the native Windows 3-D is that you get a slightly more modern appearance and a closer match to the appearance of other Windows programs. The disadvantages are:

  1. Windows always draws the border using the colors selected in the system's control panel. As a result, the effect looks right only when placed on a window whose background is the USER-GRAY color. You can accomplish this easily by creating STANDARD windows that specify BACKGROUND-LOW.
  2. The Windows 3-D effect is slightly larger than the runtime's 3-D effect. Windows draws a 1-pixel wide border around the control that is the same color as the USER-GRAY color. This border is essentially invisible against a window with the USER-GRAY background. However, this border can overwrite anything else that may be positioned there. The net effect is that you can't place controls as close together as you can with the runtime's 3-D.
  3. This 3-D style can be used only with the 32-bit runtime.

The runtime adjusts for the physical differences between the two styles. Under either style, the position and usable size of the control's interior should be same.

Note: This configuration setting can effect the behavior of an application if it is using the latest Windows control styling, that is the WIN32_NATIVECTLS configuration variable set to 1, true, or on. If WIN32_3D has not been set by the user then the default value will be overridden and set to false (0 or off). If the user has set WIN32_3D then their settings will not be overridden and if it is set to true (1 or on) then 3D drawing will occur over the top.
Parent topic: Configuration Variables


WIN32_CTL_INPUT_STATUS

Setting this variable to the default of TRUE (ON, YES, 1) causes ACCEPT...FROM INPUT STATUS to return a non-zero status if data is available in a control. If set to FALSE (OFF, NO, 0), then the data in the control does not affect the status returned by ACCEPT...FROM INPUT STATUS.

This variable is only available in the Windows runtime and is not available to the thin client.

Parent topic: Configuration Variables


WIN32_FRAMES_AS_ON_TABS

While it is possible to modify colors to get a desired look, common code is often used to display FRAME controls, whether on a TAB control or not. When common code is used, the FRAME controls on a TAB look different from FRAME controls not on a TAB, especially in the background color of the FRAME title.

Setting this variable to TRUE (ON, YES, 1) causes all FRAME controls to paint as if they are on a TAB control, particularly in the colors used to draw the control. If set to FALSE (OFF, NO, 0), then the FRAME controls on a TAB continue to have a different look than FRAME controls not on a TAB.

Parent topic: Configuration Variables


WIN32_NATIVECTLS

This variable allows an application to use the Windows control style that is in use on the workstation. To enable these visual styles, your application must be running on an operating system that contains ComCtl32.dll version 6, which is included with Windows XP and Windows Vista.

When set to TRUE (ON, YES, 1), the application displays the current control styling available on that operating system.

Note: In addition to visual differences, some XP and placeVista controls have different behaviors than their Windows classic counterpart (by Microsoft design).

The default setting is FALSE (OFF, NO, 0) which prevents the run time from using the Windows control styling, and forces the classic Windows look.

Note: The configuration variable WIN32_3D can also change the look of controls in an ACUCOBOL-GT application. It is generally recommended that you leave WIN32_3D set to its default behavior of off or false when setting WIN32_NATIVECTLS to on or true.
Note: The Windows OS allows users to configure (accessibility options) whether or not keyboard shortcut names appear with underlines. For example ctrl+c vs. ctrl+c. The WIN32_NATIVECTLS respects this setting and displays shortcut names accordingly.
Parent topic: Configuration Variables


WIN32_WIDE_CHARS

WIN32_WIDE_CHARS, which when set to 1 (or ON or TRUE), will cause the runtime to translate the data sent to these controls into wide characters before displaying the text.

Parent topic: Configuration Variables


WINDOW_INTENSITY

This configuration variable controls whether the color settings specified in the COLOR phrase of the DISPLAY WINDOW statement are used or ignored by the runtime. When the value of this variable is set to 0 (off, false, no), the COLOR intensity settings in all DISPLAY WINDOW statements are ignored. When the value of this variable is set to 1 (on, true, yes), which is the default, the runtime sets the windows intensity as specified.

Parent topic: Configuration Variables


WINDOW_TITLE

This variable has meaning only on graphical systems such as Windows. The ACUCOBOL-GT runtime system automatically sets the title of the application window to the base name of the initial object file. For example, if you run a program called notepad.cbx, then the title on the main window will be set to Notepad. The title is shown in lower-case except for the first letter, which is made upper case.

You may provide an alternate title by setting WINDOW_TITLE to the desired text. No translation of the text is done, so you should enter it using the desired case.

Note: Setting WINDOW_TITLE from within a program has no effect, because the WINDOW_TITLE setting determines only the window's initial title.

To change the title from within your program, use a DISPLAY statement. The syntax is:

DISPLAY text UPON GLOBAL WINDOW TITLE

where text is an alphanumeric literal or variable. Enter the title with the desired case. The title is always shown in the ANSI font, so if you are using a different font, your text will be translated to ANSI.

To ensure that the WINDOW_TITLE variable operates as expected, make sure that the first screen operation in your program is not DISPLAY WINDOW with a title (the DISPLAY WINDOW title is stored in the same place as the WINDOW_TITLE). Instead, do some other screen operation first, such as DISPLAY WINDOW, ERASE.

Parent topic: Configuration Variables


WINPRINT_NAMES_ONLY

This variable allows you to generate a list of the names of printers installed on a Windows PC. It does this by altering the behavior of some of the operations of the WIN$PRINTER library routine. When WINPRINT_NAMES_ONLY is set to a value of 1 (on, true, yes), the WIN$PRINTER operations that retrieve printer information return only the names of installed printers, rather than the real-time status of all available printer capabilities.

This variable can be set in the configuration file or directly in your program with the following code:

SET ENVIRONMENT "WINPRINT-NAMES-ONLY" TO "1".

Note on WIN$PRINTER library routine:

When this variable is turned on, the following operations of the WIN$PRINTER library routine are affected:

WINPRINT-GET-PRINTER-INFO
WINPRINT-GET-PRINTER-INFO-EX
WINPRINT-GET-CURRENT-INFO
WINPRINT-GET-CURRENT-INFO-EX

Instead of returning detailed information about the capabilities of each printer (duplex, copying, etc.), the routine returns only the name of the printer. This can provide a significant performance improvement, particularly with networked printers.

If you are using the default printer settings, set the WINPRINT_NAMES_ONLY variable to 1, generate a list of printer names using WINPRINTER-GET-PRINTER-INFO-EX (see the WIN$PRINTER documentation in the Appendices of the ACUCOBOL-GT manual set, or refer to the sample program prndemox.cbl), and select the desired printer.

If you want to modify the printer settings, such as the number of copies or the paper orientation, you should perform the steps described above, and then set WINPRINT_NAMES_ONLY back to the default of 0 (off, false, no). You may then use WINPRINTGETPRINTERINFOEX to obtain detailed information about the capabilities of the selected printer.

For more information about Windows printing, refer to WIN$PRINTER in Appendix I.

Parent topic: Configuration Variables


WRAP

The setting of this variable determines whether a DISPLAY statement will wrap around or be truncated when it extends past one line. When it is set to 0 (off, false, no), DISPLAY statements will be truncated. Also, any DISPLAY statement that references a column past the right edge of the current window will be ignored. An ACCEPT statement that references a column past the right edge will be placed in the home position of the window. The default value for this setting is 1 (on, true, yes).

Parent topic: Configuration Variables


XFD_DIRECTORY

This variable tells the runtime system the name of the directory that contains the data dictionaries built by the ACUCOBOL-GT compiler. The default value is the current directory.

For example, to tell the runtime that the dictionaries are stored in the directory /usr/inventory/dictionaries you would enter:

xfd_directory   /usr/inventory/dictionaries

See also the -Fo compile-time option, which tells the compiler where to put the dictionaries. Unless you have moved the dictionaries, you should use the same value for XFD_DIRECTORY that you used with the -Fo option.

If you have embedded an XFD file in an object library, the runtime will read that file instead of an XFD file that has the same name but is stored in the directory specified by XFD_DIRECTORY. The exception to this is when the XFD_DIRECTORY configuration variable uses remote name notation.

Parent topic: Configuration Variables


XFD_PREFIX

This variable defines a series of directories to search for XFD files, rather than indicating only one (as in XFD_DIRECTORY). Each directory is searched in order until an XFD matching the name of the file is found. Once a file with the same name is found, the runtime stops searching, even if other files of the same name are located in a subsequent directory in the search parameter. Only named directories are searched, not subdirectories.

Note: If the XFD you are searching for does not match the file specifications (max-keys, max-rec-size, min-rec-size, and key parameters, for example) of the file you are trying to open, the runtime will not continue searching the directories listed in XFD_PREFIX until a correct XFD file is found.

The default for XFD_PREFIX is empty. If this variable is set to any other value, the configuration variable XFD_DIRECTORY (in which you specify only one directory) is ignored. You can specify a directory path that contains embedded spaces if you surround the path with quotation marks. Separate entries using a semi-colon (;). For example:

XFD_PREFIX C:\ "Sales Data";C:\Customers

You may specify up to 4096 characters for this variable.

Parent topic: Configuration Variables


XML_KEEP_WHITESPACE

Use this variable to preserve the leading and trailing white space from data elements.

Both AcuXML and C$XML remove leading and trailing white space from data elements, including white space in CDATA sections. To get the CDATA data, nothing is needed because it is returned automatically. For other white space, use the XML_KEEP_WHITESPACE configuration variable.

Set the value to FALSE (default) to remove leading and trailing white space from the data when it is parsed. Set the value to TRUE to return all white space in the XML element. The element looks like this:
<my-data>
     this is my data
 </my-data>

Returned data starts with a new line, then four spaces, and another new line.

Parent topic: Configuration Variables


XTERM_PROGRAM

Some users may want to debug with an xterm, but don't actually want to debug with the xterm executable because it doesn't have some of the abilities they need (such as displaying non-ASCII characters). You can specify the executable used to show the debugger on UNIX by setting the XTERM_PROGRAM runtime configuration variable.

Its default value is xterm, but it can be set to any compatible program such as dtterm or kterm. The runtime executes this program when it tries to create the program for background debugging. Note that the runtime passes some arguments to this program, so this program must be able to execute with those arguments. These arguments are:

-title "title of the window"

-Sccn

-display Xserver-name

The -Sccn option allows the program to be used as the input and output channel for the runtime, and is absolutely required. Without this option, the program won't know to display data from the runtime.

Parent topic: Configuration Variables


Appendix I. Library Routines

  • General Syntax and Library List
Parent topic: Appendices


General Syntax and Library List

ACUCOBOL-GT has a large set of library routines built into the runtime system. These routines may be accessed via the CALL verb. This appendix describes each of these routines in detail. The routines are listed in alphabetical order.

In the following descriptions, the phrase "Numeric parameter" indicates a data item or literal that contains a numeric value in any of the following formats:

  • Signed or unsigned COMP-4 (or internal equivalent such as COMP-X)
  • Unsigned PIC 9 USAGE DISPLAY
  • PIC X containing digits (other data ignored)
  • Unsigned numeric literal
  • Alphanumeric literal containing digits (other data ignored)

Any routine that has a GIVING phrase specified in its USAGE may omit that phrase. If this is done, then the routine's return value will be placed into the special register RETURN-CODE instead.

  • ASCII2HEX
  • ASCII2OCTAL
  • C$88591-UTF8
    Translates a string encoded using the ISO-8859-1 code page to a UTF-8 encoded data item.
  • C$ASYNCPOLL
  • C$ASYNCRUN
  • C$CALLEDBY
    Returns the name of the caller of the currently running COBOL program or spaces if no caller exists or if the caller is unknown.
  • C$CALLERR
    Retrieves the reason why the last CALL statement failed. For accurate information, it must be called before any other CALL statement is executed.
  • C$CARG
  • C$CHAIN
  • C$CHDIR
    Changes the current working directory.
  • C$COBOL-UTF8
    Translates a string encoded using the ANSI code page specified by the COBOL_CHARACTER_SET configuration variable to a UTF-8 encoded data item.
  • C$CODESET
  • C$CONFIG
  • C$COPY
  • C$DARG
  • C$DELETE
  • C$DISCONNECT
  • C$EXCEPINFO
  • C$EXITINFO
  • C$FILEINFO
    C$FILEINFO retrieves some operating system information about a given file.
  • C$FILESYS
  • C$FULLNAME
    This routine locates a file by using the runtime's filename translation and search logic, and returns the full name of the corresponding file.
  • C$GETCGI
  • C$GETERRORFILE
  • C$GETEVENTDATA
  • C$GETEVENTPARAM
  • C$GETLASTFILEOP
  • C$GETNETEVENTDATA
  • C$GETPID
  • C$GETVARIANT
  • C$JAVA
  • C$JUSTIFY
    C$JUSTIFY performs left or right justification of data and centering of data.
  • C$KEYMAP
  • C$KEYPROGRESS
  • C$LIST-DIRECTORY
    The C$LIST-DIRECTORY routine lists the contents of a selected directory. Each operating system has a unique method for performing this task. C$LIST-DIRECTORY provides a single method that will work for all operating systems.
  • C$LOCALPRINT
  • C$LOCKPID
    This routine returns the Process ID (PID) of the process holding the lock responsible for the previous file lock or record locked condition encountered. This library routine works only with the Vision file system and the UNIX platform.
  • C$MAKEDIR
    Creates a new directory.
  • C$MEMCPY (Dynamic Memory Routine)
    Copies bytes between any two memory locations.
  • C$MYFILE
    Returns the filename of the disk file containing the currently executing program.
  • C$NARG
    This routine returns the number of parameters passed to the current program.
  • C$OPENSAVEBOX
  • C$PARAMSIZE
    This routine returns the number of bytes actually passed by the caller for a particular parameter.
  • C$PARSEXFD
  • C$PDF
    This routine enables you to perform PDF printing, offering similar (but more comprehensive) functionality to the collection of PDF_ configuration variables.
  • C$RECOVER
  • C$REDIRECT
  • C$REGEXP
    This routine allows you to search strings using regular expressions.
  • C$RERR
    Returns extended file status information.
  • C$RERRNAME
    This routine returns the name of the last file used in an I/O statement. It can be used in conjunction with C$RERR to determine file errors.
  • C$RESOURCE
  • C$RUN
    ACUCOBOL-GT for Windows supports an alternate method for running other programs. This is through the library routine C$RUN. This library routine works identically to the SYSTEM library routine, except that the calling program does not wait for the called program to finish. Instead, both programs run in parallel.
  • C$SETERRORFILE
  • C$SETEVENTDATA
  • C$SETEVENTPARAM
  • C$SETVARIANT
  • C$SLEEP
    This routine causes the program to pause in a machine efficient fashion.
  • C$SOCKET
  • C$SYSLOG
  • C$SYSTEM
    This routine combines the functionality of "SYSTEM" and "C$RUN". It allows you to run other programs from inside a COBOL application in a variety of ways.
  • C$TOUPPER and C$TOLOWER
    These routines translate text to upper- or lower-case.
  • C$UTF16-UTF8
    Translates a UTF-16 encoded string to a UTF-8 encoded data item.
  • C$UTF8-COBOL
    Translates a UTF-8 encoded string to a data item encoded using the ANSI code page specified by the COBOL_CHARACTER_SET configuration variable.
  • C$UTF8-88591
    Translates a UTF-8 encoded string to a data item encoded using the ISO-8859-1 code page.
  • C$UTF8-UTF16
    Translates a UTF-8 encoded string to a UTF-16 encoded data item.
  • C$XML
    This routine lets you retrieve and parse precise information from an XML document. It also lets you add, modify, or delete data in an XML document.
  • CBL_AND
  • CBL_CLEAR_SCR
  • CBL_CLOSE_FILE
  • CBL_COPY_FILE
  • CBL_CREATE_DIR
  • CBL_CREATE_FILE
  • CBL_DELETE_DIR
  • CBL_DELETE_FILE
  • CBL_EQ
  • CBL_ERROR_PROC
  • CBL_EXIT_PROC
  • CBL_FLUSH_FILE
  • CBL_GET_CSR_POS
  • CBL_GET_EXIT_INFO
  • CBL_GET_SCR_SIZE
  • CBL_NOT
  • CBL_OPEN_FILE
  • CBL_OR
  • CBL_READ_FILE
  • CBL_READ_SCR_ATTRS
  • CBL_READ_SCR_CHARS
  • CBL_READ_SCR_CHATTRS
  • CBL_SET_CSR_POS
  • CBL_SUBSYSTEM
  • CBL_SWAP_SCR_CHATTRS
  • CBL_WRITE_FILE
  • CBL_WRITE_SCR_ATTRS
  • CBL_WRITE_SCR_CHARS
  • CBL_WRITE_SCR_CHARS_ATTR
  • CBL_WRITE_SCR_CHATTRS
  • CBL_WRITE_SCR_N_ATTR
  • CBL_WRITE_SCR_N_CHAR
  • CBL_WRITE_SCR_N_CHATTR
  • CBL_WRITE_SCR_TTY
  • CBL_XOR
  • DISPLAY_REG_*
  • Dynamic Memory Routines
  • Error and Exit Procedures
  • HEX2ASCII
  • I$IO
    The I$IO routine provides an interface to the file handler.
  • LIB$GET_SYMBOL
  • LIB$SET_SYMBOL
  • OCTAL2ASCII
  • R$IO
  • RENAME
  • RMNet Routines
  • SYSTEM
  • S$IO
  • $WINHELP
  • W$BITMAP
  • W$BROWSERINFO
  • W$FLUSH
  • W$FONT
  • W$FORGET
  • W$GETC
  • W$GETURL
  • W$KEYBUF
  • W$MENU
  • W$MOUSE
  • W$PALETTE
  • W$PROGRESSDIALOG
  • W$STATUS
  • W$TEXTSIZE
  • WIN$PLAYSOUND
  • WIN$PRINTER
  • WIN$VERSION
    Returns version information for Windows and Windows NT host platforms.
  • Windows Print Spooler (-Q and -P)
  • Windows Registry Routines
Parent topic: Appendix I. Library Routines


ASCII2HEX

ASCII2HEX converts binary data to its hexadecimal format. This routine is the inverse of the HEX2ASCII routine.

Usage

CALL "ASCII2HEX"
    USING ASCII-VALUE, HEX-VALUE

Parameters

ASCII-VALUE PIC X(2) | The input data area containing the ASCII representation of a unit of data.
HEX-VALUE PIC X(4) | The output data area to contain the hexadecimal value.

When you define the parameters, use the exact field sizes specified in the calling conventions above, otherwise the runtime may terminate abnormally.

Parent topic: General Syntax and Library List


ASCII2OCTAL

ASCII2OCTAL converts binary data to octal format. This routine is the inverse of the OCTAL2ASCII routine.

Usage

CALL "ASCII2OCTAL"
    USING ASCII-VALUE, OCTAL-VALUE

Parameters

ASCII-VALUE PIC X(2) | The input data area containing the ASCII representation of a unit of data.
OCTAL-VALUE PIC X(8) | The output data area to contain the octal value.

When you define the parameters, use the exact field sizes specified in the calling conventions above, otherwise the runtime may terminate abnormally.

Parent topic: General Syntax and Library List


C$88591-UTF8

Translates a string encoded using the ISO-8859-1 code page to a UTF-8 encoded data item.

Usage

C$88591-UTF8 using 88591-item, itemlen
                 [, destination [, destinationlen]]

Parameters

88591
The ISO-8859-1 encoded source item to be translated. It must be either a POINTER (set to a valid value) or an alphanumeric data item.
itemlen
The number of characters of the source item that you want to translate. If this value is 0, then the size of the source item is used (except when the source is a POINTER). If this value is -1, the source is assumed to be terminated by a low-value character, and again, the entire source item will be translated.
destination
If specified, is where the translated characters will be moved. If not specified, the return-code will be the number of characters needed in the destination item to hold the entire source string. This data item can be either a POINTER or an alphanumeric data item. If it is a POINTER, you must set it to a valid value.
destinationlen
The number of characters that can be held in the destination data item. If this parameter is -1, or is not specified, then the length of destination is used.

Comments

The return value is the number of characters moved to the destination data item, or the number that would be needed (when the destination item is missing or NULL).

If fewer characters are placed in the destination than there is room for, the routine will pad the destination with spaces.

Examples

Using the following data definitions:

01 my-string-1 pic x(100).

In the following example, since itemlen is 0, the CALL translates all 5 characters (ABcde) into UTF-8, placing the result into my-string-1.

CALL C$88591-UTF8 using "ABcde", 0, my-string-1.
Parent topic: General Syntax and Library List
Related reference
C$UTF16-UTF8
C$UTF8-UTF16
C$COBOL-UTF8
C$UTF8-COBOL
C$UTF8-88591


C$ASYNCPOLL

C$ASYNCPOLL is used only with AcuConnect. It checks the status of the server program while the client is running.

Usage

CALL "C$ASYNCPOLL"
    USING HANDLE-OF-CALL, STATE-OF-CALL, PARAMETER(S)

Parameters

HANDLE-OF-CALL USAGE HANDLE | Contains the handle of the CALL previously run with C$ASYNCRUN.
STATE-OF-CALL PIC S9 | Contains a value of "0" if the run is not completed, or 1 if the run is completed.
PARAMETER(S) Any COBOL data type (optional) | Contains a parameter of the CALL. You may include as many parameters as you choose, separated by a space or comma, to define the CALL. The list of parameters used in C$ASYNCPOLL must match the list of parameters used in C$ASYNCRUN.

Comments

C$ASYNCPOLL tells AcuConnect to query the server about the status of the remote application. AcuConnect returns a status that you can DISPLAY on the client. If the status is 1 or CALL completed, C$ASYNCPOLL terminates the connection with the remote application. This library routine works only with AcuConnect.

Parent topic: General Syntax and Library List


C$ASYNCRUN

Call C$ASYNCRUN along with your remote applications to allow AcuConnect to run asynchronously.

Usage

CALL "C$ASYNCRUN"
    USING HANDLE-OF-CALL, PROGRAM-NAME, PARAMETER(S)

Parameters

HANDLE-OF-CALL USAGE HANDLE | Contains the handle of the CALL defined in working storage.
PROGRAM-NAME String Literal or PIC X(n) | Contains the name of the CALLed program.
PARAMETER(S) Any COBOL data type (optional) | Contains a parameter of the CALL. You may include as many parameters as you choose, separated by a space or comma, to define the CALL.

Comments

By default, AcuConnect performs synchronous CALLs to remote applications. The client application CALLs the remote application and waits for a response from the server to continue processing. C$ASYNCRUN tells AcuConnect to allow the client application to continue processing even while the server application is active. This library routine works only with AcuConnect.

Parent topic: General Syntax and Library List


C$CALLEDBY

Returns the name of the caller of the currently running COBOL program or spaces if no caller exists or if the caller is unknown.

Usage

CALL "C$CALLEDBY"
    USING CALLING-PROGRAM
    GIVING CALL-STATUS

Parameters

CALLING-PROGRAM PIC X(n) | Contains the name of the calling program or spaces if no caller exists or if the caller is unknown. The runtime will use as much space for the name or spaces as the COBOL program allows. If the object being called is in an object library, the program returns the PROGRAM-ID. If the object is not in an object library, the disk name is returned.
CALL-STATUS PIC S99 | This parameter receives one of the following values: 1 - Routine called by another COBOL program 0 - Routine is the main program; no caller exists -1 - Caller unknown; routine not called by a COBOL program
Parent topic: General Syntax and Library List


C$CALLERR

Retrieves the reason why the last CALL statement failed. For accurate information, it must be called before any other CALL statement is executed.

Usage

CALL "C$CALLERR"
    USING ERR-CODE, ERR-MESSAGE

Parameters

ERR-CODE PIC X(2)

This parameter receives one of the following values:

01 | Program file missing or inaccessible
02 | Called file not a COBOL program
03 | Corrupted program file
04 | Inadequate memory available to load program
05 | Unsupported object code version number
06 | Recursive CALL of a program
07 | Too many external segments
08 | Large-model program not supported (returned only by runtimes that do not support large-model programs)
09 | Exit Windows and run "share.exe" to run multiple copies of "wrun32.exe" (returned only by Windows runtimes)
14 | Japanese objects are not supported (returned only by runtimes that do not support Japanese objects)

ERR-MESSAGE PIC X(n) (optional)

This routine may optionally be passed a second alphanumeric parameter. This parameter is filled in with a descriptive message about the error encountered.

Parent topic: General Syntax and Library List


C$CARG

C$CARG returns information about the actual parameter that corresponds to a formal parameter in the USING phrase in the Procedure Division header of a subprogram. This information identifies the type and length of the argument and, when the argument is numeric or numeric edited, the number of digits and scale factor for the argument.

Note: The -Cr compiler option is required for COMPUTATION/COMP usage data items to have the expected type (otherwise they are binary) and also to have a non-integer GIVING/RETURNING item.

Usage

CALL "C$CARG" USING OKAY, ARGUMENT-NAME,
ARGUMENT-DESCRIPTION

Parameters

OKAY (PIC X)
A one-character alphanumeric data item into which the ASCII character Y is stored if C$CARG successfully identifies the argument named by argument-name; otherwise, the ASCII character N is stored in the data item.
ARGUMENT-NAME (PIC X(N))
The name of a Linkage Section data item named in the Procedure Division header USING list.
ARGUMENT-DESCRIPTION
A ten-character group data item into which the desired information about the argument specified by argument-name is stored. A typical data description for argument-description is as follows:
01 ARGUMENT-DESCRIPTION.
   02 ARGUMENT-TYPE           PIC 9(2)  BINARY(2).
   02 ARGUMENT-LENGTH         PIC 9(8)  BINARY(4).
   02 ARGUMENT-DIGIT-COUNT    PIC 9(2)  BINARY(2).
   02 ARGUMENT-SCALE          PIC S9(2) BINARY(2).

The argument-description group item will have the correct length only if ARGUMENT-TYPE, ARGUMENT-DIGIT-COUNT, and ARGUMENT-SCALE are allocated as two-byte binary and ARGUMENT-LENGTH is allocated as four-byte binary.

The fields in ARGUMENT-DESCRIPTION have the following meanings:

ARGUMENT-TYPE
returns a number indicating the type of the argument data item. The values and meanings for data type numbers returned in this field are as follows:
Type Number | Data Type | Type Number | Data Type
0 | Numeric edited | 16 | Alphanumeric
1 | Unsigned numeric DISPLAY | 17 | Alphanumeric (justified right)
2 | Signed numeric DISPLAY separate | 18 | Alphabetic
3 | Signed numeric DISPLAY | 19 | Alphabetic (justified right)
4 | Signed numeric DISPLAY separate | 20 | Alphanumeric edited
5 | Signed numeric DISPLAY | 21 | Alphabetic string edited
6 | Signed numeric COMP with -Cr compiler option | 22 | Group (fixed length)
7 | Unsigned numeric COMP with -Cr compiler option | 23 | Group (variable length)
8 | Unsigned numeric PACKED-DECIMAL | 26 | Signed numeric COMP-5
9 | Signed numeric PACKED-DECIMAL | 27 | Unsigned numeric COMP-5
10 | Unsigned numeric COMP-6 | 32 | OMITTED
11 | Signed numeric BINARY
12 | Unsigned numeric BINARY
ARGUMENT-LENGTH
Returns the number of character positions occupied by the argument data item.
ARGUMENT-DIGIT-COUNT
Returns the number of digits defined in the PICTURE character-string for an argument that is a numeric or numeric edited data item as indicated by the ARGUMENT-TYPE field value; otherwise, the value zero is returned for nonnumeric data items. The digit count for a numeric or numeric edited data item does not include any positions defined by the PICTURE symbol P, which represents a scaling position.
ARGUMENT-SCALE
Returns the power of 10 scale factor (that is, the position of the implied or actual decimal point) for an argument that is a numeric or numeric edited data item as indicated by the ARGUMENT-TYPE field value; otherwise, the value zero is returned for nonnumeric data items. If the PICTURE symbol P was used in the description of the data item, the absolute value of the ARGUMENT-SCALE value will exceed the ARGUMENT-DIGIT-COUNT value; in this case, a positive scale value indicates an integer with P scaling positions on the right of the PICTURE character-string and a negative scale value indicates a fraction with P scaling positions on the left of the PICTURE character-string.

Comments

If a calling program passes a called program two or more arguments that begin at the same location (either through redefinition, with reference modification, or because one is a group that contains the other), when the called program asks C$CARG for the parameter descriptions, it always receives that of the first actual argument passed that has the same location, regardless of the name specified in argument-name. In such cases, the C$DARG subprogram may be used to obtain the distinct descriptions by using argument-number.

Parent topic: General Syntax and Library List


C$CHAIN

The C$CHAIN routine replaces the running program and runtime system with another program.

Usage

CALL "C$CHAIN"
    USING PROG-NAME

Parameter

PROG-NAME PIC X(n) Contains an operating system command line to execute.

Description

This routine functions in the same manner as the SYSTEM library routine, except that there is no return to the running program. Instead, the current program shuts down (like a STOP RUN) and the runtime system then replaces itself with the passed program. This is similar to the CHAIN verb except that the called program is not a COBOL program; it is any program available on the host machine.

The usual reason for calling this routine is to make more memory available to the called program. The runtime system can occupy a significant amount of memory that may be needed by the called program. Calling C$CHAIN ensures that the runtime system is removed from memory along with the various COBOL programs that have been active.

Often it is desirable to return from the called program to the caller. One way to do this is to use an operating system script to re-execute the calling program. You can control the script with various exit statuses--for a description of the runtime's exit statuses, see the entry for the STOP Statement in the ACUCOBOL-GT Reference Manual. Usually the script will sit in a loop calling the ACUCOBOL-GT runtime system until it receives a special exit status. You can use the STOP RUN statement to pass that special status back to the script when you want to shut down. You should remember that when the runtime system chains to another program, the script sees the exit status of the called program as the exit status of the runtime system.

For example, suppose on a UNIX system that you have a program (called main) that executes the C$CHAIN routine. After the called program terminates, you want to re-execute the caller. You decide to use exit value "100" to indicate that the program should terminate. You could use the following "sh" script:

runcbl main
while test $? != 100; do runcbl main; done

This script runs main once, and then continues to run it until it executes a STOP RUN 100 statement. Writing the script this way allows the program that is called by C$CHAIN to have a non-zero exit value without stopping the entire run.

You may want to distinguish between the first execution of the calling program and subsequent executions. For example, you may want to display copyright information on the first execution. You can do this by using a SPECIAL-NAMES switch to distinguish between the first execution and subsequent ones. For instance, in the preceding example you could add -1 to the second runcbl command to set SWITCH-1 for the subsequent executions. Your program can then test the value of this switch to determine what to do.

Parent topic: General Syntax and Library List


C$CHDIR

Changes the current working directory.

Usage

CALL "C$CHDIR"
    USING DIR-NAME, ERR-NUM

Parameters

DIR-NAME PIC X(n) Contains the name of the new directory, or spaces.

The "@[DISPLAY]:" for Thin Client support is allowed. For example:

C$CHDIR "@[DISPLAY]:C:\path"

In Thin Client environments, to get the current default directory on the display host, DIR_NAME should contain "@[DISPLAY]:" followed by spaces.

See information regarding Thin Client and Windows Special Directories in CBL_COPY_FILE for more information.

ERR-NUM PIC 9(9) COMP-4 (optional) Holds the returned error number, or zero on success.

Comments

If a second USING parameter is passed, it must be described as PIC 9(9) COMP-4. This parameter will be set to ZERO if the directory change is successful. Otherwise, it will contain the operating system's error number.

If DIR-NAME contains spaces, then the current default directory is returned in it. In this case, ERR-NUM is not used. Otherwise, DIR-NAME should contain the name of a directory to make the new default directory. On Windows machines, this can include a drive letter. If you pass ERR-NUM, it will be set to zero if the change was successful. Otherwise, ERR-NUM will contain the error value returned by the operating system.

On some systems (such as VMS), it is legal to switch to a directory that does not exist, while other systems (Windows, UNIX) do not allow it.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

IMPORTANT

If you use C$CHDIR, create a CODE_PREFIX configuration entry to locate your object files. Ensure that all of the search locations specified by the CODE-PREFIX are full path names. Do not use the current directory or any relative path names in the CODE_PREFIX. Without a full path name, the runtime system may be unable to find your object files if it needs to re-open them.

For example, the runtime system must occasionally re-open an object file when:

  • you are using the source debugger
  • the program contains segmentation (overlays)
  • you are using object libraries

If the object file was initially found in the current directory or a directory specified relative to the current directory, and you then change the current directory with the C$CHDIR routine, the runtime system will not be able to find the object file if it needs to re-open it. This will cause a fatal error and your program will halt.

If you use C$CHDIR and you are running in debug mode, be sure to set CODE_PREFIX in the configuration file, not in the environment. You may set CODE_PREFIX in the environment when you are not in debug mode.

Considerations for AcuBench users

When you import a screen with the Screen Import Utility, a file called import.out is created in the current working directory. The Screen Designer uses this file to load the description(s) of the imported screen(s) into its designer grid and property sheet.

When you invoke the Screen Import Utility from within the Workbench, the act of exiting the runtime also causes the Screen Designer to load the import.out file which is located in the root directory of the project currently open.

If your application changes the current working directory, the import.out file will not be created in the root directory of the currently open project, so different, perhaps unexpected behaviors can occur.

import.out files will be generated correctly, and the Screen Designer will be able to import them correctly, but you will have to locate the files for the Screen Designer and open them manually using the File > Open dialog box in the Screen Designer.

Parent topic: General Syntax and Library List
Related reference
FILENAME_SPACES
CBL_COPY_FILE
CODE_PREFIX
Working with XML Data


C$COBOL-UTF8

Translates a string encoded using the ANSI code page specified by the COBOL_CHARACTER_SET configuration variable to a UTF-8 encoded data item.

Usage

C$COBOL-UTF8 using COBOL-item, itemlen
                 [, destination [, destinationlen]]

Parameters

COBOL-item
The source item encoded using the ANSI code page (as specified by the COBOL_CHARACTER_SET configuration variable), to be translated. It must be either a POINTER (set to a valid value) or an alphanumeric data item.
itemlen
The number of characters of the source item that you want to translate. If this value is 0, then the size of the source item is used (except when the source is a POINTER). If this value is -1, the source is assumed to be terminated by a low-value character, and again, the entire source item will be translated.
destination
If specified, is where the translated characters will be moved. If not specified, the return-code will be the number of characters needed in the destination item to hold the entire source string. This data item can be either a POINTER or an alphanumeric data item. If it is a POINTER, you must set it to a valid value.
destinationlen
The number of characters that can be held in the destination data item. If this parameter is -1, or is not specified, then the length of destination is used.

Comments

The return value is the number of characters moved to the destination data item, or the number that would be needed (when the destination item is missing or NULL).

If fewer characters are placed in the destination than there is room for, the routine will pad the destination with spaces.

Examples

Using the following data definitions:

01 my-string-1 pic x(100).
01 my-string-2 pic x(100).

In the following example, the CALL translates the 5 characters in my-string-1 (ABcde) into UTF-8, and places the result in my-string-2, which is then padded with UTF-8 spaces. The return-code is 5 (characters).

MOVE "ABcde" to my-string-1
CALL "C$COBOL-UTF8 using my-string-1, 5, my-string-2, 50
Parent topic: General Syntax and Library List
Related reference
C$UTF16-UTF8
C$UTF8-UTF16
C$UTF8-COBOL
C$88591-UTF8
C$UTF8-88591


C$CODESET

This routine supports the translation of a text string from EBCDIC to ASCII, or ASCII to EBCDIC.

Usage

CALL "C$CODESET"
    USING TRANS-FLAG, LENGTH, TRANS-STRING
    GIVING RETURN-VALUE.

Parameters

TRANS-FLAG PIC 9(2) COMP-X.

I ndicates the type of text in TRANS-STRING, and whether to apply LENGTH when performing the translation. TRANS-FLAG takes one of the following values:

0 | Indicates that TRANS-STRING contains EBCDIC and that LENGTH specifies the length of the string to translate to ASCII.
1 | Indicates that TRANS-STRING contains ASCII and that LENGTH specifies the length of the string to translate to EBCDIC.
2 | Indicates that TRANS-STRING contains EBCDIC and that 256 bytes of data should be translated to ASCII. The LENGTH parameter is ignored.
3 | Indicates that TRANS-STRING contains ASCII and that 256 bytes of data should be translated to EBCDIC. The LENGTH parameter is ignored.

LENGTH PIC 9(9) COMP-X

Specifies the length of the string to translate.

TRANS-STRING PIC X(n)

Contains the string to translate and the result of the translation.

RETURN-VALUE Numeric data item

Returns the number of characters translated, or zero if an error occurred.

Parent topic: General Syntax and Library List


C$CONFIG

C$CONFIG resets configuration values to a known set of values. Note, however, that certain values are set only at runtime start up, and are therefore not affected by this routine.

Usage

CALL "C$CONFIG"
    USING OP-CODE, CONFIG-FILE

Parameters

OP-CODE PIC 9 | The only valid value is 1. If the op-code is specified with no arguments, C$CONFIG resets all known configuration values to their default. Values are removed from any user-defined configuration variables, leaving them blank, and the original configuration file is reloaded.
CONFIG-FILE PIC X(n) (optional) | Specifies a new configuration file to be loaded after the configuration variable values have been reset.

Description

C$CONFIG resets all runtime configuration variables first to their default values, then to the values specified in CONFIG-FILE, if CONFIG-FILE is specified.

If you pass a blank argument for CONFIG-FILE, as shown below, all configuration variables are reset and no configuration file is loaded.

CALL "C$CONFIG" USING 1, ""
Parent topic: General Syntax and Library List


C$COPY

C$COPY creates a copy of an existing file.

Usage

CALL "C$COPY"
    USING SOURCE-FILE, DEST-FILE, FILE-TYPE,
    GIVING COPY-STATUS

Parameters

SOURCE-FILE PIC X(n) Contains the name of the file to copy. Remote name notation and "@[DISPLAY]:" notation are allowed for this parameter.

If the file name on the client starts with special directory specifiers, the thin client attempts to locate those files in special Windows directories. The special directory names are as follows:

Identifier | Directory
<APPDATA> | C:\Documents and Settings\<user>\Application Data
<COMMON_APPDATA> | C:\Documents and Settings\All Users\Application Data
<COMMON_DOCUMENTS> | C:\Documents and Settings\All Users\Documents
<DESKTOP> | C:\Documents and Settings\<user>\Desktop
<LOCAL_APPDATA> | C:\Documents and Settings\<user>\Local Settings\Application Data
<MYDOCUMENTS> | C:\Documents and Settings\<user>\My Documents

Note that these directories are not necessarily the same for all versions of Windows, and may in fact be on network drives.

DEST-FILE PIC X(n) | Contains the destination file name. Remote name notation and "@[DISPLAY]:" notation are allowed for this parameter.
FILE-TYPE PIC X (optional) Indicates the file type. If the FILE-TYPE parameter is supplied, it must be either "S", "R", "I", or "T", indicating that the source file is a sequential, relative, indexed file, or text file. Note that the "T" implies that the file is a line sequential file, since copying relative or indexed files as text is counter-intuitive and would likely corrupt those types of files. Copying text files applies when copying between UNIX and Windows systems, where text files have different line terminator characters.

The FILE-TYPE parameter can be useful in cases where the original file is held in more than one physical disk file (for example, C-ISAM indexed files are physically held in two separate files). If the FILE-TYPE parameter is omitted, then only the single physical file named in SOURCE-FILE is copied.

COPY-STATUS Any numeric type | Returns zero if successful, or non-zero if not. Currently, an unsuccessful status code is always 1, but future versions may return additional information.

Description

C$COPY creates an exact duplicate of SOURCE-FILE in DEST-FILE.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

To transfer files between the application host and display host in a thin client environment, add the prefix "@[DISPLAY]:" to the name of any source or destination file that resides on the client machine.

C$COPY "@[DISPLAY]:C:\path\file1.ext" "/usr/data/file1.ext"

To copy from one path on the client to another, specify the "@[DISPLAY]:" prefix for both the SOURCE-FILE and the DEST-FILE.

If you use the "@[DISPLAY]:" prefix, you may not use the FILE-TYPE parameter. Only the single, specified source file is copied.

See the AcuConnect User's Guide for more information about using C$COPY in a thin client environment.

Parent topic: General Syntax and Library List
Related reference
FILENAME_SPACES


C$DARG

C$DARG returns information about an actual parameter passed in the USING phrase in the CALL statement that called a subprogram. This information identifies the type and length of the argument and, when the argument is numeric or numeric edited, the number of digits and scale factor for the argument.

Note: The -Cr compiler option is required for COMPUTATION/COMP usage data items to have the expected type (otherwise they are binary) and also to have a non-integer GIVING/RETURNING item.

Usage

CALL "C$DARG" USING ARGUMENT-NUMBER, ARGUMENT-DESCRIPTION

Parameters

ARGUMENT-NUMBER
The one-relative ordinal position of the actual argument in the USING phrase of the CALL statement used to call the subprogram that calls C$DARG. The value zero obtains the description of the actual argument in the GIVING phrase of that CALL statement. If the value specified is less than zero or greater than the number of actual arguments passed, an argument-description for an omitted argument will be returned (ARGUMENT-TYPE = 32). The actual number of arguments passed can be obtained with the C$NARG subprogram. The actual number of arguments may exceed the number of formal arguments declared in the Procedure Division header of the program that calls C$DARG. All of the actual arguments can be accessed using C$DARG even though there is no formal argument name available for accessing the actual arguments beyond the number of formal arguments.
ARGUMENT-DESCRIPTION
A ten-character group data item into which the desired information about the argument specified by argument-NUMBER is stored. A typical data description for argument-description is as follows:
01 ARGUMENT-DESCRIPTION.
   02 ARGUMENT-TYPE           PIC 9(2)  BINARY(2).
   02 ARGUMENT-LENGTH         PIC 9(8)  BINARY(4).
   02 ARGUMENT-DIGIT-COUNT    PIC 9(2)  BINARY(2).
   02 ARGUMENT-SCALE          PIC S9(2) BINARY(2).

The argument-description group item will have the correct length only if ARGUMENT-TYPE, ARGUMENT-DIGIT-COUNT, and ARGUMENT-SCALE are allocated as two-byte binary and ARGUMENT-LENGTH is allocated as four-byte binary.

The fields in ARGUMENT-DESCRIPTION have the following meanings:

ARGUMENT-TYPE
returns a number indicating the type of the argument data item. The values and meanings for data type numbers returned in this field are shown in the table located in the C$CARG topic.
ARGUMENT-LENGTH
Returns the number of character positions occupied by the argument data item.
ARGUMENT-DIGIT-COUNT
Returns the number of digits defined in the PICTURE character-string for an argument that is a numeric or numeric edited data item as indicated by the ARGUMENT-TYPE field value; otherwise, the value zero is returned for nonnumeric data items. The digit count for a numeric or numeric edited data item does not include any positions defined by the PICTURE symbol P, which represents a scaling position.
ARGUMENT-SCALE
Returns the power of 10 scale factor (that is, the position of the implied or actual decimal point) for an argument that is a numeric or numeric edited data item as indicated by the ARGUMENT-TYPE field value; otherwise, the value zero is returned for nonnumeric data items. If the PICTURE symbol P was used in the description of the data item, the absolute value of the ARGUMENT-SCALE value will exceed the ARGUMENT-DIGIT-COUNT value; in this case, a positive scale value indicates an integer with P scaling positions on the right of the PICTURE character-string and a negative scale value indicates a fraction with P scaling positions on the left of the PICTURE character-string.
Parent topic: General Syntax and Library List


C$DELETE

C$DELETE deletes the indicated file.

Usage

CALL "C$DELETE"
    USING FILE-NAME, FILE-TYPE,
    GIVING STATUS

Parameters

FILE-NAME PIC X(n) Contains the name of the file to be deleted. This should either be a full path name or a name relative to the current directory.

The "@[DISPLAY]:" for Thin Client support is allowed. For example:

C$DELETE "@[DISPLAY]:C:\path\filename"

If the file name on the client starts with special directory specifiers, the thin client attempts to locate those files in special Windows directories. The special directory names are as follows:

Identifier | Directory
<APPDATA> | C:\Documents and Settings\<user>\Application Data
<COMMON_APPDATA> | C:\Documents and Settings\All Users\Application Data
<COMMON_DOCUMENTS> | C:\Documents and Settings\All Users\Documents
<DESKTOP> | C:\Documents and Settings\<user>\Desktop
<LOCAL_APPDATA> | C:\Documents and Settings\<user>\Local Settings\Application Data
<MYDOCUMENTS> | C:\Documents and Settings\<user>\My Documents

Note that these directories are not necessarily the same for all versions of Windows, and may in fact be on network drives.

FILE-TYPE PIC X (optional) Indicates the file type. If the FILE-TYPE parameter is supplied, it must be either "S", "R", or "I" indicating that the source file is a sequential, relative, or indexed file. This can be useful in cases where the original file is held in more than one physical disk file (for example, C-ISAM indexed files and Vision 4 and 5 files are physically held in two separate files). If the FILE-TYPE parameter is omitted, then only the single physical file named in FILE-NAME is deleted.

If you use the "@[DISPLAY]:" prefix, you may not use the FILE-TYPE parameter. Only the single, specified source file is deleted.

STATUS PIC 9(n) Returns 0 if successful, or 1 if not.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

Parent topic: General Syntax and Library List
Related reference
FILENAME_SPACES


C$DISCONNECT

C$DISCONNECT disconnects the executing AcuServer client from the specified server at the time of the call.

Under normal circumstances, the AcuServer client disconnects from the server automatically (without requiring you to call the C$DISCONNECT routine) at shutdown. Also, whenever a server loses its connection to a client, before a new connection is made, all old client connections are automatically closed.

Usage

CALL "C$DISCONNECT"
    USING SERVER-NAME, PORT-NUMBER
    GIVING STATUS

Parameters

SERVER-NAME PIC X(n)

Contains the name of the server computer from which you are disconnecting. The name will be terminated at the first space character.

PORT-NUMBER PIC 9(n) (optional)

Specifies the port number of SERVER-NAME. If omitted, this parameter defaults to the value of the configuration variable ACUSERVER-PORT.

STATUS PIC 9(n)

This routine returns the one of the following status codes after the operation has been performed:

0 | Client is now disconnected from the server
1 | Server/port combination was not found; no such connection
2 | Client access is not enabled

Comments

Any open files on the server should be closed before calling this routine. When these files are reopened, it is as if the original connection had never existed. In particular, any passwords needed to connect to the server will need to be reentered by the user.

Parent topic: General Syntax and Library List


C$EXCEPINFO

C$EXCEPINFO retrieves information about an object exception that has been raised.

Usage

CALL "C$EXCEPINFO"
   USING ERROR-INFO, ERR-SOURCE, ERR-DESCRIPTION,
       ERR-HELP-FILE, ERR-HELP-CONTEXT, ERR-OBJECT-HANDLE,
       ERR-CONTROL-ID

Parameters

ERROR-INFO
Group item to receive returned information.

ERROR-INFO must have the following structure (defined in activex.def):

01 ERROR-INFO.
   03 ERROR-INFO-RESULT USAGE UNSIGNED-INT.
   03 ERROR-INFO-FACILITY USAGE UNSIGNED-SHORT.
   03 ERROR-INFO-CODE USAGE UNSIGNED-SHORT.
ERROR-INFO is described Comments in this topic.
ERR-SOURCE PIC X(n) (optional)
A text string identifying the source of the exception. Typically, this is an application name.
ERR-DESCRIPTION PIC X(n) (optional)
A text description of the error intended for the user. If no description is available, ERR-DESCRIPTION is filled with spaces.
ERR-HELP-FILE PIC X(n) (optional)
The fully qualified drive, path, and file name of a help file with more information about the error. If no help is available, ERR-HELP-FILE is filled with spaces.
ERR-HELP-CONTEXT Usage unsigned-long (optional)
The help context ID of the topic within the help file. This parameter is filled in only if the ERR-HELP-FILE parameter is not spaces. The help context ID will be between 0 and 4294967295.
ERR-OBJECT-HANDLE Usage handle (optional)
The handle of the COM object or ActiveX control that generated the exception.
ERR-CONTROL-ID Usage PIC XX COMP-X (optional)
The ID of the ActiveX control that generated the exception. The value is 0 if the object that generated the exception is not an ActiveX control.

Comments

C$EXCEPINFO is typically called from an error handling procedure specified with a Format 2 USE statement in the declaratives.

The following are the parameters for the ERROR-INFO group item:

ERROR-INFO-RESULT
is a 32-bit number identifying the error. The error number will be greater than 1000 and less than 4294967296. This error number is divided into 4 fields: a severity code, a reserved portion, a facility field, and an error code.
FACILITY-ACU (4) | For status codes of exceptions raised by the ACUCOBOL-GT runtime.
FACILITY-ACTIVE-X (10) | For status codes of exceptions raised by an ActiveX control.

The severity code is the high-order bit (31). The next 4 bits are reserved (30-27). The next eleven bits are the facility field (26-16), and the last sixteen bits are the error code (15-0). The severity code is usually 1, and the reserved bits are usually set to 0. The error code is defined by the facility that raised the exception. The facility field is one of the following:

The standard facility field values and error codes are defined as condition names (level 88) in activex.def.

Note: If you receive a facility value that is anything other than the two listed above, you will need to look up the ERROR-INFO result number in the documentation for the specific ActiveX control you are using or in Microsoft’s documentation.
ERROR-INFO-FACILITY

contains the facility field extracted from ERROR-INFO-RESULT.

ERROR-INFO-CODE

contains the error code extracted from ERROR-INFO-RESULT. ERROR-INFO-CODE will be listed in the ACUCOBOL-GT error codes if the facility field is FACILITY-ACU. If the facility is FACILITY-ACTIVE-X, the ERROR-INFO-CODE may be listed in an enumeration in the ActiveX control’s COPY file or it may be one of the standard COM status codes for ActiveX controls.

When called to get information about an object exception, the error code can either be an ACUCOBOL-GT defined code or a COM status code.

ACUCOBOL-GT Error Codes (defined in activex.def):

Name | Description
ACU-E-UNEXPECTED | Unexpected error
ACU-E-INVALIDPARAMNAME | Invalid parameter name
ACU-E-INVALIDHANDLE | Invalid handle
ACU-E-INITIALSTATE | Error loading INITIAL-STATE from resource file
ACU-E-NOEXCEPINFO | No exception information available
ACU-E-INVALIDPROPNUM | Invalid property number
ACU-E-TOOMANYPARAMS | Too many parameters
ACU-E-TOOFEWPARAMS | Too few parameters
ACU-E-NOTPROPERTYGET | Property can be modified but not inquired
ACU-E-NOTPROPERTYPUT | Property can be inquired but not modified
ACU-E-CREATE | Error creating ActiveX control
COM Status Codes for ActiveX controls (defined in activex.def):
Name | Description
AX-E-ILLEGALFUNCTIONCALL | Illegal function call
AX-E-OVERFLOW | Overflow
AX-E-OUTOFMEMORY | Out of memory
AX-E-DIVISIONBYZERO | Division by zero
AX-E-OUTOFSTRINGSPACE | Out of string space
AX-E-OUTOFSTACKSPACE | Out of stack space
AX-E-BADFILENAMEORNUMBER | Bad file name or number
AX-E-FILENOTFOUND | File not found
AX-E-BADFILEMODE | Bad file mode
AX-E-FILEALREADYOPEN | File already open
AX-E-DEVICEIOERROR | Device I/O error
AX-E-FILEALREADYEXISTS | File already exists
AX-E-BADRECORDLENGTH | Bad record length
AX-E-DISKFULL | Disk full
AX-E-BADRECORDNUMBER | Bad record number
AX-E-BADFILENAME | Bad file name
AX-E-TOOMANYFILES | Too many files
AX-E-DEVICEUNAVAILABLE | Device unavailable
AX-E-PERMISSIONDENIED | Permission denied
AX-E-DISKNOTREADY | Disk not ready
AX-E-PATHFILEACCESSERROR | Path/file access error
AX-E-PATHNOTFOUND | Path not found
AX-E-INVALIDPATTERNSTRING | Invalid pattern string
AX-E-INVALIDUSEOFNULL | Invalid use of NULL
AX-E-INVALIDFILEFORMAT | Invalid file format
AX-E-INVALIDPROPERTYVALUE | Invalid property value
AX-E-INVALIDPROPERTYARRAYINDEX | Invalid property array index
AX-E-SETNOTSUPPORTEDATRUNTIME | Set not supported at run time
AX-E-SETNOTSUPPORTED | Set not supported (read-only property)
AX-E-NEEDPROPERTYARRAYINDEX | Need property array index
AX-E-SETNOTPERMITTED | Set not permitted
AX-E-GETNOTSUPPORTEDATRUNTIME | Get not supported at run time
AX-E-GETNOTSUPPORTED | Get not supported (write-only property)
AX-E-PROPERTYNOTFOUND | Property not found
AX-E-INVALIDPICTURE | Invalid clipboard format
AX-E-PRINTERERROR | Printer error
AX-E-CANTSAVEFILETOTEMP | Can’t save file to TEMP
AX-E-SEARCHTEXTNOTFOUND | Search text not found
AX-E-REPLACEMENTSTOOLONG | Replacements too long

For an example of how this works, let’s look at the standard COM error code for Out of Memory.

The code is hex 800A0007.

In binary this is “1000 0000 0000 1010 0000 0000 0000 0111”.

This error code can be broken down as follows:

1 | 000 0 | 000 0000 1010 | 0000 0000 0000 0111
Severity Code | Reserved | Facility Field | Error Code

The severity code is 1 which makes ERROR-INFO-RESULT greater than or equal to 2147483648 (hex 80000000). The reserved portion is 0. The facility code is 10 (hex A) which is defined in activex.def as FACILITY-ACTIVE-X. The error code is 7 (hex 7) which is defined in activex.def as AX-E-OUTOFMEMORY.

Example

DATA DIVISION.
WORKING-STORAGE SECTION.
COPY "ACTIVEX.DEF"
77 ERR-SOURCE           PIC X(30).
77 ERR-DESCRIPTION      PIC X(200).
77 ERR-HELP-FILE        PIC X(200).
77 ERR-HELP-CONTEXT     USAGE UNSIGNED-LONG.
77 CHOICE               PIC 9.

PROCEDURE DIVISION.
DECLARATIVES.
OBJECT-EXCEPTION-HANDLING SECTION.
    USE AFTER EXCEPTION ON OBJECT.
OBJECT-EXCEPTION-HANDLER.
    CALL "C$EXCEPINFO" USING ERROR-INFO, ERR-SOURCE,
        ERR-DESCRIPTION, ERR-HELP-FILE,
        ERR-HELP-CONTEXT.
    IF ERR-HELP-FILE = SPACES THEN
        DISPLAY MESSAGE BOX ERR-DESCRIPTION
            TITLE ERR-SOURCE
            ICON MB-ERROR-ICON
    ELSE
        DISPLAY MESSAGE BOX ERR-DESCRIPTION H'0d'
            "Do you want help ?"
            TITLE ERR-SOURCE
            ICON MB-ERROR-ICON
            TYPE IS MB-YES-NO
            DEFAULT IS MB-YES
            GIVING CHOICE
    IF CHOICE = 1 THEN
        CALL "$WINHELP" USING ERR-HELP-FILE, HELP-CONTEXT
            ERR-HELP-CONTEXT
    END-IF
END-IF.
EVALUATE TRUE
    WHEN FACILITY-ACU
        EVALUATE TRUE
            WHEN ACU-E-UNEXPECTED
                STOP RUN
            END-EVALUATE
        END-EVALUATE.
END DECLARATIVES.

MAIN-PROGRAM SECTION.
{ . . . }
* The following line causes an AX-E-SETNOTSUPPORTEDATRUNTIME
* exception since Microsoft Chart's BorderStyle property is not
* allowed to be modified at runtime
    MODIFY MS-CHART-1 BorderStyle = VtBorderStyleBold.
Parent topic: General Syntax and Library List


C$EXITINFO

The C$EXITINFO library routine returns information about an exit from an END procedure in the declaratives.

Usage

CALL "C$EXITINFO"
    USING EXIT-MESSAGE, EXIT-CODE, OS-EXIT-CODE, SIGNAL-NUMBER

Parameters

EXIT-MESSAGE Alphanumeric | Contains the lines of text that the runtime outputs to the error file or shutdown message box. Each line of text is separated by a newline character H'0A'.
EXIT-CODE Numeric (optional) Contains one of the following codes (listed in lib/sub.h):
    1     COBOL_EXIT_PROGRAM
    2     COBOL_REMOTE_CALL
    3     COBOL_STOP_RUN
    4     COBOL_CALL_ERROR
    5     COBOL_SIGNAL
    6     COBOL_FATAL_ERROR
    7     COBOL_NONFATAL_ERROR
    8     COBOL_DEBUGGER
OS-EXIT-CODE Numeric (optional) | Contains the value that the process passes to the system exit routine
SIGNAL-NUMBER Numeric (optional) | This is always 0 on Windows. On UNIX, it contains the signal number if EXIT-CODE is 5 (COBOL_SIGNAL).
Parent topic: General Syntax and Library List


C$FILEINFO

C$FILEINFO retrieves some operating system information about a given file.

Usage

CALL "C$FILEINFO"
    USING FILE-NAME, FILE-INFO,
    GIVING STATUS-CODE

Parameters

FILE-NAME PIC X(n) | Contains the name of the file to check. This should either be a full path name or a name relative to the current directory. Remote name notation and "@[DISPLAY:]" notation are allowed for this parameter. If run in standalone mode, and the "@[DISPLAY]" syntax is used, the file will be searched for on the local machine.
FILE-INFO Group item to receive returned information. FILE-INFO must have the following structure:
01  FILE-INFO.
    02  FILE-SIZE    PIC X(8) COMP-X.
    02  FILE-DATE    PIC 9(8) COMP-X.
    02  FILE-TIME    PIC 9(8) COMP-X.
STATUS-CODE Any numeric data item. | This receives the return status. It will be zero if successful, or "1" if the file does not exist or is not a regular disk file.

Description

This routine checks to see if the passed file exists and is a regular disk file. If it is, then FILE-INFO is filled in with the appropriate information. The FILE-SIZE field is the size of the file in bytes. The FILE-DATE and FILE-TIME fields indicate the time the file was last modified. FILE-DATE has the form YYYYMMDD (year/month/day, note the 4-digit year) and FILE-TIME has the form HHMMSShh (hours/minutes/seconds/hundredths--just like ACCEPT FROM TIME). On all current implementations, the hundredths field is always set to zero.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

Parent topic: General Syntax and Library List
Related reference
FILENAME_SPACES


C$FILESYS

C$FILESYS performs one of three functions, depending on the operations code passed to it. It retrieves the names of file systems known to the runtime, determines whether a particular file system is known, or returns a count of all known file systems.

Usage

CALL "C$FILESYS"
    USING OP-CODE, FILE-SYSTEM

Parameters

OP-CODE PIC 9 | The value indicates the desired operation.
FILE-SYSTEM PIC X(5) | Passes or returns a file system name. The names that are recognized are up to five characters long and are listed in the program filetbl.c, which is linked into the runtime. (For example, use visio for Vision, infor for Informix, oracl for Oracle, and "sybas" for Sybase.)

Comments

This routine can determine which file systems are known to the runtime, and can give a count of known systems.

The file system names are up to five characters long, and are listed in filetbl.c, which must be linked into the runtime. The (activated) names listed in filetbl.c are the names that are returned by this routine, and the only names that the routine recognizes.

If OP_CODE is 0, both parameters are required. The routine returns the first file system known to the runtime and gets set up to return the rest. RETURN-CODE will be set to 1 if there was a file system to return, or 0 if not.

If op-code is 1, both parameters are required. The routine returns the next file system known to the runtime. RETURN-CODE is set to 1 if there was a file system to return, or 0 if not (there are no more). You can call the routine with this parameter repeatedly, until RETURN-CODE is set to 0.

If op-code is 2, both parameters are required. The routine checks to see if the passed file system is known to the runtime. You must pass one of the names used in the program filetbl.c. (The routine checks only the first five characters of the name you pass; the rest are ignored.) The case of the name does not matter. For example, SYBAS and sybas are equivalent. RETURN-CODE is set to 1 if yes, or 0 if no.

If op-code is 3, the second parameter is not required. RETURN-CODE is set to the number of known file systems.

Parent topic: General Syntax and Library List


C$FULLNAME

This routine locates a file by using the runtime's filename translation and search logic, and returns the full name of the corresponding file.

Usage

CALL "C$FULLNAME"
    USING FILE-NAME, FULL-NAME, FILE-INFO
    GIVING STATUS-CODE

Parameters

FILE-NAME PIC X(n) | Specifies the name of the file to be located.
FULL-NAME PIC X(n) | Data item to receive the full name of the file.
FILE-INFO Group item (optional) Group item to receive information about the file located. Must have this structure:
01  FILE-INFO.
    02  FILE-SIZE    PIC X(8) COMP-X.
    02  FILE-DATE    PIC 9(8) COMP-X.
    02  FILE-TIME    PIC 9(8) COMP-X.

The FILE-SIZE field is the size of the file in bytes. The FILE-DATE and FILE-TIME fields indicate the time the file was last modified. FILE-DATE has the form YYYYMMDD (year/month/day, note the 4-digit year) and FILE-TIME has the form HHMMSShh (hours/minutes/seconds/hundredths--just like ACCEPT FROM TIME). On all current implementations, the hundredths field is always set to zero.

STATUS-CODE Any numeric data item. | This receives the return status. It will be zero if successful, or 1 if FILE-NAME could not be found on disk or if FILE-NAME is not the name of a regular disk file.

Description

C$FULLNAME invokes the runtime's data file search logic on FILE-NAME. This involves using the configuration variables FILE_PREFIX, FILE_SUFFIX and FILE_CASE. The disk is searched using the rules described in File Name Interpretation . The first matching file is returned in FULL-NAME. Note that the returned name is not automatically a full path name. Instead, it is the name of the file as the runtime found it. This may be based on the current directory.

If FILE-INFO is specified, information about the file located is returned in it.

Note: The search techniques do not involve any file system specific techniques. For example, the Vision file system has a name mapping facility for its additional segments. This facility is not used when the runtime is searching for the file. Also note that remote file names are searched for when used in conjunction with AcuServer.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

Parent topic: General Syntax and Library List
Related reference
File Name Interpretation
FILENAME_SPACES
FILE_CASE
FILE_SUFFIX
FILE_PREFIX


C$GETCGI

The C$GETCGI routine retrieves CGI (Common Gateway Interface) variables.

Usage

CALL "C$GETCGI"
    USING VARIABLE-NAME, DEST-ITEM, VALUE-INDEX
    GIVING VALUE-SIZE

Parameters

VARIABLE-NAME PIC X(n) | Contains the name of the CGI variable.
DEST-ITEM PIC X(n) | Receives the value of the given CGI variable.
VALUE-INDEX Numeric value | Contains the CGI value index. This optional parameter contains an index that is used when a CGI variable has multiple values in the CGI input data. This typically happens when multiple items have been selected from a choose many list box. For example, to receive the third selected value, pass 3 for VALUE-INDEX. If VALUE-INDEX is greater than the total number of values in the input stream for the given CGI variable, then spaces are moved to DEST-ITEM.
VALUE-SIZE Signed numeric value | Receives the size of the resulting value. This may be 0 to indicate that the variable exists but has no value, or -1 to indicate that the variable does not exist.

Description

This library routine is intended to be called from COBOL CGI scripts to retrieve CGI variables from either the environment or the standard input stream, stdin.

C$GETCGI automatically determines whether to read the CGI variable from the environment or stdin depending on the value of the REQUEST_METHOD environment variable, which is set by the Web Server. The first time C$GETCGI is called, it reads all of the CGI variables and values into a variable length buffer. If REQUEST_METHOD is GET, then the data is read from the QUERY_STRING environment variable. If the REQUEST_METHOD is POST, then it is read from stdin.

Each time C$GETCGI is called, it searches for the variable name passed in the first parameter, translates the value from CGI format into standard format, and moves the result to the destination item passed in the second parameter. An optional third parameter specifies a CGI value index. This index is used when a CGI variable has multiple values in the CGI input data, such as the case where multiple items have been selected from a choose-many list.

The size of the resulting value is returned in the special RETURN-CODE register. This may be 0 to indicate that the variable has no value or -1 to indicate that the variable does not exist. The value of RETURN-CODE is moved to VALUE-SIZE.

The value is truncated to the size of the destination item.

You may use C$GETCGI instead of or in combination with external forms. Use C$GETCGI if you must know the exact size of a CGI variable or if you are converting an existing COBOL CGI program.

Parent topic: General Syntax and Library List


C$GETERRORFILE

This routine returns the name of the runtime error file as specified with the runtime -e command-line option or with a call to the C$SETERRORFILE routine.

Usage

CALL "C$GETERRORFILE"
    USING ERROR-FILE-NAME

Parameters

ERROR-FILE-NAME PIC X(n) Contains the name of the error file or spaces if no error file was specified.
Parent topic: General Syntax and Library List


C$GETEVENTDATA

When an ActiveX control or COM object generates an event, it makes information about the event available through event parameters. These parameters are stored in the control and can be retrieved by calling C$GETEVENTDATA from the control's event procedure.

Usage

CALL "C$GETEVENTDATA"
    USING EVENT-CONTROL-HANDLE, DEST-ITEM-1, [DEST-ITEM-2, ...]
    GIVING RESULT-CODE

Parameters

EVENT-CONTROL-HANDLE USAGE HANDLE | Handle to the control that generated the event.
DEST-ITEM-1 Any COBOL data type | The first destination data item.
DEST-ITEM-2, ... Any COBOL data type (optional) | Any number of destination items.
RESULT-CODE Signed numeric value | Receives the result-code for the operation. This will be 0 to indicate success or a negative value to indicate failure. (Microsoft defines many standard result codes in their documentation. Note that these are usually in hexadecimal notation.)

Comments

C$GETEVENTDATA converts the event parameters to COBOL-type data in the destination items.

You are responsible for specifying compatible types. For instance, if the event parameter is a character string and you specify a numeric item to receive its value, C$GETEVENTDATA will try to read a number from the string and move it to your numeric item. This is not a programming error and neither the compiler nor runtime will warn you about it.

Example

Suppose you have displayed an ActiveX control that triggers an event called AxEventOne which has three parameters. You would use the following COBOL syntax to get the event parameters into data items PARAM-1, PARAM-2 and PARAM-3:

WHEN AxEventOne
  CALL "C$GETEVENTDATA" USING EVENT-CONTROL-HANDLE,
     PARAM-1, PARAM-2, PARAM-3

For more examples of how to get event parameters for ActiveX events, see ActiveX and COM Events.

Parent topic: General Syntax and Library List


C$GETEVENTPARAM

C$GETEVENTPARAM is an alternate way to get event parameters for ActiveX controls. Use it to get a single event parameter when there are several for an event. To use this routine you must know the actual name of the parameter. You may determine these names by reading the ActiveX control's documentation or by looking at the definitions in the copy book for the ActiveX control.

It is common for an ActiveX event to receive many parameters. C$GETEVENTPARAM allows you to get the values of only the parameters you care about.

Note that C$GETEVENTPARAM cannot be used to get event parameters for COM objects. You must use C$GETEVENTDATA for COM objects.

Usage

CALL "C$GETEVENTPARAM"
    USING EVENT-CONTROL-HANDLE, PARAM-NAME, PARAM-VALUE
    GIVING RESULT-CODE

Parameters

EVENT-CONTROL-HANDLE USAGE HANDLE | Handle to the control that generated the event.
PARAM-NAME PIC X(n) | The symbolic name of the event parameter.
PARAM-VALUE Any COBOL data type | Destination item to receive the event parameter's value.
RESULT-CODE Signed numeric value | Receives the result-code for the operation. This will be 0 to indicate success or a negative value to indicate failure. (Microsoft defines many standard result codes in their documentation. Note that these are usually in hexadecimal notation.)

Comments

C$GETEVENTPARAM converts the named event parameter's value to COBOL-type data in the destination item. Using this routine instead of C$GETEVENTDATA will make your code more readable. The object code will be a little larger and calls to this routine will take a little longer than calls to C$GETEVENTDATA. However, these differences will probably be unnoticeable and the benefits of readable code outweigh the performance and size considerations.

You are responsible for specifying a compatible types. For example, if the event parameter is a character string and you specify a numeric item to receive its value, C$GETEVENTPARAM will try to read a number from the string and move it to your numeric item. This is not a programming error and neither the compiler nor runtime will warn you about it.

Example

Suppose you have displayed an ActiveX control that triggers an event called AxEventOne which has three parameters. Then suppose that you only need to know the value of PARAM-2. Since PARAM-2 is the second parameter, to get its value you would have to pass a "dummy" first parameter using C$GETEVENTDATA. For example:

CALL "C$GETEVENTDATA" USING EVENT-CONTROL-HANDLE, 0, PARAM-2.

However, if you determined that the name of PARAM-2 in the ActiveX control was Param2. You could then use C$GETEVENTPARAM to accomplish this task in a more elegant and readable way. For example:

CALL "C$GETEVENTPARAM"
    USING EVENT-CONTROL-HANDLE, "Param2", PARAM-2.

For more examples of how to get event parameters for ActiveX events, see ActiveX and COM Events.

Parent topic: General Syntax and Library List


C$GETLASTFILEOP

C$GETLASTFILEOP retrieves information about the last file operation performed.

Usage

CALL "C$GETLASTFILEOP"
    USING OPERATION, ADDR, X-ADDR

Parameters

OPERATION PIC X(n)

Receives the name of the last file operation performed in the current thread. If the current thread has not performed any file operations, then OPERATION is set to spaces. The possible values are:

Close | ReadPreviousLock
Commit | ReadPreviousNoLock
Delete | Rewrite
DeleteFile | Rollback
Open | Start
ReadLock | StartTransaction
ReadNextLock | Unlock
ReadNextNoLock | UnlockAll
ReadNoLock | Write

If the current thread has not performed any file operations, then OPERATION is set to spaces.

ADDR Numeric (optional)

Receives the virtual address of the instruction that performed the last file operation in the current thread. If no operation has been performed, zero is returned.

X-ADDR PIC X(n) (optional)

Receives a 6-character string that contains the hexadecimal equivalent of the value returned in ADDR.

Description

C$GETLASTFILEOP should be called from Declaratives when an unexpected I/O error has occurred. The return values can be useful in some debugging or customer support scenarios.

The ADDR parameter is provided primarily for compatibility with other COBOL systems. You would normally convert the value returned by ADDR to hexadecimal and look up the result in the program's compiler listing. As a convenience, the X-ADDR parameter performs the hexadecimal conversion for you. You can omit the ADDR parameter by specifying "NULL" or "OMITTED" in the CALL statement, for example:

77  FILE-OP     PIC X(20).
77  X-ADDR      PIC X(6).
CALL "C$GETLASTFILEOP" USING FILE-OP, NULL, X-ADDR

This routine always returns a value of 0 for ADDR and X-ADDR when called by a Version 5.1, or earlier, native-code object file. Non-native object files return correct values regardless of version.

Parent topic: General Syntax and Library List


C$GETNETEVENTDATA

When a .NET assembly generates an event, it makes information about the event available through event parameters. These parameters are stored in the assembly and can be retrieved by calling C$GETNETEVENTDATA from the assembly's event procedure.

Usage

CALL "C$GETNETEVENTDATA"
    USING EVENT-CONTROL-HANDLE, DEST-ITEM-1, [DEST-ITEM-2, ...]
    GIVING RESULT-CODE

Parameters

EVENT-CONTROL-HANDLE USAGE HANDLE | Handle to the .NET assembly that generated the event.
DEST-ITEM-1 Any COBOL data type | The first destination data item.
DEST-ITEM-2, ... Any COBOL data type (optional) | Any number of destination items.
RESULT-CODE Signed numeric value | Receives the result-code for the operation. This will be 0 to indicate success or a negative value to indicate failure. (Microsoft defines many standard "result codes" in their documentation. Note that these are usually in hexadecimal notation.)

Comments

C$GETNETEVENTDATA converts the event parameters to COBOL-type data in the destination items.

You are responsible for specifying compatible types. For instance, if the event parameter is a character string and you specify a numeric item to receive its value, C$GETNETEVENTDATA will try to read a number from the string and move it to your numeric item. This is not a programming error and neither the compiler nor runtime will warn you about it.

Example

Suppose you have displayed a .NET assembly that triggers an event called NetEventOne that has three parameters. You would use the following COBOL syntax to get the event parameters into data items PARAM-1, PARAM-2 and PARAM-3:

WHEN NetEventOne
   CALL "C$GETNETEVENTDATA" USING EVENT-CONTROL-HANDLE,
      PARAM-1, PARAM-2, PARAM-3
Parent topic: General Syntax and Library List


C$GETPID

This routine returns the Process ID (PID) of the current process. This PID can be compared with the PID returned by the C$LOCKPID to determine if the current process is the one holding a file lock or record locked condition.

Usage

CALL "C$GETPID"
    GIVING PROCESS-ID.

Parameters

PROCESS-ID PIC 9(n) This contains a numeric data item large enough to hold a PID. On most platforms, PIC 9(5) is sufficient. On 64-bit systems, PIC 9(7) is recommended.

Comments

When called from a non-UNIX or non-Windows runtime, C$GETPID returns a PROCESS-ID of "0". This behavior should not be used for system identification. Use ACCEPT ... FROM SYSTEM-INFO instead.

Parent topic: General Syntax and Library List


C$GETVARIANT

This routine retrieves data referenced by a Variant handle. Typically, this is data passed to an ACUCOBOL-GT program from another language such as Visual Basic. Note that there is also a C$SETVARIANT routine that sets data items referenced by Variant handles

C$GETVARIANT converts Variant type data to COBOL type data. Programs that call ACUCOBOL-GT using the ACUCOBOL-GT Automation Server or runtime DLL pass their parameters (by reference) as Variant types. The COBOL program receives handles to the Variant data. C$GETVARIANT gets the data associated with a particular handle and moves it to a COBOL data item. The data is automatically converted to the proper COBOL format.

Usage

CALL "C$GETVARIANT"
    USING H-VARIANT, DEST-ITEM
    GIVING RESULT-CODE

Parameters

H-VARIANT USAGE HANDLE | Handle to Variant type data. Data passed in from a program calling ACUCOBOL-GT using the ACUCOBOL-GT Automation Server or runtime DLL is in the form of handles to Variant type data.
DEST-ITEM Any COBOL data type | The destination data item.
RESULT-CODE Signed numeric value | Receives the result code for the operation. This will be 0 or a positive value to indicate success or a negative value to indicate failure. Under Microsoft Windows this is a code of type HRESULT that can be looked up in Microsoft documentation to determine the reason for the failure or additional information about the success.

Comments

The Variant data associated with H-VARIANT is moved to DEST-ITEM using standard MOVE rules. Data items must be defined in the LINKAGE section.

C$GETVARIANT is not supported by the ACUCOBOL-GT Thin Client technology, and will only run with a standalone Windows runtime.

Parent topic: General Syntax and Library List


C$JAVA

This routine enables your ACUCOBOL-GT program to invoke a Java program. It causes the Java Virtual Machine (JVM) to be loaded (if it is not already) and the specified Java class to be loaded.

Using this routine, you can create a Java object, call the methods of a Java object, create and use Java arrays, and use Java logging.

COBOL/Java interoperability is described in Working with Java Technology. Calling the C$JAVA Routine provides detailed information and best practices for working with the C$JAVA routine.

Usage

CALL "C$JAVA"
    USING OP-CODE, CLASS-NAME, METHOD-NAME, METHOD-SIGNATURE,
        FIELD-INT, FIELD-RETURN
    GIVING STATUS-VAL
Note: To call Java via the C$JAVA routine, HP-UX users must relink the runtime so that it is statically linked to libjvm.sl. To do this, modify lib/Makefile (uncommenting and editing the lines regarding relinking for Java), then run make to relink the runtime.

Parameters

OP-CODE Numeric parameter | Specifies the operation to perform.
CLASS-NAME Alphanumeric data item or literal | Specifies the fully qualified class name, with package name if necessary, of the Java class to load.
METHOD-NAME Alphanumeric data item or literal | Specifies the name of the specific method in the Java class that you want to call.
METHOD-SIGNATURE Alphanumeric data item or literal | Specifies the method signature ID of the exact method to be called. You can get this value by running the Java utility "javap.exe"on the desired jar file or class. This utility comes with the Java JRE and automatically produces the exact signature of a given method. You can copy and paste this signature ID into your CALL "C$JAVA" statement. You can also determine this value manually as described in Method Signatures - ACU.
FIELD-INT Numeric parameter | Specifies the input parameters that the method requires.
FIELD-RETURN Numeric parameter | Specifies the parameter to hold the Java return value from the method.
STATUS-VAL Numeric parameter Specifies a status value be returned after the call is complete. Possible return values are:
CJAVA-SUCCESS           VALUE 0.
CJAVA-INVALIDARG        VALUE -1.
CJAVA-INVALIDSIGNATURE  VALUE -2.
CJAVA-CLASSNOTFOUND     VALUE -3.
CJAVA-METHODNOTFOUND    VALUE -4.
CJAVA-INVALIDPARAMTYPE  VALUE -5.
CJAVA-JAVALIBNOTLOADED  VALUE -6.
CJAVA-MEMNOTALLOC       VALUE -7.
CJAVA-INVALIDOPCODE     VALUE -8.
CJAVA-NOMEMORY          VALUE -9.
CJAVA-METHODFAILED      VALUE -10.
CJAVA-MISSINGPARAM         VALUE -11.
CJAVA-INVALIDINDEX         VALUE -12.
CJAVA-EXCEPTIONOCCURRED    VALUE -13.

CJAVA-MISSINGPARAM is returned if a required value is not passed into a Java method. For example, say a method required five parameters, but only four were passed in.

CJAVA-INVALIDINDEX is returned if the region specified is not in the array or the region is larger or goes past the end of the array.

CJAVA-EXCEPTIONOCCURRED is returned when a Java exception was thrown during the call to C$JAVA. Use the CJAVA-GETEXCEPTIONOBJECT op-code to obtain the object of the Java exception.

Description

In all of the op-codes below, you can pass either the constant name or numeric value shown in parentheses. A java.def file is located in the sample/def directory where you installed ACUCOBOL-GT. It contains the op-codes for C$JAVA, as well as array types and return values. You can include the file java.def in your COBOL program using the following statement if the java.def file is located in the same directory as the .cbl file:

   working-storage section.
   COPY "java.def".

CJAVA-NEW (op-code 1)

Create a new Java object on the local Java Virtual Machine (JVM). You must pass a fully qualified package/classname. Use the GIVING statement to return the object handle. For example:

CALL "C$JAVA" USING CJAVA-NEW, "MyJavaClass", GIVING OBJECT-HANDLE.

CJAVA-DELETE (op-code 2)

Delete an existing Java object.

CJAVA-CREATE (op-code 3)

Create a new Java object. This is the same as using the CJAVA-NEW op-code. See op-code 1 for more details.

CJAVA-DESTROY (op-code 4)

Destroy a Java object. You must pass a valid object handle:

CALL "C$JAVA" USING CJAVA-DESTROY, OBJECT-HANDLE
   GIVING STATUS-VAL.

See Creating and Using Java Objects in COBOL for more information.

CJAVA-INVOKE (op-code 7)

Same as CJAVA-CALLSTATIC. See op-code 10 for details.

CJAVA-CALL (op-code 8)

Call a virtual Java method. For example:

CALL "C$JAVA" USING CJAVA-CALL, OBJECT-HANDLE, "CobolCallingJavaStringV", "(X)X", FIELD-STRING, FIELD-STRINGRET GIVING STATUS-VAL.

Note that the object handle and method name are passed, but the class name is not required. Because an object handle has already been created, C$JAVA knows what type the handle is.

Methods can be called as static methods, virtual methods, or non-virtual methods by using op-codes 8 -10. If an op-code is not used, the default runtime behavior is to attempt to call the method statically, and then as a virtual method by attempting to create an object using a default constructor. A non-virtual method is called on the specific object that is being used. A virtual method can be called on a method that is inherited from one of the object's superclasses.

CJAVA-CALLNONVIRTUAL (op-code 9)

Call a non-virtual Java method on the specific object that is being used. For example:

CALL "C$JAVA" USING CJAVA-CALLNONVIRTUAL, OBJECT-HANDLE, "CobolCallingJavaStringV", "(X)X", FIELD-STRING, FIELD-STRINGRET GIVING STATUS-VAL.

CJAVA-CALLSTATIC (op-code 10)

Call a static Java method. For example:

CALL "C$JAVA" USING CJAVA-CALLSTATIC, "acuCobolGT/CAcuCobol",
   "CobolCallingJavaDouble", "(D)D",
   FIELD-DOUBLE, FIELD-DOUBLERET
   GIVING STATUS-VAL

Note that you can call static methods directly without having to create an object first.

See Calling Methods on Java Objects for additional details.

CJAVA-NEWARRAY (op-code 11)

Create a new Java array. This is the same as using the CJAVA-CREATEARRAY op-code. See op-code 18 for more details. See Creating and Using Java Arrays in COBOL for more information.

CJAVA-DESTROYARRAY (op-code 12)

Destroy a Java array. See Creating and Using Java Arrays in COBOL for more information.

CJAVA-SETARRAYELEMENT (op-code 13)

Set Java array elements. Pass in an array handle, the position in the array to set, and the value to set. In the following example, the first element of an array is set with the first value from an integer table that is USAGE IS SIGNED-INT OCCURS 10.

CALL "C$JAVA" USING CJAVA-SETARRAYELEMENT, ARRAY-HANDLE, 1, INT-TABLE(1), GIVING STATUS-VAL.
Note: Although Java array elements start at 0, COBOL arrays start at "1". Because C$JAVA is a COBOL statement, the SETARRAYELEMENT and GETARRAYELEMENT op-codes, and all array access from C$JAVA, use "1" as the beginning of the array.

CJAVA-GETARRAYELEMENT (op-code 14)

Get a Java array element. This call requires an array handle, the position in the array to get, and the variable into which the array value will be placed. Here is an example:

CALL "C$JAVA" USING CJAVA-GETARRAYELEMENT,
   ARRAY-HANDLE, 5, INT-TABLE(1),
   GIVING STATUS-VAL.

In this case, we are getting element 5 from the array and placing it in the first element of an integer table.

See Creating and Using Java Arrays in COBOL for more information.

CJAVA-CLEARARRAY (op-code 15)

Clear a Java array. Pass in the array handle of the array to be cleared. Here is an example:

CALL "C$JAVA" USING CJAVA-CLEARARRAY, ARRAY-HANDLE
   GIVING STATUS-VAL.

CJAVA-CONVERTARRAYTOTABLE (op-code 16)

Convert a Java array to a COBOL table. Although ACUCOBOL-GT normally does this automatically, this op-code gives the COBOL programmer more precise control over the conversion process. The call takes the array handle, the number of elements to convert, the starting element position in the array, and the COBOL table variable in which to place the converted array.

Here is an example of an array of Java ints being converted to a USAGE SIGNED-INT OCCURS 10 table:

CALL "C$JAVA" USING CJAVA-CONVERTARRAYTOTABLE,
   ARRAY_HANDLE, 10, 0, INT-TABLE(1)
   GIVING STATUS-VAL.

CJAVA-LOGMESSAGE (op-code 17)

This operation places an entry in the Java log. Java messages can be logged from a COBOL program using the CJAVA-LOGMESSAGE as follows:

CALL "C$JAVA" USING CJAVA-LOGMESSAGE, "Message to log".

The advantage of using the Java log is that it is thread-safe, and all of the messages from a given thread of execution are written to the same log whether that thread is executing COBOL or Java. Also, logs in Java are highly configurable. Note that the log output above is formatted to report date, time, class, method, and log level before the message. You can configure logging by modifying the logging.properties file found in the runtime directory.

See Using Java Logging from COBOL for additional details.

CJAVA-CREATEARRAY (op-code 18)

Create a new Java array. Following are the array types supported by C$JAVA:

   CJAVA-OBJECTARRAY     VALUE 300.
   CJAVA-BOOLEANARRAY    VALUE 301.
   CJAVA-BYTEARRAY       VALUE 302.
   CJAVA-CHARARRAY       VALUE 303.
   CJAVA-SHORTARRAY      VALUE 304.
   CJAVA-INTARRAY        VALUE 305.
   CJAVA-LONGARRAY       VALUE 306.
   CJAVA-FLOATARRAY      VALUE 307.
   CJAVA-DOUBLEARRAY     VALUE 308.
   CJAVA-STRINGARRAY     VALUE 309.

To create an array of primitive types, pass the type of array, the size of the array, and return the array handle through the GIVING statement. For example:

CALL "C$JAVA" USING CJAVA-CREATEARRAY,
   CJAVA-INTARRAY, ARRAY-SIZE
   GIVING ARRAY-HANDLE.

To create an object array:

CALL "C$JAVA" USING CJAVA-CREATEARRAY,
   CJAVA-OBJECTARRAY, 10
   GIVING ARRAY-HANDLE.

In this case, the array consists of an array of object handles.

To create a string array:

Even though strings in Java are objects, they are treated separately for the convenience of using them with PIC X tables. Here is an example of creating a string array:

CALL "C$JAVA" USING CJAVA-CREATEARRAY,
   CJAVA-STRINGARRAY, 10
   GIVING ARRAY-HANDLE.

See Creating and Using Java Arrays in COBOL for more information.

CJAVA-CONVERTTABLETOARRAY (op-code 19)

Convert a COBOL table to a Java array. Although ACUCOBOL-GT normally does this automatically, this op-code gives the COBOL programmer more precise control over the conversion process. The call requires the COBOL table from which the values will be taken, the number of elements, the position of the first element, and the handle of the destination array.

Here is an example of call that converts a table to an array:

CALL "C$JAVA" USING CJAVA-CONVERTTABLETOARRAY,
   INT-TABLE(1), 10, 0, ARRAY-HANDLE,
   GIVING STATUS-VAL.

CJAVA-LOADCLASS (op-code 20)

Manually load a Java class prior to use. Normally, java doesn't require classes to be manually loaded. When you create new object, java typically searches the classpath and loads the class.

CJAVA-DBCONNECT (op-code 21)

Connect to a Java Database Connectivity (JDBC) data source.

Because the CVM.jar package that comes with ACUCOBOL-GT contains a Java class for connecting to JDBC data sources and querying those data sources for ResultSet objects, you do not have to use the C$JAVA routine to do this. However, using C$JAVA is somewhat more efficient because the Connection and ResultSet handles do not have to be created prior to being used.

To use op-codes 21 and 22, you must include the java.def file in the working storage section of your COBOL program. Be sure that java.def file is located in the same directory as the .cbl file.

See Creating and Using a JDBC ResultSet for more information on achieving connectivity with a JDBC data source.

CJAVA-DBQUERY (op-code 22)

Query the JDBC ResultSet. See op-code 21.

CJAVA-NEWREMOTEOBJECT (op-code 23)

Connect to a Remote Object Invocation (RMI) server, and create an instance of a remote object on that server. This operation takes three parameters: the host name, the server name, and the port number. Here is an example of the call:

CALL "C$JAVA" USING CJAVA-NEWREMOTEOBJECT, "localhost", "RemoteInterfaceServer", PORT-NUMBER GIVING REMOTE-OBJ.

CALL "C$JAVA" USING CJAVA-CALL, REMOTE-OBJ, "acuUtilities/RemoteInterfaceServer", "RemoteMethod",   "()X", FIELD-STRINGRET GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-DELETE, REMOTE-OBJ GIVING STATUS-VAL.

CJAVA-STARTREMOTESERVER (op-code 24)

Start the RMI server. For example:

CALL "C$JAVA" USING CJAVA-NEW, "acuUtilities/AcuRMIServer", "()V" GIVING REMOTE-SERVER.
CALL "C$JAVA" USING CJAVA-STARTREMOTESERVER, REMOTE-SERVER, "RemoteInterfaceServer", PORT-NUMBER GIVING STATUS-VAL.

CJAVA-SETARRAYREGION (op-code 25)

Take a Java array object and copy the elements from a COBOL table data item into a specified range.

CJAVA-GETARRAYREGION (op-code 26)

Take a Java array object, get the specified range of elements, and copy them into a COBOL table data item.

CJAVA-GETEXCEPTIONOBJECT (op-code 27)

Return the exception object of the last Java exception thrown. Once the exception object is returned, you can call any of the methods on the exception object that are documented in the Java documentation.

CJAVA-SETSYSTEMPROPERTY (op-code 28)

Change a system property. Useful for setting CLASSPATH and LIBRARYPATH environment variables. For example:

CALL "C$JAVA" USING CJAVA-SETSYSTEMPROPERTY, "java.class.path",
"d:\MyClasses.jar;d:\otherDir" GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-SETSYSTEMPROPERTY, "java.library.path",
"C:\Acucorp\Acucbl700\AcuGT\bin;d:\otherDir" GIVING STATUS-VAL.

CJAVA-CALLJAVAMAIN (op-code 29)

Call a Java main method. For example:

CALL C$JAVA USING CJAVA-CALLJAVAMAIN, CobolCallingJava, \StrParam1, StrParam2, StrParam3, StrParam4 GIVING STATUS-VAL.

This example calls a Java main method with the following signature:

public static void main( String[] args );

The main method signature can include optional exceptions that have been specified by the Java programmer. The first parameter is the op-code, the second parameter is the name of the class containing the main method. This directory or JAR file containing this class must be placed on the CLASSPATH environment variable. The number of string parameters can be zero or as many as is possible to pass using the CALL statement. The COBOL calling Java samples in the sample/java directory have been updated to include a sample of such a call.

Parent topic: General Syntax and Library List


C$JUSTIFY

C$JUSTIFY performs left or right justification of data and centering of data.

Usage

CALL "C$JUSTIFY"
    USING DATA-ITEM, JUSTIFY-TYPE

Parameters

This data item contains the data to be justified.

This optional parameter contains one of three literal values:

L | indicates left justification
R | indicates right justification
C | indicates centering

If this parameter is omitted, then "R" is implied.

Description

This routine removes all leading and trailing spaces from DATA-ITEM and justifies the remaining data as indicated by JUSTIFY-TYPE. The resulting string is returned in DATA-ITEM. If centering is chosen, there will be one more space on the right than on the left if an odd number of spaces is used.

Parent topic: General Syntax and Library List


C$KEYMAP

The C$KEYMAP routine maintains a stack of keyboard configurations. This routine is used to save the current keyboard configuration just before you change it. You can then later restore the original configuration by another call to this routine. The ACUCOBOL-GT debugger uses this routine before reprogramming the keyboard for its use.

Usage

CALL "C$KEYMAP"
    USING KEYSTROKE-SETTING, STATUS-VAL

Parameters

KEYSTROKE-SETTING Numeric parameter | Dictates whether to save (1) or restore (0) the keyboard settings.
STATUS-VAL COMP-1 (optional) | Returns 1 if successful, 0 otherwise.

Comments

If KEYSTROKE-SETTING is set to 1, then the current KEYSTROKE settings are pushed onto a stack. If it is 0, then the KEYSTROKE settings are restored from the stack and the stack is popped. For a description of KEYSTROKE settings, see the ACUCOBOL-GT User's Guide, The KEYSTROKE variable.

The keyboard stack has space for 10 entries. One of these should be reserved for use by the debugger. If the stack overflows, or inadequate dynamic memory is available to save the keyboard configuration, then this routine does nothing.

This routine may optionally be passed a second parameter. This must be a COMP-1 field. It is set to 1 if the routine succeeds. It is set to 0 if the stack is full or inadequate memory is available.

The NOTEPAD.CBL sample program provided with ACUCOBOL-GT contains an example of the use of this routine.

Parent topic: General Syntax and Library List


C$KEYPROGRESS

The C$KEYPROGRESS routine is used in a USE FOR REPORTING declarative procedure to obtain information about the progress of the system when it is adding keys to a file open for BULK-ADDITION.

Usage

CALL "C$KEYPROGRESS"
    USING KEYPROGRESS-DATA

Parameters

KEYPROGRESS-DATA Group item as follows:
01  KEYPROGRESS-DATA, SYNC.
    03  KEYPROG-CUR-KEY    PIC XX COMP-N.
    03  KEYPROG-NUM-KEYS   PIC XX COMP-N.
    03  KEYPROG-CUR-REC    PIC X(4) COMP-N.
    03  KEYPROG-NUM-RECS   PIC X(4) COMP-N.

This item holds the results of the C$KEYPROGRESS routine call. A copy of this data item can be found in the COPY library keyprog.def.

Description

When you call C$KEYPROGRESS from inside a USE FOR REPORTING declarative procedure, the KEYPROGRESS-DATA group item is filled in with information about the progress the runtime is making in adding keys to a file that has been opened for BULK-ADDITION. Calling C$KEYPROGRESS at any other time has undefined effects.

The individual fields of the group item hold the following information:

KEYPROG-CUR-KEY | this is the current key being worked on by Vision. The primary key is key 1, the first alternate is key 2, and so on.
KEYPROG-NUM-KEYS | this is the total number of keys in the file.
KEYPROG-CUR-REC | this is the number of the last record written for the current key, ranging from 1 to the total number of records to write.
KEYPROG-NUM-RECS | this is the total number of records to be keyed.

For more information about how and when to use C$KEYPROGRESS, see the topic Bulk addition mode for Vision in the ACUCOBOL-GT User's Guide.

Parent topic: General Syntax and Library List


C$LIST-DIRECTORY

The C$LIST-DIRECTORY routine lists the contents of a selected directory. Each operating system has a unique method for performing this task. C$LIST-DIRECTORY provides a single method that will work for all operating systems.

Usage

CALL "C$LIST-DIRECTORY"
    USING OP-CODE, parameters

Parameters

OP-CODE PIC 99 COMP-X

Indicates which C$LIST-DIRECTORY operation to perform. The operations are described below.

Parameters vary depending on the op-code chosen.

Parameters provide information and hold results for the op-code specified. These parameters are described below.

Description

C$LIST-DIRECTORY allows you to get the names of files residing in a given directory. It accomplishes this through three distinct operations. The first operation opens the specified directory. The second operation returns the filenames in the list, one-at-a-time. The third operation closes the directory and deallocates all memory used by the routine. C$LIST-DIRECTORY has the following operation codes (defined in acucobol.def):

LISTDIR-OPEN (VALUE 1)
Opens the specified directory. It has two parameters:
Directoryname PIC X(n)
Contains the name of the directory to open. This directory must exist, and you must have permissions to read the directory. You may use remote name syntax if AcuServer is installed on the remote machine. The "@[DISPLAY]:" for Thin Client support may be used. For example:
C$LIST-DIRECTORY using listdir-open,
"@[DISPLAY]:C:\path", pattern

See CBL_COPY_FILE for more information.

Pattern PIC X(n)
Specifies the type of filename for which to search. This routine supports "wildcards," meaning that the character "*" will match any number of characters, and the character "?" will match any single character. For example, you can search by file suffix (*.def) or by a common part of a file name (acu*).
Note: On VMS platforms, when searching for all files in a directory, you must specify "*.*" instead of "*".

If the call to LISTDIR-OPEN is successful, RETURN-CODE contains a handle to the list. The value in RETURN-CODE should be moved to a data item that is USAGE HANDLE. That data item should be passed as the directory handle to the other C$LISTDIRECTORY operations. If the call to LISTDIR-OPEN fails (if the directory does not exist, contains no files, or you do not have permission to read the directory), RETURN-CODE is set to a NULL handle.

LISTDIR-NEXT (VALUE 2)
Reads each filename from the open directory. It has two parameters:
Handle USAGE HANDLE
The handle returned in the LISTDIR-OPEN operation.
Filename PIC X(n)
The location of the next filename to be returned. If the directory listing is finished, it is filled with spaces.

The call to LISTDIR-NEXT can include an additional argument, LISTDIR-FILE-INFORMATION (defined in "acucobol.def"), which receives information about the returned file name. This is an optional group item which returns information about the following data items:

LISTDIR-FILE-TYPE
The file type can be one of the following:

B = block device
C = character device
D = directory
F = regular file
P = pipe (FIFO)
S = socket
U = unknown

LISTDIR-FILE-CREATION-TIME
The creation time is the date (and time) that the file was originally created.
LISTDIR-FILE-LAST-ACCESS-TIME
The last access time is the date (and time) that the file was last accessed by some application (usually when the file was queried in some way).
LISTDIR-FILE-LAST-MODIFICATION-TIME
The last modification time is the date (and time) the file was last written to.
LISTDIR-FILE-SIZE
The size of the file is given in bytes.
LISTDIR-CLOSE (VALUE 3)
Releases the resources used by the other operations. It must be called to avoid memory leaks. It has one parameter, handle, which is the same data item used by the LISTDIR-NEXT operation.
Handle USAGE HANDLE
The handle returned in the LISTDIR-OPEN operation.
Note: Because the supported file types vary by operating system, The data items in the above list have slightly different meanings depending on your operating system. Even on operating systems that support these values, some file systems may not. Some versions of the UNIX® operating system may change these values when permissions are changed. Refer to your operating system documentation for specific definitions.

Example

The following example lists the contents of a directory with repeated calls C$LISTDIRECTORY:

WORKING-STORAGE SECTION.
copy "def/acucobol.def".
01  pattern       pic x(5) value "*.vbs".
01  directory     pic x(20) value "/virusscan".
01  filename      pic x(128).
01  mydir         usage handle.
PROCEDURE DIVISION.
MAIN.
* CALL LISTDIR-OPEN to get a directory handle.
    call "C$LIST-DIRECTORY"
       using listdir-open, directory, pattern.
    move return-code to mydir.
    if mydir = 0
       stop run
    end-if.
* CALL LISTDIR-NEXT to get the names of the files.
* Repeat this operation until a filename containing only
* spaces is returned.  The filenames are not necessarily
* returned in any particular order.  Filenames may be
* sorted on some machines and not on others.
    perform with test after until filename = spaces
       call "C$LIST-DIRECTORY"
          using listdir-next, mydir, filename
    end-perform.
* CALL LISTDIR-CLOSE to close the directory and deallocate
* memory. Omitting this call will result in memory leaks.
    call "C$LIST-DIRECTORY" using listdir-close, mydir.
    stop run.
Parent topic: General Syntax and Library List
Related reference
CBL_COPY_FILE


C$LOCALPRINT

The C$LOCALPRINT routine provides access to the ACUCOBOL-GT window manager's local print mechanism. This allows the program to write to a printer or other device attached directly to the user's terminal. One or two USING parameters should be provided.

Usage

CALL "C$LOCALPRINT"
    USING SOURCE-DATA, LINE-SPACE

Parameters

SOURCE-DATA PIC X(n)

This contains the data that will be sent to the local device. Any trailing spaces will be removed before the data is sent.

LINE-SPACE Numeric parameter (optional)

The second parameter, if specified, determines the line spacing provided by the routine. Its value is interpreted as follows:

0 | No additional characters are sent after the data
1 | A carriage return is sent after the data
2 | A carriage return and a line feed are sent after the data
3 | A carriage return and a form feed are sent after the data

If the second parameter is not supplied, then it is treated as if it were a 2.

You may add either or both of the following values to the value contained in the second parameter:

+10 | Any line-advancing control sequences are sent before the data instead of after.
+20 | Inhibits the sending of the disable-printer terminal sequence after sending the data.

For example, a second parameter value of 12 causes the printer to be advanced one line prior to sending the data (since a value of 2 causes the printer to advance one line after sending the data).

A second parameter value of 8 (with a dummy first parameter) causes the disable-print sequence to be sent to the terminal on its own.

Description

When this routine executes, it performs the following steps in this order:

  1. The terminal's Enable Print command is sent. This causes subsequent data sent to the terminal to be also sent to the attached device.
  2. The data specified in the first USING parameter (less trailing spaces) is sent to the terminal. No interpretation or modification is done to this data.
  3. The appropriate line spacing characters specified by the second USING parameter are sent to the terminal.
  4. The terminal's Disable Print command is sent. This turns off the pass-through mode.
  5. The current cursor location is set to the home position of the current window. The window manager is instructed to define the current screen state as undefined. This causes the window manager to behave correctly if the terminal's pass-through mode is destructive to the screen (e.g., characters appear on the screen as well as being sent to the attached device).
Note: Some terminals handle pass-through printing in an invisible fashion (the characters go to the printer, but do not show up on the screen), while others echo the characters onto the screen too. For maximum portability, you should assume that a call to C$LOCALPRINT will cause garbage to appear on the screen and should arrange to repaint the screen when you are finished with the local device.

The routine assumes that the attached terminal is able to do pass-through printing. You may use the ACCEPT FROM TERMINAL-INFO verb to test for this ability beforehand if you desire. You need to ensure that any communication restrictions imposed by the terminal are followed. For example, some terminals require that the attached device run at the same baud rate as the terminal.

With programs that use the Window's console (DOS-box) runtime, the C$LOCALPRINT routine simulates local printing via the following procedure. When the routine is called for the first time, the runtime system opens a file to which it writes the passed data. The name of the file is determined by the setting of the environment variable LPRINTER. Usually this will be set to the name of a device such as PRN, LPT1, and so forth. If this variable is not set, then the default name PRN is used. Serial ports are not supported.

Once this file is open, it is not closed by the runtime system. If you need to close it, you can call C$LOCALPRINT with a dummy first parameter and a second parameter of 9. Non-Windows console runtimes ignore this form of the call. Also note that no error checking is possible. If the runtime cannot open the LPRINTER file, it prints an error message and stops.

Parent topic: General Syntax and Library List


C$LOCKPID

This routine returns the Process ID (PID) of the process holding the lock responsible for the previous file lock or record locked condition encountered. This library routine works only with the Vision file system and the UNIX platform.

Usage

CALL "C$LOCKPID"
    GIVING PROCESS-ID.

Parameter

PROCESS-ID PIC 9(n) This contains a numeric data item large enough to hold a PID. On most platforms, PIC 9(5) is sufficient. On 64-bit systems, PIC 9(7) is recommended.

Comments

C$LOCKPID returns a PROCESS-ID of 0 if you have not yet encountered a locked file or record, if the PID is otherwise not found, or if you've used this routine with a non-UNIX runtime.

Parent topic: General Syntax and Library List


C$MAKEDIR

Creates a new directory.

C$MAKEDIR can make a directory only one level lower than an existing directory and cannot create more than one level at a time.

Usage

CALL "C$MAKEDIR"
    USING DIR-NAME GIVING STATUS-CODE

Parameters

DIR-NAME PIC X(n) Contains the name of the directory to be created. This should be either a full path name or a name relative to the current directory. You may use remote name syntax in combination with AcuServer to create a directory on a remote machine.

The "@[DISPLAY]:" annotation for Thin Client support may also be specified. For example:

C$MAKEDIR "@[DISPLAY]:C:\path"

See CBL_COPY_FILE for more information.

STATUS-CODE Numeric data item. Receives the return status of the call to create a directory. A return status of zero indicates that the directory was successfully created; a status of one ("1") indicates otherwise.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name.

See the entry for FILENAME_SPACES in Appendix H for more information.

Parent topic: General Syntax and Library List
Related reference
FILENAME_SPACES
CBL_COPY_FILE


C$MEMCPY (Dynamic Memory Routine)

Copies bytes between any two memory locations.

Usage

CALL "C$MEMCPY"
    USING, BY VALUE, DEST-PTR, SRC-PTR, NUM-BYTES

Parameters

DEST-PTR USAGE POINTER or USING BY REFERENCE | Contains the address of the first byte of the destination.
SRC-PTR USAGE POINTER or USING BY REFERENCE | Contains the address of the first byte of the source.
NUM-BYTES USAGE UNSIGNED-INT or an unsigned numeric literal | Indicates the number of bytes to copy.

Description

This routine copies NUM-BYTES bytes of memory from the address contained in SRC-PTR to the address contained in DEST-PTR. This routine is functionally similar to the M$COPY (Dynamic Memory Routine) routine except that parameters are passed by value instead of by reference. This routine can be used in cases where M$PUT and M$GET are not adequate. Note that this routine is relatively dangerous to use. It does not perform any error checking and can easily cause memory access violations if you pass it incorrect data. In other words, this routine is a very low-level routine and should be used cautiously.

You do not need to pass POINTER data items for SRC-PTR and DEST-PTR. If you prefer, either or both can be replaced by a data item passed BY REFERENCE. If you do this, then the address of the data item is passed to C$MEMCPY. For example, you can copy 10 bytes to DEST-ITEM from the memory address contained in SRC-PTR with:

     CALL "C$MEMCPY"
        USING BY REFERENCE DEST-ITEM, BY VALUE SRC-PTR, 10
Parent topic: General Syntax and Library List


C$MYFILE

Returns the filename of the disk file containing the currently executing program.

This is especially useful if the disk file is an object library.

Usage

CALL "C$MYFILE"
    USING PROGRAM-NAME
    GIVING CALL-STATUS

Parameters

PROGRAM-NAME PIC X(n) | Indicates the name of the disk file containing the currently executing program, if known. The runtime will use as much space for the name of the file as the COBOL program allows. This parameter will contain the filename just as the runtime received it. For example, if an object library is loaded as ../ardir/myarlib.lib, and a program in myarlib.lib calls this routine, PROGRAM-NAME will have a value of ../ardir/myarlib.lib.
CALL-STATUS PIC S99. | This parameter receives one of the following values: 1 - PROGRAM-NAME was filled successfully -1 - Program name unknown
Parent topic: General Syntax and Library List


C$NARG

This routine returns the number of parameters passed to the current program.

Usage

CALL "C$NARG"
    USING NUM-PARAM

Parameter

NUM-PARAM COMP-1

Description

This routine must be called with one USING parameter that must be a COMP-1 data item. This data item is filled in with the number of parameters. If the calling program is a subprogram, then this will be the number of USING items in the CALL statement that initiated the program. If the calling program is a main program, then this will be the number of CHAINING parameters passed from the runcbl command line or the CHAIN statement that initiated the program. C$NARG works only when the program is a called subroutine. It does not work with the "CALL RUN" form of the CALL verb.

Parent topic: General Syntax and Library List


C$OPENSAVEBOX

C$OPENSAVEBOX provides a facility for creating an Open or Save As dialog box. These dialogs allow the user to browse the system's file directories and select a file or folder.

This routine can be used by applications that are deployed in Acucorp's Thin Client environment. In this scenario, C$OPENSAVEBOX allows the user to choose a directory or file on the client (Windows) machine.

Not all systems support C$OPENSAVEBOX. However, you can determine at runtime whether the host system supports it.

Usage

CALL "C$OPENSAVEBOX"
    USING OP-CODE, OPENSAVE-DATA
    GIVING OPENSAVE-STATUS

Parameters

OP-CODE Numeric value | Selects which C$OPENSAVEBOX function to perform. The values are described below.
OPENSAVE-DATA Group item as follows:
01  OPENSAVE-DATA.
    03  OPNSAV-FILENAME         PIC X(256).
    03  OPNSAV-FLAGS            PIC 9(4) COMP-X.
    03  OPNSAV-DEFAULT-EXT      PIC X(12).
    03  OPNSAV-TITLE            PIC X(80).
    03  OPNSAV-FILTERS          PIC X(512).
    03  OPNSAV-DEFAULT-FILTER   PIC 9(4) COMP-X.
    03  OPNSAV-DEFAULT-DIR      PIC X(128).
    03  OPNSAV-BASENAME         PIC X(128).

This item holds the results of a C$OPENSAVEBOX routine call. The values are described below.

OPENSAVE-STATUS Signed numeric data item | This item returns the status of the operation. A value of 1 indicates that the operation completed successfully. A zero or negative value indicates that the operation failed.

Description

C$OPENSAVEBOX performs a variety of operations depending on the operation passed. All of the data items and definitions required by this routine can be found in "opensave.def". The operations are as follows:

OPENSAVE-SUPPORTED (op-code 1)

This operation returns a value that indicates whether the host system supports C$OPENSAVEBOX. If the system supports it, OPENSAVE-STATUS is set to 1. Otherwise, it is set to OPNSAVERR-UNSUPPORTED (value 0). The OPENSAVE-DATA parameter is not used with this op-code and should be omitted. (Note that Microsoft Windows hosts support C$OPENSAVEBOX.)

OPENSAVE-OPEN-BOX (op-code 2)

This operation initiates an Open File dialog with the user. The OPENSAVE-DATA structure initializes the dialog box and returns the results.

OPENSAVE-SAVE-BOX (op-code 3)

This operation initiates a Save As dialog with the user. The OPENSAVE-DATA structure initializes the dialog box and returns the results. On some systems, there is no difference between an Open and Save As dialog box. On other systems, there are some differences.

OPENSAVE-BROWSE-FOLDER (op-code 4)

This operation initiates a Browse for Folder dialog with the user. The OPENSAV-TITLE and OPENSAV-FILENAME fields in the OPENSAVE-DATA structure initialize the dialog box and return the result, respectively. When C$OPENSAVE BOX is called, the Browse for Folder dialog box displays the contents of OPENSAV-FILENAME as the root folder to be browsed. Only folders which are descendants of this folder are shown in the dialog box. If OPENSAV-FILENAME is blank when the routine is called, the dialog shows all folders in the user's default working folder, and a number of other items, such as the Recycle Bin. You may select an empty folder, however, if the folder specified as a root does not exist or is inaccessible, the dialog shows all folders in the user's default working folder, just as though no root was specified. The OK button is disabled if any item other than a folder is selected.

OPENSAVE-DATA

You should use the INITIALIZE verb on OPENSAVE-DATA before you fill in the data fields. This ensures that you have set all the fields to the default values and protects you from possible future changes to the OPENSAVE-DATA structure.

The OPENSAVE-DATA item is fairly large (1120 bytes). You can conserve memory by using C$OPENSAVEBOX from a utility subprogram that you write. This subprogram would include OPENSAVE-DATA. After using the subprogram, you can free the memory with the CANCEL verb. In this way, you need to keep OPENSAVE-DATA in memory only while you are using it. Alternatively, you can use the M$ALLOC library routine to allocate memory to hold OPENSAVE-DATA, and then free that memory after you are done.

The fields contained in the OPENSAVE-DATA structure are used as follows:

OPNSAV-FILENAME | On input to the routine, this item contains the default file name to use as the initial prompt. Set OPNSAV-FILENAME to spaces if there should be no default name. When the routine returns, this item contains the name of the file selected by the user. When used with the OPENSAVE-BROWSE-FOLDER operation, this item returns the file specifications of the selected folder, if any. If the user selects a folder which is not accessible, this item is blank.
OPNSAV-FLAGS | This item is used to pass information to the OPENSAVE-OPEN-BOX, OPENSAVE-SAVE-BOX, and OPENSAVE-BROWSE-FOLDER operations to modify the behavior of the associated dialog boxes. Constants for these flags are defined in opensave.def.

The following flags can be used with the OPENSAVE-OPEN-BOX and OPENSAVE-SAVE-BOX operations:

OPENSAVE-OVERWRITEPROMPT | This flag causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.
OPENSAVE-PATHMUSTEXIST | This flag specifies that the user can type only valid paths and file names. If this flag is used and the user types an invalid path and file name in the File Name entry field, the dialog box function displays a warning in a message box.
OPENSAVE-FILEMUSTEXIST | This flag specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box. If this flag is specified, the OPENSAVE-PATHMUSTEXIST flag is also used.
OPENSAVE-CREATEPROMPT | If the user specifies a file that does not exist, this flag causes the dialog box to prompt the user for permission to create the file. If the user chooses to create the file, the dialog box closes and the function returns the specified name.
OPENSAVE-NOREADONLYRETURN | This flag specifies that the returned file does not have the Read Only check box selected and is not in a write-protected directory.

The following flags can be used with the OPENSAVE-BROWSE-FOLDER operation:

OP-CODE Numeric value | Selects which C$OPENSAVEBOX function to perform. The values are described below.
OPENSAVE-DATA Group item as follows:
01  OPENSAVE-DATA.
    03  OPNSAV-FILENAME         PIC X(256).
    03  OPNSAV-FLAGS            PIC 9(4) COMP-X.
    03  OPNSAV-DEFAULT-EXT      PIC X(12).
    03  OPNSAV-TITLE            PIC X(80).
    03  OPNSAV-FILTERS          PIC X(512).
    03  OPNSAV-DEFAULT-FILTER   PIC 9(4) COMP-X.
    03  OPNSAV-DEFAULT-DIR      PIC X(128).
    03  OPNSAV-BASENAME         PIC X(128).

This item holds the results of a C$OPENSAVEBOX routine call. The values are described below.

OPENSAVE-STATUS Signed numeric data item | This item returns the status of the operation. A value of "1" indicates that the operation completed successfully. A zero or negative value indicates that the operation failed.
OPNSAV-FILENAME | On input to the routine, this item contains the default file name to use as the initial prompt. Set OPNSAV-FILENAME to spaces if there should be no default name. When the routine returns, this item contains the name of the file selected by the user. When used with the OPENSAVE-BROWSE-FOLDER operation, this item returns the file specifications of the selected folder, if any. If the user selects a folder which is not accessible, this item is blank.
OPNSAV-FLAGS | This item is used to pass information to the OPENSAVE-OPEN-BOX, OPENSAVE-SAVE-BOX, and OPENSAVE-BROWSE-FOLDER operations to modify the behavior of the associated dialog boxes. Constants for these flags are defined in "opensave.def".
OPENSAVE-OVERWRITEPROMPT | This flag causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.
OPENSAVE-PATHMUSTEXIST | This flag specifies that the user can type only valid paths and file names. If this flag is used and the user types an invalid path and file name in the File Name entry field, the dialog box function displays a warning in a message box.
OPENSAVE-FILEMUSTEXIST | This flag specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box. If this flag is specified, the OPENSAVE-PATHMUSTEXIST flag is also used.
OPENSAVE-CREATEPROMPT | If the user specifies a file that does not exist, this flag causes the dialog box to prompt the user for permission to create the file. If the user chooses to create the file, the dialog box closes and the function returns the specified name.
OPENSAVE-NOREADONLYRETURN | This flag specifies that the returned file does not have the Read Only check box selected and is not in a write-protected directory.
OPENSAVE-BROWSE-DONTGOBELOWDOMAIN | When this flag is set, network folders below the domain level in the dialog box's tree view control are not included.
OPENSAVE-BROWSE-RETURNFSANCESTORS | When this flag is set, only file system ancestors are returned. An ancestor is a subfolder that is beneath the root folder in the namespace hierarchy. If the user selects an ancestor of the root folder that is not part of the file system, the OK button is disabled.
OPENSAVE-BROWSE-EDITBOX | This flag includes an edit control in the browse dialog box allowing the user to type the name of an item.
OPENSAVE-BROWSE-NEWDIALOGSTYLE | This flag provides the user with a larger dialog box that can be resized. The dialog box has several new capabilities including: drag and drop capability within the dialog box, reordering, shortcut menus, new folders, delete, and other shortcut menu commands.
OPENSAVE-BROWSE-BROWSEINCLUDEURLS When this flag is set, the OPENSAVE-BROWSE-NEWDIALOGSTYLE, OPENSAVE-BROWSE-EDITBOX, and OPENSAVE-BROWSE-BROWSEINCLUDEFILES flags must also be set. Otherwise, the browser dialog box rejects URLs. Even when these flags are set, the browse dialog box displays URLs only if the folder containing the selected item supports them.

When the folder's "IShellFolder::GetAttributesOf" method is called, the folder must set the SFGAO_FOLDER flag. If this is not set, the browse dialog box does not display the URL.

OPENSAVE-BROWSE-UAHINT | When combined with OPENSAVE-BROWSE-NEWDIALOGSTYLE, this flag adds a usage hint to the dialog box in place of the edit box. OPENSAVE-BROWSE-EDITBOX overrides this flag.
OPENSAVE-BROWSE-NONEWFOLDERBUTTON | When this flag is set, the New Folder button in the browse dialog box is not included.
OPENSAVE-BROWSE-BROWSEFORCOMPUTER | When this flag is set, if the user selects anything other than a computer, the OK button is disabled.
OPENSAVE-BROWSE-BROWSEFORPRINTER | When this flag is set, if the user selects anything other than a printer, the OK button is disabled.
OPENSAVE-BROWSE-BROWSEINCLUDEFILES When this flag is set, the browse dialog box displays files as well as folders.
  • OPNSAV-DEFAULT-EXT - This item holds the default file name extension. The extension is the string of characters that appear after the "." in the file name. The value of OPNSAV-DEFAULT-EXT is added to the file name typed by the user, if the user does not type an extension. The default extension should not include the period ".". Set this item to spaces to avoid having a default extension.
  • OPNSAV-TITLE - This item holds the title of the dialog box. If it is set to spaces, a generic title is applied. The generic title is host-specific. When used with the OPENSAVE-BROWSE-FOLDER operation, the title of the Browse for Folder dialog is always Browse for Folder. The OPENSAV-TITLE item is displayed inside the Browse for Folder dialog box below the title bar and above the tree view control.
  • OPNSAV-FILTERS - The value of OPNSAV-FILTERS describes the set of filters that the dialog box uses to restrict the set of files shown to the user. Filters make it easier for a user to navigate through a large directory by limiting the files shown at once.

    Each filter consists of a pair of descriptors. These descriptors are separated by a vertical bar character ("|"). The first descriptor in the pair is displayed in the file type selection box of the Open or Save As dialog box. In Windows, it appears in the List of File Types drop-down box (see the illustration below). The second descriptor is the file name pattern that defines the filter. The file name pattern is formatted as "A [ . B ]" where "A" and "B" are optional text followed by an optional asterisk. An asterisk matches any sequence of characters excluding periods. This descriptor is what the system uses to look for matching files.

    Here is a sample OPNSAV-FILTERS setting that contains two filters:

    "COBOL source files (*.cbl)|*.cbl|All files (*.*)|*.*"

    The first filter in the example shows only ".cbl" files to the user. The second filter shows all files. The user selects which filter to use based on the descriptions supplied.

    Filters do not restrict the user from entering names that do not match the supplied pattern. Filters do not limit the user's choices, they only simplify the process of choosing.

    Set OPNSAV-FILTERS to spaces if you don't want any filters.

    Some systems do not support multiple filters. In this case, only the initial filter is used. See OPNSAV-DEFAULT-FILTER to determine how to select the initial filter.

  • OPNSAV-DEFAULT-FILTER - This item is used in conjunction with OPNSAV-FILTERS. The value of OPNSAV-DEFAULT-FILTER determines which of the given filters to use as the initial filter. A value of 1 selects the first filter pair, 2 selects the second pair, and so on. A value of zero also selects the first pair. This setting is not used if no filters are defined.
  • OPNSAV-DEFAULT-DIR - This item holds the default directory to use for the selected file. The dialog box initially displays the files found in this directory. If this item is set to spaces, the current directory is used. Note that the value of this item only defines the default directory. It does not prevent the user from selecting files in a different directory.
  • OPNSAV-BASENAME - When the routine returns, this item contains the base file name of the file chosen by the user. This differs from the value of OPNSAV-FILENAME in that all directory information is removed, leaving only the file name.

Error Handling

C$OPENSAVEBOX returns a value of 1 when successful. Otherwise, it returns one of the following values (found in opensave.def):

OPNSAVERR-UNSUPPORTED | This error indicates that the C$OPENSAVEBOX routine is not supported by the current host system.
OPNSAVERR-CANCELLED | This error indicates that the user clicked the "Cancel" button or typed the Escape key while using the dialog box.
OPNSAVERR-NO-MEMORY | This error indicates that not enough memory could be allocated to load the dialog box.
OPNSAVERR-NAME-TOO-LARGE | This error indicates that the name entered by the user does not fit in OPNSAV-FILENAME.

Example

This example uses C$OPENSAVEBOX to prompt for a text file name, and uses M$ALLOC to dynamically allocate OPENSAVE-DATA, freeing it after it is no longer needed.

WORKING-STORAGE SECTION.
77  OPENSAVE-DATA-SIZE    PIC 9(4) BINARY.
77  OPENSAVE-DATA-ADDR    POINTER.
77  OPENSAVE-STATUS       PIC S99.
    88  OPENSAVE-OK       VALUE 1.
77  FILE-NAME             PIC X(256).

LINKAGE SECTION.
COPY "opensave.def".

PROCEDURE DIVISION.
MAIN-LOGIC.
   SET OPENSAVE-DATA-SIZE TO SIZE OF OPENSAVE-DATA.
   CALL "M$ALLOC"
      USING OPENSAVE-DATA-SIZE, OPENSAVE-DATA-ADDR.
   IF OPENSAVE-DATA-ADDR = NULL
      {error handling here}
   ELSE
      SET ADDRESS OF OPENSAVE-DATA
          TO OPENSAVE-DATA-ADDR
      INITIALIZE OPENSAVE-DATA
      MOVE
          "Text files (*.txt)|*.txt|All files (*.*)|*.*"
          TO OPNSAV-FILTERS
      MOVE "txt" TO OPNSAV-DEFAULT-EXT
      CALL "C$OPENSAVEBOX" USING OPENSAVE-SAVE-BOX,
                                 OPENSAVE-DATA
                           GIVING OPENSAVE-STATUS

      IF OPENSAVE-OK
          MOVE OPNSAV-FILENAME TO FILE-NAME
      END-IF
      CALL "M$FREE" USING OPENSAVE-DATA-ADDR
   END-IF.
Parent topic: General Syntax and Library List


C$PARAMSIZE

This routine returns the number of bytes actually passed by the caller for a particular parameter.

Usage

CALL "C$PARAMSIZE"
    USING PARAM-NUM,
    GIVING PARAM-SIZE

Parameters

PARAM-NUM numeric parameter | This value is the ordinal position in the Procedure Division's USING phrase of the parameter whose size you want to know.
PARAM-SIZE any numeric data item | This item receives the number of bytes in the data item actually passed by the caller.

Description

This routine returns the actual size (in bytes) of a data item passed to the current program by its caller. You pass the number (starting with 1) of the data item in the Procedure Division's USING phrase, and C$PARAMSIZE will return the size of the corresponding item that was actually passed. This can be useful for handling data items of unknown size.

For example, suppose that you wanted to write a routine that could convert any data item to upper-case, up to 10000 bytes in size. This routine could look like this:

IDENTIFICATION DIVISION.
PROGRAM-ID.  MAKE-UPPERCASE.

DATA DIVISION.
WORKING-STORAGE SECTION.
77  PARAM-SIZE    PIC 9(5).

LINKAGE SECTION.
77  PASSED-ITEM   PIC X(10000).

PROCEDURE DIVISION USING PASSED-ITEM.
MAIN-LOGIC.
   CALL "C$PARAMSIZE" USING 1, GIVING PARAM-SIZE
   INSPECT PASSED-ITEM( 1 : PARAM-SIZE )
      CONVERTING "abcdefghijklmnopqrstuvwxyz"
      TO "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  EXIT PROGRAM.

In this example, if you do not use C$PARAMSIZE, you have to pass a full 10000 bytes to this routine or you get a memory usage error. By using C$PARAMSIZE and reference modification, only the memory actually passed is referenced, and there is no error. C$PARAMSIZE works only when the program is a called subroutine. It does not work with the "CALL RUN" form of the CALL verb.

If you pass a subitem of a linkage item in a CALL statement and the subprogram calls C$PARAMSIZE with requesting the size of the parameter, it will get the size as described in the linkage section of the calling program, unless that subitem is the first item of the linkage item. In that case, the size returned will be the size of the original item.

Parent topic: General Syntax and Library List


C$PARSEXFD

This routine is used to parse XFD files and retrieve information about them, giving you a way to map field description information to file record areas. Similar functionality allows the alfred utility to display data in a logical way (rather than displaying full records).

A detailed description of the use and structure of XFD files can be found in the topic XFD Files of the ACUCOBOL-GT User's Guide.

Note: The utility alfred is distributed with a file called parsexfd.ws, which describes how to use the alfred object library to parse XFD files. Although the C$PARSEXFD routine supersedes the abilities of that program, you may continue to use it. The ParseXFD COBOL program has been rewritten to use C$PARSEXFD, but the program interface has not changed.

Usage

CALL "C$PARSEXFD"
    USING OP-CODE, parameters
    GIVING return-value.

Parameters

OP-CODE (Numeric value)

The op-codes, which are defined in parsexfd.def, select which C$PARSEXFD function to perform. This table shows which operation corresponds to each operation code.

Code | Operation
0 | parse XFD file
1 | retrieve key information
2 | retrieve condition information
3 | retrieve field information
4 | test record conditions
9 | release XFD file from memory

Detailed information about the operations is given in the description below.

parameters | Op-code parameters vary depending on the operation code chosen. They provide information and hold results for the operations specified. The parameters that apply to C$PARSEXFD op-codes are all defined in parsexfd.def.
return-value (Numeric data item) | This item returns information relevant to the operation. The type of return value varies by op-code.

Description

C$PARSEXFD performs a variety of operations depending on the specified op-code. These operations are as follows:

PARSEXFD-PARSE (op-code 0)

This operation parses a specified XFD file. The syntax is:

CALL "C$PARSEXFD"
    USING PARSEXFD-PARSE, xfd-name, filename, flags,
         xfd-description.

PARSEXFD-PARSE takes the following parameters:

xfd-name (PIC X(n)) | Specifies the name of the XFD file to parse, with or without path information. If there is no path information, the configuration variables XFD_PREFIX or XFD_DIRECTORY are used to find the XFD file. You may omit the .xfd extension.
filename (PIC X(n) or NULL) | Specifies an indexed data file to be compared against the parsed XFD file. If the characteristics of the specified data file do not match the XFD, the parsed XFD is freed and the return-value is set to NULL. If this parameter is NULL or empty, the XFD file is not compared to any file.
flags (Numeric parameter) Flags modify the type of information returned from other op-codes. This parameter can be 0 (if no flags are set), or the sum of any of the following values:
  • PARSEXFD-FLAG-INCLUDE-COMMENTS (value 1) - This option causes comments to be included in the parsed XFD. The routine cannot, however, currently retrieve those comments.
  • PARSEXFD-FLAG-INCLUDE-999 (value 2) - This option includes fields with a condition code of 999, which indicates group items and other fields not normally included with XFD files.
  • PARSEXFD-FLAG-EXCLUDE-ARRAYS (value 4) - All table elements are normally appended with a value indicating their index. For example, for a field that occurs five times, the returned XFD includes five fields with _1, _2, _3, _4, and _5 appended to the field names. When this flag is set, such fields are returned with no suffix indicating their array index value. The information is still included, however, with the field group item (see below).
  • PARSEXFD-FLAG-DEEP-FIRST (value 8) - This flag modifies the order in which fields that are sub-elements of a table are returned. For example:
       07  my-array occurs 5 times.
      09  elem-1     pic x.
      09  elem-2     pic x.
      09  elem-3     pic x.

Normally this is returned as elem-1(1), elem-1(2), elem-1(3), elem-1(4), elem-1(5), elem-2(1), elem-2(2), elem-2(3), elem-2(4), elem-2(5), elem-3(1), elem-3(2), elem-3(3), elem-3(4), elem-3(5).

If PARSEXFD-FLAG-DEEP-FIRST is specified, the items are instead returned as elem-1(1), elem-2(1), elem-3(1), elem-1(2), elem-2(2), and so on. The same data is returned, but in a different order.

xfd-description (Group item) This parameter is structured as follows:
01  PARSEXFD-DESCRIPTION.
           03  PARSEXFD-HEADER-LINE.
               05  PARSEXFD-VERSION            PIC X COMP-N.
               05  PARSEXFD-SELECT-NAME        PIC X(30).
               05  PARSEXFD-FILENAME           PIC X(30).
               05  PARSEXFD-FILETYPE           PIC X COMP-N.
                   88  PARSEXFD-SEQUENTIAL-FILE    VALUE 4.
                   88  PARSEXFD-RELATIVE-FILE      VALUE 8.
                   88  PARSEXFD-INDEXED-FILE       VALUE 12.
           03  PARSEXFD-RECORD-LINE.
               05  PARSEXFD-MAX-REC-SIZE       PIC X(4) COMP-N.
               05  PARSEXFD-MIN-REC-SIZE       PIC X(4) COMP-N.
               05  PARSEXFD-NUM-KEYS           PIC X COMP-N.
           03  PARSEXFD-CONDITION-LINE.
               05  PARSEXFD-NUMBER-CONDITIONS  PIC XX COMP-N.
           03  PARSEXFD-FIELDS-LINE.
               05  PARSEXFD-NUMBER-FIELDS      PIC X(4) COMP-N.
           03  PARSEXFD-V6-INFORMATION.
               05  PARSEXFD-COBOL-TRIGGER      PIC X(100).
               05  PARSEXFD-COMPILE-LINE.
                   07  PARSEXFD-SIGN-FLAG      PIC X(2) COMP-N.
                       88  PARSEXFD-SIGN-ACU   VALUE 0.
                       88  PARSEXFD-SIGN-IBM   VALUE 4.
                       88  PARSEXFD-SIGN-MF    VALUE 8.
                       88  PARSEXFD-SIGN-NCR   VALUE 20.
                       88  PARSEXFD-SIGN-VAX   VALUE 36.
                       88  PARSEXFD-SIGN-MBP   VALUE 72.
                       88  PARSEXFD-SIGN-REA   VALUE 128.
                   07  PARSEXFD-MAX-DIGITS     PIC X(2) COMP-N.
                       88  PARSEXFD-18-DIGITS  VALUE 40.
                       88  PARSEXFD-31-DIGITS  VALUE 68.
                   07  PARSEXFD-PGM-PERIOD     PIC X.
                   07  PARSEXFD-PGM-COMMA      PIC X.
                   07  PARSEXFD-ENCODING       PIC X(2) COMP-N.
                       88  PARSEXFD_ASCII      VALUE 0.
                       88  PARSEXFD_WIDE       VALUE 1.
                       88  PARSEXFD_UTF-8      VALUE 2.
                       88  PARSEXFD_UTF-16-LE  VALUE 3.
                       88  PARSEXFD_UTF-16-BE  VALUE 5.
                       88  PARSEXFD_UTF-32-LE  VALUE 4.
                       88  PARSEXFD_UTF-32-BE  VALUE 6.

The values of the xfd-description parameter are defined as follows:

PARSEXFD-VERSION | is the version number of this XFD file.
PARSEXFD-SELECT-NAME | is the SELECT name of the file.
PARSEXFD-FILENAME | is the name of the data file described in the XFD.
PARSEXFD-FILETYPE | is the data file type. Valid values are 4 (sequential file), 8 (relative file), and 12 (indexed file).
PARSEXFD-COBOL-TRIGGER | specifies the name of the COBOL program to be executed as a trigger.
PARSEXFD-MAX-REC-SIZE | and MIN-REC-SIZE are the maximum and minimum size values for a record in this file.
PARSEXFD-NUM-KEYS | gives the number of keys described in the XFD.
PARSEXFD-SIGN-FLAG | indicates sign compatibility and is set by the -Dc compiler options.
PARSEXFD-MAX-DIGITS | indicates the maximum numeric digits. The possible values are 18 and 31. This is set by the -Dd31 compiler option. The internal values stored in the XFD for 18 and 31 digit numbers are 40 and 68. The name of the constants (which have 18 and 31 in them) tell which is which.
PARSEXFD-PGM-PERIOD | indicates the decimal value of the character used as the program period.
PARSEXFD-PGM-COMMA | indicates the decimal value of the character used as the program comma.
PARSEXFD-NUMBER-CONDITIONS | gives the number of conditions described in the XFD file.
PARSEXFD-NUMBER-FIELDS | is the number of fields available in the XFD.
PARSEXFD-ENCODING | is the encoding of the XFD file.
return-value For this op-code, the return value is the handle to the XFD. This handle must be used in future calls to C$PARSEXFD to get more information about the XFD, and to free the XFD when you are finished.

If the return-value is 0, an error occurred. You can get information about errors by examining f-errno and f-int-errno, which are defined in the filesys.def COPY file.

PARSEXFD-GET-KEY-INFO (op-code 1)

This operation retrieves information about the specified (single) key. It uses the following syntax:

CALL "C$PARSEXFD"
    USING PARSEXFD-GET-KEY-INFO, xfd-handle, keynum,
          key-description

The operation takes the following parameters:

xfd-handle | A valid handle returned by C$PARSEXFD PARSEXFD-PARSE.
keynum (Numeric parameter between 0 and PARSEXFD-NUM-KEYS) | Used to specify which key to parse. Takes a value between 0 and PARSEXFD-NUM-KEYS. Both 0 and PARSEXFD-NUM-KEYS - 1 are valid key numbers, but PARSEXFD-NUM-KEYS is not valid. In other words, key numbers are a zero-based array.
Key-description (Group item)

This parameter is structured as follows:

01 PARSEXFD-KEY-DESCRIPTION.
   03 PARSEXFD-NUMBER-SEGMENTS        PIC X COMP-N.
   03 PARSEXFD-DUP-FLAG               PIC X COMP-N.
      88 PARSEXFD-ALLOW-DUPLICATES    VALUE 1 FALSE 0.
   03 PARSEXFD-SEGMENT-DESCRIPTION
        OCCURS MAX-SEGS TIMES
        INDEXED BY PARSEXFD-SEG-IDX.
      05 PARSEXFD-SEGMENT-LENGTH      PIC X COMP-N.
      05 PARSEXFD-SEGMENT-OFFESET     PIC X(4) COMP-N.
      05 PARSEXFD-SEGMENT-OFFSET      PIC X(4) COMP-N.
   03 PARSEXFD-NUMBER-KEY-FIELDS      PIC X COMP-N.
   03 PARSEXFD-KEY-FIELDS
        OCCURS MAXNUMKEYFIELDS TIMES
        INDEXED BY PARSEXFD-KEY-FIELD-IDX.
      05 PARSEXFD-KEY-FIELD-NUM       PIC XX COMP-N.

The values of the key-description parameter are defined as follows:

PARSEXFD-NUMBER-SEGMENTS | specifies the number of segments in this key.
PARSEXFD-DUP-FLAG | shows whether duplicates are allowed in this key. A value of 1 indicates that duplicates are allowed; a value of 0 indicates no duplicates.
PARSEXFD-SEGMENT-LENGTH and SEGMENT-OFFSET | are the length and offset of each segment. The offset value is zero-based, so offset 0 is the beginning of the record. There is one SEGMENT-LENGTH and SEGMENT-OFFSET value for each segment.
PARSEXFD-NUMBER-KEY-FIELDS | gives the number of fields that make up this key. This is always at least as large as the number of segments, but may be larger (if a segment holds multiple fields).
PARSEXFD-KEY-FIELDS | is a table of key fields. This table has PARSEXFD-NUMBER-KEY-FIELDS valid elements.
PARSEXFD-KEY-FIELD-NUM | is the field number of this key field. Get information about the key field by looking at this field number.
return-value (0 or 1) | A return value of 1 indicates that the operation was successful; a 0 indicates failure. For this operation, a return code of 0 means that you have entered an invalid key number (for instance, specifying a key number of 3 for a file that only has two keys). Note, however, that if an invalid handle is specified, the results are undefined and may result in a memory violation.

PARSEXFD-GET-COND-INFO (op-code 2)

This operation retrieves information about conditions that use the WHEN directive within the XFD file. It uses the following syntax:

CALL "C$PARSEXFD"
    USING PARSEXFD-GET-COND-INFO, xfd-handle, cond-index,
          cond-description.

PARSEXFD-GET-COND-INFO takes the following parameters:

xfd-handle | A valid handle returned by C$PARSEXFD PARSEXFD-PARSE.
cond-index (Numeric parameter) | The condition index determines which condition to evaluate. It takes a value between 0 and PARSEXFD-NUMBER-CONDITIONS. Because conditions are a zero-based array, 0 and PARSEXFD-NUMBER-CONDITIONS - 1 are valid values, but PARSEXFD-NUMBER-CONDITIONS is not.
cond-description (Group item) The condition description holds information about what condition has been set (EQUAL TO, AND, OR), whether the condition has been met (is true or false), and how the condition is structured.

This parameter is structured as follows:

01  PARSEXFD-CONDITION-DESCRIPTION.
    03  PARSEXFD-CONDITION-TYPE         PIC X COMP-N.
        88  PARSEXFD-EQUAL-CONDITION    VALUE 1.
        88  PARSEXFD-AND-CONDITION      VALUE 2.
        88  PARSEXFD-OTHER-CONDITION    VALUE 3.
        88  PARSEXFD-GT-CONDITION       VALUE 4.
        88  PARSEXFD-GE-CONDITION       VALUE 5.
        88  PARSEXFD-LT-CONDITION       VALUE 6.
        88  PARSEXFD-LE-CONDITION       VALUE 7.
        88  PARSEXFD-NE-CONDITION       VALUE 8.
        88  PARSEXFD-OR-CONDITION       VALUE 9.
        88  PARSEXFD-COMPARISON-COND    VALUES 1, 4 THROUGH 8.
    03  PARSEXFD-CONDITION-FLAG         PIC X.
        88  PARSEXFD-TRUE-CONDITION     VALUE 'Y' FALSE 'N'.
    03  PARSEXFD-COMPARISON-CONDITIONS.
        05  PARSEXFD-COMP-FIELDNUM      PIC XX COMP-N.
        05  PARSEXFD-COMP-FIELDNAME     PIC X(30).
        05  PARSEXFD-COMP-FIELD-VAL     PIC X(50).
    03  PARSEXFD-OTHER-CONDITIONS
         REDEFINES PARSEXFD-COMPARISON-CONDITIONS.
        05  PARSEXFD-OTHER-FIELDNUM     PIC XX COMP-N.
        05  PARSEXFD-OTHER-FIELDNAME    PIC X(30).
    03  PARSEXFD-AND-OR-CONDITIONS
         REDEFINES PARSEXFD-COMPARISON-CONDITIONS.
        05  PARSEXFD-CONDITION-1        PIC XX COMP-N.
        05  PARSEXFD-CONDITION-2        PIC XX COMP-N.
    03  PARSEXFD-CONDITION-TABLENAME    PIC X(30).

The values of the cond-description parameter are defined as follows:

  • PARSEXFD-CONDITION-TYPE - tells whether this is an EQUAL condition, AND condition, etc.
  • PARSEXFD-CONDITION-FLAG - tells whether this condition is TRUE. This is only valid after PARSEXFD-TEST-CONDITONS (see below) has been called.
  • PARSEXFD-CONDITION-TABLENAME - is the table name specified in the TABLENAME directive of the WHEN directive.
    For EQUAL, GT (greater than), GE (greater than or equal to), LT (less than), LE (less than or equal to), and NE (not equal to) conditions, the following fields are valid:
    • PARSEXFD-COMP-FIELDNUM - is the field number of the field whose value will be tested against the value of the condition.
    • PARSEXFD-COMP-FIELDNAME - is the name of that field.
    • PARSEXFD-COMP-FIELD-VAL - is the value to be tested. This is the value specified in the WHEN directive of the FD used to create this XFD.

For OTHER conditions, the following fields are valid:

  • PARSEXFD-OTHER-FIELDNUM - is the field number of the field whose value will be different than all the other conditions which use this field.
  • PARSEXFD-OTHER-FIELDNAME - is the name of that field.

For AND and OR conditions, the following fields are valid:

  • PARSEXFD-CONDITION-1 and PARSEXFD-CONDITION-2 - are the conditions tested to determine whether this condition is true. For AND, both conditions must be true. For OR, one or both conditions must be true.

PARSEXFD-GET-FIELD-INFO (op-code 3)

This operation retrieves information about the field. It uses the following syntax:

CALL "C$PARSEXFD"
    USING PARSEXFD-GET-FIELD-INFO, xfd-handle, fieldnum,
          field-description.

The operation takes the following parameters:

xfd-handle | A valid handle returned by C$PARSEXFD PARSEXFD-PARSE.
fieldnum (Numeric parameter) | Takes a value between 0 and PARSEXFD-NUMBER-FIELDS. Because fields are a zero-based array, 0 and PARSEXFD-NUMBER-FIELDS - 1 are valid values, but PARSEXFD-NUMBER-FIELDS is not valid.
field-description (Group item) This parameter is structured as follows:
01  PARSEXFD-FIELD-DESCRIPTION.
    03  PARSEXFD-FIELD-OFFSET            PIC X(4) COMP-N.
    03  PARSEXFD-FIELD-LENGTH            PIC X(4) COMP-N.
    03  PARSEXFD-FIELD-TYPE              PIC X COMP-N.
        88  PARSEXFD-SIGNED-FIELD   VALUES NumSignSep
                                           NumSigned
                                           NumSepLead
                                           NumLeading
                                           CompSigned
                                           PackedSigned
                                           BinarySigned
                                           NativeSigned.
        88  PARSEXFD-NUM-FIELD      VALUES NumEdited THRU
                                           NativeUnsigned.
        88  PARSEXFD-FLOAT-FIELD    VALUE  Flt.
        88  PARSEXFD-ASCII-FIELD    VALUES Alphanum THRU Group.
        88  PARSEXFD-NAT-FIELD      VALUES Nat-type THRU NatEdited.
        88  PARSEXFD-WIDE-FIELD     VALUES Wide-type THRU
                                           WideEdited.
    03  PARSEXFD-FIELD-DIGITS            PIC X COMP-N.
    03  PARSEXFD-FIELD-SCALE             SIGNED-SHORT.
    03  PARSEXFD-FIELD-USER-TYPE         PIC XX COMP-N.
    03  PARSEXFD-FIELD-CONDITION         PIC XX COMP-N.
    03  PARSEXFD-FIELD-LEVEL             PIC X COMP-N.
    03  PARSEXFD-FIELD-NAME              PIC X(30).
    03  PARSEXFD-FIELD-FORMAT            PIC X(30).
    03  PARSEXFD-FIELD-OCCURS-DEPTH      PIC X COMP-N.
    03  PARSEXFD-FIELD-OCCURS-TABLE
            OCCURS MaxNumKeyFields TIMES
            INDEXED BY PARSEXFD-FIELD-OCCURS-LEVEL.
        05  PARSEXFD-FIELD-OCC-MAX-IDX   PIC XX COMP-N.
        05  PARSEXFD-FIELD-OCC-THIS-IDX  PIC XX COMP-N.
    03  PARSEXFD-FIELD-IN-KEY-FLAG       PIC X.
        88  PARSEXFD-FIELD-IS-IN-KEY     VALUE 'Y' FALSE 'N'.
    03  PARSEXFD-FIELD-SECONDARY-FLAG    PIC X.
        88  PARSEXFD-FIELD-IS-SECONDARY  VALUE 'Y' FALSE 'N'.
    03  PARSEXFD-FIELD-HIDDEN-FLAG       PIC X.
        88  PARSEXFD-FIELD-IS-HIDDEN     VALUE 'Y' FALSE 'N'.
    03  PARSEXFD-FIELD-READ-ONLY-FLAG    PIC X.
        88  PARSEXFD-FIELD-IS-READ-ONLY  VALUE 'Y' FALSE 'N'.

The values of the field-description parameter are defined as follows:

PARSEXFD-FIELD-OFFSET | is the offset of the beginning of this fie ld (zero-based).
PARSEXFD-FIELD-LENGTH | is the number of bytes this field requires.
PARSEXFD-FIELD-TYPE | describes the type of field. The types are defined as they appear in lib/sub.h, and are also listed in parsexfd.def.
PARSEXFD-FIELD-DIGITS | is either the number of digits in this numeric field, or the length if the field is non-numeric.
PARSEXFD-FIELD-SCALE | is either the scale of the numeric field or 0 if the field is non-numeric. The scale is defined as the power of ten by which the numeric value must be multiplied in order to get the actual value. For example, if the scale is -2, then there are two digits to the right of the decimal point.
PARSEXFD-USER-TYPE | describes some of the XFD directives, as listed in parsexfd.def. The UserDate, UserBinary and UserVarLength values are mutually exclusive (only one of them is set). SecondaryTable may be added to the value to signify that the SECONDARY-TABLE directive was also used.
PARSEXFD-FIELD-CONDITION | is the condition that the field depends on. A condition of 0 means that the field is always included; 999 means that the field is a group item. In the latter case, the value may not be completely meaningful (if there are binary items in the group item).
PARSEXFD-FIELD-LEVEL | is the level number of the field in the FD used to create this XFD.
PARSEXFD-FIELD-NAME | is the name of the field. If EXCLUDE-ARRAYS was NOT used when parsing the XFD, and the field is part of a table, then the field name may include array indices.
PARSEXFD-FIELD-FORMAT | is the date format specified in the XFD DATE directive.
PARSEXFD-FIELD-OCCURS-DEPTH | is the number of valid elements in the OCCURS-TABLE.
PARSEXFD-FIELD-OCCURS-TABLE | gives information about this element of a table. The OCC-MAX-IDX is the maximum index allowed. The OCC-THIS-IDX is the index of this element.
PARSEXFD-FIELD-IN-KEY-FLAG | indicates whether this field is part of a key. The value is Y if this field is a part of one or more keys, or N if not.
PARSEXFD-FIELD-SECONDARY-FLAG | indicates whether the SECONDARY-TABLE directive was used. The value is Y if so or N if not.
PARSEXFD-FIELD-HIDDEN-FLAG | indicates whether the HIDDEN directive was used on this field. The value is Y if so or N if not.
PARSEXFD-FIELD-READ-ONLY-FLAG | indicates whether the READ-ONLY directive was used on this field. The value is Y if so or N if not.
return-value (0 or 1) | A return-value of 1 indicates that the operation was successful; a 0 indicates failure. For this operation, you will only see a return code of 0 if you specify an invalid field number (for example, if you try to retrieve information about field number 17 in a record that only has 15 fields).

PARSEXFD-TEST-CONDITIONS (op-code 4)

This operation tests the conditions of a particular record. It uses the following syntax:

CALL "C$PARSEXFD"
    USING PARSEXFD-TEST-CONDITIONS, xfd-handle,
          record-pointer.

The operation takes the following parameters:

xfd-handle | A valid handle returned by C$PARSEXFD PARSEXFD-PARSE.
record-pointer | This is a pointer to the record area on which to test conditions. (Because conditions are true or false depending on the value of particular fields, the values of those fields must be known. The only way to do this is to have a record from a file, specified with the PARSEXFD-PARSE op-code, to test against.)

After calling with this op-code, you can get each condition and tell whether fields that depend on that condition should be included in this record.

PARSEXFD-RELEASE (op-code 9)

This operation frees all memory associated with the XFD. It has the following syntax:

CALL "C$PARSEXFD" USING PARSEXFD-RELEASE, xfd-handle

This operation takes a single parameter:

xfd-handle A valid handle returned by C$PARSEXFD PARSEXFD-PARSE.

After calling this op-code, do not reference the XFD handle. Doing so will result in undefined behavior, and may cause a memory access violation.

Parent topic: General Syntax and Library List


C$PDF

This routine enables you to perform PDF printing, offering similar (but more comprehensive) functionality to the collection of PDF_ configuration variables.

Usage

CALL "C$PDF"
    USING OP-CODE, parameters
    GIVING RESULT

Parameters

OP-CODE
A numeric value that selects which C$PDF function to perform. The op-codes are defined in the cpdf.def COPY file, located in the AcuGT\sample\def (Windows) or sample/def (UNIX) sub-directory of your installation directory. The op-codes are designed to match the functions described by the libharu PDF printing library, and it is those functions that are eventually called by the run time. Refer to Supported PDF Printing Functions for a list of currently supported op-codes, which you should cross-reference with the libharu API docs for more detail. The API docs can be found at https://github.com/libharu/libharu/wiki/API:-Document. There are a few programmatical differences in the COBOL emulation; see the Example section for more details.
parameters
The remaining parameters vary depending on the op-code chosen. They provide information and hold results for the operations specified. Parameters may be omitted from those operations that do not require them. You can refer to the cpdf.def COPY file and the libharu API documentation for more details.
Note: If a libharu parameter is allowed to be NULL, you can omit that parameter (if it is the last parameter), or to pass NULL to C$PDF. These parameters are denoted as (optional) in Supported PDF Printing Functions.
RESULT
A signed numeric data item that returns the status of the operation. The data type of the returned value is SIGNED-INT or PIC S9(9) COMP-5. Unless otherwise stated in Supported PDF Printing Functions, zero indicates success, and a non-zero result indicates failure.

DESCRIPTION

To use this library routine, you must include the COPY file cpdf.def, which is located in the AcuGT\sample\def (Windows) or sample/def (UNIX) sub-directory of your installation directory; copy this file into the Working-Storage section of any program that calls C$PDF. Calls to this library routine then call the third-party libharu PDF printing API (http://libharu.org/).

Example

The following example shows the functions for adding a new document and new page using the libharu API:

HPDF_Doc HPDF_New (HPDF_Error_Handler user_error_fn,
                   void *user_data);
HPDF_Page HPDF_AddPage (HPDF_Doc pdf);

These are the two equivalent COBOL calls that result in the run time calling the above functions:

call "C$PDF" using HPDF-NEW
             giving HPDF-DOC.
call "C$PDF" using HPDF-ADDPAGE
             HPDF-DOC,
             giving HPDF-PAGE.

As you can see in the COBOL syntax, the function names translate to all upper case and the underscores are replaced by hyphens. The parameters are all prefixed HPDF-, and again use upper case and hyphens.

Notes

All libharu values that are of type HPDF-REAL should be treated as PIC S9(9)v999. In most cases, this can be changed if you need more or less precision, but the values for PAGEHEIGHT, PAGEWIDTH, and HPDF-RECT may not be changed; these are assumed to have 3 digits of precision by the interface code.

Normally, the libharu functions return a status value, which is just returned to the COBOL program in the special RETURN-CODE register (or as the GIVING parameter). Where the libharu function returns a pointer to a structure. C$PDF will return a HANDLE, which can be passed to C$PDF as needed.

Some libharu functions return a HPDF_REAL value, which is a floating-point number. ACUCOBOL-GT cannot return such a value as part of the RETURN-CODE special register, and so the easiest way to code around this is to use REDEFINE, as follows:

01 HPDF-PAGEWIDTH-G.
   03 HPDF-PAGEWIDTH-R PIC S9(9) COMP-5 VALUE 0.
   03 HPDF-PAGEWIDTH REDEFINES HPDF-PAGEWIDTH-R
                     PIC S9(9)v999 COMP-5.

You can now use HPDF-PAGEWIDTH-R as the giving value, and the actual page width will be in HPDF-PAGEWIDTH:

HPDF_REAL_HPDF_Page_GetWidth(HPDF_Page page);

This is called from COBOL as:

call "C$PDF" using HPDF-PAGE-GETWIDTH, HPDF-PAGE
             giving HPDF-PAGEWIDTH-R

This call returns the width of the page (HPDF-PAGEWIDTH).

It is possible to use an implementation that uses both the PDF printing techniques (-P PDF) and C$PDF. You can call C$PDF with the name of an open file (see the CALL Statement, General Rule 6), as long as that file is using the PDF interface (-P PDF). There are some restrictions, which will cause the runtime to halt, such as creating new objects (FONT, PAGE, OUTLINE, etc...). Care must be taken to ensure that you do not modify the page in a way that causes the PDF interface to lose the current position.

  • Supported PDF Printing Functions
Parent topic: General Syntax and Library List
Related concepts
Spooler Print Formatting


Supported PDF Printing Functions

Not all of the functions in the libharu API are currently implemented in the C$PDF library routine. If you attempt to call an op-code for a function that is not implemented, you receive the following error:

Invalid or missing parameter to C$PDF

The following op-codes and their parameters are currently supported; cross-reference them with the libharu API documentation for full details on calling each function:

Note: op-codes without a return value, simply return a SIGNED-INT or PIC S9(9) COMP-5 data item indicating success (zero) or failure (non-zero) of the call.
HPDF-ADDPAGE
Parameters: None
Returns: HPDF-DOC handle
HPDF-ANNOTATION-SETBORDERSTYLE
Parameters:
1 | Annotation handle
2 | Subtype
3 | Width
4 | Dash-On
5 | Dash-Off
6 | Dash-Phase
HPDF-CREATEOUTLINE
Parameters:
1 | HPDF-DOC handle
2 | Parent (may be null)
3 | Title
4 | Encoder handle (may be null or omitted)
Returns: outline handle
HPDF-FREE
Parameters:
1 HPDF-DOC handle
HPDF-GETCURRENTENCODER
Parameters:
1 HPDF-DOC handle
Returns: current encoder handle
HPDF-GETENCODER
Parameters:
1 | HPDF-DOC handle
2 | Encoder name
Returns: encoder handle
HPDF-GETERROR
Parameters:
1 | HPDF-DOC handle
2 | Error detail (output, optional)
Returns: error code
HPDF-GETFONT
Parameters:
1 | HPDF-DOC handle
2 | Font name
Encoding name (optional)
Returns: font handle (not compatible with ACUCOBOL-GT graphical font handles)
HPDF-INSERTPAGE
Parameters:
1 | HPDF-DOC handle
2 | HPDF-PAGE handle
Returns: new HPDF-PAGE handle
HPDF-LINKANNOT-SETBORDERSTYLE
Parameters:
1 | Annotation handle
2 | Width
3 | Dash-On
4 | Dash-Off
HPDF-LINKANNOT-SETHIGHLIGHTMODE
Parameters:
1 | Annotation handle
2 | Mode
HPDF-LOADJPEGIMAGEFROMFILE
Parameters:
1 | HPDF-DOC handle
2 | Filename
HPDF-LOADJPEGIMAGEFROMMEM
Parameters:
1 | HPDF-DOC handle
2 | Pointer to image
3 | Size
HPDF-LOADPNGIMAGEFROMMEM
Parameters:
1 | HPDF-DOC handle
2 | Pointer to image
3 | Size
HPDF-LOADPNGIMAGEFROMFILE
Parameters:
1 | HPDF-DOC handle
2 | PNG filename
Returns: image handle (not compatible with ACUCOBOL-GT image handles)
HPDF-LOADPNGIMAGEFROMFILE2
Parameters:
1 | HPDF-DOC handle
2 | PNG filename
Returns: image handle (not compatible with ACUCOBOL-GT image handles)
HPDF-LOADDRAWIMAGEFROMMEM
Parameters:
1 | HPDF-DOC handle
2 | Pointer to image
3 | Width
4 | Height
5 | Color space
6 | Bits per component
HPDF-LOADRAWIMAGEFROMFILE
Parameters:
1 | HPDF-DOC handle
2 | Pointer to image
3 | Width
4 | Height
5 | Color space
HPDF-LOADTTFONTFROMFILE
Parameters:
1 | HPDF-DOC handle
2 | TTF filename
3 | TTF embedding
HPDF-LOADTTFONTFROMFILE2
Parameters:
1 | HPDF-DOC handle
2 | TTC filename
3 | TTC index
4 | TTC embedding
5 | Font name (output)
HPDF-LOADTYPE1FONTFROMFILE
Parameters:
1 | HPDF-DOC handle
2 | AFM filename
3 | PFM filename
4 | Font name (output)
HPDF-NEW
Parameters: No parameters
Returns: HPDF-DOC handle
HPDF-OUTLINE-SETDESTINATION
Parameters:
1 | HPDF-OUTLINE handle
2 | Destination handle
HPDF-OUTLINE-SETOPENED
Parameters:
1 | HPDF-OUTLINE handle
2 | Opened flag
HPDF-PAGE-BEGINTEXT
Parameters:
1 HPDF-PAGE handle
HPDF-PAGE-CLIP
Parameters:
1 HPDF-PAGE handle
HPDF-PAGE-CREATEDESTINATION
Parameters:
1 HPDF-PAGE handle
Returns: HDPF-DESTINATION handle
HPDF-PAGE-CREATELINKANNOT
Parameters:
1 | HPDF-PAGE handle
2 | HPDF-REC item
3 | Destination handle
Returns: Annotation handle
HPDF-PAGE-CREATETEXTANNOT
Parameters:
1 | HPDF-PAGE handle
2 | HPDF-RECT item
3 | Text
4 | Encoder handle (optional)
Returns: Annotation handle
HPDF-PAGE-ENDTEXT
Parameters:
1 HPDF-PAGE handle
HPDF-PAGE-FILL
Parameters:
1 HPDF-PAGE handle
HPDF-PAGE-FILLSTROKE
Parameters:
1 HPDF-PAGE handle
HPDF-PAGE-GETGMODE
Parameters:
1 HPDF-PAGE handle
Returns: graphics mode
HPDF-PAGE-GETHEIGHT
Parameters:
1 HPDF-PAGE handle
Returns: Page height *1000
HPDF-PAGE-GETWIDTH
Parameters:
1 HPDF-PAGE handle
Returns: Page width *1000
HPDF-PAGE-GRESTORE
Parameters:
1 HPDF-PAGE handle
HPDF-PAGE-GSAVE
Parameters:
1 HPDF-PAGE handle
HPDF-PAGE-LINETO
Parameters:
1 | HPDF-PAGE handle
2 | X coord
3 | Y coord
HPDF-PAGE-MOVETEXTPOS
Parameters:
1 | HPDF-PAGE handle
2 | X coord
3 | Y coord
HPDF-PAGE-MOVETO
Parameters:
1 | HPDF-PAGE handle
2 | X coord
3 | Y coord
HPDF-PAGE-RECTANGLE
Parameters:
1 | HPDF-PAGE handle
2 | X coord
3 | Y coord
4 | Width
5 | Height
HPDF-PAGE-SETDASH
Parameters:
1 | HPDF-PAGE handle
2 | Number of dash pattern parameters (0-8)
3 | Dash pattern parameters
4 | Phase (optional)
HPDF-PAGE-SETFONTANDSIZE
Parameters:
1 | HPDF-PAGE handle
2 | HPDF-FONT handle
3 | Font size
HPDF-PAGE-SETGRAYFILL
Parameters:
1 | HPDF-PAGE handle
2 | Gray fill percent
HPDF-PAGE-SETGRAYSTROKE
Parameters:
1 | HPDF-PAGE handle
2 | Gray stroke percent
HPDF-PAGE-SETLINECAP
Parameters:
1 | HPDF-PAGE handle
2 | Line cap indicator
HPDF-PAGE-SETLINEJOIN
Parameters:
1 | HPDF-PAGE handle
2 | Line join indicator
HPDF-PAGE-SETLINEWIDTH
Parameters:
1 | HPDF-PAGE handle
2 | Line width
HPDF-PAGE-SETRGBFILL
Parameters:
1 | HPDF-PAGE handle
2 | Red value
3 | Green value
4 | Blue value
HPDF-PAGE-SETRGBSTROKE
Parameters:
1 | HPDF-PAGE handle
2 | Red value
3 | Green value
4 | Blue value
HPDF-PAGE-SETSIZE
Parameters:
1 | HPDF-PAGE handle
2 | Page size indicator
3 | Direction
HPDF-PAGE-SETTEXTLEADING
Parameters:
1 | HPDF-PAGE handle
2 | Text leading value
HPDF-PAGE-SHOWTEXT
Parameters:
1 | HPDF-PAGE handle
2 | Text
3 | Text length in characters (optional)
HPDF-PAGE-SHOWTEXTNEXTLINE
Parameters:
1 | HPDF-PAGE handle
2 | Text
HPDF-PAGE-STROKE
Parameters:
1 HPDF-PAGE handle
HPDF-PAGE-TEXTOUT
Parameters:
1 | HPDF-PAGE handle
2 | X
3 | Y
4 | Text
5 | Text length in characters (optional)
HPDF-PAGE-TEXTWIDTH
Parameters:
1 | HPDF-PAGE handle
2 | Text
3 | Text length in characters (optional)
HPDF-PAGE-MEASURETEXT
Parameters:
1 | HPDF-PAGE handle
2 | Text
3 | Width
4 | Word wrap flag
5 | Actual width (optional)
HPDF-PAGE-TEXTOUT
Parameters:
1 | HPDF-PAGE handle
2 | X
3 | Y
4 | Text
5 | Text length in characters (optional)
HPDF-PAGE-TEXTWIDTH
Parameters:
1 | HPDF-PAGE handle
2 | Text
3 | Text length in characters (optional)
HPDF-SAVETOFILE
Parameters:
1 | HPDF-DOC handle
2 | Save filename (may use @[DISPLAY] syntax for thin client)
HPDF-SETCOMPRESSIONMODE
Parameters:
1 | HPDF-DOC handle
2 | Compression mode
HPDF-SETCURRENTENCODER
Parameters:
1 | HPDF-DOC handle
2 | Encoder name
HPDF-SETINFOATTR
Parameters:
1 | HPDF-DOC handle
2 | Info attribute type
3 | Info attribute value
HPDF-SETINFODATEATTR
Parameters:
1 | HPDF-DOC handle
2 | Date attribute indicator
3 | HPDF-DATE
HPDF-SETPASSWORD
Parameters:
1 | HPDF-DOC handle
2 | Owner password
3 | User password (optional)
HPDF-SETPERMISSION
Parameters:
1 | HPDF-DOC handle
2 | Permission type
HPDF-SETVIEWERPREFERENCE
Parameters:
1 | HPDF-DOC handle
2 | HPDF-Viewer preference value
HPDF-TEXTANNOT-SETICON
Parameters:
1 | Annotation handle
2 | Icon indicator
HPDF-TEXTANNOT-SETOPENED
Parameters:
1 | Annotation handle
2 | Open mode
HPDF-USECNSENCODINGS
Parameters:
1 HPDF-DOC handle
HPDF-USECNSFONTS
Parameters:
1 HPDF-DOC handle
HPDF-USECNTENCODINGS
Parameters:
1 HPDF-DOC handle
HPDF-USECNTFONTS
Parameters:
1 HPDF-DOC handle
HPDF-USEJPENCODINGS
Parameters:
1 HPDF-DOC handle
HPDF-USEJPFONTS
Parameters:
1 HPDF-DOC handle
HPDF-USEKRENCODINGS
Parameters:
1 HPDF-DOC handle
HPDF-USEKRFONTS
Parameters:
1 HPDF-DOC handle
HPDF-USEUTFENCODINGS
Parameters:
1 HPDF-DOC handle
Parent topic: C$PDF


C$RECOVER

This routine opens the transaction log file defined in the LOG_FILE configuration variable and replays all of the file operations recorded in it on the appropriate data files.

Note that file systems other than Vision may require you to use their own recovery routines, instead of C$RECOVER. Please refer to your file system manufacturer's documentation to learn how the file system handles recovery procedures.

Usage

CALL "C$RECOVER".

Description

This routine allows you to recover from a hardware failure or power outage that may have left your data files in a corrupt state. C$RECOVER is helpful for recovering from error 98s and from any error that leaves your data damaged or possibly destroyed.

In order to use this routine, you need to have been logging transactions with the START TRANSACTION and COMMIT TRANSACTION verbs. These cause file operations to be logged in log files that you designate with the LOG-FILE. Use the LOG_INCLUDE_PATTERN or LOG_EXCLUDE_PATTERN variables to determine which files' operations are recorded in the log file.

You also need a good backup of your data files. This backup should have been created just before you cleared or deleted the log file. You use your backup to restore the damaged files. Then you use C$RECOVER to read the log and recreate all of the file operations in the log, in the same sequence they were logged. These file operations are replayed on the data files. Use the LOG_RECOVER_REPORT variable to write an audit trail of the recovery process to a file.

The result is that your data files are brought up to date. After recovery, all files will be in a consistent state, because only committed (completed) transactions will be replayed from the log.

One way to use this routine is described here. First get everyone off the system. Then restore your clean backup files to their original locations. (It's a good idea to have more than one backup, because you will need a clean backup in order to recover.) Then run a COBOL program that calls the C$RECOVER routine (for example, CALL C$RECOVER). Make sure that the LOG-FILE configuration variable is set correctly. Repeat this procedure for each log file.

If a GIVING phrase is omitted, the special register RETURN-CODE is updated: a zero indicates a successful recovery, and any other value indicates a failure. The failure value corresponds to a transaction error code; see Transaction Error Codes in Appendix E of the ACUCOBOL-GT Reference Manual for a full list of values.

To make sure that your data can be recovered, follow these guidelines:

  1. Commit all transactions before you make your data file backups.
  2. Clear (or delete) your old log files as soon as your backup is complete and you know you have a good backup.
  3. Don't permit any file activity between the time you make your backup and the time you clear or delete the logs.
  4. It is possible to have multiple log files. You may periodically back up the log file and start a new one, if you are careful not to do this while there is any activity on the log or data files. Just be sure to run C$RECOVER on each log file in the same order in which they were written.
  5. Don't permit any activity on the data files during recovery.
  6. If any log file gets corrupted or destroyed, immediately make data file backups and clear or delete the old log.
Parent topic: General Syntax and Library List
Related reference
LOG_RECOVER_REPORT
LOG_EXCLUDE_PATTERN
LOG_INCLUDE_PATTERN
Transaction Error Codes


C$REDIRECT

This routine is used to install and uninstall file I/O handlers. The routine gives you the ability to redirect file I/O operations to other, separate COBOL programs (handlers) that perform file I/O operations in addition to, or instead of the original operation.

For example, you can augment a file I/O operation to act on an additional file without rewriting the original application. C$REDIRECT specifies the name of the handler(s) that performs the additional operations. The handler is simply a COBOL program. This feature is activated or deactivated by calling C$REDIRECT. Information is passed to the handler program using standard COBOL linkage items. Each program has its own set of I/O handlers. This means that only the module (or subprogram) calling C$REDIRECT is affected.

Usage

CALL "C$REDIRECT"
    USING HANDLER-FUNCTION, HANDLER-VERSION, HANDLER-NAME,
        [PREVIOUS-HANDLER-NAME],
    GIVING HANDLER-STATUS

Parameter

HANDLER-FUNCTION any numeric value | This parameter has three possible values, HANDLER-FUNCTION-PRE, HANDLER-FUNCTION-REPLACE, and HANDLER-FUNCTION-POST (defined in filesys.def).
HANDLER-VERSION any numeric value | Specifies the version of the linkage items to be passed to the handler program (defined in filesys.def). The linkage items are defined in handler.cpy. If later releases change the format of the linkage items, you can use HANDLER-VERSION to specify which version of the linkage items to use. Currently, the only legal values for this parameter are 1 and 2.
HANDLER-NAME PIC X(n) | Specifies the name of the handler program to be installed. Use NULL to uninstall a handler that has been previously installed.
PREVIOUS-HANDLER-NAME PIC X(n) (optional) | After a successful call to C$REDIRECT, this data item holds the name of the previously installed HANDLER-FUNCTION. It will contain spaces if there was no previous handler of this type.
HANDLER-STATUS signed numeric value (optional) | After a call to C$REDIRECT, this data item contains the status of the action. A 1 indicates that the install or uninstall action has succeeded and 0 indicates failure. Possible reasons for failure include an unsupported HANDLER-VERSION or an unsupported operation version.

Description

C$REDIRECT allows you to install as many as three discrete handlers:

  • The "pre" handler executes before the file I/O statement.
  • The "replace" handler executes in place of the file I/O statement.
  • The "post" handler executes after the file I/O statement.

These handlers may be used together in any combination, but each must be installed with a separate call to C$REDIRECT. All standard file I/O statements trigger the installed handlers (standard file I/O statements include: OPEN, CLOSE, READ, READ NEXT, READ PREVIOUS, WRITE, REWRITE, DELETE, DELETE FILE, START, COMMIT, and ROLLBACK). Information is passed to the handlers via standard COBOL linkage items. These items are described in the file handler.cpy that is installed with the ACUCOBOL-GT development system. Once a handler is installed, all file I/O for all files is redirected through the handler.

This routine can be used with the SORT and MERGE statements. The I/O handlers are used on the files listed in the USING and GIVING phrases when these verbs execute implicit OPEN, READ, NEXT, WRITE, AND CLOSE operations. In this situation, the handlers will be called more than once for each execution of the verb.

When an installed handler executes, it can return its status via the linkage item HANDLER-STATUS-CODE. This item is meant to return the standard COBOL file status code that is normally returned by a file operation. The value returned is made available in the file's status variable. The set of codes used is up to the developer, as long as they follow these rules:

  • Any code that starts with a 0 is considered successful.
  • Any code that starts with a 1 is considered to be an "at end" condition.
  • Any code that starts with a 2 is considered to be an "invalid key" condition.

The first handler to return an unsuccessful status code will be the last portion of the file operation to be executed, whether the remaining operation is the regular file operation or another handler. For example, a "pre" handler returning an error will preclude the execution of the normal file operation (or a "replace" handler, if defined) and the "post" handler, if defined. Declaratives are run as appropriate when a handler returns an error.

Note: C$RERR and other library functions that report internal file error codes may not return the expected results after executing a handler program.
Parent topic: General Syntax and Library List


C$REGEXP

This routine allows you to search strings using regular expressions.

Usage

CALL "C$REGEXP"
    USING OP-CODE, parameters
    GIVING return-value

Parameters

Op-codes specify the operation to perform. Each operation is defined in acucobol.def and is described in detail below. Op-codes include:
Code | Operation
1 | AREGEXP-GET-LEVEL
2 | AREGEXP-COMPILE
3 | AREGEXP-MATCH
4 | AREGEXP-RELEASE-MATCH
5 | AREGEXP-RELEASE
6 | AREGEXP-NUMGROUPS
7 | AREGEXP-GETMATCH
20 | AREGEXP-LAST-ERROR

Parameters vary depending on the operation selected. They provide information and hold results.

return-value: Numeric data item.

Unless otherwise noted, each operation returns a value or a status in return-value. Its contents vary by operation and the result of the operation.

Description

This routine allows you to use a regular expression to search a text string.

A regular expression is a formula for matching strings that have a certain pattern. For a complete description of regular expressions, see the POSIX 1003.2 standard appropriate for your platform. Windows platforms use the CAtlRegExp library; UNIX platforms use the POSIX C routines native to the platform.

A simple use of C$REGEXP is outlined in the following steps.

  1. Use the AREGEXP-GET-LEVEL op-code to validate that the host platform provides support for regular expressions.
  2. Validate and compile your regular expression with op-code AREGEXP-COMPILE. Your program should include an error handling routine in the event that the compiler finds an error in the expression.
  3. Use op-code AREGEXP-MATCH to apply a compiled regular expression to a string to search for a match. You may want to do this iteratively to find all matches in the string.
  4. Use op-codes AREGEXP-NUMGROUPS and AREGEXP-GETMATCH to work with subexpression matches.
  5. Manage the memory used by this routine with op-codes AREGEXP-RELEASE-MATCH and AREGEXP-RELEASE.

Op-codes and Parameters

AREGEXP-GET-LEVEL (op-code 1)

This operation indicates whether regular expression support is available on the host. Its usage is:

CALL "C$REGEXP" USING AREGEXP-GET-LEVEL GIVING return-value

The value of return-value can be one of the following (defined in acucobol.def):

AREGEXP-NONE | 0 | regular expression processing is not available
AREGEXP-WINDOWS | 1 | Windows regular expressions supported
AREGEXP-POSIX | 2 | POSIX regular expressions supported

AREGEXP-COMPILE (op-code 2)

This operation compiles a regular expression to ensure that it has a valid form, returning a handle to the compiled regular expression or NULL if there is an error. Its usage is:

CALL "C$REGEXP" USING AREGEXP-COMPILE, reg-expr, flags
                GIVING return-value

reg-expr

Must be a NULL-terminated regular expression. It must be NULL-terminated because trailing spaces are allowed in regular.

flags

(Optional) is the sum of one or more of the following values (defined in acucobol.def):
AREGEXP_COMPILE_IGNORECASE | 1 | Ignore case when matching patterns. (Windows or UNIX)
AREGEXP_COMPILE_BASIC | 2 | Change the type of regular expression from extended to basic. (UNIX only) (For an explanation of extended and basic, see the POSIX 1003.2 standard.)
AREGEXP_COMPILE_NO_SPECIAL | 4 | Treat all characters as ordinary characters with no special meaning. (UNIX only)
AREGEXP_COMPILE_NO_SUB | 8 | When matching, determine only if there is a match, without returning the offsets of the match. (UNIX only)
AREGEXP_COMPILE_NEWLINE | 16 | Treat newlines as special (end-of-line marker) characters. (UNIX only)
AREGEXP_COMPILE_NO_REGEXP | 32 | Treat reg-expr as text, not as a regular expression.

return-value contains a handle to the compiled expression, or NULL if an error occurred.

AREGEXP-MATCH (op-code 3)

This operation applies a regular expression to a string, and returns a handle. The match-start parameter must be initialized before AREGEXP-MATCH is attempted, as it specifies the start position in which matching should begin. To see if there is a match you need to check match-start; If it is 0, there is no match. Its usage is:

CALL "C$REGEXP" USING AREGEXP-MATCH,
   reg-expr-handle, string, length, match-start, match-end
   GIVING return-value
reg-expr-handle | is a handle to a regular expression returned by AREGEXP-COMPILE.
string | is the string to test for a match.
length | is the length of string. If length is zero, the size of string is used.
match-start | as an input parameter, match-start indicates where the matching should begin. As an output parameter, it returns the index of the start of the pattern that matched.
match-end | returns one byte beyond the pattern that matched. To test the string for additional matches, start a new AREGEXP-MATCH after setting match-start to match-end.
return-value | contains a handle to the match or zero if no match is found or an error occurred.

AREGEXP-RELEASE-MATCH (op-code 4)

This operation frees memory that is allocated when AREGEXP-MATCH is called. Return-value is not used. Its usage is:

CALL "C$REGEXP" USING AREGEXP-RELEASE-MATCH match-handle
match-handle is a handle to a match returned by AREGEXP-MATCH.

AREGEXP-RELEASE (op-code 5)

This operation frees the memory allocated when AREGEXP-COMPILE is called. Return-value is not used. Its usage is:

CALL "C$REGEXP" USING AREGEXP-RELEASE reg-expr-handle
reg-expr-handle is a handle to a regular expression returned by AREGEXP-COMPILE.

AREGEXP-NUMGROUPS (op-code 6)

This operation returns the number of substrings that matched any subgroups in the regular expression. Its usage is:

CALL "C$REGEXP" USING AREGEXP-NUMGROUPS match-handle
                GIVING return-value
match-handle | is a handle returned by AREGEXP-MATCH.
return-value | returns the number of matches.

Depending on the construction of a regular expression, it is possible for a subgroup of the regular expression to match multiple substrings. This operation reports the number of instances found in the last AREGEXP-MATCH operation. For more information, rules, and examples, see the POSIX 1003.2 documentation or one of the many books available on regular expressions.

AREGEXP-GETMATCH (op-code 7)

This operation returns a set of indices into a string passed to AREGEXP-MATCH that match the subexpression of the regular expression. Its usage is:

CALL "C$REGEXP"
    USING AREGEXP-GETMATCH, match-handle, group,
    idx-start, idx-end
    GIVING return-value

The parameters are defined as follows:

match-handle | is a handle returned by AREGEXP-MATCH.
group | is a number between 1 and the value returned by AREGEXP-NUMGROUPS.
idx-start | returns an index into the beginning of the string that matches the subexpression of the regular expression.
idx-end | returns an index to the end of the string that matches the subexpression of the regular expression.
return-value | returns 1 if the operation succeeds, and zero if there is an error.

AREGEXP-LAST-ERROR (op-code 20)

This operation returns the last error code returned by a call to C$REGEXP. Its usage is:

CALL "C$REGEXP" USING AREGEXP-LAST-ERROR GIVING return-value

The error value is returned in return-value. The possible error values (described in acucobol.def) have the following meanings:

AREGEXP-ERROR-NO-ERROR | 0 | No error
AREGEXP-ERROR-NO-MEMORY | 1 | Insufficient memory to handle the request
AREGEXP-ERROR-BRACE-EXPECTED | 2 | A closing brace is missing
AREGEXP-ERROR-PAREN-EXPECTED | 3 | A closing parenthesis is missing
AREGEXP-ERROR-BRACKET-EXPECTED | 4 | A closing bracket is missing
AREGEXP-ERROR-UNEXPECTED | 5 | An unknown error occurred
AREGEXP-ERROR-EMPTY-RANGE | 6 | An empty range was given
AREGEXP-ERROR-INVALID-GROUP | 7 | The group provided was invalid
AREGEXP-ERROR-INVALID-RANGE | 8 | An invalid range was given
AREGEXP-ERROR-EMPTY-REPEATOP | 9 | A repeat operator was given on an empty subexpression
AREGEXP-ERROR-INVALID-INPUT | 10 | The input was invalid
AREGEXP-ERROR-INVALID-HANDLE | 11 | The handle is not a regular expression handle or a match handle
AREGEXP-ERROR-INVALID-ARGUMENT | 12 | One of the arguments given is invalid
AREGEXP-ERROR-INVALID-CALL-SEQ | 13 | The order of C$REGEXP operations is an invalid sequence.
AREGEXP-ERROR-NO-MATCH | 14 | The regular expression did not find a match in the given string.
Note: If the error code returned does not match a value in the list, it may be that the value is coming from the host's regular expression library. See the documentation for the host's regular expression library.
Parent topic: General Syntax and Library List


C$RERR

Returns extended file status information.

Usage

CALL "C$RERR"
    USING EXTEND-STAT, TEXT-MESSAGE, STATUS-TYPE

Parameters

EXTEND-STAT (returned) | PIC X(5) or larger; PIC X(7) or larger under VMS
TEXT-MESSAGE (returned) | PIC X(n)
STATUS-TYPE (input) | Numeric parameter

Comments

C$RERR must be passed a USING argument that should be PICTURE X(5) or larger. This argument is filled in with either the extended file status caused by the last file I/O, or the extended transaction status caused by the last transaction operation. The value of STATUS-TYPE determines which status will be filled in.

A text message is available for some 9D errors, which are host system errors. When a text message is available, it's moved into the data item TEXT-MESSAGE, and returned as the second parameter. You can use TEXT-MESSAGE to display text to the user, so the user can decide what action to take. This parameter is ignored for transaction status.

The third parameter, STATUS-TYPE, controls whether file status or transaction status information is returned by the routine. If STATUS-TYPE is set to 1 or the parameter is omitted, file status is returned. If STATUS-TYPE is set to 2, transaction status is returned.

The first two characters of the extended file status are identical to the normal FILE STATUS value returned by ACUCOBOL-GT for a file operation. The last two characters further clarify the reason for the particular FILE STATUS value. The values used here are listed in the file status table found in Appendix E . If the file status (first two characters) is 30, the remainder of the information is the operating system's status code explaining what caused the error.

On some systems, the operating system requires more than two digits for its status codes. That is why the C$RERR routine may be passed a field that is larger than four characters. Whenever an error 30 occurs, the operating system's status value is returned in this extended field. The number returned is a left-justified decimal value. If the receiving field is too small, the right-most digits are returned. If the receiving field is too large, the excess characters are filled with spaces.

The first two characters of the extended transaction status are identical to the contents of the TRANSACTION-STATUS register. The last two characters further clarify the reason for the particular transaction status value. The values used here are listed in the transaction status table found in Appendix E .

In a few cases, there may also be a tertiary status code. If there is one, a comma will be placed immediately after the secondary status code, and the tertiary code will then appear left-justified.

Parent topic: General Syntax and Library List


C$RERRNAME

This routine returns the name of the last file used in an I/O statement. It can be used in conjunction with C$RERR to determine file errors.

Usage

CALL "C$RERRNAME"
    USING FILE-NAME

Parameter

FILE-NAME PIC X(n) This field is filled in with the name of the last file that was involved in an I/O statement. If the last statement was a transaction statement, then this routine returns spaces. The file name returned is the one found in the file's ASSIGN clause when it was opened. Any name translations specified in the configuration file are reflected in the returned name, but the FILE-PREFIX and FILE-SUFFIX used are not.
Parent topic: General Syntax and Library List


C$RESOURCE

Use C$RESOURCE to load a resource file and get a resource handle or to destroy the resource handle and free any memory associated with it. The AcuBench Screen Designer saves changes made to an ActiveX control in a "state" resource file. The runtime uses the information in this resource file when displaying the ActiveX control.

After an ActiveX control is displayed you may destroy the resource handle used to initialize it. The ActiveX control only references this resource handle during the first DISPLAY or MODIFY which sets the initial-state property (usually the first display). In general, you should destroy resource handles to free memory after all ActiveX controls that use them have been displayed.

Usage

CALL "C$RESOURCE"
    USING OP-CODE, parameters
    GIVING RESOURCE-HANDLE

Parameters

OP-CODE Numeric parameter | Op-code indicates the desired operation. The file "activex.def" contains level 78 symbolic names for these operations.
Parameters | Vary depending on the op-code chosen. These are described in the Comments section below.
RESOURCE-HANDLE PIC 9(9) | RESOURCE-HANDLE holds the return value of C$RESOURCE. Values less than or equal to zero indicate errors. This is only used by the CRESOURCE-LOAD operation.

Comments

There are two operations available in C$RESOURCE:

  1. load a resource file and return a resource handle
  2. destroy a resource handle and free its associated memory

To use C$RESOURCE, you pass an op-code as the first parameter, followed by one additional parameter. The op-code determines which operation is performed and the meaning of the additional parameter.

Currently, there are two operations:

CRESOURCE-LOAD

This operation loads a resource file from disk and returns a resource handle. It takes one additional parameter:

NAME This is an alphanumeric literal or data item that is the file name of the resource file. This must be a resource file generated by AcuBench. The file usually ends with .res.
Note: When you are running in a thin client environment, and a file name beginning with "@[DISPLAY]" is passed to this routine, it will attempt to access the file in the display host's file system. It does not download the file from the server.

CRESOURCE-DESTROY

This operation destroys a resource handle and releases its memory. It takes one additional parameter:

RES-HANDLE This is a resource handle returned by CRESOURCE-LOAD.
Note: The behavior of this library routine is affected by the setting of the FILENAME_SPACES configuration variable that may or may not allow spaces in a file name. See the documentation on FILENAME_SPACES in Appendix H, Configuration Variables for information about the terminating character for path names.

Example

CALL "C$RESOURCE" USING CRESOURCE-LOAD, "PROGRAM1.RES"
   GIVING RES-HANDLE.
IF RES-HANDLE > 0 THEN
   DISPLAY MSCHART LINE 10 COLUMN 10 LINE 5 SIZE 40
      INITIAL-STATE = (RES-HANDLE, "MSCHART-1-INITIAL-STATE")
      HANDLE IN MSCHART-1
   CALL "C$RESOURCE" USING CRESOURCE-DESTROY, RES-HANDLE
END-IF
Parent topic: General Syntax and Library List


C$RUN

ACUCOBOL-GT for Windows supports an alternate method for running other programs. This is through the library routine C$RUN. This library routine works identically to the SYSTEM library routine, except that the calling program does not wait for the called program to finish. Instead, both programs run in parallel.

Usage

CALL "C$RUN"
    USING COMMAND-LINE,
    GIVING STATUS-VAL

Parameters

COMMAND-LINE PIC X(n) | Contains the operating system command line to execute.
STATUS-VAL Any numeric data item | Returns 0 if successful or -1 if not.

Description

C$RUN sets STATUS-VAL to -1 if the call fails or to 0 if it succeeds.

C$RUN is implemented only under the Windows and Windows NT versions of ACUCOBOL-GT. On other systems, it always returns 1.

C$RUN is supported in Thin Client environments. To execute a program on the display host in a thin client environment, add the prefix @[DISPLAY]: to the name of any program that resides on the client machine. For example:

C$RUN "@[DISPLAY]:C:\notepad myfile.txt
Parent topic: General Syntax and Library List


C$SETERRORFILE

This routine sets the name of the runtime error file. Format specifiers may be used in the name. If the resulting file name differs from the current runtime error file name, the runtime closes the current error file, attempts to rename it to the new name, and opens the new file in extend mode. Subsequent error and trace messages are written to the new error file. Note that the rename operation overwrites an existing file. Also, the rename operation may fail if the original error file is in use by other runtime processes. In this case the original file will be left alone and the new file will start empty.

Usage

CALL "C$SETERRORFILE"
    USING ERROR-FILE-NAME

Parameters

ERROR-FILE-NAME PIC X(n) Contains the name of the error file. The runtime error file format specifiers may be used.

Comments

This routine provides a means for applications to embed identifying information in the runtime error file name. For example, after a user logs in, an application can change the name of the runtime error file so that it includes the user name.

If the runtime fails and the user calls customer support, the support analyst can search the directory containing runtime error files and quickly identify the one with the user's name to help resolve the issue. This is especially useful in situations where the runtime was launched from AcuConnect using an entry in the AcuConnect alias file. Since one alias is used by many users, there is potentially only one error file. In this case, error messages tied to failures experienced by a particular user may be lost or difficult to read because multiple runtime processes are writing to the same error file. C$SETERRORFILE helps by allowing you to set the error file name from COBOL for a particular runtime instance.

Parent topic: General Syntax and Library List


C$SETEVENTDATA

When an ActiveX control or COM object event procedure exits, it can send information back to the control through the event parameters. These parameters are stored in the control and can be set by calling C$SETEVENTDATA before the control's event procedure exits.

Usage

CALL "C$SETEVENTDATA"
    USING EVENT-CONTROL-HANDLE, SRC-ITEM-1, [SRC-ITEM-2, ...]
    GIVING RESULT-CODE

Parameters

EVENT-CONTROL-HANDLE USAGE HANDLE | Handle to the control that triggered the event.
SRC-ITEM-1 Any COBOL data type | The first source data item.
SRC-ITEM-2, . . . Any COBOL data type (optional) | Any number of source items.
RESULT-CODE Signed numeric value | Receives the result-code for the operation. This will be 0 to indicate success or a negative value to indicate failure. (Microsoft defines many standard result codes in their documentation. Note that these are usually in hexadecimal notation.)

Comments

C$SETEVENTDATA converts the COBOL-type data in the source items to the corresponding event parameter types.

You are responsible for specifying compatible types. For example, if the source item you specify is alphabetic, and the event parameter you are setting is a signed integer, C$SETEVENTDATA will try to read a number from the alphabetic item and move it to the event parameter. This is not a programming error and neither the compiler nor runtime will warn you about it.

Example

Suppose you have displayed an ActiveX control that triggers an event called AxEventOne which has three parameters. You would use the following COBOL syntax to get the event parameters, add two to each one and set the event parameters to their new values:

WHEN AxEventOne
   CALL "C$GETEVENTDATA" USING EVENT-CONTROL-HANDLE,
      PARAM-1, PARAM-2, PARAM-3
   ADD 2 TO PARAM-1
   ADD 2 TO PARAM-2
   ADD 2 TO PARAM-3
   CALL "C$SETEVENTDATA" USING EVENT-CONTROL-HANDLE,
      PARAM-1, PARAM-2, PARAM-3

See ActiveX and COM Events for more examples of how to set event parameters for ActiveX events.

Parent topic: General Syntax and Library List


C$SETEVENTPARAM

C$SETEVENTPARAM is an alternate way to set event parameters for ActiveX controls. Use it to set a single event parameter when there are several for an event. To use this routine you must know the actual name of the parameter. You may determine these names by reading the ActiveX control's documentation or by looking at the definitions in the copy book for the ActiveX control.

It is common for an ActiveX event to receive many parameters. C$SETEVENTPARAM allows you to set the values of only the parameters you care about.

Please note that C$SETEVENTPARAM cannot be used to set event parameters for COM objects. You must use C$SETEVENTDATA for COM objects.

Usage

CALL "C$SETEVENTPARAM"
    USING EVENT-CONTROL-HANDLE, PARAM-NAME, PARAM-VALUE
    GIVING RESULT-CODE

Parameters

EVENT-CONTROL-HANDLE USAGE HANDLE | Handle to the control that generated the event.
PARAM-NAME PIC X(n) | The symbolic name of the event parameter.
PARAM-VALUE Any COBOL data type | Source item containing the event parameter's value.
RESULT-CODE Signed numeric value | Receives the result-code for the operation. This will be 0 to indicate success or a negative value to indicate failure. (Microsoft defines many standard "result codes" in their documentation. Note that these are usually in hexadecimal notation.)

Comments

C$SETEVENTPARAM converts the COBOL-type data in the source item to the named event parameter's type. Using this routine instead of C$SETEVENTDATA will make your code more readable. The object code will be a little larger and calls to this routine will take a little longer than calls to C$SETEVENTDATA. However, these differences will probably be unnoticeable and the benefits of readable code outweigh the performance and size considerations.

You are responsible for specifying a compatible types. For example, if the source item you specify is alphabetic, and the event parameter you are setting is a signed integer, C$SETEVENTPARAM tries to read a number from the alphabetic item and move it to the event parameter. This is not a programming error and neither the compiler nor runtime warns you about it.

Example

Suppose you have displayed an ActiveX control that triggers an event called AxEventOne which has three parameters. Then suppose that PARAM-1 and PARAM-2 contain information about the event and that only PARAM-3 is meant to be set by the event procedure. Since PARAM-3 is the third parameter, to set it you would have to pass two dummy parameters using C$SETEVENTDATA. For example:

CALL "C$SETEVENTDATA"
   USING EVENT-CONTROL-HANDLE, 0, 0, PARAM-3.

However, If you determined that the name of PARAM-3 in the ActiveX control was Param3. You could then use C$SETEVENTPARAM to accomplish this task in a more elegant and readable way. For example,

CALL "C$SETEVENTPARAM"
   USING EVENT-CONTROL-HANDLE, "Param3", PARAM-3.

See ActiveX and COM Events for more examples of how to set event parameters for ActiveX events.

Parent topic: General Syntax and Library List


C$SETVARIANT

This routine sets data items referenced by Variant handles. Note that there is also a C$GETVARIANT routine that retrieves data referenced by a Variant handle.

C$SETVARIANT converts COBOL type data to Variant type data. Programs that call ACUCOBOL-GT using the ACUCOBOL-GT Automation Server or runtime DLL pass their parameters (by reference) as Variant types. The COBOL program receives handles to the Variant data. C$SETVARIANT sets the data associated with a particular handle to the value of a COBOL data item. The data is automatically converted to the proper Variant format.

Usage

CALL "C$SETVARIANT"
    USING SRC-ITEM, H-VARIANT
    GIVING RESULT-CODE

Parameters

SRC-ITEM Any COBOL data type | The source data item.
H-VARIANT USAGE HANDLE | Handle to Variant type data. Data passed in from a program calling ACUCOBOL-GT using the ACUCOBOL-GT Automation Server or runtime DLL is in the form of handles to Variant type data.
RESULT-CODE Signed numeric value | Receives the result code for the operation. This will be 0 or a positive value to indicate success or a negative value to indicate failure. Under Microsoft Windows this is a code of type HRESULT that can be looked up in Microsoft documentation to determine the reason for the failure or additional information about the success.

Comments

The COBOL data item SRC-ITEM is converted to Variant type data, and is stored in the Variant item associated with H-VARIANT.

C$SETVARIANT creates a new variant to store the initial value of the handle item passed to it is LOW-VALUES or SPACES. (It is your responsibility to free this variant using the DESTROY verb.)

The C$SETVARIANT library routine and OLE SAFEARRAY data type are supported in thin client environments, regardless of the kind of operating system on the server. However, be careful when using C$SETVARIANT in thin client environments, because it generates network traffic and can affect performance. When using this library routine in a thin client environment, you should pass only small amounts of data. Note that C$GETVARIANT is not supported in thin client environments at this time.

Parent topic: General Syntax and Library List


C$SLEEP

This routine causes the program to pause in a machine efficient fashion.

Usage

CALL "C$SLEEP"
    USING NUM-SEC

Parameter

NUM-SEC Numeric or alphanumeric parameter The number of seconds to sleep.

This parameter is a an unsigned fixed-point numeric parameter, or an alphanumeric data item containing an unsigned fixed-point number.

Description

This routine can be used to impose slight delays in loops. For example, you might want to introduce a delay in a loop that is waiting for a record to become unlocked. Calling C$SLEEP will allow the machine to execute other programs while you wait.

The C$SLEEP routine is passed one argument. This argument is the number of seconds you want to pause. For example, to pause the program for five and a half seconds, you could use either of the following:

CALL "C$SLEEP" USING 5.5
CALL "C$SLEEP" USING "5.5"

The amount of time paused is only approximate. Depending on the granularity of the system clock and the current load on the machine, the time paused may actually be shorter or longer than the time requested. Typically, the time paused will be within one second or one-tenth of a second of the amount requested (unless the machine is excessively loaded).

If the sleep duration is zero, this function does nothing. If the sleep duration is signed, this function generates a runtime error.

Parent topic: General Syntax and Library List


C$SOCKET

This routine can be used to communicate with other processes on remote or local hosts. This provides an interface to inter-process communication via sockets.

Usage

CALL "C$SOCKET"
    USING OP-CODE, parameters

Parameters

OP-CODE Numeric parameter | Specifies the operation to perform. These are defined in the description below.
Parameters | Various types defined in socket.def.

The remaining parameters vary depending on the operation selected. They provide information and hold results for the operations specified.

Description

All parameters passed to C$SOCKET are passed BY REFERENCE. The C$SOCKET routine provides any necessary conversions. Numeric arguments passed to this routine must be declared as COMP 5.

Note: If a COBOL thread calls one of these operations, all threads are blocked until the operation is finished and control is returned to the COBOL program.

AGS-CREATE-SERVER (op-code 1)

This operation creates a server-side socket. It must be called once at the beginning of any service you create. If the call is successful, the value in RETURN-CODE should be moved to a data item that is USAGE HANDLE. This data item is then passed as the socket handle to AGS-ACCEPT or AGS-NEXT-READ. This socket handle is not available for read or write operations. You can use the GIVING phrase instead of MOVE to store the value in a data item. If the call fails, RETURN-CODE is NULL. This operation has a single parameter:

port-number a numeric value specifying the port on which the socket is created. All clients must use the same port number to connect to this server.

AGS-ACCEPT (op-code 2)

This operation waits for a connection from a client. It blocks other calls while waiting, and returns only after a client has attempted to connect. If a client successfully connects, the value in RETURN-CODE is a socket handle that may be used to communicate with the client using AGS-WRITE and AGS-READ. This operation is called once if the server is a single-client server. In that case, once the client has connected it is safe to close the original server socket (created in AGS-CREATE-SERVER) using AGS-CLOSE, and use only the socket handle returned by this operation. This operation has a single parameter:

socket-handle this is returned by a call from AGS-CREATE-SERVER.

AGS-CREATE-CLIENT (op-code 3)

This operation attempts to connect to a server. It waits only a short time before giving up, so the server should be running before the client makes this call. (The length of time is dependent on the underlying socket layer.) If it is successful, the value in RETURN-CODE is a socket handle that can be used to communicate with the server using AGS-WRITE and AGS-READ. The socket handle should be moved to a data item of USAGE HANDLE. This operation takes two parameters:

port-number | a numeric value specifying the port on which the socket is created.
server-name | a PIC X(n) data item that holds the machine name of the server.

AGS-CLOSE (op-code 4)

This operation closes a socket handle. After closing a socket handle, it should no longer be referenced. This operation takes a single parameter:

socket-handle this indicates which socket to close.

AGS-WRITE (op-code 5)

This operation writes data to a socket, either from the client to the server, or from the server to the client. With this operation, data is actually written:

  • when AGS-READ is attempted on that socket,
  • when you are querying for any available sockets to read using AGS-READ or AGS-NEXT-READ, or
  • when you call AGS-FLUSH.

The value in RETURN-CODE is the number of bytes written. If this is different than the length parameter, an error has occurred.

Note: It is up to you to make sure that the server is writing when the client is reading, and vice versa. If both attempt to read at the same time, a deadlock will result.

This operation takes three parameters:

socket-handle | a valid socket handle returned from AGS-ACCEPT, AGS-CREATE-CLIENT, or AGS-NEXT-READ.
buffer | indicates a buffer to write. It can be of any format, including a group item. Be careful when sending numeric data across the network because some machines use different byte ordering than others and native numeric data can appear swapped on different machines. COMP-4 data is in the order that most network servers expect for binary data. If you are communicating with a non-COBOL client or server, you should use COMP-4 data of the correct size for the machine in question. If your client and server are both COBOL, you can use standard COBOL types.
length | the number of bytes to write. If the buffer passed is smaller than the value of this parameter, an error will result.

AGS-READ (op-code 6)

This operation reads data from a socket. It blocks other calls until all the data requested is actually read, or an error occurs. The value returned in RETURN-CODE is the number of bytes actually read. If this is different than the length parameter, an error occurred. If the socket is closed before the entire buffer is filled, C$SOCKET will return the number of bytes read to that point, which will be less than the amount requested. The next time AGS-READ is called, C$SOCKET will return -1 to signify that the socket is closed. This operation takes four parameters:

socket-handle | a valid socket handle returned from AGS-ACCEPT, AGS-CREATE-CLIENT, or AGS-NEXT-READ.
buffer | indicates a buffer to read. It can be of any format, including a group item. (The same cautions about byte order described in AGS-WRITE apply here.)
length | the number of bytes to read. If the buffer passed is smaller than the value of this parameter, an error will result. If length = 0, then the return value is the number of bytes available to be read on the socket. In other words, after calling AGS-READ with a length of 0, you can call AGS-READ again with a length equal to the previous return value and be guaranteed not to block. If length is negative, the data is moved to the buffer, but it is also left in the socket so that a future call to AGS-READ can read it again. In this case, the number of bytes transferred to the buffer is the absolute value of length.
timeval | a number, measured in milliseconds, that determines how long to execute this operation. If the specified time-out period passes, buffer will contain as much data as is available, and the return value will be the number of bytes read. This will probably be less than the number of bytes desired. This allows COBOL programs to wait for data that may not come.

AGS-FLUSH (op-code 7)

This operation flushes any data in the socket, sending any data that has been written, and checking for data to be read. The data to be read is stored in an internal buffer, awaiting a call to AGS-READ. This operation returns no value. This operation takes a single parameter:

socket-handle this indicates which socket handle to flush.

AGS-EMPTY (op-code 8)

This operation is similar to AGS-READ, except that the number of bytes is thrown away, rather than being stored. This operation takes two parameters:

socket-handle | a valid socket handle returned from AGS-ACCEPT, AGS-CREATE-CLIENT, or AGS-NEXT-READ.
length | the number of bytes to throw away. Setting this parameter means that AGS-EMPTY will not complete until that many bytes are available on the socket to throw away.

AGS-GETHOSTNAME (op-code 9)

This operation allows the COBOL program to get the name of the host machine on which the COBOL program is executing. The return value is "0" on success, and "-1" on error. This operation takes a single parameter:

hostname this parameter should be a PIC X(n) parameter. The name of the host machine is stored in this data item.

AGS-LAST-ERROR (op-code 10)

This operation allows the COBOL program to determine the last error on a socket. This information is only meaningful when an error has occurred. It is useful if one of the operations that returns a socket handle returns an error instead. The value stored in RETURN-CODE is the error number. The error numbers are listed by name in socket.def. To interpret these error codes, see third-party documentation about sockets. This operation takes a single parameter:

socket-handle a valid socket handle returned from AGS-ACCEPT, AGS-CREATE-CLIENT, or AGS-NEXT-READ, or a NULL socket handle.

AGS-NEXT-READ (op-code 11)

This operation allows you to create multi-client servers. It waits until data is ready to be read from one of the sockets your server has created. Note that this operation only returns information about sockets created as children of the server socket passed (meaning that it only waits for sockets that were ACCEPTed from that socket) and ignores all other sockets. It automatically accepts new client connections from AGS-CREATE-CLIENT, and returns the corresponding socket handle as one that can be read. The value in RETURN-CODE is a socket handle returned from AGS-ACCEPT, AGS-CREATE-CLIENT, or AGS-NEXT-READ, 0 to signify that the timeval has elapsed, or -1 to signify an error. (The socket handle returned from this operation may be from a new client which has connected and sent data. If your program has not yet recognized this as a valid socket, the value may be unfamiliar to you.) This operation takes two parameters:

server-socket-handle the socket handle returned by AGS-CREATE-SERVER.
timeval a number, measured in milliseconds, that determines how long to execute this operation. The first time you call AGS-NEXT-READ, timeval determines the length of time the operation executes. All subsequent invocations of this operation are handled in one of two ways:
  1. If there is a socket handle that has already been determined to have data available, that socket handle is returned immediately regardless of the value of timeval.
  2. If all sockets have been processed, then the setting of timeval determines how long the routine will execute, just as in the initial call. Any sockets that receive data during that time will store the data until AGS-READ or AGS-EMPTY is called with that socket as an argument. Any future calls to AGS-NEXT-READ will return those socket handles.

If timeval is set to 0, all the sockets are checked and the operation returns immediately. If no sockets have data, the routine returns 0. Otherwise the return value will be a socket that has data. If timeval is set to the default of -1, the operation waits until a socket which can be read is available (potentially forever). If all your server does is service clients, then you should always pass the value of -1 as the timeval. The only reason to pass a timeval that is not -1 is if your server wants to perform other work while it is not busy servicing clients.

AGS-REMOTE-NAME (op-code 12)

This operation returns the name of a remote machine. It takes two parameters:

socket-handle | a valid socket handle returned from AGS-ACCEPT, AGS-CREATE-CLIENT, or AGS-NEXT-READ.
remote-name | a PIC X(n) data item that is filled with the name of the remote machine.

AGS-REMOTE-ADDR (op-code 13)

This operation returns the IP address of a remote machine. It takes two parameters:

socket-handle | a valid socket handle returned from AGS-ACCEPT, AGS-CREATE-CLIENT, or AGS-NEXT-READ.
remote-addr | a PIC X(n) data item that is filled with the IP address of the remote machine.

AGS-READ-LINE (op-code 14)

This operation reads a line of data from a socket. A line is defined as a block of text terminated by either a NewLine or Carriage-Return / NewLine (NL or CRNL). The NL or CRNL is stripped from the data before it is returned, and the return value is the number of bytes read, not counting the NL or CRNL. This operation blocks other calls until all the data requested is actually read, or an error occurs. This operation takes four parameters:

socket-handle | a valid socket handle returned from AGS-ACCEPT, AGS-CREATE-CLIENT, or AGS-NEXT-READ.
buffer | indicates a buffer to read. It can be of any format, including a group item. (The same cautions about byte order described in AGS-WRITE apply here.)
length | the number of bytes to read. If the buffer passed is smaller than the value of this parameter, an error results. If length = 0, then the return value is the number of bytes available to be read on the socket. In other words, after calling AGS-READ-LINE with a length of 0, you can call AGS-READ-LINE again with a length equal to the previous return value and be guaranteed not to block. If length is negative, the data is moved to the buffer, but it is also left in the socket so that a future call to AGS-READ-LINE can read it again. In this case, the number of bytes transferred to the buffer is the absolute value of length.
timeval | a number, measured in milliseconds, that determines how long to execute this operation. If the specified time-out period passes, buffer will contain as much data as is available, and the return value will be the number of bytes read. This will probably be less than the number of bytes desired. This allows COBOL programs to wait for data that may not come.

AGS-GETHOSTADDR (op-code 15)

This operation code takes a single argument:

host-address A pic x(15) or larger item. This is the address of the local host in dotted notation (192.15.4.32) when C$SOCKET returns.

AGS-GETSOCKETPORT (op-code 16)

This operation code takes a single argument:

socket-handle This is a socket handle. The return value is the port being used by that socket, or -1 on error. This is useful when passing 0 as the port number when creating a socket, since a socket is created on some unknown port in that case. This function can then be used to determine the actual port being used.

Example

Three sample programs are provided to illustrate the use of the C$SOCKET routine.

  • sockcli.cbl is a client that connects to a server and sends it data. The server returns the data modified.
  • socksrv1.cbl is a single-client server. This means that it can accommodate a single client. When that client shuts down, the server also halts. If another client subsequently tries to connect to the server, it is ignored.
  • socksrvm.cbl is a multi-client server. Any number of clients can attach to this server. When one client disconnects, the rest continue to be serviced.

Because of limitations in the socksrvm.cbl sample program, the only way to halt the server is to kill it at the operating system level. This is not a general requirement of multi-client servers.

Parent topic: General Syntax and Library List


C$SYSLOG

This library routine can be used to open, write to, and close the system log. Using this routine, you can write to the system log or event notification system (on Windows) in the event of a serious error that administrators need to know about.

Usage

CALL "C$SYSLOG"
    USING OP-CODE, parameters

Parameters

OP-CODE Constant | Indicates which C$SYSLOG operation to perform. The operations are described below in the Description section.
parameters vary depending on the op-code chosen | Provide information and hold results for the operation specified. These parameters are discussed with their corresponding op-codes in the Description section below.

Description

C$SYSLOG sends messages to syslog on UNIX systems that have the syslog function. On other UNIX systems, and on other non-Windows operating systems, this routine sends messages to the console. On Windows systems, the routine sends messages to the event log, which can be viewed using the Event Viewer applet available on Windows.

The runtime also sends messages to the system log when it detects broken files. This function allows COBOL programmers to notify system administrators automatically when a broken file is detected, instead of relying on individual users to report such errors. The runtime sends such notifications only if the COBOL program has opened the system log using the C$SYSLOG routine as described below.

Note: Because the various implementations of system logging don't report errors, the C$SYSLOG routine does not report errors either, because it never receives any.

See your UNIX system documentation for information about the syslog facility. See your Windows documentation for information on the Event Viewer applet.

The following constants used by the C$SYSLOG library routine are defined in acucobol.def:

CSYSLOG-OPEN (op-code 0)

opens the system log. This operation takes the following two parameters and has no return value:

DOMAIN Alphanumeric item The UNC name of a Windows machine to which to send events. This parameter is used only for Windows machines. It is ignored on other operating systems.

If this parameter is set to any of the following items, the local machine executing the runtime receives the event messages:

  • the NULL keyword
  • an empty string literal (this setting generates a compiler warning)
  • a string literal that contains spaces
  • a data item with a value of spaces or low-values
APPNAME Alphanumeric item The name of the application under which to log the notifications. See the Event Viewer or syslog documentation for information about what this parameter actually does and how to filter notifications on this name.

CSYSLOG-WRITE (op-code 1)

allows you to write to the system log. This operation takes the following two parameters:

PRIORITY Numeric item This parameter may have one of the following values:
  • CSYSLOG-PRIORITY-SUCCESS (value 0)
  • CSYSLOG-PRIORITY-INFORMATION (value 1)
  • CSYSLOG-PRIORITY-WARNING (value 2)
  • CSYSLOG-PRIORITY-ERROR (value 3)

See the Event Viewer or syslog documentation that comes with your operating system for information about these values and how to filter based on them.

MESSAGE Alphanumeric item The message sent to the system log. This parameter has no maximum length; it is sent to the system log as is. The system administrator sees this message in the system log.

CSYSLOG-CLOSE (op-code 2)

closes the system log. This operation takes no parameters and returns no value. After the system log is closed and before it is opened again, all writes to the system log (including those done internally by the runtime for reporting broken files) fail with no warning or error message.

Parent topic: General Syntax and Library List


C$SYSTEM

This routine combines the functionality of "SYSTEM" and "C$RUN". It allows you to run other programs from inside a COBOL application in a variety of ways.

C$SYSTEM adds the following capabilities to the original capabilities of SYSTEM and C$RUN:

  1. Uniform programming interface for all options
  2. Asynchronous operation (C$RUN) added to UNIX hosts
  3. Windows hosts can specify minimized, maximized, or hidden windows
  4. Smart shell selection for Windows and Windows NT

Usage

CALL "C$SYSTEM"
    USING CMD-LINE, FLAGS
    GIVING EXIT-STATUS

C$SYSTEM can be used to execute a program in Thin Client environments. To execute a program on the display host in a thin client environment, add the prefix "@[DISPLAY]:" to the name of any program that resides on the client machine. For Example:

C$SYSTEM "@[DISPLAY]:C:\notepad myfile.txt"

Parameters

CMD-LINE PIC X(n) | Contains the operating system command line to execute.
FLAGS Numeric unsigned (optional) | Supplies the options for the operation. If omitted, acts as if "0" was specified.
EXIT-STATUS Any numeric data item | Returns the called program's exit status.

Flags

The FLAGS field specifies various options about how the command should be run. Determine the value of the FLAGS field by adding together the values corresponding to the following options:

CSYS-ASYNC (value 1) This option causes the command to run independently of the COBOL program. After starting the command, the COBOL program continues. When this option is specified, EXIT-STATUS returns undefined results. When this flag is not used, the COBOL program waits for the command executed to finish before the COBOL program continues. CSYS-ASYNC is functional only on Windows and UNIX systems.
Note: On UNIX machines, specifying CSYS-ASYNC with a program that tries to do input or output to the terminal is not supported.
CSYS-NO-IO (value 2) For character-based systems, the runtime normally sets the terminal to its default state prior to running the command, and resets it back to the state needed by the runtime when the command finishes. This option ensures that the called application runs correctly if the application uses the screen. However, CSYS-NO-IO also causes the runtime to "forget" the contents of the screen. This happens because the command executed may display information on the screen that ACUCOBOL-GT is not aware of. Because of this, windows created after a call to C$SYSTEM may not correctly restore the screen contents when these windows are closed. You can avoid this problem by re-initializing the screen after C$SYSTEM returns. You can do this by erasing the screen or closing a floating or pop-up window that covers the entire screen (the window must have been created by the C$SYSTEM call).

If the command to be executed will not perform any screen I/O, then you can request that C$SYSTEM retain ACUCOBOL-GT's memory of the original screen by using the CSYS-NO-IO option. This will avoid the problem described above. The option has no effect in Windows, where the command runs in its own window.

CSYS-MAXIMIZED (value 4) | This option causes the command to run in a maximized window. This is functional only when you are running under Windows.
CSYS-MINIMIZED (value 8) | This option causes the command to run in a minimized window. In addition, the COBOL program remains the active program retaining the keyboard focus and keeping the active appearance. This is functional only when you are running under Windows.
CSYS-COMPATIBILITY (value 16) | This option causes the command to run in a window that is compatible with the way the SYSTEM library routine works. Use this option if you want to modify a call to SYSTEM and change this call to C$SYSTEM. There are very few differences between the default behavior of SYSTEM and C$SYSTEM, so this option is rarely needed. The only known difference involves the Microsoft Word application. If you use SYSTEM to start Microsoft Word, it always starts in a "normal" sized window, that is, the window size suggested by Windows. If you use C$SYSTEM to start Microsoft Word (with no FLAGS specified), then Word adopts the last window size it previously used. Supplying a flag of CSYS-COMPATIBILITY causes C$SYSTEM to behave the same as SYSTEM. Of course, if you prefer the behavior of C$SYSTEM, the flag should not be used. In comparison with SYSTEM, C$SYSTEM generally conforms more closely to the way Windows itself launches programs. The CSYS-COMPATIBILITY flag is recommended only if you change a SYSTEM call to a C$SYSTEM call and you observe a difference you do not like.
CSYS-HIDDEN (value 32) | This option runs the command in a hidden window. Note that some applications, particularly those that routinely interact with the user, may get confused if you "hide" the command. This works well, however, for executing system tasks that do not have a user interface, such as executing a batch file that renames a series of files. This option is functional only when you are running under Windows.
CSYS-SHELL (value 64) When this option is specified, C$SYSTEM uses the host's command-line processor (the host's shell) to execute the command. Otherwise, the command may be executed without the command-line processor. This option affects only Windows (non-Windows versions always use the host's shell). For Windows applications that create their own windows, you should avoid using the shell the application will not receive the initial window size request specified in FLAGS. For ".COM" and ".BAT" programs, and other built-in shell commands such as COPY and DIR, you must use the shell or the command may not execute.

The effect of this option is to prefix the command with the value of the COMSPEC environment variable and "/C". Under Windows, this will usually result in a prefix like "C:\COMMAND.COM /C". Under Windows NT, the prefix will typically be "CMD.EXE /C".

CSYS-DESKTOP (value 128) This option is for applications running in the thin client environment. It indicates that the application wants to run the command on the client system rather than the application server. When the command executes, unless the CSYS-ASYNC option is also specified, the thin client appears to "hang" while the application waits for the command's termination status. This behavior can be avoided with the CSYS-ASYNC flag. The CSYS-ASYNC flag causes the command to be run asynchronously.

If CSYS-DESKTOP is specified but the calling program is not running under thin client, the flag is ignored and the command is run on the same machine as the calling application.

CSYS-INHERIT-HANDLES (value 256) This option causes the new process to inherit each inheritable handle owned by the calling process. This includes stdin, stdout, stderr, and other file handles that the calling process has open.

Note that because the called process inherits many open files, it is vulnerable to running out of file handles.

This option is needed when an Alternate Terminal Manager runtime calls C$SYSTEM to run a batch program which in turn calls another Alternate Terminal Manager runtime. Without this option, the called program will not display any output to the screen.

Comments

The C$SYSTEM routine submits CMD-LINE to the host operating system as if it were a command keyed in from the terminal. The maximum allowable length for the command line is 1024 bytes.

Note: Applications that run under Windows but that do not create their own windows should use the CSYS-SHELL flag to execute .COM, .BAT, and built-in shell commands such as COPY and DIR. See the description of CSYSSHELL below.

You should specify only one window size flag (CSYS-MAXIMIZED, CSYS-MINIMIZED, CSYS-COMPATIBILITY, or CSYS-HIDDEN). In the absence of any window size flag, the command runs in a normal window whose size is determined by the operating system. Windows programs can set their own window size. This will override the window size suggested by FLAGS. Essentially, the value of FLAGS is only a suggestion to the application. You can find possible values of FLAGS in acucobol.def.

Options that are not meaningful to the host system are ignored. Meaningful options in the same FLAGS setting are still applied.

The status of a call to C$SYSTEM is placed in EXIT-STATUS. This is usually the exit status of the executed program, or is -1 if C$SYSTEM failed. Note that Windows will return 1 from commands that are built into COMMAND.COM because COMMAND.COM does not return an exit status for built-in functions.

Parent topic: General Syntax and Library List


C$TOUPPER and C$TOLOWER

These routines translate text to upper- or lower-case.

Usage

CALL "C$TOUPPER"
    USING TEXT-DATA, VALUE TEXT-LEN

CALL "C$TOLOWER"
    USING TEXT-DATA, VALUE TEXT-LEN

Parameters

TEXT-DATA PIC X(n) | Contains the data to translate to upper- or lower-case.
TEXT-LEN USAGE UNSIGNED-INT, or a numeric literal | Contains the number of characters to translate.

Description

C$TOUPPER translates the first TEXT-LEN characters in TEXT-DATA to upper-case. C$TOLOWER translates them to lower-case. No size checking is done on TEXT-DATA, so you must ensure that TEXT-LEN has a valid value. VALUE must be included in the calling statement. If it is omitted, the program will very likely encounter memory errors. These routines only translate characters with a numeric value of 0-128. Anything above that (such as é, with a value of 130) must be mapped to its associated upper- or lower-case character using the configuration variable UPPER-LOWER-MAP.

Note: You can also translate character strings using the intrinsic functions UPPER-CASE and LOWER-CASE, the CONVERTING option of the INSPECT statement, or the UPPER or LOWER options of the ACCEPT statement.
Parent topic: General Syntax and Library List


C$UTF16-UTF8

Translates a UTF-16 encoded string to a UTF-8 encoded data item.

Usage

C$UTF16-UFT8 using utf-16-item, itemlen
                 [, destination [, destinationlen]]

Parameters

utf-16-item
The UTF-16 encoded source item to be translated. It must be either a POINTER (set to a valid value) or an alphanumeric data item.
itemlen
The number of characters of the source item that you want to translate. If this value is 0, then the size of the source item is used (not valid when source is a POINTER). If this value is -1, the source is assumed to be terminated by a low-value character, and again, the entire source item will be translated.
destination
If given, is where the translated characters will be moved. If not given, the return-code will be the number of characters needed in the destination item to hold the entire source string. This data item can be either a POINTER or an alphanumeric data item. If it is a POINTER, you must set it to a valid value.
destinationlen
The number of characters that can be held in the destination data item. If this parameter is -1, or is not specified, then the length of destination is used.

Comments

The return value is the number of characters moved to the destination data item, or the number that would be needed (when the destination item is missing or NULL).

If fewer characters are placed in the destination than there is room for, the routine will pad the destination with spaces.

Examples

Using the following data definitions:

01 my-string-1 pic x(100).
01 my-string-2 pic x(100).
01 my-pointer pointer.
01 my-len signed-int.
01 alloc-len signed-int.

In the following example, although the source (my-string-1) is 26 characters, the CALL translates only the first 10 characters into UTF-8. The amount of space required for translation is calculated, allocated, and then translated into that buffer, which is then freed upon completion of the translation.

MOVE "abcdefghijklmnopqrstuvwxyz" to my-string-1.
CALL "C$UTF16-UTF8" using my-string-1, 10.

MOVE return-code to my-len.
DIVIDE my-len by 2 GIVING alloc-len.  *> UTF-16 uses 2 bytes per character

CALL "M$ALLOC" using alloc-len my-pointer.
CALL "C$UTF16-UTF8" using my-string-1, 10, my-pointer, my-len.
CALL "M$FREE" using my-pointer.
Parent topic: General Syntax and Library List
Related reference
C$UTF8-UTF16
C$COBOL-UTF8
C$UTF8-COBOL
C$88591-UTF8
C$UTF8-88591


C$UTF8-COBOL

Translates a UTF-8 encoded string to a data item encoded using the ANSI code page specified by the COBOL_CHARACTER_SET configuration variable.

Usage

C$UTF8-COBOL using UTF-8-item, itemlen
                 [, destination [, destinationlen]]

Parameters

UTF-8-item
The UTF-8 encoded source item to be translated. It must be either a POINTER (set to a valid value) or an alphanumeric data item.
itemlen
The number of characters of the source item that you want to translate. If this value is 0, then the size of the source item is used (except when the source is a POINTER). If this value is -1, the source is assumed to be terminated by a low-value character, and again, the entire source item will be translated.
destination
If specified, is where the translated characters will be moved. If not specified, the return-code will be the number of characters needed in the destination item to hold the entire source string. This data item can be either a POINTER or an alphanumeric data item. If it is a POINTER, you must set it to a valid value.
destinationlen
The number of characters that can be held in the destination data item. If this parameter is -1, or is not specified, then the length of destination is used.

Comments

The return value is the number of characters moved to the destination data item, or the number that would be needed (when the destination item is missing or NULL).

If fewer characters are placed in the destination than there is room for, the routine will pad the destination with spaces.

Examples

Using the following data definitions:

01 my-string-1 pic x(100).
01 my-string-2 pic x(100).

In the following example, the CALL translates the 5 characters in my-string-1 (ABcde) into ANSI, and places the result in my-string-2, which is then padded with ANSI spaces. The return-code is 5 (characters).

MOVE "ABcde" to my-string-1
CALL "C$UTF8-COBOL using my-string-1, 5, my-string-2, 50
Parent topic: General Syntax and Library List
Related reference
C$UTF16-UTF8
C$UTF8-UTF16
C$COBOL-UTF8
C$88591-UTF8
C$UTF8-88591


C$UTF8-88591

Translates a UTF-8 encoded string to a data item encoded using the ISO-8859-1 code page.

Usage

C$UTF8-88591 using utf-8-item, itemlen
                 [, destination [, destinationlen]]

Parameters

utf-8-item
The UTF-8 encoded source item to be translated. It must be either a POINTER (set to a valid value) or an alphanumeric data item.
itemlen
The number of characters of the source item that you want to translate. If this value is 0, then the size of the source item is used (except when the source is a POINTER). If this value is -1, the source is assumed to be terminated by a low-value character, and again, the entire source item will be translated.
destination
If specified, is where the translated characters will be moved. If not specified, the return-code will be the number of characters needed in the destination item to hold the entire source string. This data item can be either a POINTER or an alphanumeric data item. If it is a POINTER, you must set it to a valid value.
destinationlen
The number of characters that can be held in the destination data item. If this parameter is -1, or is not specified, then the length of destination is used.

Comments

The return value is the number of characters moved to the destination data item, or the number that would be needed (when the destination item is missing or NULL).

If fewer characters are placed in the destination than there is room for, the routine will pad the destination with spaces.

Examples

Using the following data definitions:

01 my-string-1 pic x(100).

In the following example, since itemlen is 0, the CALL translates all 5 characters (ABcde) into ISO-8859-1, placing the result into my-string-1.

CALL C$UTF8-88591 using "ABcde", 0, my-string-1.
Parent topic: General Syntax and Library List
Related reference
C$UTF16-UTF8
C$UTF8-UTF16
C$COBOL-UTF8
C$UTF8-COBOL
C$88591-UTF8


C$UTF8-UTF16

Translates a UTF-8 encoded string to a UTF-16 encoded data item.

Usage

C$UTF8-UTF16 using utf-8-item, itemlen
                 [, destination [, destinationlen]]

Parameters

utf-8-item
The UTF-8 encoded source item to be translated. It must be either a POINTER (set to a valid value) or an alphanumeric data item.
itemlen
The number of characters of the source item that you want to translate. If this value is 0, then the size of the source item is used (not valid when source is a POINTER). If this value is -1, the source is assumed to be terminated by a low-value character, and again, the entire source item will be translated.
destination
If given, is where the translated characters will be moved. If not given, the return-code will be the number of characters needed in the destination item to hold the entire source string. This data item can be either a POINTER or an alphanumeric data item. If it is a POINTER, you must set it to a valid value.
destinationlen
The number of characters that can be held in the destination data item. If this parameter is -1, or is not specified, then the length of destination is used.

Comments

The return value is the number of characters moved to the destination data item, or the number that would be needed (when the destination item is missing or NULL).

If fewer characters are placed in the destination than there is room for, the routine will pad the destination with spaces.

Examples

Using the following data definitions:

01 my-string-1 pic x(100).
01 my-string-2 pic x(100).
01 my-pointer pointer.
01 my-len signed-int.
01 alloc-len signed-int.

In the following example, although the source (my-string-1) is 26 characters, the CALL translates only the first 10 characters into UTF-16. The amount of space required for translation is calculated, allocated, and then translated into that buffer, which is then freed upon completion of the translation.

MOVE "abcdefghijklmnopqrstuvwxyz" to my-string-1.
CALL "C$UTF8-UTF16" using my-string-1, 10.

MOVE return-code to my-len.
MULTIPLY my-len by 2 GIVING alloc-len.  *> UTF-16 uses 2 bytes per character

CALL "M$ALLOC" using alloc-len my-pointer.
CALL "C$UTF8-UTF16" using my-string-1, 10, my-pointer, my-len.
CALL "M$FREE" using my-pointer.
Parent topic: General Syntax and Library List
Related reference
C$UTF16-UTF8
C$COBOL-UTF8
C$UTF8-COBOL
C$88591-UTF8
C$UTF8-88591


C$XML

This routine lets you retrieve and parse precise information from an XML document. It also lets you add, modify, or delete data in an XML document.

Refer to the Guide to Interoperating with ACUCOBOL-GT, Working with Non-Vision Data for additional user instructions, examples, and help with XML terminology like element, attribute, parent, child, and sibling.

Usage

CALL "C$XML"
    USING OP-CODE, parameters...

Parameters

OP-CODE Numeric parameter | Specifies the operation to perform. These are defined in their own topics. There are constants defined for the op-codes in acucobol.def.
Parameters Vary depending on the op-code chosen. | The parameters vary depending on the operation selected. They provide information and hold results for the operations specified. These are described in the applicable op-code topic.

Comments

This utility gives you low-level control over the parsing of XML data. If you do not require such precise control or if you would prefer to use a transparent interface to map XML to COBOL, you can use AcuXML to parse the XML data instead. AcuXML is a file system interface that is designed to map XML data to COBOL based on eXtended File Descriptors (XFDs) create at compile time. See Working with XML Data for more information.

The C$XML routine is useful for parsing all XML files, including non-records-based XML files such as XFDs or configuration files that you have formatted in XML. AcuXML is not able to parse XML documents such as these, because it quits after the close of the first top-level element, considering that to be the end of the file. AcuXML is useful strictly for records-based XML files.

The following C$XML op-codes all take a parameter which is a regular expression:

  • CXML-GET-SIBLING-BY-ATTR-NAME
  • CXML-GET-SIBLING-BY-CDATA
  • CXML-GET-SIBLING-BY-ATTR-VALUE
  • CXML-GET-CHILD-BY-ATTR-VALUE
  • CXML-GET-CHILD-BY-CDATA
  • CXML-GET-CHILD-BY-NAME
  • CXML-GET-CHILD-BY-ATTR-NAME
  • CXML-GET-SIBLING-BY-NAME
  • CXML-GET-ATTRIBUTE-BY-NAME
  • CXML-GET-LAST-ERROR

If unexpected results are seen, the AREGEXP_COMPILE_NO_REGEXP flag may be required. This causes a search for the text, rather than a regular expression. See op-code 2 of C$REGEXP for a complete list of flags.

  • CXML-PARSE-FILE
    This operation parses the specified file.
  • CXML-RELEASE-PARSER
    Releases memory allocated by parsing.
  • CXML-GET-FIRST-CHILD
    Retrieves the first child element.
  • CXML-GET-NEXT-SIBLING
    Retrieves the next sibling element.
  • CXML-GET-PARENT
    Moves you to a parent element of another element.
  • CXML-GET-DATA
    Retrieves the name and value of an element.
  • CXML-GET-ATTRIBUTE-COUNT
    Retrieves the number of attributes in that element.
  • CXML-GET-ATTRIBUTE
    Retrieves the name and value of the attributes in that element.
  • CXML-GET-LAST-ERROR
    Returns the numeric value of the last error.
  • CXML-OPEN-FILE
    Opens the named file with an XML parser, positioning it at the top-level element.
  • CXML-PARSE-STRING
    Parses the specified string as XML
  • CXML-PARSE-NEXT-RECORD
    Parses the next record in the element of the specified handle.
  • CXML-GET-PREV-SIBLING
    Retrieves the previous sibling element of the handle passed.
  • CXML-NEW-PARSER
    Creates an empty XML document in memory.
  • CXML-GET-ATTRIBUTE-BY-NAME
    Retrieves the named attribute from an element.
  • CXML-GET-CHILD-BY-NAME
    Retrieves the named child element.
  • CXML-GET-CHILD-BY-CDATA
    Retrieves the child element whose data matches the regular expression given.
  • CXML-GET-CHILD-BY-ATTR-NAME
    Retrieves the child element by attribute name.
  • CXML-GET-CHILD-BY-ATTR-VALUE
    Retrieves the child element by attribute value.
  • CXML-GET-SIBLING-BY-NAME
    Retrieves the sibling element by name.
  • CXML-GET-SIBLING-BY-CDATA
    Retrieves the sibling element by character data.
  • CXML-GET-SIBLING-BY-ATTR-NAME
    Retrieves the sibling element by attribute name.
  • CXML-GET-SIBLING-BY-ATTR-VALUE
    Retrieves the sibling element by attribute value.
  • CXML-GET-COMMENT
    Retrieves the comment data.
  • CXML-SET-DATA
    Sets character data of an element.
  • CXML-MODIFY-ATTRIBUTE-VALUE
    Modifies an attribute value.
  • CXML-ADD-CHILD
    Adds a new child element.
  • CXML-ADD-SIBLING
    Adds a new sibling element.
  • CXML-ADD-ATTRIBUTE
    Adds a new attribute.
  • CXML-ADD-COMMENT
    Adds a new comment.
  • CXML-APPEND-COMMENT
    Appends a comment to the specified element handle or parser handle.
  • CXML-DELETE-ATTRIBUTE
    Deletes the specified attribute from an element.
  • CXML-DELETE-ELEMENT
    Deletes the specified element.
  • CXML-DELETE-COMMENT
    Deletes the specified comment.
  • CXML-WRITE-FILE
    Writes the data tree to the specified XML file.
  • CXML Write String
    CXML Write String
  • CXML-GET-PROC-INSTR-COUNT
    Obtains the number of processing instructions that exist.
  • CXML-GET-PROC-INSTR
    Retrieves the stylesheet and other processing instructions from the XML file.
  • CXML-SET-PROC-INSTR
    Sets the stylesheet and other processing instructions from the XML file.
  • CXML-GET-VERSION
    Retrieves the version attribute from the XML file.
  • CXML-SET-VERSION
    Sets the version attribute in the XML file.
  • CXML-GET-ENCODING
    Retrieves the encoding attribute from the XML file.
  • CXML-SET-ENCODING
    Sets the encoding attribute in the XML file.
  • CXML-GET-STANDALONE
    Retrieves the standalone attribute from the XML file.
  • CXML-SET-STANDALONE
    Sets the standalone attribute in the XML file.
  • CXML-GET-RAW-DOCTYPE-LEN
    Retrieves the raw doctype attribute length from the XML file.
  • CXML-GET-RAW-DOCTYPE
    Retrieves the raw doctype attribute from the XML file.
  • CXML-SET-RAW-DOCTYPE
    Sets the doctype attribute in the XML file.
Parent topic: General Syntax and Library List
Related reference
Working with XML Data
Related information
C$REGEXP


CXML-PARSE-FILE

Syntax:

CALL "C$XML" USING CXML-PARSE-FILE, filename

Parameters:

CXML-PARSE-FILE | Op-code 1. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
filename | pic x(n) or alphanumeric literal

On Entry:

CXML-PARSE-FILE | Value 1
filename | The name of the XML document to parse

On Exit:

RETURN-CODE Parser handle for the XML document. You should move the return code to a Working-Storage USAGE HANDLE that you have declared.

Comments:

This operation parses the specified file, returning a parser handle as the return-code. To read a file from the Internet and parse it, you can pass the filename with URL syntax. For example, you could pass the following filename:

http://myserver.mycomp.com/xmldata/bookfile.xml

Use this op-code when the file is fairly small, and you want to read and parse the whole file with a single call and store it in memory.

Example:

working-storage section.
01 parser-handle usage is handle.
COPY "acucobol.def".
procedure division.
main-logic.
*Parse an XML file
   call "C$XML" using CXML-PARSE-FILE, http://myserver.mycomp.com/xmldata/bookfile.xml
   move return-code to parser-handle.
Parent topic: C$XML


CXML-RELEASE-PARSER

Syntax:

CALL "C$XML" USING CXML-RELEASE-PARSER, handle

Parameters:

CXML-RELEASE-PARSER | Op-code 2. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle

On Entry:

CXML-RELEASE-PARSER | Value 2
handle | The parser handle returned by CXML-PARSE-FILE, CXML-OPEN-FILE, CXML-PARSE-STRING, or CXML-NEW-PARSER.

On Exit:

None

Comments:

This operation releases memory allocated by parsing. The passed handle is zeroed by this call.

Note: Failing to call with this op-code results in a memory leak.

Example:

working-storage section.
01 parser-handle usage is handle.
COPY "acucobol.def".
procedure division.
main-logic.
*Release parser
   call "C$XML" using CXML-RELEASE-PARSER, parser-handle
Parent topic: C$XML


CXML-GET-FIRST-CHILD

Syntax:

CALL "C$XML" USING CXML-GET-FIRST-CHILD, handle

Parameters:

CXML-GET-FIRST-CHILD | Op-code 3. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle

On Entry:

CXML-GET-FIRST-CHILD | Value 3
handle | A parser handle or an element handle. If a parser handle, returns the first child of the top-level element.

On Exit:

RETURN-CODE A handle of the first child element, or 0 if there are no children. (The case of no children is not considered an error, even though CXML-GET-LAST-ERROR will return 10.)

Comments:

This operation retrieves the handle of the first child element of the handle passed and places it in return-code. You should move return code to an element handle that you have declared in Working-Storage

Example:

working-storage section.
01 parser-handle usage is handle.
01 element-1-handle usage is handle.
COPY "acucobol.def".
procedure division.
main-logic.
*Get child element
   call "C$XML" using CXML-GET-FIRST-CHILD, parser-handle
   move return-code to element-1-handle.
Parent topic: C$XML


CXML-GET-NEXT-SIBLING

Syntax:

CALL "C$XML" USING CXML-GET-NEXT-SIBLING, handle

Parameters:

CXML-GET-NEXT-SIBLING | Op-code 4. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle

On Entry:

CXML-GET-NEXT-SIBLING | Value 4
handle | An element handle.

On Exit:

RETURN-CODE A handle of the next sibling element, or “0” if no more siblings. (The case of no next sibling is not considered an error, even though CXML-GET-LAST-ERROR will return “11”.)

Comments:

This operation retrieves the handle of the next sibling element of the handle passed. You should move return code to an element handle that you have declared in Working-Storage

Example:

working-storage section.
01 parser-handle usage is handle.
01 element-1-handle usage is handle.
01 element-2-handle usage is handle.
COPY "acucobol.def".
procedure division.
main-logic.
*Get child and next sibling element
   call "C$XML" using CXML-GET-FIRST-CHILD, parser-handle
   move return-code to element-1-handle.

   call "C$XML" using CXML-GET-NEXT-SIBLING, element-1-handle
   move return-code to element-2-handle.
Parent topic: C$XML


CXML-GET-PARENT

Syntax:

CALL "C$XML" USING CXML-GET-PARENT, handle

Parameters:

CXML-GET-PARENT | Op-code 5. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle

On Entry:

CXML-GET-PARENT | Value 5
handle | An element handle.

On Exit:

RETURN-CODE Contains the handle of the parent element of that element, or 0 if this is the top-level element or some other error.

Comments:

This operation enables you to go through the XML tree without keeping track of all the handles received from C$XML. It is also a way to move backwards in an XML file. This op-code does not retrieve element data. It simply moves to the element and returns the element handle. Once you have the handle to the element of interest, you can call CXML-GET-DATA to retrieve the data associated with the element.

Example:

working-storage section.
01 parser-handle usage is handle.
01 element-handle usage is handle.
COPY "acucobol.def".
procedure division.
main-logic.
*Get Parent element
   call "C$XML" using CXML-GET-PARENT, element-handle
   move return-code to parent-handle
Parent topic: C$XML


CXML-GET-DATA

Syntax:

CALL "C$XML" USING CXML-GET-DATA, handle item-name item-value item-value-length

Parameters:

CXML-GET-DATA | Op-code 6. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
item-name | pic x(n)
item-value | pic x(n)
item-value-length | numeric value

On Entry:

CXML-GET-DATA | Value 6
handle | Is an element handle or parser handle. If handle is a parser handle, it is first set to the handle of the top-level element of the parsed file.

On Exit:

item-name | Is returned as the name of the element.
item-value | Is returned as the character data of that element (the data outside of the XML tags).

Comments:

To retrieve data from an element, you use the CXML-GET-DATA op-code. In this operation, you must specify the handle for the element of interest, down to the field level. You can obtain the handle by looking at the return code for the other operations, such as CXML-GET-SIBLING-BY-NAME.

Example:

*Get the handle for the Weather element
   call "C$XML" using CXML-GET-SIBLING-BY-NAME
                   ele-1-handle
                   "weather"
                   0.
   move return-code to ele-2-handle.
*Get the weather data using that handle
   call "C$XML" using CXML-GET-DATA
                   ele-2 handle
                   throw-away-info
                   weather-val.

Once the XML data is returned, you can then pass it to other parts of your COBOL program for processing or display.

Parent topic: C$XML


CXML-GET-ATTRIBUTE-COUNT

Syntax:

CALL "C$XML" USING CXML-GET-ATTRIBUTE-COUNT, handle

Parameters:

CXML-GET-ATTRIBUTE-COUNT | Op-code 7. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle

On Entry:

CXML-GET-ATTRIBUTE-COUNT | Value 7
handle | An element handle or parser handle. If it is a parser handle, it is first set to the handle of the top-level element of the parsed file.

On Exit:

RETURN-CODE Contains the number of attributes for the specified element.
Parent topic: C$XML


CXML-GET-ATTRIBUTE

Syntax:

CALL "C$XML" USING CXML-GET-ATTRIBUTE, handle attr-num attr-name attr-value

Parameters:

CXML-GET-ATTRIBUTE | Op-code 8. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
attr-num | numeric value
attr-name | pic x(n)
attr-value | numeric value
attr-value-len (optional) | numeric value

On Entry:

CXML-GET-ATTRIBUTE | Value 8
handle | Is an element handle or parser handle. If handle is a parser handle, it is first set to the handle of the top-level element of the parsed file.

On Exit:

attr-name | the name of the attribute
attr-value | The attribute's value

Comments:

If the return-code is “0”, it can mean that there are no elements, or that the passed handle is not a valid handle. Query on the last error with op-code CXML-GET-LAST-ERROR to determine which is the case.

Before you use CXML-GET-ATTRIBUTE, we recommend that you use CXML-GET-ATTRIBUTE-COUNT. This op-code tells you how many attributes are in the element of interest. Then when you use CXML-GET-ATTRIBUTE, you know which attribute you are getting (the first attribute is number 0, the second number 1, etc.). Alternatively, if you know the name of the attribute you want and not the number of the attribute, you can use CXML-GET-ATTRIBUTE-BY-NAME. If you have an unknown number of attributes like this:

Limousine
xmlns:tsd="http://namespaces.softwareag.com/tamino/TaminoSche
maDefinition"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

and you are searching for a particular attribute, say "xmlns:xsi", you can search for the value with CXML-GET-ATTRIBUTE-BY-NAME, or you can get the count and read the attributes one by one searching for the one you want.

Parent topic: C$XML


CXML-GET-LAST-ERROR

Syntax:

CALL "C$XML" USING CXML-GET-LAST-ERROR, text-val

Parameters:

CXML-GET-LAST-ERROR | Op-code 9. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
text-val | pic x(n)

On Entry:

CXML-GET-LAST-ERROR Value 9

On Exit:

Op-code 9. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.

pic x(n)

Value 9

The text value of the error code.

Any C$XML call that fails will generate an error code, both a numeric value and a string value that describes the error. If return-code from any other function is 0 or -1, call this operation to get the error.

These errors are listed as a level 78 data item in acucobol.def. The possible errors are:

Numeric Value | Text Value | Description
1 | CXML-NO-MEMORY | Unable to create parser due to low memory
2 | CXML-EXPAT-ERROR | Unable to create parser - expat error
3 | CXML-FILE-OPEN-ERROR | Unable to open named file
4 | CXML-PARSE-ERROR | Invalid XML file or other parsing error
5 | CXML-INVALID-PARSER-HANDLE | The passed handle is not a valid parser handle
6 | CXML-INVALID-ELEMENT-HANDLE | The passed handle is not a valid element handle
7 | CXML-INVALID-ATTRIBUTE-NUMBER | Invalid attribute number
8 | CXML-URL-ERROR | The URL given could not be accessed
9 | CXML-NOT-AVAILABLE | The XML parser is not available on this machine
10 | CXML-NO-CHILDREN | The specified element has no children
11 | CXML-NO-SIBLINGS | The specified element has no siblings
12 | CXML-NO-PARENT | The specified element is a top-level element
13 | CXML-NO-VALUE | The specified element has no value
14 | CXML-NO-ATTRIBUTES | The specified element has no attributes
15 | CXML-REGEXP-ERROR | The regular expression given caused an error
16 | CXML-TOP-LEVEL | The specified parser already has a top-level element
17 | CXML-INVALID-PROC-INSTR-NUMBER | The idx given for CXML-GET-PROC-INSTR is outside the range of available processing instructions (for example, is greater than the value returned by CXML-GET-PROC-INSTR-COUNT).
18 | CXML-NO-PROCESSING-INSTRUCTIONS | There are no processing instructions for CXML-GET-PROC-INSTR-COUNT or CXML-GET-PROC-INSTR, or target was not used or is blank in CXML-SET-PROC-INSTR (for example, you are removing a processing instruction).
Parent topic: C$XML


CXML-OPEN-FILE

Syntax:

CALL "C$XML" USING CXML-OPEN-FILE, filename

Parameters:

CXML-OPEN-FILE | Op-code 10. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
filename | pic x(n) or alphanumeric literal

On Entry:

CXML-OPEN-FILE | Value 10
filename | The name of the file to open with the parser.

On Exit:

RETURN-CODE A parser handle

Comments:

To simply open a file, but not parse it, use the CXML-OPEN-FILE op-code. With the file open, you can then parse individual records using the CXML-PARSE-NEXT-RECORD op-code. To open and read an entire XML file, use the CXML-PARSE-FILE op-code.

C$XML can parse local or remote files — even files located on the Internet. You simply specify the server, IP address, or URL in the pathname. You cannot write to URLs, however.

Example:

CALL "C$XML" using CXML-OPEN-FILE "http://www.nws.noaa.gov/data/current_obs/KMYF.xml"
move return-code to parser-handle
CALL "C$XML" using CXML-PARSE-NEXT-RECORD parser-handle
move return-code to record-handle
Parent topic: C$XML


CXML-PARSE-STRING

Syntax:

CALL "C$XML" USING CXML-PARSE-STRING, string

Parameters:

CXML-PARSE-STRING | Op-code 11. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
string | pic x(n) or alphanumeric literal

On Entry:

CXML-PARSE-STRING | Value 11
string | The string or string reference to be parsed as XML

On Exit:

RETURN-CODE A parser handle

Comments:

This operation parses the specified string as XML, returning a parser handle. You can parse strings passed by reference. Note that strings passed by reference MUST be terminated with low-values so that the run-time can determine the length of the string passed. Not terminating with low-values will result in undefined behavior.

If you get XML text from another source and need to parse it, you can parse the string directly using the CXML-PARSE-STRING op-code. You do not have to write the data to a file, then parse the file. You simply specify the string directly in the call. See the example below.

Example:

call "C$XML" using CXML-PARSE-STRING,
"<?xml version=""1.0""?><group1><subgroup1><item1>data</item1></subgroup1></group1>".
move return-code to parse-handle.
Parent topic: C$XML


CXML-PARSE-NEXT-RECORD

Syntax:

CALL "C$XML" USING CXML-PARSE-NEXT-RECORD, string

Parameters:

CXML-PARSE-NEXT-RECORD | Op-code 12. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
string | pic x(n) or alphanumeric literal

On Entry:

CXML-PARSE-NEXT-RECORD | Value 12
handle | A parser handle returned by CXML-OPEN-FILE.

On Exit:

RETURN-CODE A handle to the record

Comments:

This option (in conjunction with CXML-OPEN-FILE) lets you parse individual records of a file, as opposed to parsing the entire file all at once. This operation parses the next record in the element of the specified handle. No data is returned, but now more data is available for retrieval by other op-codes. Return-code is 0 on error (including end-of-file) or non-zero if everything worked.

This option is more efficient than parsing entire files, but you must remember to parse the record before you try to retrieve its elements.

Example:

CALL "C$XML" using CXML-OPEN-FILE "http://www.nws.noaa.gov/data/current_obs/KMYF.xml"
move return-code to parser-handle
CALL "C$XML" using CXML-PARSE-NEXT-RECORD parser-handle
move return-code to record-handle
Parent topic: C$XML


CXML-GET-PREV-SIBLING

Syntax:

CALL "C$XML" USING CXML-GET-PREV-SIBLING, handle

Parameters:

CXML-GET-PREV-SIBLING | Op-code 13. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle

On Entry:

CXML-GET-PREV-SIBLING | Value 13
handle | An element handle

On Exit:

RETURN-CODE

A handle of the previous sibling element, or 0 if no previous siblings. (The case of no previous sibling is not considered an error, even though CXML-GET-LAST-ERROR will return 11.

Comments:

Once a file has been opened and parsed, you must move to an element of interest before you can retrieve its data. This op-code provides a method of moving backwards in an XML file.

Parent topic: C$XML


CXML-NEW-PARSER

Syntax:

CALL "C$XML" USING CXML-NEW-PARSER, handle

Parameters:

CXML-NEW-PARSER Op-code 14. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.

On Entry:

CXML-NEW-PARSER Value 14

On Exit:

RETURN-CODE

A parser handle for the XML document. You must pass this to CXML-WRITE-FILE and CXML-RELEASE-PARSER to free the file from memory. See the example below.

Example:

01 parser-handle usage is handle.
COPY "acucobol.def".
procedure division.
main-logic.
*Create a new XML file
   call "C$XML" using CXML-NEW-PARSER
   move return-code to parser-handle.

*write the file
   call "C$XML" using CXML-WRITE-FILE,
                  parser-handle
                  "custRec.xml".

*release the file from memory
   call "C$XML" using CXML-RELEASE-PARSER,
                  parser-handle.
Parent topic: C$XML


CXML-GET-ATTRIBUTE-BY-NAME

Syntax:

CALL "C$XML" USING CXML-GET-ATTRIBUTE-BY-NAME, handle, attr-regex-name,
                                                       attr-regex-flags, attr-idx,
                                                       attr-name, attr-value, attr-len

Parameters:

CXML-GET-ATTRIBUTE-BY-NAME | Op-code 15. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
attr-regex-name | A regular expression
attr-regex-flags (Optional) | numeric value
attr-idx | Numeric value
attr-name (Optional) | pic x(n)
attr-value (Optional) | Numeric value
attr-len (Optional) | Numeric value

On Entry:

CXML-GET-ATTRIBUTE-BY-NAME | Value 15
handle | An element handle
attr-regex-flags (Optional) | A collection of flags to apply to the regular expression. The valid flags are listed in acucobol.def and described under C$REGEXP op-code 2. They can be added together to get more than one flag.
attr-idx | One less than the starting index of attributes to search (use “0” to start at the first attribute). Is also the index of the attribute actually returned if successful. This returned attribute number can be used in the next call to GET-ATTRIBUTE-BY-NAME to continue searching where you left off.

On Exit:

RETURN CODE | The named attribute
attr-name (Optional) | (Optional) The name of the actual attribute returned.
attr-len (Optional) | (Optional) The length of the attribute value.

Comments:

Attributes have special characteristics:

  • Attributes don't have a handle; they are attached to the element handle for which they are an attribute.
  • There can be more than one attribute per element, thus more than one attribute per element handle.
  • You don't need to call CXML-GET-DATA to fetch the attribute data. The op-code retrieves the data.
Parent topic: C$XML


CXML-GET-CHILD-BY-NAME

Syntax:

CALL "C$XML" USING CXML-GET-CHILD-BY-NAME, handle, regex, flags

Parameters:

CXML-GET-CHILD-BY-NAME | Op-code 16. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
regex | A regular expression
flags (Optional) | Numeric value

On Entry:

CXML-GET-CHILD-BY-NAME | Value 16
handle | An element handle
flags (Optional) | A collection of flags to apply to the regular expression. The valid flags are listed in acucobol.def and described under C$REGEXP op-code 2. They can be added together to get more than one flag.

On Exit:

RETURN-CODE

The handle of the returned child, or 0 if no such child exists.

Comments:

This option allows you to navigate to a specific child rather than simply the next or previous one. Note that this op-code does not retrieve element data, but moves to the element and returns the element handle. Once you have the handle to the element of interest, you can call CXML-GET-DATA to retrieve the data associated with the element.

Parent topic: C$XML


CXML-GET-CHILD-BY-CDATA

Syntax:

CALL "C$XML" USING CXML-GET-CHILD-BY-CDATA, handle, regex, flags

Parameters:

CXML-GET-CHILD-BY-CDATA | Op-code 17. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
regex | A regular expression
flags (Optional) | Numeric value

On Entry:

CXML-GET-CHILD-BY-CDATA | Value 17
handle | An element handle
flags (Optional) | A collection of flags to apply to the regular expression. The valid flags are listed in acucobol.def and described under C$REGEXP op-code 2.They can be added together to get more than one flag.

On Exit:

RETURN-CODE

The handle of the returned child, or “0” if no such child exists.

Comments:

This option allows you to navigate to a specific child by specifying its character data. Note that this op-code does not retrieve element data, but moves to the element and returns the element handle. Once you have the handle to the element of interest, you can call CXML-GET-DATA to retrieve the data associated with the element.

Parent topic: C$XML


CXML-GET-CHILD-BY-ATTR-NAME

Syntax:

CALL "C$XML" USING CXML-GET-CHILD-BY-ATTR-NAME, handle, regex, flags

Parameters:

CXML-GET-CHILD-BY-ATTR-NAME | Op-code 18. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
regex | A regular expression
flags (Optional) | Numeric value

On Entry:

CXML-GET-CHILD-BY-ATTR-NAME | Value 18
handle | An element handle
flags (Optional) | A collection of flags to apply to the regular expression. The valid flags are listed in acucobol.def and described under C$REGEXP op-code 2. They can be added together to get more than one flag.

On Exit:

RETURN-CODE

The handle of the returned child, or 0 if no such child exists.

Comments:

This operation retrieves an attribute name that matches the regular expression given. Note that this op-code does not retrieve element data, but moves to the element and returns the element handle. Once you have the handle to the element of interest, you can call CXML-GET-DATA to retrieve the data associated with the element.

Parent topic: C$XML


CXML-GET-CHILD-BY-ATTR-VALUE

Syntax:

CALL "C$XML" USING CXML-GET-CHILD-BY-ATTR-VALUE, handle, regex, flags

Parameters:

CXML-GET-CHILD-BY-ATTR-VALUE | Op-code 19. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
regex | A regular expression
flags (Optional) | Numeric value

On Entry:

CXML-GET-CHILD-BY-ATTR-VALUE | Value 19
handle | An element handle
flags (Optional) | A collection of flags to apply to the regular expression. The valid flags are listed in acucobol.def and described under C$REGEXP op-code 2. They can be added together to get more than one flag.

On Exit:

RETURN-CODE

The handle of the returned child, or “0” if no such child exists.

Comments:

This operation retrieves the child element that has an attribute value that matches the regular expression given. Once you have the handle to the element of interest, you can call CXML-GET-DATA to retrieve the data associated with the element.

Parent topic: C$XML


CXML-GET-SIBLING-BY-NAME

Syntax:

CALL "C$XML" USING CXML-GET-SIBLING-BY-NAME, handle, regex, flags

Parameters:

CXML-GET-SIBLING-BY-NAME | Op-code 20. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
regex | A regular expression
flags (Optional) | Numeric value

On Entry:

CXML-GET-SIBLING-BY-NAME | Value 20
handle | An element handle.
flags (Optional) | A collection of flags to apply to the regular expression. The valid flags are listed in acucobol.def and described under C$REGEXP op-code 2. They can be added together to get more than one flag.

On Exit:

RETURN-CODE

The handle of the returned child, or “0” if no such child exists.

Comments:

This operation retrieves the named sibling element. Once you have the handle to the element of interest, you can call CXML-GET-DATA to retrieve the data associated with the element.

Example:

call "C$XML" using CXML-GET-SIBLING-BY-NAME
                      ele-1-handle
                      "weather"
                      0
   move return-code to ele-2-handle
   call "C$XML" using CXML-GET-DATA
                      ele-2-handle
                      throw-away
                      weather-val.
Parent topic: C$XML


CXML-GET-SIBLING-BY-CDATA

Syntax:

CALL "C$XML" USING CXML-GET-SIBLING-BY-CDATA, handle, regex, flags

Parameters:

CXML-GET-SIBLING-BY-CDATA | Op-code 21. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
regex | A regular expression
flags (Optional) | Numeric value

On Entry:

CXML-GET-SIBLING-BY-CDATA | Value 21
handle | An element handle.
flags (Optional) | A collection of flags to apply to the regular expression. The valid flags are listed in acucobol.def and described under C$REGEXP op-code 2. They can be added together to get more than one flag.

On Exit:

RETURN-CODE

The handle of the returned child, or “0” if no such child exists.

Comments:

This operation returns the sibling element whose data matches the regular expression given. You can then call CXML-GET-DATA to retrieve the data associated with the element.

Parent topic: C$XML


CXML-GET-SIBLING-BY-ATTR-NAME

Syntax:

CALL "C$XML" USING CXML-GET-SIBLING-BY-ATTR-NAME, handle, regex, flags

Parameters:

CXML-GET-SIBLING-BY-ATTR-NAME | Op-code 22. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
regex | A regular expression
flags(optional) | Numeric value

On Entry:

CXML-GET-SIBLING-BY-ATTR-NAME | Value 22
handle | An element handle.
flags (Optional) | A collection of flags to apply to the regular expression. The valid flags are listed in acucobol.def and described under C$REGEXP op-code 2. They can be added together to get more than one flag.

On Exit:

RETURN-CODE

The handle of the returned child, or 0 if no such child exists.

Comments:

This operation returns the sibling element that has an attribute name that matches the regular expression given. You can then call CXML-GET-DATA to retrieve the data associated with the element.

Parent topic: C$XML


CXML-GET-SIBLING-BY-ATTR-VALUE

Syntax:

CALL "C$XML" USING CXML-GET-SIBLING-BY-ATTR-VALUE, handle, regex, flags

Parameters:

CXML-GET-SIBLING-BY-ATTR-VALUE | Op-code 23. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
regex | A regular expression
flags (Optional) | Numeric value

On Entry:

CXML-GET-SIBLING-BY-ATTR-VALUE | Value 23
handle | An element handle
flags (Optional) | A collection of flags to apply to the regular expression. The valid flags are listed in acucobol.def and described under C$REGEXP op-code 2. They can be added together to get more than one flag.

On Exit:

RETURN-CODE

The handle of the returned child, or 0 if no such child exists.

Comments:

This operation returns the sibling element that has an attribute value that matches the regular expression given. You can then call CXML-GET-DATA to retrieve the data associated with the element.

Parent topic: C$XML


CXML-GET-COMMENT

Syntax:

CALL "C$XML" USING CXML-GET-COMMENT, handle, data, len

Parameters:

CXML-GET-COMMENT | Op-code 24. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
data | pic x(n)
len (Optional) | pic x(n)

On Entry:

CXML-GET-COMMENT | Value 24
handle | Is an element handle or parser handle.

On Exit:

data | Is returned as the comment for the handle.
len | (If provided) is the length of the comment.

Comments:

When comments are returned to the COBOL program, they are separated by a single byte of low-values as they are in the XML file. For example:

<!-- this is a multi-line comment for a single XML file.-->

is returned to the COBOL program as a single string. But this comment:

<!-- this is two separate comments --> <!-- this is the second line of the separate comment -->

is returned to the COBOL program with a single byte of LOW-VALUES separating the separate lines and comment. The final line is terminated by two bytes of LOW-VALUES, so you know how many lines of comments are in the XML file.

If you pass the third optional len parameter to C$XML when getting comments, the length in bytes is returned in that parameter.

Parent topic: C$XML


CXML-SET-DATA

Syntax:

CALL "C$XML" USING CXML-SET-DATA, handle, data, len

Parameters:

CXML-SET-DATA | Op-code 25. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
data | literal or pic x(n)
len (Optional) | Numeric literal or pic x(n)

On Entry:

CXML-SET-DATA | Value 25
handle | An element handle to set.
len | A numeric item that tells C$XML how many characters of the data item to use. If omitted, it defaults to the size of the variable.

On Exit:

None
Parent topic: C$XML


CXML-MODIFY-ATTRIBUTE-VALUE

Syntax:

CALL "C$XML" USING CXML-MODIFY-ATTRIBUTE-VALUE, handle, attr-num, new-attr-value,
                                                                                new-attr-len

Parameters:

CXML-MODIFY-ATTRIBUTE-VALUE | Op-code 26. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
attr-num | Numeric literal or pic x(n)
new-attr-value | literal or pic x(n)
new-attr-len (Optional) | Numeric literal or pic x(n)

On Entry:

CXML-MODIFY-ATTRIBUTE-VALUE | Value 26
handle | An element handle to modify.
new-attr-value | The new value (of length new-attr-len) of that attribute.
new-attr-len | (Optional) The length of the new attribute value. If new-attr-len is omitted, it defaults to the length of the data element given for new-attr-value.

On Exit:

None
Parent topic: C$XML


CXML-ADD-CHILD

Syntax:

CALL "C$XML" USING CXML-ADD-CHILD, handle, elem-name, elem-data, data-len

Parameters:

CXML-ADD-CHILD | Op-code 27. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
elem-name | Literal or pic x(n)
elem-data Optional | Literal or pic x(n)
data-len (Optional) | Numeric literal or pic x(n)

On Entry:

CXML-ADD-CHILD | Value 27
handle | An element handle.
elem-data | (Optional) The value of the new child element. By default, this is blank.
data-len | (Optional) The length of the new child element. If omitted, it defaults to the size of the data item.

On Exit:

RETURN-CODE A handle to the new child element.

Comments:

This operation adds a new child element to the list of children already in the specified element. The new element will be the last in the list.

Example:

working-storage section.
01 parser-handle usage is handle.
01 element-handle usage is handle.
COPY "acucobol.def".
procedure division.
main-logic.
*Create a new XML file
   call "C$XML" using CXML-NEW-PARSER
   move return-code to parser-handle.

*Add a top element (using the name of the file)
   call "C$XML" using CXML-ADD-CHILD
                  parser-handle
                  "custRec"
   move return-code to element-handle.

*Add the first field of the record, which will be a child of
*the last element.
   call "C$XML" using CXML-ADD-CHILD
                  element-handle
                  "cus-key"
                  "555-55-5555"
   move return-code to element-handle.
Parent topic: C$XML


CXML-ADD-SIBLING

Syntax:

CALL "C$XML" USING CXML-ADD-SIBLING, handle, elem-name, elem-data, data-len

Parameters:

CXML-ADD-SIBLING | Op-code 28. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
elem-name | Literal or pic x(n)
elem-data Optional | Literal or pic x(n)
data-len (Optional) | Numeric literal or pic x(n)

On Entry:

CXML-ADD-SIBLING | Value 28
handle | An element handle.
elem-data | (Optional) The value of the new sibling element. By default, this is blank.
data-len | (Optional) The length of the new sibling element. If omitted, it defaults to the size of the data item.

On Exit:

RETURN-CODE A handle to the new sibling element.

Comments:

This operation adds a new sibling element to the list of children already in the specified element. The new element will be the last in the list.

Example:

*Add the first field of the record, which will be a child of
*the last element.
   call "C$XML" using CXML-ADD-CHILD
                  element-handle
                  "cus-key"
                  "555-55-5555"
   move return-code to element-handle.

*Add the rest of the record
   call "C$XML" using CXML-ADD-SIBLING
                  element-handle
                  "cus-name"
                  "Micro Focus"
   move return-code to element-handle.

   call "C$XML" using CXML-ADD-SIBLING
                  element-handle
                  "cus-addr"
                  "The Lawn, 22-30 Old Bath Road"
   move return-code to element-handle.
Parent topic: C$XML


CXML-ADD-ATTRIBUTE

Syntax:

CALL "C$XML" USING CXML-ADD-ATTRIBUTE, handle, attr-name, attr-value, attr-value-len

Parameters:

CXML-ADD-ATTRIBUTE | Op-code 29. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
attr-name | Literal or pic x(n)
attr-data Optional | Literal or pic x(n)
attr-len (Optional) | Numeric literal or pic x(n)

On Entry:

CXML-ADD-ATTRIBUTE | Value 29
handle | An element handle.
attr-value | The new attribute value, of length attr-value-len (if given) or the length of the data element given as the attr-name.
attr-value-len | (Optional) The length of the new attribute value.

On Exit:

RETURN-CODE The index of the new attribute, or “0” on error.

Example:

working-storage section.
01 parser-handle usage is handle.
01 element-handle usage is handle.
COPY "acucobol.def".
procedure division.
main-logic.
*Create a new XML file
   call "C$XML" using CXML-NEW-PARSER
   move return-code to parser-handle.

*Add a top element (using the name of the file)
   call "C$XML" using CXML-ADD-CHILD
                  parser-handle
                  "custRec"
   move return-code to element-handle.

*Add some namespace information
   call "C$XML" using CXML-ADD-ATTRIBUTE
                  element-handle
                  "xmlns:xsi"
                  "http://www.w3.org/2001/XMLSchema-instance".
Parent topic: C$XML


CXML-ADD-COMMENT

Syntax:

CALL "C$XML" USING CXML-ADD-COMMENT, handle, data, len

Parameters:

CXML-ADD-COMMENT | Op-code 30. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
data | Literal or pic x(n)
len Optional | Numeric Literal or pic x(n)

On Entry:

CXML-ADD-COMMENT | Value 30
handle | An element handle or a parser handle.
len | (Optional) The length of the new comment.

On Exit:

RETURN-CODE 0 if an error has occurred. The return code is positive if everything went correctly.
Parent topic: C$XML


CXML-APPEND-COMMENT

Syntax:

CALL "C$XML" USING CXML-APPEND-COMMENT, handle, data, len

Parameters:

CXML-APPEND-COMMENT | Op-code 31. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
data | Literal or pic x(n)
len Optional | Numeric Literal or pic x(n)

On Entry:

CXML-APPEND-COMMENT | Value 31
handle | An element handle or a parser handle.
len | (Optional) The length of the comment.

On Exit:

RETURN-CODE 0 if an error has occurred. The return code is positive if everything went correctly.

Comments:

Note that comments are associated with the element that follows them, as in:

<!-- comment assoc with elem-1-->
<elem-1>data for elem1 </elem-1>
Parent topic: C$XML


CXML-DELETE-ATTRIBUTE

Syntax:

CALL "C$XML" USING CXML-DELETE-ATTRIBUTE, handle, atr-num

Parameters:

CXML-DELETE-ATTRIBUTE | Op-code 32. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
atr-num | Numeric Literal or pic x(n)

On Entry:

CXML-DELETE-ATTRIBUTE | Value 32
handle | An element handle.

On Exit:

None
Parent topic: C$XML


CXML-DELETE-ELEMENT

Syntax:

CALL "C$XML" USING CXML-DELETE-ELEMENT, handle,

Parameters:

CXML-DELETE-ELEMENT | Op-code 33. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle

On Entry:

CXML-DELETE-ELEMENT | Value 33
handle | An element handle.

On Exit:

RETURN-CODE 0 if an error has occurred. The return code is positive if everything went correctly.

Comments:

This operation deletes the specified element. If this element has any children, all children are also deleted.

Parent topic: C$XML


CXML-DELETE-COMMENT

Syntax:

CALL "C$XML" USING CXML-DELETE-COMMENT, handle,

Parameters:

CXML-DELETE-COMMENT | Op-code 34. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle

On Entry:

CXML-DELETE-COMMENT | Value 34
handle | An element handle or a parser handle.

On Exit:

None There is no return code (errors are silent).
Parent topic: C$XML


CXML-WRITE-FILE

Syntax:

CALL "C$XML" USING CXML-WRITE-FILE, handle, filename

Parameters:

CXML-WRITE-FILE | Op-code 35. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
filename | Literal or pic x(n)

On Entry:

CXML-WRITE-FILE | Value 35
handle | A parser handle.

On Exit:

RETURN-CODE 0 if an error has occurred. The return code is positive if everything went correctly.

Comments:

If you modify the XML file in any way, you must write to the file for your changes to take effect. Use the CXML-WRITE-FILE op-code for this purpose. You can write to the same file that you opened, or you can write to a new file. The filename that you specify can be anything you want. You cannot, however, write to a URL.

When you are finished writing to the file, you are responsible for releasing the parser from memory. This operation is not performed automatically. To release the parser, use the CXML-RELEASE-PARSER op-code.

Example:

call "C$XML" using CXML-WRITE-FILE,
                  parser-handle
                  "custRec.xml".
   call "C$XML" using CXML-RELEASE-PARSER,
                  parser-handle.
   stop run.
Parent topic: C$XML


CXML Write String

Syntax:

CALL "C$XML" USING CXML-WRITE-STRING handle, data-area

Parameters:

CXML-WRITE-STRING | Op-code 48. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
data-area | is either an alphanumeric data item, or a USAGE POINTER data item. If the latter, the allocated memory must have been allocated with M$ALLOC, and may not point to any other type of memory area.

On Exit:

RETURN-CODE 0 The return code is 0 if the data item was large enough to hold the xml stream, is positive if not, and that positive value is the amount of space needed to hold the stream, or is -1 to indicate an error.
Parent topic: C$XML


CXML-GET-PROC-INSTR-COUNT

Syntax:

CALL "C$XML" USING CXML-GET-PROC-INSTR-COUNT, handle

Parameters:

CXML-GET-PROC-INSTR-COUNT | Op-code 36. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle

On Entry:

CXML-GET-PROC-INSTR-COUNT | Value 36
handle | A parser handle.

On Exit:

RETURN-CODE The return-code is 0 on error (including that there are no processing instructions), or the number of processing instructions on success.
Parent topic: C$XML


CXML-GET-PROC-INSTR

Syntax:

CALL "C$XML" USING CXML-GET-PROC-INSTR, handle, idx, target, data

Parameters:

CXML-GET-PROC-INSTR | Op-code 37. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
idx | pic 9(n) or numeric literal
target | pic x(n)
data | pic x(n)

On Entry:

CXML-GET-PROC-INSTR | Value 37
handle | A parser handle.

On Exit:

target | Data item that is where the processing instruction target is returned. This data is space-filled from what is read from the file.
data | Data item that is where the processing instruction data is returned. This data is space-filled from what is read from the file.

Comments:

Processing instructions are composed of a target and data, and there can be multiple instructions in a given XML file. The target is the first word of the instruction line, and the data is the rest of the line. For example, given the following XML snippet:

<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<?xml-stylesheet type="text/css" href="svg_default.css"?>
<!-- testit.xml - generated by Micro Focus-->
<svg

there is a single processing instruction (the stylesheet line). The target is the first word (xml-stylesheet), and the data is the rest of the information, not including the question marks (?): type="text/css" href="svg_default.css".

Parent topic: C$XML


CXML-SET-PROC-INSTR

Syntax:

CALL "C$XML" USING CXML-SET-PROC-INSTR, handle, idx, target, data

Parameters:

CXML-SET-PROC-INSTR | Op-code 38. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
idx | pic 9(n) or numeric literal
target | pic x(n)
data | pic x(n)

On Entry:

CXML-SET-PROC-INSTR | Value 38
handle | A parser handle.

On Exit:

target | Data item that is the processing instruction target. This variable will have trailing spaces removed before being written to the XML file.
data | Data item that is the processing instruction data. This variable will have trailing spaces removed before being written to the XML file. If target is all spaces, or if target and data are omitted, the processing instruction is deleted. In this case, any later processing instructions are moved. (If instruction 3 is deleted, instruction 4 becomes instruction 3, and instruction 5 becomes instruction 4, and so on.)
Parent topic: C$XML


CXML-GET-VERSION

Syntax:

CALL "C$XML" USING CXML-GET-VERSION, handle, dest

Parameters:

CXML-GET-VERSION | Op-code 39. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
dest | A pic x(n) for n >= 3.

On Entry:

CXML-GET-VERSION | Value 39
handle | A parser handle.

On Exit:

dest | The destination for the version value.
RETURN-CODE | The return code is 0 if an error has occurred. The return code is positive if everything went correctly.
Parent topic: C$XML


CXML-SET-VERSION

Syntax:

CALL "C$XML" USING CXML-SET-VERSION, handle, new-version

Parameters:

CXML-SET-VERSION | Op-code 40. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
new-version | A pic x(n) or numeric literal "1.0"

On Entry:

CXML-SET-VERSION | Value 40
handle | A parser handle.

On Exit:

RETURN-CODE The return code is 0 if an error has occurred. The return code is positive if everything went correctly.
Parent topic: C$XML


CXML-GET-ENCODING

Syntax:

CALL "C$XML" USING CXML-GET-ENCODING, handle, dest

Parameters:

CXML-GET-ENCODING | Op-code 41. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
dest | pic x(n)

On Entry:

CXML-GET-ENCODING | Value 41
handle | A parser handle.

On Exit:

dest | The destination for the encoding value.
RETURN-CODE | The return code is 0 if an error has occurred. The return code is positive if everything went correctly.
Parent topic: C$XML


CXML-SET-ENCODING

Syntax:

CALL "C$XML" USING CXML-SET-ENCODING, handle, new-encoding

Parameters:

CXML-SET-ENCODING | Op-code 42. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
new-encoding | pic x(n)

On Entry:

CXML-SET-ENCODING | Value 42
handle | A parser handle.
new-encoding | The new encoding value.

On Exit:

RETURN-CODE The return code is 0 if an error has occurred. The return code is positive if everything went correctly.

Encoding Support

While the ISO-8859-1 encoding is supported by C$XML, it always gives strings in UTF-8, regardless of the encoding of the XML file.

Starting with version 8.1.2, the data returned to the COBOL program will be in one of three (instead of one of two) encodings. If the encoding in the XML file is given as either US-ASCII, UTF-8, or ISO-8859-1, the data returned to the COBOL program will be encoded in that character set. The only other encoding supported by C$XML is UTF-16. If an XML file is parsed that uses UTF-16, the data will be returned to the COBOL program as UTF-8.

Note that modifying the encoding will most likely cause errors, unless you translate all the data of the XML file into the new encoding before writing it. In other words, changing the encoding attribute does NOT cause the entire XML file to be translated into the new encoding automatically. Caution should be used in this area

Parent topic: C$XML


CXML-GET-STANDALONE

Syntax:

CALL "C$XML" USING CXML-GET-STANDALONE, handle, dest

Parameters:

CXML-GET-STANDALONE | Op-code 43. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
dest | pic x(n) for n >= 3

On Entry:

CXML-GET-STANDALONE | Value 43
handle | A parser handle.

On Exit:

dest | The destination for the standalone value.
RETURN-CODE | The return code is 0 if an error has occurred. The return code is positive if everything went correctly.
Parent topic: C$XML


CXML-SET-STANDALONE

Syntax:

CALL "C$XML" USING CXML-SET-STANDALONE, handle, new-standalone

Parameters:

CXML-SET-STANDALONE | Op-code 44. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
new-version | pic x(n)

On Entry:

CXML-SET-STANDALONE | Value 44
handle | A parser handle.

On Exit:

RETURN-CODE Can either be “no” or “yes”, which puts the corresponding value into the XML file. Any other value causes the stand-alone attribute to be omitted from the XML file.
Parent topic: C$XML


CXML-GET-RAW-DOCTYPE-LEN

Syntax:

CALL "C$XML" USING CXML-GET-RAW-DOCTYPE-LEN, handle

Parameters:

CXML-GET-RAW-DOCTYPE-LEN | Op-code 45. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle

On Entry:

CXML-GET-RAW-DOCTYPE-LEN | Value 45
handle | A parser handle.

On Exit:

RETURN-CODE The length of the raw doctype, or -1 on error.
Parent topic: C$XML


CXML-GET-RAW-DOCTYPE

Syntax:

CALL "C$XML" USING CXML-GET-RAW-DOCTYPE, handle, new-encoding

Parameters:

CXML-GET-RAW-DOCTYPE | Op-code 46. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
new-encoding | A pic x(n) or USAGE pointer data item

On Entry:

CXML-GET-RAW-DOCTYPE | Value 46
handle | A parser handle.

On Exit:

new-encoding | Filled in with the current raw doctype value. If it is shorter than the length of the current doctype, it will be truncated. If doctype is of type POINTER, you should include len (a numeric data item) as well and set it to the number of bytes allocated for doctype.
RETURN-CODE | The return code is 0 if an error has occurred. The return code is positive if everything went correctly.
Parent topic: C$XML


CXML-SET-RAW-DOCTYPE

Syntax:

CALL "C$XML" USING CXML-SET-RAW-DOCTYPE, handle, doctype

Parameters:

CXML-SET-RAW-DOCTYPE | Op-code 47. Numeric data item that specifies the operation to perform. Each operation is defined in acucobol.def, which is included with your system.
handle | USAGE handle
doctype | pic x(n) or string literal

On Entry:

CXML-SET-RAW-DOCTYPE | Value 47
handle | A parser handle.

On Exit:

RETURN-CODE 0 on error, or 1 on success.
Parent topic: C$XML


CBL_AND

CBL_AND performs a binary, bitwise "and" operation on a series of bytes.

Usage

CALL "CBL_AND"
    USING SOURCE, DEST, LENGTH
    GIVING STATUS

Parameters

SOURCE PIC X(n) | The source bytes for the operation.
DEST PIC X(n) | The destination bytes for the operation.
LENGTH Numeric parameter (optional) | The number of bytes to combine. If omitted, then CBL_AND uses the minimum of the size of SOURCE and the size of DEST.
STATUS Any numeric data item | The return status of the operation. Returns 0 if successful, 1 if not. This routine always succeeds, so STATUS always contains a zero.

Description

For LENGTH bytes, each byte of SOURCE is combined with the corresponding byte of DEST. The result is stored back into DEST. The bytes are combined by performing an "and" operation between each bit of the bytes. The "and" operation uses the following table to determine the result:

And | 0 | 1
0 | 0 | 0
1 | 0 | 1
Parent topic: General Syntax and Library List


CBL_CLEAR_SCR

The CBL_CLEAR_SCR routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine clears the entire screen using a specified character and attribute.

Usage

CALL "CBL_CLEAR_SCR"
    USING CHARACTER, ATTRIBUTE
    RETURNING STATUS-CODE

Parameters

CHARACTER PIC X COMP-X. | On entry, contains the character to write
ATTRIBUTE PIC X COMP-X. | On entry, contains the attribute to write
STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful
Parent topic: General Syntax and Library List


CBL_CLOSE_FILE

Usage

CAll "CBL_CLOSE_FILE"
     USING HANDLE
     RETURNING STATUS-CODE

Parameters

HANDLE (pic x(4) comp-x) This is the handle returned from CBL_OPEN_FILE or CBL_CREATE_FILE. Once this routine is called, the file handle should not be used in future calls to READ or WRITE or CLOSE, or undefined results will occur, including the possibility of a MAV.

Description

This routine is used for closing files and returns 0 on success and non-zero if an error occurred. The error is a special encoding of the digit 9 with the ANSI-74 error code, or the runtime system error number if no ANSI-74 error code pertains to the error. If RETURN-CODE is non-zero after calling this routine, you must process it as a file status, for example:

01  file-status-group.
    03  file-status     pic xx comp-x.
    03  redefines file-status.
        05  fs-byte-1  pic x.
        05  fs-byte-2  pic x comp-x.
. . .
call "CBL_CLOSE_FILE" using parameters
if return-code not = 0
    move return-code to file-status
. . .

At this point fs-byte-1 contains "9" and fs-byte-2 contains the ANSI-74 error code, or a runtime system error number.

Note: This routine is written in C and is called via the "direct" method, so it is not possible for the runtime to validate parameters for accuracy. Passing unexpected parameters will result in undefined behavior and possibly even a MAV.
Parent topic: General Syntax and Library List


CBL_COPY_FILE

CBL_COPY_FILE creates a copy of an existing file.

Usage

CALL "CBL_COPY_FILE"
    USING SOURCE-FILE, DEST-FILE,
    GIVING COPY-STATUS

Parameters

SOURCE-FILE PIC X(n) | Contains the name of the file to copy. The name can contain a path and is terminated by a space. If no path is given, the current directory is assumed. Remote name notation is allowed for this parameter.
DEST-FILE PIC X(n) | Contains the destination file name. The name can contain a path and is terminated by a space. If no path is given, the current directory is assumed. Remote name notation is allowed for this parameter.
COPY-STATUS Any numeric type | Returns 0 if successful, or 1 if not.

Description

CBL_COPY_FILE creates an exact duplicate of SOURCE-FILE in DEST-FILE.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

To transfer files between the application host and display host in a thin client environment, add the prefix "@[DISPLAY]:" to the name of any source or destination file that resides on the client machine. For example:

CBL_COPY_FILE "@[DISPLAY]:C:\path\file1.ext" "/usr/data/
file1.ext"

To copy from one path on the client to another, specify the "@[DISPLAY]:" prefix for both the SOURCE-FILE and the DEST-FILE.

If the file name on the client starts with special directory specifiers, the thin client attempts to locate those files in special Windows directories. The special directory names are as follows:

Identifier | Directory
<APPDATA> | C:\Documents and Settings\<user>\Application Data
<COMMON_APPDATA> | C:\Documents and Settings\All Users\Application Data
<COMMON_DOCUMENTS> | C:\Documents and Settings\All Users\Documents
<DESKTOP> | C:\Documents and Settings\<user>\Desktop
<LOCAL_APPDATA> | C:\Documents and Settings\<user>\Local Settings\Application Data
<MYDOCUMENTS> | C:\Documents and Settings\<user>\My Documents

these directories are not necessarily the same for all versions of Windows, and may in fact be on network drives.

Note: THIS NOTE APPLIES TO C$CHDIR.To get the current default directory on the display host, DIR_NAME should contain "@[DISPLAY]:" followed by spaces."
Parent topic: General Syntax and Library List


CBL_CREATE_DIR

CBL_CREATE_DIR creates a subdirectory. All of the directories in the given path, except the last, must already exist.

Usage

CALL "CBL_CREATE_DIR"
    USING DIR-NAME,
    GIVING STATUS

Parameters

DIR-NAME PIC X(n) | Contains the name of the directory to be created. This should be either a full path name or a name relative to the current directory. You may use remote name syntax in combination with AcuServer to create a directory on a remote machine. CBL_CREATE_DIR can make a directory only one level lower than an existing directory and cannot create more than one level at a time.
STATUS Any numeric type | Returns 0 if successful, or 1 if not.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

Parent topic: General Syntax and Library List


CBL_CREATE_FILE

Usage

CAll "CBL_CREATE_FILE"
     USING FILENAME, ACCESS-MODE, DENY-MODE, DEVICE, HANDLE
     RETURNING STATUS-CODE

Parameters

FILENAME (PIC X(n)) | This is the name of a file to create. If this file does not exist, the open fails and sets return-code to 1. The filename parameter can be blank-terminated or terminated with low-values.
ACCESS-MODE (pic x comp-x) | This parameter is ignored (the file is always open for writing only), and the file is created anew. This means that if the file exists, it is truncated to 0 bytes, and if it does not exist, it is created.
DENY-MODE (pic x comp-x) | Determines how other users can access the file: 0 to deny read and write access by other users, 1 to deny write access, 2 to deny read access, and 3 to allow all other users. This flag has an effect only on Windows systems.
DEVICE (pic x comp-x) | This is not used and must be 0.
HANDLE (pic x(4) comp-x) | This is set to the handle of the file created. Use this handle in the other functions.

Description

This routine is used for creating files and returns 0 on success and non-zero if an error occurred. The error is a special encoding of the digit 9 with the ANSI-74 error code, or the runtime system error number if no ANSI-74 error code pertains to the error. If RETURN-CODE is non-zero after calling this routine, you must process it as a file status, for example:

01  file-status-group.
    03  file-status     pic xx comp-x.
    03  redefines file-status.
        05  fs-byte-1  pic x.
        05  fs-byte-2  pic x comp-x.
. . .
call "CBL_CREATE_FILE" using parameters
if return-code not = 0
    move return-code to file-status
. . .

At this point fs-byte-1 contains 9 and fs-byte-2 contains the ANSI-74 error code, or a runtime system error number.

Note: This routine is written in C and is called via the "direct" method, so it is not possible for the runtime to validate parameters for accuracy. Passing unexpected parameters will result in undefined behavior and possibly even a MAV.
Parent topic: General Syntax and Library List


CBL_DELETE_DIR

CBL_DELETE_DIR deletes the indicated directory. The directory is deleted only if it is empty. You may use remote name syntax in combination with AcuServer to delete a directory on a remote machine.

Usage

CALL "CBL_DELETE_DIR"
    USING PATH-NAME,
    GIVING STATUS

Parameters

PATH-NAME PIC X(n) Contains the relative or absolute path name, terminated by space or NULL.

The "@[DISPLAY]:" for Thin Client support is allowed. For example:

CBL_DELETE_DIR "@[DISPLAY]:C:\path"

See CBL_COPY_FILE for more information.

STATUS Any numeric type Returns 0 if successful, or 1 if not.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

Parent topic: General Syntax and Library List


CBL_DELETE_FILE

CBL_DELETE_FILE deletes the indicated file.

Usage

CALL "CBL_DELETE_FILE"
    USING FILE-NAME,
    GIVING STATUS

Parameters

FILE-NAME PIC X(n) Contains the name of the file to be deleted. This should either be a full path name or a name relative to the current directory.

The "@[DISPLAY]:" annonation for Thin Client is allowed. For example:

CBL_DELETE_FILE "@[DISPLAY]:C:\path\filename"

See CBL_COPY_FILE for more information.

STATUS Any numeric data type Returns 0 if successful, or 1 if not.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

Parent topic: General Syntax and Library List


CBL_EQ

CBL_EQ performs a binary, bitwise "equals" operation on a series of bytes.

Usage

CALL "CBL_EQ"
    USING SOURCE, DEST, LENGTH
    GIVING STATUS

Parameters

SOURCE PIC X(n) | The source bytes for the operation.
DEST PIC X(n) | The destination bytes for the operation.
LENGTH Numeric parameter (optional) | The number of bytes to combine. If omitted, then CBL_EQ uses the minimum of the size of SOURCE and the size of DEST.
STATUS Any numeric data item | The return status of the operation. Returns "0" if successful, "1" if not. This routine always succeeds, so STATUS always contains a zero.

Description

For LENGTH bytes, each byte of SOURCE is combined with the corresponding byte of DEST. The result is stored back into DEST. The runtime combines the bytes by performing an "equals" operation between each bit of the bytes. The "equals" operation uses the following table to determine the result:

Eq | 0 | 1
0 | 1 | 0
1 | 0 | 1
Parent topic: General Syntax and Library List


CBL_ERROR_PROC

CBL_ERROR_PROC installs or removes error procedures to be called automatically if and when the current run unit generates any of certain runtime errors. This implementation calls error procedures only when a run unit generates what is called an intermediate runtime error. The list of intermediate runtime errors includes:

  • File error #
  • File error # on #
  • Illegal MERGE
  • Illegal RELEASE
  • Illegal RETURN
  • Illegal SORT
  • Index out of bounds
  • INSPECT REPLACING size mismatch
  • Invalid or missing parameter
  • Non-numeric data in numeric field
  • Passed USING item smaller than corresponding LINKAGE item
  • Program missing or inaccessible
  • Reference modifier range error
  • Transaction error #
  • Transaction error # on #
  • Use of a LINKAGE data item not passed by the caller

The "#" signs are replaced at run time by error names, numbers, or other information.

Usage

CALL "CBL_ERROR_PROC"
    USING INSTALL-FLAG PROGRAM-NAME
    [RETURNING STATUS-CODE]

Parameters

INSTALL-FLAG Numeric data item or literal | Zero if the error procedure is to be installed; nonzero if it is to be removed.
PROGRAM-NAME Alphanumeric data item or literal | Name of the error procedure to be installed or removed.
STATUS-CODE Any numeric data item | Always zero. (It is returned only for Micro Focus compatibility.)

Description

A run unit can dynamically build a single queue of one or more error procedures to be called if and when the run unit generates any of certain runtime errors. Not all runtime errors are treated in this way. Some, such as memory allocation errors, are so severe that the runtime cannot continue and must be aborted. Others, such as size errors, are handled by ordinary COBOL code. Runtime errors which call error procedures are called intermediate errors.

When an error procedure is installed, it is placed at the beginning of the queue (or moved to the beginning if it is already in the queue).

When an intermediate runtime error occurs, and there are error or exit procedures in the queues, the error procedures in the queue are called, one by one, as though by a CALL statement, in sequential order (the opposite of installation order), with a single PIC X(325) argument containing the text of an appropriate error message. This error message may contain newline characters and is null-terminated like a C string. Each procedure is removed from the queue just before it is called.

Note: You can cause the runtime to also include the program name and the address of the program failure in the string passed to the error procedure by setting the INCLUDE_PGM_INFO runtime configuration variable. See the entry for INCLUDE_PGM_INFO in Appendix H.

An error procedure must end with an EXIT PROGRAM RETURNING statement which contains an appropriate return value. If the return value is zero, then subsequent error procedures are removed from the queue and are not called.

After all error procedures are called, the exit procedures, if any, are called. Then the run unit is terminated.

If an error procedure generates an intermediate runtime error, it is terminated and the remaining error procedures, if any, are called. Then the exit procedures, if any, are called, and the run unit is terminated.

If an intermediate runtime error occurs when there are no error or exit procedures in the queues, it is handled in the usual way. In some cases, the error is ignored. In other cases, the runtime issues an error message and terminates the entire application, not just the run unit which generated the error.

Note: An error procedure may install or remove exit procedures and other error procedures. This practice is not generally recommended, however, because it may lead to hard-to-predict behaviors resulting in part from the runtime modifications employed in the handling of error and exit procedures.

Error procedure names are case-insensitive and must not contain spaces.

To prevent the program from entering an infinite loop or non-terminating condition, the total number of error and exit procedures installed or called is limited to the value of the configuration parameter MAX_ERROR_AND_EXIT_PROCS. The default value is 64. Any attempt to exceed this limit aborts the application.

Parent topic: General Syntax and Library List


CBL_EXIT_PROC

CBL_EXIT_PROC installs, removes, and queries exit procedures to be called automatically when the current run unit terminates normally.

In some cases exit procedures can be called when a run unit generates an error. See the CBL_ERROR_PROC. Routine for error-caused terminations of the run unit.

Usage

CALL "CBL_EXIT_PROC"
    USING PRIORITY-NUMBER PROGRAM-NAME
    [RETURNING STATUS-CODE]

Parameters

PRIORITY-NUMBER Numeric data item or literal | Priority number of the queue or the special value "254" or "255".
PROGRAM-NAME Alphanumeric data item or literal | Name of the exit procedure to be installed, removed, or queried.
STATUS-CODE Any numeric data item | Queue number when the exit procedure is queried.

Description

A run unit can dynamically build one or more queues of exit procedures to be called if and when the run unit terminates normally or when an error procedure terminates normally.

Exit procedures are kept in queues, one queue for each priority level. Each run unit has its own set of queues, with priorities ranging from 0 to 127, inclusive. The priority queue for an exit procedure is determined when the procedure is installed. Because it is possible for an error or exit procedure to install or remove error or exit procedures, the priorities and queues can change dynamically. The queues and priorities that apply in the end are those in effect at the time when the runtime chooses an error or exit procedure to call.

When the program calls CBL_EXIT_PROC, if the priority-number is in the range from 0 to 127, inclusive, then:

  1. The exit procedure is removed from the current run unit, if present;
  2. The exit procedure is installed at the beginning of the corresponding queue for the current run unit.

If the priority-number is 254, the exit procedure is simply removed from the current run unit.

If the priority-number is 255, the priority number of the queue in the current run unit containing the exit procedure is returned in status-code (or RETURN-CODE, if no RETURNING phrase is present). RETURN-CODE is described in CALL Statement, General Rule 21 in the ACUCOBOL-GT Reference Manual. If it is not in any queue in the current run unit, the value "255" is returned.

The installed exit procedures for the current run unit are called when the current run unit terminates by executing a STOP RUN, CALL PROGRAM or CHAIN statement.

An exit procedure cannot start a new run unit by executing a CALL RUN or CHAIN statement. If it tries to do so, the runtime displays an error message and stops without calling any other procedures.

An exit procedure must not call STOP RUN. Its effects are undefined.

Exit procedures in queues with lower priority numbers are called before those in queues with higher priority numbers. Exit procedures in the same queue are called in sequential order (the opposite of installation order). Each exit procedure is removed from its queue just before it is called.

An exit procedure may install, remove, or query other exit procedures.

An exit procedure is called as though by a CALL statement and must return by an EXIT PROGRAM statement.

Exit procedure names are case-insensitive and must not contain spaces.

No arguments are passed to an exit procedure, and an exit procedure may not return a value.

To prevent the program from entering an infinite loop or non-terminating condition, the total number of exit procedures installed or called is limited to the value of the configuration parameter MAX_ERROR_AND_EXIT-PROCS. The default value is 64. Any attempt to exceed this limit aborts the application.

Parent topic: General Syntax and Library List


CBL_FLUSH_FILE

Usage

CAll "CBL_FLUSH_FILE"
     USING HANDLE
     RETURNING STATUS-CODE

Parameters

HANDLE (pic x(4) comp-x) This is the handle returned from CBL_OPEN_FILE or CBL_CREATE_FILE. Any buffers that have not been flushed to disk will be flushed.

Description

This routine is used for flushing files and returns 0 on success and non-zero if an error occurred. The error is a special encoding of the digit 9 with the ANSI-74 error code, or the runtime system error number if no ANSI-74 error code pertains to the error. If RETURN-CODE is non-zero after calling this routine, you must process it as a file status, for example:

01  file-status-group.
    03  file-status     pic xx comp-x.
    03  redefines file-status.
        05  fs-byte-1  pic x.
        05  fs-byte-2  pic x comp-x.
. . .
call "CBL_FLUSH_FILE" using parameters
if return-code not = 0
    move return-code to file-status
. . .

At this point fs-byte-1 contains 9 and fs-byte-2 contains the ANSI-74 error code, or a runtime system error number.

Note: This routine is written in C and is called via the direct method, so it is not possible for the runtime to validate parameters for accuracy. Passing unexpected parameters will result in undefined behavior and possibly even a MAV.
Parent topic: General Syntax and Library List


CBL_GET_CSR_POS

The CBL_GET_CSR_POS routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine returns the cursor position.

Usage

CALL "CBL_GET_CSR_POS"
    USING SCREEN-POSITION
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On exit, contains the screen position of the cursor. The top left corner is row 0, column 0.

STATUS-CODE Any numeric type Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine the position of the cursor on the screen.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_GET_EXIT_INFO

CBL_GET_EXIT_INFO provides an exit procedure with certain information about the termination that invoked it. It is included mainly for compatibility with other COBOL implementations.

Usage

CALL "CBL_GET_EXIT_INFO"
    USING EXIT-INFO
    [RETURNING STATUS-CODE]

Parameters

EXIT-INFO Group item. Group item containing four elementary data items laid out as follows:
exit-info.
   p-block-size   PIC X(4) COMP-N VALUE 16.
   p-return-code  PIC X(4) COMP-N.
   p-rts-error    PIC X(4) COMP-N.
   p-exit-flags   PIC X(4) COMP-N.
STATUS-CODE Any numeric data item. Return status of the operation.

Description

Termination information is returned in the last three items of exit-info and in status-code. The items returned and their values are as follows:

p-return-code

most recent value of RETURN-CODE

p-rts-error

error number of the most recent runtime error, or zero if none

p-exit-flags

a 32-bit word with flag bits as follows (bit 0 is the least significant bit):

Bit | Meaning of "1" in this bit
0 | always zero
1 | always zero
2 | terminated by STOP RUN, CALL PROGRAM, or CHAIN
3 | always zero
4 | terminated by operator
5 | always zero
6-31 | reserved; always zero

status-code

the status of the operation as follows:

Value | Meaning
0 | success
1006 | called from outside exit procedure
1009 | value of p-block-size is not 16
Parent topic: General Syntax and Library List


CBL_GET_SCR_SIZE

The CBL_GET_SCR_SIZE routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine returns the screen size.

Usage

CALL "CBL_GET_SCR_SIZE"
    USING DEPTH, WIDTH
    RETURNING STATUS-CODE

Parameters

DEPTH PIC X COMP-X. | On exit, contains the number of lines in the screen
WIDTH PIC X COMP-X. | On exit, contains the number of columns in the screen
STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses the DEPTH and WIDTH parameters to return information about the size of the screen.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_NOT

CBL_NOT performs a binary, bitwise "not" operation on a series of bytes.

Usage

CALL "CBL_NOT"
    USING DEST, LENGTH
    GIVING STATUS

Parameters

DEST PIC X(n) | Data area containing the bytes for the operation.
LENGTH Numeric parameter (optional) | Describes the number of bytes to combine. If omitted, then CBL_NOT uses the size of DEST.
STATUS Any numeric data item | Contains the return status of the operation. Returns zero if successful, 1 if not. This routine always succeeds, so STATUS always contains a zero.

Description

For LENGTH bytes, each byte of DEST is negated in a bitwise fashion. For each bit of each byte, the result is the opposite bit value. The "not" operation uses the following table to determine the result:

Not |
0 | 1
1 | 0
Parent topic: General Syntax and Library List


CBL_OPEN_FILE

Usage

CAll "CBL_OPEN_FILE"
     USING FILENAME, ACCESS-MODE, DENY-MODE, DEVICE, HANDLE
     RETURNING STATUS-CODE

Parameters

FILENAME (PIC X(n)) | This is the name of a file to open. If this file does not exist, the open fails and sets return-code to "1". The filename parameter can be blank-terminated or terminated with low-values.
ACCESS-MODE (pic x comp-x) | This is the mode in which to open the file: 1 for Input, 2 for Output, 3 for IO. Any other value will result in the open failing, with a return-code of 1.
DENY-MODE (pic x comp-x) | Determines how other users can access the file: 0 to deny read and write access by other users, 1 to deny write access, 2 to deny read access, and 3 to allow all other users. This flag has an effect only on Windows systems.
DEVICE (pic x comp-x) | This is not used and must be 0.
HANDLE (pic x(4) comp-x) | This is set to the handle of the file opened. Use this handle in the other functions.

Description

This routine is used for opening files for reading and/or writing and returns 0 on success and non-zero if an error occurred. The error is a special encoding of the digit 9 with the ANSI-74 error code, or the runtime system error number if no ANSI-74 error code pertains to the error. If RETURN-CODE is non-zero after calling this routine, you must process it as a file status, for example:

01  file-status-group.
    03  file-status     pic xx comp-x.
    03  redefines file-status.
        05  fs-byte-1  pic x.
        05  fs-byte-2  pic x comp-x.
. . .
call "CBL_xxx_FILE" using parameters
if return-code not = 0
    move return-code to file-status
. . .

At this point fs-byte-1 contains 9 and fs-byte-2 contains the ANSI-74 error code, or a runtime system error number.

Note: This routine is written in C and is called via the direct method, so it is not possible for the runtime to validate parameters for accuracy. Passing unexpected parameters will result in undefined behavior and possibly even a MAV.

This routine is written in C and is called via the direct method, so it is not possible for the runtime to validate parameters for accuracy. Passing unexpected parameters will result in undefined behavior and possibly even a MAV.

Parent topic: General Syntax and Library List


CBL_OR

CBL_OR performs a binary, bitwise "or" operation on a series of bytes.

Usage

CALL "CBL_OR"
    USING SOURCE, DEST, LENGTH
    GIVING STATUS

Parameters

SOURCE PIC X(n) | The source bytes for the operation.
DEST PIC X(n) | The destination bytes for the operation.
LENGTH Numeric parameter (optional) | The number of bytes to combine. If omitted, then CBL_OR uses the minimum of the size of SOURCE and the size of DEST.
STATUS Any numeric data item | The return status of the operation. Returns 0 if successful, 1 if not. This routine always succeeds, so STATUS always contains a zero.

Description

For LENGTH bytes, each byte of SOURCE is combined with the corresponding byte of DEST. The result is stored back into DEST. The runtime combines the bytes by performing an "or" operation between each bit of the bytes. The "or" operation uses the following table to determine the result:

Or | 0 | 1
0 | 0 | 1
1 | 1 | 1
Parent topic: General Syntax and Library List


CBL_READ_FILE

Usage

CAll "CBL_READ_FILE"
     USING HANDLE, OFFSET, COUNT, FLAGS, BUF
     RETURNING STATUS-CODE

Parameters

HANDLE (pic x(4) comp-x) | This is the handle returned from CBL_OPEN_FILE.
OFFSET (pic x(8) comp-x) | This is the offset from which to read from the file, based at "0" to read from the first byte. Note that this is a 64-bit value, allowing access to files larger than 4GB. Note that if your OS or File System does not allow such files, setting this to a value larger than your OS or file system can support will cause undefined results.
COUNT (pic x(4) comp-x) | This is the number of bytes to read. This should not be set to a value larger than the size of the buffer (described below), or you will get undefined results, including a potential MAV.
FLAGS (pic x comp-x) | One special value is recognized. If this parameter is 128, the size of the file returned is the offset parameter, and the file is not read. The only other allowable value is 0.
BUF (pic x(n)) | This is the buffer that will store the values read from the file. This buffer should be at least count bytes long.

Description

This routine is used for reading files and returns 0 on success and non-zero if an error occurred. The error is a special encoding of the digit 9 with the ANSI-74 error code, or the runtime system error number if no ANSI-74 error code pertains to the error. If RETURN-CODE is non-zero after calling this routine, you must process it as a file status, for example:

01  file-status-group.
    03  file-status     pic xx comp-x.
    03  redefines file-status.
        05  fs-byte-1  pic x.
        05  fs-byte-2  pic x comp-x.
. . .
call "CBL_READ_FILE" using parameters
if return-code not = 0
    move return-code to file-status
. . .

At this point fs-byte-1 contains 9 and fs-byte-2 contains the ANSI-74 error code or a runtime system error number.

Note: This routine is written in C and is called via the "direct" method, so it is not possible for the runtime to validate parameters for accuracy. Passing unexpected parameters will result in undefined behavior and possibly even a MAV.
Parent topic: General Syntax and Library List


CBL_READ_SCR_ATTRS

The CBL_READ_SCR_ATTRS routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine reads a string of attributes from the screen.

Usage

CALL "CBL_READ_SCR_ATTRS"
    USING SCREEN-POSITION, ATTRIBUTE-BUFFER, STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, the screen position at which to start reading (the top left corner is row 0, column 0)

ATTRIBUTE-BUFFER PIC X(N). | On exit, this data item contains the attributes read from the screen. It must be at least the length specified by STRING-LENGTH. Positions in the data item beyond that length are unchanged.
STRING-LENGTH PIC XX COMP-X. On entry, contains the length of the string to read

On exit, contains the length of the string read when the end of the screen is reached

STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine the location to start the read operation. STRING-LENGTH specifies the length of the string of attributes to be read, starting from SCREEN-POSITION. When the routine exits, ATTRIBUTE-BUFFER contains the string of attributes read.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_READ_SCR_CHARS

The CBL_READ_SCR_CHARS routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine reads a string of characters from the screen.

Usage

CALL "CBL_READ_SCR_CHARS"
    USING SCREEN-POSITION, CHARACTER-BUFFER, STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position at which to start reading (the top left corner is row 0, column 0)

CHARACTER-BUFFER PIC X(N). | On exit, this data item contains the characters read from the screen. It must be at least the length specified by STRING-LENGTH. Positions in the data item beyond that length are unchanged.
STRING-LENGTH PIC XX COMP-X. On entry, contains the length of the string to read

On exit, contains the length of the string read when the end of the screen is reached

STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine the location to start the read operation. STRING-LENGTH specifies the length of the string of characters to be read, starting from SCREEN-POSITION. When the routine exits, CHARACTER-BUFFER contains the string of characters read.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_READ_SCR_CHATTRS

The CBL_READ_SCR_CHATTRS routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine reads a string of characters and their corresponding attributes from the screen.

Usage

CALL "CBL_READ_SCR_CHATTRS"
    USING SCREEN-POSITION, CHARACTER-BUFFER, ATTRIBUTE-BUFFER,
        STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position at which to start reading (the top left corner is row 0, column 0)

CHARACTER-BUFFER PIC X(N). | On exit, this data item contains the characters read from the screen. It must be at least the length specified by STRING-LENGTH. Positions in it beyond that length are unchanged.
ATTRIBUTE-BUFFER PIC X(N). | On exit, this data item contains the attributes read from the screen. It must be at least the length specified by STRING-LENGTH. Positions in the data item beyond that length are unchanged.
STRING-LENGTH PIC XX COMP-X. On entry, contains the length of the string to read

On exit, contains the length of the string read when the end of the screen is reached

STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine the location to start the read operation. STRING-LENGTH specifies the length of the string to be read, starting from SCREEN-POSITION. When the routine exits, CHARACTER-BUFFER contains the string of characters read, and ATTRIBUTE-BUFFER contains those characters' attributes.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_SET_CSR_POS

The CBL_SET_CSR_POS routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine moves the cursor.

Usage

CALL "CBL_SET_CSR_POS"
    USING SCREEN-POSITION
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position at which to put the cursor (the top left corner is row 0, column 0)

STATUS-CODE Any numeric type Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to move the cursor to a particular location on the screen.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_SUBSYSTEM

This routine is used to define a COBOL subsystem, which allows cancelling of all COBOL programs in the subsystem with a single statement.

Usage

This library routine takes two parameters. The first parameter is an opcode, and the second parameter depends on the opcode used:

CALL "CBL_SUBSYSTEM" using op-code, parameter GIVING status-code

Parameters

op-code (pic x comp-x) This contains one of the following values:
  • 0 - declare subsystem
  • 1 - cancel subsystem
  • 2 - remove subsystem

When op-code = 0, "parameter" is a group item that looks like:

  ss-handle    pic x(2) comp-x.
  ss-name-len  pic x(2) comp-x.
  ss-name    pic x(n).

When op-code = 1, "parameter" is:

  ss-handle    pic x(2) comp-x.

When op-code = 2, "parameter" is ignored.

On entry:

op-code has the value of the operation to perform, 0, 1, or 2.

When op-code = 0, ss-name-len holds the length of the subsystem program-name field. ss-name holds the subsystem program-name. This must be a COBOL program.

When op-code = 0, ss-handle holds the subsystem handle returned by a function 0 call.

On exit:

When op-code = 0, ss-handle holds the subsystem handle value.

Comments

  1. A subsystem is defined as a specified program in an application, plus any subprograms subsequently called by programs already in the subsystem that do not already belong to any other subsystems.
  2. opcode 0 declares a subsystem. The routine returns a subsystem handle in ss-handle. The next time the program named is called in an initial state, it becomes part of the subsystem. Any subprograms it calls also become part of the subsystem, unless they are not in an initial state.
  3. A program belonging to a subsystem is cancelled only under the following circumstances: it is the object of a CANCEL verb, the program cancels the entire subsystem using opcode 1, or the application executes a STOP RUN or CHAIN statement.
  4. opcode 1 cancels all programs in the specified subsystem. If any program in the subsystem is still active, that program is released from the subsystem and is not cancelled.
  5. opcode 2 removes the program that called it from any subsystem the program is in. To ensure a program is never included in any subsystem, call this function at the start of each entry into the program.
Parent topic: General Syntax and Library List


CBL_SWAP_SCR_CHATTRS

The CBL_SWAP_SCR_CHATTRS routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine writes a string of characters and their attributes over another character string on the screen.

Usage

CALL "CBL_SWAP_SCR_CHATTRS"
    USING SCREEN-POSITION, CHARACTER-BUFFER, ATTRIBUTE-BUFFER,
        STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position to start writing (the top left corner is row 0, column 0)

CHARACTER-BUFFER PIC X(N). On entry, contains the characters to write

On exit, this data item contains the characters overwritten on the screen. It must be at least the length specified by STRING-LENGTH. Positions in the data item beyond that length are unchanged.

ATTRIBUTE-BUFFER PIC X(N). On entry, contains the attributes to write

On exit, this data item contains the attributes overwritten on the screen. It must be at least the length specified by STRING-LENGTH. Positions in the data item beyond that length are unchanged.

STRING-LENGTH PIC XX COMP-X. On entry, this item contains the length of the string to write. Note that the write stops at the end of the screen.

On exit, this item contains the length of the overwritten string (in cells, that is character-attribute pairs).

STATUS-CODE Any numeric type Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine where to begin the write operation. On entry, CHARACTER-BUFFER and ATTRIBUTE-BUFFER contain the characters to write and their corresponding attributes, respectively, and STRING-LENGTH contains that string's length. On exit, CHARACTER-BUFFER and ATTRIBUTE-BUFFER contain the characters that were replaced on the screen and their corresponding attributes, respectively. STRING-LENGTH is the length of the string that was overwritten.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_WRITE_FILE

Usage

CAll "CBL_WRITE_FILE"
     USING HANDLE, OFFSET, COUNT, FLAGS, BUF
     RETURNING STATUS-CODE

Parameters

HANDLE (pic x(4) comp-x) | This is the handle returned from CBL_OPEN_FILE.
OFFSET (pic x(8) comp-x) | This is the offset from which to write from the file, based at "0" to read from the first byte. Note that this is a 64-bit value, allowing access to files larger than 4GB. Note that if your OS or File System does not allow such files, setting this to a value larger than your OS or file system can support will cause undefined results.
COUNT (pic x(4) comp-x) | This is the number of bytes to read. This should not be set to a value larger than the size of the buffer (described below), or you will get undefined results, including a potential MAV.
FLAGS (pic x comp-x) | One special value is recognized. This value must be set to 0.
BUF (pic x(n)) | This is the buffer that will write to the file at "offset". This buffer should be at least count bytes long.

Description

This routine is used for writing files and returns 0 on success and non-zero if an error occurred. The error is a special encoding of the digit 9 with the ANSI-74 error code, or the runtime system error number if no ANSI-74 error code pertains to the error. If RETURN-CODE is non-zero after calling this routine, you must process it as a file status, for example:

01  file-status-group.
    03  file-status     pic xx comp-x.
    03  redefines file-status.
        05  fs-byte-1  pic x.
        05  fs-byte-2  pic x comp-x.
. . .
call "CBL_WRITE_FILE" using parameters
if return-code not = 0
    move return-code to file-status
. . .

At this point fs-byte-1 contains 9 and fs-byte-2 contains the ANSI-74 error code or a runtime system error number.

Note: This routine is written in C and is called via the direct method, so it is not possible for the runtime to validate parameters for accuracy. Passing unexpected parameters will result in undefined behavior and possibly even a MAV.
Parent topic: General Syntax and Library List


CBL_WRITE_SCR_ATTRS

The CBL_WRITE_SCR_ATTRS routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine writes a string of attributes to the screen.

Usage

CALL "CBL_WRITE_SCR_ATTRS"
    USING SCREEN-POSITION, ATTRIBUTE-BUFFER, STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position at which to start writing (the top left corner is row 0, column 0)

ATTRIBUTE-BUFFER PIC X(N). | On entry, contains the attributes to write
STRING-LENGTH PIC XX COMP-X. | On entry, this item contains the length of the string to write. Note that the write stops at the end of the screen.
STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine where on the screen to begin the write operation. ATTRIBUTE-BUFFER contains the string of attributes to write, and STRING-LENGTH contains the length of that string of attributes.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_WRITE_SCR_CHARS

The CBL_WRITE_SCR_CHARS routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine writes a string of characters to the screen.

Usage

CALL "CBL_WRITE_SCR_CHARS"
    USING SCREEN-POSITION, CHARACTER-BUFFER, STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position at which to start writing (the top left corner is row 0, column 0)

CHARACTER-BUFFER PIC X(N). | On entry, contains the characters to write
STRING-LENGTH PIC XX COMP-X. | On entry, contains the length of the string to write. Note that the write stops at the end of the screen.
STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine the location on the screen to begin the write operation. CHARACTER-BUFFER contains the string of characters to write, and STRING-LENGTH contains the length of that character string.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_WRITE_SCR_CHARS_ATTR

The CBL_WRITE_SCR_CHARS_ATTR routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine writes a string of characters to the screen, giving them all the same attribute.

Usage

CALL "CBL_WRITE_SCR_CHARS_ATTR"
    USING SCREEN-POSITION, CHARACTER-BUFFER, STRING-LENGTH,
        ATTRIBUTE
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position at which to start writing (the top left corner is row 0, column 0)

CHARACTER-BUFFER PIC X(N). | On entry, contains the characters to write
STRING-LENGTH PIC XX COMP-X. | On entry, this item contains the length of the string to write. Note that the write stops at the end of the screen.
ATTRIBUTE PIC X COMP-X. | On entry, contains the attribute to write
STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine the location on the screen to begin the write operation. CHARACTER-BUFFER contains the string of characters to write, and STRING-LENGTH contains the length of that character string. The ATTRIBUTE parameter contains the attribute to apply to the character string.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_WRITE_SCR_CHATTRS

The CBL_WRITE_SCR_CHATTRS routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine writes a string of characters and their attributes to the screen.

Usage

CALL "CBL_WRITE_SCR_CHATTRS"
    USING SCREEN-POSITION, CHARACTER-BUFFER, ATTRIBUTE-BUFFER,
        STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position at which to start writing (the top left corner is row 0, column 0)

CHARACTER-BUFFER PIC X(N). | On entry, contains the characters to write
ATTRIBUTE-BUFFER PIC X(N). | On entry, contains the attributes to write
STRING-LENGTH PIC XX COMP-X. | On entry, this item contains the length of the string to write. Note that the write stops at the end of the screen.
STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine the location on the screen to begin the write operation. STRING-LENGTH specifies the length of the string to be written, starting from SCREEN-POSITION. When the routine exits, CHARACTER-BUFFER contains the string of characters written, and ATTRIBUTE-BUFFER contains those characters' attributes.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_WRITE_SCR_N_ATTR

The CBL_WRITE_SCR_N_ATTR routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine writes a specified attribute to a string of positions on the screen.

Usage

CALL "CBL_WRITE_SCR_N_ATTR"
    USING SCREEN-POSITION, ATTRIBUTE, STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position at which to start writing (the top left corner is row 0, column 0)

ATTRIBUTE PIC X COMP-X. | On entry, contains the attribute to write
STRING-LENGTH PIC XX COMP-X. | On entry, this item contains the length of the string to write. Note that the write stops at the end of the screen.
STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine the location on the screen to begin the write operation. The ATTRIBUTE parameter contains the attribute to write to the screen location, and STRING-LENGTH is the length of that attribute string.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_WRITE_SCR_N_CHAR

The CBL_WRITE_SCR_N_CHAR routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine writes a specified character to a string of positions on the screen.

Usage

CALL "CBL_WRITE_SCR_N_CHAR"
    USING SCREEN-POSITION, CHARACTER, STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position at which to start writing (the top left corner is row 0, column 0)

CHARACTER PIC X COMP-X. | On entry, contains the character to write
STRING-LENGTH PIC XX COMP-X. | On entry, this item contains the length of the string to write. Note that the write stops at the end of the screen.
STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine the location on the screen to begin the write operation. The CHARACTER parameter contains the character to write to the screen location, and STRING-LENGTH is the length of that character string.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_WRITE_SCR_N_CHATTR

The CBL_WRITE_SCR_N_CHATTR routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine writes a specified character and attribute to a string of positions on the screen.

Usage

CALL "CBL_WRITE_SCR_N_CHATTR"
    USING SCREEN-POSITION, CHARACTER, ATTRIBUTE, STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

SCREEN-POSITION Group item Group item is defined as follows:
01  SCREEN-POSITION.
    03  ROW-NUMBER      PIC X COMP-X.
    03  COLUMN-NUMBER   PIC X COMP-X.

On entry, contains the screen position at which to start writing (the top left corner is row 0, column 0)

CHARACTER PIC X COMP-X. | On entry, contains the character to write
ATTRIBUTE PIC X COMP-X. | On entry, contains the attribute to write
STRING-LENGTH PIC XX COMP-X. | On entry, this item contains the length of the string to write. Note that the write stops at the end of the screen.
STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine uses SCREEN-POSITION (in row and column coordinates) to determine the location on the screen to begin the write operation. The CHARACTER parameter contains the character to write to the screen location, and ATTRIBUTE contains that character's corresponding attribute. STRING-LENGTH is the length of that character/attribute string.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_WRITE_SCR_TTY

The CBL_WRITE_SCR_TTY routine is one of a set of library routines that facilitate reading and writing attributes on the screen. This routine writes a string of characters to the screen starting at the current position and scrolls the screen if the write operation extends beyond the end of the screen.

Usage

CALL "CBL_WRITE_SCR_TTY"
    USING CHARACTER-BUFFER, STRING-LENGTH
    RETURNING STATUS-CODE

Parameters

CHARACTER-BUFFER PIC X(N). | On entry, contains the characters to write
STRING-LENGTH PIC XX COMP-X. | On entry, this item contains the length of the string to write. If the string length extends off the screen, the screen is scrolled up a line and the write continues on the bottom line.
STATUS-CODE Any numeric type | Returns 1 if successful, or 0 if not successful

Description

This library routine writes the character string in the CHARACTER-BUFFER parameter on the screen. STRING-LENGTH contains the length of that character string. If necessary, the routine allows the write operation to continue past the end of the screen with a scrolling action.

Note: This routine is not supported with Thin Client.
Parent topic: General Syntax and Library List


CBL_XOR

CBL_XOR performs a binary, bitwise exclusive or operation on a series of bytes.

Usage

CALL "CBL_XOR"
    USING SOURCE, DEST, LENGTH
    GIVING STATUS

Parameters

SOURCE PIC X(n) | The source bytes for the operation.
DEST PIC X(n) | The destination bytes for the operation.
LENGTH Numeric parameter (optional) | Describes the number of bytes to combine. If omitted, then CBL_XOR uses the minimum of the size of SOURCE and the size of DEST.
STATUS Any numeric data item | Contains the return status of the operation. Returns 0 if successful, 1 if not. This routine always succeeds, so STATUS always contains a zero.

Description

For LENGTH bytes, each byte of SOURCE is combined with the corresponding byte of DEST. The result is stored back into DEST. The bytes are combined by performing an exclusive or operation between each bit of the bytes. The exclusive or operation uses the following table to determine the result:
Xor | 0 | 1
0 | 0 | 1
1 | 1 | 0
Parent topic: General Syntax and Library List


DISPLAY_REG_*

The routines named DISPLAY_REG_* parallel the routines named REG_*. These routines allow you to access and work with the Windows registry. For more information, see the topic Routines to Handle Dynamic Memory in this Appendix.

Parent topic: General Syntax and Library List


Dynamic Memory Routines

The next six routines, and the C$MEMCPY routine, allow you to create and manage dynamically allocated memory. This can be useful when you have to manipulate a number of items, but don't know how many items beforehand. Dynamic memory is allocated using the same mechanism that the runtime uses to allocate memory to programs. In the debugger, you can see how much dynamic memory is currently allocated to the program by running the program in the debugger. To display all memory allocated to the program select the Memory Usage menu item from the File menu (or press U on the keyboard). The amount of dynamic memory is the number that appears in the fifth position of the value displayed (see Debugger Commands in ACUCOBOL-GT User's Guide).

  • M$ALLOC (Dynamic Memory Routine)
    Allocates a new area of dynamic memory.
  • M$COPY (Dynamic Memory Routine)
    Copies a region of memory from one location to another.
  • M$FILL (Dynamic Memory Routine)
    Sets a region of memory to a constant value.
  • M$FREE (Dynamic Memory Routine)
    Frees a previously allocated piece of memory.
  • M$GET (Dynamic Memory Routine)
    Retrieves data from an allocated memory block.
  • M$PUT (Dynamic Memory Routine)
    Stores data in an allocated memory block.
Parent topic: General Syntax and Library List


M$ALLOC (Dynamic Memory Routine)

Allocates a new area of dynamic memory.

Usage

CALL "M$ALLOC"
    USING ITEM-SIZE, MEM-ADDRESS

Parameters

ITEM-SIZE Numeric parameter | This indicates the number of bytes to allocate. This must be greater than zero.
MEM-ADDRESS USAGE POINTER | This holds the return value, either the address of the allocated memory or NULL if the allocation fails.

Comments

The maximum amount of memory you may allocate in one call depends on the host machine, but is at least 65260 bytes for all machines (providing that much memory is available). M$ALLOC adds some overhead to each memory block allocated. This ranges between 4 and 16 bytes depending on the machine architecture. Also, each operating system will typically add its own overhead. The debugger's U command reports the amount of memory you have currently allocated via M$ALLOC. The overhead added by M$ALLOC is included in the total shown, but the operating system's overhead is not. Memory allocated by M$ALLOC is initialized to binary zeros (LOW VALUES).

If you try to allocate more memory than the environment can give you, M$ALLOC will return NULL, and no memory will be allocated.

Parent topic: Dynamic Memory Routines
Related information
M$COPY (Dynamic Memory Routine)
M$FILL (Dynamic Memory Routine)
M$FREE (Dynamic Memory Routine)
M$GET (Dynamic Memory Routine)
M$PUT (Dynamic Memory Routine)


M$COPY (Dynamic Memory Routine)

Copies a region of memory from one location to another.

Usage

CALL "M$COPY"
    USING DEST-PTR, SRC-PTR, NUM-BYTES

Parameters

DEST-PTR USAGE POINTER | Contains the address of the first byte of the destination region.
SRC-PTR USAGE POINTER | Contains the address of the first byte of the source region.
NUM-BYTES Numeric parameter | Indicates the size of the memory region to be copied.

Description

This routine copies NUM-BYTES from the address contained in SRC-PTR to the address contained in DEST-PTR. Note that this routine is relatively dangerous to use. No boundary checking is performed to ensure that the address range is valid, so memory access violations may result if you pass it incorrect data.

This routine is functionally similar to the C$MEMCOPY routine except that parameters are passed by reference instead of by value. For example, you can copy 10 bytes to DEST-PTR from the memory address contained in SRC-PTR with:

     CALL "M$COPY"
        USING DEST-PTR, SRC-PTR, 10
Parent topic: Dynamic Memory Routines
Related information
M$ALLOC (Dynamic Memory Routine)
M$FILL (Dynamic Memory Routine)
M$FREE (Dynamic Memory Routine)
M$GET (Dynamic Memory Routine)
M$PUT (Dynamic Memory Routine)


M$FILL (Dynamic Memory Routine)

Sets a region of memory to a constant value.

Usage

CALL "M$FILL"
    USING DEST-PTR, BYTE-VALUE, NUM-BYTES

Parameters

DEST-PTR USAGE POINTER | Contains the address of the first byte of the region to be filled.
BYTE-VALUE Alpha-numeric parameter | Contains the value with which to fill the memory region.
NUM-BYTES Numeric parameter | Indicates the size of the memory region.

Description

This routine fills NUM-BYTES with BYTE-VALUE starting at address DEST-PTR. The parameters are passed BY REFERENCE. This routine does not do any boundary checking to make sure that the address range is valid.

Parent topic: Dynamic Memory Routines
Related information
M$ALLOC (Dynamic Memory Routine)
M$COPY (Dynamic Memory Routine)
M$FREE (Dynamic Memory Routine)
M$GET (Dynamic Memory Routine)
M$PUT (Dynamic Memory Routine)


M$FREE (Dynamic Memory Routine)

Frees a previously allocated piece of memory.

Usage

CALL "M$FREE"
    USING MEM-ADDRESS

Parameter

MEM-ADDRESS USAGE POINTER Must point to a memory area previously allocated by M$ALLOC.

Comments

Use M$FREE to release a memory block allocated by M$ALLOC. This memory is returned to the pool of memory available for use by the runtime. On most operating systems, this memory is still associated with the runtime's process, so it cannot be used by any other processes. On a few systems, this memory may be made available to the operating system for re-use by other processes.

It is an error to attempt to use a block of memory once it has been freed. It is also an error to free a block of memory more than once or to free a memory address that has never been allocated. Any of these errors can lead to memory access violations. The runtime attempts to detect these errors and avoid them, but it cannot detect all such errors.

Parent topic: Dynamic Memory Routines
Related information
M$ALLOC (Dynamic Memory Routine)
M$COPY (Dynamic Memory Routine)
M$FILL (Dynamic Memory Routine)
M$GET (Dynamic Memory Routine)
M$PUT (Dynamic Memory Routine)


M$GET (Dynamic Memory Routine)

Retrieves data from an allocated memory block.

Usage

CALL "M$GET"
    USING MEM-ADDRESS, DATA-ITEM, DATA-SIZE, DATA-OFFSET

Parameters

MEM-ADDRESS USAGE POINTER | Must point to a memory area previously allocated by M$ALLOC.
DATA-ITEM Any data item | Data from the memory block will be stored in this item.
DATA-SIZE Numeric parameter (optional) | The number of bytes to move from the memory block. If omitted, then the number of bytes is set to the size of the memory block (excluding overhead bytes).
DATA-OFFSET Numeric parameter (optional) | The location within the memory block from which to start the move. The first location is position 1. If omitted, this value defaults to 1.

Description

This routine retrieves data from the memory block at MEM-ADDRESS and stores it in DATA-ITEM. Regardless of the value of DATA-SIZE, no bytes are copied from past the end of the memory block. Note that the size of DATA-ITEM is not checked.

Parent topic: Dynamic Memory Routines
Related information
M$ALLOC (Dynamic Memory Routine)
M$COPY (Dynamic Memory Routine)
M$FILL (Dynamic Memory Routine)
M$FREE (Dynamic Memory Routine)
M$PUT (Dynamic Memory Routine)


M$PUT (Dynamic Memory Routine)

Stores data in an allocated memory block.

Usage

CALL "M$PUT"
    USING MEM-ADDRESS, DATA-ITEM, DATA-SIZE, DATA-OFFSET

Parameters

MEM-ADDRESS USAGE POINTER | Must point to a memory area previously allocated by M$ALLOC.
DATA-ITEM Any data item | This is the data that will be stored in the memory block.
DATA-SIZE Numeric parameter (optional) | The number of bytes to move to the memory block. If omitted, then the number of bytes is set to the size of the memory block (excluding overhead bytes).
DATA-OFFSET PIC 9(n), USAGE DISPLAY or COMP-4 (optional) | The location within the memory block from which to start the move. The first location is position 1. If omitted, this value defaults to 1.

Description

This routine copies DATA-ITEM into the memory pointed to by MEM-ADDRESS for DATA-SIZE bytes. Regardless of the value of DATA-SIZE, no bytes are copied that exceed the size of the memory block at MEM-ADDRESS.

Parent topic: Dynamic Memory Routines
Related information
M$ALLOC (Dynamic Memory Routine)
M$COPY (Dynamic Memory Routine)
M$FILL (Dynamic Memory Routine)
M$FREE (Dynamic Memory Routine)
M$GET (Dynamic Memory Routine)


Error and Exit Procedures

The error and exit procedure facilities allow you to cause one or more error or exit procedures to be called automatically when a program generates a particular type of error or terminates normally. Support of error and exit procedures in ACUCOBOL-GT helps facilitate the porting of Micro Focus COBOL applications containing this feature to ACUCOBOL-GT.

You can specify one or more error procedures to be called automatically when a run unit terminates normally or generates any of certain runtime errors. See the CBL_ERROR_PROC Routine in this appendix for details.

You can specify one or more exit procedures to be called automatically when a run unit terminates normally. See the CBL_EXIT_PROC Routine in this appendix for details.

An exit procedure can retrieve information about the termination that induced it with the CBL_GET_EXIT_INFO routine. See the entry in this appendix for details.

The error and exit procedures discussed in this appendix are:

  • CBL_ERROR_PROC
  • CBL_EXIT_PROC
  • CBL_GET_EXIT_INFO
Parent topic: General Syntax and Library List


HEX2ASCII

HEX2ASCII converts hexadecimal data from the non-displayable hexadecimal format to its ASCII equivalent. This routine is the inverse of the ASCII2HEX routine.

Usage

CALL "HEX2ASCII"
    USING ASCII-VALUE, HEX-VALUE

Parameters

ASCII-VALUE PIC X(2) | The ASCII representation of a unit of data.
HEX-VALUE PIC X(4) | The hexadecimal value.

When you are defining the parameters, use the exact field sizes specified in the calling conventions above, otherwise the runtime may terminate abnormally.

Any characters that are not valid hexadecimal digits are treated as the digit 0. Trailing spaces are removed from the input value before conversion.

Parent topic: General Syntax and Library List


I$IO

The I$IO routine provides an interface to the file handler.

An operation code and some number of additional parameters (depending on the operation called) are passed to the routine. The return code is set automatically after the call. The external variable F-ERRNO is set according to any errors found. F-ERRNO may not be reset on entry to I$IO, and should be checked only if I$IO returns an error condition.

Usage

CALL "I$IO"
    USING OP-CODE, parameters

Parameters

  • OP-CODE Numeric parameter

    Specifies the file handling routine to be performed. This table shows which operation corresponds to each operation code. The operations are detailed in the description below:

    Code | Operation
    1 | OPEN-FUNCTION
    2 | CLOSE-FUNCTION
    3 | MAKE-FUNCTION
    4 | INFO-FUNCTION
    5 | READ-FUNCTION
    6 | NEXT-FUNCTION
    7 | PREVIOUS-FUNCTION
    8 | START-FUNCTION
    9 | WRITE-FUNCTION
    10 | REWRITE-FUNCTION
    11 | DELETE-FUNCTION
    12 | UNLOCK-FUNCTION
    13 | REMOVE-FUNCTION
    14 | SYNC-FUNCTION
    15 | EXECUTE-FUNCTION
    16 | BEGIN-FUNCTION
    17 | COMMIT-FUNCTION
    18 | ROLLBACK-FUNCTION
    19 | RECOVER-FUNCTION
    21 | IN-TRANSACTION-FUNCTION
  • parameters vary depending on the op-code chosen

    The remaining parameters vary depending on the operation selected. They provide information and hold results for the operations specified. All parameters are passed by reference. Parameters may be omitted from those operations that do not require them. These parameters are detailed in the Description below.

Description

All parameters passed to I$IO are passed by reference. This applies even to parameters that are integer values in the corresponding file handling routines. All numeric parameters should be passed to I$IO as SIGNED-SHORT values. The I$IO routine provides any necessary addressing conversions. Note that a parameter must be in the correct format for its type. Parameters that are PIC X must be terminated by a LOW-VALUES character.

Except for the MAKE function, I$IO will automatically terminate any PIC X parameters with a LOW-VALUES byte for you. Also, you do not have to specify SYNC for level 01 or level 77 parameters because they are automatically synchronized by ACUCOBOL-GT.

The file filesys.def is a COBOL COPY file that contains many useful definitions for use with I$IO. It contains definitions for the I$IO codes along with the F-ERRNO error values and many useful pre-declared variables that are of the proper type and usage.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

Note: The runtime configuration variable FILE_PREFIX is ignored by the I$IO routine.
  • OPEN-FUNCTION (op-code 1)
  • CLOSE-FUNCTION (op-code 2)
  • MAKE-FUNCTION (op-code 3)
  • INFO-FUNCTION (op-code 4)
  • READ-FUNCTION (op-code 5)
  • NEXT-FUNCTION (op-code 6)
  • PREVIOUS-FUNCTION (op-code 7)
  • START-FUNCTION (op-code 8)
  • WRITE-FUNCTION (op-code 9)
  • REWRITE-FUNCTION (op-code 10)
  • DELETE-FUNCTION (op-code 11)
  • UNLOCK-FUNCTION (op-code 12)
  • REMOVE-FUNCTION (op-code 13)
  • SYNC-FUNCTION (op-code 14)
  • EXECUTE-FUNCTION (op-code 15)
  • BEGIN-FUNCTION (op-code 16)
  • COMMIT-FUNCTION (op-code 17)
  • ROLLBACK-FUNCTION (op-code 18)
  • RECOVER-FUNCTION (op-code 19)
  • IN-TRANSACTION-FUNCTION (op-code 21)
Parent topic: General Syntax and Library List


OPEN-FUNCTION (op-code 1)

This routine opens an existing indexed file. If it is successful, the value in RETURN-CODE should be moved to a data item that is USAGE POINTER. This data item is passed as the open file handle to the other file handling routines. If it fails, RETURN-CODE is set to a NULL value. After the file is opened, the primary key is set as the current key of reference and is positioned at the beginning of the file.

The OPEN routine has three parameters, name, mode and l_parms.

  • Name

    is the name of the file to open. It must be null-terminated.

  • Mode

    is one of the following values (defined in filesys.def):

    Finput | open for input only
    Foutput | open for output only
    Fio | open for input and output
    Fextend | same as Foutput

    This routine only opens already existing files. If the file does not exist, the routine fails, even when opening with mode Foutput.

    Foutput does not delete the current file (this is different from the OPEN OUTPUT verb in COBOL).

    Mode may furthermore have one of the following flags added to it to indicate file locking options (defined in filesys.def):

    Fread_lock | locks file against other updaters
    Fwrite_lock | locks file against all others
    Fmass_update | same as Fwrite_lock
    Ftrans | extended locking rules for transaction management

    Some file systems cannot support the Fread_lock option correctly. For these systems, the setting of the external variable F_UPGRADE_RLOCK determines what happens. If this variable is set to the default, then the Fread_lock setting is treated as a normal open (no file locking). If this variable is non-zero, then the Fread_lock setting is treated as Fwrite_lock instead.

    A few file systems do not support any form of file locking. If locking is requested on one of these file systems, the open proceeds as if file locking were not specified, but the external variable F-ERRNO is set to W_NO_SUPPORT. This is also returned for file systems that cannot support multiple record locks when Fmulti_lock is specified.

    If Fmass_update is used, then the file system is also requested to emphasize speed of updates over file security.

    Additionally, Fmulti_lock may be also added to mode to request that more than one record lock be maintained in the file by this process. If this option is not specified, then any I/O operation on the file will first release any currently locked record. This results in only one record lock being set in the file at any time. When this option is used, locked records are released only when the file is closed or when the UNLOCK routine is called.

  • L_parms

    points to a null-terminated string that describes the key structure for the file. The l_parms parameter is the same as the l_parms parameter passed when using the MAKE op-code. This parameter is a string that contains three comma-separated numbers. These values are (in order):

    1 | the maximum record size
    2 | the minimum record size
    3 | the number of keys for the file.

    If the maximum record size does not match the minimum record size, then variable sized records are implied. This parameter is not used by all file systems, but is supplied for those file systems that cannot determine these values on their own.

    Note: The l_parms parameter is always required, but it is ignored by the default file systems shipped with ACUCOBOL-GT (RMS for VAX/VMS machines and Vision for all others). It is required by other file systems, however, including Btrieve and C-ISAM. If you ever intend on using any of these file systems, you should ensure that the values passed in l_params are correct.
Parent topic: I$IO


CLOSE-FUNCTION (op-code 2)

This routine closes an open file. It also removes currently held locks on the file. The CLOSE routine has only one parameter, f, a file handle returned by OPEN. For some file systems, it is possible that CLOSE will write additional records that had been previously buffered by the system. For this reason, it is possible that a disk full condition can occur.

Parent topic: I$IO


MAKE-FUNCTION (op-code 3)

This routine is used to create a new indexed file. It will overwrite any existing file. This routine will not overwrite a file that is currently in use. If the file is in use, the error E_FILE_LOCKED will be returned. The MAKE routine has six parameters, name, comment, p_parms, l_parms, keys, and trans.

This routine does not automatically terminate its parameters with LOW-VALUES, you must insure that the parameters are correctly terminated yourself. If you do not wish to supply an alternate collating sequence in the trans parameter to MAKE, then simply omit the parameter. The I$IO routine does not allow you to specify a NULL parameter which is what is expected by the MAKE routine. Instead, by omitting the parameter, the I$IO routine will construct a NULL parameter for you.

The host file system may ignore any or all of the values specified by comment, p_parms and trans. If the host system cannot perform the requested operation, it is ignored (however, if the trans value is ignored, F-ERRNO is set to W_NO_SUPPORT). If the host system cannot support one of the values specified in l_parms or keys, then MAKE fails and RETURN-CODE is set to the error condition E_NO_SUPPORT. If any of the parameters are ill-formed or contain values outside of the legal range of values, E_PARAM_ERR is returned.

Name | points to the name of the file. This must be null-terminated.
Comment | may be NULL or may point to comment string that describes the file. This comment is stored in the file, but has no other functional use. The comment may be up to 30 characters long and must be null-terminated. Many host file systems cannot store comments. On these systems, this parameter is ignored.
P_parms points to a string that describes various physical characteristics of the file. This string consists of five numeric fields separated by commas and must be null-terminated. Each of these fields advises the file system of desired treatment for the physical storage of the file. Individual file systems may ignore some or all of these fields. Furthermore, p_parms may be NULL to imply 0 for each of the fields.

The filesys.def COPY file has a data item containing these fields.

The fields are as follows:

  1. Blocking factor. This value is the number of disk sectors to store in a single file block. It may be zero to request the default blocking factor for the file system.
  2. Pre-allocate amount. This is the number of file blocks (the size of which depends on the blocking factor above) to initially allocate to the file. The purpose of this is to allocate contiguous disk space for the file. It does not limit the file's total size. This value may be zero to request the default initial allocation amount.
  3. Extension factor. This is the number of file blocks to add to the file when it needs to grow. The purpose of this is to help reduce disk fragmentation. This value may be set to zero to request the default extension amount.
  4. Compression factor. This is a value between zero and 100. It represents the amount of file compression desired. A value of zero indicates no compression and a value of 100 indicates maximum compression. Values in between indicate varying degrees of compression. The exact meaning of this depends on the host file system.
  5. Encryption flag. If this value is 1, then encryption is desired for the disk file. If it is zero, then no encryption is desired. The results of encryption depend on the host file system. Since no key is supplied, the results of encryption are usually only moderately secure.
l_parms points to a string that describes various logical characteristics of the file. The string consists of three numeric fields separated by commas. The string must be null-terminated.

The filesys.def COPY file has a data item containing these fields.

The fields are as follows:

  1. Maximum record size. This is the size of the largest record to be placed in the file. For Vision 5 and Vision 6 files, this may range from 1 to 67,108,864. For Vision 3 and 4 files, this may range from 1 to 32,767.
  2. Minimum record size. This is the size of the smallest record to be placed in the file. This may range from 1 to the maximum record size. If this field is the same as the maximum record size, then fixed-length records are implied.
  3. Number of keys. This is the number of keys in the file, including the primary key. This may range from 1 to MAX_KEYS.
keys points to a null-terminated string that describes the key structure for the file. keys is a string of numbers separated by commas. The first key described is the primary key. It may not allow duplicate values. The primary key is called key 0. The next key described is key 1 and so on. There should be as many keys described as the "number of keys" field of l_parms indicates.

The filesys.def COPY file has a data item containing these fields.

Each key description contains the following information:

  1. Number of segments. This is the number of segments in this key. A segment is a contiguous region of bytes in the record. You may describe a split key by specifying more than one segment. With Vision Version 3 files, this may range from 1 to V3_MAX_SEGS. With Vision Version 4, 5, or 6 files, this may range from 1 to MAX_SEGS.
  2. Duplicates flag. If this value is 1, then duplicate keys are allowed. If 0, then duplicate values are not allowed. This must be 0 for the primary key.
  3. Segment size. This is the number of bytes in the first segment. This may be between 1 and MAX_KEY_SIZE.
  4. Segment offset. This is the offset from the beginning of the record to the first byte of the segment. A segment that starts at the beginning of the record has an offset of 0.
  5. Remaining segments. The segment size and segment offset fields are repeated for each additional segment in the key. The sum of the segment sizes may not exceed MAX_KEY_SIZE.

For example, a file with two keys, the first one having two segments (offset zero, length 10 and offset 50, length 5) and the second one with one segment (offset 20, length 15) and allowing duplicates would be written:

2,0,10,0,5,50,1,1,15,20
trans | This parameter specifies an alternate collating sequence for the keys. If this parameter is NULL, then keys are ordered in ascending sequence based on their native unsigned value. If trans is not NULL, it must point to a 256 byte region of memory. Unlike other strings, this need not be null-terminated and is likely to contain nulls within it. This 256 byte region is used as a translation table on the bytes of each key to arrive at a new key-ordering. Each byte is used as an index into this table, and the resulting value is used to order the keys. Some host file systems cannot do key translations. On these systems, this parameter is ignored.
Parent topic: I$IO


INFO-FUNCTION (op-code 4)

This routine returns a variety of information about the open indexed file f, depending on the value of mode. The information is returned in the area pointed to by result. Most of the modes return one or more numeric values. These values are represented in result as fixed size fields with the numbers represented as strings. When more than one value is returned in result, the values are separated by commas.

The filesys.def COPY file contains layouts for each kind of information that can be retrieved with this routine.

The INFO routine has three parameters, f, mode, and result.

  • F

    is a file handle returned by OPEN.

  • Mode

    determines what result is returned with a series of comma-separated numbers that define the format of result. (Note that in the following descriptions, the first value is number 1, the second is number 2 and so on. The number of times the field number is repeated represents the size of the field. For example 111,22 indicates that two values are returned, the first one is three digits long and the second one is two digits long.)

    When a particular mode cannot be determined by the file system, then the error value E_NO_SUPPORT is set. If a particular value of mode -1 or mode -2 cannot be determined, it is set to zero.

    The following modes are supported:

    -1 | This returns the same information as the l_parms parameter of the MAKE function. Result is in the format of 11111,22222,333 where:
    -2 | Returns the same information as the p_parms parameter of the MAKE function. Result is in the format of where:
    -3 | Returns the comment specified to the MAKE function that made the file. The format is a null-terminated string of up to thirty characters.
    -4 | Returns the number of records in the file. This is returned as a 10-digit number.
    -5 | Returns the 256-byte key translation table specified to MAKE when the file was originally made. If no key translation table was specified, then the E_NO_SUPPORT error is set. In this case, this should be simply taken to mean that the native key ordering was used.
    -6 | Returns the number of currently locked records for the file handle passed to I$IO.
    -7 For Vision Version 4, 5 and 6 files, returns the number of data and index segments in the form: 11111,22222 where:

    For Vision Version 3 files, this mode always returns 00000,00000.

    -8 Returns the name and size of a Vision Version 4, 5, or 6 file segment.

    This mode is different from the other modes in that it uses the third argument as both INPUT and OUTPUT. Set FS-TYPE to FS-DATA (255) or FS-INDEX (254) and FILE-SEGMENT-NUMBER to the number of the segment you want information about. Upon return, name will contain the filename of the segment and FS-SIZE will contain the size of the segment. The FILE-SEGMENT-INFO data item in filesys.def describes this structure.

    This operation can be called with a Vision Version 3 file, also. In this case, type is ignored, but seg must be 1. The name and size returned will be those of the single Version 3 file.

    -9 | Returns the sum of the sizes of all the segments that make up a Vision Version 4, 5, or 6 file. The return value is 15 digits long. If called with a Vision Version 3 file, this operation returns the size of the single Version 3 file.
    -10 | Returns the version number of the Vision file in a three character string. For example, if the file is Vision Version 6, 006 is returned.
    0+ A mode of zero or greater indicates that information about a particular key is desired. That key information is returned as 11,2,333,44444 where:

    The third and fourth fields are repeated for each additional segment in the key.

Note: Versions of INFO prior to the version used by the 3.2 runtime returned only one digit for the number of segments in the key.
Parent topic: I$IO


READ-FUNCTION (op-code 5)

This routine reads a record out of an indexed file. The READ routine has three parameters, f, record, and keynum.

F | must be a valid file handle returned by OPEN.
Record | points to the area to hold the record read.
Keynum is the key number to read from. Key 0 is the primary key, key 1 is the first alternate and so on. The bytes in record corresponding to the key keynum must contain the key value of the record to be read. If this routine succeeds, RETURN-CODE is set to the size of the record read. RETURN-CODE is set to zero on failure.

Records read by a file open for input only are not locked. Furthermore, most file systems do not block the reading of locked records by a file open for input (Note that this feature depends on the host file system - not all can support it). Records read from a file open for I/O are automatically locked unless the external variable f-no-lock is set to a non-zero value first in which case they are treated in the same manner as files open for input.

If the key keynum allows duplicates and the next record in the file contains the same key value as the record read, the variable F-ERRNO is set to W-DUP-OK. This feature is not supported by many host file systems.

A successful READ causes the current key of reference to be set to keynum and the file position is set to the record read. This is used by the NEXT and PREVIOUS routines. If READ is unsuccessful, then the current key of reference is set to an undefined state.

Parent topic: I$IO


NEXT-FUNCTION (op-code 6)

This routine reads the next record in the sequence of records specified by the current key of reference. When a file is first opened, its key of reference is the primary key and the file is positioned so that the NEXT record is the first record in the file. The READ and START routines can change the current key of reference. The NEXT routine has two parameters, f, and record. F must be a valid file handle returned by OPEN. Record points to the area to hold the record read.

If this routine succeeds, RETURN-CODE is set to the size of the record read. If it fails, RETURN-CODE is set to zero and sets the current key of reference to the "undefined" state. However, if it fails due to the record being locked, the current key of reference is unchanged and the file pointer is set to the locked record (some file systems do not support this rule). Also, if it fails because it reached the end of the file, then the current key of reference is left unchanged and the file pointer is positioned so that a call to PREVIOUS returns the last record in the file.

The NEXT routine follows the same record locking rules as the READ routine.

If the record following the one read contains the same key value (in the current key of reference), then F-ERRNO is set to W-DUP-OK.

Parent topic: I$IO


PREVIOUS-FUNCTION (op-code 7)

This routine behaves just like the NEXT routine with two exceptions. The first is that RETURN-CODE is set to the preceding record in the file instead of the next one. The second is that it never sets the W_DUP_OK error value. The PREVIOUS routine has two parameters, f, and record. F must be a valid file handle returned by OPEN. Record points to the area to hold the record read.

Some file systems do not support the ability to read a file backwards. For these systems, this routine sets the error value E_NO_SUPPORT.

This routine treats the beginning of the file in a manner that is analogous to the way NEXT treats the end of the file. If an PREVIOUS call reaches the beginning of the file, a call to NEXT returns the first record of the file.

Parent topic: I$IO


START-FUNCTION (op-code 8)

This routine selects the current key of reference and positions the file pointer for the next NEXT or PREVIOUS routine. The START routine has five parameters, f, record, keynum, keysize and mode.

  • F

    must be a valid file handle returned by OPEN.

  • Record

    points to the area to hold the record read.

  • Keynum

    selects which key to use. The corresponding key area in record must contain the key value that will be used to position the file.

  • Keysize

    indicates the size of the key. If keysize is zero, the entire key is used. Otherwise, only the first keysize bytes of the key will be used.

  • Mode

    selects how the file is to be positioned with respect to the key value defined in record. It can be one of the following values:

    F_EQUALS | The file is positioned at the record that matches the key value
    F_NOT_LESS | The file is positioned at the record that matches the key value, or the next greater one if no one matches
    F_GREATER | The file is positioned at the first record greater than the key value specified
    F_LESS | The file is positioned at the last record smaller than the key value specified
    F_NOT_GREATER | The file is positioned at the record that matches the key value, or the last record smaller than the key value if no one matches

The F_EQUALS mode is usually used to test for the existence of a record or to position a file when the key value is known. The F_NOT_LESS and F_GREATER modes are used to position the file for a series of NEXT calls and the F_LESS and F_NOT_GREATER modes are used to prepare for a series of PREVIOUS calls.

After a successful START, the current key of reference will set to keynum. The next NEXT or PREVIOUS call will return the record selected by the START routine. Note that in this case, NEXT and PREVIOUS both return the same record.

If the START routine fails, then the current key of reference is placed in the "undefined" state.

Some file systems cannot perform the F_LESS or F_NOT_GREATER modes. On these file systems, specifying these modes causes START to return an error and set the E_NO_SUPPORT condition.

Parent topic: I$IO


WRITE-FUNCTION (op-code 9)

This routine adds a new record to the passed file. The WRITE routine has three parameters, f, record, and size.

F | must be a valid file handle returned by OPEN.
Record | points to the record to add.
Size | is the size of the record. If size is zero, then the maximum record size for the file is used.

If the file has keys that allow duplicate values, and one or more of those keys in record match keys that already exist in the file, then F-ERRNO is set to W-DUP-OK. Several file systems cannot detect this condition and in this case, F-ERRNO is set to zero instead.

For keys that allow duplicates, the new record is added such that its keys are placed at the end of the sequence of those keys with the same value. Many file systems do not support this rule, in which case the ordering is defined by the file system.

The WRITE routine does not change the current file position or affect the current key of reference.

Parent topic: I$IO


REWRITE-FUNCTION (op-code 10)

This routine replaces an existing record in the file. The REWRITE routine has three parameters, f, record, and size.

F | must be a valid file handle returned by OPEN.
Record | points to the new record to place in the file.
Size | may be zero to indicate the maximum record size for the file. The record replaced is specified by the primary key value found in record. The size of the new record need not match the size of the existing record.

For keys that are unchanged between the new record and the old record, the ordering of those keys is unchanged. For keys that have changed, the new keys are placed at the end of the sequence of keys that have the same value. If any of the changed keys match keys that already exist in the file (and these keys allow duplicates), then F-ERRNO is set to W-DUP-OK. Note that these rules depend on the host system and may be different for some file systems.

The REWRITE routine does not affect the file position or the current key of reference.

Parent topic: I$IO


DELETE-FUNCTION (op-code 11)

This routine deletes the record identified by the value found in the primary key area of record. It does not affect the current file position or key of reference. The DELETE routine has two parameters, f, and record. F must be a valid file handle returned by OPEN. Record points to the area to hold the record read.

Parent topic: I$IO


UNLOCK-FUNCTION (op-code 12)

This routine unlocks any locked records held by the current process in the passed file. It is not an error to call this routine when there are no locked records. This routine does not affect the current file position or key of reference. This routine will not unlock any records if it is called during a transaction. "Commit" (see below) should be used instead. The "unlock" routine has only one parameter, f. F must be a valid file handle returned by OPEN.

Parent topic: I$IO


REMOVE-FUNCTION (op-code 13)

This routine should remove from disk the indexed file indicated by name. This routine is specialized for indexed files because some host systems implement indexed files in more than one physical file. This routine should be called only when the file to be removed is closed. It has only one parameter, name. Name points to the name of the file. It must be NULL terminated.

Parent topic: I$IO


SYNC-FUNCTION (op-code 14)

This routine causes all file buffers to be flushed to disk. The SYNC routine has only one parameter, all_files, which is a bit field. If

(all_files & FA-MASS-UPDATE)

is non-zero, then MASS-UPDATE files should be synced. If

(all_files & FA-REMOTE)

is non-zero, then remote files should be synced.

The constants FA-MASS-UPDATE and FA-REMOTE are defined in filesys.def.

The exact effect of this routine depends on the host file system. It is entirely possible that this routine will do nothing under a particular system. Because of the highly host-dependent nature of this routine, no error reporting is done.

Parent topic: I$IO


EXECUTE-FUNCTION (op-code 15)

This routine executes a file-system specific command. The EXECUTE routine has two parameters, system, and command.

System | points to the name of the file system (e.g. "vision", "btrieve", etc.).
Command | contains a command to be executed by that file system. The list of available commands is completely file-system specific. Many file systems do not have any commands that can be executed in this manner. The routine returns 0 if successful, otherwise, RETURN-CODE is set to a file-system specific error value. For file systems that do not support any commands, -1 is always returned.
Note: Different file systems process this routine differently. For example, the interface for Microsoft SQL Server has some unique parameters. See the documentation for the specific file system interface for exceptions to this operation.
Parent topic: I$IO


BEGIN-FUNCTION (op-code 16)

The BEGIN routine initiates a transaction. On indexed file systems this usually opens the log file for appending the first time it is called (if the log file doesn't exist, it is created). This routine has no parameters.

Parent topic: I$IO


COMMIT-FUNCTION (op-code 17)

This routine commits all changes and releases all locks. It also ends a transaction. This routine has no parameters.

Parent topic: I$IO


ROLLBACK-FUNCTION (op-code 18)

This routine rolls back all files affected to the state that they were in after the last completed transaction. This routine has no parameters.

Parent topic: I$IO


RECOVER-FUNCTION (op-code 19)

This routine rolls forward all files affected to the state that they were in after the last completed transaction. This routine has no parameters.

Parent topic: I$IO


IN-TRANSACTION-FUNCTION (op-code 21)

This routine returns a value indicating whether or not the program is currently in an unfinished transaction. The return value is 1 if there is current and unfinished transaction, 0 otherwise. This routine has no parameters.

Example

The following program opens a file, determines the number of records in the file, and then reads each of those records, printing out the size of each record found.

This example makes heavy use of variables found in filesys.def.

IDENTIFICATION DIVISION.
PROGRAM-ID.  EXAMPLE.

DATA DIVISION.

WORKING-STORAGE SECTION.

* Assume that we already know the maximum record size, minimum
* record size and the number of keys in the file.

78 MAX-SIZE    VALUE 1000.
78 MIN-SIZE    VALUE 100.
78 KEY-COUNT   VALUE 1.

COPY "filesys.def".

77  FILE-HANDLE               USAGE POINTER.
01  RECORD-AREA.
    03 OCCURS MAX-SIZE TIMES  PIC X.

PROCEDURE DIVISION.
MAIN-LOGIC.
* Open the file
    SET OPEN-FUNCTION TO TRUE.
    MOVE MAX-SIZE TO MAX-REC-SIZE.
    MOVE MIN-SIZE TO MIN-REC-SIZE.
    MOVE KEY-COUNT TO NUM-KEYS.
    MOVE Finput TO OPEN-MODE.
    CALL "I$IO" USING IO-FUNCTION, "MYFILE", OPEN-MODE,
                LOGICAL-INFO.
    IF RETURN-CODE = ZERO
        DISPLAY "Could not open file, error code = ", F-ERRNO,
                CONVERT
        STOP RUN.
    MOVE RETURN-CODE TO FILE-HANDLE.
* Now get the record count
    SET INFO-FUNCTION TO TRUE.
    SET GET-RECORD-COUNT TO TRUE.
    CALL "I$IO" USING IO-FUNCTION, FILE-HANDLE, INFO-MODE,
                RECORD-COUNT-INFO.
    IF E-NO-SUPPORT
        DISPLAY "File system cannot determine record count"
        PERFORM CLOSE-FILE
        STOP RUN.
* Read each record
    SET NEXT-FUNCTION TO TRUE
    PERFORM NUMBER-OF-RECORDS TIMES
        CALL "I$IO" USING IO-FUNCTION, FILE-HANDLE, RECORD-AREA
        IF RETURN-CODE = ZERO
        DISPLAY "Error reading record, code = ", F-ERRNO,
                 CONVERT
        PERFORM CLOSE-FILE
        STOP RUN
        ELSE
        DISPLAY "Record size = ", RETURN-CODE, CONVERT, LEFT
        END-IF
    END-PERFORM.
* All done
    PERFORM CLOSE-FILE.
    STOP RUN.

CLOSE-FILE.
    SET CLOSE-FUNCTION TO TRUE.
    CALL "I$IO" USING IO-FUNCTION, FILE-HANDLE.
Parent topic: I$IO


LIB$GET_SYMBOL

The LIB$GET_SYMBOL routine retrieves a symbol's current value. This routine is VMS-specific and should never be used on other machines.

Usage

CALL "LIB$GET_SYMBOL"
    USING SYM-NAME, SYM-VALUE, SYM-SIZE, SYM-LOCATION

Parameters

SYM-NAME PIC X(n) | Contains the name of the symbol to retrieve. The local symbol table is searched first, followed by the global table.
SYM-VALUE PIC X(n) | If a value is found, it is returned in the second parameter.
SYM-SIZE PIC 9(n) USAGE COMP-1 (optional) | The third parameter is optional. It is filled in with the number of characters contained in the returned value.
SYM-LOCATION PIC X or PIC 9 (optional) | The final parameter is also optional. It is filled in with a 1 if the value is found in the local symbol table, a 2 if found in the global table.

This routine does not report any error conditions. See the VMS System Routines manual for details on VMS-specific routines.

Parent topic: General Syntax and Library List


LIB$SET_SYMBOL

This routine sets the value of a symbol belonging to the current command processor. This library routine is VMS-specific and should never be used on other machines.

Usage

CALL "LIB$SET_SYMBOL"
    USING SYM-NAME, SYM-VALUE, SYM-LOCATION

Parameters

SYM-NAME PIC X(n) USAGE DISPLAY | The first parameter is the symbol's name. This name has trailing spaces removed and is converted to upper case.
SYM-VALUE PIC X(n) or PIC 9(n) USAGE DISPLAY | The second parameter is the value to assign to the symbol. This is not converted to upper case, but does have trailing spaces removed.
SYM-LOCATION PIC X or PIC 9 USAGE DISPLAY (optional) | The third parameter is optional. It should be a 1 to set the symbol in the local symbol table. It should be a 2 to use the global symbol table. If this parameter is omitted, the local table is used.

This routine does not report any error conditions. See the VMS System Routines manual for details on VMS-specific routines.

Comments

It is possible to set a symbol's value from ACUCOBOL-GT using the SYSTEM library routine, but when you do this, the symbol's value immediately resets to its previous value as soon as the SYSTEM call is complete. This is because the SYSTEM routine starts another command processor which maintains its own set of symbols.

Parent topic: General Syntax and Library List


OCTAL2ASCII

OCTAL2ASCII converts data presented in octal format to its ASCII equivalent. This routine is the inverse of the ASCII2OCTAL routine.

Usage

CALL "OCTAL2ASCII"
    USING ASCII-VALUE, OCTAL-VALUE

Parameters

ASCII-VALUE PIC X(2) | The ASCII representation of a unit of data.
OCTAL-VALUE PIC X(8) | The octal value.

When you are defining the parameters, use the exact field sizes specified in the calling conventions above, otherwise the runtime may terminate abnormally.

Any characters that are not valid octal digits are treated as the digit 0. Trailing spaces are removed from the input value.

Parent topic: General Syntax and Library List


R$IO

The R$IO routine provides an interface to the relative file handler. Calls to the routine require an operation code and a variable number of parameters, depending on the operation called. The return code is set automatically after the call. The external variable F-ERRNO is set according to any errors found. F-ERRNO may not be reset on entry to R$IO, and should be checked only if R$IO returns an error condition.

Usage

CALL "R$IO"
    USING OP-CODE, PARAMETERS

Parameters

  • OP-CODE Numeric parameter

    Specifies the file handling routine to be performed. The following table lists each op-code and its corresponding operation. The operations are detailed below:

    Code | Operation
    1 | R-OPEN-FUNCTION
    2 | R-CLOSE-FUNCTION
    3 | R-MAKE-FUNCTION
    4 | R-READ-FUNCTION
    5 | R-NEXT-FUNCTION
    6 | R-PREVIOUS-FUNCTION
    7 | R-START-FUNCTION
    8 | R-WRITE-FUNCTION
    9 | R-REWRITE-FUNCTION
    10 | R-DELETE-FUNCTION
    11 | R-UNLOCK-FUNCTION
  • PARAMETERS vary depending on op-code

    The remaining parameters vary depending on the operation selected. They provide information and hold results for the operations specified. Parameters may be omitted from those operations that do not require them. The parameters are detailed below.

Description

All parameters passed to R$IO are passed by reference. This applies even to parameters that are integer values in the corresponding file handling routines.

R$IO automatically terminates PIC X filename parameters with a LOW-VALUES byte.

You do not have to specify SYNC for level 01 or level 77 parameters because they are automatically synchronized by ACUCOBOL-GT.

The filesys.def COPY file contains many useful definitions for use with R$IO. It contains definitions for the R$IO op-codes as well as the F-ERRNO error values. It also includes many useful pre-declared variables that are of the proper type and usage.

Note: The behavior of this routine is affected by the setting of the FILENAME_SPACES configuration variable that may or may not allow spaces in a file name. See the entry for FILENAME_SPACES in Appendix H, for information about the terminating character for path names.

The runtime configuration variables FILE_PREFIX and FILE_SUFFIX are ignored by the R$IO routine.

  • R-OPEN-FUNCTION (op-code 1)
  • R-CLOSE-FUNCTION (op-code 2)
  • R-MAKE-FUNCTION (op-code 3)
  • R-READ-FUNCTION (op-code 4)
  • R-NEXT-FUNCTION (op-code 5)
  • R-PREVIOUS-FUNCTION (op-code 6)
  • R-START-FUNCTION (op-code 7)
  • R-WRITE-FUNCTION (op-code 8)
  • R-REWRITE-FUNCTION (op-code 9)
  • R-DELETE-FUNCTION (op-code 10)
  • R-UNLOCK-FUNCTION (op-code 11)
Parent topic: General Syntax and Library List


R-OPEN-FUNCTION (op-code 1)

This routine opens an existing relative file. If it is successful, the value in RETURN-CODE should be moved to a data item that is USAGE HANDLE. This data item is passed as the open file handle to the other file handling routines. If it fails, RETURN-CODE is set to a NULL value.

The R-OPEN-FUNCTION routine takes four required parameters, and one optional parameter: filename, mode, maxsize, minsize, and blocks.

  • Filename

    is the name of the file to open. It does not need to be null-terminated.

  • Mode

    is one of the following values (defined in filesys.def):

    Finput | open for input only
    Foutput | open for output only
    Fio | open for input and output
    Fextend | open for output only (same as Foutput)

    Foutput does not delete the current file (this behavior differs from the OPEN OUTPUT statement in COBOL).

    This routine only opens files that already exist. If the file does not exist, the routine fails, even when opening with mode Foutput.

    Mode may furthermore have one of the following flags added to it to indicate file locking options (defined in filesys.def):
    Fread_lock | locks file against other updaters
    Fwrite_lock | locks file against all others
    Fmass_update | locks file against all others (same as Fwrite_lock)

    If Fmass_update is used, the file system is directed to emphasize speed of updates over file security.

    Additionally, Fmulti_lock may be added to mode to request that more than one record lock be maintained in the file by this process. If this option is not specified, then any I/O operation on the file will first release any currently locked record. This results in only one record lock being set in the file at any time. When this option is used, locked records are released only when the file is closed or when the UNLOCK routine is called.

  • Maxsize

    is the maximum record size.

  • Minsize

    is the minimum record size. If maxsize is not equal to minsize, the records are considered variable length.

  • Blocks

    is the size of a block in bytes. This parameter is optional and defaults to zero (0), meaning that a block is the size of a record.

Parent topic: R$IO


R-CLOSE-FUNCTION (op-code 2)

This routine closes an open file. It also removes currently held locks on the file. R-CLOSE-FUNCTION has only one parameter, file_handle, the file handle of the file to close. The file handle is a handle returned by the R-OPEN-FUNCTION. For some file systems, it is possible that R-CLOSE-FUNCTION will write additional records that had been previously buffered by the system. For this reason, it is possible that a disk full condition can occur.

Parent topic: R$IO


R-MAKE-FUNCTION (op-code 3)

This routine creates a new relative file. It will overwrite any existing file of the same name. However, it will not overwrite a file that is currently in use. If the file is in use, the error E_FILE_LOCKED is returned.

The R-MAKE-FUNCTION routine has two required parameters and one optional parameter: filename, l_params, blocks.

filename | is the name of the file to create. The name need not be null-terminated.
l_parms is a string that describes logical characteristics of the file. The string consists of two numeric fields separated by a comma. The string must be null-terminated. The fields are as follows:
  1. Maximum record size. This is the size in bytes of the largest record to be placed in the file. This can range from 1 to 67,108,864.
  2. Minimum record size.
blocks | is the size of a block of records in bytes. The default is zero (0).
Parent topic: R$IO


R-READ-FUNCTION (op-code 4)

This routine reads a record out of the relative file. The R-READ-FUNCTION routine has three parameters: file_handle, record_area, and keyval.

file_handle | must be a valid file handle returned by R-OPEN-FUNCTION.
record_area | points to the area to hold the record read. It must be at least MAXSIZE bytes in length.
keyval | is the record number of the record to read. It is a long value.

If R-READ-FUNCTION succeeds, RETURN-CODE is set to the size of the record read, plus one. If it fails, RETURN-CODE is set to zero. However, if the function fails because the record is locked, the file pointer is set to the locked record.

Records read in a file open for input only are not locked. Furthermore, most file systems do not block the reading of locked records in a file open for input (this feature depends on the host file system - not all support it). Records read from a file open for I/O are automatically locked unless the external variable f-no-lock is set to a non-zero value, in which case they are treated in the same manner as files open for input.

Parent topic: R$IO


R-NEXT-FUNCTION (op-code 5)

This routine reads the next record in the sequence of records in a relative file. The R-NEXT-FUNCTION routine has two parameters: file_handle and record_area.

file_handle | must be a valid file handle returned by R-OPEN-FUNCTION.
record_area | points to the area to hold the record read. It must be at least MAXSIZE bytes in length.

If R-NEXT-FUNCTION succeeds, RETURN-CODE is set to the size of the record read, plus one. If it fails, RETURN-CODE is set to zero. However, if the function fails because the record is locked, the file pointer is set to the locked record.

Records read in a file open for input only are not locked. Furthermore, most file systems do not block the reading of locked records in a file open for input (this feature depends on the host file system - not all support it). Records read from a file open for I/O are automatically locked unless the external variable f-no-lock is set to a non-zero value, in which case they are treated in the same manner as files open for input.

Parent topic: R$IO


R-PREVIOUS-FUNCTION (op-code 6)

This routine reads the previous record in the sequence of records in a relative file. The R-PREVIOUS-FUNCTION routine has two parameters: file_handle and record_area.

file_handle | must be a valid file handle returned by R-OPEN-FUNCTION.
record_area | points to the area to hold the record read. It must be at least MAXSIZE bytes in length.

If R-PREVIOUS-FUNCTION succeeds, RETURN-CODE is set to the size of the record read, plus one. If it fails, RETURN-CODE is set to zero. However, if the function fails because the record is locked, the file pointer is set to the locked record.

Records read in a file open for input only are not locked. Furthermore, most file systems do not block the reading of locked records in a file open for input (this feature depends on the host file system - not all support it). Records read from a file open for I/O are automatically locked unless the external variable f-no-lock is set to a non-zero value, in which case they are treated in the same manner as files open for input.

Parent topic: R$IO


R-START-FUNCTION (op-code 7)

This routine positions the file pointer for the next R-NEXT-FUNCTION or R-PREVIOUS-FUNCTION. The R-START-FUNCTION routine has three parameters: file_handle, keyval, and mode.

  • file_handle

    must be a valid file handle returned by R-OPEN-FUNCTION.

  • keyval

    is the record position at which to start. It is a long value.

  • mode

    is a direction. Valid values are as defined in filesys.def. They include:

    F-EQUALS (0) | start at the specified key
    F-NOT-LESS (1) | start at the specified key, or the one after
    F-GREATER (2) | start at the record beyond the specified key
    F-LESS (3) | start at the record before the specified key
    F-NOT-GREATER (4) | start at the specified key, or the one before

The F_EQUALS mode is usually used to test for the existence of a record or to position a file when the key value is known. The F_NOT_LESS and F_GREATER modes are used to position the file for a series of NEXT calls and the F_LESS and F_NOT_GREATER modes are used to prepare for a series of PREVIOUS calls.

After a successful START, the current key of reference is set to keyval. The next READ, NEXT or PREVIOUS call returns the record selected by the START routine. Note that in this case, READ, NEXT and PREVIOUS will all return the same record.

If the START routine fails, the current key of reference is placed in the undefined state.

Some file systems cannot perform the F_LESS or F_NOT_GREATER modes. On these file systems, specifying these modes causes START to return an error and set the E_NO_SUPPORT condition.

Parent topic: R$IO


R-WRITE-FUNCTION (op-code 8)

This routine adds a new record to the file. It has four parameters: file_handle, record, length, and keyval.

file_handle | must be a valid file handle returned by R-OPEN-FUNCTION.
record | is the record data to write to the file.
length | is the number of bytes to write (for variable-length files).
keyval | is the record number to write. A keyval of -1 means to write at the end of the file.

The R-WRITE-FUNCTION routine does not change the current file position.

Parent topic: R$IO


R-REWRITE-FUNCTION (op-code 9)

This routine replaces an existing record in the file. It has four parameters: file_handle, record, length, and keyval.

file_handle | must be a valid file handle returned by R-OPEN-FUNCTION.
record | is the record data to write to the file.
length | is the number of bytes to write (for variable-length files).
keyval | is the record number to write. A keyval of -1 means to write at the end of the file.

The R-REWRITE-FUNCTION routine does not change the current file position.

Parent topic: R$IO


R-DELETE-FUNCTION (op-code 10)

This routine deletes the specified record. It does not affect the current file position. The DELETE routine has two parameters:

file_handle | must be a valid file handle returned by R-OPEN-FUNCTION.
keyval | specifies the position of the record to delete.
Parent topic: R$IO


R-UNLOCK-FUNCTION (op-code 11)

This routine unlocks any locked records held by the current process in the specified file. It is not an error to call this routine when there are no locked records. This routine does not affect the current file position. This routine will not unlock any records if it is called during a transaction. "Commit" should be used instead.

R-UNLOCK-FUNCTION has only one parameter: file_handle. File_handle must be a valid file handle returned by R-OPEN-FUNCTION.

Parent topic: R$IO


RENAME

Renames the existing file. RENAME takes two, three, or four USING parameters.

Usage

CALL "RENAME"
    USING SOURCE-FILE, DEST-FILE, RENAME-STATUS, FILE-TYPE

Parameters

SOURCE-FILE PIC X(n) | Contains the name of the file to rename.
DEST-FILE PIC X(n) | Contains the new name for the file. The RENAME routine will remove the destination file if necessary.
RENAME-STATUS PIC 9(9) COMP-4 | This parameter will be set to ZERO if the routine is successful, otherwise it will be set to the operating system's error number.
FILE-TYPE PIC X | Indicates the file type. If the FILE-TYPE parameter is used, it must specify either an "S" for a sequential file, an "R" for a relative file, or an "I" for an indexed file. If FILE-TYPE is not used, it is assumed to be "S". This can be useful in cases where the file is held in more than one physical disk file (for example, C-ISAM indexed files are physically held in two separate files). If the FILE-TYPE parameter is omitted, then only the single physical file named in SOURCE-FILE is renamed.

Comments

The file being renamed should be closed. Note that the RENAME routine cannot rename a file across different drives under Windows, but it can change a file's directory. Under UNIX systems, the RENAME procedure will attempt to copy the file if the target name is on a different device. This may take some time if the file is large. If the copy is successful, the original file is removed.

Note: The behavior of this library routine is affected by the setting of the FILENAME_SPACES configuration variable that may or may not allow spaces in a file name. See the documentation on FILENAME_SPACES in Appendix H for information about the terminating character for path names.
Parent topic: General Syntax and Library List


RMNet Routines

  • Introduction
  • Function Calls
Parent topic: General Syntax and Library List


Introduction

RMNet is a library of COBOL callable subprograms for exchanging messages with other computers using the Hypertext Transfer Protocol (HTTP). It is possible to construct the messages to be exchanged strictly within the COBOL program, but the recommended solution is to use the Micro Focus XML Extensions product to reliably construct well formed messages.

Before using the RMNet library, it is necessary for your program to call the NetInit subprogram to initialize the library. When your program is finished with the RMNet library, call the NetCleanup subprogram to release the internal resources that RMNet has allocated.
Note: NetCleanup does not free the resources that it has returned to your program. Use the NetFree subprogram to free these resources.

To transmit a request for information to another computer and wait for the response, use the HttpGet subprogram. To transmit a message to another computer and wait for a response message, use the HttpPost subprogram. By HTTP protocol standards, use HttpGet when your program is merely requesting information from the remote machine and HttpPost when updating the data on the other machine. (Note that SOAP defies HTTP conventions and use HttpPost for all requests.)

If an error occurs during the processing of your program's request, use the NetGetError subprogram to retrieve a text interpretation of the error.

Parent topic: RMNet Routines


Function Calls

All the calls except NetCleanup and NetFree return a status-code which, when nonzero, indicates an error with the call. A string representation of the error may be obtained by calling NetGetError; free the error-pointer returned by NetGetError with NetFree.

status-code is a numeric item, at least 3 digits in length.

  • HttpGet
  • HttpGetReturnCode
  • HttpPost
  • HttpSetConnectTimeout
  • HttpSetCookieFile
  • HttpSetEncoding
  • HttpSetResponseHeader
  • HttpSetTimeout
  • NetCleanup
  • NetFree
  • NetGetError
  • NetInit
  • NetSetKeyPassword
  • NetSetProxyServer
  • NetSetSSLCA
  • NetSetSSLCert
  • NetSetSSLKey
  • NetSSLVerifyPeer
Parent topic: RMNet Routines


HttpGet

This function initiates an HTTP GET request and waits for a response. The HTTP GET method is used to request a representation of the specified resource.

Usage

CALL "HttpGet" USING
         destination-url
         response-pointer
         response-length
         [extra-headers]
         GIVING
         status-code.

Syntax

destination-url | An alphanumeric item specifying the target URL for the GET.
response-pointer | A pointer to an alphanumeric item specifying the value of the HTTP response. After use, use NetFree to return memory used to store response.
response-length | A numeric item returning the length of the HTTP response to which reponse-pointer points.
extra-headers | An optional alphanumeric item specifying extra headers to be added to the HTTP header. This argument consists of name/value pairs separated by hex x"00", and ended with two x"00"'s.
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


HttpGetReturnCode

This function is used to return the three-digit HTTP status code from the last HTTP request.

Usage

CALL "HttpGetReturnCode" USING
         http-return-code
         GIVING
         status-code.

Parameters

http-return-code | A three-digit RFC2616 compliant http status code.
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


HttpPost

This function initiates an HTTP POST request and waits for a response. The HTTP POST method is used to submit data to be processed by the identified resource. The data is included in the body of the request.

Usage

CALL "HttpPost" USING
         destination-url
         content-type
         request-pointer
         request-length
         response-pointer
         response-length
         [extra-headers]
         GIVING
         status-code.

Parameters

destination-url | An alphanumeric item specifying the target URL for the POST.
content-type | An alphanumeric item specifying the value of the ContentType HTTP header variable.
request-pointer | A pointer to an alphanumeric item whose value comprises the content of the POST.
request-length | A numeric item specifying the length of the content to which request-pointer points.
response-pointer | A pointer to an alphanumeric item returning the content of the HTTP response. After use, use NetFree to return memory used to store response.
response-length | A numeric item returning the length of the HTTP response to which response-pointer points.
extra-headers | An optional alphanumeric item specifying extra headers to be added to the HTTP header. This argument consists of name/value pairs separated by hex x"00", and ended with two x"00"'s.
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


HttpSetConnectTimeout

This function sets the CURLOPT_CONNECTTIMEOUT option value to the number of seconds specified. This value is the maximum amount of time in seconds that is allowed to make the connection to the server. This value is a portion of the time specified by CURLOPT_TIMEOUT, so this value should be set at less than the value of CURLOPT_TIMEOUT. See the HttpSetTimeout function for more information.

Usage

CALL "HttpSetConnectTimeout” USING
         timeout-in-seconds
         GIVING
         response-status.

Parameters

timeout-in-seconds | A numeric item specifying the maximum amount of time in seconds allowed for a request to complete. When the specified number of seconds expires, then an outstanding request is terminated with an error.
response-status | A status code that, if nonzero, means the request encountered an error. You can get the string representation of the error by calling NetGetError .
Parent topic: Function Calls


HttpSetCookieFile

This function will enable cookies in the current RMNet session and, optionally, can specify the location of a file used to store and retrieve cookies in Mozilla or Netscape cookie format.

Usage

CALL "HttpSetCookieFile" [USING
         cookie-file]
         GIVING
         status-code.

Parameters

cookie-file | An optional alphanumeric item specifying the location of a file used to store and retrieve cookies in Mozilla or Netscape cookie format. You may repeat the call for multiple cookie files. If given a blank or bad cookie-file then the call will merely enable cookies for the current RMNet session.
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


HttpSetEncoding

This function sets the contents of the Accept-Encoding header sent in an HTTP request, and enables decoding of a response when a Content-Encoding header is received. This is a request, not an order; the server may or may not do it.

Usage

CALL "HttpSetEncoding" [USING
         encode-type]
         GIVING
         status-code.

Parameters

encode-type | An optional alphanumeric item specifying the supported HTTP content encoding type. Three encodings are supported: identity, which does nothing, deflate which requests the server to compress its response using the zlib algorithm, and gzip which requests the gzip algorithm. If the encode-type argument is not supplied, then an Accept-Encoding header containing all supported encodings is sent.
source-code | A numeric item that, if nonzero, the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


HttpSetResponseHeader

This function will enable or disable the inclusion of HTTP response headers in the XML response document.

Usage

CALL "HttpSetResponseHeader” USING
         http-header-flag
         GIVING
         status-code.

Parameters

http-header-flag | A numeric item. If this item is set to 1 the HTTP response headers will be included in the XML output. This function must be called again with http-header-flag set to 0 to disable the inclusion of HTTP response headers.
source-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError .
Parent topic: Function Calls


HttpSetTimeout

This function sets the CURLOPT_TIMEOUT option value to the number of seconds specified. This value is the maximum amount of time in seconds that is allowed for the request to complete. The CURLOPT_CONNECTTIMEOUT value is a portion of the time specified by CURLOPT_TIMEOUT, so this value should be set greater than the value of CURLOPT_CONNECTTIMEOUT. See the HttpSetConnectTimeout function for more information.

Usage

CALL "HttpSetTimeout” USING
         timeout-in-seconds
         GIVING
         response-status.

Parameters

timeout-in-seconds | A numeric item specifying the maximum amount of time in seconds allowed for a request to complete. When the specified number of seconds expires, then an outstanding request is terminated with an error.
response-status | A status code that, if nonzero, means the request encountered an error. You can get the string representation of the error by calling NetGetError .
Parent topic: Function Calls


NetCleanup

This function frees up all of the resources owned by an RMNet session. If you call this, and wish to create another RMNet session, you must call NetInit again. Any response and error pointers retrieved by NetGetError and the Get/Post functions must be freed by the caller. NetCleanup does not release these resources.

Usage

CALL "NetCleanup".
Parent topic: Function Calls


NetFree

This function is used to free the memory of a pointer given by RMNet.

Usage

CALL "NetFree" USING
         pointer-to-free.

Parameters

pointer-to-free A pointer given by RMNet that caller wishes to free. Use this function only for pointers that have been given to caller by RMNet.
Parent topic: Function Calls


NetGetError

This function is used to return the text of an error from the last RMNet operation.

Usage

CALL "NetGetError" USING
         error-pointer
         error-length
         GIVING
         status-code.

Parameters

error-pointer | A pointer to an alphanumeric item describing the error that occurred during the transaction, if any. After use, use NetFree to return memory used to store response.
error-length | A numeric item returning the length of the error to which error-pointer points.
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


NetInit

This function initializes the RMNet session and must be called before any other RMNet calls; otherwise, an error code will be returned in response-status.

Usage

CALL "NetInit"
         GIVING
         status-code.

Parameters

status-code A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


NetSetKeyPassword

This function is used to specify the password required to load your SSL private key file.

Usage

CALL "NetSetKeyPassword" USING
         private-key-password
         GIVING
         status-code.

Parameter

private-key-password | An alphanumeric item containing the password required for your SSL private key.
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


NetSetProxyServer

This function will set the HTTP proxy to use. Error codes will be returned in response-status.

Usage

CALL "NetSetProxyServer" USING
         proxy-server
         GIVING
         status-code.

Parameters

proxy-server | An alphanumeric item specifying the host name or dotted IP address of proxy server. To specify the port number, append :[port] to the end of the host name.
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


NetSetSSLCA

This function is used to specify a file containing one, or more, certificates of public Certificate Authorities. The certificates must be in PEM format.

Usage

CALL "NetSetSSLCA" USING
         public-ca-file
         GIVING
         status-code.

Parameters

public-ca-file | An alphanumeric item specifying the location of a file containing accepted public certificate authorities. (Default: ca-bundle.crt supplied in the zip file.)
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


NetSetSSLCert

This function is used to specify the location of a file containing a client-side Secure Sockets Layer (SSL) certificate.

Usage

CALL "NetSetSSLCert" USING
         public-cert-file
         GIVING
         status-code.

Parameters

public-cert-file | An alphanumeric item specifying the location of a file containing a PEM formatted certificate.
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


NetSetSSLKey

This function is used to specify the location of a file containing a Sockets Layer (SSL) private key file. The private key file must be in PEM format.

Usage

CALL "NetSetSSLKey" USING
         private-key-file
         GIVING
         status-code.

Parameters

private-key-file | An alphanumeric item specifying the location of a file containing the file name of a PEM formatted private key.
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


NetSSLVerifyPeer

This function will enable or disable the SSL peer verification. This will determine whether RMNet verifies the authenticity of the peer's certificate, i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authorities located in your certificate authorities bundle.

Usage

CALL "NetSSLVerifyPeer” USING
         SSL-verifypeer-flag
         GIVING
         status-code.

Parameters

SSL-verifypeer-flag | A numeric item. If this item is set to 1 RMnet will verify the authenticity of the peer's certificate (default), if set to 0, peer certificate authenticity will not be verified.
status-code | A numeric item that, if nonzero, indicates the request encountered an error. In this case, the string representation of the error may be obtained by calling NetGetError.
Parent topic: Function Calls


SYSTEM

The SYSTEM library routine provides a method of executing an operating system command.

Usage

CALL "SYSTEM"
    USING MY-COMMAND-LINE,
    GIVING EXIT-STATUS

Parameters

MY-COMMAND-LINE PIC X(n) | Contains the operating system command line to execute.
EXIT-STATUS Any numeric data item | Returns the called program's exit status.

Comments

The SYSTEM routine takes a parameter, which is submitted to the host operating system as if it were a command typed in from a terminal.

Some operating systems place limits on the length of a command-line string. Under Windows, the limit is 128 bytes. When you issue a SYSTEM call using a variable, make sure that the length of the variable doesn't exceed the operating system's limit.

The user's terminal is set to its default operating state before this command is run and is reset after it's complete. The runtime system waits for the command to complete.

Note: On Windows systems, if you append an ampersand (&) character to the command line, the program will run asynchronously. This should not be done for programs providing input files, but is often useful for programs processing output files.

The status of a call to SYSTEM is placed into EXIT-STATUS. This is usually the exit status of the executed program, or is -1 if the SYSTEM routine failed.

Here's an example of a call to SYSTEM. On a UNIX machine, you could display a directory listing of the /usr directory with the following command:

CALL "SYSTEM" USING "ls /usr"

If your machine is running Windows and you want to execute MS-DOS operating system commands via SYSTEM, you must pass the name COMMAND.COM, as well as the operating system command. Use the syntax shown in this example that executes the DIR command:

CALL "SYSTEM" USING
     "COMMAND.COM /C DIR"

When CALL "SYSTEM" is used to initiate a program, it looks only for files with a .EXE extension. If you want to call a .COM or .BAT file, you must explicitly add that extension in your code. For example:

CALL "SYSTEM" USING
     "COMMAND.COM /C MYBATCH.BAT"

The SYSTEM routine is provided in source form as a sample of a C subroutine.

Note: This routine causes ACUCOBOL-GT to forget the contents of the user's screen. This is done because the command executed may display information on the screen that ACUCOBOL-GT is not aware of. Because of this, pop-up windows made after a call to the SYSTEM routine may not correctly restore the screen contents when they are closed. You can avoid this problem by re-initializing the screen after you call the SYSTEM routine. You can do this by erasing the screen or by closing a pop-up window that covers the entire screen.

If the command to be executed will not perform any screen I/O, then you can request the SYSTEM routine to retain ACUCOBOL-GT's memory of the user's screen. This will avoid the problem mentioned in the preceding paragraph. To do this, simply pass a second argument to the SYSTEM routine. This may be any parameter you choose. For clarity, we suggest that the second argument be the literal "NO IO".

Parent topic: General Syntax and Library List


S$IO

The S$IO routine provides an interface to the sequential file handler. Calls to the routine require an operation code and a variable number of parameters, depending on the operation called. The return code is set automatically after the call. The external variable F-ERRNO is set according to any errors found. F-ERRNO may not be reset on entry to S$IO, and should be checked only if S$IO returns an error condition.

Note: File locking should be applied whenever SEEK operations are used.

Usage

CALL "S$IO"
    USING OP-CODE, PARAMETERS

Parameters

  • OP-CODE Numeric parameter

    Specifies the file handling routine to be performed. The following table lists each op-code and its corresponding operation. The operations are detailed below:

    Code | Operation
    1 | S-OPEN-FUNCTION
    2 | S-CLOSE-FUNCTION
    3 | S-MAKE-FUNCTION
    4 | S-READ-FUNCTION
    5 | S-WRITE-FUNCTION
    6 | S-REWRITE-FUNCTION
    7 | S-SEEK-FUNCTION
  • PARAMETERS variable depending on op-code

    The remaining parameters vary depending on the operation selected. They provide information and hold results for the operations specified. Parameters may be omitted from those operations that do not require them.

Description

All parameters passed to S$IO are passed by reference. This applies even to parameters that are integer values in the corresponding file handling routines.

Except for the MAKE function, S$IO automatically terminates PIC X parameters with a LOW-VALUES byte.

You do not have to specify SYNC for level 01 or level 77 parameters because they are automatically synchronized by ACUCOBOL-GT.

The filesys.def COPY file contains many useful definitions for use with S$IO. It contains definitions for the S$IO op-codes as well as the F-ERRNO error values. It also incudes many useful pre-declared variables that are of the proper type and usage.

The behavior of this routine is affected by the setting of the FILENAME_SPACES configuration variable that may or may not allow spaces in a file name. See the documentation on FILENAME_SPACES in Appendix H for information about the terminating character for path names.

The runtime configuration variables FILE_PREFIX and FILE_SUFFIX are ignored by the S$IO routine.

  • S-OPEN-FUNCTION (op-code 1)
  • S-CLOSE-FUNCTION (op-code 2)
  • S-MAKE-FUNCTION (op-code 3)
  • S-READ-FUNCTION (op-code 4)
  • S-WRITE-FUNCTION (op-code 5)
  • S-REWRITE-FUNCTION (op-code 6)
  • S-SEEK-FUNCTION (op-code 7)
Parent topic: General Syntax and Library List


S-OPEN-FUNCTION (op-code 1)

This routine opens an existing sequential file. If it is successful, the value in RETURN-CODE should be moved to a data item that is USAGE HANDLE. This data item is passed as the open file handle to the other file handling routines. If it fails, RETURN-CODE is set to a NULL value.

The S-OPEN-FUNCTION routine has four required parameters, and three optional parameters: name, mode, recsize, type, blocking, padding, pipe_name.

  • Name

    is the name of the file to open. It need not be null-terminated.

  • Mode

    is one of the following values (defined in filesys.def):

    Finput | open for input only
    Foutput | open for output only
    Fio | open for input and output
    Fextend | open for output only (same as Foutput)

    Foutput does not delete the current file (this behavior differs from the OPEN OUTPUT statement in COBOL).

    Note: This routine only opens files that already exist. If the file does not exist, the routine fails, even when opening with mode Foutput.

    Mode may furthermore have one of the following flags added to it to indicate file locking options (defined in filesys.def):

    Fread_lock | locks file against other updaters
    Fwrite_lock | locks file against all others
    Fmass_update | locks file against all others (same as Fwrite_lock)

    If Fmass_update is used, the file system is directed to emphasize speed of updates over file security.

    Additionally, Fmulti_lock may be added to mode to request that more than one record lock be maintained in the file by this process. If this option is not specified, then any I/O operation on the file will first release any currently locked record. This results in only one record lock being set in the file at any time. When this option is used, locked records are released only when the file is closed or when the UNLOCK routine is called.

  • Recsize

    is the maximum size of each record. This must be known at open time.

  • Type

    is the type of sequential file, and is one of the following values (defined in filesys.def):

    S-FIXED | fixed record binary sequential file
    S-VAR-COUNT | variable record length binary sequential file
    S-LINE | line sequential file
    S-PRINT | line sequential file
  • Blocking

    is the size of a block, in bytes. This parameter is optional and defaults to 0, meaning that a block is the size of a record.

  • Padding

    is the value of the pad character for filling short blocks. This parameter is optional and defaults to 0, meaning that any short blocks are padded with a binary 0 value.

  • Pipe-name

    is the name of the pipe to open instead of a file. This parameter is optional. It only has an effect on UNIX machines.

Parent topic: S$IO


S-CLOSE-FUNCTION (op-code 2)

This routine closes an open file. It also removes currently held locks on the file. S-CLOSE-FUNCTION has only one parameter, f, a file handle returned by the S-OPEN-FUNCTION. For some file systems, it is possible that S-CLOSE-FUNCTION will write additional records that had been previously buffered by the system. For this reason, it is possible that a disk full condition can occur.

Parent topic: S$IO


S-MAKE-FUNCTION (op-code 3)

This routine creates a new sequential file. It will overwrite any existing file of the same name. However, it will not overwrite a file that is currently in use. If the file is in use, the error E_FILE_LOCKED is returned.

This routine does not automatically terminate its parameters with LOW-VALUES. You must ensure that its parameters are correctly terminated.

The S-MAKE-FUNCTION routine takes two parameters: name and l_parms.

name contains the name of the file. The name need not be null-terminated.
l-parms is a string that describes various logical characteristics of the file. The string consists of three numeric fields separated by commas. The string must be null-terminated. This parameter is optional. If it is not specified, the values are not known to the runtime. The fields are as follows:
  1. Maximum record size. This is the size in bytes of the largest record to be placed in the file. This can range from 1 to 67,108,864.
  2. The file type (accepted values are the same as described in S-OPEN-FUNCTION). This must be a single byte containing a binary value that indicates the type of the file.
  3. Block size. This is the size of a block of records.
Parent topic: S$IO


S-READ-FUNCTION (op-code 4)

This routine reads the next record in the sequence of records. The S-READ-FUNCTION routine has two parameters, f and record.

F | must be a valid file handle returned by S-OPEN-FUNCTION.
Record | points to the area to hold the record read.

If S-READ-FUNCTION succeeds, RETURN-CODE is set to the size of the record read, plus one. If it fails, RETURN-CODE is set to zero. However, if the function fails due to the record being locked, the file pointer is set to the locked record.

Records read in a file open for input only are not locked. Furthermore, most file systems do not block the reading of locked records in a file open for input (this feature depends on the host file system - not all support it). Records read from a file open for I/O are automatically locked unless the external variable f-no-lock is set to a non-zero value, in which case they are treated in the same manner as files open for input.

Parent topic: S$IO


S-WRITE-FUNCTION (op-code 5)

This routine adds a new record to the named file. It has four parameters: f, record, size, and cr_cntrl.

F | must be a valid file handle returned by S-OPEN-FUNCTION.
Record | points to the record to add.
Size | is the size of the record. If size is zero, then the maximum record size for the file is used.
Cr_cntrl | is the number of lines to advance before writing the new record. This is only valid for print files.

The S-WRITE-FUNCTION routine does not change the current file position.

Parent topic: S$IO


S-REWRITE-FUNCTION (op-code 6)

This routine replaces an existing record in the file. It has three parameters: f, record, and size.

F | must be a valid file handle returned by S-OPEN-FUNCTION.
Record | points to the new record to place in the file.
Size | is the size of the record. It may be zero to indicate the maximum record size for the file. The size of the new record need not match the size of the existing record.

The S-REWRITE-FUNCTION routine does not affect the file position.

Parent topic: S$IO


S-SEEK-FUNCTION (op-code 7)

This routine changes the current position of the file for subsequent READs.

The only time the runtime supports a seek in a sequential file is 1) to find the last record in order to read the file backwards, and 2) after each READ to seek to the previous record. These are the only uses of SEEK supported by this library. The file must be locked to ensure that other users of the file don't add to it.

S-SEEK-FUNCTION has three parameters: f, offset and mode.

f | must be a valid file handle returned by OPEN.
offset | is the number of bytes to move from the current file position. Offset is limited to a 32-bit value.
mode | is a flag that specifies the position from which the offset is measured. A value of zero sets the position at the beginning of the file, regardless of the current position. A value of one sets the position to the current position. A value of two sets the position to the end of the file. Note that offset can be negative value.
Parent topic: S$IO


$WINHELP

If you have the Microsoft Windows Software Development Kit (SDK), you can access help files created with the SDK help compiler by calling the $WINHELP library routine. You can also access compiled HTML files that have the .chm extension. This is a support routine for Windows and Windows NT, and is not portable to other systems.

$WINHELP provides a direct interface to the Microsoft "WinHelp" library routine for files created with the SDK help compiler. This routine allows you to perform various functions using Microsoft Help. Normally, you would use this to allow the user to browse help information associated with your application.

For compiled HTML files whose names end with the .chm extension, $WINHELP invokes the Microsoft HTML Help Viewer application hh.exe.

Note: $WINHELP is not supported in Microsoft Windows Vista. Vista does not support WinHelp files (.hlp) meaning any programs that use the $WINHELP routine will no longer function. Microsoft is encouraging developers to transition their help file formats to CHM, HTML, or XML.

Usage

CALL "$WINHELP"
    USING HELP-FILE, OP-CODE, PARAM-VAL

Parameters

HELP-FILE PIC X(n) | This is the file name of the help file.
OP-CODE Numeric parameter | This value indicates the desired operation.
PARAM-VAL Type depends on op-code | This is an operation-dependent parameter. It may be omitted for several operations.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

  • HLP Files
  • WinHelp
  • Commonly Used Operations
  • CHM Files
Parent topic: General Syntax and Library List


HLP Files

Microsoft Help allows the user to search through .HLP files in a variety of ways. In order to use Microsoft Help in your application, you must create one or more .HLP files. To do this, you need a program that converts text files into help files. This is called a help compiler. You can find a help compiler (called hc) and instructions on its use in the Microsoft Windows SDK. You will also find information on how to construct the text files that get compiled into help files.

Note: Microsoft is encouraging developers to move away from .HLP files, as this file type is not supported in Windows Vista.
Parent topic: $WINHELP


WinHelp

After you've created help files, use the WinHelp library routine to interact with the Microsoft Help application that is bundled with Windows. This allows you to perform a variety of functions such as opening one of your help files and directing Help to a particular topic. WinHelp is fully explained in the SDK documents.

$WINHELP provides a direct interface to WinHelp. The advantages to using $WINHELP are:

  • you don't have to relink the runtime system
  • you use a simplified calling sequence

WinHelp takes four parameters: the handle of the main application window, the name of the help file, an operation code and an operation-dependent parameter. $WINHELP takes similar parameters, but with the following differences:

  • You do not pass the window-handle parameter. $WINHELP always supplies this parameter using the main ACUCOBOL-GT window. Thus, you pass (at most) three parameters to $WINHELP instead of the four that are passed to WinHelp.
  • If the operation-dependent parameter is not needed, you may omit it. In this case, $WINHELP will pass a value of zero to WinHelp.
  • All parameters are passed BY REFERENCE (the default for COBOL).

In summary, you pass either two or three parameters to $WINHELP. These are (in order):

  1. the filename of the help file
  2. the desired operation code
  3. an operation-dependent parameter (which can be omitted)

As a convenience, the COBOL declarations for the operation codes can be found in the file winhelp.def. The operation codes found there exactly correspond to the operation codes documented for WinHelp in the SDK.

Parent topic: $WINHELP


Commonly Used Operations

Most of the operation codes are used to manage context-sensitive help. For more information about ACUCOBOL-GT support for context-sensitive help, See Help Automation in User Interface Programming for more information. For a simple, context-independent help, you will typically use just the following operations:

HELP-CONTENTS | Displays the topic specified by the Contents option in the [OPTIONS]section of the .HPJ file. Microsoft indicates that this command is for backward compatibility. New applications should provide a .CNT file and use the HELP-FINDER command. You do not use the third parameter for this call.
HELP-FINDER | Displays the Help Topics dialog box with the last tab used. You do not use the third parameter for this call.
HELP-PARTIALKEY | Use this operation to bring up the keyword-search window. The third parameter should be the entire or partial keyword you want to find. Typically, this will be set to LOW-VALUES to allow key searches throughout the keyword list. One easy way to do this is to use "x'00'" as the third parameter.
HELP-HELPONHELP | Calls up Help's own help file. The third parameter is not used.
HELP-QUIT | Use this to exit the Help application. Microsoft requires that each application using Help logs out when it is done (if it doesn't, then Help keeps running after the application has quit). Note that $WINHELP tracks each help file used and automatically logs out each one when the runtime shuts down. Because of this, you need to use HELP-QUIT only if you want to shut down Help prior to exiting your application.

The help system provided with the ACUCOBOL-GT debugger uses these calls. The debugger presents three options to the user: "Contents", "Search", and "Help on Help". The COBOL code that corresponds to these cases is:

     evaluate menu-selection
        when menu-contents
           call "$winhelp" using
           "acudebug.hlp",
           help-contents
*Note newer applications should consider using help-finder instead of help-contents.

        when menu-search
           call "$winhelp" using
           "acudebug.hlp",
           help-partialkey, x"00"

        when menu-help-on-help
           call "$winhelp" using
           "acudebug.hlp",
           help-helponhelp
     end-evaluate.

This is all that's required to provide a simple help system. For information on creating a context-sensitive help system, see the SDK documentation.

Parent topic: $WINHELP


CHM Files

Microsoft makes an online help system called HTML Help. HTML Help uses the underlying components of Microsoft Internet Explorer to display help content. HTML Help supports HTML, ActiveX, Java, scripting (JavaScript and Microsoft Visual Basic Script), and HTML image formats (.jpeg, .gif, .png).

To create online help for your application, use the authoring tool in HTML Help called HTML Help Workshop (HHW). HHW will help you create a compiled HTML file that ends with the .chm extension. The Official Microsoft Help Authoring Kit from Microsoft Press has more information about help authoring. Contact Microsoft for more information about compiled HTML files.

$WINHELP will automatically detect the .chm file extension and invoke the Microsoft HTML Help Viewer application (hh.exe) to access the file. Only two operation codes are supported, HELP-CONTENTS and HELP-CONTEXT. When the operation code is HELP-CONTENTS, $WINHELP simply passes the specified compiled HTML help file name as a command-line argument to hh.exe. When the second parameter to $WINHELP, the operation code, is HELP-CONTEXT, $WINHELP constructs a command line using the following template:

hh.exe -mapid context_id help_file

where help_file is the first parameter to $WINHELP and context_id is the third parameter to $WINHELP. For example, the COBOL call:

CALL "$WINHELP" USING "c:\mydir\myhelp.chm", HELP-CONTENTS

translates to the system command line:

hh c:\mydir\myhelp.chm

and

CALL "$WINHELP" USING "c:\mydir\myhelp.chm",
    HELP-CONTEXT, 72

translates to:

hh -mapid 72 c:\mydir\myhelp.chm
Parent topic: $WINHELP


W$BITMAP

This routine is a collection of related operations that handle bitmapped (BMP and JPEG) images. Only Windows machines can actually display bitmaps. On all other machines, this routine returns an error code.

Usage

CALL "W$BITMAP"
    USING OP-CODE, parameters,
    GIVING BITMAP-HANDLE

Parameters

OP-CODE Numeric parameter | Selects the W$BITMAP operation to perform. The file acugui.def contains level 78 symbolic names for these operations. Unless otherwise noted, these operations can be used in a thin client environment. The specific operations are described below.
parameters | Vary depending on the op-code chosen.
BITMAP-HANDLE PIC S9(9) COMP-4 (or COMP-5) | BITMAP-HANDLE holds the return value of W$BITMAP. Values less than or equal to zero indicate errors. If you are loading or destroying ImageLists, this should be a COMP-5 field.

Description

W$BITMAP can be used to display a bitmapped image, load a bitmapped image into memory, or remove a bitmapped image and free its memory. You can use this routine to load a bitmapped image into memory as a Windows API data type called an ImageList, which treats the bitmap file as a series of fixed-width images. This provides a simplified way to load and destroy ImageLists when using the thin client. This routine can be used to capture screen shots of an active window or desktop. This routine can also be used to load IPictureDisp objects.

When it is trying to locate a bitmap file, W$BITMAP will search first for a resource with the specified name, and then for a disk file. Resources are named in a fashion similar to disk files, but without any directory information. (See the COPY RESOURCE statement in ACUCOBOL-GT Reference Manual for more information about including resources.)

Note: When you are running in a thin client environment, and a file name beginning with @[DISPLAY] is passed to this routine, it will attempt to access the file in the display host's file system. It does not download the file from the server. For more information, refer to the topic Using Library Routines and DLLs in Thin Client, in the AcuConnect User's Guide.

W$BITMAP will examine files to determine the type of image format. If the file suffix is .jpg, .jpe or .jpeg, W$BITMAP assumes the file is a JPEG image. Otherwise, it assumes the files are in BMP format. In order to read JPG files, you must have the file ajpg32.dll installed in the runtime directory. Only 32-bit runtimes support JPEG format images. If you need JPEG support on 64-bit Windows, run the 32-bit runtime or the Thin Client. You can also run the Thin Client with the 64-bit runtime.

W$BITMAP loads 24-bit color or 8-bit grayscale images in the JPEG File Interchange Format (JFIF). It reads baseline and extended DCT sequential and progressive files that are Huffman encoded (file types SOF0, SOF1, SOF2). The JPG lossless mode format is not supported.

Note: The behavior of this library routine is affected by the setting of the FILENAME_SPACES configuration variable that may or may not allow spaces in a file name. See the documentation on FILENAME_SPACES in Appendix H.
  • WBITMAP-DISPLAY (op-code 1)
  • WBITMAP-DESTROY (op-code 2)
  • WBITMAP-LOAD (op-code 3)
  • WBITMAP-LOAD-IMAGELIST (op-code 5)
  • WBITMAP-DESTROY-IMAGELIST (op-code 6)
  • WBITMAP-CAPTURE-IMAGE (op-code 7)
  • WBITMAP-CAPTURE-DESKTOP (op-code 8)
  • WBITMAP-CAPTURE-CLIPBOARD (op-code 9)
  • WBITMAP-LOAD-PICTURE (op-code 10)
  • Error Handling
Parent topic: General Syntax and Library List


WBITMAP-DISPLAY (op-code 1)

This operation retrieves a bitmapped image from disk and displays it on the screen. This opcode takes four additional parameters:

name | This is an alphanumeric literal or data item that is the file name of the bitmap to display. This must be a file that contains a device-independent bitmap (usually called .bmp files). Create this file with a bitmap editor. For example, the bitmap contained in the sample program tour.cbl was created using the Paint program that comes with Windows. The file name is not interpreted--it should be the exact file name of the image.
row | This is a numeric parameter. This value is the row where you want to place the upper-left corner of the image. Row values are treated just as they are in a DISPLAY statement. This means that row 1 is the top row of the current ACUCOBOL-GT window. You may also refer to fractional row positions. For example, row 1.5 is halfway between the top of row 1 and the top of row 2.
column | This is a numeric parameter. This identifies the column where the upper-left corner of the image is to be placed. COLUMN is processed in the same manner as ROW.
flags | This is a numeric parameter that contains display options. Currently, the only option is WBITMAP-NO-FILL. When this is set, it inhibits the background-fill operation described below. This parameter can be omitted, in which case the fill option behaves as described.

The bitmapped image contained in the named file is loaded into memory, converted to a device-dependent bitmap and displayed at the position indicated by ROW and COLUMN. The entire image in the file is displayed, except that it is truncated to fit in the current ACUCOBOL-GT window.

Note: You should generally try to produce small bitmaps, because full-screen bitmaps occupy significant amounts of memory and can take noticeable time to process. If you use Windows Paint to create the image, you should first use the Image Attributes option to set the size of the image (the default is a full page; you'll want to make it smaller).

Frequently, the edges of the image will not exactly match a row and column boundary. ACUCOBOL-GT fills the tiny area between the edge of the bitmap and the next character cell with the current window's background color. If you use the WBITMAP-NO-FILL parameter, then the runtime leaves this area alone. Usually, this means that it will show arbitrary data as the program progresses. This can be useful, however, if you are placing several bitmaps very close together and do not want the fill area of one bitmap to overwrite another bitmapped image.

When W$BITMAP returns, it sets BITMAP-HANDLE to a positive (non-zero) value that is the bitmap's handle. This should be saved in a variable declared as PIC 9(9). Use the handle when you make future reference to the displayed image (for example, you need the handle in order to remove the bitmap and free the memory that it occupies). If BITMAP-HANDLE is less than or equal to zero, then an error has occurred.

You may display data and pop-up windows over bitmapped images. However, the current implementation may cause the image to flash through the data displayed on top when the runtime is repainting the screen. The final image should be correct, but the flash can be annoying in some cases. To avoid this, either do not display anything over the image, or display over the entire image (the runtime will not try to display the image if it is entirely hidden).

The effect of displaying overlapping bitmapped images is undefined.

Parent topic: W$BITMAP


WBITMAP-DESTROY (op-code 2)

This operation removes a bitmapped image from the screen and frees the memory used by that bitmap. It takes only one parameter, the handle of the bitmap returned by WBITMAP-DISPLAY. This should be either USAGE COMP-4 or unsigned DISPLAY.

When an image is removed from the screen, it's replaced by spaces using the current window's background color. Only those parts of the screen that are currently showing the image are updated.

You can effectively remove an image from the screen by displaying over it. However, this does not free the memory used by the image. The runtime also spends some time whenever it updates the screen determining whether or not the image is visible. For these reasons, you should destroy images when you are done with them.

The runtime automatically destroys all remaining images when it shuts down.

Parent topic: W$BITMAP


WBITMAP-LOAD (op-code 3)

This operation loads bitmapped images from disk into memory so that they can be displayed with bitmapped buttons.

Note: You may not use remote name notation with this operation.

This op-code takes three additional parameters. They are, in order:

name | A literal or data item containing the name of the file to load. The length of the name (including path) should not exceed 90 characters. This limit may vary on different operating systems.
bitmap-handle | A PIC S9(9) COMP-4 data item that stores a handle to the bitmapped image loaded into memory.
flags | A numeric parameter that contains loading options. This parameter can be omitted. Currently the only option is WBITMAP-NO-DOWNLOAD. This option is intended for programs that are deployed with the ACUCOBOL-GT Thin Client. When the option is set, the server does not download the specified bitmap to the client. The flag indicates to the server that the bitmap is already in the client's cache directory. To properly use the option, the program must keep track of whether the bitmap is already in the client's cache.

If the operation is successful, bitmap-handle holds a positive value. If bitmap-handle is 0 or negative, an error occurred.

If you have bitmapped images in more than one file, you need to load each file before using the images they contain. Be sure to store separate handles for each file loaded.

When you are done with an image and have destroyed all the buttons that reference that image, you can remove it from memory with the WBITMAP-DESTROY operation. Do not destroy an image that is referenced by an active control or print job, because the results are unpredictable.

Parent topic: W$BITMAP


WBITMAP-LOAD-IMAGELIST (op-code 5)

This operation works in the same way as the WBITMAP-LOAD operation, except that the returned handle is a Win32 API ImageList handle instead of a bitmap handle. This handle can be directly used by ActiveX controls which use ImageLists, and should be USAGE COMP-5. When running under the thin client, the resulting ImageList resides on the desktop machine. The ImageList handle is only meaningful to software components on that machine (such as a displayed ActiveX control). Unlike images loaded with WBITMAP-LOAD, the runtime does not track ImageLists. For this reason, you should destroy an ImageList once you no longer need it. Error values returned by this operation are identical to those returned by the WBITMAP-LOAD operation. This operation takes up to three additional parameters:

name | This required alphanumeric literal is the name of the file you wish to load. It should be a BMP or JPG file. The file is handled in exactly the same fashion as it is for the WBITMAP-LOAD operation.
width | This numeric parameter is optional. The bitmap file is treated as a series of distinct images arranged horizontally. The height of each image is determined by the height of the bitmap. The width of each image is defined by this parameter, expressed in pixels. Each image must be the same width. If omitted, a default width of 16 pixels (a common width for toolbar images) is used.
transparent-color This optional numeric literal is set to the value of a color that you designate as a "transparent" color. Pixels of this color are not displayed when the bitmap is drawn, allowing the background to show through. Color values are expressed as integers composed of red, green and blue components. The mathematical expression for the composite value is:

(blue * 65536) + (green * 256) + (red)

where red, green, and blue are values between 0 and 255. You can use a hexadecimal numeric literal to express this value since each component of the color occupies one byte in a binary value. For example, "x#FF8000" expresses an orange color with red at 255, green at 128, and blue at 0. The first byte (x 'FF') is the red value, the second byte (x'80') is the green value, and the last byte (x'00') is the blue value.

Note: The value "x#C0C0C0" is often used for the transparent color since this is the medium gray shade used in default Windows color schemes. Images drawn using this as a background color adapt well when the user changes from the default color scheme.

If this parameter is omitted, all colors are treated as usual and the image is drawn without modification.

Parent topic: W$BITMAP


WBITMAP-DESTROY-IMAGELIST (op-code 6)

This operation destroys an ImageList. Normally this will be an ImageList created by the WBITMAP-LOAD-IMAGELIST operation, but it may be any ImageList that resides on the desktop machine. When running under the thin client, the ImageList is destroyed on the desktop machine. This operation takes a single parameter, the handle of the ImageList to destroy. This should be USAGE COMP-5. Because the runtime cannot verify this parameter, you should take extra care to ensure that it is valid.

Parent topic: W$BITMAP


WBITMAP-CAPTURE-IMAGE (op-code 7)

This operation captures a screen shot of a window, and stores it as a BMP file. If you are using this operation in a thin client environment, see Accessing Local Resource Files in the AcuConnect User's Guide for special considerations. This operation takes four additional parameters:

name This required alphanumeric literal is the name of the file in which the image is saved. The name may include embedded spaces. This parameter is not affected by the FILE_PREFIX configuration variable. If a file of the specified name already exists, it is overwritten unless it is read-only. If this parameter is omitted or set to spaces, the image is saved to the Windows clipboard.
window-handle This optional PIC S9(9) COMP-4 data item is the Windows system handle of the image to capture. If this parameter is omitted or set to 0, the currently active window is captured. (Active means the window that responds to a keystroke.) If no window-handle is available or there is no currently active window, an image of the desktop is captured.

The Windows system handle is not the same as the Acucorp window handle. You may determine the value of window-handle using the following code:

   DISPLAY WINDOW HANDLE IN acu-handle.
or
   DISPLAY ENTRY-FIELD HANDLE IN acu-handle.
   INQUIRE acu-handle SYSTEM HANDLE IN window-handle.

where acu-handle is the handle of a window or control, and window-handle is a PIC 9(9) COMP-5 or PC X(4) COMP-N data item.

client This optional numeric data item is used to specify whether to capture the entire window, or just the interior of the window. If you specify this parameter, you must also specify window-handle. This parameter may have one of two values:
  • 0 - (default) The entire window is captured, including the title bar, window frame, menu, etc.
  • 1 - Only the interior of the window specified by window-handle is captured. This can be useful if you are displaying a scanned image, and want to capture only that image, not the window frame.
colordepth This optional numeric data item sets the number of color bits per pixel used when capturing the image. If this value is not specified, the screen default is used. The default color density of a screen is a property of the video adapter driver. On most modern PCs this is set to 24-bits per pixel. This parameter is not used when images are saved to the clipboard. This parameter may be set to one of the following values:
  • 1 - Monochrome
  • 4 - 4-bits per pixel
  • 8 - 8-bits per pixel (256 colors)
  • 16 - 16-bits per pixel
  • 24 - 24-bits per pixel (True color)
  • 32 - 32-bits per pixel (True color)

When making copies of all or part of the screen, do not use higher color density than necessary. Color is memory intensive and a higher color density does not improve image quality as much as it results in a larger file size. Consider what you will use the image for and set colordepth accordingly. Many tools do not support bitmaps with more than 256 colors. A color density setting of 8 is adequate for most situations.

Parent topic: W$BITMAP


WBITMAP-CAPTURE-DESKTOP (op-code 8)

This operation captures a screen shot of the entire desktop and stores it as a BMP file. (If you are using this operation in a thin client environment, refer to the topic Accessing Local Resource Files of the AcuConnect User's Guide for special considerations.) This operation takes two additional parameters:

name This required alphanumeric literal is the name of the file in which the image is saved. The name may include embedded spaces. The length of name (including path) should not exceed 90 characters. This limit may vary on different operating systems. This parameter is not affected by the FILE_PREFIX configuration variable. If a file of the same name already exists, it is overwritten unless it is read-only. If this parameter is omitted or set to spaces, the image is saved to the Windows clipboard.
colordepth This optional numeric data item sets the number of color bits per pixel used when capturing the image. If this value is not specified, the screen default is used. The default color density of a screen is a property of the video adapter driver. On most modern PCs it is 24-bits per pixel. This parameter is not used when images are saved to the clipboard. This parameter may be set to one of the following values:
  • 1 - Monochrome
  • 4 - 4-bits per pixel
  • 8 - 8-bits per pixel (256 colors)
  • 16 - 16-bits per pixel
  • 24 - 24-bits per pixel (True color)
  • 32 - 32-bits per pixel (True color)

When making copies of all or part of the screen, do not use higher color density than necessary. Color is memory intensive and a higher color density does not improve image quality as much as it results in a larger file size. Consider what you will use the image for and set colordepth accordingly. Many tools do not support bitmaps with more than 256 colors. A color density setting of 8 is adequate for most situations.

Parent topic: W$BITMAP


WBITMAP-CAPTURE-CLIPBOARD (op-code 9)

This operation saves the current content of the Windows clipboard as a BMP file. If the clipboard is empty or contains an unsupported datatype, such as text, an error is returned. If you are using this operation in a thin client environment, See Accessing Local Resource Files of the AcuConnect User's Guide for special considerations. This operation takes only one parameter, the filename to which the clipboard content must be saved.

name This required alphanumeric literal is the name of the file in which the image is saved. The name may include embedded spaces. The length of name (including path) should not exceed 90 characters. This limit may vary on different operating systems. This parameter is not affected by the FILE_PREFIX configuration variable. If a file of the specified name already exists, it is overwritten unless it is read-only.
Parent topic: W$BITMAP


WBITMAP-LOAD-PICTURE (op-code 10)

This operation accepts a filename and returns a handle to an IPictureDisp object. This is similar to the Visual Basic LoadPicture function. You must use the acuclass.def file to obtain the definition of the IPictureDisp object.

An IPictureDisp object uses the IPictureDisp interface to expose its properties through Automation. It provides a subset of the functionality available through IPicture methods. For more information, go to: msdn.microsoft.com/library and search for IPictureDisp and/or IPicture.

The following image formats are supported:

Bitmaps & device independent bitmaps (DIB) | .bmp
Icons | .ico
Joint Photographic Experts Group (JPEG) | .jpg
Windows MetaFile | .wmf
Graphics Interchange Format | .gif

This operation takes one parameter:

name This required alphanumeric literal is the name of the file you want to load. The filename must include an absolute path. The length of name (including path) should not exceed 90 characters.
Note: If the operation is successful, bitmap-handle holds a positive value. If bitmap-handle is 0 or negative, an error occurred. Note that the runtime does not manage memory consumed by this function. When you are done with an image, you should remove it from memory with a DESTROY IPictureDisp_handle statement.

The IPictureDisp handle will not accept negative values. If an error (a negative value) is returned, you must use a REDEFINES, or move the value to a signed numeric variable, in order to read the error code. See Example 3 below.

Error Handling

If the value of BITMAP-HANDLE is 0 or negative, an error has occurred. These errors are defined in acugui.def.

WBERR-UNSUPPORTED (value 0)
The system does not support bitmapped images. Currently, ACUCOBOL-GT supports bitmap display on Windows systems only.
WBERR-FILE-ERROR (value -1)
A file error occurred when trying to open name. The most common cause is that name does not exist. Other possibilities include a permissions error or running out of file handles.
WBERR-NO-MEMORY (value -2)
The system ran out of memory trying to allocate space for the image.
WBERR-NOT-BITMAP (value -3)
The named file does not contain a device-independent bitmap.
WBERR-FORMAT-UNSUPPORTED (value -4)
The format of the current image is not supported.
WBERR-MISSING-DLL (value -5)
The run time has attempted to load a .jpg file and the file ajpg32.dll can not be found.
WBERR-INVALID-HWND (value -6)
The run time can not capture the current image. The window handle provided was invalid.
WBERR-INVALID-DATA (value -7)
The run time can not access the bitmap object. This can happen if the window has been closed, or if the image is corrupt.
WBERR-INVALID-CLIPBOARD (value -8)
The run time has been denied access to the clipboard. This may be because another application has locked the clipboard.
WBERR-INVALID-PALETTE (value -9)
The run time is not able to create the palette for this image. The most common cause is that the image is corrupt or has an unsupported palette size.

Example 1

The following example shows the first two op-codes in use. After the example, the parameters are described. For an example of the WBITMAP-LOAD operation, see Example 3.

Notice the two calls to W$BITMAP in the sample code. First, W$BITMAP displays a logo, then uses the DISPLAY verb to place two lines of text on the screen. The second call to W$BITMAP removes the logo from the screen and releases the memory it occupies.

* Displays the logo for 2 seconds.

display window, line 7, column 26, lines 9, size 30, color black +
   bckgrnd-white, erase, shadow, no scroll, pop-up area is window-1.

* Now give the name of the bitmap file and
* the row and column of the upper left corner:

call "w$bitmap" using wbitmap-display, "sample/acucob85.bmp", 2, 5.

* Save the handle so it is available when needed
* to remove the image: move return-code to bitmap-handle.

* Check to make sure the logo file was found and
* that no error occurred:

if bitmap-handle <= zero
   close window window-1
else
   display "Copyright (c) 1985 - 2000", line 7, size 30, centered
   display "Acucorp, Inc.", line 8, size 30, centered
   accept single-char, auto, before time 200
end-if
close window window-1

* Remove the bitmapped image and release the
* memory it uses:

call "w$bitmap" using wbitmap-destroy, bitmap-handle.

Example 2

Following are several examples of different W$BITMAP calls to capture screen shots and desktop images:

* This call captures the standard active window as a file
* named "myfile.bmp"
call "W$BITMAP" using WBITMAP-CAPTURE-IMAGE "myfile.bmp".

* This call captures the standard active window onto
* the Windows clipboard
call "W$BITMAP" using WBITMAP-CAPTURE-IMAGE " ".

* This call captures the client area of the active
* window as a file named "myfile.bmp" using 8-bit color
call "W$BITMAP"
   using WBITMAP-CAPTURE-IMAGE "myfile.bmp" 0 1 8.

* This call captures the indicated window handle using 16-bit
* color and saves it as a file named "myfile.bmp"
inquire mycontrol system handle in hWND
call "W$BITMAP"
   using WBITMAP-CAPTURE-IMAGE "myfile.bmp" hWND 0 16.

* This call captures the entire desktop as a file named
* "myfile.bmp" using 32-bit color
call "W$BITMAP" using WBITMAP-CAPTURE-DESKTOP "myfile.bmp" 32.

* This call captures the current bitmap content of the Windows
* clipboard as a file named "myfile.bmp"
call "W$BITMAP" using WBITMAP-CAPTURE-CLIPBOARD "myfile.bmp".

Example 3

The following sample program calls W$BITMAP to load an IPicture object.

       ...

SPECIAL-NAMES.
   COPY "acuclass.def".
     .

WORKING-STORAGE SECTION.
   COPY "acugui.def".
     77  myIPictureDisp     HANDLE OF IPictureDisp.
     77  myErrorTest REDEFINES myIPictureDisp PIC S9(9) COMP-5.

   ...
PROCEDURE DIVISION.
   MAIN-001.

  CALL "W$BITMAP" USING WBITMAP-LOAD-PICTURE
      "C:\MyDir\MyBitmaps.bmp"
       GIVING myIPictureDisp.

EVALUATE myErrorTest
     WHEN WBERR-FILE-ERROR
        DISPLAY MESSAGE BOX
          "File not found"
          TITLE "Error"
          INITIALIZE myIPictureDisp
     WHEN WBERR-FORMAT-UNSUPPORTED
        DISPLAY MESSAGE BOX
          "Format not supported"
           TITLE "Error"
           INITIALIZE myIPictureDisp
     WHEN OTHER
          DISPLAY MESSAGE BOX
          "File successfully loaded"
          TITLE "Success"
END-EVALUATE.
DESTROY myIPictureDisp.
GOBACK.
Parent topic: W$BITMAP


Error Handling

If the value of BITMAP-HANDLE is 0 or negative, an error has occurred. These errors are defined in acugui.def.

Error | Value | Description
WBERR-UNSUPPORTED | 0 | The system does not support bitmapped images. Currently, ACUCOBOL-GT supports the display of bitmaps on Windows systems only.
WBERR-FILE-ERROR | -1 | A file error occurred when trying to open name. The most common cause is that name does not exist. Other possibilities include a permissions error or running out of file handles.
WBERR-NO-MEMORY | -2 | The system ran out of memory trying to allocate space for the image.
WBERR-NOT-BITMAP | -3 | The named file does not contain a device-independent bitmap.
WBERR-FORMAT-UNSUPPORTED | -4 | The format of the current image is not supported.
WBERR-MISSING-DLL | -5 | The runtime has attempted to load a .jpg file and the file ajpg32.dll cannot be found
WBERR-INVALID-HWND | -6 | The runtime cannot capture the current image. The window handle provided was invalid.
WBERR-INVALID-DATA | -7 | The runtime cannot access the bitmap object. This can happen if the window has been closed, or if the image is corrupt.
WBERR-INVALID-CLIPBOARD | -8 | The runtime has been denied access to the clipboard. This may be because another application has locked the clipboard.
WBERR-INVALID-PALETTE | -9 | The runtime is not able to create the palette for this image. The most common cause is that the image is corrupt or has a palette size that is not supported.
Parent topic: W$BITMAP


W$BROWSERINFO

The W$BROWSERINFO routine provides information about a requesting Web browser. This routine is used in conjunction with the ACUCOBOL-GT Web Runtime.

Usage

CALL "W$BROWSERINFO"
    USING BROWSERINFO-DATA

Parameters

BROWSERINFO-DATA Group item as follows:

01 BROWSERINFO-DATA.
   03 USER-AGENT-STRING       PIC X(50).
   03 BROWSWER-MAJOR-VERSION  PIC X COMP-X.
   03 BROWSWER-MINOR-VERSION  PIC X COMP-X.
BROWSERINFO-DATA is found in the COPY library acucobol.def. The values are as follows:
USER-AGENT-STRING | This is the browser's user_agent field. It contains the name of the browser as it is sent to the HTTP server. It may also contain version numbers, product name, and operating system name. Netscape browsers set the first seven characters of this field to Mozilla. Microsoft Internet Explorer sets this field to Microsoft Internet Explorer.
BROWSER-MAJOR-VERSION | This is the major version number reported by the browser. This is not the same as the major version number displayed in the browser's About screen. Many browsers simply place a 0 in this field.
BROWSER-MINOR-VERSION | This is the minor version number reported by the browser. This is not the same as the minor version number displayed in the browser's About screen.

Description

Upon return from W$BROWSERINFO, all of the data elements contained in BROWSWERINFO-DATA are filled in. If you call W$BROWSERINFO when the COBOL application is not running in a Web browser via the Web Runtime, the first field is set to spaces, and the last two fields are set to zero (0).

Parent topic: General Syntax and Library List


W$FLUSH

The W$FLUSH routine causes the screen and/or cursor to be refreshed. It can be used to ensure that the user sees the most current display (see the explanation under Description, below).

Usage

CALL "W$FLUSH"
    USING PARAM-NUM

Parameters

PARAM-NUM numeric data item (optional) Specifies what part of the display (screen or cursor) is refreshed.

Description

Calling this routine refreshes the display so that the user sees everything that is current, even if an ACCEPT has not been performed. Normally, the runtime ensures that the information the user sees is correct only when input is required from the user. This means that if you DISPLAY some text or control, and then perform extensive processing without also performing an ACCEPT, the text or control may not be immediately visible to the user. Possible values are:

0 | (default) the screen is made current, but the cursor may appear in an arbitrary location. (This is due to output optimization.)
1 | the screen and cursor are made current
2 | on UNIX machines using the BUFFERED-SCREEN configuration option, the screen is made current at the next clock tick on all other machines this has the same behavior as setting the value to 1.
3 | on UNIX machines using the BUFFERED-SCREEN configuration option, the screen and cursor are made current at the next clock tick on all other machines this has the same behavior as setting the value to 1.
Note: Prior to the introduction of W$FLUSH, some programs worked around this problem using the statement ACCEPT OMITTED BEFORE TIME 0.

If you are experiencing a performance penalty for these runtime calls, especially during file processing where the screen is updated after each record, you can choose to inhibit calls to W$FLUSH. This can be useful if you want to simulate "mass update" functionality for ActiveX controls that do not have this capability built in. Use one of the following parameters:

256 | inhibits any future calls to W$FLUSH, including those made internally by the runtime system. Only a call with parameter 257 will be honored. This parameter must be turned off to restore user interaction.
257 | cancels the inhibited state caused by parameter 256. This parameter does not cause a flush itself; it just allows future calls to W$FLUSH to function. You must call this parameter before interacting with the user.

For example:

   78  INHIBIT-FLUSH   VALUE 256.
   78  ALLOW-FLUSH     VALUE 257.

   CALL "W$FLUSH" USING INHIBIT-FLUSH
   PERFORM LARGE-ACTIVEX-UPDATE
   CALL "W$FLUSH" USING ALLOW-FLUSH
Parent topic: General Syntax and Library List


W$FONT

The W$FONT routine provides general support for selecting fonts and determining their characteristics.

Usage

CALL "W$FONT"
    USING OP-CODE, FONT-HANDLE, WFONT-DATA
    GIVING WFONT-STATUS

Parameters

OP-CODE Numeric value | Selects the W$FONT function to perform. These operations are described below.
FONT-HANDLE USAGE HANDLE or HANDLE OF FONT | When retrieving a font from the system, the system stores a handle to the font in this item. With other operations, this value specifies the font to act on.
WFONT-DATA Group item as follows:
01 WFONT-DATA.
   03 WFONT-FACE-DATA.
      05 WFONT-DEVICE                  HANDLE, VALUE NULL.
         88 WFDEVICE-CONSOLE           VALUE NULL.
         88 WFDEVICE-WIN-PRINTER       VALUE 1.
      05 WFONT-NAME                    PIC X(33).
      05 WFONT-CHAR-SET                PIC X COMP-X.
         88 WFCHARSET-DONT-CARE        VALUE 0.
         88 WFCHARSET-DEFAULT          VALUE 1.
         88 WFCHARSET-WIN-OEM          VALUE 2.
         88 WFCHARSET-WIN-SYMBOL       VALUE 3.
         88 WFCHARSET-WIN-SHIFTJIS     VALUE 4.
         88 WFCHARSET-WIN-HANGUL       VALUE 5.
         88 WFCHARSET-WIN-GB2312       VALUE 6.
         88 WFCHARSET-WIN-CHINESEBIG5  VALUE 7.
         88 WFCHARSET-WIN-JOHAB        VALUE 8.
         88 WFCHARSET-WIN-HEBREW       VALUE 9.
         88 WFCHARSET-WIN-ARABIC       VALUE 10.
         88 WFCHARSET-WIN-GREEK        VALUE 11.
         88 WFCHARSET-WIN-TURKISH      VALUE 12.
         88 WFCHARSET-WIN-VIETNAMESE   VALUE 13.
         88 WFCHARSET-WIN-THAI         VALUE 14.
         88 WFCHARSET-WIN-EASTEUROPE   VALUE 15.
         88 WFCHARSET-WIN-RUSSIAN      VALUE 16.
         88 WFCHARSET-WIN-MAC          VALUE 17.
         88 WFCHARSET-WIN-BALTIC       VALUE 18.
      05 WFONT-SIZE                    PIC X COMP-X.
      05 WFONT-BOLD-STATE              PIC X COMP-X.
         88 WFONT-BOLD                 VALUE 1, FALSE 0.
      05 WFONT-ITALIC-STATE            PIC X COMP-X.
         88 WFONT-ITALIC               VALUE 1, FALSE 0.
      05 WFONT-UNDERLINE-STATE         PIC X COMP-X.
         88 WFONT-UNDERLINE            VALUE 1, FALSE 0.
      05 WFONT-STRIKEOUT-STATE         PIC X COMP-X.
         88 WFONT-STRIKEOUT            VALUE 1, FALSE 0.
      05 WFONT-PITCH-STATE             PIC X COMP-X.
         88 WFONT-FIXED-PITCH          VALUE 1, FALSE 0.
      05 WFONT-FAMILY                  PIC X COMP-X.
         88 WFFAMILY-DONT-CARE         VALUE 0.
         88 WFFAMILY-MODERN            VALUE 1.
         88 WFFAMILY-ROMAN             VALUE 2.
         88 WFFAMILY-SWISS             VALUE 3.
         88 WFFAMILY-SCRIPT            VALUE 4.
         88 WFFAMILY-DECORATIVE        VALUE 5.
   03 WFONT-CHOOSE-DATA.
      05 WFONT-CHOOSE-FLAGS            PIC X COMP-X.
      05 WFONT-CHOOSE-MIN-SIZE         PIC X COMP-X.
      05 WFONT-CHOOSE-MAX-SIZE         PIC X COMP-X.
      05 WFONT-CHOOSE-RED              PIC X COMP-X.
      05 WFONT-CHOOSE-GREEN            PIC X COMP-X.
      05 WFONT-CHOOSE-BLUE             PIC X COMP-X.
      05 WFONT-CHOOSE-COLOR-NUM        PIC X COMP-X.
   03 WFONT-ANGLE                      PIC X(2) COMP-X.

WFONT-DATA contains parameters that are used by the various W$FONT operations. The descriptions below detail how each operation uses this data item.

WFONT-STATUS Signed numeric data item | WFONT-STATUS returns the status of the operation. Unless otherwise specified below, a value of 1 indicates success and 0 or a negative value indicates failure.

All of the data items and definitions required by this routine can be found in the COPY library fonts.def. To avoid problems should the format of WFONT-DATA change in a future version of ACUCOBOL-GT, it is recommended that you always use the fonts.def COPY file.

Description

W$FONT performs a variety of operations depending on the specified op-code. The operations are as follows:
  • WFONT-SUPPORTED (op-code 1)
  • WFONT-GET-FONT (op-code 101)
  • WFONT-GET-CLOSEST-FONT (op-code 102)
  • WFONT-DESCRIBE-FONT (op-code 106)
  • WFONT-CHOOSE-FONT (op-code 2)
  • WFONT-DATA
  • WFONT-SUPPORTED (op-code 1)
  • WFONT-GET-FONT (op-code 101)
  • WFONT-GET-CLOSEST-FONT (op-code 102)
  • WFONT-DESCRIBE-FONT (op-code 106)
  • WFONT-CHOOSE-FONT (op-code 2)
  • WFONT-DATA
  • Error Handling
Parent topic: General Syntax and Library List


WFONT-SUPPORTED (op-code 1)

This operation returns a value that indicates whether the host system supports W$FONT. If it does not, WFONT-STATUS is set to WFONTERR-UNSUPPORTED (value "0"). This indicates that the host system does not use fonts (as would be normal for a non-graphical host). A return value of WFONT-FONT-SUPPORT (value "1") indicates that fonts are supported, but the WFONT-CHOOSE-FONT operation is not available. Finally, a value of WFONT-FULL-SUPPORT (value "2") indicates that all W$FONT operations are supported on the system.

The FONT-HANDLE and WFONT-DATA parameters are not used with this op-code and should be omitted.

Parent topic: W$FONT


WFONT-GET-FONT (op-code 101)

This operation returns a font on the system that matches the specifications in WFONT-DATA. If a matching font is found, its handle is returned in FONT-HANDLE and WFONT-STATUS is set to "1". If no matching font is found, FONT-HANDLE is set to NULL and WFONT-STATUS returns the WFONTERR-FONT-NOT-FOUND error condition.

Note:

Fonts occupy memory. If you no longer need a font, you can free the memory used by the font by using the DESTROY verb on the font's handle. The runtime automatically destroys all fonts when it terminates.

In WFONT-GET-FONT, the WFONT-DATA fields are used to describe the desired font. These fields are described in detail below. You should always INITIALIZE the group item WFONT-DATA prior to filling in these fields to ensure that unused fields contain the proper default values.

If you do not specify WFONT-NAME, WFONT-CHAR-SET, or WFONT-SIZE, the corresponding aspect of the font will be arbitrary. In general, you should always specify WFONT-NAME and WFONT-SIZE to get useful results.

Parent topic: W$FONT


WFONT-GET-CLOSEST-FONT (op-code 102)

This operation is identical to WFONT-GET-FONT, except that it doesn't fail if it cannot find the specified font. Instead, it returns the closest matching font. Note that only Windows systems are capable of performing this operation. On other systems, this call is treated as being identical to WFONT-GET-FONT. You should specify WFONT-CHAR-SET with this function to ensure that the returned font is useful. Also, specifying WFONT-FAMILY can help in locating a suitable font.

Parent topic: W$FONT


WFONT-DESCRIBE-FONT (op-code 106)

This operation returns the characteristics of the font described by FONT-HANDLE in WFONT-DATA. All of the fields contained in the subgroup WFONT-FACE-DATA are returned, within the capabilities of the host system.

Parent topic: W$FONT


WFONT-CHOOSE-FONT (op-code 2)

This operation presents the user with a dialog box that allows for the direct selection of a font. If the user cancels the dialog box, W$FONT returns a status of WFONTERR-CANCELLED. Otherwise, W$FONT returns a status of "1" and sets WFONT-FACE-DATA to a description of the chosen font. FONT-HANDLE is not used and should be passed as "NULL". To generate a font handle for the user's choice, take the WFONT-FACE-DATA values returned by this operation and pass them to the WFONT-GET-FONT operation.

Values contained in WFONT-CHOOSE-DATA modify the behavior of the dialog box and return additional information. These fields are described below. You should always INITIALIZE the group item WFONT-DATA prior to filling any fields. This ensures that you have the correct default values for unused fields.

Not all systems that support fonts support this function. See the WFONT-SUPPORTED operation above for details.

Parent topic: W$FONT


WFONT-DATA

The fields of WFONT-DATA are used as follows:

WFONT-DEVICE This item identifies the device that a font is associated with. When a font is associated with a particular device, it should not be used on another device, because these results are undefined. Under Windows, fonts can be shared between devices, but the size is incorrect, because Windows fonts are internally stored with their sizes represented in pixels/device-units instead of points. For example, using a screen font that is 15 pixels high on a laser printer (with 300 or 600 dpi) produces tiny letters. All settings of WFONT-DEVICE are machine-dependent except for the following:
WFDEVICE-CONSOLE | This setting (default value "NULL") associates the font with the user's screen.
WFDEVICE-WIN-PRINTER | This setting (default value "1") is meaningful only under Windows systems. It associates the font with the currently selected printer for the Windows spooler. If you are using WIN$PRINTER, this item must be set to "true" before you call W$FONT.
WFONT-NAME | This item holds the face name of the font. This name is case-sensitive and may contain internal spaces. When asking for a font, you must match its name exactly. If this item is set to spaces, then any font is allowed to match. Under Windows, some common True Type font names are "Courier New", "Times New Roman", and "Arial".
WFONT-SIZE | This item holds the size, in points, of the font's characters. A value of zero allows for any size font. In that case, the size chosen by the system may or may not be useful. If you are not certain which size to choose, start with "10" and adjust from there.
WFONT-BOLD | When this item is set to TRUE, the font is a boldface font.
WFONT-ITALIC | When this item is set to TRUE, the font is italic. Note that under Windows, most controls have difficulty displaying italic fonts correctly.
WFONT-UNDERLINE | When this item is set to TRUE, the font is underlined.
WFONT-CHAR-SET | This item defines the character set to use. A font's character set includes the internal representations used for each character. The possible settings are as follows:
WFCHARSET-DONT-CARE | This allows for any character set. When returned by a call to WFONT-DESCRIBE-FONT, it indicates that the font's character set is unknown or does not correspond to one of the following settings. When requesting a specific font, use this setting only if you are certain that the face name you are requesting uses the character set you want. This may be necessary when you are asking for a font that uses a character set other than any of the following (as might be true for some oriental character sets).
WFCHARSET-DEFAULT | This setting corresponds to a host-dependent default character set. This is the character set most commonly used by the host system. Under Windows, this is the ANSI character set. If you are not certain which setting of WFONT-CHAR-SET to use, use this one.
WFCHARSET-WIN-OEM | This setting is meaningful only under Windows. It corresponds to the host hardware's "OEM" character set. For IBM-style PCs, this is the traditional MS-DOS character set. This is the same character set used by the built-in font "TRADITIONAL-FONT".
WFCHARSET-WIN-name The following settings are meaningful only in a Windows environment. They correspond to various character sets supported by Windows fonts (where name is the supported font name from the list below). You may select the character set directly in the "script" portion of the font chooser dialog box. Note that most fonts only support a subset of these character sets.
  • WFCHARSET-WIN-SYMBOL
  • WFCHARSET-WIN-SHIFTJIS
  • WFCHARSET-WIN-HANGUL
  • WFCHARSET-WIN-GB2312
  • WFCHARSET-WIN-CHINESEBIG5
  • WFCHARSET-WIN-JOHAB
  • WFCHARSET-WIN-HEBREW
  • WFCHARSET-WIN-ARABIC
  • WFCHARSET-WIN-GREEK
  • WFCHARSET-WIN-TURKISH
  • WFCHARSET-WIN-VIETNAMESE
  • WFCHARSET-WIN-THAI
  • WFCHARSET-WIN-EASTEUROPE
  • WFCHARSET-WIN-RUSSIAN
  • WFCHARSET-WIN-MAC
  • WFCHARSET-WIN-BALTIC
WFONT-STRIKEOUT | When this item is set to TRUE, the font is struck-out (i.e., has a line running horizontally through the middle of the characters).
WFONT-FIXED-PITCH | When this item is set to TRUE, the font is fixed-pitch. This means that each character in the font is the same width.
WFONT-FAMILY | This item describes the look of the font in very general terms. It is used to aid in selecting a font when WFONT-NAME is not specified or not found. No font is ever rejected because it does not match the requested family. Usually this field can be set to WFFAMILY-DONT-CARE, but specifying other choices can be useful when you don't know what fonts are on a system and you want to find one close to a specific font. Some graphical systems do not have the concept of font families. On these systems, the value of this field is ignored. The possible values of WFONT-FAMILY are:
WFFAMILY-DONT-CARE | This setting allows for any font family. When set by WFONT-DESCRIBE-FONT, it indicates that the font family is unknown or does not match any of the following possibilities.
WFFAMILY-MODERN | This setting indicates a font with a constant stroke width. These fonts are typically fixed-pitch, but need not be. Example fonts are "Courier" and "Elite".
WFFAMILY-ROMAN | This setting indicates a font with variable stroke width and serifs. Example fonts include "Times Roman" and "New Century Schoolbook".
WFFAMILY-SWISS | This setting indicates a font with variable stroke width and no serifs. Example fonts include "Helvetica" and "MS Sans Serif".
WFFAMILY-SCRIPT | This setting indicates a font designed to look like handwriting. Example fonts are "Script" and "Comic Sans MS".
WFFAMILY-DECORATIVE | This setting indicates a font for decorative or novelty purposes. "Old English" is an example of such a font.
WFONT-ANGLE | This item holds a value specifying the angle at which the font will print. The value can range from the default of "0", which is the normal horizontal orientation, to "360", which is the same as "0". For example, to print at a 45-degree angle, set WFONT-ANGLE to "45". To print upside down, set it to "180". Any font supported by the destination printer can be loaded with this setting. This feature works only when printing a font, not when displaying a font on screen. Note: You should use the WINPRINT-SET-CURSOR operation of W$PRINTER to set the position of the cursor prior to making a WRITE statement using this feature.
WFONT-CHOOSE-FLAGS | This item modifies the behavior of WFONT-CHOOSE-FONT based on the following settings. You can set any combination of these by adding together the corresponding values (all contained in "fonts.def"):
WFCHOOSE-FIXED-ONLY | This setting allows the user to select only a fixed-pitch font. Otherwise, any font can be chosen.
WFCHOOSE-INITIALIZE | This setting causes the various fields of the dialog box to be initialized based on the values contained in WFONT-FACE-DATA. Otherwise, the fields will have no initial value.
WFCHOOSE-EFFECTS-OK | This setting causes the special-effects section of the dialog box to appear. This section allows the user to select the following traits: underline, strike-out, and color. If it's not set, then this section does not appear in the dialog box.
WFCHOOSE-ANSI-ONLY As Windows has evolved, the fonts listing in the W$FONT dialog no longer contains only ANSI fonts. While UNICODE fonts may be used with ACUCOBOL-GT, using them relies on translation back and forth between locales, a process the COBOL programmer has no means of influencing. For COBOL programmers who want to let their users have the liberty of selecting fonts, it is therefore beneficial to limit the fonts to ANSI fonts only.

This setting allows the user to select only ANSI fonts. Otherwise any font can be chosen. This flag can be used in combination with any other flag value.

Note that this flag is for use with the WFONT-CHOOSE-FONT operation only. Default value is off. Programmers must make an active choice, e.g. turn this flag on, to get the functionality.

Prior to the call to W$FONT set the flag:

MOVE WFCHOOSE-ANSI-ONLY
TO WFONT-CHOOSE-FLAGS
CALL "W$FONT" USING
WFONT-CHOOSE-FONT,
NULL, WFONT-DATA

If you have used one of the other flags for WFONT-CHOOSE-FLAGS, you can combine it with this new setting by adding instead of moving:

ADD WFCHOOSE-ANSI-ONLY TO WFONT-CHOOSE-FLAGS

WFONT-CHOOSE-MIN-SIZE | This item, when set to a positive value, specifies the minimum font size (in points) that the user can choose.
WFONT-CHOOSE-MAX-SIZE | This item, when set to a positive value, specifies the maximum font size (in points) that the user can choose. When it's set to zero, no maximum is established.
WFONT-CHOOSE-RED | This item is used only when the WFCHOOSE-EFFECTS-OK flag is set. It returns the red component of the color chosen. This is a number in the range of "0" to "255". See the W$PALETTE Routine for ways to use this value. On systems that do not support palettes, this value is always zero.
WFONT-CHOOSE-GREEN | This item is similar to WFONT-CHOOSE-RED, except it returns the green component of the color.
WFONT-CHOOSE-BLUE | This item is similar to WFONT-CHOOSE-RED, except it returns the blue component of the color.
WFONT-CHOOSE-COLOR-NUM | This item is used only when the WFCHOOSE-EFFECTS-OK flag is set. It returns the ACUCOBOL-GT color number (in the range of "1" to "16") if the color chosen by the user corresponds to a color in the current window's palette. If it does not, then this value is set to zero. Non-zero values can be used directly in the COLOR phrase of a screen item to get the correct color.

Parent topic: W$FONT


Error Handling

The following values are returned by various operations when an error occurs. All error values are less than or equal to zero.

Error | Description
WFONTERR-UNSUPPORTED | This error indicates that the current host system does not use fonts and the W$FONT routine is not supported.
WFONTERR-CANCELLED | This error indicates that the dialog box used by WFONT-CHOOSE-FONT was canceled by the user.
WFONTERR-FONT-NOT-FOUND | This error indicates that no font was found that matched the requested font.
WFONTERR-INVALID-HANDLE | T his error indicates that the value in FONT-HANDLE does not correspond to an existing font.
Parent topic: W$FONT


W$FORGET

The W$FORGET routine causes the ACUCOBOL-GT Terminal Manager to reinitialize itself.

Usage

CALL "W$FORGET"

Description

The exact effects of this routine depend on the host machine, but include such things as setting the current screen image to unknown, repositioning the cursor to the last line on the screen, and placing the current screen attribute to unknown. Note that once the current screen image is forgotten, any pop-up windows that you create afterwards will act as if the original screen image were spaces. This may erase some portions of the screen when you close those windows.

The reasons for calling this routine are fairly specialized. This routine allows the window manager to function correctly when the user's screen has been changed in ways that the window manager is unaware of. Since the window manager keeps an exact image of the user's screen, it must manage every change to the screen itself. If it does not, then you must tell it to forget its current screen image. You can use this routine to restart the window manager after a sequence of ANSI-style ACCEPT or DISPLAY statements.

Parent topic: General Syntax and Library List


W$GETC

The W$GETC routine retrieves the next keystroke from the user and returns it to the program. The keystroke is not echoed. Use this routine when you require detail management of the keyboard.

In the current implementation, W$GETC does not interact well with event procedures. You should avoid using W$GETC if you use event procedures at the same time. In this case, you can use single character ACCEPT statements instead.

Usage

CALL "W$GETC"
    USING KEY-FOUND

Parameter

KEY-FOUND PIC X(2)

Description

W$GETC places the keystroke found into its single parameter. If the character is a single 8-bit value, the first character of the return value is a space and the second character is the character typed. For example, if the user types an A, the return value will be a space followed by A.

If the key typed is a special character such as a function key or the operating system's backspace key, W$GETC returns the two-character keycode found in the ACUCOBOL-GT User's Guide Table of keys Topic. For example, if the user types function key 5, the return value will be k5.

Finally, if an end-of-file condition occurs, then W$GETC returns the two-character sequence -1.

Parent topic: General Syntax and Library List


W$GETURL

W$GETURL works with the Web Runtime. It tells the runtime to pass a given URL (Uniform Resource Locator) to the host browser. The browser handles this URL as if it were typed into the URL entry field. After a CALL to W$GETURL, subsequent URL requests are ignored until the CALL completes. See the Acucorp manual A Programmer's Guide to the Internet for a description of the Web Runtime.

Usage

CALL "W$GETURL"
    USING URL, TARGET

Parameters

URL PIC X(n) | Contains the complete URL. This can be of any type, such as http, ftp, news, mailto, gopher, or javascript.
TARGET PIC X(n) | Represents the destination for displaying the URL. This can be the name of a window or a frame, or one of several special target names. If you specify _current or _self or _top, the response data is written to the browser window, and the Web Runtime is unloaded. If you specify _new or _blank, the response data is written to a new browser window. You can also write the response data to a frame by specifying the frame name as the target parameter.

Comments

After a CALL is made to W$GETURL, subsequent URL requests are ignored until the CALL completes.

Description

Each URL that you pass with the W$GETURL routine contains a protocol and a path, separated by a colon. For example, http://www.acucorp.com/ tells the browser to use the HyperText Transfer Protocol and to contact the Web server www.acucorp.com and to ask for the root page (/).

Sending e-mail uses themailto protocol. For example, mailto:support@acucorp.com opens an e-mail message to the user support at the machine acucorp.com.

JavaScript is also supported as a protocol, so you can execute JavaScript sequences that display dialog boxes, create Web pages, build text files, and so forth.

Note: This routine is available only when the calling COBOL program is running in a Web browser window via the ACUCOBOL-GT Web Runtime. The routine is not available to programs run by the standard runtime when the standard runtime is executed by a Web browser. The RETURN-CODE register is set to 1 after a successful call and set to "0" if this routine is unavailable.
Parent topic: General Syntax and Library List


W$KEYBUF

This routine lets you add characters to the runtime's keyboard input buffer. This allows a program to simulate user input.

Usage

CALL "W$KEYBUF"
    USING OP-CODE, parameters

Parameters

OP-CODE PIC 9(2) Vary depending on the op-code chosen

Description

The first parameter to W$KEYBUF is a number that determines the action of the routine. The following options are supported:

op-code | Description
1 | Use op-code 1 to add keystrokes to the keyboard input buffer. In this case, the second parameter to W$KEYBUF specifies the key or keys you want to add. Optionally, you may also specify a third parameter that contains the number of characters you want to add. If you omit the third parameter, then all of the second parameter is used (including any trailing spaces). When keystrokes are added to the input buffer, they are placed after any previously added keystrokes, but before any keys typed by the user. This ensures that the user does not interfere with your programmatic control.
2 | This is the same as 1 except that the characters are added at the beginning of the input buffer instead of at the end.
3 | Use op-code 3 to empty the input buffer. This can be useful in some error handling routines. Note that this routine does not empty the operating system's input buffer--any keys queued up by the user are still available. Only keys added with W$KEYBUF are removed.
4 | Op-code 4 turns on the keystroke recording mechanism. You must pass as a second parameter the name of a buffer in which you want to place the recorded keystrokes. The buffer is a field you have defined in the Data Division. The size of this buffer limits the number of keystrokes recorded. You may optionally pass a third parameter that is the size of the buffer. If you omit the third parameter, then the entire buffer is used. The keystroke recorder does not initialize the buffer, and it does not modify any part of the buffer that follows the last recorded keystroke.
5 | Op-code 5 turns off the keystroke recorder. This action sets RETURN-CODE to the number of characters used in the buffer to hold the recorded keystrokes.
6 | Op-code 6 inquires whether or not the keystroke recorder is active. This will set RETURN-CODE to 1 if keystroke recording is currently turned on. If it is turned off, then RETURN-CODE will be set to 0.
7 | Op-code 7 causes keys typed by the user to be recorded in a file. You pass the name of the file as the first parameter after the op-code. If that file exists, it is deleted first. If the file is successfully created, then RETURN-CODE is set to zero. If the file cannot be created, then RETURN-CODE is set to 1. You use op-code 5 to turn off the recording. Only one recording mode can be active at once, so this op-code will cancel any other active keystroke recording. In thin client environments, keys typed by the user are recorded in a temporary local file. That file is automatically uploaded to the server when recording is stopped with op-code 5.
8 | Op-code 8 is identical to op-code 7, except that the file is appended to if it already exists. In thin client environments, the file is downloaded from the server to the client, appended to, and then uploaded to the server with op-code 5.
9 Op-code 9 causes a previously recorded file to be played back. The keystrokes recorded in that file are treated as input from the user. The file name is passed as the first parameter after the op-code. RETURN-CODE is set to zero if the file is opened successfully, otherwise RETURN-CODE is set to 1. Keystrokes inserted into the keyboard buffer using op-codes 1 or 2 of W$KEYBUF are processed before the keystrokes recorded in the file. Once the keystrokes in the file have all been used, control passes back to the user's keyboard.

In thin client environments, this op-code first tries to open the file on the client machine using the path specified in the CALL statement. If the file is not found, the thin client requests that the file be downloaded from the server. In this case the path specified in the CALL statement refers to the server machine's file system. The specified path can be an absolute path or a path relative to the current working directory, as specified in the alias file. If the file is found, it is downloaded to the client machine and stored in the thin client's temporary cache directory (the directory specified by the TEMP environment variable; often C:\WINDOWS\TEMP. If the TEMP environment variable is not set, the files are stored in the client's current working directory. The file is not downloaded again unless it changes or is deleted from the client.

Note: There is a runtime command-line option that causes the immediate playback of a keystroke file. This option, -k, causes the next command-line argument to be treated as the name of a file that contains recorded keystrokes. The runtime internally calls W$KEYBUF using op-code 9 and this file name prior to executing the first COBOL program. The effect is that the keystrokes recorded in the file are treated as the runtime's first user input.
10 Op-code 10 allows you to specify how long the system waits after each simulated keystroke is processed. The delay, expressed in hundredths of a second, is passed as the second parameter. For example, to add a quarter-second delay to each keystroke, use the following:
     CALL "W$KEYBUF" USING 10, 25
You can terminate a pause early by pressing any key.
11 | Op-code 11 defines a key that causes the playback to pause for an indefinite time period, allowing you to explain a special feature. The playback resumes when another key is pressed. To designate the pause key, use op-code 11 with the ASCII value of the key. Note that you can only define a pause key that is a simple ASCII key, not a complex key like a function key.
12 | Op-code 12 defines a key that stops the playback and returns the program to interactive mode. Use op-code 12 with the ASCII value of the cancel key.

Special keystrokes

You may specify special keystrokes by placing code names in curly braces. Within curly braces, you may use the caret (^) to indicate Control characters or the "at" symbol (@) to indicate ALT characters. For example, "{^M}" indicates Control+M and "{@L}" indicates ALT+L.

You may also use a special key's two-character name as found in Table of Keys in the ACUCOBOL-GT User's Guide. For example, you may refer to function key 2 with "{k2}".

Menu selections are encoded as {m#} where "#" is the numeric ID of the menu item.

You may insert specific pauses in a simulated input stream using the following character sequences:

{p#} | where # is in hundredths of a second
{P#} | where # is in seconds
{P} | 1-second pause

A programmed pause also includes any pause introduced by op-code 10, described above. You can terminate a pause early by pressing any key.

Finally, if you require an opening curly brace on its own, specify it twice. For example: {{.

The following line specifies that the next characters processed should be abc, Tab, def, and function key 1:

CALL "W$KEYBUF" USING 1, "abc{^I}def{k1}".

The keystroke recording mechanism records normal keys as native characters. The keystroke recorder will not record a time out event.

In order to operate correctly with graphical controls on Windows systems, the W$KEYBUF routine converts characters placed into the keyboard buffer into keyboard scan codes. Thus, you can use only those characters that have a corresponding keyboard scan code. As a result, you can play back non-English characters only when you have installed a keyboard that contains those characters.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.

Parent topic: General Syntax and Library List


W$MENU

You construct and control menus with the W$MENU library routine. You use the CALL statement to access this routine.

Usage

CALL "W$MENU"
    USING OP-CODE, parameters,
    GIVING WMENU-RESULT

Parameters

OP-CODE Numeric parameter | This indicates the desired operation. Level 78 symbolic names for these operations can be found in acugui.def.
parameters | Vary depending on the op-code chosen
WMENU-RESULT PIC S9(9) | Holds the return value from W$MENU. A value of zero indicates failure for all operations.

Description

The routine takes one or more parameters, which are always passed BY REFERENCE (the default in COBOL). The first parameter is always an operation code. This code defines what the routine will do. The remaining parameters depend on the operation selected. The operation codes are defined in the COPY file acugui.def. The available codes are described here:

OP-CODE Numeric parameter | This indicates the desired operation. Level 78 symbolic names for these operations can be found in acugui.def.
parameters | Vary depending on the op-code chosen
WMENU-RESULT PIC S9(9) | Holds the return value from W$MENU. A value of zero indicates failure for all operations.
WMENU-NEW | This operation constructs a new empty menu bar. W$MENU returns a handle for this menu bar in the special register WMENU-RESULT. This handle should be stored in a variable declared as PIC S9(9) COMP-4. All future references to this menu bar are made with this handle. This operation can fail if the system runs out of memory. In this case, WMENU-RESULT will be set to zero.
WMENU-NEW-POPUP | This operation constructs a new empty pop-up menu. W$MENU returns a handle for this menu in the special register WMENU-RESULT. This handle should be stored in a variable declared as PIC S9(9) COMP-4. All future references to this pop-up menu are made with this handle. This operation can fail if the system runs out of memory. In this case, WMENU-RESULT will be set to zero. This option is available for Windows systems only.
WMENU-POPUP | This operation displays a pop-up menu and gets the user's response. After the user makes a selection, the pop-up menu is removed. (This is not the typical way to display a pop-up window. It is easier to assign the pop-up menu to a window or control and let the runtime handle activation.) The second parameter passed in conjunction with this operation code is the handle of the pop-up menu to show. The next two parameters are optional. If they are omitted, the menu appears where the mouse is currently located. If specified, they are the row and column (respectively) of the location where the menu should appear. This is expressed in screen base units (pixels under Windows), with 1,1 being the upper left corner of the physical screen. The user's response is sent to the current window and is treated as if it were a regular entry from the widow's menu bar. This option is available for Windows systems only.
WMENU-DESTROY | You must pass the handle of a valid menu as the second parameter. That menu is destroyed and all memory it occupies is released. Any submenus that it contains are also destroyed. If the menu is currently being displayed, it is removed from the screen first. After destroying a menu, you must not use it any more. You should not destroy a submenu directly–use the WMENU-DELETE operation instead.
WMENU-DESTROY-DELAYED | You must pass the handle of a valid menu as the second parameter. If that menu is not being displayed, the menu is destroyed and all memory it occupies is released. Any submenus that it contains are also destroyed. If the menu is currently being displayed, it is not destroyed immediately. Instead, it is marked for destruction later. It is actually destroyed immediately after the next WMENU-SHOW operation. After destroying a menu, you must not use it any more. You should not destroy a submenu directly–use the WMENU-DELETE operation instead.
WMENU-ADD Adds a menu item to a menu. This operation takes several parameters. Note that all of the parameters are passed as integers (either USAGE DISPLAY or COMP-4) except for the text parameter, which is alphanumeric. You must use WMENU-SHOW to display an altered menu at the top level.

The parameters are, in order:

  • Handle - This is the handle of the menu to which you are adding the item.
  • Position - This is the location at which you want to place the new item. If this value is zero, then the item is appended to the menu. Otherwise, this value is the ID of the item in front of which you want to insert the new item.
  • Flags - This is a combination of one or more of the following:
    • W-CHECKED - indicates that a check mark should be placed beside the item. Check marks appear only on submenus.
    • W-DISABLED - indicates that the item may not be selected. It will appear gray on the menu.
    • W-SEPARATOR  - indicates that this item consists of a bar that separates items on the menu. This item may not be selected by the user. The text field is ignored for this item. Separator bars may appear only on submenus.

    You may combine flags by adding their values together. Values are defined in the file acugui.def. The default value is 0, which indicates an enabled, unchecked menu item.

  • Text - This is the text of the menu item that will appear on the menu bar. Text is limited to 50 characters. The text will appear exactly as you specify it, so be sure to use the desired case. (Graphical environments typically have conventions that you may want to follow, for consistency with other applications. For example, under Windows it is conventional to capitalize the first letter of each major word in a menu item.)

    You may place an "&" symbol in front of the letter you want to use as the key letter for this menu item. The user can select this menu item by pressing <Alt> and typing its key letter. The key letter typically appears underlined on the menu (you can change this appearance; see the topic Menu Configuration With the Generic Menu Handler in ACUCOBOL-GT User Interface Programming).

    If you omit the "&" symbol, no underline will appear, and the first letter of the item will be used as the item's key letter. If the same key letter represents more than one item, and a user types that letter, the system will highlight the next menu item with that key letter and will wait for the user to confirm the selection by pressing <return>. If flags contains the W-SEPARATOR option, you should either omit this parameter or pass NULL.

  • Id - This is an unsigned integer less than or equal to 4095 that you will use to identify this menu item. Use this ID anytime you need to refer to this menu item. This is the ID that's returned to your program when the item is selected by the user. Assign a unique ID to each item in a particular menu hierarchy. Normal (text) menu items must be given an ID. Submenu names and separator bars may optionally be given an ID of zero. These become anonymous menu items that you may never refer to again. If this parameter is omitted, an ID of zero is used.
  • Submenu - This parameter is omitted or set to zero for normal menu items and separator bars. You can create a submenu by setting this value to the handle of another menu. When the user selects this item, that other menu will pop up. Pop-up menus are placed down and to the right, unless they fit better in another position.
WMENU-CHANGE | This operation takes the same parameters as WMENU-ADD (handle, position, flags, text, id, and submenu). The position parameter must not be zero. It indicates the ID of the menu entry you want to change. That entry is deleted and the entry described by the current parameters is inserted in the same location. If the item that you are replacing is a submenu, that submenu's entries are also destroyed. If you change the main menu bar, you must use WMENU-SHOW to display the changed menu.
WMENU-DELETE | Pass the handle of a menu as the second parameter, and the ID of an entry in that menu as the third parameter. The indicated entry is removed by this operation. If the deleted item is a submenu name, the submenu is also destroyed. If you change the main menu bar, you must use WMENU-SHOW to display the changed menu.
WMENU-CHECK | This operation places a check mark in front of a menu item. You pass two additional parameters: the handle of the menu and the ID of the item you want to change. Only items that appear in submenus can have check marks.
WMENU-UNCHECK | Use this operation to remove a check mark from a menu item. The second and third parameters are the handle of the menu and the ID of the item you want to change.
WMENU-DISABLE | Use this operation to disable individual menu items. Disabled menu items are displayed with gray text. The second and third parameters are the menu's handle and the ID of the item you want to disable. You may disable items that appear on the top level of the menu. If you disable a submenu, then access to the submenu's items is denied. If you change the main menu bar, you must use WMENU-SHOW to display the changed menu. If you call W$MENU using this option, and pass the menu's main handle, without specifying an item on the menubar, the entire menu bar is disabled.
WMENU-ENABLE | Use this operation to enable a menu item. The second and third parameters are the menu's handle and the menu item's ID. If you change the main menu bar, you must use WMENU-SHOW to display the changed menu.
WMENU-SHOW Use this operation to display a menu bar on the screen. The first parameter after the op-code is the handle of the menu bar to show. The second parameter (optional) is the handle of the window on which to display the menu. If the second parameter is omitted, the menu is displayed on the current window. Use this operation both to display the menu bar initially and to display any changes made to the top level of the menu.

For example, if you disable one of the top-level menu items, then you must use WMENU-SHOW to make that change visible. If the application already has another menu bar showing when you call WMENU-SHOW, then that menu bar is removed. It is not destroyed--you may re-use that menu bar again later. If you pass a menu handle of zero, then any existing menu bar is removed and no new menu bar is shown, so passing a menu handle of zero is a way to clear all menu bars off the screen.

WMENU-REFRESH | Use this operation to redraw an existing menu. This is typically used to restore a menu that has been overwritten by an external piece of software. For example, if you called the SYSTEM library routine to display the current directory, the directory listing might overwrite the menu. Use WMENU-REFRESH to redraw the menu when you are ready to see it again.
WMENU-GET-MENU | Sets WMENU-RESULT to the handle of the currently displayed menu. This returns zero if no menu is currently displayed. Use this in routines that need to save the current menu bar before replacing it with their own menu.
WMENU-RELEASE This operation logically removes the menu from the screen, but doesn't update the screen. The menu is still visible, but not operational. This makes the entire screen available to your program, but doesn't scroll the current screen contents. This is occasionally useful when you need to remove a menu bar and clear the entire screen. If you instead use WMENU-SHOW to remove the menu bar, you'll have additional screen activity as it removes the menu bar and (if that bar was static) scrolls the screen. The screen update isn't needed if you are going to clear the whole screen anyway.

Under Windows, this function blocks the menu bar, but leaves it in place. The runtime uses this function just prior to shutting down.

This operation takes no parameters.

WMENU-GET-CONFIGURATION | Returns the generic menu handler's current configuration. You must pass it one parameter that has the layout described in the next section. This gets filled in with the current configuration. This operation sets WMENU-RESULT to 1 if the configuration was retrieved. It sets WMENU-RESULT to 0 if the host machine does not use the generic menu handler. In this case, the configuration information is not used and is meaningless.
WMENU-SET-CONFIGURATION You must pass one parameter to this operation that has the layout described in the next section. It causes this parameter to become the current configuration for the generic menu handler. It sets WMENU-RESULT to 1 if the generic menu handler is being used, or 0 if it is not. In the latter case, the configuration will not be used.

If you have a menu displayed when you change the configuration, you should immediately use WMENU-SHOW to update that menu. Alternately, you may use WMENU-SHOW to remove that menu and display a new menu with the new configuration. If you have a menu displayed and change the configuration, you can get undefined results if you fail to use WMENU-SHOW.

WMENU-BLOCK | This inhibits the menu. It works by maintaining a blocking-count. Initially, the blocking-count is set to zero. This call adds one to the blocking-count. Anytime the blocking-count is greater than zero, the user will not be allowed to use the menu. This is typically used by modal routines that need to ensure that the user completes some action before continuing. For example, if you are prompting for a file name, you might want to disable the menu until the user has entered a name. See also WMENU-UNBLOCK, WMENU-GET-BLOCK, and WMENU-SET-BLOCK.
WMENU-UNBLOCK | If the blocking-count is currently greater than zero, this subtracts one from the blocking-count. If this results in the blocking-count reaching zero, then the user will once again be able to use the menu. See also WMENU-BLOCK, WMENU-GET-BLOCK, and WMENU-SET-BLOCK.
WMENU-GET-BLOCK | Sets WMENU-RESULT to the current blocking-count. This is typically used by routines that need to save the current menu state before replacing the menu with their own menu. They can save the blocking-count, set it to zero (with WMENU-SET-BLOCK), and then reset to the saved state when they exit. For example, the ACUCOBOL-GT debugger uses this call when replacing the application menu with its own menu. See also WMENU-BLOCK, WMENU-UNBLOCK, and WMENU-SET-BLOCK.
WMENU-SET-BLOCK Sets the blocking-count to the value of the second parameter. Use this in conjunction with WMENU-GET-BLOCK to save and restore the current blocking-count. See also WMENU-BLOCK, WMENU-UNBLOCK, and WMENU-GET-BLOCK.

The W$MENU routine always sets WMENU-RESULT. Except as described above, this is either 1 to indicate success or 0 to indicate that the operation failed.

The ACUCOBOL-GT generic menu handler allows you to configure several aspects of its look and feel. This is done with get/set configuration operations described in the previous section. For both of these operations, you must pass a parameter that has the following layout:

01 MENU-CONFIGURATION.
   03 MENU-STYLE                         PIC 9 COMP-X.
      88 MENU-IS-STATIC                  VALUE 0.
      88 MENU-IS-POPUP                   VALUE 1.
   03 MENU-CHECK-MARK                    PIC X.
   03 MENU-SUBMENU-MARK                  PIC X.
   03 MENU-COLOR-ATTRIBUTES.
      05 MENU-NORMAL-COLOR-ATTRIBUTES.
         07 MENU-NORMAL-COLOR            PIC 9(4) COMP-X.
         07 MENU-NORMAL-COLOR-KEY-1      PIC 9(4) COMP-X.
         07 MENU-NORMAL-COLOR-KEY-2      PIC 9(4) COMP-X.
      05 MENU-SELECTED-COLOR-ATTRIBUTES.
         07 MENU-SELECTED-COLOR          PIC 9(4) COMP-X.
         07 MENU-SELECTED-COLOR-KEY-1    PIC 9(4) COMP-X.
         07 MENU-SELECTED-COLOR-KEY-2    PIC 9(4) COMP-X.
      05 MENU-DISABLED-COLOR-ATTRIBUTES.
         07 MENU-DISABLED-COLOR          PIC 9(4) COMP-X.
         07 MENU-DISABLED-COLOR-KEY-1    PIC 9(4) COMP-X.
         07 MENU-DISABLED-COLOR-KEY-2    PIC 9(4) COMP-X.
   03 MENU-MONO-ATTRIBUTES.
      05 MENU-NORMAL-MONO-ATTRIBUTES.
         07 MENU-NORMAL-MONO             PIC 9(4) COMP-X.
         07 MENU-NORMAL-MONO-KEY-1       PIC 9(4) COMP-X.
         07 MENU-NORMAL-MONO-KEY-2       PIC 9(4) COMP-X.
      05 MENU-SELECTED-MONO-ATTRIBUTES.
         07 MENU-SELECTED-MONO           PIC 9(4) COMP-X.
         07 MENU-SELECTED-MONO-KEY-1     PIC 9(4) COMP-X.
         07 MENU-SELECTED-MONO-KEY-2     PIC 9(4) COMP-X.
      05 MENU-DISABLED-MONO-ATTRIBUTES.
         07 MENU-DISABLED-MONO           PIC 9(4) COMP-X.
         07 MENU-DISABLED-MONO-KEY-1     PIC 9(4) COMP-X.
         07 MENU-DISABLED-MONO-KEY-2     PIC 9(4) COMP-X.

A copy of this data item can be found in acugui.def.

When a menu is shown, the current configuration defines how it is presented. The fields have the following meaning:

  • MENU-STYLE - Determines whether the menu is static (value "0) or pop-up (value 1). The default is static.
  • MENU-CHECK-MARK - Sets the character used to display check marks. The default character is an asterisk.
  • MENU-SUBMENU-MARK - Sets the character used to indicate that the item is a submenu. This is not used on the main menu bar. The default character is a greater-than sign.
  • MENU-COLOR-ATTRIBUTES - Defines the display attributes used if the station supports color. This is described in detail below.
  • MENU-MONO-ATTRIBUTES - Defines the display attributes used if the station is monochrome. See below for details.

    Notice that there are two sets of attributes, one for color stations and one for monochrome stations. Within each set, there are three group items that determine the attributes used for a particular case. Using color stations as an example, we have:

  • MENU-NORMAL-COLOR-ATTRIBUTES - Determines the attributes used for the normal menu items. This is used for the menu's background color along with all items that are not highlighted or disabled.
  • MENU-SELECTED-COLOR-ATTRIBUTES - Determines the attributes used for the currently selected (highlighted) menu items.
  • MENU-DISABLED-COLOR-ATTRIBUTES - Determines the attributes used by disabled menu items.

    Finally, within each group, there are three fields that determine the attributes used for the appropriate menu items. For example, with normal menu items on a color station, we have:

  • MENU-NORMAL-COLOR - This is the attribute used to draw the menu item and its background.
  • MENU-NORMAL-COLOR-KEY-1 - This is the attribute used to draw the key letter in the menu item (if any).
  • MENU-NORMAL-COLOR-KEY-2  - This is used only if MENU-NORMAL-COLOR-KEY-1 contains the underline attribute and the station does not support underlining. In this case, the actual attribute used is determined by this field.

This scheme of having two possible attributes available for the key letter makes it easier to implement a portable set of attributes. Traditionally, key letters are shown underlined, and so underlining is typically used in the KEY-1 attribute. Since many stations do not support underlining, having a second attribute provides a backup system.

Attributes are set using the same scheme as that used for the COLOR phrase in an ACCEPT or DISPLAY statement. The only exception is that the Protected attribute (32768) has a special meaning when used in conjunction with disabled menu items. If you specify protected as the disabled item's color, then disabled items will appear in parentheses on the menu. This helps distinguish them from normal items.

Attribute values are numeric. They represent combinations of colors and other video features such as intensity. You make combinations by adding appropriate values together from these tables:
Color | Foreground | Background
Black | 1 | 32
Blue | 2 | 64
Green | 3 | 96
Cyan | 4 | 128
Red | 5 | 160
Magenta | 6 | 192
Brown | 7 | 224
White | 8 | 256
Attribute | Value
Reverse video | 1024
Low intensity | 2048
High intensity | 4096
Underline | 8192
Blink | 16384
Protected | 32768
  • Color Defaults
  • Monochrome Defaults
Parent topic: General Syntax and Library List


Color Defaults

Type | Main Attribute | Key-1 Attribute | Key-2 Attribute
Normal | Black on Cyan (129) | Black on Cyan, Underlined (8321) | High-intensity White on Cyan (4232)
Selected | White on Blue (72) | White on Blue, Underlined (8264) | High-intensity White on Blue (4168)
Disabled | White on Cyan (136) | White on Cyan (136) | White on Cyan (136)
Parent topic: W$MENU


Monochrome Defaults

The default settings for monochrome attributes are as follows:

Type | Main Attribute | Key-1 Attribute | Key-2 Attribute
Normal | Black on White (257) | Black on White, Underlined (8449) | High-intensity Black on White (4353)
Selected | White on Black (40) | White on Black, Underlined (8232) | High-intensity White on Black (4136)
Disabled | Black on White, Parenthesized (32935) | Black on White (257) | Black on White (257)

The ACUCOBOL-GT debugger always uses the default configuration for its own menu bar.

Parent topic: W$MENU


W$MOUSE

This routine allows you to control the behavior of the mouse. Before using W$MOUSE to respond to mouse actions, be sure that you have unmasked the actions you want to notice (see the topic, House Mouse Actions are Handled).

Usage

CALL "W$MOUSE"
    USING OP-CODE, parameters,
    GIVING MOUSE-STATUS

Parameters

  • OP-CODE Numeric parameter - This indicates the desired operation. Level 78 symbolic names for these operations can be found in the file acugui.def.
    Code | Operation
    0 | TEST-MOUSE-PRESENCE
    1 | GET-MOUSE-STATUS
    2 | GET-MOUSE-SCREEN-STATUS
    3 | SET-MOUSE-POSITION
    4 | SET-MOUSE-SCREEN-POSITION
    5 | SET-MOUSE-SHAPE
    6 | SET-DELAYED-MOUSE-SHAPE
    7 | GET-MOUSE-SHAPE
    8 | CAPTURE-MOUSE
    9 | RELEASE-MOUSE
    10 | ENABLE-MOUSE
    19 | SET-MOUSE-HELP
    23 | SET-MOUSE-POSITION-EX
    24 | SET-MOUSE-SCREEN-POSITION-EX
    25 | SET-MOUSE-POSITION-PIXEL
    26 | SET-MOUSE-SCREEN-POSITION-PIXEL
    parameters - Vary depending on the op-code chosen.
  • MOUSE-STATUS - A numeric data item

    Holds the return value from W$MOUSE. This is used only with the ENABLE-MOUSE, TEST-MOUSE-PRESENCE, and GET-MOUSE-SHAPE operations.

Description

The first parameter you pass to W$MOUSE is an operation code. This code tells W$MOUSE what to do. The number and type of the remaining parameters depend on the operation selected. All parameters are passed BY REFERENCE (the default in COBOL). The operation code can be one of the following:

  • ENABLE-MOUSE (op-code 10)
  • TEST-MOUSE-PRESENCE (op-code 0)
  • GET-MOUSE-STATUS (op-code 1)
  • GET-MOUSE-SCREEN-STATUS (op-code 2)
  • SET-MOUSE-POSITION (op-code 3)
  • SET-MOUSE-POSITION-EX (op-code 23)
  • SET-MOUSE-POSITION-PIXEL (op-code 25)
  • SET-MOUSE-SCREEN-POSITION (op-code 4)
  • SET-MOUSE-SCREEN-POSITION-EX (op-code 24)
  • SET-MOUSE-SCREEN-POSITION-PIXEL (op-code 26)
  • SET-MOUSE-SHAPE (op-code 5)
  • SET-DELAYED-MOUSE-SHAPE (op-code 6)
  • GET-MOUSE-SHAPE (op-code 7)
  • CAPTURE-MOUSE (op-code 8)
  • RELEASE-MOUSE (op-code 9)
  • SET-MOUSE-HELP (op-code 19)
  • Mouse Handling: Sample Code
Parent topic: General Syntax and Library List


ENABLE-MOUSE (op-code 10)

Turns on the mouse on character-based systems. (By default the mouse is invisible.) The value of RETURN-CODE is set to 1 if a mouse is present, 0 if no mouse is found. (Takes no additional parameters.)

On some machines there is an appreciable delay when the mouse is enabled.

Under graphical environments such as Windows, ENABLE-MOUSE is not necessary. It sets the value of RETURN-CODE properly, but no other action occurs, because the mouse is always enabled in these environments.

Parent topic: W$MOUSE


TEST-MOUSE-PRESENCE (op-code 0)

Used to detect the presence of a mouse. The value of RETURN-CODE is set to 1 if a mouse is available on the system. It is set to 0 if no mouse is present. (Takes no additional parameters.) Note that on character-based systems, the mouse must be enabled before its presence can be detected. So if you haven't enabled the mouse (see ENABLE-MOUSE above), RETURN-CODE will have a value of 0.

Parent topic: W$MOUSE


GET-MOUSE-STATUS (op-code 1)

Returns information about the mouse's location and the state of each of its buttons. You must pass a group item with the following structure (defined in acugui.def):

01  MOUSE-INFO.
   03  MOUSE-ROW               PIC 9(4) COMP-1.
       88  MOUSE-OFF-SCREEN    VALUE ZERO.
   03  MOUSE-placeStateCOL               PIC 9(4) COMP-1.
   03  LBUTTON-STATUS          PIC 9.
       88  LBUTTON-DOWN        VALUE 1.
   03  MBUTTON-STATUS          PIC 9.
       88  MBUTTON-DOWN        VALUE 1.
   03  RBUTTON-STATUS          PIC 9.
       88  RBUTTON-DOWN        VALUE 1.
   03  MOUSE-ROW-EX            PIC 9(6)V99 COMP-4, SYNC.
   03  MOUSE-placeStateCOL-EX            PIC 9(6)V99 COMP-4.
   03  MOUSE-ROW-PIXEL         PIC 9(8) COMP-4.
   03  MOUSE-placeStateCOL-PIXEL         PIC 9(8) COMP-4.

The routine fills in this structure with data about the mouse. Each of the three status"fields is set to 1 if the corresponding button is depressed. Otherwise, they are set to zero. The various row and column fields are set to the location of the mouse within the current ACUCOBOL-GT window. If the mouse is outside of the current window, then these values are set to zero.

Here's an example of a call to W$MOUSE that returns the menu item the mouse is pointing to:

* find-mouse-menu-row - returns (in mouse-row)
* the menu item that the mouse pointer is
* currently on. If the mouse is not on a menu
* item, it returns zero.

find-mouse-menu-row.
   call "w$mouse" using get-mouse-status, mouse-info
   if mouse-row >= menu-row and
         mouse-row < menu-row + num-menu-items * 2
      compute mouse-row = mouse-row - menu-row + 1
   else
      move zero to mouse-row.

After an ACCEPT statement is executed, all CALLs to W$MOUSE pertain to that ACCEPT statement, until another ACCEPT is executed. So, you always get the right mouse status. By synchronizing the mouse actions with the appropriate exception values, the runtime ensures that you process the mouse correctly.

Parent topic: W$MOUSE


GET-MOUSE-SCREEN-STATUS (op-code 2)

This function is the same as the GET-MOUSE-STATUS function, except that the row and column coordinates are relative to the application's virtual screen instead of the current window. If the mouse is not located anywhere in the application's window, then the coordinates are set to zero.

Parent topic: W$MOUSE


SET-MOUSE-POSITION (op-code 3)

You must pass a group item with the same structure as described under GET-MOUSE-STATUS. The mouse is placed at the coordinates named by MOUSE-ROW and MOUSE-COL, relative to the current ACUCOBOL-GT window. The button-status fields are not used.

Parent topic: W$MOUSE


SET-MOUSE-POSITION-EX (op-code 23)

You must pass a group item with the same structure as described under GET-MOUSE-STATUS. The mouse is placed at the coordinates named by MOUSE-ROW-EX and MOUSE-COL-EX, relative to the current ACUCOBOL-GT window. These coordinates are similar to MOUSE-ROW and MOUSE-COL, except that the positioning of the mouse is performed using a precision of hundredths of cells. The button-status fields are not used.

Parent topic: W$MOUSE


SET-MOUSE-POSITION-PIXEL (op-code 25)

You must pass a group item with the same structure as described under GET-MOUSE-STATUS. The mouse is placed at the coordinates named by MOUSE-ROW-PIXEL and MOUSE-COL-PIXEL, relative to the current ACUCOBOL-GT window. These coordinates describe the mouse position in terms of the display's base units (which are pixels for graphical systems). Unlike MOUSE-ROW and MOUSE-COL, or MOUSE-ROW-EX and MOUSE-COL-EX, the uppermost pixel is row 0/column "0" instead of row 1/column 1. The button-status fields are not used.

Parent topic: W$MOUSE


SET-MOUSE-SCREEN-POSITION (op-code 4)

This is the same as SET-MOUSE-POSITION, except that the position is relative to the application's virtual screen.

Parent topic: W$MOUSE


SET-MOUSE-SCREEN-POSITION-EX (op-code 24)

The same as SET-MOUSE-POSITION-EX, except that the position is relative to the application's virtual screen.

Parent topic: W$MOUSE


SET-MOUSE-SCREEN-POSITION-PIXEL (op-code 26)

The same as SET-MOUSE-POSITION-PIXEL, except that the position is relative to the application's virtual screen.

Parent topic: W$MOUSE


SET-MOUSE-SHAPE (op-code 5)

The second parameter defines the desired shape of the mouse pointer. The shape is changed immediately, even if the mouse has not been moved. The possible values are:

ARROW-POINTER | The default arrow shape
BAR-POINTER | A vertical bar
CROSS-POINTER | Cross hairs
HELP-POINTER | A question mark
WAIT-POINTER | An hourglass

These are defined in acugui.def. Note that the runtime system changes the shape of the mouse when you are using automatic mouse handling. When an ACCEPT statement finishes execution, the last shape defined by SET-MOUSE-SHAPE is restored.

Parent topic: W$MOUSE


SET-DELAYED-MOUSE-SHAPE (op-code 6)

This is identical to SET-MOUSE-SHAPE, except that the mouse pointer is not changed immediately. Instead, it is changed as soon as the user moves it. The automatic mouse handler uses this function to provide a smoother mouse appearance.

Parent topic: W$MOUSE


GET-MOUSE-SHAPE (op-code 7)

The value of RETURN-CODE is set to the current mouse shape. If SET-DELAYED-MOUSE-SHAPE is in effect, waiting for the mouse to move, then the delayed shape is returned. (Takes no additional parameters.)

Parent topic: W$MOUSE


CAPTURE-MOUSE (op-code 8)

Normally, only mouse actions that occur within the application's virtual screen are processed by the runtime system. (The virtual screen is the drawing space allocated to the application.) Actions that occur outside of this space are handled by other applications or by the environment. The CAPTURE-MOUSE function causes the runtime to process all mouse messages, regardless of where they occur. This should be done only in special cases, because it prevents the user from using the mouse in any other application. Normally, you capture the mouse only when the user is marking or dragging some object on the screen. By capturing the mouse, you can control the action even if the user accidentally moves the mouse outside of the application. (Takes no additional parameters.)

When the mouse is captured, if the mouse is outside of the legal boundaries, the GET-MOUSE-STATUS and GET-MOUSE-SCREEN-STATUS functions no longer return zero in the row and column fields. Instead, the row and column fields contain the nearest legal coordinate to the mouse's actual position.

Parent topic: W$MOUSE


RELEASE-MOUSE (op-code 9)

This reverses the effects of the CAPTURE-MOUSE function. You must call this sometime after calling CAPTURE-MOUSE, or the environment will not be able to use the mouse again. (Takes no additional parameters.)

Parent topic: W$MOUSE


SET-MOUSE-HELP (op-code 19)

When the second parameter is 1, this op-code turns the mouse pointer into a help-mode pointer--the mouse is captured and the pointer takes the shape of a question mark. When the second parameter is 0, the help-mode state is turned off--the mouse is released and the pointer returns to its default shape. This option is only supported under Microsoft Windows.

Note: If you use help automation, you don't need to use this option. Help automation automatically manages the help-mode mouse states for you. See Help Automation in User Interface Programming for more information.
Parent topic: W$MOUSE


Mouse Handling: Sample Code

identification division.
program-id.  mouse-sample.
remarks.
   This program provides an example of programmed
   mouse handling.
data division.
working-storage section.

77  key-entered    pic 9(3).
    88  mouse-button-clicked  value 81, 87.
    88  left-button-clicked   value 81.
    88  right-button-clicked  value 87.

77  menu-selection  pic 9 value 1.
    88  exit-selected  value 9.

77  MOUSE-FLAGS    pic 9(5).
77  pointer-idx    pic 9 value zero.

01  name-array.
  03 name-data.
    05  filler    pic x(9) value "arrow".
    05  filler    pic x(9) value "bar".
    05  filler    pic x(9) value "cross".
    05  filler    pic x(9) value "hourglass".
  03  mouse-name redefines name-data occurs 4    pic x(9).

copy "acugui.def".
screen section.
01  main-screen.
  03  "The Screen", reverse high line 1 col 20.
  03  "Change Pointer", reverse high line 2 col 3.
  03  "Describe Pointer", reverse high line 4 col 3.
  03  "EXIT", reverse high line 6 col 3.
procedure division.
main-logic.

* Test for presence of mouse on system.
    call "w$mouse" using test-mouse-presence.
    if return-code = zero
      display "No mouse present"
      go to main-logic-exit.

* Enable program to recognize left and right button clicks.
    add allow-left-down, allow-right-down giving mouse-flags.
    set environment "mouse-flags" to mouse-flags.

    display main-screen.
    perform main-screen-handling
      until exit-selected.
main-logic-exit.

    stop run.

main-screen-handling.

    accept omitted, line 1, control key in key-entered.

    if mouse-button-clicked
      call "w$mouse" using get-mouse-status, mouse-info
      evaluate mouse-row
        when 2   perform change-mouse-shape
        when 4   perform display-mouse-shape
        when 6   set exit-selected to true
        when other
          display "Clicked"
        end-evaluate.

change-mouse-shape.
    if pointer-idx < 4
      add 1 to pointer-idx
    else
      move 1 to pointer-idx.
    call "w$mouse" using set-mouse-shape, pointer-idx.

display-mouse-shape.
    call "w$mouse" using get-mouse-shape.
  display "Current mouse shape is" mouse-name (return-code).
Parent topic: W$MOUSE


W$PALETTE

In graphical environments, you can customize the basic set of colors that you use in your programs.

ACUCOBOL-GT allows programs to reference 16 distinct colors (8 low-intensity and 8 high-intensity). For most machines, this set of colors is fixed (black, blue, green, cyan, red, magenta, brown, and white). On Windows machines, you can select which 16 colors you will be using. You are given access to a palette of 16 colors that defines which color corresponds to each color number.

You control the palette through the library routine W$PALETTE.

Usage

CALL "W$PALETTE"
    USING OP-CODE, WPALETTE-DATA
    GIVING RESULT

Parameters

OP-CODE Numeric value | Selects which palette function to perform. The operations are described below.
WPALETTE-DATA Group item as follows:
01  WPALETTE-DATA.
    03  WPAL-COLOR-ID    PIC X COMP-X.
    03  WPAL-FLAGS REDEFINES
        WPAL-COLOR-ID    PIC X COMP-X.
    03  WPAL-RED         PIC X COMP-X.
    03  WPAL-USER-COLOR-ID REDEFINES
        WPAL-RED         PIC X COMP-X.
    03  WPAL-GREEN       PIC X COMP-X.
    03  WPAL-BLUE        PIC X COMP-X.

This provides information and holds results for certain operations described below. It may be omitted from those operations that do not use it.

RESULT Signed numeric data item. | Returns the status of the operation. Unless otherwise stated below, 1 indicates success, and a zero or negative result indicates failure.

The WPALETTE-DATA group item and all of the level 78 symbolic names described below can be found in the COPY library palette.def.

Description

W$PALETTE performs a variety of operations depending on the passed OP-CODE. These operations are shown below.

  • WPALETTE-SUPPORTED (op-code 1)
  • WPALETTE-NUM-COLORS (op-code 2)
  • WPALETTE-GET-COLOR (op-code 3)
  • WPALETTE-SET-COLOR (op-code 4)
  • WPALETTE-UPDATE (op-code 5)
  • WPALETTE-CHOOSE-COLOR (op-code 6)
  • WPALETTE-SET-USER-COLOR (op-code 7)
  • Error Handling
Parent topic: General Syntax and Library List


WPALETTE-SUPPORTED (op-code 1)

This determines the level of support the host machine provides for the W$PALETTE routine. Use this to determine if the host machine will allow you to perform certain operations.

WPALETTE-DATA is not used. The RESULT value will be one of the following:

WPAL-NO-SUPPORT (value 0) | This value indicates that the host machine does not support palettes. Only the WPALETTE-SUPPORTED and WPALETTE-NUM-COLORS operations will function. Currently, this result is returned for all platforms other than Windows and Windows NT.
WPAL-PALETTE-SUPPORTED (value 1) | This value indicates that all W$PALETTE functions are supported except for the WPALETTE-CHOOSE-COLOR function.
WPAL-FULL-SUPPORT (value 2) | This value indicates that all W$PALETTE functions are available.
Parent topic: W$PALETTE


WPALETTE-NUM-COLORS (op-code 2)

This operation sets RESULT to the number of distinct solid colors that the host machine can display simultaneously.

WPALETTE-DATA is not used. For monochrome machines, the RESULT value will be 2. For color machines other than Windows, this value will be 16.

For Windows machines, this value will depend on the host hardware and drivers installed. For a standard VGA system, this value will be 16. For Super VGA systems with the proper driver installed, this value can be 256 or higher. If the machine supports more than 32,767 distinct colors, then 32767 will be returned.

For machines with 16 or fewer colors, the standard ACUCOBOL-GT palette represents the entire range of solid (pure) colors. In order to display any other color, that color must be simulated by dithering two or more colors together. Windows allows us to do this, but only for background colors. If you attempt to display a dithered color in the foreground, Windows will automatically substitute the nearest solid color. Dithered background colors can also make the foreground text look ragged, depending on the exact colors used. For this reason, you may want to limit yourself to solid colors. One way to do this is to allow the user to change the palette only when the machine supports 256 colors or more.

Parent topic: W$PALETTE


WPALETTE-GET-COLOR (op-code 3)

This operation retrieves the color that currently corresponds to a particular color number. Colors are numbered 1 through 16. The first 8 colors correspond to the low-intensity colors.

Their initial values are as follows:

1 | Black
2 | Blue
3 | Green
4 | Cyan
5 | Red
6 | Magenta
7 | Brown
8 | White

The second set of 8 colors contains the same colors in their high-intensity forms. To determine the current definition of any color number, move the color number desired into the WPAL-COLOR-ID field of WPALETTE-DATA and call W$PALETTE.

When it returns, the WPAL-RED, WPAL-GREEN, and WPAL-BLUE fields of WPALETTE-DATA will be filled in with the current definition of that color number. Each of these fields will contain a value from 0 to 255 that indicates the intensity of the red, green, and blue components of the color. A red-green-blue (RGB) combination of 0, 0, 0 indicates black. A RGB value of 255, 255, 255 is bright white. Other values cover the entire range of colors possible under Windows.

Parent topic: W$PALETTE


WPALETTE-SET-COLOR (op-code 4)

This function complements WPALETTE-GET-COLOR; it lets you assign a new color to a particular color number. At entry, WPAL-COLOR-ID should contain the color number you want to change. WPAL-RED, WPAL-GREEN, and WPAL-BLUE should contain the RGB value of the new color (see WPALETTE-GET-COLOR for a description of RGB values).

For example, if you want to make color number 2 represent a dark blue-green, you could use the following values:

WPAL-COLOR-ID | 2
WPAL-RED | 0
WPAL-GREEN | 64
WPAL-BLUE | 64
Note: Changing the palette will change the colors currently shown on the screen as well as all future displays. In the previous example, if you had displayed any data (or background) using color number 2, that data would now change to dark blue-green.

The color palette is the lowest level of color handling in the ACUCOBOL-GT system. It defines the basic set of colors used. Although you are free to change the palette as you see fit, ACUCOBOL-GT makes certain assumptions that you should be aware of. First of all, ACUCOBOL-GT assumes that color 1 is always black, and color 16 is always bright white. Likewise, colors 8 and 9 are assumed to be shades of gray. These assumptions affect the rendering of window shadows and 3-D lines. Additionally, the first 8 colors are assumed to be low-intensity, and the second 8 are high-intensity.

ACUCOBOL-GT computes the high- or low-intensity version of a color by adding or subtracting 8 from its color number. This assumption also affects the rendering of 3-D lines if you use them on a colored background. Although you are not required to maintain any of these assumptions, be aware of them so that you can anticipate the total effects of your changes.

Parent topic: W$PALETTE


WPALETTE-UPDATE (op-code 5)

In order to allow you to change several colors efficiently, W$PALETTE does not immediately apply the new palette after you change it. It waits until the next screen update (usually caused by either an ACCEPT or DISPLAY statement). In most cases this is adequate. If you want to force the screen to be updated immediately with the new palette, you can use the WPALETTE-UPDATE function. WPALETTE-DATA is not used. The effect is to update the screen with the new palette and return.

Parent topic: W$PALETTE


WPALETTE-CHOOSE-COLOR (op-code 6)

This operation provides a simple method for getting a color selection from the user. You can use this to simplify the process of constructing your color palette according to your user's desires. When this operation executes, a standard color selection box pops up over your application. This box is similar to the Color Palette portion of the Windows' Control Panel application. It should be familiar to most users.

This box contains a selection of pre-determined colors (called the Basic Colors) that the user can choose from. Windows selects these colors. Typically, there are 48 of them drawn from the entire spectrum (there can be fewer on some systems).

The user can pick one of these by clicking the mouse on it or by using the arrow keys.

Beneath these colors is a set of 16 Custom Colors. Initially, these colors are all white. The user can select the Define Custom Colors option to define new colors. This pulls up a color chart that the user can select from. After selecting a custom color, the user can add it to the set of 16 custom colors by selecting the Add to Custom Colors button. This color is then available for future selection.

The user selects the OK button (or presses <Enter>) to complete selection of the color. The RGB value of the color selected is returned in WPAL-RED, WPAL-GREEN, and WPAL-BLUE.

Alternately, the user can select the Cancel button (or press <escape>). In this case, no color is returned and the value of RESULT is set to WPERR-CANCELLED (see below).

The initial default color selection is black (RGB value 0, 0, 0). You may supply a different default value by moving the desired color into WPAL-RED, WPAL-GREEN, and WPAL-BLUE. You must also set WPAL-FLAGS to WPAL-USE-DEFAULT (value 1). If you do not use this option, then you should set WPAL-FLAGS to zero before calling W$PALETTE.

The color selection box is a standard component of Windows and Windows NT.

Note: In some Windows setups COMMDLG.DLL provides support for the color selection dialog (as well as other standard dialogs). Because ACUCOBOL-GT is used to build applications for use in a variety of nations and languages, Acucorp does not distribute this file. The standard dialogs defined in this DLL contain text that is specific to the local language.
Parent topic: W$PALETTE


WPALETTE-SET-USER-COLOR (op-code 7)

This operation allows you to assign selected system colors to COBOL color numbers. It uses two fields in the WPALETTE-DATA group item.

WPAL-COLOR-ID | contains the number of the COBOL color you want to change. Values range from 1 (low-intensity black) to 16 (high-intensity white).
WPAL-USER-COLOR-ID | contains the number of the system color to use. You can use either WPUSER-COLOR-3D, which matches the system's color for the background of 3-D objects, or WPUSER-COLOR-BACKGROUND, which matches the system's color for window backgrounds. These values are defined in palette.def.

The following example redefines the COBOL color number 8 (which is gray in the default palette) to be the same as the system's 3-D color:

    MOVE 8 TO WPAL-COLOR-ID
    MOVE WPUSER-COLOR-3D TO WPAL-USER-COLOR-ID
    CALL "W$PALETTE" USING
       WPALETTE-SET-USER-COLOR, WPALETTE-DATA

Errors are handled in the same manner as the WPALETTE-SET-COLOR function. Note that under some systems, such as Microsoft Windows, the system colors can change dynamically at runtime. If this occurs, the runtime will automatically remap the colors in the palette as needed to match the new system colors.

For additional color configuration options, see the USER-GRAY, USER-WHITE, and USER-COLORS options of the DISPLAY FLOATING WINDOW verb.

Parent topic: W$PALETTE


Error Handling

RESULT is set to a positive value if the call to W$PALETTE is successful. Except for the WPALETTE-SUPPORTED and WPALETTE-NUM-COLORS operations, the success value is always 1. A zero or negative value indicates a problem. The following values are possible:

WPERR-UNSUPPORTED (value 0) | Either the requested operation cannot be performed on the host system, or you passed an invalid operation code.
WPERR-BAD-ARG (value -1) | Either you did not pass WPALETTE-DATA when it was required, or WPALETTE-DATA contains some invalid data.
WPERR-CANCELLED (value -2) | The user selected the cancel operation of the color selection box, or the user closed the selection box.
Parent topic: W$PALETTE


W$PROGRESSDIALOG

This routine provides a general way to show a user how an operation is progressing. It is typically used when deleting, copying, moving, uploading, or downloading large files or a large number of files. It can also be used when performing a time-consuming operation that you want to allow the user to cancel at any time.

Usage

CALL "W$PROGRESSDIALOG"
   USING OP-CODE, parameters
   GIVING WPROGRESS-RESULT.

Parameters

OP-CODE Numeric parameter | This indicates the desired operation. Level 78 symbolic names for these operations can be found in acugui.def.
parameters | Vary depending on the op-code chosen

Description

W$PROGRESSDIALOG provides access to the features of the Windows progress dialog box, which is exposed through the IProgressDialog COM interface. This interface is part of the BROWSEUI.DLL Windows system library and was originally part of Internet Explorer 5.

W$PROGRESSDIALOG can be used to create a modal or modeless window containing a progress dialog, set its title, animation, text lines, progress, and cancel message. The progress dialog can be configured to automatically estimate and display the time remaining until the operation completes.

The progress dialog runs on a background thread. This allows the progress dialog to update its display, estimate the time remaining until the operation completes, and handle the user cancelling the operation independently of the work being done by the COBOL program. The progress dialog updates and remains responsive even during long operations such as C$COPY across a thin client connection. There is no need to set the FILE_IO_PROCESSES_MESSAGES configuration variable.

  • WPROGRESSDIALOG-CREATE (op-code 1)
  • WPROGRESSDIALOG-DESTROY (op-code 2)
  • WPROGRESSDIALOG-SET-PROGRESS (op-code 3)
  • WPROGRESSDIALOG-QUERY-CANCEL (op-code 4)
  • WPROGRESSDIALOG-SET-LINE (op-code 5)
  • WPROGRESSDIALOG-RESET-TIMER (op-code 6)
  • WPROGRESSDIALOG-C-COPY (op-code 7)
Parent topic: General Syntax and Library List


WPROGRESSDIALOG-CREATE (op-code 1)

This operation creates and starts the progress dialog. A handle to the progress dialog is returned in the data item specified in the GIVING clause. This handle should be stored in a variable declared as USAGE HANDLE.

This op-code takes six additional optional parameters, which appear in order below:

title

A literal or data item containing the text that will appear in the title bar of the progress dialog.

cancel-message

A literal or data item containing the text that is shown on line 3 (underneath the progress bar) when the user clicks the Cancel button. Since the progress dialog operates on a separate background thread there will be a delay between the time the user presses the Cancel button and the time the COBOL program calls W$PROGRESSDIALOG WPROGRESSDIALOG-QUERY-CANCEL. Since this delay might be significant, the progress dialog provides the user with immediate feedback by clearing text lines 1 and 2 and displaying the cancel message on line 3. The message is intended to let the user know that the delay is normal and that the progress dialog box will be closed shortly. Typically, it is set to something like Please wait while ....

flags

A numeric literal or data item, which specifies flags that determine the operation of the progress dialog. This can be a combination of the following values:

WPROGRESSDIALOG-NORMAL (value 0) | Normal progress dialog behavior.
WPROGRESSDIALOG-MODAL (value 1) | The progress dialog box will be modal to the current window. By default, a progress dialog box is modeless.
WPROGRESSDIALOG-AUTOTIME (value 2) | Automatically estimate the remaining time and display the estimate on line 3. If this flag is set, WPROGRESSDIALOG-SET-LINE can be used only to display text on lines 1 and 2.
WPROGRESSDIALOG-NOTIME (value 4) | Do not show the "time remaining" text.
WPROGRESSDIALOG-NOMINIMIZE (value 8) | Do not display a minimize button on the dialog box's title bar.
WPROGRESSDIALOG-NOPROGRESSBAR (value 16) | Do not display a progress bar. Normally, an application can quantitatively determine how much of the operation remains and periodically pass that value to WPROGRESSDIALOG-SET-PROGRESS. The progress dialog uses this information to update its progress bar. This flag is typically set when the calling application needs to wait for an operation to finish but does not have any quantitative information it can use to update the dialog box.

animation-type

A numeric literal or data item, which specifies the type of AVI clip that will run in the dialog box. It can be one of the following values:

Data Item | Value
WPROGRESSDIALOG-ANIMATION-NONE | 0
WPROGRESSDIALOG-ANIMATION-FILECOPY | 1
WPROGRESSDIALOG-ANIMATION-FILEMOVE | 2
WPROGRESSDIALOG-ANIMATION-FILEDEL | 3
WPROGRESSDIALOG-ANIMATION-FILEDELR | 4
WPROGRESSDIALOG-ANIMATION-FILENUKE | 5
WPROGRESSDIALOG-ANIMATION-SEARCH | 6
WPROGRESSDIALOG-ANIMATION-FINDCOMP | 7
WPROGRESSDIALOG-ANIMATION-FINDFILE | 8
WPROGRESSDIALOG-ANIMATION-CUSTOM (value 99) | 99

If you specify WPROGRESS-ANIMATION-CUSTOM, there are two additional parameters:

resource-dialog A literal or data item containing the name of a DLL or EXE that includes the AVI file as a resource.
resource-id The resource id of the AVI file in the file specified by resource-dialog.

For example, if you want to use an AVI file named MYANIMATION.AVI that is included as a resource in a DLL named MYRES.DLL with ID 1007, you can specify it with the following parameters:

CALL "W$PROGRESSDIALOG" USING WPROGRESSDIALOG-CREATE
"Title" "Cancel Message"
WPROGRESSDIALOG-MODAL
WPROGRESSDIALOG-ANIMATION-CUSTOM
"MYRES.DLL"
1007
GIVING PD-HANDLE.
Note: The requirement for the AVI file to be a resource is a limitation of the Microsoft IProgressDialog COM interface. There is no provision for loading an AVI file directly.
Parent topic: W$PROGRESSDIALOG


WPROGRESSDIALOG-DESTROY (op-code 2)

This operation destroys the progress dialog box. It takes only one parameter, the handle of the progress dialog returned by WPROGRESSDIALOG-CREATE.

Parent topic: W$PROGRESSDIALOG


WPROGRESSDIALOG-SET-PROGRESS (op-code 3)

This operation updates the progress dialog box with the current state of the work being monitored. It takes three parameters:

handle | The handle of the progress dialog returned by WPROGRESSDIALOG-CREATE.
completed | A numeric literal or data item specifying an application-defined value that indicates what proportion of the work has been completed so far.
total | A numeric literal or data item specifying an application-defined value that specifies what value the 'completed' parameter will have when the work is complete.
Parent topic: W$PROGRESSDIALOG


WPROGRESSDIALOG-QUERY-CANCEL (op-code 4)

This operation checks whether the user has pressed the cancel button. You must periodically use this function to poll the progress dialog box object to determine whether the operation has been canceled.

This operation takes one parameter, the handle of the progress dialog returned by WPROGRESSDIALOG-CREATE. It returns 1 if the user has pressed the cancel button, 0 otherwise, in the data item specified with the GIVING clause or in the special RETURN-CODE register.

Parent topic: W$PROGRESSDIALOG


WPROGRESSDIALOG-SET-LINE (op-code 5)

This operation sets the text lines that are displayed in the progress dialog. It takes three parameters:

string | A data item containing the text to display.
line-num | A numeric literal or data item containing the line number on which the text is to be displayed. This can be either 1, 2, or 3. If WPROGRESSDIALOG-AUTOTIME was specified in the flags parameter when the progress dialog was created, then only lines 1 and 2 can be used. The estimated time will be displayed on line 3.
compact-path | A numeric literal or data item whose value is 1 or 0. The default value for this parameter is 1, set it to 0 to turn off path string compaction or the following described behavior. There is a defect in the Microsoft's dialog design of the text string field. If a string is longer than what the field can contain the default behavior is to wrap rather than clip the text. Only the top-most pixels of the wrapped text can be seen and so is cosmetically unpleasing and functionally useless. However, if compact-path is a 1 then text that is too long for the field will be truncated and an ellipsis (...) gets appended to the end of the string. This is better default behavior for ACUCOBOL-GT programmers. Note: This parameter has no effect on strings or paths less than the field width.
Parent topic: W$PROGRESSDIALOG


WPROGRESSDIALOG-RESET-TIMER (op-code 6)

This operation resets the progress dialog box timer to zero. It takes one parameter, the handle of the progress dialog returned by WPROGRESSDIALOG-CREATE.

The timer is used to estimate the remaining time. It is started when your application calls WPROGRESSDIALOG-CREATE. Unless your application will start immediately, it should call WPROGRESS-RESET-TIMER just before starting the work. This practice ensures that the time estimates will be as accurate as possible. This method should not be called after the first call to WPROGRESSDIALOG-SET-PROGRESS.

Parent topic: W$PROGRESSDIALOG


WPROGRESSDIALOG-C-COPY (op-code 7)

This operation specifies that the progress dialog should monitor the progress of the C$COPY when transferring files to or from a remote machine in a thin client environment. It takes one parameter, the handle of the progress dialog returned by WPROGRESSDIALOG-CREATE.

Parent topic: W$PROGRESSDIALOG


W$STATUS

W$STATUS works with the ACUCOBOL-GT Web Runtime. It tells the runtime to display a text message in the browser's status bar. See the Acucorp document, A Programmer's Guide to the Internet, for information about the Web Runtime.

Usage

CALL "W$STATUS"
    USING STATUS-MESSAGE

Parameter

STATUS-MESSAGE PIC X(n) Contains the message to be displayed in the browser's status bar.

This routine is available only when the calling COBOL program is running in a Web browser window via the ACUCOBOL-GT Web Runtime. The routine is not available to programs run by the standard runtime when the standard runtime is executed by a Web browser. The RETURN-CODE register is set to 1 after a successful call and set to 0 if this routine is unavailable.

Parent topic: General Syntax and Library List


W$TEXTSIZE

The W$TEXTSIZE routine allows you to measure the height and width of a string of text in a particular font.

Usage

CALL "W$TEXTSIZE"
    USING TEXT-STRING, TEXTSIZE-DATA

Parameters

TEXT-STRING PIC X(n) Contains the string to be measured
TEXTSIZE-DATA PIC X(n) The TEXTSIZE-DATA data item is found in the COPY file acugui.def. It is defined as follows:
01 TEXTSIZE-DATA.
   03 TEXTSIZE-FONT      HANDLE OF FONT.
   03 TEXTSIZE-WINDOW    HANDLE OF WINDOW.
   03 TEXTSIZE-SIZE-X    PIC 9(7)V99  COMP-4.
   03 TEXTSIZE-CELLS-X   PIC 9(7)V99  COMP-4.
   03 TEXTSIZE-BASE-X    PIC 9(9)     COMP-4.
   03 TEXTSIZE-SIZE-Y    PIC 99V99    COMP-4.
   03 TEXTSIZE-CELLS-Y   PIC 99V99    COMP-4.
   03 TEXTSIZE-BASE-Y    PIC 9(4)     COMP-4.
   03 TEXTSIZE-FLAGS     PIC X        COMP-X.
      88 TEXTSIZE-STRIP-SPACES VALUE 1, FALSE ZERO.

Description

The W$TEXTSIZE routine measures the average height and width of TEXT-STRING according to the parameters found in TEXTSIZE-DATA and returns the results in TEXTSIZE-DATA. The measurement is returned using a variety of units.

The data elements in TEXTSIZE-DATA are used as follows:

TEXTSIZE-FONT (HANDLE OF FONT) | This item holds the handle of the font that you want the runtime to measure. If the value is NULL, DEFAULT-FONT is used. TEXTSIZE-FONT is initialized to NULL in acugui.def.
TEXTSIZE-WINDOW (HANDLE OF WINDOW) | This item holds the handle of the window that you want to use when measuring the number of window cells the text occupies (see TEXTSIZE-CELLS-X and TEXTSIZE-CELLS-Y below). If this value is NULL, the current window is used. If there is no current window, the cells\ measurement is returned with the value zero. TEXTSIZE-WINDOW is initialized to NULL in acugui.def.
TEXTSIZE-FLAGS (PIC X COMP-X) | If TEXTSIZE-STRIP-SPACES is true, W$TEXTSIZE does not include any trailing spaces in the measurement of TEXTSTRING. Otherwise, trailing spaces are included in the measurement. TEXTSIZE-FLAGS is initialized to NULL in acugui.def.
TEXTSIZE-SIZE-X (PIC 9(7)V99 COMP-4) | Returns the width of the text in label size units. This is the SIZE value required for a label to exactly contain the text. It is computed by dividing the length of the text by the size of the font's 0 character. For fixed-pitch fonts, the value returned is the same as the number of characters in TEXT-STRING.
TEXTSIZE-SIZE-Y (PIC 99V99 COMP-4) | Returns the height of the text in label size units. This is the LINES value required for a label to exactly contain the text. By definition, this value is always 1.
TEXTSIZE-CELLS-X (PIC 9(7)V99 COMP-4) | Returns the width of the text in window cells. It is computed by dividing the width of the text by the width of a window cell.
TEXTSIZE-CELLS-Y (PIC 99V99 COMP-4) | Returns the height of the text in window cells. It is computed by dividing the height of the text by the height of a window cell.
TEXTSIZE-BASE-X (PIC 9(9) COMP-4) | Returns the width of the text in base units. On a graphical system, a base unit is a pixel. On a character-based system, a base unit is a character cell.
TEXTSIZE-BASE-Y (PIC 9(4) COMP-4) | Returns the height of the text in base units. On a graphical system, a base unit is a pixel. On a character-based system, a base unit is a character cell.
Parent topic: General Syntax and Library List


WIN$PLAYSOUND

The WIN$PLAYSOUND routine lets you play a .WAV file on Microsoft Windows machines (wave-form sound). You can also play sounds that the user has assigned to system events in the control panel.

WIN$PLAYSOUND is supported and can be used by applications deployed in Acucorp's Thin Client environment.

Usage

CALL "WIN$PLAYSOUND"
    USING SOUND-NAME, SOUND-FLAGS
    GIVING SOUND-STATUS

Parameters

SOUND-NAME PIC X(n) | Identifies the sound to play. This is either the name of a registered system sound or the name of a .WAV file.
SOUND-FLAGS numeric parameter | One or more optional values added together. The SOUND-FLAG options are described below. The option names are contained in the COPY library acugui.def.
SOUND-STATUS signed numeric data item Indicates the status of the operation as follows:
  • -1 - Operation not available - host machine is not Windows
  • 0 - Operation failed
  • 1 - Operation succeeded

Description

WIN$PLAYSOUND causes the sound specified in SOUND-NAME to be played. If SOUND-NAME contains the name of a system event, the sound associated with that event is played (the association is made via the Windows Control Panel). Otherwise, WIN$PLAYSOUND assumes that SOUND-NAME contains the name of a .WAV audio file.

Note: When you are running in a thin client environment, and a file name beginning with @[DISPLAY] is passed to this routine, it will attempt to access the file in the display host's file system. It does not download the file from the server. For more information, see the topic, Using Library Routines and DLLs in Thin Client of the AcuConnect User's Guide.

If SOUND-NAME does not correspond to a system event and the file cannot be found, the default system sound is played. The default sound is also played when there is not enough memory available to load the specified file. If a default sound is not available, the routine does nothing and returns 0 in SOUND-STATUS.

This routine searches for the specified .WAV file in the object libraries, the working directory, and then the directories specified in the PATH environment variable. You can add .WAV files to your object library by using the COPY RESOURCE statement or CBLUTIL utility program. Specifying a SOUND-NAME of spaces stops any sound that is currently playing.

Note: The behavior of this library routine is affected by the setting of the FILENAME_SPACES configuration variable that may or may not allow spaces in a file name. See the documentation on FILENAME_SPACES in Appendix H, Configuration Variables for information about the terminating character for path names.

System event names are implementation dependent. The Windows API documents that the following sounds are always available:

  • SystemAsterisk
  • SystemExclamation
  • SystemExit
  • SystemHand
  • SystemQuestion
  • SystemStart

Other system sound events are defined in the registry under Windows 98. Use regedit to look in the registry location:

HKEY_CURRENT_USER\AppEvents\EventLabels

The naming conventions for system sound events is implementation dependent.

The following options can be specified in SOUND-FLAGS. To use them, add together the values of the options and assign them to SOUND-FLAGS. The optional values have level 78 names associated with them. These names are defined in acugui.def.

SND-SYNC (value 0) | This option causes the program to pause while the sound is being played. WIN$PLAYSOUND will not return until the sound has finished.
SND-ASYNC (value 1) | This option causes the program to continue to run while the sound is playing. Note that you can halt a sound that is playing by passing a SOUND-NAME of spaces to a subsequent call to WIN$PLAYSOUND.
SND-LOOP (value 8) | To work, this option must be used with the SND-ASYNC option. This option causes the sound to play continuously, restarting from the beginning when the end is reached. The sound can be stopped by passing a SOUND-NAME of spaces on a subsequent call.
SND-NOSTOP (value 16) | Normally, any sound playing will be stopped when a new sound is specified. With NOSTOP, if a sound is already playing, it will continue to play and WIN$PLAYSOUND will return a SOUND-STATUS value of 0.
Parent topic: General Syntax and Library List


WIN$PRINTER

The WIN$PRINTER library routine is designed to enhance the ability of COBOL to take advantage of the Windows print spooler. This routine is available on all systems that run ACUCOBOL-GT, but is useful only with Microsoft Windows. Not all printer drivers are supported by this routine.

WIN$PRINTER configures the Windows print spooler only and cannot be used to configure the printer directly.

You must assign your print file to -P SPOOLER or to -Q printername in the configuration file to access the Windows print spooler.

If you have assigned your print file to -P SPOOLER-DIRECT or to -Q printername using the DIRECT=ON option, then you retain control over the format of the pages. In this situation, WIN$PRINTER can be used to select a printer, but not to print bitmaps or determine paper size, page orientation, fonts, margins, and the like. The information returned by WIN$PRINTER about the numbers of lines and columns on the page may not be accurate in this situation and should not be used.

CAUTION:
Just as with changes to fonts and menus, modifications to Windows printer settings are global for a specific instance of the runtime. Settings established in one COBOL application will affect subsequent COBOL applications performed in the same runtime instance. If you do not want settings to apply globally in this case, you must reverse the settings manually within the program. However, these modified printer settings will not affect later executions unless you store the settings and reactivate them at the next instance of the runtime. Windows global settings, other windows applications and other instances of the runtime are not affected by changes made by the WIN$PRINTER library routine.

When you change Windows settings in general, and printer settings in particular, Windows posts a message informing its subsystems of the change. The runtime looks for these messages and passes that information on to the WIN$PRINTER operation codes when they are called. This may cause inconsistencies between the information stored in the COBOL program and the runtime, such as the order of printers in the internal printer list. To avoid this problem, always use the printer name, rather than the printer number, when calling op-codes that require a printer identity. The name will always be unique, while the number is relative to the internal printer list and may not be accurate.

WIN$PRINTER always performs the printer number test before the printer name test. This means that if WINPRINTER-NO-OF-PRINTERS is a positive number, the function will look for that printer number before looking for the printer name. This could result in a WPRTERR-BAD-ARG error. To overrule this ranking and use the printer name, set the argument WINPRINT-NO-OF-PRINTERS to zero before accessing printer-specific information.

Usage

CALL "WIN$PRINTER"
    USING OP-CODE, parameters,
    GIVING RESULT

Parameters

OP-CODE | A numeric value that selects which WIN$PRINTER function to perform. The op-codes are defined in winprint.def and described in the WIN$PRINTER op-codes section below.
RESULT | A signed numeric data item that returns the status of the operation. The data type of the returned value is SIGNED-INT or PIC S9(9) COMP-5. Unless otherwise stated below, 1 indicates success, and a zero or negative result indicates failure.
parameters | The remaining parameters vary depending on the operation code chosen. They provide information and hold results for the operations specified. Parameters may be omitted from those operations that do not require them. The parameters that apply to WIN$PRINTER op-codes are WINPRINT-DATA, WINPRINT-SELECTION, WINPRINT-COLUMN, WINPRINT-MEDIA, WINPRINT-JOB-STATUS and data defined in WORKING-STORAGE by the user. These are all defined in winprint.def. The parameters correspond to each of the op-codes as follows:
OP-CODE | Parameter
WINPRINT-SUPPORTED | none
WINPRINT-SETUP | none
WINPRINT-SETUP-USE-MARGINS | none
WINPRINT-GET-SETTINGS-SIZE | none
WINPRINT-GET-SPOOL-ERR | none
WINPRINT-SET-JOB | none
WINPRINT-UPDATE-PRINTERS | none
WINPRINT-GET-SETTINGS | user defined
WINPRINT-SET-SETTINGS | user defined
WINPRINT-SET-DATA-COLUMNS | WINPRINT-COLUMN
WINPRINT-CLEAR-DATA-COLUMNS | WINPRINT-COLUMN
WINPRINT-SET-PAGE-COLUMN | WINPRINT-COLUMN
WINPRINT-CLEAR-PAGE-COLUMNS | WINPRINT-COLUMN
WINPRINT-GET-PAGE-COLUMN | WINPRINT-COLUMN
WINPRINT-COLUMN-ALIGN-VERT | WINPRINT-COLUMN
WINPRINT-SET-STD-FONT | WINPRINT-DATA
WINPRINT-GET-PAGE-LAYOUT | WINPRINT-DATA
WINPRINT-SET-FONT | WINPRINT-DATA
WINPRINT-SET-LINES-PER-PAGE | WINPRINT-DATA
WINPRINT-GET-CAPABILITIES | WINPRINT-DATA
WINPRINT-PRINT-BITMAP | WINPRINT-DATA
WINPRINT-SET-MARGINS | WINPRINT-DATA
WINPRINT-GET-MARGINS | WINPRINT-DATA
WINPRINT-GRAPH-BRUSH | WINPRINT-DATA
WINPRINT-GRAPH-PEN | WINPRINT-DATA
WINPRINT-GRAPH-DRAW | WINPRINT-DATA
WINPRINT-SET-CURSOR | WINPRINT-DATA
WINPRINT-SET-TEXT-COLOR | WINPRINT-DATA
WINPRINT-SET-BKMODE | WINPRINT-DATA
WINPRINT-GET-JOB-STATUS | WINPRINT-JOB-STATUS
WINPRINT-SET-JOB-STATUS | WINPRINT-JOB-STATUS
WINPRINT-GET-PRINTER-MEDIA | WINPRINT-MEDIA
WINPRINT-GET-NO-PRINTERS | WINPRINT-SELECTION
WINPRINT-GET-PRINTER-INFO | WINPRINT-SELECTION
WINPRINT-SET-PRINTER | WINPRINT-SELECTION
WINPRINT-GET-CURRENT-INFO | WINPRINT-SELECTION
WINPRINT-GET-CURRENT-INFO-EX | WINPRINT-SELECTION
WINPRINT-SET-PRINTER-EX | WINPRINT-SELECTION
WINPRINT-GET-CURRENT-INFO-EX | WINPRINT-SELECTION
WINPRINT-GET-PRINTER-STATUS | WINPRINT-SELECTION

Description

To use this library routine you must include the COPY file winprint.def. You will need to copy this file into the Working-Storage section of any program that calls WIN$PRINTER. You must also assign the print file to either -P SPOOLER or to -Q <printername>, as described in your Getting Started guide.

WIN$PRINTER takes one or more parameters. The first parameter is a mandatory operation code that indicates which sub-function of WIN$PRINTER to perform. The operation codes are described under WIN$PRINTER op-codes, below.

The other parameters are optional data items defined in winprint.def or defined by the user in Working-Storage. You use these data items to pass data to and from WIN$PRINTER. The specific data passed depends on the particular operation being called. Some operations do not use a data item, in which case it can be omitted.

The definitions of WINPRINT-DATA, WINPRINT-SELECTION, WINPRINT-COLUMN, WINPRINT-MEDIA, and WINPRINT-JOB-STATUS are included in winprint.def. These definitions may change in future versions as capabilities are added to WIN$PRINTER. However, ACUCOBOL-GT will continue to support the existing formats.

When WIN$PRINTER is called, it sets a return value to indicate whether the call succeeded or failed. A positive value indicates success. A zero or a negative value indicates an error. The error codes are defined in the section on error handling, below.

If the call to WIN$PRINTER does not include a GIVING item for the return value, the return value is placed in the special register RETURN-CODE.

See graphprn.cbl and prndemox.cbl for examples of many of the WIN$PRINTER functions.

Several operations accept parameters that have values measured in the dots-per-inch (DPI) resolution of the output device. Using the Windows graphical device interface (GDI), a program can get DPI information for a given printer on the system. A demonstration program written in COBOL is available in the Support area of the Acucorp Web site. To download the program, open your Web browser and navigate to: www.acucorp.com/support/public/sample_programs/index.php. Select Graphical User Interface Sample Programs from the drop down list and click GetPrinterResolution.cbl.

  • Error Handling
  • WIN$PRINTER op-codes
Parent topic: General Syntax and Library List


Error Handling

When you call WIN$PRINTER, it returns a status value. This numeric value is returned in the CALL statement's GIVING data item, or the special register RETURN-CODE if no GIVING item is specified. A positive value indicates that the routine succeeded. A value of zero or less indicates that an error or exception occurred. These situations have level 78 values defined for them in winprint.def. The defined values include:

WPRTERR-BAD-ARG | This code indicates an unknown operation code or illegal value for any of the WIN$PRINTER functions.
WPRTERR-BAD-DRIVER | This code is returned when the spooler can't find a device driver that corresponds to the selected printer.
WPRTERR-BUFFER-TOO-SMALL | This code is returned when the data item passed to the WINPRINT-GET-SETTINGS operation is too small to hold the spooler's current configuration.
WPRTERR-CANCELLED | This code is returned when you use the WINPRINT-SETUP or WINPRINT-SETUP-USE-MARGINS operation to display the printer setup dialog box and the user clicks the Cancel button or closes the dialog box without clicking the OK button. This status can usually be ignored because the runtime automatically restores the prior configuration.
WPRTERR-DEVICE-INCAPABLE | This code is returned when you try to print a bitmap and the printer you are using cannot print bitmaps.
WPRTERR-DRV-LOADFAIL | This code is returned when WIN$PRINTER failed to load the driver information for the chosen printer. This could be caused by a corrupted file, bad registry settings, or a remote printer being offline.
WPRTERR-ENUM-FAIL | This code is returned when one of the WIN$PRINTER functions does not find any available printers on the system.
WPRTERR-NO-MEMORY | This code indicates that the system ran out of memory when trying to perform the requested operation.
WPRTERR-SPOOLER-CLOSED | This code is returned when you attempt to print a bitmap on a closed print file.
WPRTERR-SPOOLER-OPEN | This code indicates that the program tried to change the spooler's configuration while a spooled print file was open.
WPRTERR-SPOOL-ERR | This code is returned when there is an error in the Graphical Device Interface (GDI) layer that is not listed in winprint.def. Use the operation WINPRINT-GET-SPOOL-ERR to obtain the exact Windows API code and refer to your Windows SDK documentation for a description.
WPRTERR-UNSUPPORTED | This code is returned whenever WIN$PRINTER is called on a machine that is not a Windows machine.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-SETTINGS-SIZE
    GIVING RESULT

Return Values

This operation returns the number of bytes needed to hold the current spooler configuration.

Description

The spooler configuration includes the destination device, paper size, and page orientation. It does not include the current font selection. Use this operation to ensure that you have a large enough buffer when using the WINPRINT-GET-SETTINGS and WINPRINT-SET-SETTINGS operations.

Note: This operation is not supported in Acucorp's Thin Client environment.
Parent topic: WIN$PRINTER


WIN$PRINTER op-codes

The following is a list of WIN$PRINTER operation codes and their effects. These level 78 items are all defined in winprint.def.

  • WINPRINT-DATA op-codes
  • WINPRINT-SELECTION op-codes
  • WINPRINT-COLUMN op-codes
  • WINPRINT-JOB-STATUS op-codes
  • WINPRINT-MEDIA op-codes
  • USER-DATA op-codes
  • Printer Information op-codes
  • WINPRINT-DATA op-codes
  • WINPRINT-SELECTION op-codes
  • WINPRINT-COLUMN op-codes
  • WINPRINT-JOB-STATUS op-codes
  • WINPRINT-MEDIA op-codes
  • USER-DATA op-codes
Parent topic: WIN$PRINTER


Printer Information op-codes

The following operation codes provide general information about page layout, the print spooler buffer, and whether or not the WIN$PRINTER routine is supported.

  • WINPRINT-GET-SETTINGS-SIZE
  • WINPRINT-SETUP
  • WINPRINT-SETUP-USE-MARGINS
  • WINPRINT-SUPPORTED
  • WINPRINT-GET-SPOOL-ERR
  • WINPRINT-SET-JOB
  • WINPRINT-UPDATE-PRINTERS
Parent topic: WIN$PRINTER op-codes


WINPRINT-GET-SETTINGS-SIZE

This operation code retrieves the size of the buffer available in the current spooler configuration.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-SETTINGS-SIZE
    GIVING RESULT

Return Values

This operation returns the number of bytes needed to hold the current spooler configuration.

Description

The spooler configuration includes the destination device, paper size, and page orientation. It does not include the current font selection. Use this operation to ensure that you have a large enough buffer when using the WINPRINT-GET-SETTINGS and WINPRINT-SET-SETTINGS operations.

Note: This operation is not supported in ACUCOBOL-GT'sThin Client environment.
Parent topic: Printer Information op-codes


WINPRINT-SETUP

This operation code calls the standard Windows Setup Printer dialog box. This allows the user to select which printer to use, the desired page orientation (landscape or portrait), and the desired paper size and source. To also get the page margins, use WINPRINT-SETUP-USE-MARGINS instead. Note that there is also a WINPRINT-SETUP-EX operation code for calling the PrintDlgEx function, which is considered a more modern and feature-rich printer dialog box and is fully supportd in Windows Vista.

In Windows Vista, Microsoft no longer fully supports the PrintDlg function, which leaves the function relatively useless. This in turn limits the functionality of WINPRINT-SETUP, which is used to call PrintDlg.

To minimize the impact on users of WINPRINT-SETUP, the runtime detects when it is executed on placeVista and will change to use the new WINPRINT-SETUP-EX operation code that is used to display the PrintDlgEx printer window.

Note that the application must have a window open in order for this feature to work. If no window is open, the printer dialog will not be shown, the error WPRTERR-WINDOW-REQUIRED will be returned, and the print job may go to the default printer.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SETUP
    GIVING RESULT

Description

The runtime internally configures itself based on the selections chosen by the user. These become the settings used during the remainder of the run or until the next call to this operation. Settings return to their defaults when the runtime exits.

If you are using the WINPRINT-SELECTION data structure, calls to WINPRINT-SETUP must also be followed by a call to WINPRINT-GET-CURRENT-INFO(-EX) to ensure consistency between COBOL data storage information and the current Windows configuration. However, if you do not use any of the operation codes that rely on the WINPRINT-SELECTION group, there is no need to call WINPRINT-GET-CURRENT-INFO(-EX).

Note: Changing the output device with this operation will reset any columns you have set using WINPRINT-COLUMN op-codes.
Parent topic: Printer Information op-codes


WINPRINT-SETUP-USE-MARGINS

This operation code calls the standard Windows Setup Printer dialog box and utilizes the margins specified in the dialog box. This allows the user to select which printer to use, the desired page orientation, the margins, and the desired paper size and source.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SETUP-USE-MARGINS
    GIVING RESULT

Description

The WINPRINT-SETUP-USE-MARGINS operation code is similar to WINPRINT-SETUP in its base usage.

If you are using the WINPRINT-SELECTION data structure (like WINPRINT-SETUP), it must be followed by a call to WINPRINT-GET-CURRENT-INFO(-EX) to ensure consistency between COBOL data storage information and the current Windows configuration. However, if you do not use any of the operation codes that rely on the WINPRINT-SELECTION group, there is no need to call WINPRINT-GET-CURRENT-INFO(-EX).

WINPRINT-SETUP-USE-MARGINS is defined in winprint.def. You can use this operation code with WINPRINT-GET-MARGINS to obtain the current margin.

Note: Changing the output device with this operation will reset any columns you have set using WINPRINT-COLUMN op-codes.
Parent topic: Printer Information op-codes


WINPRINT-SUPPORTED

This operation code determines if the WIN$PRINTER routine is supported (i.e., the host machine is a Windows machine).

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SUPPORTED
    GIVING RESULT

Return Values

This operation sets the return value of WIN$PRINTER to 1 if the WIN$PRINTER routine is supported. Otherwise it sets the return value to WPRTERR-UNSUPPORTED.

Comments

The WIN$PRINTER routine can only be used with Microsoft Windows.

Parent topic: Printer Information op-codes


WINPRINT-GET-SPOOL-ERR

This operation code obtains the number of the most recent Windows Graphical Device Interface (GDI) error from the Windows API.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-SPOOL-ERR
    GIVING RESULT

Return Values

This operation returns the most recent Windows GDI error.

Description

The complexity of Windows graphics capabilities make it impossible to catalog all possible error conditions in winprint.def. Therefore, if a graphical error condition occurs, the WIN$PRINTER op-code that caused the error returns WPRTERR-SPOOL-ERR to indicate that a Windows API error occurred. Use WINPRINT-GET-SPOOL-ERR to retrieve the specific Windows API error number, then refer to Windows API documentation for a description of the problem.

This operation should be called immediately after a WIN$PRINTER operation call has returned WPRTERR-SPOOL-ERR. Calling this function under other circumstances will return unpredictable values. This operation does not impact WRITE statements.

Note: Calling WINPRINT-GET-SPOOL-ERR does not reset the last GDI error internally. Do not use this operation as a method to verify that a call worked properly.
Parent topic: Printer Information op-codes


WINPRINT-SET-JOB

This operation code returns the identifier of the job that is currently spooling into the printer. The ID number returned by this operation will be compatible with, and may be used in conjunction with, the operations WINPRINT-SET-JOB-STATUS and WINPRINT-GET-JOB-STATUS.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-JOB JOB-ID
    GIVING PRINT-JOB.

Return Values

If you set JOB-ID to 0, WINPRINT-SET-JOB returns the identifier of the job that is currently spooling into the printer (PRINT-JOB). You can then use that number to tell WIN$PRINTER operations which print job is the target. This is your only way to obtain the ID of a job. To restore the system default settings, simply call this operation with a JOB-ID of -1

Description

This call should be issued immediately after the opening of a job. For example:

OPEN OUTPUT FIRST-FILE.
CALL "WIN$PRINTER" USING WINPRINT-SET-JOB JOB-ID GIVING FIRST-ID.

where FIRST-ID is a variable declared signed-integer, such as:

77 FIRST-ID USAGE SIGNED-INT.

Subsequent calls to WIN$PRINTER may use FIRST-ID to identify the target for the next action, as follows:

      OPEN    OUTPUT           FIRST-FILE.
      CALL    "WIN$PRINTER"    USING
              WINPRINT-SET-JOB 0
              GIVING           FIRST-ID.
      OPEN    OUTPUT           SECOND-FILE. | Is now current.
*Initialize the print record for the first print job.
      MOVE    "This is job 1, printed with MS Sans Serif." TO
              RECORD-FILE-1.
*Initialize the print record for the second print job.
      MOVE    "This is job 2, printed with Script." TO
              RECORD-FILE-2.
*Set active job to the first print job.
      CALL    "WIN$PRINTER"    USING
              WINPRINT-SET-JOB FIRST-ID.
*Set the preferred font for the first print job.
      INITIALIZE               WINPRINT-DATA.
      MOVE    FIRST-FONT       TO WPRTDATA-FONT.
      CALL    "WIN$PRINTER"    USING
              WINPRINT-SET-FONT
              WINPRINT-DATA.

If you try to perform an operation that requires an active print job and there is none, an error status is returned. This series of calls can be used with all WIN$PRINTER functions, with the following exceptions:

  • The status of a printer cannot be determined using WINPRINT-GET-PRINTER-STATUS or WINPRINT-GET-JOB-STATUS unless the print job has already started. This is because the port monitor must both detect a print error and report it to the printer queue before it can be recognized by WIN$PRINTER functions.
  • Due to a limitation in the Microsoft Windows API, computers that run Windows 9x (Windows 98, and Windows ME) do not return the spooler job ID when opening a print job. This means that you cannot use the WINPRINT-GET-JOB-STATUS and WINPRINT-SET-JOB-STATUS operations of the WIN$PRINTER library routine on these machines. (These operations are used to check and modify the status of a particular printer.)

When you are printing multiple jobs simultaneously, you should not set a printer font before the print job has been opened because the font could be applied to the wrong job. Once the print job is opened, you may set the font, using the JOB-ID of the target printer.

However, if you need to change the printer settings for subsequent job on a different printer, you should set JOB-ID to -1 before setting WINPRINT-SET-SETTINGS or WINPRINT-SET-PRINTER(-EX). This causes WINPRINT-SET-JOB to return the ID number of the next job in the queue (after the current job). This should be done just prior to calling an OPEN statement. When JOB-ID is set to -1, the runtime executes the next WIN$PRINTER operation as if no current job were printing. This does not affect existing jobs, but it affects the status of subsequent jobs, unless it is an OPEN, WRITE, or CLOSE statement.

Parent topic: Printer Information op-codes


WINPRINT-UPDATE-PRINTERS

Usage

CALL "WIN$PRINTER"
     USING WINPRINT-UPDATE-PRINTERS

Description

This op-code enables you to force the runtime to reload the internal printerlist so that any changes to that list (new printer added, for example) will be detected by the COBOL program.

This op-code takes no parameters and always returns TRUE. By calling this op-code, the runtime printing system is told to reload the printer list. A call to this op-code should be followed by a call to one of the following op-codes to ensure synchronization between the COBOL printer list and the internal runtime:

    78  WINPRINT-GET-NO-PRINTERS            VALUE 13.
    78  WINPRINT-GET-PRINTER-INFO           VALUE 14.
    78  WINPRINT-GET-CURRENT-INFO           VALUE 16.
    78  WINPRINT-GET-PRINTER-INFO-EX        VALUE 28.
    78  WINPRINT-GET-CURRENT-INFO-EX        VALUE 30.
Parent topic: Printer Information op-codes


WINPRINT-DATA op-codes

The following operation codes use the data item WINPRINT-DATA (defined in winprint.def). These operations are used to specify the appearance of a printed page, including features such as font, page layout and graphics placement.

  • WINPRINT-GET-CAPABILITIES
  • WINPRINT-GET-MARGINS
  • WINPRINT-GET-PAGE-LAYOUT
  • WINPRINT-GRAPH-DRAW
  • WINPRINT-GRAPH-BRUSH
  • WINPRINT-GRAPH-PEN
  • WINPRINT-PRINT-BITMAP
  • WINPRINT-SET-CURSOR
  • WINPRINT-SET-TEXT-COLOR
  • WINPRINT-SET-FONT
  • WINPRINT-SET-LINES-PER-PAGE
  • WINPRINT-SET-MARGINS
  • WINPRINT-SET-STD-FONT
  • WINPRINT-SET-BKMODE
  • WINPRINT-GET-CAPABILITIES
  • WINPRINT-GET-MARGINS
  • WINPRINT-GET-PAGE-LAYOUT
  • WINPRINT-GRAPH-DRAW
  • WINPRINT-GRAPH-BRUSH
  • WINPRINT-GRAPH-PEN
  • WINPRINT-PRINT-BITMAP
  • WINPRINT-SET-CURSOR
  • WINPRINT-SET-TEXT-COLOR
  • WINPRINT-SET-FONT
  • WINPRINT-SET-LINES-PER-PAGE
  • WINPRINT-SET-MARGINS
  • WINPRINT-SET-STD-FONT
  • WINPRINT-SET-BKMODE
Parent topic: WIN$PRINTER op-codes


WINPRINT-GET-CAPABILITIES

This operation code determines whether or not a printer can print bitmaps.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-CAPABILITIES, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03 WPRTDATA-CAPABILITIES REDEFINES
      WPRTDATA-SET-STD-FONT.
      05 WPRTDATA-BITMAPS-OK-FLAG      PIC 9.
         88 WPRTDATA-BITMAPS-OK        VALUE 1, FALSE ZERO.

Return Values

This operation returns information about the capabilities of the currently selected printer to WPRTDATA-CAPABILITIES. Currently, the only capability returned to this parameter is whether or not the printer can print bitmaps. If it can, WPRTDATA-BITMAPS-OK is true. Printers that do not use a raster technology (such as a pen plotter) cannot print bitmaps.

Parent topic: WINPRINT-DATA op-codes


WINPRINT-GET-MARGINS

This operation code may be used with WINPRINT-SETUP-USE-MARGINS to obtain the margins set in the Windows printer setup dialog box or the margins set with WINPRINT-SET-MARGINS.

If used with WINPRINT-SETUP-USE-MARGINS, it returns information about the current default margin in the Windows printer setup dialog box using centimeters or inches but not with pixels or cells. This occurs because the operation code is used with WINPRINT-SETUP-USE-MARGINS and can therefore be used only with values supported by the dialog box.

If you have used WINPRINT-SET-MARGINS and later call WINPRINT-GET-MARGINS, the values returned are those originally set with WINRPRINT-SET-MARGINS, which may include inches, centimeters, pixels, or cells.

Usage

INITIALIZE WPRTDATA-MARGINS
CALL "WIN$PRINTER"
    USING WINPRINT-GET-MARGINS, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03 WPRTDATA-MARGINS REDEFINES
      WPRTDATA-SET-STD-FONT.
      05 WPRTDATA-TOP-MARGIN           PIC 9(7)V99 COMP-5.
      05 WPRTDATA-BOTTOM-MARGIN        PIC 9(7)V99 COMP-5.
      05 WPRTDATA-LEFT-MARGIN          PIC 9(7)V99 COMP-5.
      05 WPRTDATA-RIGHT-MARGIN         PIC 9(7)V99 COMP-5.
      05 WPRTDATA-MARGIN-UNITS         UNSIGNED-SHORT.

WINPRINT-GET-MARGINS requires the WPRTDATA-MARGINS structure to be passed as the second parameter and WPRTDATA-MARGINS is filled with the current margins defined as the defaults in the printer dialog box.

Return Values

This operation returns one of the following values:

  • WPRTMARGIN-CENTIMETERS
  • WPRTMARGIN-INCHES
  • WPRTMARGIN-PIXELS (only if set with WINPRINT-SET-MARGINS)
  • WPRTMARGIN-CELLS (only if set with WINPRINT-SET-MARGINS)
Parent topic: WINPRINT-DATA op-codes


WINPRINT-GET-PAGE-LAYOUT

This operation code determines how many columns and rows of characters will fit on a page.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-PAGE-LAYOUT, WINPRINT-DATA,
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03 WPRT-PAGE-LAYOUT REDEFINES
      WPRTDATA-SET-STD-FONT.
      05 WPRTDATA-LINES-PER-PAGE       UNSIGNED-SHORT.
      05 WPRTDATA-COLUMNS-PER-PAGE     UNSIGNED-SHORT.

Return Values

This operation returns the number of print rows that can fit on a page in WPRTDATA-LINES-PER-PAGE, and the number of print columns in WPRTDATA-COLUMNS-PER-PAGE. This accounts for the current page size, orientation, and printer font. You may use this routine either before or after opening a print file.

Because of the large number of variables involved with printing under Windows (for example, the font size, the paper size, and print orientation), we recommend that you use this routine to determine how many lines will fit on a page when you are formatting reports.

However, we do not recommend using this operation when printing in DIRECT mode using -P SPOOLER or -Q printername. When you print in DIRECT mode, the Windows print spooler has no control of the printer, and no initialization of the printer is performed by the Windows printer driver. This means that the print job uses the hardware defaults. For example, if you print in DIRECT mode to a printer with the hardware default paper size set to placecountry-regionUS letter format, that is the format used, even if the driver has A4 paper set as the default, in which case this operation is likely to return incorrect values.

Parent topic: WINPRINT-DATA op-codes


WINPRINT-GRAPH-DRAW

This operation code specifies the size, shape and location of a graphic in the current print job using pen and brush attributes specified by WINPRINT-GRAPH-BRUSH and WINPRINT-GRAPH-PEN .

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GRAPH-DRAW, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03  WPRTDATA-DRAW REDEFINES
   WPRTDATA-SET-STD-FONT.
      05  WPRTDATA-DRAW-START-X       PIC 9(7)V99 COMP-5.
      05  WPRTDATA-DRAW-START-Y       PIC 9(7)V99 COMP-5.
      05  WPRTDATA-DRAW-STOP-X        PIC 9(7)V99 COMP-5.
      05  WPRTDATA-DRAW-STOP-Y        PIC 9(7)V99 COMP-5.
      05  WPRTDATA-DRAW-UNITS         UNSIGNED-SHORT.
      05  WPRTDATA-DRAW-SHAPE         UNSIGNED-SHORT.

Return Value

This operation returns the coordinates and shape of a graphic.

Description

The printer must be open to perform this operation. WPRTDATA-DRAW should be initialized prior to use. There is no limit to the number of times this operation may be called. Once it is called, all further printing using the WRITE statement is performed using a TRANSPARENT background. The TRANSPARENT setting is not usually applied to WRITE statements, but this mode is necessary for graphics to print correctly. (This does not apply to WINPRINT-COLUMN operations, which have a particular setting for TRANSPARENCY.)

Note: The current cursor position on the printer is not modified by this call.

If WINPRINT-GRAPH-PEN or WINPRINT-GRAPH-BRUSH have not yet been called, this operation will create and use the defaults. The default pen is solid black, with a width of 1. The default brush is NULL, meaning there is no fill.

Note: When you call WINPRINT-GRAPH-DRAW, the operation will automatically test to see if a form feed is pending. If this is the case, the form feed will be performed before the call to this operation is executed.

WINPRINT-GRAPH-DRAW has the following values:

  • WPRTDATA-DRAW-UNITS - Specifies the unit of measure of the values passed for drawing coordinates. If an illegal value is set, the unit of measure will be set to the default (WPRTUNITS-PIXELS). The unit of measure may be set to one of the following values:
    WPRTUNITS-CELLS Values are measured using the cell size of the currently selected font. The cell-size is determined by the height and width of the 0 character of a font. This is roughly equivalent to measuring in characters.

    If you use a proportional font, it is common for uppercase characters to be wider than this measurement. Non-integer values are allowed in the measurements.

    WPRTUNITS-CELLS-ABS | Values are measured using the "cell size" of the currently selected font. Positioning is based on the left edge of the paper, regardless of the physical left margin determined by the printer (even if the absolute position is smaller). If the dimensions of the area to be printed are less than the printer's left or top physical margin, or greater than the printer's right or bottom physical margin, WIN$PRINTER will return an error. (Note that due to inherent differences in the hardware of printer manufacturers, this value may not provide truly device-independent results.)
    WPRTUNITS-INCHES | Values are measured in inches.
    WPRTUNITS-INCHES-ABS | Values are measured in inches. Positioning is based on the left edge of the paper, regardless of the physical left margin determined by the printer (even if the absolute position is smaller). If the dimensions of the area to be printed are less than the printer's left or top physical margin, or greater than the printer's right or bottom physical margin, WIN$PRINTER will return an error.
    WPRTUNITS-CENTIMETERS | Values are measured in centimeters.
    WPRTUNITS-CENTIMETERS-ABS | Values are measured in centimeters. Positioning is based on the left edge of the paper, regardless of the physical left margin determined by the printer (even if the absolute position is smaller). If the dimensions of the area to be printed are less than the printer's left or top physical margin, or greater than the printer's right or bottom physical margin, WIN$PRINTER will return an error.
    WPRTUNITS-PIXELS (default) Values are measured using the dots-per-inch (DPI) resolution of the output device. Only integer values are allowed in the measurements.

    The actual size of this measurement varies depending on the target printer's resolution. This means that a width of 5 will appear differently on a 300dpi printer than it will on a 600dpi printer. Consider the unit of measure relative to the resolution of the targeting printer before printing.

  • WPRTDATA-DRAW-SHAPE - Specifies which type of shape to draw. If an illegal value is used, no shape will be drawn. The possible values are:
    WPRT-DRAW-RECTANGLE | Draws a rectangle with 90-degree corners.
    WPRT-DRAW-ROUND-RECTANGLE | Draws a rectangle with rounded corners.
    WPRT-DRAW-LINE | Draws a line.
  • WPRTDATA-DRAW-START-X - Specifies the top-left horizontal coordinate of the shape to draw. The unit of measure is set with WPRTDATA-DRAW-UNITS. The minimum value of this coordinate is 0. The top-leftmost coordinate for all graphic operations is 0,0
  • WPRTDATA-DRAW-START-Y - Specifies the top-left vertical coordinate of the shape to draw. The unit of measure is set with WPRTDATA-DRAW-UNITS. The minimum value of this coordinate is 0. The top-leftmost coordinate for all graphic operations is 0,0
  • WPRTDATA-DRAW-STOP-X - Specifies the lower-right horizontal coordinate of the shape to draw. The unit of measure is set with WPRTDATA-DRAW-UNITS. The maximum value of this coordinate depends on the unit of measure selected.
  • WPRTDATA-DRAW-STOP-Y - Specifies the lower-right vertical coordinate of the shape to draw. The unit of measure is set with WPRTDATA-DRAW-UNITS. The maximum value of this coordinate depends on the unit of measure selected.

Example

See graphprn.cbl for examples of printing graphics. This example will draw a box with rounded edges:

INITIALIZE               WPRTDATA-DRAW.
MOVE    WPRT-DRAW-ROUND-RECTANGLE TO  WPRTDATA-DRAW-SHAPE.
MOVE    3                TO  WPRTDATA-DRAW-START-X.
MOVE    1                TO  WPRTDATA-DRAW-START-Y.
MOVE    40               TO  WPRTDATA-DRAW-STOP-X.
MOVE    10               TO  WPRTDATA-DRAW-STOP-Y.
MOVE    WPRTUNITS-CELLS  TO  WPRTDATA-DRAW-UNITS.

CALL    "WIN$PRINTER"
        USING     WINPRINT-GRAPH-DRAW, WINPRINT-DATA
        GIVING    CALL-RESULT.
Parent topic: WINPRINT-DATA op-codes


WINPRINT-GRAPH-BRUSH

This operation code specifies the pattern or solid color used to fill a shape drawn with WINPRINT-GRAPH-DRAW.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GRAPH-BRUSH, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03  WPRTDATA-BRUSH REDEFINES
   WPRTDATA-SET-STD-FONT.
      05  WPRTDATA-BRUSH-STYLE        UNSIGNED-SHORT.
      05  WPRTDATA-BRUSH-COLOR        PIC 9(9) COMP-5

Return Values

This operation returns the style and color of the brush used by WINPRINT-GRAPH-DRAW.

Description

The printer must be open to perform this operation. It must be called prior to WINPRINT-GRAPH-DRAW. Once executed, the brush specified will apply to all graphic operations until a new call is executed. The selected brush is released when the printer is closed and will not affect subsequent print jobs. WPRTDATA-BRUSH must be initialized before use. There is no limit to the number of times this operation may be called.

WINPRINT-GRAPH-BRUSH has the following values:

  • WPRTDATA-BRUSH-COLOR - Specifies the color used to fill the shape drawn with WINPRINT-GRAPH-DRAW. The color resolution (COLORREF) is a combination of Red, Green, and Blue (RGB). The intensity of each color in the mix is determined by a number between 0 and 255. The default color (0,0,0) is black.
    Note: See your Windows API documentation for more information about RGB colors and COLORREF values.
  • WPRTDATA-BRUSH-STYLE - Specifies the pattern used to fill the shape drawn with WINPRINT-GRAPH-DRAW. It may be set to one of the following values:
    WPRT-BRUSH-SOLID | Selects a solid brush that fills the shape with the color selected in WPRTDATA-BRUSH-COLOR.
    WPRT-BRUSH-NULL (default) | The shape is not filled, and the background layer will show through.
    WPRT-BRUSH-BDIAGONAL | Fills the shape with a pattern of lines angled at 45-degrees. (//////)
    WPRT-BRUSH-CROSS | Fills the shape with a pattern of crosses. (++++++)
    WPRT-BRUSH-DIAGCROSS | Fills the shape with a pattern of diagonal crosses. (xxxxxx)
    WPRT-BRUSH-FDIAGONAL | Fills the shape with a pattern of lines angled at –45-degrees. (\\\\\\)
    WPRT-BRUSH-HORIZONTAL | Fills the shape with a pattern of dashes. (------)
    WPRT-BRUSH-VERTICAL | Fills the shape with a pattern of vertical bars. (||||||)
    WPRT-BRUSH-DKGRAY | Fills the shape with solid dark gray. If color is specified, it is ignored.
    WPRT-BRUSH-GRAY | Fills the shape with solid gray. If color is specified, it is ignored.
    WPRT-BRUSH-LTGRAY | Fills the shape with solid light gray. If color is specified, it is ignored.

Example

See graphprn.cbl for examples of printing graphics. This example will fill the shapes drawn with solid gray:

INITIALIZE WPRTDATA-BRUSH.
MOVE WPRT-BRUSH-GRAY  TO  WPRTDATA-BRUSH-STYLE.

CALL "WIN$PRINTER"
    USING WINPRINT-GRAPH-BRUSH, WINPRINT-DATA
    GIVING CALL-RESULT.
Parent topic: WINPRINT-DATA op-codes


WINPRINT-GRAPH-PEN

This operation code specifies characteristics of the pen used to draw a shape with WINPRINT-GRAPH-DRAW.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GRAPH-PEN, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03  WPRTDATA-PEN REDEFINES
   WPRTDATA-SET-STD-FONT.
      05  WPRTDATA-PEN-STYLE          UNSIGNED-SHORT.
      05  WPRTDATA-PEN-WIDTH          UNSIGNED-SHORT.
      05  WPRTDATA-PEN-COLOR          PIC 9(9) COMP-5.

Return Values

This operation returns the characteristics of lines drawn with WINPRINT-GRAPH-DRAW.

Description

The printer must be open to perform this operation. It must be called prior to WINPRINT-GRAPH-DRAW. Once executed, the pen specified will apply to all graphic operations until a new call is executed. The selected pen is released when the printer is closed and will not affect subsequent print jobs. WPRTDATA-PEN must be initialized before use. There is no limit to the number of times this operation may be called.

WINPRINT-GRAPH-PEN has the following values:

WPRTDATA-PEN-WIDTH | Specifies the thickness of the line drawn using WINPRINT-GRAPH-DRAW. The default unit of measure is pixels. For example, if WPRTDATA-PEN-WIDTH is set to 0, the width will be one pixel, unless another unit of measure has been selected. The default value is 1. The actual size of this measurement is affected by the target printer's resolution. This means that a width of 5 will appear differently on a printer with a resolution of 300 dots-per-inch (DPI) than it will on a printer with 600dpi. Consider the unit of measure relative to the resolution of the targeting printer before printing.
WPRTDATA-PEN-COLOR | Specifies the color of a line drawn using WINPRINT-GRAPH-DRAW. The color resolution (COLORREF) is a combination of Red, Green, and Blue (RGB). The intensity of each color in the mix is determined by a number between 0 and 255. The default color (0,0,0) is black. See your Windows API documentation for more information about RGB colors and COLORREF values.
WPRTDATA-PEN-STYLE | Specifies the type of line drawn. It may be set to one of the following values:
WPRT-PEN-SOLID (default) | Draws a solid line in the color selected in WPRTDATA-BRUSH-COLOR.
WPRT-PEN-NULL | Draws an invisible line. The background layer will show through.
WPRT-PEN-DASH | Draws a line of dashes (------). WPRTDATA-PEN-WIDTH must equal 1 to use this style.
WPRT-PEN-DOT | Draws a line of dots (......). WPRTDATA-PEN-WIDTH must equal 1 to use this style.
WPRT-PEN-DASHDOT | Draws a line of alternating dashes and dots (-.-.-.-.-.-.). WPRTDATA-PEN-WIDTH must equal 1 to use this style.
WPRT-PEN-DASHDOTDOT | Draws a line of dashes followed by two dots, (-..-..-..-..-..-..). WPRTDATA-PEN-WIDTH must equal 1 to use this style.
WPRT-PEN-INSIDEFRAME | Draws a solid line inside of the actual geometric area of the shape.

Example

See graphprn.cbl for examples of printing graphics. This example will draw lines and shapes with a solid pen that is 10 pixels thick:

INITIALIZE WPRTDATA-PEN.
MOVE WPRT-PEN-SOLID  TO  WPRTDATA-PEN-STYLE.
MOVE 10  TO  WPRTDATA-PEN-WIDTH.

CALL "WIN$PRINTER"
    USING  WINPRINT-GRAPH-PEN, WINPRINT-DATA
    GIVING  CALL-RESULT.
Parent topic: WINPRINT-DATA op-codes


WINPRINT-PRINT-BITMAP

This operation code prints a bitmap in the current report.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-PRINT-BITMAP, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03 WPRTDATA-PRINT-BITMAP REDEFINES
      WPRTDATA-SET-STD-FONT.
      05 WPRTDATA-BITMAP               PIC X(4) COMP-N.
      05 WPRTDATA-BITMAP-ROW           PIC 9(7)V99 COMP-5.
      05 WPRTDATA-BITMAP-COL           PIC 9(7)V99 COMP-5.
      05 WPRTDATA-BITMAP-HEIGHT        PIC 9(7)V99 COMP-5.
      05 WPRTDATA-BITMAP-WIDTH         PIC 9(7)V99 COMP-5.
      05 WPRTDATA-BITMAP-FLAGS         UNSIGNED-SHORT.

Description

The print file must be open when you are using this function. The bitmap is printed according to the data contained in WPRTDATA-PRINT-BITMAP. To ensure that elements are initialized to their default values, INITIALIZE WPRTDATA-PRINT-BITMAP before filling in the elements.

Note: When you call WINPRINT-PRINT-BITMAP, the operation will automatically test to see if a form feed is pending. If this is the case, the form feed will be performed before the call to this operation is executed.

WPRTDATA-BITMAP should contain the handle of the bitmap you want to print. You can obtain this handle by calling the library routine W$BITMAP with the WBITMAP-LOAD option. This handle can be the same as the handle of the bitmap you have displayed on the screen.

The dimensions of the bitmap are specified by WPRTDATA-BITMAP-HEIGHT and WPRTDATA-BITMAP-WIDTH. The unit of measurement by which the size of the bitmap is calculated is set with WPRTDATA-BITMAP-FLAGS. One of the following values is used:

WPRTBITMAP-SCALE-CELLS | the height and width of a cell depends on the number of rows and columns in the report. The currently selected font for the printer determines the number of rows and columns on a page. The top left corner of a report is row 1, column 1. You may use fractional rows and columns, but if you specify a row or column less than 1, then the bitmap is placed at row 1, column 1.
WPRTBITMAP-SCALE-INCHES | the units represent inches on the printed page.
WPRTBITMAP-SCALE-CENTIMETERS | the units represent centimeters on the printed page.
WPRTBITMAP-SCALE-PIXELS | the units are based on the resolution of the output device. This is measured in dots-per-inch (DPI). Fractional values are ignored.

The location of the top left corner of a bitmap is specified by WPRTDATA-BITMAP-ROW and WPRTDATA-BITMAP-COL. By default, this coordinate is specified in cells. You may choose to use another unit of measurement by setting WPRTDATA-BITMAP-FLAGS to one of the following values (defined in winprint.def):

WPRTBITMAP-UNITS-INCHES | Values are measured in inches.
WPRTBITMAP-UNITS-CENTIMETERS | Values are measured in centimeters.
WPRTBITMAP-UNITS-PIXELS | Values are measured using the dots-per-inch (DPI) resolution of the output device. Only integer values are allowed. The actual size of this measurement varies depending on the target printer's resolution. Consider the unit of measure relative to the resolution of the targeting printer before printing.
WPRTBITMAP-UNITS-CELLS-ABS | Values are measured in cells, and the position of the bitmap is based on the left edge of the paper, regardless of the physical left margin determined by the printer (even if the absolute position is smaller).
WPRTBITMAP-UNITS-INCHES-ABS | Values are measured in inches and the position of the bitmap is based on the left edge of the paper, regardless of the physical left margin determined by the printer (even if the absolute position is smaller).
WPRTBITMAP-UNITS-CENTIMETERS-ABS | Values are measured in centimeters and the position of the bitmap is based on the left edge of the paper, regardless of the physical left margin determined by the printer (even if the absolute position is smaller).

This is illustrated in Example 2, below.

Many printers have much higher resolution than screens do. For example, many laser printers can print 300 or 600 dots per inch while most screens display less than 100 pixels per inch. An image that is 1024 pixels wide would fill or overflow many screens, but would be less than 2 inches wide on a 600 DPI printer. For this reason, bitmaps are usually scaled when they are printed. By default, the runtime scales the image so that the relative proportions of the printed image match those of the same image when it is viewed on the screen.

Scaling a bitmap

To scale a bitmap to a particular size, you must set WPRTDATA-BITMAP-FLAGS to the desired unit of measure (cells, inches, centimeters, or pixels). Then set the desired dimensions of the bitmap in WPRTDATA-BITMAP-WIDTH and WPRTDATA-BITMAP-HEIGHT.

You can either set both dimensions or leave one dimension at zero. When one of the dimensions is set to zero, the relative proportions of the image are unchanged after the scaling of the other dimension is complete.

You can inhibit the scaling done by the runtime by setting WPRTDATA-BITMAP-FLAGS to WPRTBITMAP-PRINTER-BITMAP. This informs the runtime that the bitmap was designed directly for printing on the current printer and should not be scaled. You can also add the value of WPRTDATA-BITMAP-FLAGS to the other scaling options discussed above to prevent the runtime from performing an adjustment to the scaling. Adjustments are usually done to account for the difference in the relative proportions of the screen's X and Y density in comparison to the printer's X and Y density. Some devices have a much higher resolution in one dimension than the other. This adjustment handles the changes needed when you are viewing a screen image on a printer. Most applications, however, should avoid this option because most bitmaps are meant to be displayed on the screen only.

Colors in the bitmap image are preserved by the runtime. It is up to the printer's driver to decide how to print color images on a black-and-white device. Most drivers turn colors into varying shades of gray.

Examples

The following sample code prints the AcuBench logo in the center of an 80-character print line. It scales the image to be 30 characters wide to simplify the centering computation. This example assumes that the printer is already open:

77  LOGO-HANDLE        PIC S9(9) COMP-4.
        :
        :
CALL "W$BITMAP" USING WBITMAP-LOAD, "devsuite.bmp"
    GIVING LOGO-HANDLE
INITIALIZE WPRTDATA-PRINT-BITMAP
MOVE LOGO-HANDLE TO WPRTDATA-BITMAP
MOVE 1 TO WPRTDATA-BITMAP-ROW
MOVE 26 TO WPRTDATA-BITMAP-COL
MOVE 30 TO WPRTDATA-BITMAP-WIDTH

*Height left at zero

MOVE WPRTBITMAP-SCALE-CELLS
     TO WPRTDATA-BITMAP-FLAGS
CALL "WIN$PRINTER" USING WINPRINT-PRINT-BITMAP,
     WINPRINT-DATA
CALL "W$BITMAP" USING WBITMAP-DESTROY, LOGO-HANDLE

The following example code scales a bitmap to be 3-by-3 inches square, and places the top left corner 10 centimeters away from both the left and top margins. This example assumes that the printer is already open:

77  LOGO-HANDLE        PIC S9(9) COMP-4.
        :
        :
CALL "W$BITMAP" USING WBITMAP-LOAD, "your_bitmap.bmp"
     GIVING LOGO-HANDLE
INITIALIZE WPRTDATA-PRINT-BITMAP
MOVE LOGO-HANDLE TO WPRTDATA-BITMAP
MOVE 10 TO WPRTDATA-BITMAP-ROW WPRTDATA-BITMAP-COL.
MOVE 3 TO WPRTDATA-BITMAP-HEIGHT WPRTDATA-BITMAP-WIDTH.
MOVE WPRTBITMAP-SCALE-INCHES TO WPRTDATA-BITMAP-FLAGS.
ADD  WPRTBITMAP-UNITS-CENTIMETERS TO WPRTDATA-BITMAP-FLAGS.

CALL "WIN$PRINTER" USING WINPRINT-PRINT-BITMAP,
     WINPRINT-DATA
CALL "W$BITMAP" USING WBITMAP-DESTROY, LOGO-HANDLE
Parent topic: WINPRINT-DATA op-codes


WINPRINT-SET-CURSOR

This operation code allows you to change the position of the printer's write cursor. This is useful when doing multiple write statements that include a variety of fonts, font sizes, and font attributes.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-CURSOR, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03 WPRTDATA-DRAW REDEFINES
   WPRTDATA-SET-STD-FONT.
      05  WPRTDATA-DRAW-START-X       PIC 9(7)V99 COMP-5.
      05  WPRTDATA-DRAW-START-Y       PIC 9(7)V99 COMP-5.
      05  WPRTDATA-DRAW-STOP-X        PIC 9(7)V99 COMP-5.
      05  WPRTDATA-DRAW-STOP-Y        PIC 9(7)V99 COMP-5.
      05  WPRTDATA-DRAW-UNITS         UNSIGNED-SHORT.
      05  WPRTDATA-DRAW-SHAPE         UNSIGNED-SHORT.

Return Values

This option returns the horizontal and vertical coordinates of the write cursor. If an error is returned, the current cursor position is not affected.

Description

When printing in Windows, the position of text on the printed page is determined by the location of the write cursor. This is usually handled automatically by the runtime, but you may use this operation to position the cursor yourself.

The printer must be open to perform this operation. WPRTDATA-DRAW should be initialized prior to use. The current cursor position on the printer is modified by this call only if WPRTDATA-DRAW-SHAPE is set to a value of 0 and the operation is successful. When the cursor is moved in this manner, subsequent WRITE statements will be affected. One exception is that the vertical position of subsequent calls to WINPRINT-COLUMNS will be altered, but not the horizontal position.

Note: When you call WINPRINT-SET-CURSOR, the operation will automatically test to see if a form feed is pending. If this is the case, the form feed will be performed before the call to this operation is executed.

If you use this operation with WPRDATA-DRAW-SHAPE set to a non-zero value, the cursor is not repositioned. This can be used to inquire the position of the write cursor without changing it. There is no limit to the number of times this operation may be called.

WINPRINT-SET-CURSOR has the following values:

  • WPRTDATA-DRAW-START-X - Specifies the X coordinate of the cursor location. The unit of measure is set with WPRTDATA-DRAW-UNITS. The minimum value of this coordinate is 0.
  • WPRTDATA-DRAW-START-Y - Specifies the Y coordinate of the cursor location. The unit of measure is set with WPRTDATA-DRAW-UNITS. The minimum value of this coordinate is 0.
  • WPRTDATA-DRAW-STOP-X - Returns the lower-right horizontal coordinate of the cursor location. This parameter has no input value, the previous X coordinate is returned. The unit of measure is determined by the setting of WPRTDATA-DRAW-UNITS.
  • WPRTDATA-DRAW-STOP-Y - Returns the lower-right vertical coordinate of the cursor location. This parameter has no input value, the previous Y coordinate is returned. The unit of measure is determined by the setting of WPRTDATA-DRAW-UNITS.
  • WPRTDATA-DRAW-UNITS - Specifies the unit of measure used for the values passed. If an illegal value is used, the default will be used (WPRTUNITS-PIXELS). The unit of measure may be set to one of the following values:
    WPRTUNITS-CELLS Values are measured using the cell size of the currently selected font. The cell-size is determined by the height and width of the 0 character of a font. This is roughly equivalent to measuring in characters.

    Positioning is relative to the individual printer's physical margin. Please note that the margin set in WINPRINT-SET-MARGINS is not used to determine the cursor position.

    If you use a proportional font, it is common for uppercase characters to be wider than this measurement. Non-integer values are allowed in the measurements.

    WPRTUNITS-CELLS-ABS | Values are measured using the cell size of the currently selected font. Positioning is based on the left edge of the paper, regardless of the physical left margin determined by the printer (even if the absolute position is smaller). If the dimensions of the area to be printed are less than the printer's left or top physical margin, or greater than the printer's right or bottom physical margin, WIN$PRINTER will return an error. (Note that due to inherent differences in the hardware of printer manufacturers, this value may not provide truly device-independent results.)
    WPRTUNITS-INCHES | Values are measured in inches. Positioning is relative to the individual printer's physical margin. Please note that the margin set in WINPRINT-SET-MARGINS is not used to determine the cursor position.
    WPRTUNITS-INCHES-ABS | Values are measured in inches. Positioning is based on the left edge of the paper, regardless of the physical left margin determined by the printer (even if the absolute position is smaller). If the dimensions of the area to be printed are less than the printer's left or top physical margin, or greater than the printer's right or bottom physical margin, WIN$PRINTER will return an error.
    WPRTUNITS-CENTIMETERS | Values are measured in centimeters. Positioning is relative to the individual printer's physical margin. Please note that the margin set in WINPRINT-SET-MARGINS is not used to determine the cursor position.
    WPRTUNITS-CENTIMETERS-ABS | Values are measured in centimeters. Positioning is based on the left edge of the paper, regardless of the physical left margin determined by the printer (even if the absolute position is smaller). If the dimensions of the area to be printed are less than the printer's left or top physical margin, or greater than the printer's right or bottom physical margin, WIN$PRINTER will return an error.
    WPRTUNITS-PIXELS (default) Values are measured using the dots-per-inch (DPI) resolution of the output device. Only integer values are allowed in the measurements. Positioning is relative to the individual printer's physical margin. Please note that the margin set in WINPRINT-SET-MARGINS is not used to determine the cursor position.

    The actual size of this measurement varies depending on the target printer's resolution. This means that a coordinate of 5 will appear in a different location on a 300dpi printer than it will on a 600dpi printer. Consider the unit of measure relative to the resolution of the targeting printer before printing.

  • WPRTDATA-DRAW-SHAPE - Determines if subsequent WRITE statements will be affected. A value of 0 sets the position of the write cursor. A non zero value will simply return the coordinates of the current position of the write cursor. Return values are determined by the setting of WPRTDATA-DRAW-UNITS.
    Note: If you are using WPRDATA-DRAW-SHAPE to inquire the position of the write cursor, and WPRTDATA-DRAW-UNITS is set to a value other than WPRTUNITS-PIXELS, there is a possibility that the cursor position returned may not be 100% accurate, due to rounding errors.
Parent topic: WINPRINT-DATA op-codes


WINPRINT-SET-TEXT-COLOR

This operation code specifies the foreground color for text.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-TEXT-COLOR, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03  WPRTDATA-TEXT-COLOR REDEFINES
       WPRTDATA-SET-STD-FONT.   PIC 9(9) COMP-5.

Return Values

This option returns text color prior to the change. Use this value to restore a temporary change.

Description

When printing, color resolution is a result of a combination of three basic colors; Red, Green, and Blue (RGB). The intensity of each color in the mix is determined by a number between 0and 255. For example, the lowest possible intensity, (0,0,0), produces black, and the highest possible intensity (255,255,255), produces white. This formula of three numbers is referred to as the COLORREF.

The ACUCOBOL-GT runtime does not provide a mechanism with which to determine the COLORREF. If you want to specify a color, you must calculate the value yourself. The following C formula can be used to calculate the COLORREF:

(((BYTE) (R) | ((WORD) (BYTE 9g)) <<8))|(((DWORD) (BYTE) (b)) <<16))

See your Windows API documentation for more information about RGB colors and COLORREF values.

The printer must be open to perform this operation. There is no need to reset this function. WPRTDATA-TEXT-COLOR should be initialized prior to use. This operation affects the color used with subsequent WRITE statements. Cursor position is not affected by this operation. This operation is ignored on non-color printers. WINPRINT-SET-TEXT-COLOR has the following value:

WPRTDATA-TEXT-COLOR Specifies the color used to write text. The color is indicated by the COLORREF, representing the percentage used of the three basic colors; Red, Green, and Blue (RGB). The default of 0 is solid black.

Example

This example will set the current text foreground color to light blue when printed on a color printer:

INITIALIZE WPRTDATA-TEXT-COLOR.
MOVE 96 TO RGB-RED.
MOVE 106 TO RGB-GREEN.
MOVE 232 TO RBG-BLUE.
PERFORM CALC-COLORREF.
MOVE COLORREF TO WPRTDATA-TEXT-COLOR.
CALL "WIN$PRINTER" USING
     WINPRINT-SET-TEXT-COLOR
     WPRTDATA-TEXT-COLOR
     GIVING CALL-RESULT.

The sample program graphprn.cbl contains an example of using the C formula described above to determine the RGB color value (CALC-COLORREF).

Parent topic: WINPRINT-DATA op-codes


WINPRINT-SET-FONT

This operation code allows you to select any printer font for spooled reports.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-FONT, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03 WPRTDATA-SET-FONT REDEFINES
      WPRTDATA-SET-STD-FONT.
      05 WPRTDATA-FONT     HANDLE OF FONT.

Description

First, obtain a handle to the desired font with the W$FONT routine described earlier. Once you have the font handle, you can select it as the current font by setting WPRTDATA-FONT to the desired font handle and using WINPRINT-SET-FONT. The font is now associated with the current printer until you change the font again or the runtime finishes. Note that the font is only used for reports printed by the runtime's spooler handler, which you use when you assign a print file to -P SPOOLER.

Fonts are device-specific. If you let the user change printers via WIN$PRINTER's setup operation, then the user should get a new font handle from W$FONT and associate it with the new printer.

You should not DESTROY a font handle that is currently selected as the print font, unless the printer is closed and you will not open it again. If you do, then that font will not be available to the printer.

You may use proportionally spaced fonts in print files. The runtime handles the proportional spacing correctly (in other words, it does not use a fixed width for each character). The runtime computes the number of columns that fit on a page for a proportional font by using the font's average width. (See winspool.cbl for a sample program that uses arbitrary fonts chosen by the user.)

Parent topic: WINPRINT-DATA op-codes


WINPRINT-SET-LINES-PER-PAGE

This operation code sets the number of lines that should be printed on a page.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-LINES-PER-PAGE, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03 WPRT-PAGE-LAYOUT REDEFINES
      WPRTDATA-SET-STD-FONT.
      05 WPRTDATA-LINES-PER-PAGE       UNSIGNED-SHORT.
      05 WPRTDATA-COLUMNS-PER-PAGE     UNSIGNED-SHORT.

Description

Printing forms using the Windows spooler is sometimes difficult because you cannot easily control the height of a chosen font. Most Windows fonts do not conform to older standards about font height. For example, 12 point Courier does not necessarily print at 6 lines per inch. You can use the WINPRINT-GET-PAGE-LAYOUT operation to determine the number of lines that fit on a page for a given font. Sometimes, however, you need to be able to set the line height explicitly.

This operation allows you to do that. It sets the number of lines that should be printed on a page. The runtime uses this number to adjust the height of the printed font. Note that the font is not scaled--it is simply printed in the specified vertical space.

In order to specify the number of lines that will fit on a page, you must consider the height or vertical resolution of each line. WINPRINT-SET-LINES-PER-PAGE obtains the page height, calculates the physical margins of the page, and sets the font height. The value of the font height includes the visible height of a letter plus its top and bottom margins. If your font height is 7 dots-per-inch (dpi), this includes the top and bottom margins of the font itself, so the actual font height might be only 5 dpi. Note that these values differ from font to font.

When using this option, set the number of lines desired in WPRTDATA-LINES-PER-PAGE (also defined in winprint.def). Then pass WINPRINT-DATA to the routine. For example:

     * Set 60 lines per page
          MOVE 60 TO WPRTDATA-LINES-PER-PAGE
          CALL "WIN$PRINTER"
             USING WINPRINT-SET-LINES-PER-PAGE,
             WINPRINT-DATA

You can set the lines per page with the spooler open or closed. If you set it when it is open, then the new font height takes effect the next time the page position is advanced. In either case, the lines per page is reset to the default value the next time the spooler is closed. You can explicitly reset to the default font height by setting WPRTDATA-LINES-PER-PAGE to zero.

Note: We do not recommend using this operation when printing with -P SPOOLER-DIRECT or -Q printername DIRECT=ON. When you print in DIRECT mode, the Windows print spooler has no control over the printer, the printer is not initialized by the Windows printer driver. This means that the print job uses the hardware defaults. For example, if you print in DIRECT mode to a printer with the hardware default paper size set to US letter format, that is the format used, even if the driver has A4 paper set as the default. In this situation, the operation is likely to return incorrect values.
Parent topic: WINPRINT-DATA op-codes


WINPRINT-SET-MARGINS

This operation code allows you to set the margins on a report.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-MARGINS, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
   03 WPRTDATA-MARGINS REDEFINES
      WPRTDATA-SET-STD-FONT.
      05 WPRTDATA-TOP-MARGIN           PIC 9(7)V99 COMP-5.
      05 WPRTDATA-BOTTOM-MARGIN        PIC 9(7)V99 COMP-5.
      05 WPRTDATA-LEFT-MARGIN          PIC 9(7)V99 COMP-5.
      05 WPRTDATA-RIGHT-MARGIN         PIC 9(7)V99 COMP-5.
      05 WPRTDATA-MARGIN-UNITS         UNSIGNED-SHORT.
Note: This group item should be initialized before it is used.

Description

When combined with the ability to set the exact height of a line (see WINPRINT-SET-LINES-PER-PAGE), this operation lets you reliably print on pre-printed forms with many different devices. WINPRINT-SET-MARGINS sets the margins for the next report if the printer is not open, or for the current report if the printer is open. If the printer is open and the current page is blank, the margin change occurs for the current page. Otherwise, the margin change occurs on the next page.

Note: Most printers have minimum margins that cannot physically be printed in, regardless of the setting of the logical margins.

Setting Margins

The four margin fields should be set to the values you want to use. For example, to set half-inch top and bottom margins you would move .5 to WPRTDATA-TOP-MARGIN and WPRTDATA-BOTTOM-MARGIN. You can set a margin to zero to use the printer's default margins.

Note: This operation calculates the printable area of a report when determining the capacity for lines or columns. Setting a value for WPRTDATA-RIGHT-MARGIN does not cause the print line to be truncated.

Before you can set the margins, the MARGIN-UNITS field must be set to a level 78 that describes the measurement units. The choices are:

WPRTMARGIN-DEFAULT-MARGINS | Use printer default margins (this is the default).
WPRTMARGIN-PIXELS | Margins expressed in printer-dependent units. Laser printers, for example, use either 300 or 600 units per inch.
WPRTMARGIN-CELLS | Margins expressed as a number of rows or columns based on the currently selected font.
WPRTMARGIN-INCHES | Margins expressed in inches.
WPRTMARGIN-CENTIMETERS | Margins expressed in centimeters.

To use the margin-setting feature to simplify printing on pre-printed forms, we suggest this sequence:

  1. Establish which printer you want to use.
  2. Select the font.
  3. Set the margins.
  4. Set the line height.

It is important to note that step (3) should precede step (4) because the line height depends on the top and bottom margins that you have set. For an 11" form, a typical scenario might be:

Font: Courier New, 12 point
Margins: .5" top and bottom
Lines per page: 60

This would result in 6 lines per inch with 3 blank lines at the top and bottom of each page. The code to set the margins for this case would be:

INITIALIZE WPRTDATA-MARGINS
MOVE .5 TO WPRTDATA-TOP-MARGIN, WPRTDATA-BOTTOM-MARGIN
MOVE WPRTMARGIN-INCHES TO WPRTDATA-MARGIN-UNITS
CALL "WIN$PRINTER" USING WINPRINT-SET-MARGINS,
      WINPRINT-DATA
Parent topic: WINPRINT-DATA op-codes


WINPRINT-SET-STD-FONT

This operation code allows you to select one of a number of predefined fonts to use for the report. You must make this selection prior to opening the print file.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-STD-FONT, WINPRINT-DATA
    GIVING RESULT

Parameters

WINPRINT-DATA Group item defined in winprint.def as follows:
01 WINPRINT-DATA.
   03 WPRTDATA-SET-STD-FONT.
      05 WPRTDATA-STD-FONT            PIC X COMP-X.
      05 FILLER                       PIC X(21).

Description

The font selected is used until explicitly changed or the runtime exits. You specify which font to use by moving one of the following level 78 values to WPRTDATA-STD-FONT before calling WIN$PRINTER:

WPRTFONT-DEFAULT | Requests the printer's default font. This is the initial setting.
WPRTFONT-COURIER-12 | Requests a 12-point TrueType Courier font.
WPRTFONT-COURIER-12-COMP | Requests a 12-point TrueType Courier font and rescales it so that at least 132 columns of print will fit on a page. This is similar to the compressed print mode supported by many printers.
WPRTFONT-COURIER-10 | Requests a 10-point TrueType Courier font.
WPRTFONT-COURIER-10-COMP | Requests a 10-point TrueType Courier font and rescales it so that at least 132 columns of print will fit on a page.

When you are using either of the compressed print modes, the rescaling of the font occurs when the print file is opened. This ensures that the font is scaled correctly for the current page size and orientation. The rescaling operation normally results in skinny characters, but can actually result in stretched characters if more than 132 characters would naturally fit on a page. The runtime asks the Windows TrueType font engine to scale the font to fit exactly 132 characters on a line even if more would normally fit.

You should be aware that the TrueType font engine does not always produce exact results, particularly when rescaling a font. You may end up with a font that fits more than 132 columns on a page. You may also end up with a font that is a slightly different height when compressed than when not. You can also end up with a font that is only vaguely related to the requested one if, for example, the user has removed the TrueType fonts or if the print driver cannot handle TrueType fonts. These effects are due to the internal workings of the TrueType font engine and the way that Windows handles fonts in general. Under Windows, an application cannot select a particular font. Instead, it describes the font's characteristics and Windows selects the closest matching font using a weighted-penalty system for deciding which font is the closest match. Sometimes, no font matches exactly, so Windows substitutes the font that has the closest match.

Parent topic: WINPRINT-DATA op-codes


WINPRINT-SET-BKMODE

Usage

CALL "WIN$PRINTER"
     USING WINPRINT-SET-BKMODE
       desired-bkmode

Parameters

bkmode bkmode may be either:
78 WPRT-BKMODE-TRANSPARENT              VALUE 1.
78 WPRT-BKMODE-OPAQUE                   VALUE 2.

Description

WINPRINT-SET-BKMODE enables you to set the background mode for printing. This is useful for adding watermark effect to prints.

By calling this op-code, the printing mode of the current print job is set accordingly. Note that if you have multiple print jobs, and you are not setting the current print job, WINPRINT-SET-JOB must be called prior to this op-code to target the correct print. A call to this function with no active print will be ignored, and a value that differs from those specified above will be ignored.

Parent topic: WINPRINT-DATA op-codes


WINPRINT-SELECTION op-codes

The following operation codes use the data item WINPRINT-SELECTION (defined in winprint.def). These operations are used to set the properties of a printer, including features such as printer selection, number of copies, page orientation and collating.

  • WINPRINT-GET-CURRENT-INFO
  • WINPRINT-GET-CURRENT-INFO-EX
  • WINPRINT-GET-NO-PRINTERS
  • WINPRINT-GET-PRINTER-INFO
  • WINPRINT-GET-PRINTER-INFO-EX
  • WINPRINT-GET-PRINTER-STATUS
  • WINPRINT-SET-PRINTER
  • WINPRINT-SET-PRINTER-EX
  • WINPRINT-SETUP-EX
Parent topic: WIN$PRINTER op-codes


WINPRINT-GET-CURRENT-INFO

This operation code returns information about the currently selected printer.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-CURRENT-INFO, WINPRINT-SELECTION
    GIVING RESULT

Parameters

WINPRINT-SELECTION Group item defined in winprint.def as follows:
01 WINPRINT-SELECTION.
   03 WINPRINT-NAME                    PIC X(80).
   03 WINPRINT-PORT                    PIC X(80).
   03 WINPRINT-DRIVER                  PIC X(80).
   03 WINPRINT-DRV-VERSION             SIGNED-INT.
   03 WINPRINT-NO-OF-PRINTERS          SIGNED-SHORT.
      88 WPRTERR-NO-PRINTERS           VALUE -1.
   03 WINPRINT-IS-DEFAULT              SIGNED-SHORT.
      88 WPRT-IS-NOT-DEFAULT           VALUE 0.
      88 WPRT-IS-DEFAULT               VALUE 1.
   03 WINPRINT-COPIES                  SIGNED-SHORT.
      88 WPRT-HAS-NO-COPY              VALUE 1.
   03 WINPRINT-ORIENTATION             SIGNED-SHORT.
      88 WPRT-HAS-NO-LANDSCAPE         VALUE 0.
      88 WPRT-HAS-LANDSCAPE            VALUE 1.
   03 WINPRINT-QUALITY                 SIGNED-SHORT.
   03 WINPRINT-CURR-ORIENTATION        SIGNED-SHORT.
   03 WINPRINT-CURR-COPIES             SIGNED-SHORT.

Return Values

A printer is considered selected if it has performed a print using -Q <printername or -P SPOOLER, or if WIN$PRINTER has executed using any of the WINPRINT-DATA op-codes. If no printer is selected, this operation will return information about the Windows default printer.

Description

The printer may be open or closed to perform these functions. There is no need to reset any of these functions. WINPRINT-SELECTION should be initialized prior to use. WINPRINT-GET-CURRENT-INFO has the following values:

WINPRINT-NAME | Returns the name of the currently selected printer.
WINPRINT-PORT | Specifies the printer port (or UNC address) of the currently selected printer.
WINPRINT-DRIVER | Specifies the printer driver name.
WINPRINT-DRV-VERSION | Specifies the version number of the printer driver (vendor-specific).
WINPRINT-NO-OF-PRINTERS | Specifies the number of the currently selected printer in the runtime's internal list.
WINPRINT-IS-DEFAULT | Determines if the printer is the Windows print spooler default printer. If yes, the returned value is WPRT-IS-DEFAULT.
WINPRINT-COPIES | Returns the number of copies the printer is capable of producing. Typically this number is 99 or 999.
WINPRINT-ORIENTATION | Determines if the printer supports landscape orientation. If yes, the return value is WPRT-HAS-LANDSCAPE.
WINPRINT-QUALITY | Returns the current setting for the varying grades of print quality. This value applies to dot-matrix printers. Most inkjet and laser printers do not support this method of determining the level of print quality.
WINPRINT-CURR-COPIES | Returns the current default value for the number of copies to print.
Parent topic: WINPRINT-SELECTION op-codes


WINPRINT-GET-CURRENT-INFO-EX

This operation code returns additional information about the currently selected printer, extending the functionality of WINPRINT-GET-CURRENT-INFO.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-CURRENT-INFO-EX, WINPRINT-SELECTION
    GIVING RESULT

Parameters

WINPRINT-SELECTION Group item defined in winprint.def as follows:
01  WINPRINT-SELECTION.
   03 WINPRINT-NAME                    PIC X(80).
   03 WINPRINT-PORT                    PIC X(80).
   03 WINPRINT-DRIVER                  PIC X(80).
   03 WINPRINT-DRV-VERSION             SIGNED-INT.
   03 WINPRINT-NO-OF-PRINTERS          SIGNED-SHORT.
   03 WINPRINT-IS-DEFAULT              SIGNED-SHORT.
   03 WINPRINT-COPIES                  SIGNED-SHORT.
   03 WINPRINT-ORIENTATION             SIGNED-SHORT.
   03 WINPRINT-QUALITY                 SIGNED-SHORT.
   03 WINPRINT-CURR-ORIENTATION        SIGNED-SHORT.
   03 WINPRINT-CURR-COPIES             SIGNED-SHORT.
   03 WINPRINT-DUPLEX                  SIGNED-SHORT.
   03 WINPRINT-COLLATE                 SIGNED-SHORT.
   03 WINPRINT-COLOR                   SIGNED-SHORT.
   03 WINPRINT-CURR-DUPLEX             SIGNED-SHORT.
   03 WINPRINT-CURR-COLLATE            SIGNED-SHORT.
   03 WINPRINT-CURR-PAPERSIZE          SIGNED-SHORT.
   03 WINPRINT-CURR-TRAY               SIGNED-SHORT.
   03 WINPRINT-CURR-COLOR              SIGNED-SHORT.
   03 WINPRINT-JOB-TITLE               PIC X(80).

This group item has numerous conditional variables. See winprint.def for the complete list.

Return Values

A printer is considered selected if it has performed a print using -Q printername or -P SPOOLER, or if WIN$PRINTER has executed using any of the WINPRINT-DATA op-codes. If no printer is selected, this operation will return information about the Windows default printer.

Description

The printer may be open or closed to perform these functions. There is no need to reset any of these functions. WINPRINT-SELECTION should be initialized prior to use. WINPRINT-GET-CURRENT-INFO-EX has all the same values as WINPRINT-GET-CURRENT-INFO plus the following additional values:

WINPRINT-DUPLEX | Determines if the currently selected printer supports duplex printing. If yes, the returned value is WPRT-HAS-DUPLEX.
WINPRINT-COLLATE | Determines if the currently selected printer supports collating. If yes, the returned value is WPRT-HAS-COLLATE.
WINPRINT-COLOR | Determines if the currently selected printer can print in color. If color printing is supported, the returned value is WPRT-HAS-COLOR.
WINPRINT-CURR-DUPLEX | Returns the current duplex setting of the printer. Possible values are: WPRT-SIMPLEX, WPRT-DUPLEX-VERTICAL, and WPRT-DUPLEX-HORIZONTAL.
WINPRINT-CURR-COLLATE | Determines if the collating feature of the currently selected printer is turned on or off.
WINPRINT-CURR-PAPERSIZE | Returns the current paper size selected in the printer driver. Values less than 42 should correspond to the PAPER-SIZES table in "winprint.def". Values greater than 41 and less than 69 are defined by version 4.x of Windows NT. Values greater than 68 and less than 119 are defined in Windows 2000. Values greater than 118 and less than 256 are considered undefined. Values greater than 255 are considered user defined.
WINPRINT-CURR-TRAY | Returns the currently selected paper tray as defined in the printer driver. Values less than 16 should correspond to the PAPER-TRAYS table in winprint.def. Values greater than 15 and less than 256 are considered undefined. Values greater than 255 are considered device specific. Values 12 and 13 are not defined in the PAPER-SIZES table in winprint.def. This matches a similar gap in the Windows API. Refer to prndemox.cbl for an example of how to compensate for these undefined values.
WINPRINT-CURR-COLOR | Determines if the printer is in the proper mode to print in color. If yes, WPRT-COLOR is returned. Monochromatic printers or color printers with color support disabled return WPRT-MONOCHROME. Note: When using one of these extended operations, it is best to pair it with a corresponding extended operation. For example, use WINPRINT-GET-CURRENT-INFO-EX with WINPRINT-SET-PRINTER-EX, instead of with WINPRINT-SET-PRINTER.
Parent topic: WINPRINT-SELECTION op-codes


WINPRINT-GET-NO-PRINTERS

This operation code retrieves the number of printers installed on a system.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-NO-PRINTERS, WINPRINT-SELECTION
    GIVING RESULT

Parameters

WINPRINT-SELECTION Group item defined in winprint.def as follows:
01 WINPRINT-SELECTION.
   03 WINPRINT-NAME                    PIC X(80).
   03 WINPRINT-PORT                    PIC X(80).
   03 WINPRINT-DRIVER                  PIC X(80).
   03 WINPRINT-DRV-VERSION             SIGNED-INT.
   03 WINPRINT-NO-OF-PRINTERS          SIGNED-SHORT.
      88 WPRTERR-NO-PRINTERS           VALUE -1.
   03 WINPRINT-IS-DEFAULT              SIGNED-SHORT.
      88 WPRT-IS-NOT-DEFAULT           VALUE 0.
      88 WPRT-IS-DEFAULT               VALUE 1.
   03 WINPRINT-COPIES                  SIGNED-SHORT.
      88 WPRT-HAS-NO-COPY              VALUE 1.
   03 WINPRINT-ORIENTATION             SIGNED-SHORT.
      88 WPRT-HAS-NO-LANDSCAPE         VALUE 0.
      88 WPRT-HAS-LANDSCAPE            VALUE 1.
   03 WINPRINT-QUALITY                 SIGNED-SHORT.
   03 WINPRINT-CURR-ORIENTATION        SIGNED-SHORT.
   03 WINPRINT-CURR-COPIES             SIGNED-SHORT.

Return Values

The number returned by this operation will be stored in WINPRINT-NO-OF-PRINTERS.

The number in WINPRINT-NO-OF-PRINTERS may differ depending on the host operating system. On a Windows 98 system, the number in WINPRINT-NO-OF-PRINTERS will represent the number of printers that are attached with a local driver. But in a Windows NT/Windows 2000 environment, the number in WINPRINT-NO-OF-PRINTERS will represent the number of printers that are attached with a local driver and possibly include the number of remote printers with drivers stored on network servers.

Description

This op-code does not alter any of the current printer settings. It is recommended, but not required, that this op-code be executed before the WINPRINT-GET-PRINTER-INFO op-code.

Parent topic: WINPRINT-SELECTION op-codes


WINPRINT-GET-PRINTER-INFO

This operation code retrieves information about a particular printer. It does not alter any of the current printer settings.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-PRINTER-INFO, WINPRINT-SELECTION
    GIVING RESULT

Parameters

WINPRINT-SELECTION Group item defined in winprint.def as follows:
01 WINPRINT-SELECTION.
   03 WINPRINT-NAME                    PIC X(80).
   03 WINPRINT-PORT                    PIC X(80).
   03 WINPRINT-DRIVER                  PIC X(80).
   03 WINPRINT-DRV-VERSION             SIGNED-INT.
   03 WINPRINT-NO-OF-PRINTERS          SIGNED-SHORT.
      88 WPRTERR-NO-PRINTERS           VALUE -1.
   03 WINPRINT-IS-DEFAULT              SIGNED-SHORT.
      88 WPRT-IS-NOT-DEFAULT           VALUE 0.
      88 WPRT-IS-DEFAULT               VALUE 1.
   03 WINPRINT-COPIES                  SIGNED-SHORT.
      88 WPRT-HAS-NO-COPY              VALUE 1.
   03 WINPRINT-ORIENTATION             SIGNED-SHORT.
      88 WPRT-HAS-NO-LANDSCAPE         VALUE 0.
      88 WPRT-HAS-LANDSCAPE            VALUE 1.
   03 WINPRINT-QUALITY                 SIGNED-SHORT.
   03 WINPRINT-CURR-ORIENTATION        SIGNED-SHORT.
   03 WINPRINT-CURR-COPIES             SIGNED-SHORT.

Return Values

Device names up to 80 characters in length will be stored. If a name is wider than 80 characters, it will be truncated from the rightmost position. These names may contain embedded spaces. The following information will be returned:

WINPRINT-NAME | Holds the name of the selected printer as given in the Printers folder under Settings.
WINPRINT-PORT | Holds the name of the selected port (or UNC address) as given in the properties of the printer.
WINPRINT-DRIVER | Holds the name of the assigned driver as seen in the properties of the printer. Note that for remote printers, this name will almost always be given as winspool.
WINPRINT-DRV-VERSION | Holds the version number of the driver for the requested printer.
WINPRINT-NO-OF-PRINTERS | Holds the number of the current printer. Remember, this number is based on the order of printers in the computer's internal printer list, and may change from time to time. It is not recommended to identify a printer by number unless you first enumerate the printers by calling WINPRINT-GET-NO-PRINTERS.
WINPRINT-IS-DEFAULT | Holds the value of 1 if the printer is the Windows default printer, otherwise it is set to 0.
WINPRINT-COPIES | Holds the maximum number of copies the printer is able to provide. The most common value is 99. If a printer is not copy capable, it will have the value of 1.
WINPRINT-CURR-COPIES | Returns the current number of copies the driver is set to print. Note that some printers return a value of 1, indicating that the original is copy number 1. Other printers appear to return a value of 0, indicating an original plus 0 copies. You can change this value to the number of copies you wish to print.
WINPRINT-QUALITY | Returns the current setting for the varying grades of print quality. This value applies to dot-matrix printers. Most inkjet and laser printers do not support this method of determining the level of print quality.
WINPRINT-ORIENTATION | Holds a value indicating the orientation ability of the printer. If portrait and landscape modes are supported, this value is set to 1. If only portrait mode is supported, it is set to 0.
WINPRINT-CURR-ORIENTATION | Returns the current orientation set in the driver, if portrait mode is active, the value is set to 1. If landscape mode is active, the value is set to 2. A value of 0 uses the printer's default setting. You can change this value to set the orientation you prefer.

Description

Calling the op-code WINPRINT-GET-NO-PRINTERS before calling WINPRINT-GET-PRINTER-INFO is recommended. However, it is not necessary to perform WINPRINT-GET-NO-PRINTERS each time you run WINPRINT-GET-PRINTER-INFO. You can perform the operation once and store the data until it is needed.

Note: If you want to retrieve information about all the printers on the system, start with a value of 1 in WINPRINT-NO-OF-PRINTERS in the WINPRINT-SELECTION record. Increment this value by one for each new execution until a negative value is returned.
Parent topic: WINPRINT-SELECTION op-codes


WINPRINT-GET-PRINTER-INFO-EX

This operation code returns additional information about a particular printer, extending the functionality of WINPRINT-GET-PRINTER-INFO. It does not alter any of the current printer settings.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-PRINTER-INFO-EX, WINPRINT-SELECTION
    GIVING RESULT

Parameters

WINPRINT-SELECTION Group item defined in winprint.def as follows:
01  WINPRINT-SELECTION.
   03 WINPRINT-NAME                    PIC X(80).
   03 WINPRINT-PORT                    PIC X(80).
   03 WINPRINT-DRIVER                  PIC X(80).
   03 WINPRINT-DRV-VERSION             SIGNED-INT.
   03 WINPRINT-NO-OF-PRINTERS          SIGNED-SHORT.
   03 WINPRINT-IS-DEFAULT              SIGNED-SHORT.
   03 WINPRINT-COPIES                  SIGNED-SHORT.
   03 WINPRINT-ORIENTATION             SIGNED-SHORT.
   03 WINPRINT-QUALITY                 SIGNED-SHORT.
   03 WINPRINT-CURR-ORIENTATION        SIGNED-SHORT.
   03 WINPRINT-CURR-COPIES             SIGNED-SHORT.
   03 WINPRINT-DUPLEX                  SIGNED-SHORT.
   03 WINPRINT-COLLATE                 SIGNED-SHORT.
   03 WINPRINT-COLOR                   SIGNED-SHORT.
   03 WINPRINT-CURR-DUPLEX             SIGNED-SHORT.
   03 WINPRINT-CURR-COLLATE            SIGNED-SHORT.
   03 WINPRINT-CURR-PAPERSIZE          SIGNED-SHORT.
   03 WINPRINT-CURR-TRAY               SIGNED-SHORT.
   03 WINPRINT-CURR-COLOR              SIGNED-SHORT.
   03 WINPRINT-JOB-TITLE               PIC X(80).

This group item has numerous conditional variables. See winprint.def for the complete list.

Return Values

This operation returns information about the currently selected printer using the values described in WINPRINT-GET-PRINTER and the values described below.

Description

The printer may be open or closed to perform these functions. There is no need to reset any of these functions. WINPRINT-SELECTION should be initialized prior to use. WINPRINT-GET-PRINTER-INFO-EX has all the same values as WINPRINT-GET-PRINTER-INFO plus the following additional values:

WINPRINT-DUPLEX | Determines if the currently selected printer supports duplex printing. If yes, the returned value is WPRT-HAS-DUPLEX.
WINPRINT-COLLATE | Determines if the currently selected printer supports collating. If yes, the returned value is WPRT-HAS-COLLATE.
WINPRINT-COLOR | Determines if the currently selected printer can print in color. If color printing is supported, the returned value is WPRT-HAS-COLOR.
WINPRINT-CURR-DUPLEX | Returns the current duplex setting of the printer. Possible values are: WPRT-SIMPLEX, WPRT-DUPLEX-VERTICAL, and WPRT-DUPLEX-HORIZONTAL.
WINPRINT-CURR-COLLATE | Determines if the collating feature of the currently selected printer is turned on or off.
WINPRINT-CURR-PAPERSIZE | Returns the current paper size selected in the printer driver. Values less than 42 should correspond to the PAPER-SIZES table in "winprint.def". Values greater than 41 and less than 69 are defined by version 4.x of Windows NT. Values greater than 68 and less than 119 are defined in Windows 2000. Values greater than 118 and less than 256 are considered undefined. Values greater than 255 are considered user defined.
WINPRINT-CURR-TRAY | Returns the currently selected paper tray as defined in the printer driver. Values less than 16 should correspond to the PAPER-TRAYS table in winprint.def. Values greater than 15 and less than 256 are considered undefined. Values greater than 255 are considered device specific. Values 12 and 13 are not defined in the PAPER-SIZES table in winprint.def. This matches a similar gap in the Windows API. Refer to "prndemox.cbl" for an example of how to compensate for these undefined values.
WINPRINT-CURR-COLOR | Determines if the printer is in the proper mode to print in color. If yes, WPRT-COLOR is returned. Monochromatic printers or color printers with color support disabled return WPRT-MONOCHROME.
Note: When using one of these extended operations, it is best to pair it with a corresponding extended operation. For example, use WINPRINT-GET-PRINTER-INFO-EX with WINPRINT-SET-PRINTER-EX, instead of with WINPRINT-SET-PRINTER.
Parent topic: WINPRINT-SELECTION op-codes


WINPRINT-GET-PRINTER-STATUS

This operation code allows you to check the current status of a printer. This can be used to see if a printer is available to perform a print job or not.

In some cases the printer may respond that it is ready when, in fact, there are jobs pending because the printer is out of paper or paused. (This is a feature of the Windows API.) We recommend that you check condition of the printer using the WINPRINT-JOB-STATUS operation codes.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-PRINTER-STATUS, WINPRINT-SELECTION
    GIVING RESULT

Parameters

WINPRINT-SELECTION Group item defined in winprint.def as follows:
01 WINPRINT-SELECTION.
   03 WINPRINT-NAME                    PIC X(80).
   03 WINPRINT-PORT                    PIC X(80).
   03 WINPRINT-DRIVER                  PIC X(80).
   03 WINPRINT-DRV-VERSION             SIGNED-INT.
   03 WINPRINT-NO-OF-PRINTERS          SIGNED-SHORT.
      88 WPRTERR-NO-PRINTERS           VALUE -1.
   03 WINPRINT-IS-DEFAULT              SIGNED-SHORT.
      88 WPRT-IS-NOT-DEFAULT           VALUE 0.
      88 WPRT-IS-DEFAULT               VALUE 1.
   03 WINPRINT-COPIES                  SIGNED-SHORT.
      88 WPRT-HAS-NO-COPY              VALUE 1.
   03 WINPRINT-ORIENTATION             SIGNED-SHORT.
      88 WPRT-HAS-NO-LANDSCAPE         VALUE 0.
      88 WPRT-HAS-LANDSCAPE            VALUE 1.
   03 WINPRINT-QUALITY                 SIGNED-SHORT.
   03 WINPRINT-CURR-ORIENTATION        SIGNED-SHORT.
   03 WINPRINT-CURR-COPIES             SIGNED-SHORT.

Return Values

This operation returns the printer status as defined in the Windows API.

A great variety of conditions can affect a single print job and printer status may be the result of a combination of values. This makes it impossible to catalog all possible status settings in winprint.def. Refer to the Windows API documentation for a description of any status not covered in that file.

Description

This operation may be called any time, whether the printer is open or not. There is no need to reset this function. WINPRINT-SELECTION should be initialized prior to use. WINPRINT-NAME must be set to the name of the desired printer. WINPRINT-NAME passes the printer name as an input variable. Printer settings are not modified by this operation.

Note: If this function is executed on a networked printer with a missing or malfunctioning network, your application may appear to hang. Once the timeout has completed, your application will resume. This is a feature of the Windows API, not an effect of the runtime.
Parent topic: WINPRINT-SELECTION op-codes


WINPRINT-SET-PRINTER

This operation code allows you to select a specific printer and set properties.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-PRINTER, WINPRINT-SELECTION
    GIVING RESULT

Parameters

WINPRINT-SELECTION Group item defined in winprint.def as follows:
01 WINPRINT-SELECTION.
   03 WINPRINT-NAME                    PIC X(80).
   03 WINPRINT-PORT                    PIC X(80).
   03 WINPRINT-DRIVER                  PIC X(80).
   03 WINPRINT-DRV-VERSION             SIGNED-INT.
   03 WINPRINT-NO-OF-PRINTERS          SIGNED-SHORT.
      88 WPRTERR-NO-PRINTERS           VALUE -1.
   03 WINPRINT-IS-DEFAULT              SIGNED-SHORT.
      88 WPRT-IS-NOT-DEFAULT           VALUE 0.
      88 WPRT-IS-DEFAULT               VALUE 1.
   03 WINPRINT-COPIES                  SIGNED-SHORT.
      88 WPRT-HAS-NO-COPY              VALUE 1.
   03 WINPRINT-ORIENTATION             SIGNED-SHORT.
      88 WPRT-HAS-NO-LANDSCAPE         VALUE 0.
      88 WPRT-HAS-LANDSCAPE            VALUE 1.
   03 WINPRINT-QUALITY                 SIGNED-SHORT.
   03 WINPRINT-CURR-ORIENTATION        SIGNED-SHORT.
   03 WINPRINT-CURR-COPIES             SIGNED-SHORT.

Description

WINPRINT-NAME must hold the name of the printer as received by WINPRINT-GET-PRINTER-INFO. If WINPRINT-COPIES is set to a positive value greater than one, you may use WINPRINT-CURR-COPIES to set the number of copies to print. If WINPRINT-CURR-COPIES is set to zero, the printer driver default is used. If WINPRINT-ORIENTATION is set to a positive value, then WINPRINT-CURR-ORIENTATION may be set to any of the following values:

WPRTSEL-ORIENT-DEFAULT | For printer default.
WPRTSEL-ORIENT-PORTRAIT | For portrait orientation.
WPRTSEL-ORIENT-LANDSCAPE | For landscape orientation.

WINPRINT-QUALITY may be used to select varying grades of print quality. One may use the predefined constants for this purpose:

WPRTSEL-QUALITY-DEFAULT | For printer default.
WPRTSEL-QUALITY-HIGH | For high quality.
WPRTSEL-QUALITY-MEDIUM | For medium quality.
WPRTSEL-QUALITY-LOW | For low quality.
WPRTSEL-QUALITY-DRAFT | For draft quality.
Note: WINPRINT-QUALITY only applies to dot-matrix-type printers. Most inkjet and laser printers do not support this method of determining different levels of print quality.

Specifying a Printer

The steps for actually specifying a printer differ depending on whether or not you know the name of the printer.

If you know the name of the printer, set WINPRINT-NO-OF-PRINTERS to 0, and set WINPRINT-NAME to the name of the printer as given in the Printers folder under Settings. Specify any settings you desire and call WIN$PRINTER using WINPRINT-SET-PRINTER.

If you don't know the name of the printer, start by calling WIN$PRINTER using WINPRINT-GET-NO-PRINTERS and storing the result in an appropriate variable. Next, enumerate the printers by iterating through the available printers starting with 1, ending with the value obtained from WINPRINT-NO-OF-PRINTERS. Stop when you have found the printer you want. Specify the settings you desire and call WIN$PRINTER again, this time using WINPRINT-SET-PRINTER. An example of this scenario can be found in the sample program prndemo.cbl.

The WINPRINT-SET-PRINTER operation also allows you to change some printer settings while the printer is open, or spooling. For example, if you are printing a portrait-oriented report that contains a single-page table in landscape format, you would need to change the page orientation during printing. When you are using this feature, the only properties you can alter for this op-code are those controlling the number of copies, the page orientation and the print quality. All other properties for this op-code use the existing settings.

Comments

If you call WINPRINT-SET-PRINTER on an open print job, there is an implicit form feed. WINPRINT-SET-PRINTER must be called before you begin to print the page with the different setting, and after all printing is done on the page immediately preceding the page with the different setting. When the current page is finished, the print cursor is positioned at the top leftmost point on the new page. The new page accepts the current values specified for number of copies, page orientation and print quality, provided they are within legal parameters for the particular setting.

Because this feature of WINPRINT-SET PRINTER occurs during a print job, it alters the document being printed, particularly by setting any current page margins to the printer default values. This means that if you have customized margins and you call WINPRINT-SET-PRINTER on an open printer, you will have to reset the margins after the call to reestablish your custom margin settings.

Margin limitations may vary from portrait to landscape on the same printer and you may not be able to specify the same values for both orientations.

Changing the output device with this operation will reset any columns you have set using WINPRINT-COLUMN op-codes.

Example

Here is an example of how to specify a printer named Gutenberg:

INITIALIZE WINPRINT-NO-OF-PRINTERS.
MOVE "Gutenberg" TO WINPRINT-NAME.
CALL "WIN$PRINTER"
    USING WINPRINT-GET-PRINTER-INFO WINPRINT-SELECTION.

*we want to set landscape orientation

MOVE WPRTSEL-ORIENT-LANDSCAPE TO WINPRINT-CURR-ORIENTATION.

*with this call, subsequent print jobs will print in landscape
*orientation from Gutenberg

CALL "WIN$PRINTER"
    USING WINPRINT-SET-PRINTER WINPRINT-SELECTION.
Parent topic: WINPRINT-SELECTION op-codes


WINPRINT-SET-PRINTER-EX

This operation code allows you to select a specific printer and set properties, extending the functionality of WINPRINT-SET-PRINTER.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-PRINTER-EX, WINPRINT-SELECTION

Parameters

WINPRINT-SELECTION Group item defined in winprint.def as follows:
01  WINPRINT-SELECTION.
   03 WINPRINT-NAME                    PIC X(80).
   03 WINPRINT-PORT                    PIC X(80).
   03 WINPRINT-DRIVER                  PIC X(80).
   03 WINPRINT-DRV-VERSION             SIGNED-INT.
   03 WINPRINT-NO-OF-PRINTERS          SIGNED-SHORT.
   03 WINPRINT-IS-DEFAULT              SIGNED-SHORT.
   03 WINPRINT-COPIES                  SIGNED-SHORT.
   03 WINPRINT-ORIENTATION             SIGNED-SHORT.
   03 WINPRINT-QUALITY                 SIGNED-SHORT.
   03 WINPRINT-CURR-ORIENTATION        SIGNED-SHORT.
   03 WINPRINT-CURR-COPIES             SIGNED-SHORT.
   03 WINPRINT-DUPLEX                  SIGNED-SHORT.
   03 WINPRINT-COLLATE                 SIGNED-SHORT.
   03 WINPRINT-COLOR                   SIGNED-SHORT.
   03 WINPRINT-CURR-DUPLEX             SIGNED-SHORT.
   03 WINPRINT-CURR-COLLATE            SIGNED-SHORT.
   03 WINPRINT-CURR-PAPERSIZE          SIGNED-SHORT.
   03 WINPRINT-CURR-TRAY               SIGNED-SHORT.
   03 WINPRINT-CURR-COLOR              SIGNED-SHORT.
   03 WINPRINT-JOB-TITLE               PIC X(80).

This group item has numerous conditional variables. See winprint.def for the complete list.

Description

The printer may be open or closed to perform these functions. There is no need to reset any of these functions. WINPRINT-SELECTION should be initialized prior to use. WINPRINT-SET-PRINTER-EX has all the same values as WINPRINT-SET-PRINTER plus the following additional values:

WINPRINT-CURR-DUPLEX If WINPRINT-DUPLEX is set to a positive value greater than one, you may set this to one of the following values:
  • WPRT-SIMPLEX
  • WPRT-DUPLEX-VERTICAL
  • WPRT-DUPLEX-HORIZONTAL
WINPRINT-CURR-COLLATE | If WINPRINT-COLLATE is set to a positive value greater than one, you may use WINPRINT-CURR-COLLATE to turn collating on or off.
WINPRINT-CURR-PAPERSIZE | Because of the huge variety of paper sizes supported by different printers, this can be set to any value. Values less than 42 should correspond to the PAPER-SIZES table in winprint.def. Values greater than 41 and less than 69 are defined by version 4.x of Windows NT. Values greater than 68 and less than 119 are defined in Windows 2000. Values greater than 118 and less than 256 are undefined. Values greater than 255 are user defined. The runtime accepts any value, no validation is performed.
WINPRINT-CURR-TRAY Because of the huge variety of paper trays supported by different printers, this can be set to any value. Values less than 16 should correspond to the PAPER-TRAYS table in winprint.def. Values greater than 15 and less than 256 are undefined. Values greater than 255 are device specific. The runtime accepts any value, no validation is performed.

Values 12 and 13 are not defined in the PAPER-TRAYS table in winprint.def. This matches a similar gap in the Windows API. Refer to prndemox.cbl for an example of how to compensate for these undefined values.

WINPRINT-CURR-COLOR | If WINPRINT-COLOR is set to a positive value greater than one, you may use this to turn color printing on or off.
Note: When using one of these extended operations, it is best to pair it with a corresponding extended operation. For example, use WINPRINT-GET-CURRENT-INFO-EX with WINPRINT-SET-PRINTER-EX, instead of with WINPRINT-SET-PRINTER.
Parent topic: WINPRINT-SELECTION op-codes


WINPRINT-SETUP-EX

Usage

CALL "WIN$PRINTER"
     USING WINPRINT-SETUP-EX WPRTDATA-SETUP-EX-FLAGS.
or
        CALL "WIN$PRINTER" USING WINPRINT-SETUP-EX.

Parameters

This op-code has an optional parameter (described in winprint.def):

  • WPRTDATA-SETUP-EX-FLAGS - This parameter may be set to one of these values:
    WPRT-PRINTTOFILE (32) By setting this, the Print To File checkbox is checked when the dialog is shown, which means when you open the print, a file save dialog will automatically show. You can also see this if, after this call, you use the WINPRINT-GET-CURRENT-INFO-EX to update the content of WINPRINT-SELECTION, in which case the WINPRINT-PORT will contain the string FILE:. Note that if you want to print to file and do not want to have the dialog show, set the environment variable WIN-SPOOLER-PORT to a filename of your choice prior to the OPEN statement. Note that this file does not have to exist, but it must be a valid filename. If it does exist, it will be overwritten. This flag may be combined with WPRT-DISABLEPRINTTOFILE, for example:
    ADD 32 524288 GIVING WPRTDATA-SETUP-EX-FLAGS
    WPRT-DISABLEPRINTTOFILE (524288) By setting this, the Print to File checkbox will show, but appears disabled so the user cannot change it. This flag may be combined with WPRT-PRINTTOFILE, for example:
    ADD 32 524288 GIVING WPRTDATA-SETUP-EX-FLAGS
    WPRT-HIDEPRINTTOFILE (1048576)

    This will remove the Print to File checkbox, so it will not appear on the printer selection dialog.

Description

This op-code is used to invoke the Microsoft SDK PrintDlgEx printer dialog. Note that this printer dialog is considered a more modern and feature-rich function than its predecessors (PrintDlg, PageSetup) and is fully supported on Windows Vista.

Comments

This op-code requires Windows 2000 or later; if you try to execute this call on a machine equipped with Win9x, WinME, or Win NT of any version, it will return the error code:

WPRTERR-UNSUPPORTED (0)

It also requires that the application display a window prior to the call of this op-code. If your application has not displayed a window and you call this op-code, the following error code is returned:

WPRTERR-WINDOW-REQUIRED (-14)

This works also in thin client environments. Note that in thin client environments, Windows print will occur on the client side with the resources available to the client.

If you experience problems with execution, use the A-TRACE environment variable. By setting this and a trace file, both the return code from the dialog and the COM error that may have happened will be written to the trace file.

Parent topic: WINPRINT-SELECTION op-codes


WINPRINT-COLUMN op-codes

WINPRINT-COLUMN takes the standard print line supplied by the COBOL program and breaks it up into zones of data, where each zone is printed at a specified column position on the page. Initially, there is only one column that starts at the left margin, has no separation zone between columns and has an alignment of WPRTALIGN-NONE. When printing, if there are more input columns than output columns, the unmatched input columns are not printed. If there are more output columns than input columns, the unmatched output columns are printed as if the data for those columns consisted of spaces.

Note: You should INITIALIZE WINPRINT-COLUMN first to ensure compatibility with future versions of the runtime.

WINPRINT-COLUMN is not part of the WINPRINT-DATA structure. When using WINPRINT-SET-PAGE-COLUMN, pass the WINPRINT-COLUMN structure instead of the WINPRINT-DATA structure. This will ensure that changes to WINPRINT-COLUMN can be detected dynamically by the routine.

Two op-codes control the input by specifying the zones in the print line. (This is similar to the DATA-COLUMNS property of the LIST-BOX control.):

  • WINPRINT-SET-DATA-COLUMNS
  • WINPRINT-CLEAR-DATA-COLUMNS

Three op-codes control the output by specifying the page layout. (This is similar to the DISPLAY-COLUMNS property of the LIST-BOX control.)

  • WINPRINT-SET-PAGE-COLUMN
  • WINPRINT-CLEAR-PAGE-COLUMNS
  • WINPRINT-GET-PAGE-COLUMN

These operation codes use the data item WINPRINT-COLUMN (defined in winprint.def).

  • WINPRINT-SET-DATA-COLUMNS
  • WINPRINT-CLEAR-DATA-COLUMNS
  • WINPRINT-SET-PAGE-COLUMN
  • WINPRINT-CLEAR-PAGE-COLUMNS
  • WINPRINT-GET-PAGE-COLUMN
  • WINPRINT-COLUMN-ALIGN-VERT
Parent topic: WIN$PRINTER op-codes


WINPRINT-SET-DATA-COLUMNS

This operation code defines columns in the data when printing with a proportionally spaced font.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-DATA-C0LUMNS, CHARACTER-POSITION
    GIVING RESULT

Parameters

CHARACTER-POSITION Numeric value One or more numeric values indicating each position that starts a new column of data.

Description

This is one of two op-codes that control the input by specifying the zones in the print line. (This is similar to the DATA-COLUMNS property of the LIST-BOX control.)

Specify one or more numeric values that represent the character position from the left side of the print record that begins a new column of data. Data starting at this column and extending to the beginning of the next column (or end of the print record) will be printed together as a single column on the page. The first column always starts at position 1 of the print record. Initially, there is only one data column, which starts from the beginning of the print record and extends to the end of the print record.

Column specifications are additive. If you call WIN$PRINTER with this operation multiple times, all the columns specified are combined and appear in the resulting printout. Column specifications last until they are cleared, or the process that is running shuts down. See WINPRINT-CLEAR-DATA-COLUMNS for information on how to clear column specifications.

Note: The current column definitions apply to any report being printed. One advantage to this is that you can change the column definitions mid-report. To do this, simply change them before writing the print record.

Example

In the following example, the print line of a three column report is made ready for printing using a proportional font:

01  PRINT-RECORD.
    03  CUST-NAME     PIC X(30).
    03  FILLER        PIC X.
    03  CUST-PHONE    PIC X(15).
    03  FILLER        PIC X.
    03  CUST-BALANCE  PIC ZZZ,ZZZ,ZZZ.99-.

CALL "WIN$PRINTER" USING WINPRINT-SET-DATA-COLUMNS, 31, 47.

Note that this is the same as the following:

CALL "WIN$PRINTER" USING WINPRINT-SET-DATA-COLUMNS,
     RECORD-POSITION OF CUST-PHONE,
     RECORD-POSITION OF CUST-BALANCE.
Parent topic: WINPRINT-COLUMN op-codes


WINPRINT-CLEAR-DATA-COLUMNS

This operation code clears all columns settings that have been specified in the print line.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-CLEAR-DATA-COLUMNS
    GIVING RESULT

Description

This is one of two op-codes that control the input by specifying the zones in the print line. (This is similar to the DATA-COLUMNS property of the LIST-BOX control.) This operation takes no parameters.

When executed, the printer setup returns to the default print record for columns. This is one column starting at the beginning of the print record and ending at the end of the print record.

Parent topic: WINPRINT-COLUMN op-codes


WINPRINT-SET-PAGE-COLUMN

This operation code describes how the columns appear when printed.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-PAGE-COLUMN, WINPRINT-COLUMN
    GIVING RESULT

Parameters

WINPRINT-COLUMN Group item defined in winprint.def as follows:
01  WINPRINT-COLUMN, SYNC.
    03  WINPRINT-COL-START              PIC 9(7)V99 COMP-5.
    03  WINPRINT-COL-INDENT             PIC 9(7)V99 COMP-5.
    03  WINPRINT-COL-SEPARATION         PIC 9(7)V99 COMP-5.
    03  WINPRINT-COL-FONT               HANDLE OF FONT.
    03  WINPRINT-COL-UNITS              PIC 99 COMP-X.
    03  WINPRINT-COL-ALIGNMENT          PIC X.
    03  WINPRINT-TRANSPARENCY           PIC 99 COMP-X.
        88  WINPRINT-TRANSPARENT        VALUE 1, FALSE 0.
    03  WINPRINT-COL-FONTCOLOR          PIC 9(9) COMP-5 SYNC.
    03  WINPRINT-COL-FONTCOLOR-NEG      PIC 9(9) COMP-5 SYNC.

        78  WPRTUNITS-CELLS                     VALUE 0.
        78  WPRTUNITS-INCHES                    VALUE 1.
        78  WPRTUNITS-CENTIMETERS               VALUE 2.
        78  WPRTUNITS-PIXELS                    VALUE 3.
        78  WPRTALIGN-NONE                      VALUE SPACE.
        78  WPRTALIGN-LEFT                      VALUE "L".
        78  WPRTALIGN-RIGHT                     VALUE "R".
        78  WPRTALIGN-CENTER                    VALUE "C".
        78  WPRTALIGN-DECIMAL                   VALUE "D".
        78  WPRTALIGN-DECIMAL-SUPPRESS          VALUE "S".

Description

This is one of three op-codes that control the output by specifying the page layout. (This is similar to the DISPLAY-COLUMNS property of the LIST-BOX control.)

Each column of data is mapped to an output column in the print record: the first data column maps to the leftmost output column, the second data column to the next output column to the right, and so on. Each time WINPRINT-SET-PAGE-COLUMN is used, a new output column is defined. To reset the output columns, use WINPRINT-CLEAR-PAGE-COLUMNS as described below. Once set, output columns remain in effect until explicitly cleared or the runtime process shuts down.

Note: Changing the output device will also reset the columns (this occurs if you use of any of these op-codes: WINPRINT-SETUP, WINPRINT-SETUP-USE-MARGINS, WINPRINT-SET-SETTINGS, WINPRINT-SET-PRINTER).

If you describe a new column that starts in exactly the same position as a previously described column, then the new column replaces the previous column definition (replacement detection is calculated using output device units).

The fields in WINPRINT-COLUMN define the output column. The fields have the following meaning:

  • WINPRINT-COL-START - Sets the leftmost point of the column on the page. The units of measurement are defined by WINPRINT-COL-UNITS. The measurement is made with respect to the left margin of the page. This position is calculated at the time that the column is defined. However, it is always relative to the left margin, so changing the left margin will shift the columns. The column ends at the beginning of the next column or the right margin if there is no next column.

    You may use this with WPRTUNITS-CELLS-ABS, WPRT-CENTIMETERS-ABS, or WPRTUNITS-INCHES-ABS to set the start position using an absolute value from the left edge of the paper.

  • WINPRINT-COL-INDENT - Modifies the left edge of the column by adding its value to the WINPRINT-COL-START value. The units of measurement are defined by WINPRINT-COL-UNITS. The indent is normally set to zero. You can use a non-zero value to specify an indented column in a convenient fashion. You would typically use this when you wanted to indent a column for a particular set of output lines. Otherwise, you would have to clear all the columns and redefine them in order to change the left edge of one column.
    Note: The values of WPRTUNITS-CENTIMETERS-ABS, WPRTUNITS-INCHES-ABS, and WPRTUNITS-CELLS-ABS do not affect this field because the field is always calculated as the given value.
  • WINPRINT-COL-SEPARATION - Defines the width of the separation zone. This zone appears at the rightmost edge of the column. This zone is generally kept blank, but see WINPRINT-COL-ALIGNMENT for exceptions. The value specified is the width of this zone (which must be less than the width of the column). It is expressed in the units defined by WINPRINT-COL-UNITS.
    Note: The values of WPRTUNITS-CENTIMETERS-ABS, WPRTUNITS-INCHES-ABS, and WPRTUNITS-CELLS-ABS do not affect this field because the field is always calculated as the given value.
  • WINPRINT-COL-FONT - Sets the handle of the font to be used when printing the column. Set to NULL to use the font currently selected for the printer (this is the default). If you place a valid printer font handle in this field, then that font is used when printing this column regardless of the printer's font. Note that the printer's font still defines the height of the line.
  • WINPRINT-COL-UNITS - Defines the measurement units used for WINPRINT-COL-START, WINPRINT-COL-INDENT and WINPRINT-COL-SEPARATION.

    The following values are valid:

    WPRTUNITS-CELLS Values are measured using the cell size of the currently selected font. A font's cell size is the size of the '0' digit in the font. This is roughly equivalent to measuring in characters.

    If you use a proportional font, it is common for uppercase characters to be wider than this measurement. If a column contains mostly uppercase data, you will need to make it wider than the number of characters in the data if you do not want to truncate the text. If a column contains numbers or mixed-case data, you can usually just set the column width to be the same as the number of characters in the data when measuring in cells. Non-integer values are allowed in the measurements.

    WPRTUNITS-INCHES | Values are measured using inches.
    WPRTUNITS-CENTIMETERS | Values are measured using centimeters.
    WPRTUNITS-PIXELS | Values are measured using the resolution of the output device. Only integer values are allowed in the measurements. Note that the device resolution varies from device to device, and so these units are rarely used.

    To measure units using an absolute value from the left edge of the page, you use WPRTUNITS-CELLS-ABS. To specify an absolute value from the left edge of the page for WINPRINT-COL-START only, you can use the following counterparts:

    • WPRTUNITS-CELLS-ABS
    • WPRTUNITS-INCHES-ABS
    • WPRTUNITS-CENTIMETERS-ABS

    Other settings of WINPRINT-COL-UNITS are invalid.

  • WINPRINT-COL-ALIGNMENT - Describes how data should be aligned in the column. The following values are allowed:

    Any other setting of WINPRINT-COL-ALIGNMENT is invalid.

    WPRTALIGN-NONE | No alignment is performed on the data, it is printed as is. In addition, the data is not truncated to fit the column. Any data that extends into the next column will be visible if you are printing with transparent text background, otherwise it may not be visible, as it will be overwritten when the following column is written.
    WPRTALIGN-LEFT | Leading and trailing spaces are removed from the data and it is printed left aligned in the column. The text is truncated so that it does not extend into the separation zone.
    WPRTALIGN-CENTER | Leading and trailing spaces are removed from the data and it is printed centered between the start of the column and the start of the column's separation zone. Text is truncated so that it does not extend into the separation zone.
    WPRTALIGN-RIGHT | Leading and trailing spaces are removed from the data and it is right aligned with respect to the beginning of the separation zone. Leading text is truncated so that it does not extend past the left edge of the column.
    WPRTALIGN-RIGHT-SIGN This is identical to WPRTALIGN-RIGHT, with the additional trait that space padding is automatically added to accommodate a trailing negative sign ("-"). For example, when printing a variable defined as PIC ZZZ9-, WPRTALIGN-RIGHT would align the column as follows:

    WPRTALIGN-RIGHT-SIGN would align the column as follows:

    22O
    220-
    WPRTALIGN-DECIMAL | Leading and trailing spaces are removed from the data. The data is then examined to find the leftmost occurrence of the runtime's current notion of the decimal point character. The rightmost edge of the decimal point is aligned with the beginning of the separation zone. If no decimal point is found, the right edge of the data is aligned there instead. Data may extend into the separation zone and is truncated at the beginning and end of the column.
    WPRTALIGN-DECIMAL-SUPPRESS | This is identical to WPRTALIGN-DECIMAL, with the additional trait that the decimal point used to align the data is replaced by a space when the data is printed. Columns with this style are limited to 256 data characters.

    Any other setting of WINPRINT-COL-ALIGNMENT is invalid.

  • WPRTDATA-TRANSPARENCY - When the level 88 item WPRTDATA-TRANSARENT is set to true, then the column's foreground text is printed, but its background is left alone. This allows you to print text over something else, such as a bitmap, without erasing it. When WPRTDATA-TRANSPARENT is set to false, then the column's background is also printed, writing over anything else on the page. Note that only the background behind the actual text printed is affected. Suppressed leading and trailing spaces are not printed.
  • WINPRINT-COL-FONTCOLOR - This member of WINPRINT-COLUMN is used to specify a column's font color. This member should be set to a COLORREF (real color) value. See the Color Reference section below for details. If this member is 0 (NULL), it defaults to the color black. If this color is set, it will only be applied to the print of the column that it is associated with. It is a foreground color only.

    For example, to make the entire contents of a column blue, set all other WINPRINT-COLUMN members first then code the following:

    INITIALIZE WINPRINT-COL-FONTCOLOR-NEG.
MOVE  16711680 TO WINPRINT-COL-FONTCOLOR.
CALL  "WIN$PRINTER"    USING
WINPRINT-SET-PAGE-COLUMN
WINPRINT-COLUMN.

    See the Columns with Color code example for a detailed demonstration of printing columns and values in color.

  • WINPRINT-COL-FONTCOLOR-NEG - This member of WINPRINT-COLUMN enables you to specify an alternate color for negative numbers in a column. where the text terminates with the negative symbol, as defined on the host computer. This member should be set to a COLORREF (real color) value. See the Color Reference section below for details. If this member is 0 (NULL), it defaults to the color black. If this color is set and the last symbol of the column text equals the computer negative sign, it will overrule a possible use of WINPRINT-COL-FONTCOLOR and be applied only to the text that is about to be printed. It is a foreground color only.

    For example, to make negative values red, set all other WINPRINT-COLUMN members first then code the following:

    INITIALIZE WINPRINT-COL-FONTCOLOR.
MOVE       X#000000FF TO
      WINPRINT-COL-FONTCOLOR-NEG.
CALL  "WIN$PRINTER" USING
WINPRINT-SET-PAGE-COLUMN
WINPRINT-COLUMN.

    See the Columns with Color code example for a detailed demonstration of printing columns and values in color.

Real Colors (COLORREF)

COLORREF is a Windows native data item and should be declared in working storage as a PIC X(4) COMP-N item. You may also apply the SYNC clause when used internal to a group.

COLORREF is a value that can be created from the RGB (See WPAL-RED, WPAL-GREEN and WPAL-BLUE in palette.def) colors returned from the palette dialog. You can do this by using the following COMPUTE statement:

COMPUTE COLORREF-VAR  =
    WPAL-RED)    +
    WPAL-GREEN * 256)  +
    WPAL-BLUE * 65536).

You can also create it yourself. For instance, to create a blue color:

MOVE X#00FF0000 TO COLORREF-VAR.

To get a green color:

MOVE X#0000FF00 TO COLORREF-VAR.

To get a red color:

MOVE X#000000FF TO COLORREF-VAR.

If you want colors in between, just mix between the three values. Remember you only use 3 byte colors, so the most significant byte should be NULL.

Columns with Colors Code Example

The following code example demonstrates the use of several WIN$PRINTER operation codes and their members including: WINPRINT-SET-PAGE-COLUMN and its members: WINPRINT-COL-FONTCOLOR; WINPRINT-COL-FONTCOLOR-NEG.

The output of the program is three columns of data where the first column is blue, the second column is black, and the third column is negative numbers red, positive numbers black. Like this:

Amount 1: | 500.00 | 1,500.00-
Amount 2: | 2,500.00- | 2,500.00
Amount 3: | 33,500.00 | 33,500.00-
Amount 4: | 444,500.00- | 444,500.00
PROGRAM-ID. ColumnWithColors.

       FILE-CONTROL.
       SELECT      PRINT-FILE       ASSIGN TO "-P SPOOLER"
                   ORGANIZATION     IS LINE SEQUENTIAL.

       FILE SECTION.
       FD PRINT-FILE.
       01 PRINT-LINE                PIC X(80).

       WORKING-STORAGE SECTION.
       COPY "WINPRINT.DEF".
       COPY "FONTS.DEF".
       77  COLUMN-FONT             HANDLE OF FONT.
       77  STANDARD-FONT           HANDLE OF FONT.

       PROCEDURE DIVISION.
       MAIN.

           INITIALIZE               WINPRINT-SELECTION.
           CALL    "WIN$PRINTER"    USING
                   WINPRINT-GET-CURRENT-INFO-EX
                   WINPRINT-SELECTION.
           SET     WPRT-COLOR       TO TRUE.
           CALL    "WIN$PRINTER"    USING
                   WINPRINT-SET-PRINTER-EX
                   WINPRINT-SELECTION.

           OPEN    OUTPUT           PRINT-FILE.
           INITIALIZE               WFONT-DATA
                     STANDARD-FONT.
           MOVE    "Courier New"    TO WFONT-NAME.
           MOVE    12               TO WFONT-SIZE.
           SET     WFONT-BOLD       TO FALSE.
           SET     WFDEVICE-WIN-PRINTER TO TRUE.
           CALL    "W$FONT"         USING
                   WFONT-GET-FONT
                   STANDARD-FONT
                   WFONT-DATA.
           INITIALIZE               WINPRINT-DATA
           MOVE    STANDARD-FONT    TO WPRTDATA-FONT
           CALL    "WIN$PRINTER"    USING
                   WINPRINT-SET-FONT
                   WINPRINT-DATA.

           INITIALIZE               WFONT-DATA
                                    COLUMN-FONT.
           MOVE    "Arial"          TO WFONT-NAME.
           MOVE    12               TO WFONT-SIZE.
           SET     WFONT-BOLD       TO TRUE.
           SET     WFDEVICE-WIN-PRINTER TO TRUE.
           CALL    "W$FONT"         USING
                   WFONT-GET-FONT
                   COLUMN-FONT
                   WFONT-DATA.

           WRITE   PRINT-LINE       FROM
                   "This demo requires a COLOR printer to show colors."
                   BEFORE ADVANCING 1 LINE.
           WRITE   PRINT-LINE       FROM
                   "It is also required with 8.1 runtime version"
                   BEFORE ADVANCING 1 LINE.
           WRITE   PRINT-LINE       FROM
                   "The first column should be blue."
                   BEFORE ADVANCING 1 LINE.
           WRITE   PRINT-LINE       FROM
                   "The second column should print the regular black."
                   BEFORE ADVANCING 1 LINE.
           WRITE   PRINT-LINE       FROM
                   "The third column should print the regular black,"
                   BEFORE ADVANCING 1 LINE.
           WRITE   PRINT-LINE       FROM
                   "except of negative numbers, they should be in red."
                   BEFORE ADVANCING 1 LINE.
           WRITE   PRINT-LINE       FROM
                   "Column 3 is using ARIAL font, the rest is Courier."
                   BEFORE ADVANCING 2 LINES.

           CALL    "WIN$PRINTER"    USING
                   WINPRINT-SET-DATA-COLUMNS
                   1
                   12
                   24.

           INITIALIZE               WINPRINT-COLUMN
                                    WINPRINT-COL-UNITS
                                    WINPRINT-COL-FONTCOLOR
                                    WINPRINT-COL-FONTCOLOR-NEG.
           MOVE    1                TO WINPRINT-COL-START.
           MOVE    0.2              TO WINPRINT-COL-SEPARATION.
           MOVE    WPRTALIGN-LEFT   TO WINPRINT-COL-ALIGNMENT.
           MOVE    1                TO WINPRINT-TRANSPARENCY.
           MOVE    ZEROS            TO WINPRINT-COL-INDENT.

           MOVE    16711680         TO WINPRINT-COL-FONTCOLOR.
           CALL    "WIN$PRINTER"    USING
                   WINPRINT-SET-PAGE-COLUMN
                   WINPRINT-COLUMN.

           MOVE    5                TO WINPRINT-COL-SEPARATION.
           MOVE    WPRTALIGN-DECIMAL TO WINPRINT-COL-ALIGNMENT.
           MOVE    0                TO WINPRINT-COL-FONTCOLOR.
           MOVE    12               TO WINPRINT-COL-START.

           CALL    "WIN$PRINTER"    USING
                   WINPRINT-SET-PAGE-COLUMN
                   WINPRINT-COLUMN.

           MOVE    COLUMN-FONT      TO WINPRINT-COL-FONT.
           MOVE    WPRTALIGN-RIGHT-SIGN TO
                   WINPRINT-COL-ALIGNMENT.
           MOVE    28               TO WINPRINT-COL-START.
           MOVE    0                TO WINPRINT-COL-FONTCOLOR.
           MOVE    255              TO WINPRINT-COL-FONTCOLOR-NEG.
           CALL    "WIN$PRINTER"    USING
                   WINPRINT-SET-PAGE-COLUMN
                   WINPRINT-COLUMN.

           MOVE    50               TO WINPRINT-COL-START.
           INITIALIZE               WINPRINT-COL-FONTCOLOR
                                    WINPRINT-COL-FONTCOLOR-NEG.
           CALL    "WIN$PRINTER"    USING
                   WINPRINT-SET-PAGE-COLUMN
                   WINPRINT-COLUMN.

           MOVE "Amount 1:      500.00     1,500.00- " TO PRINT-LINE.
           WRITE PRINT-LINE BEFORE ADVANCING 1 LINE.
           MOVE "Amount 2:    2,500.00-    2,500.00  " TO PRINT-LINE.
           WRITE PRINT-LINE BEFORE ADVANCING 1 LINE.
           MOVE "Amount 3:   33,500.00    33,500.00- " TO PRINT-LINE.
           WRITE PRINT-LINE BEFORE ADVANCING 1 LINE.
           MOVE "Amount 4:  444,500.00-  444,500.00  " TO PRINT-LINE.
           WRITE PRINT-LINE BEFORE ADVANCING 1 LINE.

           CALL "WIN$PRINTER" USING WINPRINT-CLEAR-DATA-COLUMNS.

           CLOSE PRINT-FILE.
Parent topic: WINPRINT-COLUMN op-codes


WINPRINT-CLEAR-PAGE-COLUMNS

This operation code clears all columns settings that have been specified in the page layout.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-CLEAR-PAGE-COLUMNS,
    GIVING RESULT

Description

This is one of three op-codes that control the output by specifying the page layout. (This is similar to the DISPLAY-COLUMNS property of the LIST-BOX control.) This operation takes no additional parameters.

The operation removes all the output column definitions and restore to the initial state of one output column that starts at the left margin, has no separation zone and has an alignment of WPRTALIGN-NONE.

Parent topic: WINPRINT-COLUMN op-codes


WINPRINT-GET-PAGE-COLUMN

This operation code retrieves information about a particular column on the page.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-PAGE-COLUMN, COLUMN-POSITION,
        WINPRINT-COLUMN
    GIVING RESULT

Parameters

COLUMN-POSITION Numeric value A numeric value indicating which column to retrieve.
WINPRINT-COLUMN Group item defined in winprint.def as follows:
01  WINPRINT-COLUMN, SYNC.
    03  WINPRINT-COL-START              PIC 9(7)V99 COMP-5.
    03  WINPRINT-COL-INDENT             PIC 9(7)V99 COMP-5.
    03  WINPRINT-COL-SEPARATION         PIC 9(7)V99 COMP-5.
    03  WINPRINT-COL-FONT               HANDLE OF FONT.
    03  WINPRINT-COL-UNITS              PIC 99 COMP-X.
    03  WINPRINT-COL-ALIGNMENT          PIC X.
    03  WINPRINT-TRANSPARENCY           PIC 99 COMP-X.
        88  WINPRINT-TRANSPARENT        VALUE 1, FALSE 0.

        78  WPRTUNITS-CELLS                     VALUE 0.
        78  WPRTUNITS-INCHES                    VALUE 1.
        78  WPRTUNITS-CENTIMETERS               VALUE 2.
        78  WPRTUNITS-PIXELS                    VALUE 3.
        78  WPRTALIGN-NONE                      VALUE SPACE.
        78  WPRTALIGN-LEFT                      VALUE "L".
        78  WPRTALIGN-RIGHT                     VALUE "R".
        78  WPRTALIGN-CENTER                    VALUE "C".
        78  WPRTALIGN-DECIMAL                   VALUE "D".
        78  WPRTALIGN-DECIMAL-SUPPRESS          VALUE "S".

Description

This is one of three op-codes that control the "output" by specifying the page layout. (This is similar to the DISPLAY-COLUMNS property of the LIST-BOX control.)

This operation takes two additional parameters. The first is a numeric parameter that indicates which column to retrieve. Columns are numbered from left-to-right on the printed page, starting with 1. The second parameter retrieves the current definition of the specified column and stores it in WINPRINT-COLUMN. This is useful if you want to change the characteristics of a particular column. You can use this operation to get the current settings, change the ones you want, and use WINPRINT-SET-PAGE-COLUMN to apply the changed settings.

The units used for the various measurements are determined by setting WINPRINT-COL-UNITS in the WINPRINT-COLUMN structure passed into the call. You should set this to the desired units before calling WIN$PRINTER. If WINPRINT-COL-UNITS contains an invalid setting, the units used by default are WPRTUNITS-CELLS.

Example

In the following example, the first column is retrieved and its current indent is set to 3 characters.

MOVE WPRTUNITS-CELLS TO WINPRINT-COL-UNITS
CALL "WIN$PRINTER"
   USING WINPRINT-GET-PAGE-COLUMN, 1, WINPRINT-COLUMN
MOVE 3 TO WINPRINT-COL-INDENT
CALL "WIN$PRINTER"
   USING WINPRINT-SET-PAGE-COLUMN, WINPRINT-COLUMN
Parent topic: WINPRINT-COLUMN op-codes


WINPRINT-COLUMN-ALIGN-VERT

Usage

CALL "WIN$PRINTER  "
USING WINPRINT-COLUMN-ALIGN-VERT
  GIVING result

Return Values

This op-code returns one of the following statuses:

Positive value | Success
WPRTERR-SPOOLER-CLOSED (-6) | The op-code has been called before the print job has been started (before OPEN has been executed). This is not possible.
WPRTERR-NO-COLUMNS (-13) | The op-code has been called before any columns have been set. This is not possible.

Description

WINPRINT-COLUMN-ALIGN-VERT enables your COBOL application to support printing requests that contain fonts of alternate heights. This op-code tells the runtime to find the tallest font, and align the print so that all the print on one line comes out without any overlap of print from another line that immediately precedes or follows. Using this op-code only has meaning if you use alternate height fonts within the same line in conjunction with the WINPRINT-COLUMN feature. If you do not use alternate fonts, you do not need to call WINPRINT-COLUMN-ALIGN-VERT.

Do not call WINPRINT-COLUMN-ALIGN-VERT until all columns are set; if you do, the alignment calculations will be incorrect and the result unpredictable.

The new op-code WINPRINT-COLUMN-ALIGN-VERT is fully supported in thin client environments.

Comments

When using alternate fonts simultaneously, the runtime's internal line counter does not stay accurate with the actual line height. If you are using a variety of font heights you should take measures to control how much space there is left on the page.

Parent topic: WINPRINT-COLUMN op-codes


WINPRINT-JOB-STATUS op-codes

The following operation codes use the data item WINPRINT-JOB-STATUS (defined in winprint.def). These operations are used check and modify the status of a particular printer.

  • WINPRINT-GET-JOB-STATUS
  • WINPRINT-SET-JOB-STATUS
  • WINPRINT-GET-JOB-STATUS
  • WINPRINT-SET-JOB-STATUS
Parent topic: WIN$PRINTER op-codes


WINPRINT-GET-JOB-STATUS

This operation code allows you to check the current status of a print job. This is useful for determining if a printer is paused or out of paper.

Note: Due to a limitation in the Windows API, computers that run Windows 9x (Windows 98, and Windows ME) do not return the spooler job ID when opening a print job. This means that you cannot use the WINPRINT-GET-JOB-STATUS operation on these machines

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-JOB-STATUS, WINPRINT-JOB-STATUS
    GIVING RESULT

Parameters

WINPRINT-JOB-STATUS Group item defined in winprint.def as follows:
01  WINPRINT-JOB-STATUS.
   03  WINPRINT-JOB-PRINTER            PIC X(80).
   03  WINPRINT-JOB-ID                 SIGNED-INT.
   03  WINPRINT-JOB-STATUS-NO          PIC 9(9) COMP-5.
      88 WPRT-JOB-PAUSE                VALUE 1.
      88 WPRT-JOB-RESUME               VALUE 2.
      88 WPRT-JOB-CANCEL               VALUE 3.
      88 WPRT-JOB-RESTART              VALUE 4.
   03  WINPRINT-JOB-POSITION           SIGNED-INT.
   03  WINPRINT-JOB-PAGE-TOTAL         SIGNED-INT.
   03  WINPRINT-JOB-PAGE-PRINTED       SIGNED-INT.
   03  WINPRINT-JOB-STATUS-TEXT        PIC X(80).

Return Values

This operation returns the printer status as defined in the Windows API.

A great variety of conditions can affect a single print job and printer status may be the result of a combination of values. This makes it impossible to catalog all possible status settings in winprint.def. Refer to the Windows API documentation for a description of any status not covered in that file.

Description

This operation may be called at any time a print job has started, or has started and closed. There is no need to reset this function. WINPRINT-JOB-STATUS should be initialized prior to use.

Note: If this function is executed on a networked printer with a missing or malfunctioning network, your application may appear to hang. Once the timeout has completed, your application will resume. This is a feature of the Windows API, not an effect of the runtime.
WINPRINT-GET-JOB-STATUS has the following values:
WINPRINT-JOB-PRINTER | Should be set to the value of WINPRINT-NAME as obtained through a call to WINPRINT-GET-PRINTER-INFO(-EX) or WINPRINT-GET-CURRENT-INFO(-EX).
WINPRINT-JOB-ID | Returns the Windows Job ID of the last print job. The printer must be open. The Job ID may be used for subsequent calls to the same printer, even if multiple jobs are printing.
WINPRINT-JOB-STATUS-NO | Specifies the current condition of the printer, which may be one or more of the JOB-CONDITIONS defined in winprint.def.
WINPRINT-JOB-POSITION | Specifies a print job's current position in the queue of a particular printer. For example, if your job is third in the queue, this value is 3. This does not necessarily mean that the print job will wait until the two prior jobs in the queue have printed.
WINPRINT-JOB-PAGE-TOTAL | Specifies the total number of pages to print.
WINPRINT-JOB-PAGE-PRINTED | Specifies the total number of pages printed at the time of inquiry.
WINPRINT-JOB-STATUS-TEXT | Specifies the status of the printer as a text string. Depending on the error condition, this string may be empty. This is a feature of the Windows API. Use both this parameter and WINPRINT-JOB-STATUS-NO when checking job status to be sure that you have determined the correct error condition.
Parent topic: WINPRINT-JOB-STATUS op-codes


WINPRINT-SET-JOB-STATUS

This operation code allows you to modify the current status of a print job.

Note: Due to a limitation in the Windows API, computers that run Windows 9x (Windows 98, and Windows ME) do not return the spooler job ID when opening a print job. This means that you cannot use the WINPRINT-SET-JOB-STATUS operation on these machines.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-JOB-STATUS, WINPRINT-JOB-STATUS
    GIVING RESULT

Parameters

WINPRINT-JOB-STATUS Group item defined in winprint.def as follows:
01  WINPRINT-JOB-STATUS.
   03  WINPRINT-JOB-PRINTER            PIC X(80).
   03  WINPRINT-JOB-ID                 SIGNED-INT.
   03  WINPRINT-JOB-STATUS-NO          PIC 9(9) COMP-5.
      88 WPRT-JOB-PAUSE                VALUE 1.
      88 WPRT-JOB-RESUME               VALUE 2.
      88 WPRT-JOB-CANCEL               VALUE 3.
      88 WPRT-JOB-RESTART              VALUE 4.
   03  WINPRINT-JOB-POSITION           SIGNED-INT.
   03  WINPRINT-JOB-PAGE-TOTAL         SIGNED-INT.
   03  WINPRINT-JOB-PAGE-PRINTED       SIGNED-INT.
   03  WINPRINT-JOB-STATUS-TEXT        PIC X(80).

Return Values

This operation returns the printer status as defined in the Windows API.

A great variety of conditions can affect a single print job and printer status may be the result of a combination of values. This makes it impossible to catalog all possible status settings in winprint.def. Refer to the Windows API documentation for a description of any status not covered in that file.

Description

This operation may not be called while the printer is open. WINPRINT-JOB-STATUS should be initialized prior to use.

Note: If this function is executed on a networked printer with a missing or malfunctioning network, your application may appear to hang. Once the timeout has completed, your application will resume. This is a feature of the Windows API, not an effect of the runtime.

WINPRINT-GET-JOB-STATUS has the following values:

WINPRINT-JOB-PRINTER | Should be set to the value of WINPRINT-NAME as obtained through a call to WINPRINT-GET-PRINTER-INFO(-EX) or WINPRINT-GET-CURRENT-INFO(-EX).
WINPRINT-JOB-ID | Specifies the print job to be modified. You must get the job ID number with WINPRINT-GET-JOB-STATUS, before you can set this value. If set to 0, the runtime will automatically look up the most recent print job. If a job is currently printing, that is the job that will be modified.
WINPRINT-JOB-STATUS-NO | Modify the current print job by setting one of the following values: WPRT-JOB-PAUSE, WPRT-JOB-RESUME, WPRT-JOB-CANCEL, or WPRT-JOB-RESTART.
WINPRINT-JOB-PAGE-TOTAL | Specifies the total number of pages to print.
WINPRINT-JOB-STATUS-TEXT | Specifies the status of the printer as a text string. Depending on the error condition, this string may be empty. This is a feature of the Windows API. Use both this parameter and WINPRINT-JOB-STATUS-NO when checking job status to be sure that you have determined the correct error condition.
Parent topic: WINPRINT-JOB-STATUS op-codes


WINPRINT-MEDIA op-codes

The following operation code uses the data item WINPRINT-MEDIA (defined in winprint.def) to access the paper sizes and paper trays supported by a printer driver. WINPRINT-GET-PRINTER-MEDIA

  • WINPRINT-GET-PRINTER-MEDIA
Parent topic: WIN$PRINTER op-codes


WINPRINT-GET-PRINTER-MEDIA

This operation code allows you to access the paper sizes and paper trays supported by the printer driver.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-PRINTER-MEDIA, WINPRINT-MEDIA
    GIVING RESULT

Parameters

WINPRINT-MEDIA Group item defined in winprint.def as follows:
01  WINPRINT-MEDIA.
   03  WINPRINT-MEDIA-PRINTER       PIC X(80).
   03  WINPRINT-MEDIA-PORT          PIC X(80).
   03  WINPRINT-MEDIA-PAPERCOUNT    SIGNED-SHORT.
   03  WINPRINT-MEDIA-TRAYCOUNT     SIGNED-SHORT.
   03  WINPRINT-MEDIA-PAPER         SIGNED-SHORT
                                    OCCURS MAX-PAPER-SIZES.
   03  WINPRINT-MEDIA-TRAYS         SIGNED-SHORT
                                    OCCURS MAX-PAPER-TRAYS.

Description

This operation may be called at any time a print job has started, or has started and closed. There is no need to reset this function. WINPRINT-MEDIA should be initialized prior to use.

WINPRINT-MEDIA has the following values:

WINPRINT-MEDIA-PRINTER | Should be set to the value of WINPRINT-NAME as obtained through a call to WINPRINT-GET-PRINTER-INFO(-EX) or WINPRINT-GET-CURRENT-INFO(-EX).
WINPRINT-MEDIA-PORT | Should be set to the value of WINPRINT-PORT from the WINPRINT-SELECTION op-code.
WINPRINT-MEDIA-PAPERCOUNT | Returns the total number of paper sizes supported by the selected printer driver. This number varies from printer to printer. The maximum value is 41, even if the printer driver actually supports more sizes of paper.
WINPRINT-MEDIA-TRAYCOUNT | Returns the total number of paper trays supported by the printer driver. This number varies from printer to printer. The maximum value is 13, even if the printer driver actually supports more paper trays.
WINPRINT-MEDIA-PAPER | Returns an array of supported paper sizes. The array is limited to a maximum of 41 possible sizes. Each number in the array corresponds to a paper size defined by WINPRINT-CURR-PAPERSIZE in "winprint.def". The numbers in the array may not appear in sequential order (1,2,3...). If WINPRINT-MEDIA-PAPERCOUNT returns a value less than 41, values between the returned count and 41 are undefined. Values over 41 are not defined by the Windows API, and may be undefined, device specific or user-defined.
WINPRINT-MEDIA-TRAYS | Returns an array of supported paper trays. The array is limited to a maximum of 13 possible trays. Each number in the array corresponds to a paper tray defined by WINPRINT-CURR-TRAY in winprint.def. The numbers in the array may not appear in sequential order (1,2,3...). If WINPRINT-MEDIA-TRAYS returns a value less than 13, values between the returned count and 13 are undefined. Values over 13 are not defined by the Windows API, and may be undefined, device specific or user-defined.
Parent topic: WINPRINT-MEDIA op-codes


USER-DATA op-codes

The following operation codes use data items defined by the user in Working-Storage:

  • WINPRINT-GET-SETTINGS
  • WINPRINT-SET-SETTINGS
  • WINPRINT-GET-SETTINGS
  • WINPRINT-SET-SETTINGS
Parent topic: WIN$PRINTER op-codes


WINPRINT-GET-SETTINGS

This operation code retrieves information about the destination device.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-GET-SETTINGS, BUFFER
    GIVING RESULT

Return Values

This operation returns the number of bytes used in the buffer to hold the spooler's configuration settings.

The number of bytes needed to hold the configuration can change when new settings are selected by the user, often by several hundred bytes. You should allow for a wide range of configuration sizes. Experiments suggest that 1000 bytes is adequate to hold typical configurations, but there is no guaranteed upper boundary.

Comments

The parameter, BUFFER, is a PIC X(n) data item containing the spooler's current configuration. BUFFER should be the second argument to WIN$PRINTER. The spooler's configuration includes information about the destination device, its paper size, and page orientation. It does not include information about the current font selection. The information stored in the buffer is binary data that corresponds to some internal structures used by Windows. This information should be left unchanged. This operation should be called before calling WINPRINT_SET_SETTINGS.

Note: This operation is not supported in ACUCOBOL-GT's Thin Client environment. Use the WINPRINT-GET-PRINTER-INFO-EX operation instead.
Parent topic: USER-DATA op-codes


WINPRINT-SET-SETTINGS

This operation code sets the spooler's configuration to match information stored in the specified buffer.

Usage

CALL "WIN$PRINTER"
    USING WINPRINT-SET-SETTINGS, BUFFER
    GIVING RESULT

Description

BUFFER must contain the same spooler configuration data returned by an earlier call to WINPRINT-GET-SETTINGS. Passing other data is an error that can cause a variety of problems, including unexpected printout results or a General Protection Fault in Windows.

Changing the output device with this operation will reset any columns you have set using WINPRINT-COLUMN op-codes.

Note: This operation is not supported in Acucorp's Thin Client environment. Use the WINPRINT-SET-PRINTER operation instead.
Parent topic: USER-DATA op-codes


WIN$VERSION

Returns version information for Windows and Windows NT host platforms.

This routine provides more information about the system than is returned by the ACCEPT FROM SYSTEM-INFO statement.

Usage

CALL "WIN$VERSION"
    USING WINVERSION-DATA

Parameters

WINVERSION-DATA Group item as follows:
01  WINVERSION-DATA.
    03  WIN-MAJOR-VERSION     PIC X COMP-X.
    03  WIN-MINOR-VERSION     PIC X COMP-X.
    03  WIN-PLATFORM          PIC X COMP-X.
        88  PLATFORM-WIN-31   VALUE 1.
        88  PLATFORM-WIN-95   VALUE 2.
        88  PLATFORM-WIN-9X   VALUE 2.
        88  PLATFORM-WIN-NT   VALUE 3.
    03  WIN-WORDSIZE          PIC X COMP-X.
        88  WIN-WORDSIZE-16   VALUE 1.
        88  WIN-WORDSIZE-32   VALUE 2.
        88  WIN-WORDSIZE-64   VALUE 3.
    03  WIN-BUILDNUMBER                 PIC X(4) COMP-X.
    03  WIN-CSDVERSION                  PIC X(128).
    03  WIN-SERVICEPACK-MAJOR           PIC X COMP-X.
    03  WIN-SERVICEPACK-MINOR           PIC X COMP-X.
    03  WIN-SUITEMASK                   PIC X(4) COMP-X.
    03  WIN-PRODUCTTYPE                 PIC X COMP-X.
        88 WIN-NT-WORKSTATION           VALUE 1.
        88 WIN-NT-DOMAIN-CONTROLLER     VALUE 2.
        88 WIN-NT-SERVER                VALUE 3.

WINVERSION-DATA is found in the COPY library winvers.def.

Comments

Upon return from WIN$VERSION, all of the data elements contained in WINVERSION-DATA are filled in. If you call WIN$VERSION and the host machine is not a Windows or Windows NT system, the fields are set to zero.

The WINVERSION-DATA fields have the following meaning:

  • WIN-MAJOR-VERSION - The major version number reported by Windows. See table below for possible values.
  • WIN-MINOR-VERSION - The minor version number reported by Windows. See table below for possible values.
Windows Version | WIN-MAJOR-VERSION | WIN-MINOR-VERSION | Other
Windows XP | 5 | 1 | Not applicable.
Windows XP Professional x64 Edition | 5 | 2 | OSVERSIONINFOEX.wProductType == VER_NT_WORKSTATION) && (SYSTEM_INFO.wProcessorArchitecture==PROCESSOR_ARCHITECTURE_AMD64
Windows Vista | 6 | 0 | OSVERSIONINFOEX.wProductType == VER_NT_WORKSTATION
Windows 7 | 6 | 1 | OSVERSIONINFOEX.wProductType == VER_NT_WORKSTATION
Windows Server 2012 | 6 | 2 | OSVERSIONINFOEX.wProductType == VER_NT_WORKSTATION
Windows Server 2008 R2 | 6 | 1 | OSVERSIONINFOEX.wProductType != VER_NT_WORKSTATION
Windows Server 2008 | 6 | 0 | OSVERSIONINFOEX.wProductType != VER_NT_WORKSTATION
Windows Server 2003 R2 | 5 | 2 | GetSystemMetrics(SM_SERVERR2) != 0
Windows Home Sever | 5 | 2 | OSVERSIONINFOEX.wSuiteMask & VER_SUITE_WH_SERVER
Windows Server 2003 | 5 | 2 | GetSystemMetrics(SM_SERVERR2) == 0
  • WIN-PLATFORM - Provides a general description of the host system. If the host is Windows NT/Windows 2000, the value is set to PLATFORM-WIN-NT. If the host is Windows 98, the value is set to PLATFORM-WIN-9X.
  • WIN-WORDSIZE - This item is set to WIN-WORDSIZE-32 for a 32-bit operating system, and WIN-WORDSIZE-64 for a 64-bit operating system.
  • WIN-BUILDNUMBER - Identifies the build number of the operating system.
  • WIN-CSDVERSION - Indicates the latest Service Pack installed on the system. If no Service Pack has been installed the string is empty.
  • WIN-SERVICEPACK-MAJOR - Indicates the major version number of the latest Service Pack installed on the system. If no Service Pack has been installed the value is 0.
  • WIN-SERVICEPACK-MINOR - Indicates the minor version number of the latest Service Pack installed on the system. If no Service Pack has been installed the value is 0.
  • WIN-SUITEMASK - This is a bit mask that identifies the product suites available on the system. Refer to the operating system documentation for a list of possible values.
  • WIN-PRODUCTTTYPE - Identifies additional information about the system.
Parent topic: General Syntax and Library List


Windows Print Spooler (-Q and -P)

In Windows, there are two ways that your application can print something. It can either send data directly to an output device (by opening the appropriate port), or it can use the Windows print spooler. Most applications use the spooler because it allows the user to queue-up a series of documents and then print them out in the background, while performing other tasks. In this regard, the Windows print spooler works much like spoolers common to other operating systems (for example, the lp program on UNIX machines).

In other ways, however, the Windows print spooler is very different from classical spoolers. These differences derive from the graphical nature of Windows and Windows applications and can affect what you can accomplish from COBOL. This topic discusses how the Windows print spooler works and how it affects your programs. It includes information on using the -Q and -P configuration options to assign printers to the print spooler and details for using these options with the WIN$PRINTER library routine.

Programs that use traditional spoolers usually work like this:

  1. The program sends text, data, and printer-control sequences to the spooler.
  2. The spooler saves the data on disk. As resources become available, the spooler sends the information on to the port driver that manages the system's printer.
  3. The port driver delivers the data stream to the printer, which produces the document.

In this scenario, the program provides all of the printer-control coding. The spooler and port driver simply coordinate transfer of the data to the printer.

The print spooling method under Windows is different. The sequence of operations typically works like this:

  1. The program calls the Windows graphical Application Programming Interface (API) to describe a logical image of each page in the document. This Windows graphical API is called the Graphical Device Interface (GDI).
  2. The GDI subsystem constructs a low-level description of each page, which is passed to the print driver. The print driver and GDI work together to construct the data stream needed to produce the proper output on the printer. This data stream is temporarily stored on disk.
  3. As resources become available, the spooler sends the disk data to the port driver for the printer. From this point on, the process is the same as for a traditional spooler.

The operation of the spooler itself is very similar under both scenarios. What is different is that, under Windows, the GDI and print driver are responsible for producing the printer-control sequences, while in the traditional model, the program produces the control sequences.

This approach to the printing process allows Windows applications to produce graphical output without knowing how to drive specific types of printers. This greatly simplifies the printing task for sophisticated programs such as word processors and drawing programs.

However, for simple reports, this is much more complicated than the traditional approach. Instead of simply sending text data and carriage control codes, the application must go through an involved process of getting a device context, selecting and measuring an appropriate font, formatting lines of text and drawing them to the device context, and maintaining the necessary line and position information.

Fortunately, ACUCOBOL-GT simplifies this work. The runtime system contains print drivers that know how to simulate traditional style printing using the Windows spooler. To take advantage of these drivers, simply assign the print file to -Q printername or to -P SPOOLER. You can also use -P PDF filename to produce a PDF file called filename. To format the print output, see Spooler Print Formatting.

Note: The process used by Windows to print (via the GDI) interferes with programs that attempt to control the printer directly. Programs that embed control codes in their print data (to perform various functions such as changing the printer's pitch, shifting to compressed print mode, or drawing a form on a laser printer) will not work under Windows because the GDI does not understand the control codes. Instead, it tries to treat the codes as regular text data to be drawn.

The process used by Windows has the advantage that an application does not need to know how to drive an individual printer, but has the disadvantage that an application cannot choose to drive the printer directly.

If you have an application that needs to control the printer directly, you have three choices:

  • Examine the WIN$PRINTER routine described below. It allows you to perform some basic control operations directly from COBOL.
  • Send the report directly to the printer by assigning the print file to the printer's device. This allows you to directly control the printer, but you lose the advantages of using the Windows print spooler.
  • Use the GDI to describe the print image you want. This generally involves calling an external function written in C or some other language that has direct GDI support. This choice provides the greatest flexibility, but can be a large amount of work.
  • -Q <printername>
  • -P SPOOLER
  • Spooler Print Formatting
  • Direct Control
  • Printing Multiple Jobs Simultaneously
Parent topic: General Syntax and Library List


-Q <printername>

If you want the Windows spooler to format the pages of your report, but you want to use a particular printer, assign your print file to:

PRINTER1 -Q \\printername

in the configuration file (CBLCONFI). Printername is the printer designation as given in the Printers folder under Settings in the Start menu. The name may be up to 80 characters long and contain embedded spaces. The name may not include the semicolon character (;) or be surrounded by single or double quotes. The pages are printed in the manner described in -P SPOOLER below. The sample programs "graphprn.cbl" and "prndemox.cbl" contain examples of these functions.

To determine a valid printername, use the WIN$PRINTER library routine to obtain the name of the desired printer. (This is described under the WINPRINT-SET-PRINTER operation code in Specifying a Printer.) Then add the following line to your code:

MOVE "-Q \\printername" TO WS-PRINTER-NAME.

When the runtime opens a file assigned to -Q printername it sets the Windows print spooler to use this printer. The printer driver must be installed on the computer from which you print. If printername is not recognized by the runtime, a dialog box allows you to choose a printer manually.

  • Setting Options
  • Output from sample program - PaperInfo.cbl
Parent topic: Windows Print Spooler (-Q and -P)


Setting Options

You may also use -Q printername to set several other printing options in the configuration file using the following syntax:

-Q printername[;option1=x][;option2=x][;option3=x]...

The following options may appear in any order. Options not supported by the printer driver are ignored. printername should appear as shown in WINPRINT-NAME, but the options are case insensitive.

Note: The options PITCH, COLS, LINES, and FONT are all mutually dependent. Omitting one or more of these options may cause the resulting printout to look wrong.
%%ACU-CURRENT%% May be set immediately after the -Q instead of providing a printer name. This specifies to use whatever printer is currently considered the runtime's default printer.
Note: This entry is case sensitive, it must be all upper case.
%%WINDOWS-STANDARD%% May be set immediately after the -Q instead of providing a printer name. This specifies to use whatever printer is currently considered the Windows default printer.
Note: This entry is case sensitive, it must be all upper case.
CHARSET Specifies one of the character sets defined in fonts.def. Refer to the supported values described in the table below. If you use CHARSET, you must also use FONT.

If CHARSET is not specified, it has the same effect as CHARSET=WIN-DEFAULT. To specify an alternative character set, the necessary fonts must be present on the computer.

COLLATE Specifies that multiple print copies should be collated. In order for COLLATE to have any effect, COPY must also be set to a value greater than 1. COLLATE takes the following values:
  • 0, NO, FALSE

    Implies no collating, or collating off.

  • 1, YES, TRUE

    Specifies collating, or collating on.

COLOR | Indicates to print in color. COLOR may be set to a legal RGB color code number. See the library function WINPRINT-SET-TEXT-COLOR for more information on the color value.
COLS | Specifies the number of columns (width) on the page. This number is not validated by the runtime or the spooler. Choose a number of columns that coordinate with the selected font and pitch when designing the report layout.
COPY | If your printer supports this feature, COPY allows you to specify the number of copies to print.
DIRECT | Setting DIRECT to ON causes the job to print as if the configuration file was set to -P SPOOLER-DIRECT. This option also disables any use of additional options. Setting DIRECT to the default of OFF causes the job to print to the selected printer as if the configuration file was set to -P SPOOLER.
DUPLEX If supported by the printer, enables printing on both sides of the paper. If not supported by the printer, single-sided printing occurs without any warning.

DUPLEX takes the following values:

  • 1, NO, FALSE

    Default value, which implies no duplex.

  • 2, YES, TRUE

    Implies vertical duplexing.

  • 3

    Implies horizontal duplexing.

FONT Use FONT to specify a single font name. The font name may have embedded spaces, but may not contain double or single quotes. If the font does not exist, the closest matching font is chosen.

The runtime does not align columns. If you are printing a report containing columns, you should use a fixed-width font.

LINES | Specifies the lines (rows of characters) on the page. This number is not validated by the runtime or the spooler. Choose a number of lines that is compatible with the selected font and pitch when designing the report layout.
ORIENTATION | If your printer supports this feature, ORIENTATION allows you to specify LANDSCAPE or PORTRAIT orientation for the report. The default value of ORIENTATION is driver specific.
PAPER | Specifies the paper size to be used for the print job. PAPER is set to a paper format number for the target printer and the target tray. See library function WINPRINT-GET-PRINTER-MEDIA for more information on paper formats. Paper formats and paper trays are individual and unique to each printer installation. They can also be modified by users. Because of this, you should use a calibration routine when installing your software. This is a program that will list the available printers, paper formats, and trays. The output from the calibration program can then be used to assign the PAPER and PAPERTRAY properties. A sample calibration program called PaperInfo.cbl is provided in the samples directory of ACUCOBOL-GT. The output from this program appears in the Example section and is used to demonstrate the setting of PAPER and PAPERTRAY.
PAPERTRAY Specifies the paper size to be used for the print job. PAPER is set to a paper format number for the target printer and the target tray. See library function WINPRINT-GET-PRINTER-MEDIA for more information on paper formats.

See the important note for the PAPER variable.

Also note that if there is no match between the paper format designated to a tray in Windows and the value you set in PAPER, the paper choice will take precedence and the printer driver will choose the tray that supports your paper choice.

PITCH | This value specifies the point size of the font. Pitch does not determine the number of characters per line. If you use a larger pitch, the characters simply appear more crowded. For example, when you are printing 132 columns, a pitch of 10 produces better character spacing than a pitch of 12.
SPOOLER-RESET Resets the printer to its start up defaults. SPOOLER-RESET takes the following values:
  • 0, NO, FALSE

    No change.

  • 1, YES, TRUE

    Reset printer to start up defaults.

CHARSET Values

CHARSET can take one of the following values:

Variant 1 | Variant 2 | Variant 3
DEFAULT | WFCHARSET-DEFAULT | 1
WIN-OEM | WFCHARSET-WIN-OEM | 2
WIN-SYMBOL | WFCHARSET-WIN-SYMBOL | 3
WIN-SHIFTJIS | WFCHARSET-WIN-SHIFTJIS | 4
WIN-HANGUL | WFCHARSET-WIN-HANGUL | 5
WIN-GB2312 | WFCHARSET-WIN-GB2312 | 6
WIN-CHINESEBIG5 | WFCHARSET-WIN-CHINESEBIG5 | 7
WIN-JOHAB | WFCHARSET-WIN-JOHAB | 8
WIN-HEBREW | WFCHARSET-WIN-HEBREW | 9
WIN-ARABIC | WFCHARSET-WIN-ARABIC | 10
WIN-GREEK | WFCHARSET-WIN-GREEK | 11
WIN-TURKISH | WFCHARSET-WIN-TURKISH | 12
WIN-VIETNAMESE | WFCHARSET-WIN-VIETNAMESE | 13
WIN-THAI | WFCHARSET-WIN-THAI | 14
WIN-EASTEUROPE | WFCHARSET-WIN-EASTEUROPE | 15
WIN-RUSSIAN | WFCHARSET-WIN-RUSSIAN | 16
WIN-MAC | WFCHARSET-WIN-MAC | 17
WIN-BALTIC | WFCHARSET-WIN-BALTIC | 18

Examples

To use the Windows spooler with an HP Laserjet printer driver located on SERVER1, and specify the font, font size, width and number of lines in the report, enter the following into CBLCONFI:

PRINTER1 -Q \\SERVER1\HP Laserjet IV;FONT=Times New Roman;PITCH=12;COLS=132;LINES=65.

To print three copies directly to the printer on a server named GUTENBERG in Landscape orientation, enter the following into CBLCONFI:

PRINTER1 -Q \\GUTENBERG\HP Laserjet IV;DIRECT=ON;ORIENTATION=LANDSCAPE;COPY=3

To specify the Greek character set on a server named SERVER5, enter the following into CBLCONFI:

PRINTER1 -Q \\SERVER5\Laserjet;FONT=Courier New;PITCH=12;LINES=60;COLS=80;CHARSET=11
Parent topic: -Q <printername>


Output from sample program - PaperInfo.cbl

PaperInfo.cbl is provided in the sample directory of AcuGT. Its output provides values that can be used with PAPER and PAPERTRAY.

Dell Laser MFP 1815 PCL 6
Paper formats
  (001) - Letter 8 1/2 x 11 in
  (005) - Legal 8 1/2 x 14 in
  (007) - Executive 7 1/4 x 10 1/2 in
  (009) - A4 210 x 297 mm

Paper Trays
  (007) - Auto
  (001) - Upper tray
  (006) - Manual envelope

To direct your print to the printer Dell Laser MFP 1815 PCL 6, on paper format A4 210 x 297 mm and using the Upper tray, enter the following into CBLCONFI:

PRNFILE -Q Dell Laser MFP 1815 PCL 6;COPY=2;COLLATE=1
Parent topic: -Q <printername>


-P SPOOLER

If you want to use the default printer and font, simply assign your print file to -P SPOOLER. For example, to assign PRINTER to the spooler, enter the following line in your COBOL configuration file (CBLCONFI):

PRINTER1  -P  SPOOLER

By default, the runtime system assigns the PRINTER device to the spooler. You may change this in the configuration file by assigning PRINTER to some other name.

When the runtime opens a file assigned to -P SPOOLER, it automatically initiates a job with the Windows spooler and constructs print pages in accordance with your program. The runtime uses the default printer and font. If the user looks for the job in the spooler, it is named with the current title of the ACUCOBOL-GT window.

Note: The Windows spooler operates by drawing your report on each page. It constructs its own control codes to handle formatting. If you assign your print file to -P SPOOLER and your file contains device-dependent control sequences (such as those used to shift to a condensed font, or to print a form and then fill it in), the codes will be passed to the spooler as data and thus will not be interpreted correctly. If you have reports that depend on embedded control codes, print those directly to the device, or assign the print file to -P SPOOLER-DIRECT, as described in Direct Control.
Parent topic: Windows Print Spooler (-Q and -P)


Spooler Print Formatting

When using the -P SPOOLER option, you can change fonts in the middle of a report when using the Windows spooler: simply select the new font via the W$FONT library routine while the print file is open. You can change fonts at any time, even mid-line, but make sure that WFDEVICE_WIN_PRINTER is set to TRUE before you call W$FONT. When advancing lines, the runtime uses the height of the selected font to determine the height of the line, and the font must be associated with the selected printer.

When using the -P PDF option, there are a number of runtime configuration variables (all prefixed PDF_) to enable you to change the characteristics of a PDF file without the need to modify your COBOL source. If you want more control over the PDF file output, you can modify your COBOL program and use the SET ENVIRONMENT statement to set any of these configuration variables.

Parent topic: Windows Print Spooler (-Q and -P)
Related reference
PDF_FONT_TYPE
PDF_FONT_SIZE
PDF_FONT_NAME
PDF_PAGE_SIZE
PDF_PAGE_DIRECTION
PDF_MARGIN_TOP
PDF_MARGIN_RIGHT
PDF_MARGIN_LEFT
PDF_MARGIN_BOTTOM
PDF_FONT_TYPE1_PFB
PDF_FONT_TYPE1_AFM
PDF_FONT_TRUETYPE_TTC_INDEX
PDF_FONT_TRUETYPE_TTF
PDF_FONT_TRUETYPE_TTC
C$PDF
Related information
W$FONT


Direct Control

If you want to control the format of the printout yourself using embedded control codes, simply assign your print file to -P SPOOLER-DIRECT or to -Q printername using the DIRECT=ON option. For example, to assign the print job PRINTER1 to the spooler and retain direct control over formatting, enter the following line in your COBOL configuration file (CBLCONFI):

PRINTER1  -P  SPOOLER-DIRECT

Or, use the following command to assign PRINTER1 to the spooler for printing to a specific printer while retaining direct formatting control:

PRINTER1 -Q printername;DIRECT=ON

Both of these methods cause the print job to be sent to the printer via the Windows spooler, but the program does not use the spooler to format the pages. You must use embedded control codes to handle formatting (much as you would under UNIX if you used the UNIX spooler).

When using the -P SPOOLER-DIRECT option, you may use the WIN$PRINTER library routine to choose a printer. But because you completely control the printer, the various options provided by WIN$PRINTER are ignored. For example, WIN$PRINTER does not set the page size, page orientation, or font. Information returned from WIN$PRINTER, such as number of lines and columns on the page, may not be accurate and should not be used.

Parent topic: Windows Print Spooler (-Q and -P)


Printing Multiple Jobs Simultaneously

If you need to print multiple jobs at the same time, you must open multiple File Descriptors that point to -P SPOOLER or -P SPOOLER-DIRECT simultaneously. For example, you may have two simultaneous print jobs:

SELECT FIRST-FILE
       ASSIGN TO PRINTER "-P SPOOLER".

SELECT SECOND-FILE
       ASSIGN TO PRINTER "-P SPOOLER".

..

PROCEDURE DIVISION.

..

       OPEN OUTPUT FIRST-FILE.
       OPEN OUTPUT SECOND-FILE.

and both will print to the default Windows printer without interfering with each other. You can call WIN$PRINTER using WINPRINT-SETUP or WINPRINT-SETUP-USE-MARGINS before one or both of the OPEN statements. Each file may have individual file status variables, or may refer to a common file status variable.

This does not mean that you can open a single File Descriptor multiple times. For example, the following will return file status indicating that the file is already opened:

SELECT FIRST-FILE
       ASSIGN TO PRINTER "-P SPOOLER".

..

PROCEDURE DIVISION.

..

       OPEN OUTPUT FIRST-FILE.
       OPEN OUTPUT FIRST-FILE.

This is normal behavior and is consistent with the way file handling is implemented in COBOL and in other programming languages.

If you are using only the verbs OPEN, CLOSE, and WRITE, no further changes to your code are needed. If you are using WIN$PRINTER (other than WINPRINT-SETUP or WINPRINT-SETUP-USE-MARGINS), you need to specify which print job is affected. This can be done in one of two ways:

  1. The simplest way is to execute the WIN$PRINT operation immediately after an OPEN or WRITE statement on the intended job. Every execution of OPEN and WRITE sets the current job as the default so that subsequent activity using WIN$PRINTER is automatically directed to the job that was last accessed with an OPEN or WRITE statement.

    In this situation, if you have multiple jobs running, and you close one of them, the runtime switches to the next job in the list. For example, if you are printing jobs 1, 2, and 3, and you close job 2, the close command sets the current job to 3. If there is no job 3, the runtime attempts to set to the job that preceded the closed job (which in this case is job 1). If there are no jobs, the current job is initialized.

  2. The other method is to use the WINPRINT-SET-JOB operation of the WIN$PRINTER library routine.
Parent topic: Windows Print Spooler (-Q and -P)


Windows Registry Routines

CAUTION:
When you are changing registry settings, Windows does not validate any of the values you write to it–any operation is allowed. Therefore, you must be very careful of what changes you make to the registry because no error messages will appear if you make a mistake. You should create a backup of your Windows registry before making any changes. Even better, back up your entire configuration, so that it could be restored in full in the event of a crash.

The library routines that follow enable you to create and query Windows Registry keys. Each routine can be called by either of two names. Use the DISPLAY_REG_* name when you want to work with the registry on the display host (this is the local host when the application is run with a standard runtime, and the thin client when the application is run with the thin client). Use the REG_* name when you want to work with the registry on the server host (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

If the routines are called from a non-Windows platform, they will return an error status code of -1.

The Windows Registry contains the hardware, software, and user preferences that determine the configuration of a particular PC. When a user makes changes to the desktop, file structure, system configuration or software, the changes are reflected in the registry. This information used to be contained in files like config.sys, autoexec.bat, win.ini, system.ini and control.ini, but the registry provides a single source for accessing all of a computer's settings.

Each setting in the registry has a handle or Key. Only two registry keys are actually stored on the hard disk: HKEY_LOCAL_MACHINE and HKEY_USERS. All other registry keys are aliases or branches of these two principal keys, or are created dynamically by Windows. For example, HKEY_CLASSES_ROOT is an alias of the branch HKEY_LOCAL_MACHINE\Software\Classes. In order to interact with these registry keys, the Windows Application Programmer's Interface (API) provides a series of functions that call the registry. Acucorp has created the library routines below to operate registry functions from within your COBOL program.

For security reasons, in thin client deployments several of the functions require user authorization before the action is performed. These functions include:

  • DISPLAY_REG_CREATE_KEY
  • DISPLAY_REG_CREATE_KEY_EX
  • DISPLAY_REG_DELETE_KEY
  • DISPLAY_REG_DELETE_VALUE
  • DISPLAY_REG_SET_VALUE
  • DISPLAY_REG_SET_VALUE_EX

When one of these functions is called, a Security Information dialog is displayed and the user must select a Yes or No button to indicate whether the action may proceed. The security information dialog may look like this:

The Security Information Dialog

  • REG_CLOSE_KEY, DISPLAY_REG_CLOSE_KEY
    Closes a specified registry key by providing access to the Windows registry routine RegCloseKey.
  • REG_CREATE_KEY, DISPLAY_REG_CREATE_KEY
    Creates a specified registry key by providing access to the Windows registry routine RegCreateKey. If the key already exists, this function opens it (same functionality as REG_OPEN_KEY). If the key does not exist, it is created and then opened.
  • REG_CREATE_KEY_EX, DISPLAY_REG_CREATE_KEY_EX
    Creates a specified registry key by providing access to the Windows registry routine RegCreateKeyEx. If the key already exists, this function opens it (same functionality as REG_OPEN_KEY_EX). If the key does not exist, it is created and then opened.
  • REG_DELETE_KEY, DISPLAY_REG_DELETE_KEY
    Deletes a specified registry key by providing access to the Windows registry routine RegDeleteKey. When a key is deleted, its value and all of its subkeys are also deleted.
  • REG_DELETE_VALUE, DISPLAY_REG_DELETE_VALUE
    Deletes a named value from a specified registry key.
  • REG_ENUM_KEY, DISPLAY_REG_ENUM_KEY
    Enumerates subkeys of a specified open registry key. REG_ENUM_KEY retrieves the name of one subkey each time it is called.
  • REG_ENUM_VALUE, DISPLAY_REG_ENUM_VALUE
    Enumerates the values of a specified registry key. REG_ENUM_VALUE retrieves the name of one value each time it is called.
  • REG_OPEN_KEY, DISPLAY_REG_OPEN_KEY
    Opens a specified registry key by accessing the Windows registry routine RegOpenKey.
  • REG_OPEN_KEY_EX, DISPLAY_REG_OPEN_KEY_EX
    Opens a specified registry key by accessing the Windows registry routine RegOpenKeyEx.
  • REG_QUERY_VALUE, DISPLAY_REG_QUERY_VALUE
    Retrieves the value associated with a specified registry key by accessing the Windows registry routine RegQueryValue.
  • REG_QUERY_VALUE_EX, DISPLAY_REG_QUERY_VALUE_EX
    Retrieves the type and data for a specified value name associated with an open registry key.
  • REG_SET_VALUE, DISPLAY_REG_SET_VALUE
    Associates a value with a specified registry key by accessing the Windows registry routine RegSetValue.
  • REG_SET_VALUE_EX, DISPLAY_REG_SET_VALUE_EX
    Sets value and type information for a specified open registry key.
Parent topic: General Syntax and Library List


REG_CLOSE_KEY, DISPLAY_REG_CLOSE_KEY

Closes a specified registry key by providing access to the Windows registry routine RegCloseKey.

Use DISPLAY_REG_CLOSE_KEY when you want the action to be performed on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_CLOSE_KEY when you want the action to be performed on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_CLOSE_KEY"
    USING OPEN-KEY-HANDLE
    GIVING STATUS-CODE

Parameters

OPEN-KEY-HANDLE Usage unsigned-long | Handle of an open key to close.
STATUS-CODE Numeric data item. | Receives the return status of the call to Microsoft's RegCloseKey function. A return status of zero indicates success; non-zero indicates that an error occurred.

Comments

Registry keys should not be left open any longer than necessary.

Parent topic: Windows Registry Routines


REG_CREATE_KEY, DISPLAY_REG_CREATE_KEY

Creates a specified registry key by providing access to the Windows registry routine RegCreateKey. If the key already exists, this function opens it (same functionality as REG_OPEN_KEY). If the key does not exist, it is created and then opened.

Use DISPLAY_REG_CREATE_KEY when you want the action to be performed on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_CREATE_KEY when you want the action to be performed on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_CREATE_KEY"
    USING OPEN-KEY-HANDLE, SUBKEY-TO-BE-CREATED,
        SUBKEY-HANDLE
    GIVING STATUS-CODE

Parameters

OPEN-KEY-HANDLE Usage unsigned-long Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

The key created or opened by REG_CREATE_KEY is a subkey of the key identified by OPEN-KEY-HANDLE.

SUBKEY-TO-BE-CREATED PIC X(n) | Name of the subkey to create or open.
SUBKEY-HANDLE Usage unsigned-long | Data item to receive the handle of the newly created or opened key.
STATUS-CODE Numeric data item. | Receives the return status of the call to Microsoft's RegCreateKey function. A return status of zero indicates success; non-zero indicates that an error occurred.

Comments

REG_CREATE_KEY may be used to create several keys at once.

For example, by setting SUBKEY-TO-BE-CREATED to

     "key1\key2\key3"

you could create three keys, where key3 is a subkey of key2, key2 is a subkey of key1, and key1 is a subkey of the key specified by OPEN-KEY-HANDLE. The lowest-level key (key3 in this example) is the one that is opened and has its handle returned in SUBKEY-HANDLE.

Parent topic: Windows Registry Routines


REG_CREATE_KEY_EX, DISPLAY_REG_CREATE_KEY_EX

Creates a specified registry key by providing access to the Windows registry routine RegCreateKeyEx. If the key already exists, this function opens it (same functionality as REG_OPEN_KEY_EX). If the key does not exist, it is created and then opened.

Use DISPLAY_REG_CREATE_KEY_EX when you want the action to be performed on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_CREATE_KEY_EX when you want the action to be performed on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_CREATE_KEY_EX"
    USING OPEN-KEY-HANDLE, SUBKEY-TO-BE-CREATED,CLASS-NAME,
        OPTIONS, SAM-DESIRED, SUBKEY-HANDLE, DISPOSITION
    GIVING STATUS-CODE

Parameters

  • OPEN-KEY-HANDLE Usage unsigned-long

    Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):

    • HKEY_CLASSES_ROOT
    • HKEY_CURRENT_USER
    • HKEY_LOCAL_MACHINE
    • HKEY_USERS

    The key created or opened by REG_CREATE_KEY_EX is a subkey of the key identified by OPEN-KEY-HANDLE.

  • SUBKEY-TO-BE-CREATED PIC X(n)

    Name of the subkey to create or open.

  • CLASS-NAME PIC X(n)

    Specifies the class (object type) of the key to be created. This parameter is ignored if the key already exists.

  • OPTIONS Usage unsigned-long

    Specifies special options for the key. This parameter must be one of the following values (defined in acugui.def):

    Value | Meaning
    REG_OPTION_VOLATILE The value of this key varies depending on the Windows operating system used:

    Windows 98: This value is ignored. That is, even if REG_OPTION_VOLATILE is specified, the RegCreateKeyEx function creates a nonvolatile key and returns ERROR_SUCCESS.

    Windows NT 4.0, Windows 2000: This key is volatile; the information is stored in memory and is not preserved when the system is restarted.

    REG_OPTION_NON_VOLATILE | This key is not volatile; the information is stored in a file and is preserved when the system is restarted.

    By default, keys are not volatile. This option is ignored if the key already exists.

  • SAM-DESIRED Usage unsigned-long

    Specifies a security access mask (SAM) that describes the desired security access for the new key. This parameter can be a combination of the following values (defined in acugui.def):

    Value | Meaning
    KEY_ALL_ACCESS | Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, EY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access.
    KEY_CREATE_LINK | Permission to create a symbolic link.
    KEY_CREATE_SUB_KEY | Permission to create subkeys.
    KEY_ENUMERATE_SUB_KEYS | Permission to enumerate subkeys.
    KEY_EXECUTE | Permission for read access.
    KEY_NOTIFY | Permission for change notification.
    KEY_QUERY_VALUE | Permission to query subkey data.
    KEY_READ | Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access.
    KEY_SET_VALUE | Permission to set subkey data.
    KEY_WRITE | Combination of KEY_SET_VALUE and KEY_CREATE_SUB_KEY access.

    The above values may be combined in COBOL applications by using the CBL_OR library routine.

  • SUBKEY-HANDLE Usage unsigned-long

    Data item to receive the handle of the newly created or opened key.

  • DISPOSITION Usage unsigned-long

    Points to a variable that receives one of the following disposition values (defined in acugui.def):

    Value | Meaning
    REG_CREATED_NEW_KEY | The key did not exist and was created.
    REG_OPENED_EXISTING_KEY | The key existed and was simply opened without being changed.
  • STATUS-CODE Numeric data item

    Receives the return status of the call to Microsoft's RegCreateKeyEx function. A return status of zero indicates success; non-zero indicates that an error occurred.

Parent topic: Windows Registry Routines


REG_DELETE_KEY, DISPLAY_REG_DELETE_KEY

Deletes a specified registry key by providing access to the Windows registry routine RegDeleteKey. When a key is deleted, its value and all of its subkeys are also deleted.
Note: On Windows NT systems only, this routine cannot be used to delete keys that have subkeys.

Use DISPLAY_REG_DELETE_KEY when you want the action to be performed on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_DELETE_KEY when you want the action to be performed on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

 CALL "REG_DELETE_KEY"
     USING OPEN-KEY-HANDLE, SUBKEY-TO-BE-DELETED,
     GIVING STATUS-CODE

Parameters

OPEN-KEY-HANDLE Usage unsigned-long Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

The key deleted by REG_DELETE_KEY is a subkey of the key identified by OPEN-KEY-HANDLE.

SUBKEY-TO-BE-DELETED PIC X(n)

Name of the key to delete. Must be a subkey of the key identified by OPEN-KEY-HANDLE. If SUBKEY-TO-BE-DELETED is set to NULL or to a string consisting of all spaces, the routine does nothing and returns with STATUS-CODE set to 13.

STATUS-CODE Numeric data item.

Receives the return status of the call to Microsoft's RegDeleteKey function. A return status of zero indicates success; non-zero indicates that an error occurred. On 32-bit Windows systems, a return status of 5 indicates that either the application does not have delete privileges for the specified key, or another application has the key opened.

Parent topic: Windows Registry Routines


REG_DELETE_VALUE, DISPLAY_REG_DELETE_VALUE

Deletes a named value from a specified registry key.

Use DISPLAY_REG_DELETE_VALUE when you want the action to be performed on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_DELETE_VALUE when you want the action to be performed on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_DELETE_VALUE"
    USING OPEN-KEY-HANDLE, VALUE-NAME,
    GIVING STATUS-CODE

Parameters

OPEN-KEY-HANDLE Usage unsigned-long Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
VALUE-NAME PIC X(n) | Name of the value to delete. If NULL or an empty string, the value set by REG_SET_VALUE will be deleted.
STATUS-CODE Numeric data item. | Receives the return status of call to Microsoft's RegDeleteValue function. A return status of zero indicates success; non-zero indicates that an error occurred.

Comments

The key identified by OPEN-KEY-HANDLE must have been opened with KEY_SET_VALUE access (KEY_WRITE access includes KEY_SET_VALUE access).

Parent topic: Windows Registry Routines


REG_ENUM_KEY, DISPLAY_REG_ENUM_KEY

Enumerates subkeys of a specified open registry key. REG_ENUM_KEY retrieves the name of one subkey each time it is called.

Use DISPLAY_REG_ENUM_KEY to perform the action on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_ENUM_KEY to perform the action on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_ENUM_KEY"
    USING OPEN-KEY-HANDLE, NDX, SUBKEY-NAME, NAME-SIZE,
    GIVING STATUS-CODE

Parameters

OPEN-KEY-HANDLE Usage unsigned-long Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS

The keys enumerated by REG_ENUM_KEY are subkeys of the key identified by OPEN-KEY-HANDLE.

NDX Numeric data item | Specifies the index of the subkey to retrieve. NDX should be set to '1' for the first call to REG_ENUM_KEY and then incremented for subsequent calls. The subkeys are not returned in any particular order.
SUBKEY-NAME PIC X(n) | Receives the name of the subkey. REG_ENUM_KEY copies only the name of the subkey, not the full key hierarchy, to the SUBKEY-NAME buffer.
NAME-SIZE Numeric data item | Specifies the size, in characters, of the SUBKEY-NAME buffer.
STATUS-CODE Numeric data item. | Receives the return status of the call to Microsoft's RegEnumKey function. A return status of zero indicates success; non-zero indicates that an error occurred.

Comments

To enumerate subkeys, your application should initialize the NDX parameter to 1 and call REG_ENUM_KEY repeatedly, incrementing NDX each time, until there are no more subkeys. You can tell that there are no more subkeys when the function returns a non-zero STATUS-CODE (259 for 32-bit Windows).

While an application is using REG_ENUM_KEY, it should not make calls to any registry routines that might change the key being queried.

If the subkey name exceeds the size of the SUBKEY-NAME buffer (as specified by the NAME-SIZE parameter), the result depends on the operating system. Under 32-bit Windows, a STATUS-CODE of 234 is returned.

Parent topic: Windows Registry Routines


REG_ENUM_VALUE, DISPLAY_REG_ENUM_VALUE

Enumerates the values of a specified registry key. REG_ENUM_VALUE retrieves the name of one value each time it is called.

Use DISPLAY_REG_ENUM_VALUE to perform the action on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_ENUM_VALUE to perform the action on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_ENUM_VALUE"
    USING OPEN-KEY-HANDLE, NDX, VALUE-NAME, NAME-SIZE,
        DATA-TYPE, VALUE-DATA, DATA-SIZE,
    GIVING STATUS-CODE

Parameters

  • OPEN-KEY-HANDLE Usage unsigned-long
    Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
    • HKEY_CLASSES_ROOT
    • HKEY_CURRENT_USER
    • HKEY_LOCAL_MACHINE
    • HKEY_USERS
  • NDX Numeric data item

    Specifies the index of the value to retrieve. NDX should be set to 1 for the first call to REG_ENUM_VALUE and then incremented for subsequent calls. The values are not returned in any particular order.

  • VALUE-NAME PIC X(n)

    Receives the name of the value.

  • NAME-SIZE Usage unsigned-long

    Specifies the size, in characters, of the VALUE-NAME buffer. When the function returns, NAME-SIZE contains the size of the string copied to VALUE-NAME.

  • DATA-TYPE Usage unsigned-long

    Points to a variable that receives the type code for the value entry. The type code can be one of the following values (defined in acugui.def):

    Value | Meaning
    REG_BINARY | Binary data in any form.
    REG_DWORD | A 32-bit number.
    REG_DWORD_LITTLE_ENDIAN | A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order word. This is the most common format for computers running Windows and Windows NT.
    REG_DWORD_BIG_ENDIAN | A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order word.
    REG_EXPAND_SZ | A null-terminated string that contains unexpanded references to environment variables (for example, "%PATH%"). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
    REG_LINK | A Unicode symbolic link.
    REG_MULTI_SZ | An array of null-terminated strings, terminated by two null characters.
    REG_NONE | No defined value type.
    REG_RESOURCE_LIST | A device-driver resource list.
    REG_SZ | A null-terminated string. It will be a Unicode or ANSI string, depending on whether you use the Unicode or ANSI functions.
  • VALUE-DATA Variable parameter
    Buffer to receive the data for the value entry. If you know what type of data is being returned, you may specify this parameter accordingly. If the type of data returned is unknown, you may specify a group item structured as follows:
    01 VALUE-DATA
   02 VALUE-DATA-ORIG                                PIC X (n).
   02 VALUE-DWORD redefines VALUE-DATA-ORIG          Usage signed-long.
   02 VALUE-LIT-ENDIAN redefines VALUE-DATA-ORIG     Usage signed-long.
   02 VALUE-BIG-ENDIAN redefines VALUE-DATA-ORIG     S9 (9) COMP-4.
   02 VALUE-EXPAND-SZ redefines VALUE-DATA-ORIG      PIC X (n).
   02 VALUE-LINK redefines VALUE-DATA-ORIG           PIC X (n).
   02 VALUE-MULTI-SZ redefines VALUE-DATA-ORIG       PIC X (n).
   02 VALUE-NONE redefines VALUE-DATA-ORIG           PIC X (n).
   02 VALUE-RESOURCE-LIST redefines VALUE-DATA-ORIG  PIC X (n).
   02 VALUE-SZ redefines VALUE-DATA-ORIG             PIC X (n).
  • DATA-SIZE Usage unsigned-long

    Specifies the size, in bytes, of the VALUE-DATA buffer. When the function returns, DATA-SIZE contains the number of bytes copied to VALUE-DATA. This parameter can be NULL only if VALUE-DATA is NULL.

  • STATUS-CODE Numeric data item

    Receives the return status of call to Microsoft's RegEnumValue function. A return status of zero indicates success; non-zero indicates that an error occurred. A value of 259 indicates that there are no more values for the specified key.

Comments

To enumerate values, an application should initialize the NDX parameter to 1 and call REG_ENUM_VALUE repeatedly, incrementing NDX each time, until there are no more values (that is, until the function returns with STATUS-CODE set to 259).

While an application is using REG_ENUM_VALUE, it should not make calls to any registry routines that might change the values being queried.

The key identified by the OPEN-KEY-HANDLE parameter must have been opened with KEY_QUERY_VALUE access.

Parent topic: Windows Registry Routines


REG_OPEN_KEY, DISPLAY_REG_OPEN_KEY

Opens a specified registry key by accessing the Windows registry routine RegOpenKey.

Use DISPLAY_REG_OPEN_KEY to perform the action on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_OPEN_KEY to perform the action on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_OPEN_KEY"
    USING OPEN-KEY-HANDLE, SUBKEY-TO-BE-OPENED, SUBKEY-HANDLE,
    GIVING STATUS-CODE

Parameters

OPEN-KEY-HANDLE Usage unsigned-long Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
SUBKEY-TO-BE-OPENED PIC X(n)

String containing the name of the key to open. This key must be a subkey of the key identified by OPEN-KEY-HANDLE.

SUBKEY-HANDLE Usage unsigned-long

Data item to receive the handle of the opened subkey.

STATUS-CODE Numeric data item.

Receives the return status of the call to Microsoft's RegOpenKey function. A return status of zero indicates success; non-zero indicates that an error occurred.

Comments

You can use REG_OPEN_KEY to open a key several layers deep in the registry tree structure. For example, if you set SUBKEY-TO-BE-OPENED to a string of the form:

     "level_1\level_2\level_3"

this would open the key level_3, where level_3 is a subkey of level_2, level_2 is a subkey of level_1, and level_1 is a subkey of the key specified by OPEN-KEY-HANDLE.

Parent topic: Windows Registry Routines


REG_OPEN_KEY_EX, DISPLAY_REG_OPEN_KEY_EX

Opens a specified registry key by accessing the Windows registry routine RegOpenKeyEx.

Use DISPLAY_REG_OPEN_KEY_EX to perform the action on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_OPEN_KEY_EX to perform the action on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_OPEN_KEY_EX"
    USING OPEN-KEY-HANDLE, SUBKEY-TO-BE-OPENED, SAM-DESIRED,
        SUBKEY-HANDLE,
    GIVING STATUS-CODE

Parameters

  • OPEN-KEY-HANDLE Usage unsigned-long
    Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
    • HKEY_CLASSES_ROOT
    • HKEY_CURRENT_USER
    • HKEY_LOCAL_MACHINE
    • HKEY_USERS
  • SUBKEY-TO-BE-OPENED PIC X(n)

    String containing the name of the key to open. This key must be a subkey of the key identified by OPEN-KEY-HANDLE.

  • SAM-DESIRED Usage unsigned-long

    Specifies a security access mask (SAM) that describes the desired security access for the new key. This parameter can be a combination of the following values (defined in acugui.def):

    Value | Meaning
    KEY_ALL_ACCESS | Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access.
    KEY_CREATE_LINK | Permission to create a symbolic link.
    KEY_CREATE_SUB_KEY | Permission to create subkeys.
    KEY_ENUMERATE_SUB_KEYS | Permission to enumerate subkeys.
    KEY_EXECUTE | Permission for read access.
    KEY_NOTIFY | Permission for change notification.
    KEY_QUERY_VALUE | Permission to query subkey data.
    KEY_READ | Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access.
    KEY_SET_VALUE | Permission to set subkey data.
    KEY_WRITE | Combination of KEY_SET_VALUE and KEY_CREATE_SUB_KEY access.

    You may combine the above in COBOL by using the CBL_OR library routine.

  • SUBKEY-HANDLE Usage unsigned-long

    Data item to receive the handle of the opened key.

  • STATUS-CODE Numeric data item.

    Receives the return status of call to Microsoft's RegOpenKeyEx function. A return status of zero indicates success; non-zero indicates that an error occurred.

Parent topic: Windows Registry Routines


REG_QUERY_VALUE, DISPLAY_REG_QUERY_VALUE

Retrieves the value associated with a specified registry key by accessing the Windows registry routine RegQueryValue.

Use DISPLAY_REG_QUERY_VALUE to perform the action on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_QUERY_VALUE to perform the action on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_QUERY_VALUE"
    USING OPEN-KEY-HANDLE, RETURN-VALUE, RETURN-SIZE,
    GIVING STATUS-CODE

or

CALL "REG_QUERY_VALUE"
    USING OPEN-KEY-HANDLE, RETURN-VALUE, RETURN-SIZE,
       SUBKEY-NAME,
    GIVING STATUS-CODE

Parameters

OPEN-KEY-HANDLE Usage unsigned-long Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
RETURN-VALUE PIC X(n) | Receives the value associated with the specified key.
RETURN-SIZE usage unsigned-long | Specifies the size, in characters, of the RETURN-VALUE buffer. When the function returns, RETURN-SIZE contains the size of the string copied to RETURN-VALUE.
SUBKEY-NAME PIC X(n) (optional) | Name of a subkey of OPEN-KEY-HANDLE for which a value is to be retrieved. If SUBKEY-NAME is omitted or contains an empty string, REG_QUERY_VALUE retrieves the value associated with the key identified by OPEN-KEY-HANDLE.
STATUS-CODE Numeric data item. | Receives the return status of the call to Microsoft's RegQueryValue function. A return status of zero indicates success; non-zero indicates that an error occurred.

Comments

When REG_QUERY_VALUE is called repeatedly in a loop, be sure to reset the value of RETURN-SIZE between calls.

If the length of the value string exceeds the size of the RETURN-VALUE buffer (the buffer size is indicated in the input value of RETURN-SIZE), then the behavior of the routine depends on the operating system. On 32-bit Windows systems, a value string that exceeds the size of the RETURN-VALUE buffer causes RETURN-SIZE to be set to the full length of the value string. In this case, the value string is not copied into RETURN-VALUE, and STATUS-CODE is set to 234.

Parent topic: Windows Registry Routines


REG_QUERY_VALUE_EX, DISPLAY_REG_QUERY_VALUE_EX

Retrieves the type and data for a specified value name associated with an open registry key.

Use DISPLAY_REG_QUERY_VALUE_EX to perform the action on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_QUERY_VALUE_EX to perform the action on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_QUERY_VALUE_EX"
    USING OPEN-KEY-HANDLE, VALUE-NAME, DATA-TYPE, VALUE-DATA,
        DATA-SIZE,
    GIVING STATUS-CODE

Parameters

  • OPEN-KEY-HANDLE Usage unsigned-long
    Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
    • HKEY_CLASSES_ROOT
    • HKEY_CURRENT_USER
    • HKEY_LOCAL_MACHINE
    • HKEY_USERS
  • VALUE-NAME PIC X(n)

    Name of the value to be queried.

  • DATA-TYPE Usage unsigned-long

    Points to a variable that receives the type code for the value entry. The type code can be one of the following values (defined in acugui.def):

    Value | Meaning
    REG_BINARY | Binary data in any form.
    REG_DWORD | A 32-bit number.
    REG_DWORD_LITTLE_ENDIAN | A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order word. This is the most common format for computers running Windows and Windows NT.
    REG_DWORD_BIG_ENDIAN | A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order word.
    REG_EXPAND_SZ | A null-terminated string that contains unexpanded references to environment variables (for example, "%PATH%"). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
    REG_LINK | A Unicode symbolic link.
    REG_MULTI_SZ | An array of null-terminated strings, terminated by two null characters.
    REG_NONE | No defined value type.
    REG_RESOURCE_LIST | A device-driver resource list.
    REG_SZ | A null-terminated string. It will be a Unicode or ANSI string, depending on whether you use the Unicode or ANSI functions.
  • VALUE-DATA Variable parameter
    Buffer to receive the data for the value entry. If you know what type of data is being returned, you may specify this parameter accordingly. If the type of data returned is unknown, you may specify a group item structured as follows:
    01 VALUE-DATA
   02 VALUE-DATA-ORIG                                PIC X (n).
   02 VALUE-BINARY redefines VALUE-DATA-ORIG         PIC X (n).
   02 VALUE-DWORD redefines VALUE-DATA-ORIG          Usage signed-long.
   02 VALUE-LIT-ENDIAN redefines VALUE-DATA-ORIG     Usage signed-long.
   02 VALUE-BIG-ENDIAN redefines VALUE-DATA-ORIG     S9 (9) COMP-4.
   02 VALUE-EXPAND-SZ redefines VALUE-DATA-ORIG      PIC X (n).
   02 VALUE-LINK redefines VALUE-DATA-ORIG           PIC X (n).
   02 VALUE-MULTI-SZ redefines VALUE-DATA-ORIG       PIC X (n).
   02 VALUE-NONE redefines VALUE-DATA-ORIG           PIC X (n).
   02 VALUE-RESOURCE-LIST redefines VALUE-DATA-ORIG  PIC X (n).
   02 VALUE-SZ redefines VALUE-DATA-ORIG             PIC X (n).
  • DATA-SIZE Usage unsigned-long

    Prior to the call, must specify the size, in bytes, of the VALUE-DATA buffer. When the function returns, DATA-SIZE contains the number of bytes copied to VALUE-DATA.

  • STATUS-CODE Numeric data item

    Receives the return status of call to Microsoft's RegQueryValueEx function. A return status of zero indicates success; non-zero indicates that an error occurred. A return status of 234 indicates that the size of the data to be returned in VALUE-DATA exceeds the buffer size specified by the DATA-SIZE parameter.

Comments

The key identified by OPEN-KEY-HANDLE must have been opened with KEY_QUERY_VALUE access.

This function does not expand the environment-variable names in the value data when the value type is REG_EXPAND_SZ.

When calling the REG_QUERY_VALUE_EX function with OPEN-KEY-HANDLE set to the HKEY_PERFORMANCE_DATA handle and a value string of a specified object, the returned data structure sometimes has unrequested objects. Don't be surprised; this is normal behavior. When calling the REG_QUERY_VALUE_EX function, you should always expect to 'walk' the returned data structure to look for the requested object.

Parent topic: Windows Registry Routines


REG_SET_VALUE, DISPLAY_REG_SET_VALUE

Associates a value with a specified registry key by accessing the Windows registry routine RegSetValue.

Use DISPLAY_REG_SET_VALUE to perform the action on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_SET_VALUE to perform the action on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_SET_VALUE"
    USING OPEN-KEY-HANDLE, VALUE,
    GIVING STATUS-CODE

or

CALL "REG_SET_VALUE"
    USING OPEN-KEY-HANDLE, VALUE, SUBKEY-NAME,
    GIVING STATUS-CODE

Parameters

OPEN-KEY-HANDLE Usage unsigned-long

Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
VALUE PIC X(n) | String containing the value to set for the specified key.
SUBKEY-NAME PIC X(n) (optional) | Name of a subkey of OPEN-KEY-HANDLE with which to associate a value. If there is no existing subkey matching the name specified, REG_SET_VALUE will first create it. If SUBKEY-NAME is omitted or contains an empty string, the specified value will be associated with the key identified by OPEN-KEY-HANDLE.
STATUS-CODE Numeric data item. | Receives the return status of the call to Microsoft's RegSetValue function. A return status of zero indicates success; non-zero indicates that an error occurred.
Parent topic: Windows Registry Routines


REG_SET_VALUE_EX, DISPLAY_REG_SET_VALUE_EX

Sets value and type information for a specified open registry key.

Use DISPLAY_REG_SET_VALUE_EX to perform the action on the display host's registry (the local host when the application is run with a standard runtime; the thin client when the application is run with the thin client). Use REG_SET_VALUE_EX to perform the action on the server host's registry (the local host when the application is run with a standard runtime, and the application host when the application is run with the thin client).

Usage

CALL "REG_SET_VALUE_EX"
    USING OPEN-KEY-HANDLE, DATA-TYPE, VALUE-DATA, DATA-SIZE,
    GIVING STATUS-CODE

or:

CALL "REG_SET_VALUE_EX"
    USING OPEN-KEY-HANDLE, DATA-TYPE, VALUE-DATA, DATA-SIZE,
        VALUE-NAME,
    GIVING STATUS-CODE

Parameters

  • OPEN-KEY-HANDLE Usage unsigned-long
    Handle of a currently open key or one of the following predefined handles of keys that are always open (defined in acugui.def):
    • HKEY_CLASSES_ROOT
    • HKEY_CURRENT_USER
    • HKEY_LOCAL_MACHINE
    • HKEY_USERS
  • DATA-TYPE Usage unsigned-long

    Specifies the type code for the value entry. The type code can be one of the following values (defined in acugui.def):

    Value | Meaning
    REG_BINARY | Binary data in any form.
    REG_DWORD | A 32-bit number.
    REG_DWORD_LITTLE_ENDIAN | A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order word. This is the most common format for computers running Windows and Windows NT.
    REG_DWORD_BIG_ENDIAN | A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order word.
    REG_EXPAND_SZ | A null-terminated string that contains unexpanded references to environment variables (for example, "%PATH%"). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
    REG_LINK | A Unicode symbolic link.
    REG_MULTI_SZ | An array of null-terminated strings, terminated by two null characters.
    REG_NONE | No defined value type.
    REG_RESOURCE_LIST | A device-driver resource list.
    REG_SZ | A null-terminated string. It will be a Unicode or ANSI string, depending on whether you use the Unicode or ANSI functions.
  • VALUE-DATA Variable parameter
    Buffer to set the data for the value entry. If you know what type of data is being returned, you may specify this parameter accordingly. If the type of data returned is unknown, you may specify a group item structured as follows:
    01 VALUE-DATA
   02 VALUE-DATA-ORIG                                PIC X (n).
   02 VALUE-BINARY redefines VALUE-DATA-ORIG         PIC X (n).
   02 VALUE-DWORD redefines VALUE-DATA-ORIG          Usage signed-long.
   02 VALUE-LIT-ENDIAN redefines VALUE-DATA-ORIG     Usage signed-long.
   02 VALUE-BIG-ENDIAN redefines VALUE-DATA-ORIG     S9 (9) COMP-4.
   02 VALUE-EXPAND-SZ redefines VALUE-DATA-ORIG      PIC X (n).
   02 VALUE-LINK redefines VALUE-DATA-ORIG           PIC X (n).
   02 VALUE-MULTI-SZ redefines VALUE-DATA-ORIG       PIC X (n).
   02 VALUE-NONE redefines VALUE-DATA-ORIG           PIC X (n).
   02 VALUE-RESOURCE-LIST redefines VALUE-DATA-ORIG  PIC X (n).
   02 VALUE-SZ redefines VALUE-DATA-ORIG             PIC X (n).
  • DATA-SIZE Usage unsigned-long

    Specifies the size, in bytes, of the information in the VALUE-DATA buffer. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, DATA-SIZE must include the size of the terminating null character.

  • VALUE-NAME PIC X(n)

    Name of the value to set. If a value with this name is not already present in the key, the function adds it to the key.

  • STATUS-CODE Numeric data item

    Receives the return status of call to Microsoft's RegSetValueEx function. A return status of zero indicates success; non-zero indicates that an error occurred.

Comments

Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the registry. This helps the registry perform efficiently. Application elements such as icons, bitmaps, and executable files should be stored as files and not be placed in the registry.

The key identified by the OPEN-KEY-HANDLE parameter must have been opened with KEY_SET_VALUE access.

Parent topic: Windows Registry Routines


ACUCOBOL-GT Version 10.2.0 Run-Time Manual

  • Copyright Statement
  • Introduction
  • Data Execution Prevention
  • Setting up your Terminals
  • Runtime Configuration File
  • Runtime Options
  • Runtime Debugger
  • File Status Codes
  • Utilities
  • Shared Memory
Parent topic: extend Interoperability Suite


Introduction

  • Overview
  • Available Runtime Systems
Parent topic: ACUCOBOL-GT Version 10.2.0 Run-Time Manual


Overview

This Runtime Manual provides a summary of the options, variables, error codes, and utilities used with the ACUCOBOL-GT® runtime system, also known as the COBOL Virtual Machine(TM). The runtime system is part of the extend® family of solutions.

After a program is successfully compiled with the ACUCOBOL-GT compler, it is ready for immediate execution with the ACUCOBOL-GT runtime. There is no link step. Programs called during execution are loaded dynamically. See Compiler and Runtime in the ACUCOBOL-GT User's Guide for more information.

Parent topic: Introduction


Available Runtime Systems

On UNIX, Linux, and OpenVMS systems, the runtime executable is named runcbl or runcbl.exe. On some UNIX systems, the runtime is provided as a shared object library named libruncbl.so or libruncbl.a. In this manual, the runtime executable is often referred to as runcbl.

  • Windows Runtime Systems
Parent topic: Introduction


Windows Runtime Systems

Several types of runtimes are available on Windows systems, each of which supports a distinct type of deployment. Each runtime is licensed separately.

  • The standard Windows runtime is encapsulated in a dynamic link library (DLL), and is started via the program named "wrun32.exe". This runtime is used for all standard Windows deployments.
  • Thin client deployments use a special runtime named "acuthin.exe". For more information about thin client technology, see the AcuConnect®User's Guide.
  • The Windows Console runtime, named "crun32.exe", supports applications originally developed for Extended DOS or other character-based systems. The console runtime uses the Windows Console API and runs in a virtual DOS window. For more information, see ACUCOBOL-GT User's Guide > Introduction > The ACUCOBOL-GT Runtime > Windows Console Runtime.
  • The Alternate Terminal Manager (ATM) runtime, named "run32.exe", allows users to use a 32-bit Windows server in much the same way that some UNIX servers are used. With the ATM runtime, the user can telnet to the Windows server (with a third-party telnet service) to execute character-based ACUCOBOL-GT programs in the telnet window. The ATM is described in more detail in ACUCOBOL-GT User's Guide > Terminal Manager.
  • To support Windows-based deployment of Web applications, there is a special Web runtime and CGI runtime. For more information on these options, see A Programmer's Guide to the Internet
Parent topic: Available Runtime Systems


Data Execution Prevention

Data Execution Prevention (DEP) is a Microsoft security feature that monitors and protects certain pages or regions of memory, preventing them from executing (usually malicious) code.

When DEP is enabled, all data regions are marked as non-executable by default.

When DEP is disabled, vulnerabilities such as buffer overruns can leave your code exposed to an injection of malicious code within these regions that can then be executed. For a more detailed explanation of DEP, visit the Microsoft Support site (https://support.microsoft.com/en-us), where you can find various articles on how it works, and how to enable and disable it on a number of platform and applications.

From version 10.0.0 onwards, the ACUCOBOL-GT runtime and acuthin client has DEP enabled. This should not generally cause any adverse effects, but where it might cause problems is when attempting to run ActiveX controls that were designed prior to the introduction of DEP; the effect is that they will most likely produce a memory access violation exception, which if not handled, will crash the application.

To enable you to continue to use these ActiveX controls, we have supplied a runtime and a thin client that allows you to run your applications with DEP disabled. However, be aware that using these executables exposes the risks mentioned above.

Note: If your application utilizes the ACUCOBOL-GT web runtime, then control of DEP is governed by its containing Microsoft technologies (such as Internet Explorer). Refer to the third-party documentation for controlling DEP in that product.
  • DEP-aware Runtime Systems and Thin Clients
Parent topic: ACUCOBOL-GT Version 10.2.0 Run-Time Manual


DEP-aware Runtime Systems and Thin Clients

There are two runtime executables supplied with ACUCOBOL-GT.
wrun32.exe
Use this .exe to run your application in a runtime environment that has DEP enabled.
wrunns.exe
Use this .exe to run your application in a runtime environment that has DEP disabled.
See Data Execution Prevention for the associated risks of running this.
There are also two thin client executables supplied with ACUCOBOL-GT.
acuthin.exe
Use this .exe to run your application in a runtime environment that has DEP enabled.
acuthinns.exe
Use this .exe to run your application in a runtime environment that has DEP disabled.
See Data Execution Prevention for the associated risks of running this.
You can check the DEP status of each of these .exe files by using the -v parameter:
wrun32 -v
Parent topic: Data Execution Prevention


Setting up your Terminals

  • How the Terminal Manager Works
  • Getting Your Terminals Ready
  • The Keyboard Interface
  • The Display Interface
  • Restricted Attribute Handling
  • The Terminal Database File
Parent topic: ACUCOBOL-GT Version 10.2.0 Run-Time Manual


Runtime Configuration File

  • Introduction
  • Configuration Variables
Parent topic: ACUCOBOL-GT Version 10.2.0 Run-Time Manual


Runtime Options

  • Using the Runtime System
  • Runtime Options
Parent topic: ACUCOBOL-GT Version 10.2.0 Run-Time Manual


Runtime Debugger

  • Run-Time Debugger
Parent topic: ACUCOBOL-GT Version 10.2.0 Run-Time Manual


Dynamic Runtime Tracing

You can create a diagnostics report that traces the behavior of a runtime environment. You can enable this tracing dynamically on any of your existing programs; however, certain details can only be traced if your programs are compiled with the debugging options -Gs and -Gl before they are executed.

Use the following steps to produce a runtime diagnostics report from a command prompt:

  1. If required, compile your program for debugging; the minimum requirements are the -Gs and -Gl compiler options:
    ccbl -Gs -Gl my-prog.cbl
  2. Run the program with the --analyze switch.
    runcbl --analyze my-prog.acu
  3. Locate the process ID of your runtime process, and then create a configuration file named analyze.process-ID.cfg.
    Note: The configuration file should be located in the current directory, or in the %PUBLIC%\etc (Windows), or /etc (UNIX) directory.
  4. Populate the configuration file with the required runtime options; see Configuration Variables for Dynamic Runtime Tracing.
  5. Turn tracing on using the -analyze option to cblutil:
    cblutil -analyze process-ID
    You can specify more than one process ID to enable tracing for multiple processes.
    CAUTION:
    For UNIX users - cblutil is unable to determine if the specified process is a runtime that has been started with the --analyze switch. An error is only returned if you specify a non-existent process ID, or when you do not have sufficient permissions to send a signal to the process. An alternative method to turn on tracing is to send a SIGUSR2 signal to the runtime, using the kill command; refer to your operating system documentation for specific details.
  6. Use your program as you would normally; the actions set to be traced are written to the report file specified by OUTPUT_FILENAME_PATTERN.
  7. To stop tracing, run the command at step 5 again, or terminate the program.

    The report file is created in the directory from which the program was run.

  8. View the tracing output from the report file.
  • Configuration Variables for Dynamic Runtime Tracing
Parent topic: Run-Time Debugger
Related reference
Configuration Variables for Dynamic Runtime Tracing


Configuration Variables for Dynamic Runtime Tracing

Use the following configuration variables in the dynamic runtime tracing configuration file (analyze.process-ID.cfg).

OUTPUT_FILENAME_PATTERN

This variable determines the name of the report file that the tracing output is written to.

Use the following special parameters to help configure the name:
  • If the file name starts with a plus sign ("+"), the report is appended to the specified file. By default, a new report overwrites the specified file.
  • If the name contains the string %p, when the report is generated that string is replaced with the process ID (PID) of the runtime from which the report originates.
  • If the name contains the string %d, that string is replaced with the current date in the form YYYYMMDD where YYYY is the year, MM month and DD day.
  • If the name contains the string %t, that string is replaced with the current time in the form HHMMSSTTT where HH is the hour, MM minute, SS second and TTT milliseconds.
  • If the name contains the string %u, that string is replaced with the username.
  • If the name contains the string %h, that string is replaced with the hostname.

Default value: analyze.process-ID.rpt

FILE_IO
This variable determines the type of file IO operations that are traced. In the following example, only the OPEN and CLOSE operations are traced:
FILE_IO OPEN CLOSE

Permissible values: any combination of MAKE, OPEN, CLOSE, READ, NEXT, PREVIOUS, START, WRITE, REWRITE, DELETE, UNLOCK, or ALL (TRUE or ON) to trace all - Default value: 0

PROGRAM_INFO
The variable determines the type of program operations that are traced. In the following example, only the CALL and PERFORM operations are traced:
PROGRAM_INFO CALL PERFORM

Permissible values: any combination of CALL, CALLSUB, EXIT, CANCEL, PERFORM, ENTER, LEAVE, or ALL (TRUE or ON) to trace all (except CALLSUB - this must be specified explicitly to trace calls within the sub() function) - Default value: 0

Note: The PERFORM, ENTER, and LEAVE operations relate to performing, entering, and leaving a section or paragraph during a PERFORM statement. Tracing these operations requires that your program was compiled for symbolic debugging (-Gs).
COLLECT_STATS

When set to TRUE, a Counts section at the end of the tracing output that keeps a count of the traced FILE_IO and PROGRAM_INFO operations. If both FILE_IO and PROGRAM_INFO are not set, this variable has no effect.

Permissible values: TRUE, FALSE - Default value: TRUE

DUMP_RUNTIME_STATE

When set to TRUE, the current state of the program being traced is included, as long as the program was compiled for symbolic debugging (-Gs) and with line number mapping enabled (-Gl).

When TRUE, the runtime configuration variables that control the Abend Diagnostic Report (ACU_DUMP_WIDTH and ACU_DUMP_TABLE_LIMIT) will be honored when dumping the program state. See Using the Abend Diagnostic Report (ADR) for more information. Note that the dump is written to the report specified by OUTPUT_FILENAME_PATTERN (the ACU_DUMP_FILE variable is ignored in this situation).

Permissible values: TRUE, FALSE - Default value: TRUE

Parent topic: Dynamic Runtime Tracing
Related concepts
Dynamic Runtime Tracing
Using the Abend Diagnostic Report (ADR)


File Status Codes

  • Introduction
  • Table of Codes
  • Vision Secondary Error Codes for Error 98s
  • Transaction Error Codes
  • IBM DOS/VS Error Codes
Parent topic: ACUCOBOL-GT Version 10.2.0 Run-Time Manual


Utilities

  • Object File Utility - cblutil
  • Vision File Utility - vutil
  • File Transfer Utility - vio
  • Indexed File Record Editor (alfred)
  • logutil
  • The Profiler
  • External Sort Utility AcuSort
  • Remote Preprocessing Utility Boomerang
Parent topic: ACUCOBOL-GT Version 10.2.0 Run-Time Manual


Shared Memory

  • acushare Utility Program
Parent topic: ACUCOBOL-GT Version 10.2.0 Run-Time Manual


extend Product Guides

  • Acu4GL Version 10.2.0 User's Guide
  • AcuBench Version 10.2.0 User's Guide
  • AcuConnect Version 10.2.0 User's Guide
  • AcuServer Version 10.2.0 User's Guide
  • AcuSQL Version 10.2.0 User's Guide
  • AcuToWeb Version 10.2.0 User's Guide
  • AcuXDBC Version 10.2.0 User's Guide
  • Xcentrisity Business Information Server for extend User's Guide
Parent topic: extend Interoperability Suite


Acu4GL Version 10.2.0 User's Guide

  • Copyright Statement
  • Acu4GL Overview
  • Getting Started
  • XFDs
  • Using XFD Directives
  • Invalid Data
  • Working with COBOL
  • New and Existing Databases
  • Compiler and Runtime Options
  • Performance and Troubleshooting
  • Appendix A: Acu4GL for Informix Information
  • Appendix B: Acu4GL for Microsoft SQL Server
  • Appendix C: Acu4GL for Oracle
  • Appendix D: Acu4GL for ODBC
  • Appendix E: Acu4GL for Sybase Information
  • Appendix F: Acu4GL for DB2
Parent topic: extend Product Guides


Acu4GL Overview

This section provides an overview of Micro Focus Acu4GL, and how you can use its interfaces to bridge the worlds of COBOL and Structured Query Language (SQL).

It explains how to describe data in your COBOL programs and how to handle differences in the field names and data types that are passed between COBOL and the database engine.

  • Introduction
  • RDBMS Support
  • Accessing Data
  • Database Concepts
  • How Acu4GL Works
Parent topic: Acu4GL Version 10.2.0 User's Guide


Introduction

This guide describes how to use Acu4GL interfaces to access information stored in supported relational database management systems. It explains how to describe data in your COBOL programs and how to handle differences in the field names and data types that are passed between COBOL and the database engine.

Parent topic: Acu4GL Overview
Related information
RDBMS Support
Accessing Data
Database Concepts
How Acu4GL Works


RDBMS Support

Acu4GL supports the following RDBMSs:

  • DB2
  • Informix
  • Microsoft SQL Server
  • ODBC
  • Oracle
  • Sybase
RDBMS support includes the following:
RDBMS | Latest Versions Tested | Probable compatibility, based on vendor information (Client/Server may be used for connecting to other versions)
DB2 | 10.5 | Versions greater than 8.1
Informix | 12.1.0 | Versions greater than 7.51.xC1
Microsoft SQL Server | 2016 | Versions greater than 6.5
ODBC | 3.0 | Versions greater than 3.0
Oracle | 12c | Versions greater than 9i
Sybase | 12.5 | Versions greater than 11.x

The essence of Acu4GL is that standard COBOL I/O statements are used to access databases. Acu4GL handles the translation between standard COBOL and the language that the RDBMS understands.

Specific instructions and status messages apply to each type of RDBMS, and these are included in their own RDBMS-specific sections.

Parent topic: Acu4GL Overview
Related information
Introduction
Accessing Data
Database Concepts
How Acu4GL Works


Accessing Data

COBOL systems include a standard file system. The COBOL system files can optionally be replaced by (or used in conjunction with) database management systems such as Oracle and DB2. This is possible through the ACUCOBOL-GT Generic file handler, which can accommodate a wide variety of protocols.

  • Interface Routines
  • Extended File Descriptors (XFDs)
  • Web Runtime Integration
Parent topic: Acu4GL Overview
Related information
Introduction
RDBMS Support
Database Concepts
How Acu4GL Works


Interface Routines

All file systems communicate with the ACUCOBOL-GT Generic file handler via interface routines. The interfaces to various RDBMSs are available from Micro Focus as add-on modules. You can add any combination of traditional indexed file interfaces and RDBMS interfaces that meet particular needs. The run time system communicates with relational databases via the special family of add-on interfaces called Acu4GL.

Parent topic: Accessing Data
Related information
Extended File Descriptors (XFDs)
Web Runtime Integration


Extended File Descriptors (XFDs)

Acu4GL uses XFDs created by the compiler. These files map COBOL records into database fields and map the database fields back into records.

For detailed information about XFDs, see XFDs.

Parent topic: Accessing Data
Related information
Interface Routines
Web Runtime Integration


Web Runtime Integration

The ACUCOBOL-GT Web Runtime is enabled for Acu4GL. In essence, if an Acu4GL ".dll" file is in the path and the Acu4GL license with the same base name is in the Web runtime directory, and the appropriate configuration file options are set, the Web runtime can take advantage of the acu4GL interface. The particular .dll files for supported 32-bit runtimes are as follows:

a4ora32.dll - Acu4GL for Oracle

a4sql32.dll - Acu4GL for Microsoft SQL Server

a4syb32.dll - Acu4GL for Sybase

a4db232.dll - Acu4GL for DB2

a4odbc32.dll - Acu4GL for ODBC

Note: Microsoft Internet Explorer Version 5.5 Service Pack 2 and above supports the ACUCOBOL-GT Web Runtime. For more information regarding the ACUCOBOL-GT Web Runtime, please consult the Programmer's Guide to the Internet user manual.
Parent topic: Accessing Data
Related information
Interface Routines
Extended File Descriptors (XFDs)


Database Concepts

Relational databases differ from indexed file systems in several significant ways. These are the logical associations between database concepts and COBOL indexed file concepts:

Indexed File Concept | Database Concept
Directory | Database
File | Table
Record | Row
Field | Column

Or, put another way:

  • Database operations are performed on columns. Indexed file operations are performed on records
  • A COBOL indexed file is logically represented in database table format. Within a table, each column represents one COBOL field; each row represents one COBOL record
  • Database table columns are strictly associated with a particular data type, such as date, integer, or character. In COBOL, data can have multiple type definitions

For example, for Oracle, a COBOL record that looks like this:

01  terms-record.
    03  terms-code        pic 999.
    03  terms-rate        pic s9v999.
    03  terms-days        pic 9(2).
    03  terms-descript    pic x(15).

would be represented in the database as a table with a format similar to this:

Name | Null | Type
TERMS_CODE | NOT NULL | NUMBER (3)
TERMS_RATE | – | NUMBER (4, 3)
TERMS_DAYS | – | NUMBER (2)
TERMS_DESCRIPT | – | CHAR (15)
Parent topic: Acu4GL Overview
Related information
Introduction
RDBMS Support
Accessing Data
How Acu4GL Works


How Acu4GL Works

Acu4GL implements a direct, transparent interface between COBOL and RDBMSs.

Previously, accessing a relational database from a COBOL program involved writing SQL code and embedding that code in your program. You had to know SQL, and you had to write SQL statements appropriate for the specific database you wanted to access. Because your queries were tailored to suit one database management system, you had to re-code your COBOL application if you wanted to access a different RDBMS, or an indexed file system, or even to migrate a file from one system to another.

As an alternative, some interface products now translate COBOL I/O statements into direct reads and writes on the database files, without going through the driver, or engine, supplied by the database manufacturer. This means that the COBOL programmer must provide for enforcement of database rules that the engine already knows about and is designed to handle. Bypassing the database engine also means that new constraints or changes in the database structure require reprogramming of the COBOL application.

Acu4GL implements a more suitable approach by dynamically generating industry standard SQL from COBOL I/O statements. As the run time system is executing your COBOL application, Acu4GL is running behind the scenes to match up the requirements and rules of both COBOL and the RDBMS to accomplish the task set by your application. This means that Acu4GL uses the full power designed into the database engine. The engine enforces database rules and constraints; any violations are returned to the COBOL program as I/O error conditions.

  • What Is a Transparent Interface?
  • XFDs and Mapping
  • Summary
Parent topic: Acu4GL Overview
Related information
Introduction
RDBMS Support
Accessing Data
Database Concepts


What Is a Transparent Interface?

Acu4GL provide a transparent, efficient interface between your program and the relational database. The interface is categorized as transparent because the communication between your COBOL program and the database is smooth, with no special query coding on your part and no interruptions in the execution of your program. You need not change your COBOL code if you later want to access a different database or to access an alternate indexed file system.

The information exchange operations between the database and the COBOL program are invisible to the end user. For example, if your program specifies a READ, a database query is automatically generated by the interface. Then the data that is read from the database is translated into a COBOL record. This exchange occurs in fractions of a second, and the application proceeds without interruption.

Parent topic: How Acu4GL Works
Related information
XFDs and Mapping
Summary


XFDs and Mapping

Because relational databases handle I/O at the column (field) level, and COBOL handles I/O at the record level, some mapping is necessary to associate records with their fields. One function of Acu4GL is to map COBOL records into database fields, and to map the database fields back into records. Acu4GL does this by consulting XFDs generated by the Compiler. The detailed structure of XFDs is discussed in How XFDs are Formed.

Acu4GL builds its own database queries dynamically whenever an input or output request is received. You just compile your program, and Acu4GL does the rest.

Parent topic: How Acu4GL Works
Related reference
How XFDs are Formed
Related information
What Is a Transparent Interface?
Summary


Summary

Acu4GL ensures that all database changes are immediately available to your COBOL program. It also ensures that all data updates to your COBOL program are immediately reflected in the database.

After your XFDs are generated, you can switch to a different RDBMS simply by setting the DEFAULT_HOST to point to the new RDBMS. No recompiling is necessary.

Because Acu4GL accesses the database through its native engine, the full relational integrity of the database is maintained. The COBOL program need not be concerned about such things as enforcing relationships between keys and foreign keys on tables or constraints on field relationships and contents.

If you have specified that a file is to reside on a RDBMS (by setting either DEFAULT_HOST or filename_HOST), an OPEN OUTPUT filename statement in your COBOL program generates a CREATE TABLE filename function on the specified host database. Appropriate permissions are granted based on login and password and access parameters; see the RDBMS-specific sections of this Help for specific details. For large tables, your systems database administrator can create the table and indexes for you. Databases offer many methods for creating tables that may improve performance for large tables, such as spreading the table across multiple hard drives or storing the data and the indexes on different drives.

Changes to the way a database functions should be carefully considered and tested before being fully implemented. If a database violation occurs, the engine detects it, and Acu4GL returns an I/O error condition to the COBOL program. The program can, if desired, call a standard COBOL library routine for an extended error description.

It is possible that there are library routines that do not work with or do not make sense to use with some of the Acu4GL interfaces. To find out if that is the case with your Acu4GL interface, look in the Common Questions and Answers section of the appendix specific to your interface.

Parent topic: How Acu4GL Works
Related information
What Is a Transparent Interface?
XFDs and Mapping


Getting Started

For installation instructions specific to the RDBMS you plan to use, see the specific links below. Once you have installed and configured the Acu4GL interface, refer to the Licensing section, and then to test the setup, run the demonstration program.

The Working with COBOL section also contains demonstration programs, which can be compiled and run to produce database tables.

  • Installation
  • Demonstration Program
  • Using the sql.acu Program
Parent topic: Acu4GL Version 10.2.0 User's Guide


Installation

The installation instructions for your particular RDBMS can be found in the specific RDBMS section of this manual.

Each of these topics contains an overview of the Connector functions, installation instructions, setup instructions, technical specifications, and a troubleshooting guide.

Note: Before going any further in this manual, go to the Appendix that pertains to your RDBMS and begin the Connector installation and setup processes. Once the installation is complete and you are ready to run, return to this topic; then begin with Demonstration Program.
Parent topic: Getting Started
Related information
Informix Information
ODBC Information
Oracle Information
Microsoft SQL Server Information
Sybase Information


Demonstration Program

As soon as your installation and setup are complete, you may compile and run the demonstration program (demo.cbl), which is included in the sample directory (which by default is %PUBLIC%\Documents\Micro Focus\extend x.x.x\sample). This program illustrates many of the Acu4GL product capabilities, including how to:

  • map RDBMS data types to traditional COBOL data types.
  • compile a COBOL program in preparation for interfacing with an RDBMS.
  • modify records within the RDBMS database.

The demo program simulates what might be used in a distributor's shipping department. You'll be creating the orderfile table in an existing database of your choosing. The table will contain information about the orders placed by the distributor's customers. The orderfile table has the following columns of information (the database data type and COBOL data type are shown for each):

Note: The data type may be slightly different depending on the RDBMS.
Column Name | Data Type | COBOL PIC
order_name | varchar(4) | pic 9(4)
order_date | int | pic 9(6)
customer_num | varchar(3) | pic 9(3)
ship_instruct | varchar(40) | pic x(40)
backlog | varchar(1) | pic x
po_num | varchar(10) | pic x(10)
ship_date | int | pic 9(6)
ship_weight | decimal(8,2) | pic 9(6)v99
ship_charge | decimal(6,2) | pic 9(4)v99
paid_date | int | pic 9(6)

Here is the COBOL FD (file descriptor) that matches the orderfile table. Note that the FD entries must match the names of the RDBMS fields and must match their data types:

fd  orders.
01  order-record.
    03  order-num              pic x(4).
    03  order-fields.
        05  order-date         pic 9(6).
        05  customer-num       pic 9(3).
        05  ship-instruct      pic x(40).
        05  backlog            pic x.
        05  po-num             pic x(10).
        05  ship-date          pic 9(6).
        05  ship-weight        pic 9(6)v99.
        05  ship-charge        pic 9(4)v99.
        05  paid-date          pic 9(6).
  • Compiling and Running the Demo Program
Parent topic: Getting Started


Compiling and Running the Demo Program

Perform the following steps to compile and run:

  1. Compile using the applicable command line:

    Windows: ccbl32 -Fx -o demo demo.cbl

    UNIX: ccbl -Fx -o demo demo.cbl

    This compiles the program and generates the ACUCOBOL-GT data dictionary orderfile.xfd. The runtime system will use this data dictionary to map RDBMS data types to COBOL data types.

  2. Verify the runtime by entering the applicable command:

    Windows: wrun32 -vv

    UNIX: runcbl -vv

    Be sure that the version information you receive references your Acu4GL product.

  3. Notify the ACUCOBOL-GT runtime system that you are interfacing to an RDBMS driver. You accomplish this by adding the following line to your runtime configuration file or to the machine's environment:
    DEFAULT_HOST RDBMS_NAME

    If you're running demo.cbl from the same directory where you placed the ACUCOBOL-GT data dictionary, you are ready to run. If the data dictionary (orderfile.xfd, created when you compiled the demo program) is in another directory, you will need to add the following line to the cblconfig configuration file:

    XFD_PREFIX dir-containing-dictionary
  4. Set any environment variables required for your specific Acu4GL product. See the Designating the Host Data Source or Designating the Host File System topic in the Appendix specific to your particular RDBMS.
  5. run the demo program by entering the applicable command:.

    Windows: wrun32 -c config demo

    UNIX: runcbl -c config demo

Depending on your system, you will see either a character or window based version of the program.

The demo program enables you to view or change any of the rows (records) in the orders table.

You can also view the source code for the demo program from the Options Menu. Selecting View Program will start the debugger and display the source code. Be sure you compiled the program with -Zd and executed it with -d.

Parent topic: Demonstration Program


Using the sql.acu Program

Micro Focus provides a utility program that gives you access to some of the standard SQL commands. Once you have compiled sql.cbl, it can be called from a COBOL program or executed from the command line. This file is located in the acu4gl sub-directory of your sample directory.

As a general rule, sql.acu may be used to issue all SQL commands except those that perform data retrieval. The sql.acu program cannot perform statements that return data, such as the SELECT statement. This category of statements returns an error when passed to the sql.acu program.

The global variable return-code is 0 when a command has completed successfully. If a command is not successful, return-code contains an error code.

  • Running sql.acu from the Command Line
  • Calling sql.acu from a Program
Parent topic: Getting Started


Running sql.acu from the Command Line

To use the sql.acu utility to create an empty table and grant access privileges to other users.
Note: When naming columns and tables, make sure to use underscores ("_"), not hyphens ("-"), or a syntax error will result.
  1. From a command prompt enter:
    wrun sql.acu
  2. Enter the following (italics indicate variable names, non-italics are SQL reserved words):
    CREATE TABLE newtab (col1 CHAR(30), col2 CHAR(11))
  3. Enter the following command:
    GRANT ALL PRIVILEGES ON newtab TO PUBLIC
  4. Now enter:
    CREATE UNIQUE INDEX newtab_index ON newtab (col1)
  5. Press Enter to exit the program.
You should now become familiar with the Demonstration Program.
Parent topic: Using the sql.acu Program


Calling sql.acu from a Program

You can also call sql.acu from within a COBOL program. The syntax is:

call "sql.acu" using mysql-command

The SQL command may be up to 50,000 characters and may be a variable or a quoted command string in the CALL statement.

Note: The sql.acu utility may be used only with SQL commands that are data definition statements (those that do not return data). Be sure to end each SQL command with a semicolon (";").

Example

IDENTIFICATION DIVISION.
program-id.  command.
* the sql.acu command to issue data
* definition commands to the RDBMS.
DATA DIVISION.
working-storage section.
01  sql-command                       pic x(75).
01  error-status.
    03 primary-error                  pic x(2).
    03 secondary-error                pic x(40).
01  error-text                        pic x(40).
01  error-window                      pic x(10).
PROCEDURE DIVISION.
main-logic.  display window erase.
     display window line 20, column 2
            size 75, lines 3, boxed,
            top title "SQL COMMAND",
            bottom right title "Return to exit".
     perform do-sql-command, with test after,
            until sql-command = spaces.
stop run.
do-sql-command.
     accept sql-command, line 1, column 1,
        erase to end of line.
if sql-command not = spaces
call "sql.acu" using sql-command
if return-code not zero
perform show-error.
show-error.
     display window line 2, column 2,
        size 75 lines 6, boxed, erase,
        pop-up area is error-window.
     call "C$RERR" using error-status,
        error-text.
     display "DATABASE ERROR:",
        secondary-error.
display error-text.
accept omitted.
close window error-window.
     display window line 20, column 2,
        size 75, lines 3.
Parent topic: Using the sql.acu Program


XFDs

Extended File Descriptors (XFDs) map COBOL records to database fields. These are called XFDs because they're based on standard COBOL File Descriptors (FDs). An XFD file is created as an XML file. The XFD contains a description of a COBOL indexed, sequential, or relative file based on its fields. XFDs are used to interface to database management systems.

  • Creating XFDs
  • How XFDs are Formed
  • Defaults Used in XFD Files
  • Summary of XFD Fields
  • Identical Field Names
  • Long Field Names
  • Naming the XFD File
Parent topic: Acu4GL Version 10.2.0 User's Guide


Creating XFDs

The compiler creates an XFD for each indexed file in the compiled program when you specify the -Fx compile-time option. XFDs are fully portable, so no recompilation is necessary if you change hardware.

The compiler option -Fa causes the generation of XFDs for indexed, relative, and sequential files for use with international character mapping only.

The compiler option -F4 generates version 4 XFD files for backwards compatibility with older versions of the runtime.

Parent topic: XFDs
Related information
Compiling and Runtime Configuration


How XFDs are Formed

XFDs enable the interface to create a table (or access an existing one) in the database for each indexed file. Each column in the table contains the values for one field. The column names are essentially the field names.

The table that is built is based on the largest record in the COBOL file and contains the fields from that record plus any key fields (key fields are those that are named in KEY IS phrases of SELECT verbs in the FILE CONTROL section). This ensures that data from all COBOL records fit within the table and simplifies the storage and retrieval process. If you were to examine the database columns, only the fields from the largest record, and the key fields, would appear. For additional information, see Defaults Used in XFD Files.

Note: If the field named in the KEY IS phrase is a group item, it does not become a column in the database table. Instead, each of the elementary items subordinate to the named group item become a column. You can force a group item to be a column by using the USE GROUP XFD directive.

With multiple record formats (level 01), not all COBOL fields are represented in the database by name, but all fields are storable and retrievable. The XFD maps fields from all records of a file to the corresponding locations in the master (largest) record of the file, and thus to the database table. Since Acu4GL has access to the XFD, it knows where the data from a given COBOL record fits in the database tables. This activity is invisible to the COBOL application.

For example, if your program has one file with the three records shown below, the underlined fields are included in the database table by default (this example assumes that ar-codes-key is named in a KEY IS phrase). Some fields do not appear in the table, but the XFD maps them to the master field names. Acu4GL thus eliminates redundancies for optimum performance.

01  ar-codes-record.
    03  ar-codes-key.
        05  ar-code-type      pic x.
        05  ar-code-num       pic 999.
01  ship-code-record.
    03  filler                pic x(4).
    03  ship-weight           pic s999v9.
    03  ship-instruct         pic x(15).
01  terms-code-record.
    03  filler                pic x(4).
    03  terms-rate-1          pic s9v999.
    03  terms-days-1          pic 9(3).
    03  terms-rate-2          pic s9v999.
    03  terms-descript        pic x(15).

The following diagram shows how Acu4GL creates database columns for some of the fields in the COBOL record, while the XFD maps other fields to those columns; this means that all of the fields are accessible to the COBOL program.

Making Field Accessible to COBOL Programs

See Defaults Used in XFD Files for a description of rules that Acu4GL follows as it builds the database table and an explanation of how you can override those rules when necessary.

Parent topic: XFDs
Related information
USE GROUP XFD directive
Defaults Used in XFD Files
KEY IS Phrase


Defaults Used in XFD Files

Several elements of COBOL require special handling when XFDs are built. These include multiple record definitions REDEFINES, FILLER, and OCCUR. This section describes how the compiler handles each of these situations.

Note that in many instances you can override the default behavior described below by placing special comment lines in the FDs of your COBOL code. These comments are called XFD directives, and are described in Using XFD Directives. For example, the WHEN XFD directive lets you use multiple definitions for a single set of data by specifying when each definition should be used.

Databases generally do not support the notion of multiple definitions for the same column. As the following paragraphs explain, whenever a COBOL program gives more than one definition for the same data, the compiler chooses which definition to use in the XFD and disregards the rest.

  • KEY IS Phrase
  • REDEFINES Clause
Parent topic: XFDs
Related information
WHEN XFD directive
Using XFD Directives


KEY IS Phrase

Fields named in KEY IS phrases of SELECT statements are included as column names. Other fields that occupy the same areas as the key fields (by either explicit or implicit redefinition) are not included by name, but are mapped to the key field column names by the XFD.

Remember, if the field named in the KEY IS phrase is a group item, it does not become a column in the database table unless a USE GROUP XFD directive is used See How XFDs are Formed for more information. Instead, the subordinate fields of the group item are used.

Parent topic: Defaults Used in XFD Files
Related information
USE GROUP XFD directive


REDEFINES Clause

Fields contained in a redefining item occupy the same positions as the fields being redefined. The compiler needs to select only one of the field definitions to use. The default rule that it follows is to use the fields in the item being redefined as column names; the XFD maps fields that appear subordinate to a REDEFINES clause to column names.

Multiple Record Definitions

This same rule extends to multiple record definitions. In COBOL, multiple record definitions are essentially redefinitions of the entire record area. This leads to the same complication that is encountered with REDEFINES: multiple definitions for the same data. So the compiler needs to select one definition to use.

Multiple Record Definitions

Because the multiple record types can be different sizes, the compiler needs to use the largest one, so that it can cover all of the fields adequately. Thus, the compiler's rule is to use the fields in the largest record defined for the file. If more than one record is of the largest size, the compiler uses the first one.

Group Items

Note that group items are, by default, never included in an XFD for the same reason that REDEFINES are excluded: they result in multiple names for the same data items. You can, however, choose to combine grouped fields into one data item by specifying the USE GROUP XFD directive.

FILLER Data Items

In a COBOL FD, FILLER data items are essentially place holders. FILLER items are not uniquely named and thus cannot be uniquely referenced. For this reason, they are not placed into the XFD. The XFD maintains the correct mapping of the other fields, and no COBOL record positional information is lost.

Sometimes you need to include a FILLER data item, such as when it occurs as part of a key. In such a case, you could include it under a USE GROUP XFD directive or give it a name of its own with the NAME XFD directive.

OCCURS Definition

An OCCURS clause always requires special handling, because the run time system must assign a unique name to each database column. The run time system accomplishes this by appending sequential index numbers to the item named in the OCCURS clause.

For example, if the following were part of a file's description:

03  employee-table occurs 20 times.
    05  employee-number            pic 9(3)

these column names would be created in the database table:

employee_number_1
employee_number_2
.
.
.
employee_number_10
employee_number_11
.
.
.
employee_number_20

Note that the hyphens in the COBOL code are translated to underscores in database field names, and the index number is preceded by an underscore.

Parent topic: Defaults Used in XFD Files
Related information
USE GROUP XFD directive
NAME XFD directive


Summary of XFD Fields

Fields defined with an OCCURS clause are assigned unique sequential names. Fields without names are disregarded. When multiple fields occupy the same area, the compiler chooses only one of them unless you have a WHEN XFD directive to distinguish them. To choose, the compiler:

  • Preserves fields mentioned in KEY IS phrases
  • Discards group items unless USE GROUP is specified
  • Discards REDEFINES
  • Uses the largest record if there are multiple record definitions
Parent topic: XFDs
Related information
WHEN XFD directive


Identical Field Names

In COBOL, you distinguish fields with identical names by qualification. For example, there are two fields named RATE in the following code, but they can be qualified by their group items. Thus, you would reference RATE OF TERMS-CODE and RATE OF AR-CODE in your program:

01  record-area.
    03  terms-code.
        05  rate                   pic s9v999.
        05  days                   pic 9(3).
        05  descript               pic x(15).
    03  ar-code.
        05  rate                   pic s9v999.
        05  days                   pic 9(3).
        05  descript               pic x(15).

Database systems consider duplicate names an error. Thus, if more than one field in a particular file has the same name, the XFD is not generated for that file.

The solution to this situation is to add a NAME XFD directive that associates an alternate name with one or both of the conflicting fields.

Parent topic: XFDs
Related information
NAME XFD directive


Long Field Names

To meet the SQL requirements of some relational database management systems (RDBMSs), the Acu4GL run time truncates long field names to the maximum allowed by the RDBMS. (In the case of the OCCURS clause described above, the truncation is to the original name, not the appended index numbers. However, the final name, including the index number, is limited to the RDBMS maximum.) It's a good idea to make sure that your field names are unique (and meaningful) within the first 18 characters.

The database you are connecting to may allow longer names, and if so, more characters are used. Names longer than 30 characters generate a warning. Instead of allowing default truncation, use the NAME XFD directive to give a shorter alias to a field with a long name. Note that within the COBOL application you can continue to use the original name. The NAME XFD directive affects only the XFD connection to the RDBMS table.

Parent topic: XFDs
Related information
NAME XFD directive


Naming the XFD File

The compiler needs to give a name to each XFD file that is built. It attempts to build the name from your COBOL code, although there are some instances where the name in the code is nonspecific, and you must provide a name.

Each XFD name is built from a starting name that is derived (if possible) from the SELECT statement in your COBOL code. The following table explains how that occurs.

ASSIGN name is a variable | If the SELECT for the XFD file has a variable ASSIGN name (ASSIGN TO filename), you must specify a starting name for the .xfd file via a FILE XFD directive in your code. This process is described in Using XFD Directives
ASSIGN name is a constant | If the SELECT for the XFD file has a constant ASSIGN name (such as ASSIGN TO COMPFILE), that name is used as the starting name for the .xfd file name
ASSIGN name is generic | If the ASSIGN phrase refers to a generic device (such as ASSIGN TO DISK), the compiler uses the SELECT name as the starting name for the XFD
  • Forming the Final XFD Name
  • Mapping Other Files to an XFD
Parent topic: XFDs
Related information
FILE XFD directive
Using XFD Directives


Forming the Final XFD Name

From the starting name, the final name is formed as follows:

  • The compiler removes any extensions from the starting name
  • It constructs a universal base name by stripping out directory information that fits any of the formats used by the operating systems that run the compiler
  • It reduces the base name to eight characters and converts it to lower case
  • It appends the letters .xfd to the base name

Examples of XFD names

COBOL code File name
ASSIGN TO "usr/ar/customer.dat"
 customer.xfd
SELECT TESTFILE, ASSIGN TO DISK
 testfile.xfd
ASSIGN TO FILENAME
 (you specify)
Parent topic: Naming the XFD File


Mapping Other Files to an XFD

At run time, it is possible to use a single XFD for files that have different names. For example, suppose a site has customer files that have identical structures but different names (such as CUST0001, CUST0002, and CUST0003). It's not necessary to have a separate XFD for each file, as long as their record definitions are the same.

The individual files can all be mapped to the same XFD via an ACUCOBOL-GT runtime configuration file variable called XFD_MAP. The following paragraphs describe how this works.

Suppose your COBOL application has a SELECT with a variable ASSIGN name, such as customer-file. This variable assumes different values (such as CUST0001 and CUST0002) during program execution.

Before compiling the application, you would use the FILE XFD directive to provide a base name for the XFD. Suppose you provide CUST as the base. The compiler would then generate an XFD named cust.xfd. (The compiler always converts XFD names to lower case.)

To ensure that all customer files, each having a unique name, use this same XFD, enter the following in your ACUCOBOL-GT runtime configuration file:

XFD_MAP   CUST* = CUST

The asterisk ("*") in the example is a wildcard that matches any number of characters. Note that the extension .xfd should not be included in the map. This statement would cause the XFD cust.xfd to be used for all files whose names begin with CUST.

The XFD_MAP variable has this syntax:

XFD_MAP   [pattern = base-xfd-name]  ...

where pattern consists of any valid filename characters and may include "*" or "?". These two characters have special meanings in the pattern:

* | matches any number of characters
? | matches a single occurrence of any character

For example:

CUST???? | matches CUST0001 and CUSTOMER; does not match CUST001 or CUST00001
CUST* | matches all of the above
CUST*1 | matches CUST001 and CUST0001 and CUST00001; does not match CUSTOMER
*OMER | matches CUSTOMER; does not match CUST001 or CUST0001

The XFD_MAP variable is read during the open file stage of any Connector interfaces linked into the run time system.

XFD values can be replaced or added to the end of existing XFD map values by setting the XFD_MAP_RESETS ACUCOBOL-GT runtime configuration file variable. This variable determines whether setting XFD_MAP adds to or replaces the existing value. When this variable is set to 0 (off, false, no), setting XFD_MAP adds new value patterns to the end of the existing value. When XFD_MAP_RESETS is set to 1 (on, true, yes), setting XFD_MAP replaces the existing value with a new value. The default value is 1 (on, true, yes).

This variable may be useful if you need to include multiple XFD_MAP lines in an ACUCOBOL-GT runtime configuration file and want to avoid setting and resetting the variable. When multiple lines exist, all patterns are used in the order they are listed.

Parent topic: Naming the XFD File
Related information
XFD_MAP configuration variable
FILE XFD directive
XFD_MAP_RESETS configuration variable


Using XFD Directives

This section explains what XFD directives are, and how you can use them in your COBOL File Descriptors (FDs) to control how your database tables are built.

  • Introduction
  • XFD Directive Syntax
  • Supported XFD Directives
Parent topic: Acu4GL Version 10.2.0 User's Guide


Introduction

EXtended File Descriptors (XFDs) are based on your COBOL File Descriptors (FDs). Each XFD describes all of the fields for one file.

XFD directives are optional comments that you can use in your FDs to control how things look on the database side. Many applications use only the -Fx compiler option. XFD directives are most commonly used when a site intends to do a lot of work with the relational database management system (RDBMS) outside of the COBOL application, and wants to control how the database table is built.

XFD directives are special comments placed into an FD in your COBOL source code. They guide the building of the XFDs, which in turn guide the building of the database table.

Each XFD directive includes the letters XFD. These three letters indicate to the compiler that the comment is to be used in XFD generation.

XFD directives provide extended control over how the database table is built. Among other things, they let you:

  • Specify a column name to be used in the database table, in place of a COBOL field name.
  • Map elementary items of a group item together into a single column.
  • Cause numeric COBOL data to be treated as a text string in the database.
  • Cause the fields from a specific record in a file to appear in the database table (rather than just the fields from the largest record).
  • Assign a column the DATE type, providing the built-in functionality that dates have in the RDBMS.
  • Give a name to the XFD file itself.

XFD directives are always placed within a COBOL FD. They do not affect Procedure Division I/O statements, and they do not change your COBOL fields in any way. Rather, they guide the building of the XFDs, giving you control over the way COBOL data maps to database fields.

You can build XFDs directly from your source code with only the -Fx compiler option if the default mapping rules described in XFDs and New and Existing Databases are sufficient for your situation. If you would like to override the default mapping behavior or map a field to a different name, you must add additional XFD directives to your COBOL code.

Parent topic: Using XFD Directives
Related reference
Supported XFD Directives
New and Existing Databases


XFD Directive Syntax

Place each XFD directive syntax on a line by itself, immediately before the COBOL line to which it pertains.

Introduce each XFD directive with a $ in the Indicator Area (column 7 in standard ANSI source format), followed immediately by the letters XFD, and then the XFD directive itself. There should be no space between the $ and the XFD. Spaces are permitted elsewhere on the line as separators. For example, the NAME XFD directive looks like this:

$XFD  NAME = EMP-NUMBER

An alternate ANSI-compliant way to introduce a directive is with an asterisk (*) in the Indicator Area. In this case, you begin the directive with the letters XFD and enclose the entire comment in double parentheses. For example:

*(( XFD  NAME = EMP-NUMBER ))

There should be no space between the asterisk and the double left parentheses. Spaces are permitted elsewhere on the line as separators. You may use either form of the directive syntax (or both) in your applications.

Note that XFD directives are case-insensitive and that hyphens and underscores are considered equivalent. Thus, for example,

$XFD VAR_LENGTH
$XFD VAR-LENGTH
$xfd var_length
$xfd var-length

are all recognized as equivalent.

Two or more XFD directives that pertain to the same line of COBOL code may be combined on one comment line. The XFD directives should be separated by a space or a comma. For example, to specify both USE GROUP and NUMERIC at the same time, you would add this line:

$XFD  USE GROUP, NUMERIC
  • Line Continuation for Complex XFDs
    Syntax for XFD directives that exceed one line.
Parent topic: Using XFD Directives


Line Continuation for Complex XFDs

$XFD directives may be continued onto multiple lines by specifying a single character backslash (\) as the last non-blank character on a line. For example:

$XFD WHEN (var1 = "abc" and var2 = "def"    \
$XFD       and (var3 = "ghi" or var4 = "jkl"))  \
$XFD       or var5 != "xyz"

Line Continuation Rules

  • $XFD directives are continued via a backslash as the last non-blank character on the line.
  • Continued lines begin with $XFD just like the first directive line (with the dollar sign in the indicator column).
  • The final continuation line omits the trailing backslash.
  • "The overall combined directive is a concatenation of all of the continuation lines.
  • The next character after the blank that follows $XFD is the next character of the directive. That character logically replaces the backslash on the previous line.
  • There is no limit on the number of continuation lines other than the limit on total program source lines, and the overall size of the continued directive is limited only by available memory. But it is highly unlikely that one XFD directive would ever need to exceed a few dozen lines or a few thousand characters.
  • In standard ANSI source format the contents of columns 73-80 are ignored, the continuation backslash must appear in Area B (columns 12-72).
  • Backslashes within data (literals) do not cause a problem because they are inside quoted strings (and cannot be the last non-blank character on the line).
  • In-line comments ("*>") are not allowed on continued XFD directive lines.
  • A new error message is generated for a syntax error within continued XFD directive lines and the erroneous continuation lines scanned up to that point are ignored. Possible syntax errors include placing a source line other than a comment line within an intended sequence of continued XFD directive lines, or omitting the final continuation line (the line that begins with $XFD and does not end with a trailing backslash). Other errors are possible when the directive itself is scanned and processed.
Parent topic: XFD Directive Syntax
Parent topic: Directive Syntax


Supported XFD Directives

The following XFD directives are supported.

XFD Directive | Brief Description
ALPHA | Allows you to treat a data item as alphanumeric text in the database, when it is declared as numeric in the COBOL program
BINARY | Specifies that the data in the field could be alphanumeric data of any classification
COBOL-TRIGGER | Tells Acu4GL that a COBOL trigger is to be executed
COMMENT | Allows you to include comments in an XFD file
DATE | Stores a field in the database as a date or time
FILE | Supplies a starting name from which the XFD file name is formed
NAME | Assigns a database field name to the field defined on the next line
NUMERIC | Allows you to treat a data item as an unsigned integer when it is declared as alphanumeric
SECONDARY_TABLE | Indicates that the next data item may be placed into a subordinate table
USE GROUP | Allows you to enter a group item into the database as a single field
VAR_LENGTH | Requests that the data item that immediately follows the XFD directive be assigned a type that implies variable length
WHEN | Lets you include multiple record definitions or REDEFINES in a database table
XSL | Allows you to include a stylesheet reference in the XML header
  • ALPHA XFD directive
  • BINARY XFD directive
  • COBOL-TRIGGER XFD directive
  • COMMENT XFD directive
  • CREATEXFD XFD directive
  • DATE XFD directive
  • FILE XFD directive
  • NAME XFD directive
  • NUMERIC XFD directive
  • SECONDARY_TABLE XFD directive
  • USE GROUP XFD directive
  • VAR_LENGTH XFD directive
  • WHEN XFD directive
  • XSL XFD directive
Parent topic: Using XFD Directives


ALPHA XFD directive

The ALPHA XFD directive allows you to treat a data item as alphanumeric text in the database, when it is declared as numeric in the COBOL program.

Syntax

$XFD ALPHA

This is especially useful when you have numeric keys in which you occasionally store non-numeric data, such as LOW-VALUES or special codes. In this situation, treating the field as alphanumeric allows you to move any kind of data to it.

Example

Suppose you have specified KEY IS code-key. Then assume the following record definition:

01  code-record.
    03  code-key.
        05  code-num      pic 9(5).

In the database, group items are disregarded, so CODE-NUM is the actual key field. Suppose you needed to move a non-numeric value to the key:

MOVE "C0531" TO CODE-KEY.
WRITE CODE-RECORD.

In this case the results are not well-defined because a non-numeric value has been moved into a numeric field. The database might very well reject the record.

One way to solve this problem is to use the ALPHA XFD directive. This causes the corresponding database field to accept alphanumeric data:

 01  code-record.
     03  code-key.
$XFD ALPHA
         05  code-num      pic 9(5).

As an alternative, you could specify the USE GROUP XFD directive on the line before code-key. The USE GROUP XFD directive implies that the field is alphanumeric.

Parent topic: Supported XFD Directives
Related information
USE GROUP directive


BINARY XFD directive

The BINARY XFD directive is used to specify that the data in the field could be alphanumeric data of any classification. Absolutely any data is allowed.

The BINARY XFD directive cannot be used in combination with the VAR_LENGTH XFD directive.

The method of storing fields declared as binary is database-specific. For example, Oracle uses the data type raw for the field.

Syntax

$XFD BINARY

Example

You might use this XFD directive when you need to store a key that contains LOW-VALUES; COBOL allows a numeric field to contain LOW or HIGH values, but these are invalid for a numeric field in the RDBMS:

 01  code-record.
     03  code-key.
         05  code-indic          pic x.
$XFD BINARY
         05  code-num            pic 9(5).
         05  code-suffix         pic x(3).
             .
             .
             .
 move low-values to code-num.
Parent topic: Supported XFD Directives
Related information
VAR_LENGTH directive


COBOL-TRIGGER XFD directive

This XFD directive indicates that a COBOL trigger is to be executed.

Note: This XFD directive must come immediately before the file descriptor of the file for which the trigger is defined. It uses the standard XFD directive syntax.

Syntax

XFD COBOL-TRIGGER=program-name

The following three parameters are passed to the COBOL program:

01  OPCODE.
  88  READ-BEFORE       VALUE "r".
  88  READ-AFTER        VALUE "R".
  88  WRITE-BEFORE      VALUE "w".
  88  WRITE-AFTER       VALUE "W".
  88  REWRITE-BEFORE    VALUE "u".
  88  REWRITE-AFTER     VALUE "U".
  88  DELETE-BEFORE     VALUE "d".
  88  DELETE-AFTER      VALUE "D".

01  FILE-RECORD         PIC X(MAX-RECORD-SIZE).

01  ERROR-CODE          PIC 99.

You can use C$PARAMSIZE to determine the size of the record passed, in case you have variable-length records.

In cases in which the record size is known, the actual record is passed [READ-AFTER (all), WRITE-BEFORE, WRITE-AFTER, REWRITE-BEFORE, REWRITE-AFTER].

In cases in which the record size is not known, the maximum record size is passed [READ-BEFORE (all), DELETE-BEFORE, DELETE-AFTER].

The contents of this field are identical to the record area given to the file operation. The BEFORE images have the value before the file operation, and the AFTER images have the value after the file operation.

Use the ERROR-CODE parameter to signal that an error occurred:

  • If you set this parameter in a BEFORE trigger, the file operation does not execute
  • If you set this parameter in an AFTER trigger, the run time system treats the file operation as an error, though in fact the file operation did execute. This means that, for sequential access (next or previous), the file position has changed and a subsequent next or previous act as if the prior file operation succeeded

Also, if you set an error in the REWRITE-AFTER or DELETE-AFTER, the record does not return to its prior state — the record is modified or deleted in the database. We suggest that you use transactions if this behavior is not acceptable.

Please note that if the COBOL program cannot be called (for any reason), it is treated as having succeeded.

Parent topic: Supported XFD Directives


COMMENT XFD directive

The COMMENT XFD directive lets you include comments in an XFD file. Because the information is embedded in a comment, it doesn't interfere with processing by the interfaces. Each comment entered with this XFD directive appears in the XFD file with the symbol "#" in column one.

Syntax

$XFD COMMENT text
Parent topic: Supported XFD Directives


CREATEXFD XFD directive

Use the CREATEXFD directive to tell the compiler to generate XFDs for the COBOL files contained in your program.

This directive has the following format:

Syntax

$SET CREATEXFD ( version=n, xfd-directory=pathname, file-type=all )

All of the arguments are optional, and can be given in any order.

version=n | Causes XFD files of type n to be used. Currently, "6" is the only valid value here. Any other value causes XFD files of the latest version to be created
xfd-directory=pathname | Causes the XFD files to be created in the directory named by pathname. Pathname must be a valid directory, either absolute or relative, and must be writable to the user
file-type=all | Causes XFD files for all file types to be created. Without this argument, the Compiler creates XFD files for only indexed files. If anything other than "all" is specified, the Compiler creates XFD files only for indexed files
Parent topic: Supported XFD Directives
Related concepts
XFD_DIRECTORY configuration variable
Related reference
C$PARAMSIZE


DATE XFD directive

The DATE XFD directive is used to store a field in the database as a date. Because there's no COBOL syntax that identifies a field as a date, you may want to add this XFD directive to differentiate dates from other numbers, so that they enjoy the properties associated with dates in the RDBMS. To view special options for two-digit dates, see the description of the ACUCOBOL-GT runtime configuration file variable 4GL_2000_CUTOFF in 4GL_2000_CUTOFF configuration variable.

Syntax

$XFD DATE=date-format-string

This XFD directive implies the NUMERIC XFD directive.

If no date-format-string is specified, six-digit (or six-character) fields are retrieved as YYMMDD from the database. Eight-digit fields are retrieved as YYYYMMDD.

The date-format-string is a description of the desired date format, composed of characters from the following list:

M | Month (01–12)
Y | Year (two or four digits)
D | Day of month (01–31)
J | Julian day (00000000–99999999)
E | Day of year (001–366)
H | Hour (00–23)
N | Minute
S | Second
T | Hundredths of a second

Any other characters cause the date format string to be invalid and result in a corrupt XFD error or a compile-time warning.

Each character in a date format string can be considered a place holder that represents the type of information stored at that location. The characters also determine how many digits are used for each type of data.

For example, although you would typically represent the month with two digits, if you specify "MMM" as part of your date format, the resulting date uses three digits for the month, left-zero-filling the value. If the month is given as "M", the resulting date uses a single digit and truncates on the left.

Julian Dates

Because the definition of Julian day varies, the DATE XFD directive offers a great deal of flexibility for representing Julian dates. Many source books define the Julian day as the day of the year, with January 1st being 001, January 2nd being 002, and so forth. If you want to use this definition for Julian day, simply use "EEE" (day of year) in your date formats.

Other reference books define the Julian day as the number of days since some specific base date in the past. This definition is represented in the DATE XFD directive with the letter "J" (for example, a six-digit date field would be preceded with the XFD directive $XFD DATE=JJJJJJ). The default base date for this form of Julian date is 12/31/4714 BC.

You may define your own base date for Julian date calculations by setting the ACUCOBOL-GT runtime configuration file variable 4GL_JULIAN_BASE_DATE.

Handling Invalid Dates or Times

Dates in the following range are considered valid:

01/01/0001 to 12/31/9999

If the interface considers a date or time valid and passes it to an RDBMS that considers it invalid, the results depend on the particular RDBMS. Some systems return an error code. Some store the date as NULL and do not return an error. Some store the date or time in an unpredictable fashion and do not return an error. We recommend that you determine the error handling procedures of the RDBMS in use.

If a COBOL program attempts to write a record containing a date or time that the Acu4GL knows is invalid, the Acu4GL inserts NULLs into the date or time field and writes the record.

If a COBOL program attempts to read into a record from a table with a NULL date or time field, zeroes are inserted into that field in the COBOL record.

For date fields having two-digit years, by default years 0 through 19 are inserted as 2000 through 2019, and years 20 through 99 are inserted as 1920 through 1999.

You can control a number of these situations using configuration variables; see the links at the bottom of the page for more details.

Note:

If a field is used as part of a key, the field cannot be a NULL value. For information about converting date values using the 4GL_CONVERT_DATE_ZERO variable, see 4GL_CONVERT_DATE_ZERO configuration variable.

Using Group Items

You may place the DATE XFD directive in front of a group item, as long as you also use the USE GROUP XFD directive.

Examples

Example 1

 $xfd date
      03  date-hired    pic 9(8).
      03  pay-scale     pic x(3).

The column "date-hired" has eight digits is type DATE in the database, with a format of YYYYMMDD.

Example 2

$XFD DATE, USE GROUP
      03  date-hired.
          05  yyyy      pic 9(4).
          05  mm        pic 9(2).
          05  dd        pic 9(2).

This also produces a column named "date-hired" with eight digits and type DATE in the database, format YYYYMMDD.

Example 3

 $XFD DATE=EEEYYYY
      03  date-sold      pic 9(7).
      03  sales-rep      pic x(30).

This produces a column named "date-sold" with seven digits and type DATE in the database. The date contains the day of the year (for example, February 1st would be 032), followed by the four-digit year, such as 1999).

Example 4

Note: This format and data type is only applicable with SQL Server, and only when using the SQL Server Native Client 11.0 (or later) ODBC driver.
$XFD DATE=HHNNSSTTT
   03 trans-time pic 9(9).

This produces a column named "trans-time" containing data items of type TIME. The time is represented down to the hundredths of a second (for example, 123030030 represents a time of 12:30:30.03).

Parent topic: Supported XFD Directives
Related information
DATE_MIN_LOW_VALUES
DATE_MAX_HIGH_VALUES
DATE_ZERO_VALUE
DATE_NULL_VALUE
DATE_NINE_VALUE
DATE_INVALID_VALUE
4GL_2000_CUTOFF configuration variable
4GL_JULIAN_BASE_DATE configuration variable
4GL_CONVERT_DATE_ZERO configuration variable
NUMERIC directive
USE GROUP directive


FILE XFD directive

The FILE XFD directive supplies a starting name from which the XFD file name is formed. This XFD directive is required only when the file name in the COBOL code is nonspecific. For example, use this XFD directive when the SELECT for the file has a variable ASSIGN name (ASSIGN TO variable_name). In this case, the Connector cannot form a file name automatically, and you must provide a name. The starting name serves as the basis for the XFD name.

Syntax

$XFD FILE=name

This XFD directive must appear on the line immediately preceding the file's FD.

Example

Suppose your SELECT statement has a variable ASSIGN name such as the one shown here:

select my-file
assign to my-variable.

Then you would need to add the FILE XFD directive as shown here:

select my-file
 assign to my-variable.
    .
    .
    .
$xfd  file=payroll
 fd my-file
Parent topic: Supported XFD Directives
Related information
XFD_MAP configuration variable


NAME XFD directive

The NAME XFD directive assigns a database field name to the field defined on the next line.

Syntax

$XFD NAME=fieldname

This XFD directive has several uses, as shown in the following examples.

Example 1 — Non-unique field names

Within a database file, all field names must be unique. (Multiple database tables may include the same field name, but duplicates may not exist within a single table.) Unique field names are not required in COBOL, because names can be qualified by group items.

For example, the following is acceptable in COBOL:

01  employee-record.
    03  date-hired.
        05  yy      pic 99.
        05  mm      pic 99.
        05  dd      pic 99.
    03  date-last-paid.
        05  yy      pic 99.
        05  mm      pic 99.
        05  dd      pic 99.

You need not change the field names in your COBOL program to access a database. Instead, you use the NAME XFD directive to provide unique database names for the fields. For example:

  01  employee-record.
      03  date-hired.
          05  yy      pic 99.
          05  mm      pic 99.
          05  dd      pic 99.
      03      date-last-paid.
 $xfd  name=year-paid
          05  yy      pic 99.
 $xfd  name=month-paid
          05  mm      pic 99.
 $xfd  name=day-paid
          05  dd      pic 99.

The dates portion of the resulting database table is as follows.

yy | mm | dd | year_paid | month_paid | day_paid
88 | 02 | 15 | 94 | 04 | 30

Example 2 — Names not unique within first 18 characters or longer than 18 characters

Some SQL-based databases require that names be unique within 18 characters, and some require that names be no longer than 18 characters. For those systems, the run time system truncates longer COBOL names after the first 18 characters.

For names that are identical within the first 18 characters, or are not meaningful if shortened to the first 18 characters, use the NAME XFD directive to assign them different database field names.

Suppose you had:

01  acme-employee-record.
    03  acme-employee-record-date-hired          pic x(6).
    03  acme-employee-record-date-last-paid      pic x(6).

You could add two NAME XFD directives to differentiate the two item names by making them meaningful within 18 characters:

  01  acme-employee-record.
 $xfd name=date-hired
      03  acme-employee-record-date-hired        pic x(6).
 $xfd name=date-last-paid
      03  acme-employee-record-date-last-paid    pic x(6).

Note that your COBOL names have not changed. The new names are used only for the database fields.

Each time you compile your program to create XFDs, any field names longer than 18 characters is checked for uniqueness within the first 18. If any field names are identical for the first 18 characters, a compiler warning message appears. A warning of this type does not prevent the program from compiling, and the XFD is generated.

Example 3 — Assigning shorter names

You may want to use the NAME XFD directive to assign shorter names than those used in your COBOL programs. This makes the formation of interactive SQL queries easier and quicker. For example:

 $XFD  NAME=EMPNO
      03  employee-number        pic x(8).

This XFD directive causes the XFD to map EMPLOYEE-NUMBER to EMPNO in the database.

Example 4 — Matching field names and COBOL FDs

If your database already exists, and a field name in the database does not match the name used in your COBOL FD, you can use a NAME XFD directive to associate the two names. For example:

 $xfd name=employee-no
      03  employee-number        pic x(8).

This XFD directive causes the XFD to map EMPLOYEE-NUMBER in the COBOL program to EMPLOYEE-NO in the database.

Example 5 — Renaming fields that begin with a numeric character

If your COBOL program uses field names that begin with a numeric character, use the NAME XFD directive to assign a different name for use with your database. SQL typically generates a syntax error when it encounters a column name that begins with a numeric character. For example:

    03  12-months-sales      pic 9(5)V99.

could be renamed this way:

 $xfd  name=twelve-months-sales
      03  12-months-sales    pic 9(5)V99.
Parent topic: Supported XFD Directives
Related reference
CREATEXFD XFD directive


NUMERIC XFD directive

The NUMERIC XFD directive allows you to treat a data item as an unsigned integer when it is declared as alphanumeric. You might use this when the data stored in the item is always numeric.

Syntax

$XFD NUMERIC

Example

$xfd numeric
 01  student-code      pic x(7).
Parent topic: Supported XFD Directives


SECONDARY_TABLE XFD directive

Some Acu4GL interfaces (including MSSQL Server) permit subordinate tables. When this is the case, you can use the SECONDARY_TABLE XFD directive to indicate that the next data item may be placed into a subordinate table if more than one table is necessary to accommodate the data.

Up to 26 subordinate tables can be created from a single record description. Each table name is based on the original table name, with a letter from A to Z appended. For example, if the original table were named "my-table", subsequent subordinate tables would be given these names:

  • my-tableA
  • my-tableB
  • my-tableC
  • my-tableD

When the run time system accesses the XFD, it makes an initial pass through the data, taking all eligible data items for which the SECONDARY_TABLE XFD directive is not specified.

SECONDARY_TABLE is ignored for certain data items. These include:

  • Any field that is part of a key
  • Any field that is an indicator for a WHEN XFD directive

If the table size is not exceeded in the first pass, then, in a second pass, the run time system appends to the original table all items marked SECONDARY_TABLE that can be accommodated.

When the first table reaches a limit (either in total number of columns or total number of characters), that table is created, and a new table is begun. Items that did not fit into the previous table are placed into a subordinate table, in the order in which they are encountered.

The process repeats until all items have been accommodated.

It is permissible to place the SECONDARY_TABLE XFD directive just before a level 01 record definition. In this case, it applies to all fields underneath the level 01.

Syntax

$XFD SECONDARY_TABLE

Example

 $xfd secondary_table
  01  description      pic x(80).
Parent topic: Supported XFD Directives
Related information
WHEN XFD directive


USE GROUP XFD directive

The USE GROUP XFD directive allows you to enter a group item into the database as a single field, instead of using the elements contained in the group. This is necessary if the item is stored in an existing database as a group, rather than as individual fields.

Combining fields of data into meaningful groups for database storage also improves I/O efficiency.

Syntax

$XFD USE GROUP

By default, the USE GROUP XFD directive implies that the consolidated field is alphanumeric. If you want a numeric field, simply add the word NUMERIC at the end of the XFD directive.

Example 1 – Combining DATE and USE GROUP XFD directives

For example, the XFD directive in the following code combines the functions of the USE GROUP and DATE XFD directives, and indicates that the date should be entered into the database as a single date-formatted data item instead of three distinct fields:

  $XFD  USE GROUP, DATE
       03  date-entered.
           05  yy      pic 99.
           05  mm      pic 99.
           05  dd      pic 99.

Either a comma or a space (or both) may separate the word "DATE" from the words "USE GROUP".

Example 2 – Forming larger units

Other fields with which you might use this XFD directive include multi-part account numbers or department numbers, or keys that are referenced as a unit but not by their individual pieces. Here's an example of an item that might be grouped:

 $xfd  use group
  01  gl-acct-no.
      03  main-acct     pic 9(4).
      03  sub-acct      pic 9(3).
      03  dept-no       pic 9(3).

If you are using an existing database in which certain fields are grouped, they must also be grouped in your COBOL file descriptor.

If the database does not yet exist, keep in mind that combining fields into groups can improve execution speed. Whether to group fields or not also depends on whether they are always stored and used together. Someone who really knows how the data is being used might help to identify groups of fields that can be combined to speed processing.

Parent topic: Supported XFD Directives
Related information
DATE XFD directive
NUMERIC XFD directive


VAR_LENGTH XFD directive

By default, the Compiler generates fixed-length fields in the XFD. The VAR_LENGTH XFD directive requests that the data item that immediately follows the XFD directive be assigned a type that implies variable length, if possible. This can save considerable space in your database.

The VAR_LENGTH XFD directive cannot be used in combination with the BINARY XFD directive.

The precise variable type that is assigned to the data item depends on which RDBMS is in use. Possible variable types that might be assigned are VARCHAR, LVARCHAR and VARBINARY.

Syntax

$XFD VAR_LENGTH

Example

For example, the XFD directive in the following code indicates that the employee-name field should be entered into a DB2 database as a VARCHAR data item.

 $XFD  VAR_LENGTH
      03  employee-notes      pic x(300).
Parent topic: Supported XFD Directives
Related information
BINARY XFD directive


WHEN XFD directive

The WHEN XFD directive is used when you want to include multiple record definitions or REDEFINES in a database table. It's typically used when you want to force certain columns to be built that wouldn't be built by default (because you want to use them from the RDBMS side). For more information, see REDEFINES Clause.

Recall that the key fields and the fields from the largest record are automatically included as explicit columns in the database table. All fields are stored and retrieved from the database, whether they appear as explicit columns or not. So you don't need to use WHEN unless you want to ensure that some additional fields are explicitly listed by name in the table. For details about how fields are included in the database table, see How XFDs Are Formed.

WHEN declares that the field (or subordinate fields, if it is a group item) that immediately follow the XFD directive must appear as a column (or columns) in the database table. It also states one condition under which the columns are to be used. The WHEN XFD directive guarantees that the fields are explicitly included in the table, as long as they aren't FILLER and don't occupy the same area as key fields.

The WHEN XFD directive results in a table that unites all fields subordinate to the WHEN XFD directive. This table might include more columns and could affect performance and storage requirements.

Syntax

$XFD WHEN field = value     (equals)
$XFD WHEN field <= value    (is less than or equals)
$XFD WHEN field < value     (is less than)
$XFD WHEN field >= value    (is greater than or equals)
$XFD WHEN field > value     (is greater than)
$XFD WHEN field != value    (is not equal to)
$XFD WHEN field = OTHER

The value may be an explicit data value (in quotes). The word "OTHER" can be used only with "=". It means use the following field(s) only if the WHEN condition(s) listed at the level of this field are not met.

Note: WHEN values must be on individual lines as single values in the code. WHEN values cannot be combined.

For example:

     03 ar-code-type                  pic x.
$xfd when ar-code-type = "s"
     03 ship-code-record              pic x(4).
$xfd when ar-code-type = "b"
     03 backorder-code-record redefines ship-code-record.
$xfd when ar-code-type = other
     03 obsolete-code-record redefines ship-code-record.

OTHER may be used before one record definition, and may be used once at each level within each record definition.

Note: A WHEN XFD directive with condition OTHER must be used if there is a possibility that the data in the field does not meet any of the explicit conditions specified in the other WHEN XFD directives. If this is not done, results are undefined.

Example 1

01 ar-codes-record.
  03 ar-codes-key.
    05 ar-code-type    pic x.
    05 ar-code-num     pic 999.
01 ship-code-record.
  03 filler            pic x(4).
  03 ship-instruct     pic x(15).
01 terms-code-record.
  03 filler            pic x(4).
  03 terms-rate-1      pic s9v999.
  03 terms-days-1      pic 9(3).
  03 terms-rate-2      pic s9v999.
  03 terms-descript    pic x(15).

If you add the WHEN XFD directive as shown below, it causes the fields from the SHIP-CODE-RECORD to be included in the database table, and determines when specific database columns are used. The underlined fields then appear as columns in the database table:

 01 ar-codes-record.
   03 ar-codes-key.
     05 ar-code-type      pic x.
     05 ar-code-num       pic 999.
$xfd when ar-code-type = "s"
 01 ship-code-record.
   03 filler              pic x(4).
   03 ship-instruct       pic x(15).
$xfd when ar-code-type = "t"
 01 terms-code-record.
   03 filler              pic x(4).
   03 terms-rate-1        pic s9v999.
   03 terms-days-1        pic 9(3)
   03 terms-rate-2        pic s9v999.
   03 terms-descript      pic x(15).

FILLER data items don't have unique names and are thus not used to form columns in the database table. You could use the NAME XFD directive to give them a name if you really need to see them in the database table.

Note: In this example, the FILLER data items implicitly redefine key fields. Thus, they would be disregarded even if you provided a name for them.

Example 2

In the following code, in which no WHEN XFD directives are used, the underlined fields are explicitly named in the database table. (Key fields have the suffix key in their names in this example.)

Note that REDEFINES records simply re-map the same data area and are not explicitly included in the database table by default:

01 archive-record.
  03 filler               pic x(33).
  03 archive-code         pic 9(6).
  03 archive-location     pic 9(2).
  03 filler               pic x(10).
01 master-record.
  03 animal-id-key.
    05 patient-id         pic 9(6).
    05 species-code-type  pic 9(5).
    05 species-name       pic x(6).
  03 service-code-key.
    05 service-code-type  pic 9(6).
    05 service-name       pic x(10).
  03 billing-code.
    05 billing-code-type  pic 9(4).
    05 plan-name          pic x(8).
  03 office-info.
    05 date-in-office     pic 9(8).
    05 served-by-name     pic x(10).
  03 remote-info redefines office-info.
    05 van-id             pic 9(4).
    05 proc-code          pic 9(8).
    05 vet-name           pic x(6).

If you add the WHEN XFD directives shown below, you add several columns to the database table. The fields which then appear in the table are underlined:

$xfd when animal-id-key = "00000000000000000"
 01 archive-record.
   03 filler              pic x(33).
   03 archive-code        pic 9(6).
   03 archive-location    pic 9(2).
   03 filler              pic x(10).
$xfd when animal-id-key = other
 01 master-record.
$xfd use group
   03 animal-id-key.
     05 patient-id        pic 9(6).
     05 species-code-type pic 9(5).
     05 species-name      pic x(6).
   03 service-code-key.
     05 service-code-type pic 9(6).
     05 service-name      pic x(10).
   03 billing-code.
     05 billing-code-type pic 9(4).
     05 plan-name         pic x(8).
$xfd when billing-code-type = "1440"
   03 office-info.
     05 date-in-office    pic 9(8).
     05 served-by-name    pic x(10).
$xfd when billing-code-type = other
   03 remote-info redefines office-info.
     05 van-id            pic 9(4).
     05 proc-code         pic 9(8).
     05 vet-name          pic x(6).

Example 3

If your application has a REDEFINES whose field names are more meaningful than the fields they redefine, you might consider switching the order of your code, rather than using a WHEN XFD directive. Use the less significant field names in the REDEFINES.

For example, you might change this:

   03 code-info.
     05 filler        pic 9(8).
     05 code-1        pic x(10).
   03 patient-info redefines code-info.
     05 patient-id    pic 9(4).
     05 service-code  pic 9(8).
     05 server-name   pic x(6).

to this:

   03 patient-info.
     05 patient-id    pic 9(4).
     05 service-code  pic 9(8).
     05 server-name   pic x(6).
   03 code-info redefines patient-info.
     05 filler        pic 9(8).
     05 code-1        pic x(10).

The fields that would appear in the database table by default are underlined above. This shows how the column names might become more meaningful when the order is reversed. Your application operates the same either way.

Note: When a WHEN XFD directive condition is met, COBOL record definitions or REDEFINES records that are subordinate to other WHEN XFD directives are not used. Database columns in rows that correspond to those records are set to the special database value NULL. This means that there is no value provided for those columns. NULL is not equivalent to zero, and it has special properties in the RDBMS. For example, you can select all rows for which a given column is NULL.

Example 4

This COBOL code:

01  col-type                         pic x.
 $xfd  when col-type = "a"
      03  def1                         pic x(2).
 $xfd  when col-type = "b"
      03  def2 redefines def1          pic 9(2).

results in this database table:

col_type | def1 | def2
a | Xx | <Null>
b | <Null> | 10
  • WHEN Complex Expressions
    Syntax and rules for using complex expressions with WHEN directives.
Parent topic: Supported XFD Directives
Related information
How XFDs are Formed
NAME XFD directive
REDEFINES Clause


WHEN Complex Expressions

The XFD WHEN directive supports complex expressions such as those containing multiple AND and OR operations and parentheses to group sub-expressions for proper order of evaluation. For example:

$XFD WHEN (var1 = "abc" or var1 = "def") and \
$XFD      (var2 > "000" or var3 > "000") and \
$XFD       var4 != "xyzzy"

Here is a more complete example:

       fd idx1-file.
       01 idx1-record1.
          03 filler pic x(46).

       01 idx1-record2.
          03 idx1-key.
             05 idx1-num1  pic 9(3).
             05 idx1-num2  pic 9(3).
             05 idx1-num3  pic 9(3).
          03 filler pic x(37).

      $xfd when ((idx1-num1 = "000" or idx1-num1 = "009") and  \
      $xfd       (idx1-num2 = "000" or idx1-num2 = "009"))     \
      $xfd   tablename=one
       01 idx1-record3.
          03 filler pic x(6).
          03 rec3-name1  pic x(20).
      $xfd when idx1-num3 = "333" or idx1-num3 = "444", tablename=two
          03 rec3-name2  pic x(20).

      $xfd when idx1-num1 = "001" AND idx1-num2 = "001"
       01 idx1-record4.
          03 filler pic x(6).
          03 rec4-name1  pic x(30).
          03 rec4-name2  pic x(10).

      $xfd when idx1-num1 > "001" OR idx1-num2 > "001"
       01 idx1-record5.
          03 filler pic x(6).
          03 rec5-text  pic x(40).

WHEN Expression Rules

  1. The AND operation takes precedence over the OR operation. If sc1, sc2, and sc3 are simple conditions (as defined above) then the expression sc1 or sc2 and sc3 is interpreted as sc1 or (sc2 and sc3) meaning that the AND of sc2 and sc3 is performed first and the result of that operation is OR'ed with sc1. If you want the OR operation performed first then you must specify (sc1 or sc2) and sc3 using parentheses.
  2. Since expressions are likely to use parentheses it is strongly recommended that the "$XFD" syntax be used rather than the "*(( XFD" with trailing "))" syntax.
  3. Mismatched parentheses cause an error to be reported.
  4. The maximum number of simple conditions in one expression is 50. An error is reported if the maximum is exceeded.
  5. Only one WHEN expression directive is allowed on consecutive lines. For example, the following three lines cause a syntax error to be reported:
    $XFD WHEN var1 = "abc" or var2 = "def"
$XFD WHEN var3 = "xyz"
01  record-type-2.

    If what you meant was:

    $XFD WHEN (var1 = "abc" or var2 = "def") \
$XFD   and var3 = "xyz"
01  record-type-2.

    then you must code it that way (note the use of parentheses and the backslash XFD directive line continuation character).

    "The optional condition tablename at the end of a WHEN directive applies to all simple conditions within the expression and to the overall combined expression. For example:

    $XFD WHEN (var1 = "abc" or var1 = "def") and \
$XFD      (var2 = "123" or var2 = "456") \
$XFD      tablename = table-2
01  record-type-2.

    The condition tablename table-2 is applied to all four simple conditions and propagated to the two OR conditions and to the final AND condition of the expression.

Parent topic: WHEN XFD directive
Parent topic: WHEN directive


XSL XFD directive

The XSL XFD directive allows you to include a stylesheet reference in the XML header.

Syntax

$XFD XSL=stylesheet

where stylesheet is an alphanumeric literal indicating the appropriate stylesheet. The Compiler includes the following line in all generated XML-style XFD files:

<?xml-stylesheet type="text/xsl" href="stylesheet"?>

For example:

$XFD XSL="myxsl.xsl"

generates this line:

<?xml-stylesheet type="text/xsl" href="myxsl.xsl"?>
Parent topic: Supported XFD Directives


Invalid Data

This section lists the COBOL data items that are considered invalid, and explains what happens to them when they are stored in the database. This section also explains that database items that are considered invalid, and explains how those are translated to COBOL.

  • Illegal COBOL Data
Parent topic: Acu4GL Version 10.2.0 User's Guide


Illegal COBOL Data

COBOL data (except key data) that is illegal by database standards is stored in the database as null unless you specifically override this default. (Use the ACUCOBOL-GT runtime configuration file variable 4GL_ILLEGAL_DATA to override.)

The following COBOL data usages are considered illegal by the database:

 | Illegal Values
USAGE DISPLAY numbers | LOW-VALUES , HIGH-VALUES, and SPACES
COMP-2 numbers | HIGH-VALUES and SPACES
COMP-3 numbers | HIGH-VALUES

All other numeric types fit one of the preceding cases (depending on their internal storage format)

DATE fields | The value "zero" and any other illegal conditions as defined by the date's USAGE type (see above)
text fields | LOW-VALUES

BINARY numbers are always legal, and all values are legal in BINARY text fields.

  • Invalid Key Data
  • Invalid Data Other Than Keys
Parent topic: Invalid Data
Related information
4GL_ILLEGAL_DATA configuration variable


Invalid Key Data

Any field that is part of a key is never stored as null. (A null key does not have a well-defined position in relation to other keys.) If a key field has an illegal value, the field is stored in the database as described here:

Illegal LOW-VALUES | minimum possible value (0 or -99999...) minimum possible date value (01/01/01)
Illegal HIGH-VALUES | maximum possible value (99999...) maximum possible date value (database dependent)
Illegal SPACES | zero (or 01/01/01 for a date field)
Parent topic: Illegal COBOL Data


Invalid Data Other Than Keys

You have the option to convert illegal data, other than keys, into legal values by setting the configuration variable 4GL_ILLEGAL_DATA to Converted. When this is set, the Acu4GL interface converts data the same way it does for keys.

4GL_ILLEGAL_DATA can also be set to Null to indicate that illegal COBOL data other than keys should be converted to null. This is the default behavior.

Parent topic: Illegal COBOL Data
Related information
4GL_ILLEGAL_DATA configuration variable


Working with COBOL

After the environment has been set up for the Acu4GL interface, you are ready to use the system. This section describes how to prepare your COBOL program and compile it for use with Acu4GL.

  • Examples of Preparing and Compiling a Program
  • Creating File Descriptors and SELECT Statements
Parent topic: Acu4GL Version 10.2.0 User's Guide


Examples of Preparing and Compiling a Program

The acu4gl sub-directory within your Sample directory contains three sample programs that are based on the code excerpt below. These programs show different ways of how to manipulate your COBOL records in readiness for being written to a database.

Note: If you are not familiar with XFD directives, you may want to read the topics in the Using XFD Directives section before continuing with this topic.

The examples are based upon a purchase orders file from a COBOL program and will be stored in a database. The file descriptor below contains the records that handle all of the information from a fictitious company's purchase orders. Within it are two record types:

  • The purchase order (header) record (there is one of these for each purchase order form)
  • The purchase order detail record (there is one detail record for each line item in a purchase order)

The file is keyed off the purchase order number. This following three examples demonstrate three different approaches to using the COBOL file descriptor and XFD directives:

  • Example 1 (order1.cbl) only includes the largest record in the database table; see Example 1 - Compiling with just the -Fx compiler option.
  • Example 2 (order2.cbl) uses the WHEN XFD directive, which causes all record formats to be included in the database; see Example 2 - Compiling with the WHEN XFD Directive.
  • Example 3 (order3.cbl) groups together several fields and renames them, for convenience; see Example 3 - Using Additional XFD Directives.
IDENTIFICATION DIVISION.
program-id.  purchase.
ENVIRONMENT DIVISION.
input-output section.
file-control.

select p-o-file
assign to disk "purch1"
organization is indexed
access mode is dynamic
record key is p-o-number
file status is p-o-status.

DATA DIVISION.
file section.
fd p-o-file.
01 p-o-record.
   03 p-o-division-number                pic 9(3).
   03 p-o-record-type                    pic x.
      88 header-record                   value "h".
      88 detail-record                   value "d".
   03 p-o-number                         pic 9(10).
   03 p-o-number-detail redefines
         p-o-number.
      05 picking-ticket-number           pic 9(6).
      05 shipping-region                 pic 9(2).
      05 p-o-customer-type               pic 9(2).
      05 p-o-customer-breakdown redefines
            p-o-customer-type.
         07 customer-category            pic x.
         88 p-o-customer-retail          value "r".
         88 p-o-customer-whlsale         value "w".
         07 customer-pay-format          pic x.
            88 is-net-30                 value "3".
            88 is-net-10                 value "1".
   03 p-o-date.
      05 p-o-yy                          pic 9(2).
      05 p-o-mm                          pic 9(2).
      05 p-o-dd                          pic 9(2).

01 p-o-detail-record.
   03 p-o-dept-number                    pic 9(3).
   03 p-o-record-type                    pic x.
   03 detail-p-o-number                  pic 9(10).
   03 p-o-shipping-info.
      05 p-o-quantity-to-ship            pic s9(4) comp.
      05 p-o-total-quantity              pic s9(4) comp.
   03 p-o-notes.
      05 notes-line occurs 3 times       pic x(40).
working-storage section.
01 p-o-status                            pic x(2).
PROCEDURE DIVISION.
level-1 section.
main-logic.

open output p-o-file.
close p-o-file.
stop run.
  • Example 1 - Compiling with just the -Fx compiler option
  • Example 2 - Compiling with the WHEN XFD Directive
  • Example 3 - Using Additional XFD Directives
Parent topic: Working with COBOL
Related reference
Using XFD Directives
Example 1 - Compiling with just the -Fx compiler option
Example 2 - Compiling with the WHEN XFD Directive
Example 3 - Using Additional XFD Directives


Example 1 - Compiling with just the -Fx compiler option

This example (order1.cbl) just uses the -Fx compiler option to generate the XFD. The compiled program builds the database table shown at the end of this section.

The database table builds as follows.
  • First, any fields listed in the KEY IS clause of the SELECT are included (p-o-number in this example).
  • The compiler then takes the largest record (p-o-detail-record) and lists the fields that make up that record.
The rest of this section shows the specific fields that are placed into the table.

All data from the COBOL program is stored in and retrieved from the database, even though not all fields are explicitly named in the database table. For a description of how this works, see XFDs.

The underlined fields are the only ones entered into the table:

fd p-o-file.
 01  p-o-record.
     03  p-o-division-number                   pic 9(3).
     03  p-o-record-type                       pic x.
         88  header-record                     value "h".
         88  detail-record                     value "d".
     03  p-o-number                            pic 9(10).
     03  p-o-number-detail redefines p-o-number.
         05  picking-ticket-number             pic 9(6).
         05  shipping-region                   pic 9(2).
         05  p-o-customer-type                 pic 9(2).
         05  p-o-customer-breakdown redefines
               p-o-customer-type.
             07  customer-category             pic x.
                 88  p-o-customer-retail       value "r".
                 88  p-o-customer-whlsale      value "w".
             07  customer-pay-format           pic x.
                 88 is-net-30                  value "3".
                 88 is-net-10                  value "1".
     03  p-o-date.
         05  p-o-yy                            pic 9(2).
         05  p-o-mm                            pic 9(2).
         05  p-o-dd                            pic 9(2).

 01  p-o-detail-record.
     03  p-o-dept-number                       pic 9(3).
     03  p-o-record-type                       pic x.
     03  detail-p-o-number                     pic 9(10).
     03  p-o-shipping-info.
         05  p-o-quantity-to-ship              pic s9(4) comp.
         05  p-o-total-quantity                pic s9(4) comp.
     03  p-o-notes.
         05  notes-line occurs 3 times         pic x(40).

As the table is built:

  • Any hyphens in the COBOL field names are converted to underscores
  • Field names longer than 18 characters generate a warning if the first 18 characters are not unique. Some databases limit you to 18 total characters. Use the least number of characters for optimal portability and end-user efficiency. You can use the NAME XFD directive for this to avoid changing your procedure division code.
  • Fields in OCCURS clauses get special handling, because the run time system must assign a unique name to each data item. Sequential index numbers are appended to the item named in the OCCURS. Limits vary between databases. See to the documentation for your RDBMS. In some instances, the name may be truncated by the Connector if necessary before the index is added.
Note: detail-p-o-number is not part of the table because the key overlays this area.

The following table is built in the database:

Column Name | Type
p_o_number | number(10)*
p_o_dept_number | number(3)*
p_o_record_type | char(1)
p_o_quantity_to_ship | number(4)*
p_o_total_quantity | number(4)*
notes_line_1 | char(40)
notes_line_2 | char(40)
notes_line_3 | char(40)

* The actual database data type may vary.

See the Limits and Ranges topic for your specific RDBMS for a list of supported data types and their COBOL equivalents.

Parent topic: Examples of Preparing and Compiling a Program
Related reference
XFDs
NAME XFD directive


Example 2 - Compiling with the WHEN XFD Directive

This example (order2.cbl) enables you to override the default table build; it allows you to force certain columns to be built that would be built by default. Add the WHEN XFD directive in front of each record, which results in the underlined fields being entered into the table:

fd p-o-file.
$xfd when p-o-record-type = "h"
 01  p-o-record.
     03  p-o-division-number                       pic 9(3).
     03  p-o-record-type                           pic x.
         88  header-record                         value "h".
         88  detail-record                         value "d".
     03  p-o-number                                pic 9(10).
     03  p-o-number-detail redefines p-o-number.
         05  picking-ticket-number                 pic 9(6).
         05  shipping-region                       pic 9(2).
         05  p-o-customer-type                     pic 9(2).
         05  p-o-customer-breakdown redefines
               p-o-customer-type.
             07  customer-category                 pic x.
                 88  p-o-customer-retail           value "r".
                 88  p-o-customer-whlsale          value "w".
             07  customer-pay-format               pic x.
                 88  is-net-30                     value "3".
                 88  is-net-10                     value "1".
     03  p-o-date.
         05  p-o-yy                                pic 9(2).
         05  p-o-mm                                pic 9(2).
         05  p-o-dd                                pic 9(2).
$xfd when p-o-record-type = "d"
 01  p-o-detail-record.
     03  p-o-dept-number                           pic 9(3).
     03  p-o-record-type                           pic x.
     03  detail-p-o-number                         pic 9(10).
     03  p-o-shipping-info.
         05  p-o-quantity-to-ship                  pic s9(4) comp.
         05  p-o-total-quantity                    pic s9(4) comp.
     03  p-o-notes.
         05  notes-line occurs 3 times             pic x(40).
Note: p-o-record-type is entered into the table only once. The detail-p-o-number field is not part of the table, because the key overlays this area.

The following table is built in the database:

Column Name | Type
p_o_division_number | number(3)*
p_o_record_type | char(1)
p_o_number | number(10)*
p_o_yy | number(2)*
p_o_mm | number(2)*
p_o_dd | number(2)*
p_o_dept_number | number(3)*
p_o_quantity_to_ship | number(4)*
p_o_total_quantity | number(4)
notes_line_1 | char(40)
notes_line_2 | char(40)
notes_line_3 | char(40)

* The actual database data type may vary.

Note: When p_o_record_type is h, p_o_dept_number, p_o_quantity_to_ship, p_o_total_quantity, and notes_lines_1, 2, and 3 become NULL. When p_o_record_type is d, p_o_division_number, p_o_yy, p_o_mm and p_o_dd become NULL.
Parent topic: Examples of Preparing and Compiling a Program
Related reference
WHEN XFD directive


Example 3 - Using Additional XFD Directives

This example (order3.cbl) demonstrates how to streamline the code to introduce the following changes:

  • Apply the USE GROUP XFD directive to the notes to group them, which improves execution speed and clarity. Accessing each note line individually from the database side is not required.
  • Rename the notes field for convenience.
  • Apply the USE GROUP and DATE XFD directives to the date, to give it all the properties of a date on the database side.
fd p-o-file.
$xfd when p-o-record-type = "h"
 01  p-o-record.
     03  p-o-division-number                      pic 9(3).
     03  p-o-record-type                          pic x.
         88  header-record                        value "h".
         88  detail-record                        value "d".
     03  p-o-number                               pic 9(10).
     03  p-o-number-detail redefines p-o-number.
         05  picking-ticket-number                pic 9(6).
         05  shipping-region                      pic 9(2).
         05  p-o-customer-type                    pic 9(2).
         05  p-o-customer-breakdown redefines
               p-o-customer-type.
             07  customer-category                pic x.
                 88  p-o-customer-retail          value "r".
                 88  p-o-customer-whlsale         value "w".
             07  customer-pay-format              pic x.
                 88  is-net-30                    value "3".
                 88  is-net-10                    value "1".
$xfd use group, date
     03  p-o-date.
         05  p-o-yy                               pic 9(2).
         05  p-o-mm                               pic 9(2).
         05  p-o-dd                               pic 9(2).
$xfd when p-o-record-type = "d"
 01  p-o-detail-record.
     03  p-o-dept-number                          pic 9(3).
     03  p-o-record-type                          pic x.
     03  detail-p-o-number                        pic 9(10).
     03  p-o-shipping-info.
         05  p-o-quantity-to-ship                 pic s9(4) comp.
         05  p-o-total-quantity                   pic s9(4) comp.
$xfd use group, name = notes
     03  p-o-notes.
         05  notes-line occurs 3 times            pic x(40).
Note: p-o-record-type is entered only once into the table. The detail-p-o-number field is not part of the table, because the key overlays this area.

The following table is built in the database:

Column Name | Type
p_o_division_number | number(3)
p_o_record_type | char(1)
p_o_number | number(10)
p_o_date | date
p_o_dept_number | number(3)
p_o_quantity_to_ship | number(4)
p_o_total_quantity | number(4)
notes | char(120)
Parent topic: Examples of Preparing and Compiling a Program
Related reference
DATE XFD directive
USE GROUP XFD directive


Creating File Descriptors and SELECT Statements

acu4glfd is a Windows-based utility that can help you analyze tables and create File Descriptors and SELECT statements. This utility uses ODBC technology to retrieve table information to list the fields in the table. When possible, the utility also determines a unique index and uses that index as the primary key.

Upon request, acu4glfd generates two kinds of output:

  1. a file descriptor (FD), listing the names of the columns in a table and their associated data types
  2. a SELECT statement for the file

You can COPY the FD and SELECT statement into your COBOL program, although you may need to make some changes, as indicated in this topic.

The acu4glfd utility is intended to help you jump start preparing your table for use with a COBOL program. The program determines the names of the columns, attempts to determine the appropriate ACUCOBOL-GT® data type for the column, and attempts to determine the primary key.
Note: acu4glfd does not attempt to identify alternate keys.

Remember, though, that database data is flat, and COBOL data can contain group items and depth. Because table data does not contain information about GROUP structure the way a COBOL program does, it may be necessary for you to tweak the code produced by acu4glfd and specify a picture before the program compiles properly. Any errors produced in this early compilation will assist in fine-tuning the FD for your COBOL program. This saves the time and effort of completely analyzing the table and coding the FD and SELECT statements yourself.

The acu4glfd utility operates only on data types that are understood by ODBC. Database drivers can define their own data types as well; these driver-defined data types are not recognized by acu4glfd. Therefore, the utility may not be able to identify all data types represented in the table. Refer to your database, driver, and ODBC documentation for additional information. Before starting the acu4glfd utility, you must define your table/data as an ODBC data source. See your ODBC documentation for information about drivers and data sources.

Note that the examples are based on the following table in Microsoft Access.

Note that the phone number (PHONE field) is the table's key.

Parent topic: Working with COBOL
Related reference
Using acu4glfd


New and Existing Databases

This section explains how to handle your data in both existing and new databases.

  • Databases
  • Default Behavior
  • Accessing Existing Database Files
Parent topic: Acu4GL Version 10.2.0 User's Guide


Databases

You may encounter one of two situations as you begin to use Acu4GL. In situation one, the database files don't exist yet. In situation two, the database files already exist, and you want to access that existing data from a COBOL application. There may or may not already be existing COBOL programs that access the database.

Each situation has potential questions.
  • How do I declare COBOL data so that it matches the database data?
  • Are there any special fields in the database that must be accessed in a special way?
  • How do I create COBOL record names, field names, index names, and data types that best conform to the compiler, Acu4GL, and the database engine?
These questions are addressed in the next few sections.
Parent topic: New and Existing Databases


Default Behavior

The following are automatically handled by Acu4GL:

  • Conversion of uppercase field names to lowercase (or vice versa) when necessary.
  • Data conversions needed to match the internal storage formats used by the database.
  • Creation of database files, if needed, when you execute an OPEN OUTPUT verb. If this is your situation, matching COBOL fields to database fields should not be an issue. Fields match perfectly, because the database fields are based on your COBOL code. As an alternative, you can use your database query tool to create a database.
  • Sequencing of data returned from a database: you may encounter unexpected sequencing. If your COBOL definition does not include alternate keys with duplicates, the data is returned in key order. If your COBOL definition does include alternate keys with duplicates, Acu4GL cannot control the sequence in which the data is returned. The database query optimizer decides how to order the returned records. For a set of records with the same key value, the records may not be in historical order
Parent topic: New and Existing Databases


Accessing Existing Database Files

If accessing existing data in a relational database, you need to know how to declare your data to match the database fields.

If your COBOL code isn't written yet, you should follow the guidelines given in the Appendix for your specific RDBMS.

If your COBOL code already exists, you can make necessary adjustments by adding XFD directives to your code. XFD directives are comments that guide the creation of the eXtended File Descriptors (XFDs). The XFDs in turn help map the COBOL fields to their equivalent database fields. XFD directives are described in Using XFD Directives, and XFDs are described in XFDs.

  • How Do I Match Existing Text Fields?
  • How Do I Match Existing Numeric Fields?
  • Field Names
Parent topic: New and Existing Databases
Related information
Using XFD Directives
XFDs


How Do I Match Existing Text Fields?

To access character data, you simply declare the field as PICTURE X, with as many X's as appropriate.

Parent topic: Accessing Existing Database Files


How Do I Match Existing Numeric Fields?

Numeric fields are more database-specific than text fields. Most relational database systems accommodate INTEGER, DECIMAL, and DATE types. For information on the handling of other numeric types, see the Appendix containing information specific to your RDBMS.

Parent topic: Accessing Existing Database Files


Field Names

If your COBOL application already exists, and if it must access a relational database that already exists, you may have to work around differences in the names of the fields, as well as naming conventions imposed by the RDBMS. For example, your program might use the name EMPLOYEE-NO, while the database uses the name EMP-NUMBER for the same item of information.

  • Resolving Name Conflicts
Parent topic: Accessing Existing Database Files


Resolving Name Conflicts

If naming differences exist, you need not rename your COBOL fields and you need not change the database. This is because the -Fx compiler option builds XFDs that map your COBOL fields to the correct database fields. The mapping is automatic if the names are the same. If the COBOL name differs from the database name, you enable the compiler to make the correct mapping by adding a NAME XFD directive to your COBOL code.

You can also use XFD directives to produce other effects when data is mapped from COBOL to the database. XFD directives are described in detail in Using XFD Directives.

Parent topic: Field Names
Related information
Using XFD Directives
Name XFD Directive


Compiler and Runtime Options

These topics descibe compiler options related to XFD generation. They also detail the runtime configuration variables that apply to all of the Acu4GL interfaces.

  • Compiler File Options
  • Run-time Configuration Variables
Parent topic: Acu4GL Version 10.2.0 User's Guide


Run-time Configuration Variables

There are several variables that can be set in your run-time configuration file that affect Acu4GL processing. Those listed below are applicable to any RDBMS with which Acu4GL communicates. Some configuration variables are database-specific; those variables are discussed in the individual database product topics found in this User's Guide.

Most configuration variables can be read with the ACCEPT FROM ENVIRONMENT verb. If the variable to be read is numeric, the receiving field must be defined either as a numeric field or as an alphanumeric field of five or more characters. If it is defined as alphanumeric and is longer than five characters, the value that is read from the environment will occupy the leftmost five characters of the field and the remainder will be space-filled.

  • 4GL_2000_CUTOFF configuration variable
  • 4GL_8_DIGIT_CUTOFF configuration variable
  • 4GL_COLUMN_CASE configuration variable
  • 4GL_COMMIT_COUNT configuration variable
  • 4GL_CONVERT_DATE_ZERO configuration variable
  • 4GL_DB_MAP configuration variable
  • 4GL_EXTRA_DB_COLS_OK configuration variable
  • 4GL_FULL_DATA_TEST configuration variable
  • 4GL_IGNORED_SUFFIX_LIST configuration variable
  • 4GL_ILLEGAL_DATA configuration variable
  • 4GL_JULIAN_BASE_DATE configuration variable
  • 4GL_USEDIR_LEVEL configuration variable
  • 4GL_WHERE_CONSTRAINT configuration variable
  • DEFAULT_HOST configuration variable
  • FILE_TRACE configuration variable
  • filename_HOST configuration variable
  • XFD_DIRECTORY configuration variable
  • XFD_MAP configuration variable
  • XFD_MAP_RESETS configuration variable
  • XFD_PREFIX configuration variable
Parent topic: Compiler and Runtime Options


4GL_2000_CUTOFF configuration variable

This variable implements "date windowing" for Acu4GL. It determines the two-digit years considered to be in the twentieth century and the two-digit years considered to be in the twenty-first century.

This variable accepts a two-digit value. Two-digit years that are smaller than this value are considered part of the twenty-first century ("2000" is added to these dates).

Two-digit years that are equal to or larger than this value are considered to be in the twentieth century ("1900" is added to them).

The default value for 4GL_2000_CUTOFF is 20.

Parent topic: Run-time Configuration Variables
Related information
4GL_8_DIGIT_CUTOFF configuration variable


4GL_8_DIGIT_CUTOFF configuration variable

This variable determines whether to use the 4GL_2000_CUTOFF variable for dates that do not use a format string and that are 8 digits. Setting this variable to 1 causes Acu4GL to apply the 4GL_2000_CUTOFF logic for 8-character-long dates. The default value is 0 (off, false, no). This variable can also take values of 1 (on, true, yes).

Parent topic: Run-time Configuration Variables
Related information
4GL_2000_CUTOFF configuration variable


4GL_COLUMN_CASE configuration variable

This configuration variable causes Acu4GL to leave the case of the field names found in the XFD unchanged. Normally, all field names are converted to lower case by the Connector (except for Oracle, which converts all values to upper case), and all hyphens are converted to underscores.

Valid values are:

UNCHANGED | All field names are used unchanged when the database table is created. Be aware that hyphens are not converted to underscores in this situation. Most databases do not accept hyphens in column names, so the XFD must be modified by hand to replace hyphens with underscores
LOWER (default) | Field names are converted to lower case and hyphens are converted to underscores
Parent topic: Run-time Configuration Variables


4GL_COMMIT_COUNT configuration variable

The 4GL_COMMIT_COUNT variable sets the conditions in which Acu4GL issues an automatic COMMIT WORK operation. Valid values are:

0 (Default) | The run time system tracks the number of logical locks that are currently in effect. When the number of logical locks reaches zero, the run time system assumes that a transaction is complete and issues a COMMIT statement
n | When set to a nonzero value, the run time system tracks the number of WRITE, REWRITE, and DELETE operations, until the value of 4GL_COMMIT_COUNT is reached, at which time the run time system issues a COMMIT statement. The READ, START, and READ NEXT operations do not count toward this total, because the run time system is tracking data-altering operations rather than logical record locks. The disadvantage of this method is that when a COMMIT is issued, any record locks held by the run time system are released
-1 | No commit is issued by Acu4GL

When 4GL_COMMIT_COUNT is set to -1, the alternatives are:

  • Call your database query tool with COMMIT WORK or ROLLBACK WORK
  • Use the COBOL verbs COMMIT and ROLLBACK, available in ACUCOBOL-GT

    4GL_COMMIT_COUNT is set to -1 automatically when you use the transaction management facilities available in ACUCOBOL-GT.

A COMMIT WORK is, however, issued on exit from the run time system (for example, on execution of a STOP RUN).

Examples

4GL_COMMIT_COUNT 0

A commit is issued when no locks are held, either because all files that had locked records are closed, or because a COBOL COMMIT verb has been issued. This is the default value.

Note that some data sources lose the current row when a COMMIT or ROLLBACK is executed. For these data sources, setting 4GL_COMMIT_COUNT to 0 can slow performance.

4GL_COMMIT_COUNT n

A commit is issued after n operations. WRITE, REWRITE, and DELETE count towards n; READ, START, and READ NEXT do not.

4GL_COMMIT_COUNT  -1

No commit is issued by Acu4GL. When 4GL_COMMIT_COUNT is set to -1, the only way to perform a commit or rollback is to call your database query tool with COMMIT WORK or ROLLBACK WORK, or use the COBOL verbs COMMIT and/or ROLLBACK.

4GL_COMMIT_COUNT is set to -1 automatically when you use the transaction management facilities available in ACUCOBOL-GT. A COMMIT WORK is, however, issued on exit from the run time system (for example, on execution of a STOP RUN).

Note:
  • 4GL_COMMIT_COUNT can be set in the ACUCOBOL-GT runtime configuration file only
  • 4GL_COMMIT_COUNT is available only in the Acu4GL for DB2 interface
Parent topic: Run-time Configuration Variables


4GL_CONVERT_DATE_ZERO configuration variable

If your data uses dates as part of database keys, some database dates cannot be written as NULL or illegal values. To write data that includes NULL or illegal values, the Connector converts the NULL or illegal date values used in keys to a value of 01/01/01 when writing data to some databases. Unfortunately, the code would not make a similar conversion when reading the same record, and those records written with 01/01/01 were not found. This could easily result in writing a record that cannot be read or deleted. When 4GL_CONVERT_DATE_ZERO is set to the default setting CONVERTED, the Connector locates and returns those records written using the date 01/01/01. This functionality can be disabled by setting the variable to UNCHANGED.

Parent topic: Run-time Configuration Variables


4GL_DB_MAP configuration variable

This configuration variable lets you set one map at a time, by using FILE-PREFIX as a list of directories, each of which maps to a different database. Note that in this case "database" refers to "collection of tables" rather than distinguishing between, say, DB2 and Microsoft SQL Server.

The syntax of the value of 4GL_DB_MAP is:

directory = database

where directory is matched against the file specification, and database is used when a directory matches. For example, if you have two databases, data01 and data02, and have COBOL programs written that reference data files in /home/dataA and /home/dataB, you can set 4GL_DB_MAP as follows:

4GL-DB-MAP /home/dataA = data01
4GL-DB-MAP /home/dataB = data02

When the run time attempts to open a file with a directory specification of /home/dataA, the Connector uses the table in database data01.

By setting this variable to blank, all maps are reset to nothing, so no mapping is performed.

Currently, this feature is available with the Acu4GL for Microsoft SQL Server interface. Any special instructions are included in the section describing support.

The 4GL_USEDIR_LEVEL variable determines how many levels of directory information to use as part of a table name. 4GL_DB_MAP interacts with 4GL_USEDIR_LEVEL, in the following way:

  • 4GL_DB_MAP is tested first, to determine which database to search for the table
  • Then 4GL_USEDIR_LEVEL is used to change the final name of the table
Parent topic: Run-time Configuration Variables


4GL_EXTRA_DB_COLS_OK configuration variable

4GL_EXTRA_DB_COLS_OK allows the database table to have more columns than the COBOL program's corresponding file descriptor.

If the 4GL_EXTRA_DB_COLS_OK variable is set to True (on, yes), its default value, the number of columns in the database table do not have to match up with the number of fields in the COBOL program that is accessing the table. The database table can have more columns than the COBOL program references; however, the COBOL program may not have more fields than the database table.

Ensure that these extra columns are set correctly when new rows are added to the table. This is database-dependent. For example, under some databases, the columns should either have a default value or should allow NULL. Ensuring that the column value is set is important because the SQL generated by the Acu4GL interface does not reference the extra columns when inserting rows. This ACUCOBOL-GT runtime configuration file can also take values of False (off, no).

Note: Only Acu4GL for Microsoft SQL Server supports this variable.
Parent topic: Run-time Configuration Variables


4GL_FULL_DATA_TEST configuration variable

The ACUCOBOL-GT runtime configuration file variable 4GL_FULL_DATA_TEST lets you specify whether an entire field is tested for illegal data or if only the first byte is tested. The default value is False (0, off, no), meaning that only the first byte of data is tested. However, if set to True (1, on, yes), the entire field is tested for illegal data.

Parent topic: Run-time Configuration Variables


4GL_IGNORED_SUFFIX_LIST configuration variable

This variable is a space-delimited list of case-independent suffixes to ignore when opening Microsoft SQL Server tables or DB2 tables.

The standard syntax for MSSQL tables is

server.database.owner.table

with a dot (".") as the separator. This syntax causes the filename idx1.dat to be interpreted as "the table dat owned by the user idx1." By setting this variable (which must be set in the ACUCOBOL-GT runtime configuration file, and cannot be set via SET ENVIRONMENT), the Connector ignores the listed suffixes.

There can be up to 10 ignored suffixes (more than that are not kept internally, and are ignored.) The default value for this variable is dat.

Example

4GL_IGNORED_SUFFIX_LIST dat idx txt
Parent topic: Run-time Configuration Variables


4GL_ILLEGAL_DATA configuration variable

4GL_ILLEGAL_DATA determines how COBOL data considered illegal by the database is converted before being stored in the database.

The default value is NULL. This causes all illegal data (except key fields) to be converted to null before it is stored.

The value CONVERTED causes the following conversions to occur:

Illegal LOW-VALUES | Minimum possible value (0 or 99999...) Minimum possible date value (01/01/01)
Illegal HIGH-VALUES | Maximum possible value (99999...) Maximum possible date value (database dependent)
Illegal SPACES | Zero (or 01/01/01 for a date field)

Illegal data in key fields is always converted, regardless of the value of this variable.

Oracle Special Options

The following values for 4GL_ILLEGAL_DATA apply only to Oracle character fields:

KEY_MOD

If a key field contains LOW-VALUES in the first byte, the field is considered invalid. The default behavior is to set the field to the minimum possible value. For character fields, this would result in a single character with the hex value of 0x01 being inserted. (For fixed-length fields, Oracle would space pad the field.)

Setting 4GL_ILLEGAL_DATA to KEY_MOD results in only the first byte of an invalid key field being modified to the hex value of 0x01. The remainder of the field remains unchanged.

This value can be useful for users converting from versions prior to 6.2 in which the interface's functionality matched this behavior rather than the documented behavior.

PASS_THROUGH

Setting 4GL_ILLEGAL_DATA to PASS_THROUGH allows all key field and non-key field values to directly pass to Oracle after having trailing spaces removed for variable length fields. Any error detection on the fields is handled by the Oracle database itself.

Parent topic: Run-time Configuration Variables


4GL_JULIAN_BASE_DATE configuration variable

This variable sets the base date to be used for Julian date calculations. It is used in conjunction with the DATE XFD directive.

To define your own base date for Julian dates, set this variable to a date having the format YYYYMMDD.

The default value is set internally at 01/01/4713 BC. (Dates other than the default must be greater than 01/02/4713 BC.)

For example, suppose your COBOL program uses dates in the form of the number of days since 12/31/1899. If you want to store these dates in a database accessed by Acu4GL, you can set your DATE XFD directives to be $XFD DATE=JJJJJJ (make sure that the number of characters matches your date field). Then you should set the configuration variable 4GL_JULIAN_BASE_DATE to 18991231.

If you are using the run time intrinsic functions that work with Julian dates, set 4GL_JULIAN_BASE_DATE to December 31, 1600 using the Gregorian calendar.

Parent topic: Run-time Configuration Variables
Related information
DATE directive


4GL_USEDIR_LEVEL configuration variable

This variable provides a method of mapping filenames (with directory information) to table names. 4GL_USEDIR_LEVEL lets you use files of the same name, which would normally go into separate directories, as separate names in a single database. This variable determines how many levels of directory information to use as part of the table name.

  • If set to the default value of 0, all directory information is removed from the filename before it is used as a table name
  • When set to negative values, nothing is done differently
  • When set to a positive value, the number determines how much directory information to keep

For example, given the file /home/data1/gl/master.dat, the following values result in the given table name:

4GL-USEDIR-LEVEL | Final resolved name
0 | master.dat
1 | glmaster.dat
2 | data1glmaster.dat
3 or larger | homedata1glmaster.dat

This variable has an upper limit of 127 characters and is currently available with the Acu4GL for Microsoft SQL Server interface. Any special instructions are included in the section describing support.

The 4GL_DB_MAP configuration variable enables you to set one map at a time. 4GL_USEDIR_LEVEL interacts with 4GL_DB_MAP as follows.

  • 4GL_DB_MAP is tested first, to determine which database to search for the table
  • Then 4GL_USEDIR_LEVEL is used to change the final name of the table
Parent topic: Run-time Configuration Variables
Related information
4GL_DB_MAP configuration variable


4GL_WHERE_CONSTRAINT configuration variable

4GL_WHERE_CONSTRAINT lets you override any value given in the external variable A4GL-WHERE-CONSTRAINT. This ACUCOBOL-GT runtime configuration file variable can have a value with any length (limited only by machine memory). If a value is set in 4GL_WHERE_CONSTRAINT, any value in the external variable is ignored. For information on the external variable, see The WHERE Constraint.

Parent topic: Run-time Configuration Variables
Related information
The WHERE Constraint


DEFAULT_HOST configuration variable

If you are opening an existing file, most file systems linked into the run time system are searched for the named file. If, however, you are creating a new file, you must tell the run time system which file system to use. You accomplish this with the following ACUCOBOL-GT runtime configuration file variable:

DEFAULT_HOST filesystem

This variable designates the file system used for newly created files that are not individually assigned. If this variable is not given a value, the EXTFH file system is used.

Examples

DEFAULT_HOST DB2

means that all new files are be DB2 files unless individually assigned to another file system.

DEFAULT_HOST ORACLE

means that all new files are be Oracle files unless individually assigned to another file system.

Parent topic: Run-time Configuration Variables


FILE_TRACE configuration variable

This variable allows you to start file tracing without opening the debugger. Set this variable to a non-zero value to save information about all file OPENs, READs, and WRITES in the error file. The default is 0.

Parent topic: Run-time Configuration Variables


filename_HOST configuration variable

The filename_HOST variable can be used to assign a newly-created file to a file system. This ACUCOBOL-GT runtime configuration file variable is used to assign an individual data file to a file system. Any file so assigned uses the designated file system, and not the one specified by DEFAULT_HOST.

Substitute the base name of the file for filename. The name you substitute should not include any directory names and should not include a file extension.

Example

For example, if the file CUSTFILE were the only file you wanted to assign to the DB2 file system, and all other files were to be Oracle files, you could specify:

DEFAULT_HOST  DB2
CUSTFILE_HOST  ORACLE

in the ACUCOBOL-GT runtime configuration file.

The DEFAULT_HOST variable specifies the file system to be used for all files not specified by filename_HOST.

You can use DEFAULT_HOST and filename_HOST in combination to assign your new files in a default with exceptions manner. For example, the following directives:

DEFAULT_HOST DB2
afile_HOST ORACLE
bfile_HOST ORACLE

mean that all new files except afile and bfile is be assigned to DB2, and those two files are assigned to Oracle.

Now suppose myfile1a and myfile1b both reside in mydb1, and myfile2a and myfile2b both reside in mydb2. With the following XFD directives:

DEFAULT_HOST DB2
a-oracle-database mydb1
myfile1a-HOST oracle
myfile1b-HOST oracle
myfile2a mydb2.dbo.myfile2a
myfile2b mydb2.dbo.myfile2b
mydb2-HOST oracle

the run time system uses the Oracle interface for myfile1a, myfile1b, myfile2a, and myfile2b and finds all the tables in the correct database. When the COBOL program opens myfile2a, the run time system translates that name to mydb2.dbo. myfile2a looks at the basename to determine the file system to use (mydb2). It then looks for mydb2-HOST to determine which file system to send the file requests to.

Parent topic: Run-time Configuration Variables
Related information
DEFAULT_HOST configuration variable


XFD_DIRECTORY configuration variable

XFD_DIRECTORY tells the run time system the name of the directory that contains the XFD files built by the compiler. The default value is the current directory.

Example

To tell the run time system that the XFDs are stored in the directory /usr/inventory/dictionaries, enter the following:

xfd–directory   /usr/inventory/dictionaries
Note: This variable is ignored if you have specified a search path for XFD files using the XFD_PREFIX configuration variable. XFD_PREFIX extends the functionality of XFD_DIRECTORY.

For information about the directive that tells the compiler where to put the XFDs, see the -Fx compiler option. Unless you have moved the XFD files, you should use the same value in XFD_PREFIX (or for XFD_DIRECTORY) that you used with the -Fx compiler option.

Parent topic: Run-time Configuration Variables
Related reference
XFD_PREFIX configuration variable
CREATEXFD XFD directive


XFD_MAP configuration variable

XFD_MAP tells the run time system to associate certain filenames with a particular XFD. This enables you to use one XFD for many different files. You can use XFD_MAP to add or replace the existing value, depending on the setting of the XFD_MAPS_RESETS configuration variable.

The XFD_MAP variable has this syntax:

XFD_MAP   [pattern = base-xfd-name]  ...

where pattern consists of any valid filename characters and may include "*" or "?". These two characters have special meanings in the pattern:

* | matches any number of characters
? | matches a single occurrence of any character

For example:

CUST???? | matches CUST0001 and CUSTOMER; does not match CUST001 or CUST00001
CUST* | matches all of the above
CUST*1 | matches CUST001 and CUST0001 and CUST00001; does not match CUSTOMER
*OMER | matches CUSTOMER; does not match CUST001 or CUST0001

Note that XFD_MAP cannot be read from the ACCEPT FROM ENVIRONMENT statement.

Parent topic: Run-time Configuration Variables
Related information
XFD_MAP_RESETS configuration variable


XFD_MAP_RESETS configuration variable

This ACUCOBOL-GT runtime configuration file variable determines whether setting the XFD_MAP adds to or replaces the existing value.

Valid values are:

Value | Effect when setting the ACUCOBOL-GT runtime configuration file variable
"0" (off, false, no) | Adds new value patterns to the end of the existing value
"1" (on, true, yes) the default | Replaces the existing value with a new value

This variable may be useful if you need to include multiple XFD_MAP lines in an ACUCOBOL-GT runtime configuration file and want to avoid setting and resetting the variable. When multiple lines exist, all patterns are used in the order they are listed.

Parent topic: Run-time Configuration Variables
Related information
XFD_MAP configuration variable


XFD_PREFIX configuration variable

When this ACUCOBOL-GT runtime configuration file variable is assigned a value, it is used to locate the XFD file, and the variable XFD_DIRECTORY is ignored. XFD_PREFIX enables you to define a specific series of directories to search for XFD files, rather than indicating only one. The run time system searches each directory in the order specified until an XFD file matching the name of the desired file is found and then assumes that is the correct file.

Therefore, when using the XFD_PREFIX variable, be aware that the run time system:

  • Searches each named directory and not its subdirectories
  • Stops searching once a matching file name is found, even if other files of the same name are located in a different directory later in the series
  • Does not validate that the file specifications (such as key or record size parameters) of the XFD file match those in the COBOL program. Be sure the correct file you want to use is in the path specified

You can specify a directory path that contains embedded spaces if you surround the path with quotation marks. You separate entries using a semi-colon (;). For example:

XFD_PREFIX C:\"Sales Data";C:\Customers

You can specify up to 4096 characters for this variable.

Note: The default for XFD_PREFIX is empty. If this variable is set to any other value, the XFD_DIRECTORY (in which you specify only one directory) is ignored.
Parent topic: Run-time Configuration Variables
Related information
XFD_DIRECTORY configuration variable


Performance and Troubleshooting

These topics provide guidelines for improving system performance. Also included is an alphabetical listing of the error messages that can occur during the compilation of your program.

  • Performance Issues
  • Setting External Variables
  • Compiler Errors
  • Compiler Warnings
  • Retrieving Runtime Errors
  • Questions and Answers
Parent topic: Acu4GL Version 10.2.0 User's Guide


Performance Issues

Adding a relational database management system (RDBMS) brings significant complexity to any computer system. A few key guidelines may help to improve the performance of the system and prevent problems as the database grows.

  • Guidelines
Parent topic: Performance and Troubleshooting


Guidelines

The following sections describe some areas for you to consider as you prepare your database and your COBOL program.

  • The WHERE Constraint
Parent topic: Performance Issues


The WHERE Constraint

The Acu4GL WHERE constraint is an external variable that gives the developer some control over the data searches that result from database queries. It can help to improve performance in some situations. This topic describes purpose of the WHERE constraint and shows how it is implemented.

COBOL data processing is based on keyed READ operations following a positioning operation. Records are read until the key value being processed changes. Because traditional COBOL data processing is based on a B+ tree file system, the overhead for such operations is relatively minor.

RDBMS data processing introduces a new level of complexity to data processing. The database's query optimizer receives the SQL query for the COBOL operation being performed and then builds a working set of data that satisfies that query. Because the database optimizer has many different possible execution methods, this can result in poor performance if the optimizer chooses a query execution path that is less than optimal.

Performance degradation may also result from the fact that queries generated by COBOL operations result in unbounded index queries. Unbounded queries are generated because COBOL positioning operations (Start Not Less Than and Start Not Greater Than) provide only one of the bounding conditions for the working set, instead of both an upper and lower boundary.

As an example, consider the case in which an application needs to process all items in a warehouse on aisle 17, shelf 8, and bin 2. If each of these items is a field in a key, the COBOL program might generate the following query for a READ operation:

Note: The following example applies to the Acu4GL for Oracle product. The SQL generated differs based on the interface.
SELECT * FROM warehouse_items WHERE
   aisle = 17 and
   shelf = 8 and
   bin = 2
ORDER BY aisle ASC, shelf ASC, bin ASC;

This query achieves the desired result but has one problem. For the COBOL program to end its processing, it must read a record that has a new value for bin. The COBOL application has no way of specifying an upper boundary for the read operation, so when all rows of data from bin 2 have been read, the Connector attempts to read the next record by generating the following query:

SELECT * FROM warehouse_items WHERE
   aisle = 17 and
   shelf = 8 and
   bin > 2
ORDER BY aisle ASC, shelf ASC, bin ASC;

This query causes the database query optimizer to gather all records pertaining to items on the remainder of shelf 8 to build its working set. This is excessive from the COBOL application's point of view, because the COBOL program needs only the first record of the working set to determine that it has finished processing.

This problem can be even more serious if the application is processing the last bin on a shelf. Because there are no more bins on that shelf, the query would drop down a level and generate the following:

SELECT * FROM warehouse_items WHERE
   aisle = 17 and
   shelf > 8
ORDER BY aisle ASC, shelf ASC, bin ASC;

This would select all items on the remainder of that aisle of the warehouse, which could be a very large working set if each aisle had 130 shelves.

The database query optimizer normally does not build the entire working set if it has been properly tuned, but instead performs INDEXED READS to process the query. This means that the query optimizer traverses an index tree to retrieve the records, much as COBOL index files do, as opposed to using combinations of indexes and sort and merge operations.

It can be helpful to influence precisely which information is to be returned. If the precise scope of the record processing performed by the read operations is known at compile time (or before the query is executed), information retrieval can be more finely tuned.

Acu4GL provides a method by which the COBOL programmer can provide additional information to the database query optimizer by providing more specific selection information to the Connector. This selection information is added to the WHERE clause of the SQL queries generated by the Connector. This can be particularly useful in providing upper boundaries to queries being generated, with the result that the working set is smaller.

Upper boundaries can be provided on the key segments for a select, or any other selection criteria needed to constrain the working set to just the desired subset of rows. This additional information is added to generated queries with the AND condition. It is not possible for the application developer to specify a larger working set than would otherwise have resulted. The developer may only constrain the working set to a smaller subset.

  • To use the WHERE constraint from COBOL
Parent topic: Guidelines
Related information
To use the WHERE constraint from COBOL


To use the WHERE constraint from COBOL

The following steps are required for using the WHERE constraint.

  1. Declare an External Variable

    To make use of WHERE constraints from COBOL, the application must declare an external variable for communication with the Acu4GL interface. This variable is declared as follows:

    77  a4gl-where-constraint  pic x(32750) external.
  2. Modify Your COBOL Procedures

    Your COBOL application should move the information that you want added to the WHERE clause to the new external variable before a COBOL positioning operation such as START or READ is performed. The additional constraint is then applied to any SQL read query performed on that file until a new positioning operation is performed.

    The additional query information is also stored in the Connector's cursor cache, so that if the same read conditions occur in later processing, the existing closed cursor can be reused with new bind variables instead of being regenerated.

    Be sure to fill the external variable before a positioning operation (START or READ). The WHERE constraint affects only READ NEXT operations preceded by a positioning operation. The WHERE constraint does not affect a READ NEXT that was not preceded by a positioning operation (such as a READ NEXT without a START immediately after opening a file).

Example

In your COBOL program you include this statement:

Move "ftest_key > 3 and ftest_key < 6" to
   A4GL_WHERE_CONSTRAINT.
Inspect A4GL_WHERE_CONSTRAINT replacing trailing spaces by
   low-values.
START FTEST-FILE KEY NOT LESS FTEST-KEY.

These results occur:

CURSOR 0:
SELECT *,ROWID FROM ftest WHERE (ftest_key1_seg1 = ? AND
ftest_key1_seg2 >= ?) AND (ftest_key > 3 and ftest_key < 6)
ORDER BY ftest_key1_seg1 ASC, ftest_key1_seg2 ASC;
CURSOR 1:
SELECT *,ROWID FROM ftest WHERE (ftest_key1_seg1 > ?) AND
(ftest_key > 3 and ftest_key < 6) ORDER BY ftest_key1_seg1 ASC,
ftest_key1_seg2 ASC;

Limitations

  • WHERE constraints added by the COBOL program may not be portable between databases.
  • The application may specify conditions of such complexity that they confuse the database query optimizer, resulting in poor performance. Be sure to examine the results of the optimizer trace facilities to ensure optimal performance.
  • Verify the COBOL application is not sending information that results in a syntax error that is not detected until run time.
  • The WHERE constraint should reference only columns in the primary table.
  • If users have different configurations at different sites, so that some files can be vision files at one site, but Acu4GL tables at another site, then the WHERE-CONSTRAINT can be difficult to use. This happens because after the WHERE-CONSTRAINT is used, it is marked empty so it won't be used again. However, if a file is a vision file, the WHERE-CONSTRAINT is not used, and might be used for the next file. For example: At site 1, files AA and AB are both SQL Server tables. At site 2, file AA is a vision file, and AB is a SQL Server table. If the COBOL program sets a WHERE-CONSTRAINT that would work with file AA, then at site 2, that WHERE-CONSTRAINT will instead be used for file AB, which will fail.
Parent topic: The WHERE Constraint


Setting External Variables

When using Acu4GL, file status variables and declarations may not be able to provide enough information to determine the cause of the error and the recommended resolution.

Setting external variables can provide additional information in troubleshooting situations. For example, if the database returns an error that does not map to one of the standard COBOL errors (record locked, duplicate key, etc.), the external variables F-ERRNO, F-INT-ERRNO, F-INT2-ERRNO and F-ERRMSG contain additional information. Typically, F-ERRNO is E_INTERNAL (which has a value of 15). F-INT-ERRNO and F-INT2-ERRNO are the error values returned by the database, and F-ERRMSG points to a text message returned by the database.

Add the following EXTERNAL declarations to working-storage:

01  F-INT-ERRNO   BINARY-LONG  SIGNED 	EXTERNAL.
01  F-INT2-ERRNO  BINARY-LONG  SIGNED	 EXTERNAL.
01  F-ERRMSG      POINTER             	EXTERNAL.
77  F-ERRNO       BINARY-SHORT SIGNED 	EXTERNAL.
Note: Not all errors return textual messages.
Parent topic: Performance and Troubleshooting


Compiler Errors

The errors listed below could occur when you compile with the -Fx compiler option. In some cases, the XFD cannot be built until you remove the error condition. (XFD errors do not, however, prevent the object code from being generated.) For information about XFDs, see the XFDs section.

For detailed information about a particular error message, see Compiler Error Messages.

Bad picture for DATE: keyname
Data missing from key segment keyname
Directive word too long: keyname
GROUP expected after USE
Missing '=' in XFD directive
Missing field name after WHEN
xxx: unknown XFD directive
Value should be a name: xxx
Value should be numeric: xxx
Value should be a literal: xxx
Variable file name requires FILE directive
WHEN variable xxx not found in record
  • Bad picture for DATE: keyname
    The PICTURE must be six or eight bytes in length, either alphanumeric or numeric with no sign.
  • Data missing from key segment keyname
    This error occurs when some part of the named key cannot be placed in the XFD; the XFD cannot be generated in this situation.
  • Directive word too long: keyname
    With one exception, the words contained in an XFD directive, including field names, cannot exceed 30 characters. The value of a WHEN XFD directive may consist of up to 50 characters.
  • GROUP expected after USE
    The USE GROUP XFD directive must include both words.
  • Missing '=' in XFD directive
    The NAME XFD directive requires an equal ("=") sign. The WHEN XFD directive requires a comparison operator.
  • Missing field name after WHEN
    A valid field name, or the word "OTHER", must be specified with the WHEN XFD directive.
  • xxx: unknown XFD directive
    The Compiler did not recognize the XFD directive you used. The xxx is the XFD directive found.
  • Value should be a literal: xxx
    This error occurs when the item to the right of an "=" should be a literal, and it isn't. The xxx in the message is the value found. A literal is either a quoted string or a numeric integer.
  • Value should be a name: xxx
    This error occurs when the item to the right of an "=" should be a name, and it isn't. For example, it would be an error to use a quoted string with the NAME XFD directive: $XFD NAME=some text. The xxx in the message is the value found.
  • Value should be numeric: xxx
    This error occurs when the item to the right of an "=" should be numeric and it isn't. The xxx in the message is the value found.
  • Variable file name requires FILE directive
    This message occurs when the Compiler cannot assign a name to the .xfd file, because the ASSIGN phrase for the file names a variable file name.
  • WHEN variable xxx not found in record
    This happens if you have a WHEN XFD directive that mentions a variable that doesn't exist in the record.
Parent topic: Performance and Troubleshooting
Related reference
CREATEXFD XFD directive
Appendix D. Compiler Error Messages


Bad picture for DATE: keyname

The PICTURE must be six or eight bytes in length, either alphanumeric or numeric with no sign.
Parent topic: Compiler Errors


Data missing from key segment keyname

This error occurs when some part of the named key cannot be placed in the XFD; the XFD cannot be generated in this situation.

This usually occurs because of filler. For example:

01  my-record.
    03  my-key.
        05  filler            pic xx.
        05  field-1           pic xx.

If my-key is declared as a record key, this error occurs because the area of the key described by filler is not included in the XFD.

Resolution:

To correct this error, ensure that every character that is part of the key is included in some field that is part of the XFD. Use an XFD to give a field name to each filler, to ensure that fillers are included:

 01  my-record.
     03  my-key.
$xfd name=myfiller
         05   filler            pic xx.
         05   field-1           pic xx.
Parent topic: Compiler Errors


Directive word too long: keyname

With one exception, the words contained in an XFD directive, including field names, cannot exceed 30 characters. The value of a WHEN XFD directive may consist of up to 50 characters.
Parent topic: Compiler Errors
Related information
WHEN directive


GROUP expected after USE

The USE GROUP XFD directive must include both words.
Parent topic: Compiler Errors
Related information
USE GROUP directive


Missing '=' in XFD directive

The NAME XFD directive requires an equal ("=") sign. The WHEN XFD directive requires a comparison operator.
Parent topic: Compiler Errors
Related information
NAME directive
WHEN directive


Missing field name after WHEN

A valid field name, or the word "OTHER", must be specified with the WHEN XFD directive.
Parent topic: Compiler Errors
Related information
WHEN directive


xxx: unknown XFD directive

The Compiler did not recognize the XFD directive you used. The xxx is the XFD directive found.

Resolution:

Check for a typographical error.

Parent topic: Compiler Errors


Value should be a literal: xxx

This error occurs when the item to the right of an "=" should be a literal, and it isn't. The xxx in the message is the value found. A literal is either a quoted string or a numeric integer.
Parent topic: Compiler Errors


Value should be a name: xxx

This error occurs when the item to the right of an "=" should be a name, and it isn't. For example, it would be an error to use a quoted string with the NAME XFD directive: $XFD NAME=some text. The xxx in the message is the value found.
Parent topic: Compiler Errors


Value should be numeric: xxx

This error occurs when the item to the right of an "=" should be numeric and it isn't. The xxx in the message is the value found.
Parent topic: Compiler Errors


Variable file name requires FILE directive

This message occurs when the Compiler cannot assign a name to the .xfd file, because the ASSIGN phrase for the file names a variable file name.

Resolution:

In this case, you must use a FILE XDF directive to name the .xfd file.

Parent topic: Compiler Errors
Related information
FILE directive


WHEN variable xxx not found in record

This happens if you have a WHEN XFD directive that mentions a variable that doesn't exist in the record.
Parent topic: Compiler Errors
Related information
WHEN directive


Compiler Warnings

The compiler may also generate the following warning messages. For detailed information about a particular error message, see Compiler Error Messages in the ACUCOBOL-GT documentation.

xxx not unique in first 30 characters
Field xxx causes duplicate database data
  • Field xxx causes duplicate database data
  • xxx not unique in first 30 characters
Parent topic: Performance and Troubleshooting


Field xxx causes duplicate database data

The warning informs you of a special database situation that is not advisable. The XFD builds and the interface operates correctly.

This warning means that your record definition should be restructured. Your current definition is set up in such a way that:

  1. You have overlapping key fields, and
  2. Both keys must be represented in the database as separate items.

Acu4GL handles this situation by keeping the overlapping keys updated simultaneously, so that they always have the same value. However, the warning alerts you that you have the same data represented twice in the database. This is dangerous, because someone at the site might access the database via SQL and accidentally change only one of the keys.

Here's an example of the problem and a description of how to correct it (the example assumes that both key-1and key-2 have been declared as keys):

01  order–record.
    03  key–1.
        05  field–a                  pic x(5).
        05  field–b                  pic 9(5).
        05  key–2
            redefines field–b        pic x(3).

This example generates the warning message.

Because key-2 is a key, it must also be represented in the database. It doesn't correspond exactly to any other data field, so it must be entered as a separate column in the database.

In the COBOL view of the file, key-1and key-2 overlap. But the requirements of database storage force the same data (known to COBOL as field-b) to be physically represented twice in the database. Any updates to the data from any COBOL program correctly updates both columns. Updates from outside of this COBOL program carry no such guarantee.

Resolution

In this example, you can correct the situation by breaking field-b into two columns, so that key-2 corresponds exactly to another data field:

01  order–record.
    03  key–1.
        05  field–a                        pic x(5).
        05  field–b.
            07  field-b1                   pic x(3).
            07  field-b2                   pic 9(2).
        05  key–2
            redefines field–b              pic x(3).
Parent topic: Compiler Warnings


xxx not unique in first 30 characters

This message occurs if a field name is not unique within the first 30 characters. The xxx is the name found.

Resolution:

You can either change the field name or apply the NAME XFD directive.

Parent topic: Compiler Warnings
Related information
NAME XFD directive


Retrieving Runtime Errors

You can determine the meanings of your database error codes by referring to the database documentation. Here are methods for storing the complete error code and some helpful text that describes it.

You can retrieve a secondary error code by using selected runtime options, or by calling the library routine C$RERR, described in C$RERR. Note that you can pass two parameters to C$RERR for interface errors (rather than just one). The first parameter retrieves the code; the second parameter retrieves a message associated with the error condition.

Note: For Oracle users: Because 9D takes two bytes and Oracle secondary errors can be four bytes, the first parameter should be PIC x(6).

You can retrieve runtime errors in three ways, as described in these topics:

  • Retrieving Messages with -x runtime option
  • Retrieving Messages with the Debugger
  • Retrieving Messages with C$RERR
Parent topic: Performance and Troubleshooting


Retrieving Messages with -x runtime option

At run time, if you specify an error file and use the -x option, the runtime puts the extended error code and some text associated with the error into the error file. (When run against an Informix database, you'll see three levels of error codes in the file: ACUCOBOL-GT error, Informix database error, and ISAM error.) A value of zero for any level means no error at that level.

Example

runcbl -le errfile -x myprogram

Where:

-l | Causes the contents of the runtime configuration file to be included in the error output.
e (or -e) | Causes the error output to be placed in the file named immediately after the option.
errfile | The user-specific name of the error file
-x | Causes the secondary error numbers to be included.
myprogram | The name of your object file

The error file will look like this:

*** File system error value = 3 ***
*** Dictionary (.xfd) file not found***
File error 9D,03 on filename
Dictionary (.xfd) file not found
Parent topic: Retrieving Runtime Errors


Retrieving Messages with the Debugger

Occasionally you may receive an error message that means syntax error. (In Informix, for example, this is error code 201.) You can examine the error file and determine the cause of the problem if you receive this error code. You'll need to rerun the program, specifying the options shown below, and turning on Trace Files (TF) when execution begins:

runcbl -dle errfile -x yourprog

The -d turns on the debugger. The source code does not need to be compiled in debug mode. After you press Enter, you will be at the debugger screen. Enter the following command:

tf n

where n is a number from 1 to 9. The higher the number you enter, the more debugging information you receive. See Debugger and Utilities for more information on using the debugger.

FILE TRACE ON is echoed on the screen. Now enter the following command:

g

You are now running your program normally. Proceed until you encounter the error condition, and then exit. Your error file contains the error information described in Method One, above, and also contains the SQL queries that the Acu4GL product constructed. Examining these queries can help to determine the cause of the syntax error. Please contact Technical Services if you need help.

Parent topic: Retrieving Runtime Errors


Retrieving Messages with C$RERR

You might want to separate the error codes and their associated text, and store them in variables. The variables can then be displayed to the screen or handled in whatever way you deem appropriate.

You saw an example of the usage of C$RERR in the sample program in Getting Started. The simplified example shown below uses the library routine C$RERR with two parameters to retrieve the complete error code (first parameter) and its associated text (second parameter).

DATA DIVISION.
   .
   .
working-storage section.
01  file-status                   pic xx.
01  error-status.
    03 primary-error              pic x(2).
    03 secondary-error            pic x(40).
01  error-text                    pic x(40).

PROCEDURE DIVISION.
   .
   .
get-file-err.
call "C$RERR" using error-status, error-text, status-type.
display "FILE ERROR:", primary-error.
display "DATABASE ERROR:",  secondary-error.
display error-text.
accept omitted.
stop run.
Here's an example of the output you might get from this:

FILE ERROR: 9D
DATABASE ERROR: 1608

For Informix

Remember that the extended code can consist of two parts (database error and ISAM error), separated by a comma. In the example shown below, we use the library routine C$RERR with two parameters to retrieve the complete error code (first parameter) and its associated text (second parameter). Then we use the UNSTRING verb to separate the code into its parts:

DATA DIVISION
   .
   .
   .
working-storage section.
01  file-status                          pic xx.
01  error-status.
    03 primary-error                     pic x(2).
    03 extended-error                    pic x(40).
01  secondary-error                      pic x(10).
01  isam-error                           pic x(40).
01  error-text                           pic x(40).

PROCEDURE DIVISION
   .
   .
   .
get-file-err.
   call "C$RERR" using error-status, error-text.
   unstring extended-error delimited by "," into
      secondary-error, isam-error.

   display "FILE ERROR:", primary-error.
   display "DATABASE ERROR:", secondary-error.
   display "ISAM ERROR:", isam-error.

   display error-text.
   accept omitted.
   stop run.
Here's an example of the output you might get from this:

FILE ERROR: 9D
DATABASE ERROR: 350
ISAM ERROR: 108
Index already exists on column.

An additional method, also for Informix only, allows you to take the Informix error number and use the "finderr" syntax to discover error information. More information on this syntax can be found in your Informix documentation. The syntax is:

finderr xxxxx

Where xxxxx is the Informix error number.

Parent topic: Retrieving Runtime Errors


Questions and Answers

Here are some answers to common questions that can apply to any relational database management system (RDBMS) data source supported by the Acu4GL™ family of interfaces.

I can't seem to get Acu4GL to create the files in my database or ODBC data source. They keep coming up as indexed files.
Check to see that the DEFAULT_HOST variable is set in the runtime configuration file or the environment. Setting DEFAULT_HOST in the environment overrides the setting in the runtime configuration file.

Enter one of the following commands, depending on your operating system.

For UNIX systems: runcbl -vv

For Windows systems: wrun32 -vv

to make sure that the version number of the Acu4GL interface for your RDBMS is reported. This tells you that the Acu4GL product has been installed successfully.

Note: In Windows environments, if -vv does not return the Acu4GL product information, make sure the runtime has the name you used and is the first so-named executable on the PATH, and that the .dll is in the same directory. If you are running Acu4GL for Sybase, and -vv does not return the Sybase Acu4GL product information, make sure the linked runtime has the name you used and is the first so-named executable on the PATH. If you cannot locate a runtime that displays a Sybase Acu4GL product version number using -vv, you must create one by re-linking the runtime. If you must do that, make sure that USE_SYBASE is set to 1 in the file filetbl.c before you relink.
Can I use both an RDBMS or ODBC data source and Vision at the same time?
Yes, you can. In the configuration file, set DEFAULT_HOST to the file system you want the runtime to use automatically. Then, for select files, assign them to an alternate file system with the variable filename_HOST. For example, to put CUSTFILE into a specified RDBMS and everything else into Vision, you would add:
DEFAULT_HOST   Vision
CUSTFILE_HOST  name_of_file_system

where name_of_file_system is one of the following: Oracle , MSSQL, ODBC, Sybase, Informix, or DB2.

How can I find out what an error message is?
If you run your application with the -x option, you will receive extended error numbers that include those returned by your RDBMS or ODBC application.
Note: For Informix, two types of errors are returned: the Informix error and the ISAM error. For Oracle, the error code must include five digits. If your error code does not already include five digits, you must add leading zeros to complete this requirement. For example, if your error code is code number 150, the syntax for this option would be OERR ORA 00150.

If you have sent the errors to an output file with the -e option, the runtime will also attempt to include the text that explains the errors. You can also use the C$RERR library routine. You can also retrieve error codes from within your COBOL program. See the example in Retrieving Runtime Errors.

Do my eXtended File Descriptor (XFD) files have to be in the same directory as my object files?
No. You can instruct the compiler to put the XFD files in an alternate directory with the -Fo compiler option. Then at run time, make sure you have the configuration variable XFD_PREFIX set to include that same directory. See Compiler and Runtime Options for information on the -Fo option and the XFD_PREFIX configuration variable.
Why aren't my KEYs being retrieved in the correct order?
If your KEY field is numeric or alphanumeric, you may have illegal data in the field. For example, if you've used LOW-VALUES or HIGH-VALUES to mark control records, those values are considered invalid and can cause the records containing them to be retrieved in an unexpected sequence.

To enable special values such as these to be processed, use the BINARY XFD directive in front of the key field. This allows data of any classification to be processed. Either designate an individual field as binary, or specify USE GROUP, BINARY in front of a group of fields.

The method of storing variables declared as binary is database-specific. For example, for Oracle databases, variables declared as binary are stored as raw fields. Refer to your database documentation for information specific to your data source or RDBMS.

Is it possible to use the same XFD file for data files with different names, if they all have the same structure? This would be useful when I create several customer files that use the same record definitions.
At run time, it is possible to use a single XFD for files that have different names. For example, suppose a site has customer files that have identical structures but different names (such as CUST0001, CUST0002, and CUST0003). It's not necessary to have a separate XFD for each file, as long as their record definitions are the same. The individual files can all be mapped to the same XFD via the ACUCOBOL-GT runtime configuration file variable XFD_MAP. Here's how it works.

Suppose your COBOL application has a SELECT with a variable ASSIGN name, such as "customer-file". This variable assumes different values (such as CUST0001 and CUST0002) during program execution.

Before compiling the application, you would use the FILE XFD directive to provide a base name for the XFD. Suppose you provide "CUST" as the base. The Compiler would then generate an XFD named cust.xfd. (The Compiler always converts XFD names to lower case.)

To ensure that all customer files, each having a unique name, will use this same XFD, you make this entry in your configuration file:

XFD_MAP  CUST* = CUST

The asterisk (*) in the example is a wildcard that matches any number of characters. The extension .xfd should not be included in the map. This statement would cause the XFD cust.xfd to be used for all files whose names begin with CUST.

The XFD_MAP variable has this syntax:

XFD_MAP   [pattern = base-xfd-name]  ...
where pattern consists of any valid filename characters and may include "*" or "?". These two characters have special meanings in the pattern:
* matches any number of characters
? matches a single occurrence of any character
For example:
CUST???? matches CUST0001 and CUSTOMER;

does not match CUST001 or CUST00001

CUST* matches all of the above
CUST*1 matches CUST001 and CUST0001 and CUST00001;

does not match CUSTOMER

*OMER matches CUSTOMER;

does not match CUST001 or CUST0001

The XFD_MAP variable is read during the open file stage of any Connector interface used with the run-time system.
I'm unsuccessful in trying to create a table in MSSQL Server, and when I check the trace log, I find the following "File Error:9k":
 ssinit_connection sss
Trying to open a connection to server
MyBadServer
 report_status called from 1176
 [1] 08001 17 – [DBNETLIB]SQL Server does not exist or access denied.
[2] 01000 53 – [DBNETLIB]ConnectionOpen (Connect()).sssssss

Where MyBadServer is the value set in the configuration file for A-MSSQL-DEFAULT-CONNECTION.

You might be using the wrong server name in the A-MSSQL-DEFAULT-CONNECTION variable. One way you can verify the server name is by following the steps below. This method is useful if you don't have the client tools for SQL Server installed.
  1. Create a new ODBC Datasource for SQL Server.
  2. When prompted for the server name, select your local server from the drop-down list of available servers.
  3. Connect to this server using ODBC Administrator.

This will provide you with the name of the server you need to use in the A-MSSQL-DEFAULT-CONNECTION variable.

Parent topic: Performance and Troubleshooting


Appendix A: Acu4GL for Informix Information

These topics provide you with the information you need that is specific to Acu4GL® for Informix.

  • Getting Started with Acu4GL for Informix
  • Configuration File Variables
  • Informix Performance
  • Technical Tips
  • Limits and Ranges
  • Runtime Errors
  • Common Questions and Answers
Parent topic: Acu4GL Version 10.2.0 User's Guide


Getting Started with Acu4GL for Informix

Important: Micro Focus does not provide the Informix libraries along with the Acu4GL® product. The Informix Libraries are necessary for providing a proper connection between Informix and extend products. If you do not already possess them, please consult your database documentation or database vendor for information on obtaining these libraries.

You need to order Embedded ESQL for C. If you are using the version 5.1 series, you need the version 5.1 0.UC1.client libraries. If you are using the version 7.2 series or higher, you need the version 7.2x or higher.

To find out whether you can use a client/server environment to communicate with other database versions, contact IBM.

Follow the directions provided in your Informix documentation for installation of the Informix libraries, or, depending on what your arrangement is with Informix, contact Informix Technical Support for any questions you may have.

Before you begin using Acu4GL for Informix on a new system, you must install and configure the Informix RDBMS. Your Informix vendor provides installation instructions.

Several steps that must be performed before you begin using Acu4GL for Informix on a new system are:

  • Install and configure the Informix RDBMS.
  • Install Acu4GL for Informix.
  • Designate a database.
    Note:

    Acu4GL for Informix does not support ANSI-mode databases.

  • Prepare and compile your COBOL program.

Your Informix vendor provides installation instructions for the Informix RDBMS.

Please refer to the file SERVERS_7.2 in the release directory of your Informix distribution for more information about version 7.2, 7.3, and above.

  • Installation Preparation
  • Installation Steps
  • Designating a Database
  • Filename Translation
Parent topic: Appendix A: Acu4GL for Informix Information


Installation Preparation

The Informix Acu4GL product is an add-on module that must be linked with the ACUCOBOL-GT® runtime system. (Note that your versions of Acu4GL and the runtime must be the same.) For this reason, you’ll need a C compiler to install Acu4GL. Acu4GL is compatible with Informix versions 5.x1, 7.2, 7.3, 9 and later.

Note: Please make sure that you have obtained the proper Informix libraries for your version of Informix. See Getting Started with Acu4GL for Informix for information on these libraries.

Acu4GL is shipped using either TAR or CPIO format, depending on the type of machine you have. The label on the product medium tells you which format has been used.

Create a directory on your machine to hold the product and then type one of the following commands:

tar xfv device

or

cpio -icvBd < device

In either case, device is the appropriate hardware device name (for example, /dev/rdiskette or /dev/rmt0).

Note: Sites using Texas Instruments System 1500 should add an uppercase “T” to the cpio options (“-icvBdT”).
Parent topic: Getting Started with Acu4GL for Informix


Installation Steps

To install the Acu4GL for Informix product, perform the following steps:

Step 1: Install Informix

Install the Informix RDBMS and make sure it is operational. Micro Focus does not provide this product. Make sure you install the libraries in the appropriate directories, based on the Informix documentation.

We recommend that you obtain Interactive SQL (ISQL) or dbaccess if possible. This is not mandatory, but it will give you quite a bit of flexibility. ISQL allows you to do database work outside of COBOL, including interactive queries and reports. ACUCOBOL-GT’s standard file utility, vutil, cannot be used on Informix tables.

One way to test the installation of Informix is to access Interactive SQL and examine the stores database.

Step 2: Create a new runtime

Create a new runtime system that includes the Informix Acu4GL product.

Note:

In the following directions, the term “runtime system” refers to the runtime shared object on systems, where the ACUCOBOL-GT runtime is a shared object, and to runcbl on other systems, where the runtime is static. The runtime is a shared object on the following systems: AIX 5.1 and later, HP-UX 11 and later, and Solaris 7 and later. To check, look at the contents of the “lib” subdirectory of your ACUCOBOL-GT installation. If the files “libruncbl.so” or “libruncbl.sl” reside in that directory, the runtime is a shared object on your system.

2a. Backup

Make a backup copy of your newly installed runcbl or libruncbl.so.

2b. Create a “Makefile.inf” file

The “inf_inst” program can be run to create a “Makefile.inf” file.

Note:

Please read the reference section at the start of the “inf_inst” script for the latest information regarding the “Makefile.ini” and database or platform differences.

  1. First, create the Makefile.inf file by entering the following command:
    sh inf_inst

    in the …/install directory.

  2. Next, you are asked to enter the directory where ACUCOBOL-GT is installed. Type the information and press Enter.
  3. After that, you are asked which version of Informix you have installed. You have four choices:
    • For version 5.x1, enter “5”.
    • For version 7.2 32-bit, enter “7”.
    • For version 7.3 or for version 9, enter “3”.
    • For version 7.3 64-bit, enter “4”.
  4. Once you have entered the version, add the names of your C routines (“.o”), if any, to the line starting with “SUBS=”.
Note:

The “if_inst” script generates a makefile that may require slight modifications. Make sure that the FSI_LIBS line in your makefile is correct.

Now you are ready to relink your ACUCOBOL-GT runtime.

2c. Link the runtime system

  1. Make sure you are in the directory containing the ACUCOBOL-GT runtime system. Then, at the UNIX prompt, enter the following command:
    make clean

    to ensure that you have a clean directory in which to build your runtime.

  2. Now enter the following command:
    make -f Makefile.inf

    or

    makerun

    This compiles “sub.c” and “filetbl.c” and then links the runtime system.

2d. Verify the link

  1. Enter the following command:
    runcbl -vv
  2. Check to see that the version of the Informix Acu4GL is reported to your screen. This will verify that the link was successful.
  3. If no Acu4GL version number is displayed, this means that something isn’t set up properly.
    • Check filetbl.c to make sure that USE_INFORMIX is set to “1” (Step 2b).
    • Then check Makefile for accuracy (see Step 2c), and relink (Step 2d).

Shared libraries

If you have relinked the ACUCOBOL-GT runtime and receive an error message of this type when you try to execute it:

Could not load library; no such file or directory

Can’t open shared library . . .

this may mean that your operating system is using shared libraries and cannot find them. This can occur even if the shared libraries reside in the same directory in which you are currently located.

Different versions of the UNIX operating system resolve this issue in different ways, so it is important that you consult your UNIX documentation to resolve this error.

Some versions of UNIX require that you set an environment variable that points to shared libraries on your system. For example, on an IBM® RS/6000® running AIX® 4.1, the environment variable LIBPATH must point to the directory in which the shared libraries are located. On HP/UX, the environment variable that must be set to point to shared libraries is SHLIB_PATH. On UNIX SVR4, the environment variable is LD_LIBRARY_PATH.

Be sure to read the system documentation for your operating system to determine the appropriate way to locate shared libraries.

A second way to resolve this type of error is to link the libraries into the runtime with a static link. Different versions of the C development system use different flags to accomplish this link. Please consult the documentation for your C compiler to determine the correct flag for your environment.

Step 3: Copy runcbl to the correct directory

If the runtime is a statically linked runcbl, copy the new executable to a directory mentioned in your execution path. This file needs to have execute permission for everyone who will be using the compiler or runtime. This step is not necessary when the runtime system is a shared library.

The ACUCOBOL-GT license file for the runtime (“runcbl.alc”) and the license file for the Acu4GL product to Informix (“runcbl.ilc”) must be copied into the same directory as the runtime executable.

If you rename your runtime executable, be sure to rename your license files to use the same base name, with the extensions unchanged. For example, if you rename your runtime to be “myprog”, then the license file for the Acu4GL product for Informix should be renamed “myprog.ilc”, and the license file for the runtime should be renamed “myprog.alc”.

The remaining files can be left in the directory in which they were unloaded.

Step 4: Compile the sample program

  1. If you are using the C-shell, enter the command rehash.
  2. Now try compiling and running the sample program with the following commands:
    ccbl   -Zd -Fx  demo.cbl
runcbl demo.acu
Note:

You can also run the sample program using runtime flags, if necessary.

Parent topic: Getting Started with Acu4GL for Informix


Designating a Database

Use the configuration variable DEFAULT_HOST to establish Informix as your file system:

DEFAULT_HOST  informix

Next, select the particular Informix database to be accessed by your COBOL application. Identify this database to the runtime system via the DATABASE configuration variable:

DATABASE  database-name

The database you choose might be one that has been in use at the site for some time and already contains data, or it might be a new, blank database that has just been created and named.

Note:

The Acu4GL product for Informix allows you to create a file with an OPEN OUTPUT statement, just as you can create Vision indexed files. The Informix equivalent of a Vision file is a table, not a database. You need to have an existing database for your Informix tables, just as you must have an existing directory for Vision files.

To create a new, blank database, use the tools available from Informix.

Parent topic: Getting Started with Acu4GL for Informix


Filename Translation

As you prepare to work with Acu4GL for Informix, you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together.

When the ACUCOBOL-GT compiler generates XFD files, it uses lowercase letters to name the XFD file. In addition, the compiler changes hyphens to underscores when naming the XFD file.

Through configuration variables, the runtime translates the file name in the COBOL program into the filename that is passed to the open() function in the runtime. The open() function determines which file system to pass the request to, but does not change the name of the file. For additional information on configuration variables, see Configuration Variables.

At this point, Acu4GL for Informix translates the file name to lowercase letters and changes hyphens to underscores. This “new” name is the one that Acu4GL for Informix will use in the future for references to the database table.

Parent topic: Getting Started with Acu4GL for Informix


Configuration File Variables

These topics list the runtime configuration file variables that are specific to Acu4GL for Informix. Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in Compiling and Runtime Configuration.

See DEFAULT_HOST configuration variable and DATABASE for important information on setting these variables.

  • A_INF_DUPLICATE_KEY configuration variable
  • A_INF_NO_TRANSACTION_ERROR configuration variable
  • A_INFORMIX_ERROR_FILE configuration variable
  • DATABASE
  • INF_LOGIN
  • INF_PASSWD
  • INFORMIX_TYPE configuration variable
  • MAX_CURSORS
Parent topic: Appendix A: Acu4GL for Informix Information


A_INF_DUPLICATE_KEY configuration variable

This variable determines how Acu4GL for Informix handles the processing of alternate keys with duplicates. When reading on an alternate key with duplicates, it is possible that not all records will be returned. The probability of this scenario increases if the direction of the read changes (for example, switching from read next to read previous). This generally occurs when:

  • The data set was imported from an external file
  • The database has undergone large amounts of modifications, resulting in the re-use of row IDs
  • The initial query returned the record set in a way such that the records are not in row ID order

Three potential values can be set for this variable:

Note: These settings can affect performance. If you need assistance, see your Database Administrator.

Zero (0)

If this variable is set to zero (0), no ROWID is added to the SELECT statements for reading in a forward direction, but a ROWID is added to SELECT statements for reading in a backward direction if the file is not a VIEW.

Note: We don’t recommend setting this variable to zero (0), because ROWIDs may not be in ascending order. This method can be used if the direction in which the application reads records does not change, but it is unknown if this will work for all situations. We provide this method for backwards compatibility only.

One (1)

If this variable is set to one (1), a ROWID is added to the ORDER BY clause of all SELECT statements reading tables on an alternate key that allow duplicates. A ROWID is not added if the file is a VIEW. This assures a predictable ordering of keys and is the default setting.

Two (2)

If this variable is set to two (2), the primary key segments are added to the ORDER BY clause of all SELECT statements reading tables or VIEWs on an alternate key that allow duplicates.

Parent topic: Configuration File Variables


A_INF_NO_TRANSACTION_ERROR configuration variable

This configuration file variable allows you to enable or disable the 9D/ 255 - Not in transaction Informix error. The default setting for this variable is “1” and does not allow this message to be displayed. If this variable is set to zero (0), the 9D/ 255 error is returned if a stop run caused a commit or rollback to be sent to Acu4GL for Informix

Parent topic: Configuration File Variables


A_INFORMIX_ERROR_FILE configuration variable

This configuration file variable allows you to map errors using a text file to supplement the default method of providing errors. By adding the name of the file that contains the actual error mapping to A_INFORMIX_ERROR_FILE, database-specific errors are mapped to COBOL errors.

Note:

Several messages related to COBOL I/O cannot be supplemented.

Example

A sample syntax for this configuration file variable would be:

A_INFORMIX_ERROR_FILE=INFerrs

where:

INFerrs is a file of a specified format containing a mapping of database-specific errors to COBOL errors. One such entry might be:

1 DUPLICATE_RECORD
Parent topic: Configuration File Variables


DATABASE

DATABASE specifies the name of the specific database to be accessed. You cannot open any database files until you have set this variable.

Example

DATABASE stores

indicates the stores database is to be accessed.

Note:

If you choose, you can set the DATABASE variable in the startup script for the session.

Parent topic: Configuration File Variables


INF_LOGIN

INF_LOGIN indicates the user name under which you want to connect to the database system. This is an optional variable. If INF_LOGIN and INF_PASSWD are not set, a default login is performed. If these variables are set, there must be a matching UNIX login name and password.

Example

To connect to the database with the user name MYNAME, you would specify:

INF_LOGIN  MYNAME

in the configuration file.

See also: INF_PASSWD

Parent topic: Configuration File Variables


INF_PASSWD

The variable INF_PASSWD should be set to the password assigned to the database account associated with the user name specified by INF_LOGIN. If INF_LOGIN and INF_PASSWD are not set, a default login is performed. If these variables are set, there must be a matching UNIX login name and password.

Example

For example, if the account with the user name has the associated password “CW021535”, specify

INF_PASSWD  CW021535

in the configuration file or the environment.

See also: INF_LOGIN

Parent topic: Configuration File Variables


INFORMIX_TYPE configuration variable

This configuration variable is needed only when using Acu4GL for Informix. It specifies whether Informix-Online or Informix-SE (standard Edition) is used as the database engine. Valid values are ONLINE, ON-LINE, O (for Informix-Online), SE, or S (for Informix-SE).

Parent topic: Configuration File Variables


MAX_CURSORS

MAX_CURSORS is the number of cursors (parameterized queries) in Acu4GL’s cursor cache. The default value is 100. The range is 1–100. If you set this variable to a number less than the maximum of 100, you may reduce the number you specify in the Informix system parameter OPEN_CURSORS by a like amount. The value of Informix’s OPEN_CURSORS should exceed MAX_CURSORS by at least 7.

Example

To allow your application to use up to 23 cursors, specify

MAX_CURSORS   23

in the configuration file.

Parent topic: Configuration File Variables


Informix Performance

Informix databases include many advanced concepts, such as parallel queries, multi-processor support, and virtual processors.

To increase performance for large sites on powerful multi-processor machines, Informix has changed some of the database default configurations, moving to a “cost based” optimization for its default query mode. This means that the query optimizer for Informix OnLine makes its decisions about optimization based purely on costs, without considering translation isolation mode. With this default, OnLine does not give preference to index scans (nested-loop joins and key base reads) over table scans (other join methods).

The behavior can be especially problematic in the case of benchmark testing. When the table is created, a mass insert of the records is performed on the database table. The indexes are created for the table, but the database has not yet gathered information about the distribution of data in the underlying table, or the usefulness of a particular index. The lack of statistical information within the database regarding the data in the tables results in possible poor decisions on the part of the query optimizer. The optimizer is unable to determine that an index exists that best matches the requirements of the query and will choose an alternate execution approach that will cause drastically poorer performance of the benchmark application.

Example

As an example of this problem, we will examine performance times from ACUCOBOL-GT’s “iobench” program.

Test | Informix 5.1 SunOS 4.1.3 | Informix 7.2 Intel 486 System 5.4 | Informix 9
Write Sequential | 1.2 | 1.8 | 3.33
Sort Sequential | 3.3 | 3.4 | 4.30
Load Index 1 | 13.8 | 16.1 | 24.74
Read Index 1 | 19.5 | 732.9 | 1085.90
Update Index 1 | 4.5 | 2.8 | 56.33
Load Index 2 | 24.2 | 29.6 | 28.33
Update Index 2 | 13.6 | 10.0 | 56.83
Total | 80.1 | 796.6 | 1259.66

The times between the two machines and databases that the benchmark were run on are comparable for all times except for the read operation. The read operation shows a significant performance degradation.

Isolating the problem

To isolate the source of the problem, you can insert into your COBOL program a call to Acu4GL’s utility program sql.acu. Before the Read benchmark test, we inserted the call:

CALL "sql.acu" USING SQL-COMMAND.

In the working-storage section, SQL-COMMAND is defined as follows:

77 SQL-COMMAND      pic x(75) value "SET EXPLAIN ON".

This call instructs the Informix database engine to print out the query optimizer’s execution plan to a file in the current directory called “sqexpain.out”. Here is a sample of the optimizer’s output:

QUERY:
------
SELECT *, rowid FROM idx1 WHERE idx_1_key >= ? ORDER
BY idx_1_key ASC

Estimated Cost: 2
Estimated # of Rows Returned: 3
Temporary Files Required For: Order By

1) informix.idx1: SEQUENTIAL SCAN

    Filters: informix.idx1.idx_1_key >= '0000000900'

This output shows that the Informix query optimizer is performing a sequential scan on the table for each set of start/read operations. The optimizer is also making use of a temporary file during processing to sort the information in key order, as described by the “ORDER BY” clause. This clause is necessary to ensure that the COBOL application receives the records in the required sequence.

Problem resolutions

To correct the problems with the query optimizer, you can take one of several approaches:

  1. Override the Informix database parameter in the database configuration files.
  2. Override the new database parameter for a given user session.
  3. Provide the query optimizer with more information so that it can choose a more efficient method of returning data.

Method 1: Configuration files

The Informix database engine reads a system configuration file each time it is started. Two configuration files apply: the file “onconfig.std” is used as a template for creating database configuration files when new databases are created; the “onconfig.<database>” file is the configuration file for a given database. In the database configuration file, locate the line

OPTCOMPIND    2    # To hint the optimizer

Modify this line to read

OPTCOMPIND    0    # To hint the optimizer

The OPTCOMPIND configuration parameter helps the optimizer choose an appropriate join method for your application. A setting of “0” indicates that when appropriate indexes exist, the optimizer chooses index scans (nested-loop joins), without considering the cost, over table scans (sort-merge joins or hash joins).

This new setting takes effect the next time you shut down and restart the ONLINE database engine. The altered setting is then applied to all operations with the query optimizer. To ensure that this change applies to newly created databases, you should modify the “onconfig.std” file.

Method 2: Altering a user session

You can modify how the query optimizer executes queries on an individual basis by setting a UNIX environment variable in the user’s environment. This environment variable should be set before executing your COBOL application. It cannot be set with the COBOL “SET CONFIGURATION” or “SET ENVIRONMENT” verbs. Use the syntax “setenv OPTCOMPIND 0” or “OPTCOMPIND=0; export OPTCOMPIND”, depending on which shell is being used.

Method 1 and method 2 resulted in the following “iobench” times:

Test | Informix 5.1 SunOS 4.1.3 | Informix 7.2 Intel 486 System 5.4 | Informix 9
Write Sequential | 1.2 | 1.8 | 3.25
Sort Sequential | 3.3 | 3.3 | 4.33
Load Index 1 | 13.8 | 16.6 | 24.92
Read Index 1 | 19.5 | 22.4 | 47.23
Update Index 1 | 4.5 | 4.1 | 5.57
Load Index 2 | 24.2 | 22.9 | 28.19
Update Index 2 | 13.6 | 10.9 | 6.22
Total | 80.1 | 81.9 | 119.71

We can verify the changes that were made by examining the output of the query optimizer. The above test resulted in these results:

QUERY:
------
SELECT *, rowid FROM idx1 WHERE idx_1_key >= ? ORDER BY idx_1_key ASC
Estimated Cost: 4
Estimated # of Rows Returned: 3
1) informix.idx1: INDEX PATH
    (1) Index Keys: idx_1_key
        Lower Index Filter: informix.idx1.idx_1_key >= '0000000900'

Both method 1 and method 2 above are useful if you are processing new data. They have the drawback, however, that they permanently constrain the execution paths that the query optimizer has to choose from. To allow the query optimizer the greatest flexibility in working with data that exists day-to-day on your system, you will want to choose the next method.

Method 3: Provide the query optimizer with information

Database tables that are in use on a frequent basis can benefit from providing the query optimizer with more information. This allows the optimizer to work at its best in returning information from the database. You provide the optimizer with information of the tables by issuing the following SQL command:

UPDATE STATISTICS HIGH FOR TABLE <tablename>;

Executing this command updates the Informix system database catalog tables SYSTABLES, SYSCOLUMNS, SYSINDEXES, and SYSDISTRIB. The optimizer uses this data to determine the best execution path for queries. The database server does not update this statistical data automatically, however. Statistics are updated only when you issue an UPDATE STATISTICS statement.

Informix recommends that you run UPDATE STATISTICS in high mode for all columns that head an index. For the fastest execution time of the UPDATE STATISTICS statement, you must execute one UPDATE STATISTICS statement in the high mode for each such column. For each multi-column index, run UPDATE STATISTICS in low mode for all of its columns.

You may want to perform the UPDATE STATISTICS on the entire table periodically as shown above, instead of just on the indexes.

For more information on optimizing Informix performance and general maintenance issues, please refer to your Informix-OnLine documentation.

Parent topic: Appendix A: Acu4GL for Informix Information


Technical Tips

Switching file systems

Switching file systems Each time a file is opened, the file system identified by the filename_HOST configuration variable (if present) or the DEFAULT_HOST variable is used. You can change the value of these variables in your code by including:

SET ENVIRONMENT "filename_HOST" TO filesystem

or

SET ENVIRONMENT "DEFAULT_HOST" TO filesystem

just before you open the file. SET ENVIRONMENT thus enables you to change file systems during the execution of your program. The filesystem value for Informix is “Informix”. The value for Vision is “Vision”.

If you change to the Informix file system in the midst of a program, be sure to specify the database to be used:

SET ENVIRONMENT "DEFAULT_HOST" TO "INFORMIX"

SET ENVIRONMENT "DATABASE" TO "STORES"

Note that the database cannot be changed if there are tables open in the active database. Be sure to close all tables before making a change.

Remember that SET ENVIRONMENT is not the typical way to specify a file system. Normally the file system is designated in the runtime configuration file and is not changed in the COBOL program.

Parent topic: Appendix A: Acu4GL for Informix Information


Limits and Ranges

The following limits exist for the Informix-SE file system:

  • Maximum indexed key size: 120 bytes
  • Maximum number of fields per key: 8

The following limits exist for the Informix-OnLine file system:

  • Maximum indexed key size: 256 bytes
  • Maximum number of fields per key: 16

With the Acu4GL product for Informix, only one database can be open at a time. Within this one database, a maximum of 100 tables can be open at the same time. You can set this table maximum to a lower number via the runtime configuration variable MAX_CURSORS.

The following Informix data types are not currently supported:

  • INTERVAL
  • BLOB
  • FLOAT
  • SMALLFLOAT

Acu4GL for Informix supports the following data types; conversions between COBOL and database formats are as shown:

COBOL to | INFORMIX
  • PIC X
  • PIC X(n) (n<=255)
  • PIC X(n) (255 < n <=32739)
  • CHAR
  • VARCHAR
  • LVARCHAR
  • PIC 9
  • PIC 99X
  • PIC 999
  • PIC 9999
SMALLINT
  • PIC 9(5)
  • PIC 9(6)
  • PIC 9(7)X
  • PIC 9(8)
  • PIC 9(9)
INTEGER
All other PIC 9’s | DECIMAL
INFORMIX to | COBOL
INTERGERX
  • PIC S9(10) or
  • PIC S9(9)
  • COMP-4
SMALLINT
  • PIC S9(5) or
  • PIC S9(4)
  • COMP-4
DECIMAL (6,2) | PIC (4)V99
MONEY(4) | PIC (2)V99
SERIAL | PIC 9(9)
DATE
  • PIC 9(6) or
  • PIC 9(8)
DATETIME
  • PIC 9(12) or
  • PIC 9(14)
VARCHAR (max, min) | PIC X(max)
LVARCHAR (max, min) | PIC X(max)

When the VAR_LENGTH directive is applied to a field, it is converted to a VARCHAR data type if the field is up to 255 bytes in size, or the LVARCHAR data type if the field is larger than 255 bytes, up to a maximum of 32,739 bytes, in size.

Opening a file I-O exclusive doesn’t hold lock on Informix. This is a limitation on the way the Informix Acu4GL product works. Since we do not do any actual operations on the table except to get information about it, Informix does not tell us the file is locked. Users should get a lock condition when they do a read with lock.

Performing error handling on the read/write will yield a 99 record locked on any read operation performed — even if the file is open for input.

Other limits are described in Limits and Ranges of the ACUCOBOL-GT documentation.

Parent topic: Appendix A: Acu4GL for Informix Information


Runtime Errors

This topic lists the Acu4GL error messages that could occur during execution of your program. Performance and Troubleshooting provides information on compile-time errors and also provides several methods for retrieving runtime errors.

An explanation and a recommended recovery procedure follow each message. Runtime errors will have this format:

9D/nn

The 9D indicates a file system error and is reported in your FILE STATUS variable. The xx is a secondary, or extended, error code. You can retrieve an extended error code by using selected runtime options or by calling the library routine C$RERR. Note that you can pass two parameters to C$RERR for interface errors (rather than just one). The first parameter retrieves the code; the second parameter retrieves a message associated with the error condition. This process is explained in detail on the following pages.

When the extended error code is greater than 99, the error is explained in the Informix documentation. Error codes less than 99 are explained here:

01 DATABASE is not defined in the environment

You must specify which database you are using. Use the DATABASE configuration variable.

02 Attempt to open more than one database at once

This can happen if you specify a database, open a file, then specify a different database with SET ENVIRONMENT, and try to open another file. Informix does not allow files to be open from two databases simultaneously.

03 Dictionary (.xfd) file not found

The dictionary file for one of your COBOL files cannot be located. Be sure you have specified the correct directory via your XFD_PREFIX configuration variable. You may need to recompile with the “-Fx” option to re-create the dictionary. See Compiler and Runtime Options for information on compiler options.

04 Corrupt dictionary file

The dictionary file for one of your COBOL files is corrupt and cannot be read. Recompile with “-Fx” to re-create the dictionary.

05 Too many fields in the key

(more than 8 for Informix-SE, more than 16 for Informix-OnLine)

Check your key definitions and redefine the key that is illegal, and then recompile with the “-Fx” option.

There are additional 9D extended error numbers; these have values of 100 or more. Often they have two parts that are separated by a comma (such as 9D 350,108). These are Informix error codes. The first part is the database error; the second part (if any) is the ISAM error.

Informix database error numbers are typically greater than 200. ISAM errors, when present, fall between 100 and 199.

Note:

See your Informix documentation regarding the finderr syntax for more information.

06 Mismatched dictionary file

The dictionary file (.xfd) for one of your files conflicts with the COBOL description of the file FD. The xx indicates a tertiary error code that is defined by the host file system. You can determine the exact nature of the mismatch by referring to the host system’s error values.

The tertiary error code may have any of these values:

  • 01 – mismatch found but exact cause unknown (this status is returned by the host file system)
  • 02 – mismatch found in file’s maximum record size
  • 03 – mismatch found in file’s minimum record size
  • 04 – mismatch found in the number of keys in the file
  • 05 – mismatch found in primary key description
  • 06 – mismatch found in first alternate key description
  • 07 – mismatch found in second alternate key description

The list continues in this manner for each alternate key.

255 Not in transaction

A stop run has caused a commit or rollback to be sent to Acu4GL for Informix. By default, this message is disabled. If you would like to enable this message, set the A_INF_NO_TRANSACTION_ERROR variable to zero (0).

Parent topic: Appendix A: Acu4GL for Informix Information


Common Questions and Answers

This topic contains some questions and answers specific to Acu4GL for Informix.

Question

How do I create new databases?

Answer

You have two choices: (1) you can use an Informix product, such as ISQL, to create a new database, or (2) you can use the program sql.acu provided with your Acu4GL product.

To use the sql.acu utility to create an empty database and grant access privileges to other users, enter the following command:

runcbl sql.acu

The program pauses to accept an SQL command. Enter the following:

CREATE DATABASE database-name
Note: If you want to use the transaction logging facility available in ACUCOBOL-GT, you must enable it for the database you are creating. The precise SQL command depends on the Informix engine you are using, as shown below.

For Informix-OnLine, enter the following command to use transaction logging:

CREATE DATABASE database-name WITH LOG;

For Informix-SE, enter the following command to use transaction logging:

CREATE DATABASE database-name WITH LOG IN
   '/acct/f1992/acct_log';

If you are using an Informix database with transactions enabled, you must use ACUCOBOL-GT’s transaction management capabilities. (Either use START TRANSACTION and COMMIT, or compile with -fs, or use the sql.acu program to issue BEGIN WORK and COMMIT.) Using a transaction-enabled database without ACUCOBOL-GT’s transaction management capabilities results in the records not being locked and can generate error messages.

The program pauses to accept an SQL command. Now enter the following:

GRANT DBA TO PUBLIC

Then press Enter again to exit the program.

The database name may be up to ten characters and must contain only letters, digits, and underscores. The first character must be a letter.

The statement GRANT DBA TO PUBLIC gives the Database Administrator access privileges to all other users.

Question

Is it possible to use both Informix-OnLine and Informix-SE on the same machine?

Answer

Yes. You’ll need to tell the runtime which database engine to use. You do this by setting the environment variable SQLEXEC as shown here:

Informix-OnLine
     SQLEXEC =  ${INFORMIXDIR}/lib/sqlturbo
Informix-SE
     SQLEXEC =  ${INFORMIXDIR}/lib/sqlexec

Setting SQLEXEC tells the Informix utility programs and the ACUCOBOL-GT runtime which engine to access. This variable must be set before you execute the runtime. Only one engine (either OnLine or SE) can be used for any given execution of the runtime.

INFORMIXDIR is an environment variable that you must set to the location of your Informix product.

Question

What files do I need to link my C routines into Acu4GL?

Answer

From your ACUCOBOL-GT runtime medium you need:

  • sub.c
  • sub85.c
  • filetbl.c
  • config85.c
  • sub.h
  • libruncbl.a
  • libvision.a
  • libacuterm.a
  • clntstub.o

If you are using AcuServer™, instead of linking clntstub.o, see the relinking instructions in your AcuServer User's Guide.

From your Acu4GL medium, you need all of the following that are present:

  • infemb7.o - for version 7.2
  • infemb73.o - for version 7.3
  • infemb.oo - for version 5.1
  • inf.o
  • cur.o
  • * libsql.a
  • * libgen.a
  • * libos.a
  • * libasf.a
  • * netlib.a

* These files are provided by Informix and should be located in the appropriate Informix directory.

Instructions for linking are given in Installation Steps.

Question

I could not find the secondary error number for a 9D in the documentation. What does the number mean?

Answer

The errors fall into three categories:

01 – 99 are Acu4GL codes and are described in Runtime Errors.

100 – 199 are ISAM errors and are explained in Informix manuals.

200 and up are Informix database errors and are explained in Informix manuals.

Question

Can the Acu4GL for Informix product support a full date/time format?

Answer

The finest time granularity that Informix will support is one hundredths of a second. To achieve this, you must be sure the code is correct in the DATE directive and specify a date-format-string in your COBOL application, as opposed to just a date.

Question

Are there any ACUCOBOL-GT library routines that do not work with, or would not make sense to use with Acu4GL for Informix?

Answer

Yes. There are two ACUCOBOL-GT library routines that either don’t work with or do not make sense to use with Acu4GL for Informix: C$COPY and C$RECOVER.

Parent topic: Appendix A: Acu4GL for Informix Information


Appendix B: Acu4GL for Microsoft SQL Server

These topics provide information specific to Acu4GL for Microsoft SQL Server.

  • Microsoft SQL Server Concepts Overview
  • Installation and Setup
  • Filename Translation
  • Supported Data Types for SQL Server
  • Configuration File Variables
  • Using the Database Table
  • Table Locking
  • Stored Procedures
  • Limits and Ranges
  • Runtime Errors
  • Common Questions and Answers
Parent topic: Acu4GL Version 10.2.0 User's Guide


Microsoft SQL Server Concepts Overview

This quick overview of some basic design concepts underlying the Microsoft SQL Server (MSSQL) Database Management System (RDBMS) helps to interface your COBOL program to it.

Servers

An MSSQL server is one copy of the database engine executing on a computer. A server has a name, and when a program wants to access a database controlled by that server, the program asks for a connection to the server by name. Multiple servers, controlling different databases, can be executing on a single machine. The default name that MSSQL gives to a server is localhost; refer to the A_MSSQL_DEFAULT_CONNECTION configuration variable for further details on how to connect your program to one or more servers.

Table Ownership

Table names in MSSQL have the form database.owner.table_name. Within MSSQL, if you are the owner of a given table, you can refer to it as just table_name. If you are not the owner, you must refer to it with the owner of the table as a prefix; thus, different owners can have tables of the same name. However, this is not true when you use the Acu4GL for MSSQL interface.

The Acu4GL interface works a little differently: it automatically determines the owner name used to reference a table. It is therefore essential that there are not multiple tables with the same name in a single database, even though the tables have different owners. If there are such multiple tables, the interface does not necessarily find the correct one, and no diagnostic is issued.

Table names include dots (.) as separators. Because of this, you must make sure there are no extensions on COBOL file names that could be converted to table names. For example, for a COBOL file named IDX1.DTA, the Connector attempts to open a table DTA with owner IDX1. You can avoid this problem either by renaming your COBOL file in your source program or by using a configuration file variable to map the file name to an allowable file name, such as:

IDX1.DTA  IDX1

In the above example, IDX1.DTA is the name in the ASSIGN clause of the file's SELECT statement.

If you map your file name to a new name, drop the extension to form the new name. The compiler uses the base file name — without the extension — to create the eXtended File Descriptor (XFD) file name IDX1.XFD. XFDs are explained in detail in XFDs. The run time system needs to locate this file. But if you've mapped the file name to something completely different (such as MYFILE), the run time looks for an XFD file named MYFILE.XFD. So you would have to remember to change the name of IDX1.XFD to MYFILE.XFD in the XFD directory. Dropping the extension when you map the name prevents having to perform this extra step.

Refer to 4GL_IGNORED_SUFFIX_LIST configuration variable for an alternate method of removing file extensions.

Security

Security is implemented in the MSSQL RDBMS. A user is required to log in to the RDBMS before any file processing can occur. Acu4GL provides both a default and a user-configurable method for implementing this; refer to Setting up the User Environment for further details on how to supply login details.

Generally, it is best for someone with database administrator (DBA) privileges to create and drop the tables, allowing others only the permissions to add, change, or delete information contained in them.

See the Microsoft SQL Server documentation for more details on DBA privileges.

Parent topic: Appendix B: Acu4GL for Microsoft SQL Server
Related information
A_MSSQL_DEFAULT_CONNECTION configuration variable
4GL IGNORED SUFFIX LIST configuration variable
XFDs
Setting Up the User Environment


Installation and Setup

The following section covers the client setup required before you begin using Acu4GL for Microsoft SQL Server (MSSQL) on a new system. The Microsoft SQL Server RDBMS must be installed and configured prior to this, and must be at least version 6.5.

You will also be required to install some stored procedures as part of the client installation. For that you will need something such as Microsoft SQL Server's Query Analyzer or SQL Server command-line tools to run the query that installs the stored procedures.

Note: The default sort order for MSSQL is case-independent. Make sure that this is what you really want when you install the server. The Acu4GL connector uses the sort order as installed and cannot change its behavior to do case-dependent ordering if that is not what the server uses.

First you must install the files from the Micro Focus installation media onto the client machine. Then follow the instructions below for the server machine. Final setup steps on the client machine complete the installation.

Be sure to use the 64-bit libraries with a 64-bit run time system and 64-bit Acu4GL for MSSQL, and the 32-bit libraries with a 32-bit run time system and 32-bit Acu4GL for MSSQL.

Perform the following steps to set up Acu4GL on a new system:

  • Installing the Server and Client Machine
  • Setting Up a User Login
  • Setting Up the User Environment
  • Designating the Host File System
Parent topic: Appendix B: Acu4GL for Microsoft SQL Server


Installing the Server and Client Machine

The Acu4GL interface for MSSQL is an add-on module. The installation includes a .DLL or .so file that is detected at run time. It is not necessary to relink the run time system.

Typically, the setup is one of a client machine using a Acu4GL connector to access an SQL database on a separate server; however, your SQL server and your client can be on the same machine. The Acu4GL interface can be executed on a machine that is running any supported Windows or Linux platform.

See To Install Acu4GL for Microsoft SQL Server for details on client and server configuration, regardless of how you are set up.

  • To install Acu4GL for Microsoft SQL Server
Parent topic: Installation and Setup


To install Acu4GL for Microsoft SQL Server

Note: Your Microsoft SQL Server can be installed on a separate server, or on the same machine as your client. See the Microsoft SQL Server help for details on how to configure the relevant communications.
  1. Install a supported version of Microsoft SQL Server.

    You must install and configure Microsoft SQL Server, version 6.5 or later, on the Windows or Linux server machine before you install Acu4GL for MSSQL on the client machine. Follow the installation instructions from the vendor.

  2. Copy ms_inst.cmd (Windows) or ms_inst.sh (Linux/UNIX) from the install sub-directory of your Micro Focus product installation directory to a directory on the server.

    This is the batch file supplied by Micro Focus that creates the stored procedures necessary for using Acu4GL.

  3. Execute the batch file using the following command:

    ms_inst LockDatabase

    where LockDatabase is the database you want to use for the internal lock tables; this does not need to be an existing database, as one will be created, if required, in the next step. However, you must ensure the required Acu4GL users have write access to this database.

    Executing this command produces a ms_inst.sql file.

  4. Execute the contents of this file (ms_inst.sql) using one of the appropriate database tools (such as SQL Query Analyzer or the SQL Server Management Studio on Windows, or the SQL Server command-line tools on Linux).

    When complete, the stored procedures necessary for the MSSQL connector are installed.

This completes the setup on the server machine.

Note: If you are updating from an earlier version of Acu4GL, be sure to install the new stored procedures. Stored procedures are always updated in such a way that they are compatible with older versions of the product, so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software. Your new version of Acu4GL for MSSQL may not run properly without the corresponding stored procedures.

It can be difficult to maintain multiple copies of stored procedures; therefore, we recommend that you continue to create the stored procedures in the same database. If your installation does not permit this, you do have the flexibility to create the stored procedures elsewhere. However, to facilitate maintenance of the stored procedures, we recommend that you create as few databases as possible.

Parent topic: Installing the Server and Client Machine


Setting Up a User Login

For Acu4GL for MSSQL to be able to communicate with the SQL Server, you must supply a valid user login that has access to the database that you are reading from and writing to. The user login must also have write access to the database in which you installed the stored procedures earlier.

You can set up either one general user login for all Acu4GL users or a login for each individual user. To set up a user login, you must have DBA privileges for the SQL Server; see the Microsoft SQL Server documentation for more information on setting up user logins.

Parent topic: Installation and Setup


Setting Up the User Environment

The previous step spoke of the need to use a valid user login. Once you have those details, you need to set them in your user environment by adding the values to the variables mentioned below.

To set up your user environment to use Acu4GL, you must do the following:

  • Set the A_MSSQL_LOGIN and A_MSSQL_PASSWD variables, either in your environment or in the ACUCOBOL-GT runtime configuration file. Alternately, set the configuration variable A_MSSQL_NT_AUTHENTICATION to TRUE (Windows only). For security reasons, it is best to set the password variable from your COBOL program by asking the user to enter a password and then executing:
    SET ENVIRONMENT "A_MSSQL_PASSWD" TO user-entry
  • Make a personalized copy of the ACUCOBOL-GT runtime configuration file and populate it with configuration variables to suit your requirements; see Configuration File Variables for more information. Ensure the configuration file is in effect when you run your Acu4GL application.
Parent topic: Installation and Setup
Related reference
Configuration File Variables


Designating the Host File System

If you are opening an existing file, all file systems linked into the run time system are searched for the named file. If, however, you are creating a new file, you must tell the run time system which file system to use. You accomplish this with one of the following ACUCOBOL-GT runtime configuration file variables:

DEFAULT_HOST filesystem

or

filename_HOST filesystem

DEFAULT_HOST Variable

Use the DEFAULT_HOST variable to designate the file system to be used for newly created files that are not individually assigned. For example:

DEFAULT_HOST MSSQL

means that all new files are MSSQL tables unless otherwise specified by the second ACUCOBOL-GT runtime configuration file variable, filename_HOST.

filename_HOST Variable

Use the filename_HOST variable to assign an individual data file to a file system. Any file so assigned uses the designated file system and not the one specified by DEFAULT_HOST. The syntax is:

filename_HOST filesystem

where filename is the file name, without any extension, named in the ASSIGN TO clause of your SELECT statement. For example:

myfile_HOST MSSQL

means that myfile is under the MSSQL file system.

You can use these ACUCOBOL-GT runtime configuration file variables in combination to assign your new files in a default with exceptions manner; for example, this set of entries:

DEFAULT_HOST DB2
afile_HOST MSSQL
bfile_HOST MSSQL

means that all new files except afile and bfile are assigned to DB2, and those two files are assigned to MSSQL.

You can also change the values of these variables during program execution by including in your code:

SET ENVIRONMENT "filename_HOST" TO filesystem

or

SET ENVIRONMENT "DEFAULT_HOST" TO filesystem

This enables you to change file systems during the execution of your program. This is not the typical way to specify a file system; normally it is designated in the ACUCOBOL-GT runtime configuration file and is not changed in the COBOL program.

Note: The Acu4GL interface to MSSQL allows you to create an MSSQL table with an OPEN OUTPUT statement, just as you can create indexed files. The MSSQL equivalent of an indexed file is a table, not a database. You must create a database for your MSSQL tables before you run the COBOL program that creates the tables, just as you must create a directory for your files before you run a COBOL program that creates indexed files.

See To Install Acu4GL for Microsoft SQL Server for instructions to complete the installation. Once installation is complete, you can prepare and compile your COBOL program.

Parent topic: Installation and Setup
Related reference
Demonstration Program
Preparing and Compiling Your COBOL Program Example
filename HOST configuration variable
DEFAULT HOST configuration variable
To install Database Connectors on a Windows server


Filename Translation

As you prepare to work with Acu4GL for MSSQL, you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together.

When the compiler generates XFD files, it uses lowercase letters to name the XFD file. In addition, the compiler changes hyphens to underscores when naming the XFD file.

Through ACUCOBOL-GT runtime configuration file variables, the run time system translates the file name in the COBOL program into the filename that is passed to the open() function in the run time system. The open() function determines which file system to pass the request to, but does not change the name of the file.

However, the Connector needs the name of the file to find the appropriate XFD file. To do this, Acu4GL changes the name of the file to lowercase letters and changes hyphens to underscores. Note, however, that this is performed only on a local copy of the file. Once the XFD file is found, the filename reverts to the name that was originally passed to the open() function. Characters that are illegal in identifiers, such as a hyphen ("-"), are trapped by Acu4GL neither find the file nor create a new one.

Parent topic: Appendix B: Acu4GL for Microsoft SQL Server


Supported Data Types for SQL Server

The table below shows the mappings used by Acu4GL when interacting with Microsoft SQL Server.

Data type | Generated using...
DATETIME | The DATE XFD directive, specifying both date and time information.
DATE | The DATE XFD directive, specifying only date information.
TIME | The DATE XFD directive, specifying only time information.
BINARY(n) | The BINARY XFD directive, specifying a COBOL field 8000 bytes or less. n refers to the number of bytes.
IMAGE | The BINARY XFD directive, specifying a COBOL field greater than 8000 bytes.
CHAR(n) or NCHAR(n) | A COBOL field of type PIC X(n), where n is less than 8000 characters/digits. For NCHAR, the Unicode and COBOL conversion is also dependent on the COBOL_CHARACTER_SET configuration variable.
GUID | A COBOL field of type PIC X(36). Note: Support is only for existing tables containing this type; Acu4GL cannot create a new column of this type. If required, use the A_MSSQL_IGNORE_GUID_COLUMNS configuration variable to ignore the GUID column in a table.
TEXT | A COBOL field of type PIC X(n), where n is 8000 characters/digits or more.
VARCHAR(n) or NVARCHAR(n) | The VAR_LENGTH XFD directive and specifying a COBOL field of type PIC X(n), where n refers to the size of the COBOL field. For NVARCHAR, the Unicode and COBOL conversion is also dependent on the COBOL_CHARACTER_SET configuration variable.
FLOAT | A COBOL field of type DOUBLE.
REAL | A COBOL field of type FLOAT.
TINYINT | A COBOL field of type PIC 9 or PIC 99.
SMALLINT | A COBOL field of type PIC 9(3) or PIC 9(4).
INT | A COBOL field of type of PIC 9(5) to PIC 9(8).
BIGINT | A COBOL field of type PIC 9(9) to PIC 9(18).
DECIMAL(n,0) | A COBOL field of type PIC(19) or larger, where n is the number of digits.
DECIMAL(n,m) | A decimal COBOL field, where n refers to the number of digits to the left of the decimal point and m refers to the number of digits to the right of the decimal point.
Parent topic: Appendix B: Acu4GL for Microsoft SQL Server
Related reference
BINARY XFD directive
VAR_LENGTH XFD directive
DATE XFD directive
A_MSSQL_IGNORE_GUID_COLUMNS configuration variable


Configuration File Variables

These topics list the run-time configuration file variables that are specific to Microsoft SQL Server. Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are listed in Run-time Configuration Variables.

  • A_MSSQL_ADD_IDENTITY configuration variable
  • A_MSSQL_ADD_TIMESTAMP configuration variable
  • A_MSSQL_APPROLE_NAME configuration variable
  • A_MSSQL_APPROLE_PASSWD configuration variable
  • A_MSSQL_CREATE_UNICODE_COLUMNS configuration variable
  • A_MSSQL_CURSOR_OPTION_1,2,3 configuration variables
  • A_MSSQL_DATABASE configuration variable
  • A_MSSQL_DEADLOCK_LOOPS configuration variable
  • A_MSSQL_DEFAULT_CONNECTION configuration variable
  • A_MSSQL_DEFAULT_OWNER configuration variable
  • A_MSSQL_DO_NOT_TRANSLATE_CHAR configuration variable
  • A_MSSQL_FAILOVER_PARTNER configuration variable
  • A_MSSQL_FAILOVER_PARTNER_SPN configuration variable
  • A_MSSQL_IGNORE_GUID_COLUMNS configuration variable
  • A_MSSQL_FAST_ACCESS configuration variable
  • A_MSSQL_LIMIT_DROPDOWN configuration variable
  • A_MSSQL_LOCK_DB configuration variable
  • A_MSSQL_LOGIN configuration variable
  • A_MSSQL_MAX_BINARY_LENGTH configuration variable
  • A_MSSQL_MAX_CHAR_LENGTH configuration variable
  • A_MSSQL_MAX_CHARACTERS configuration variable
  • A_MSSQL_MAX_COLUMNS configuration variable
  • A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable
  • A_MSSQL_NATIVE_LOCK_TIMEOUT configuration variable
  • A_MSSQL_NO_23_ON_START configuration variable
  • A_MSSQL_NO_CACHED_READ configuration variable
  • A_MSSQL_NO_COUNT_CHECK configuration variable
  • A_MSSQL_NO_DBID configuration variable
  • A_MSSQL_NO_RECORD_LOCKS configuration variable
  • A_MSSQL_NO_TABLE_LOCKS configuration variable
  • A_MSSQL_NT_AUTHENTICATION configuration variable
  • A_MSSQL_ODBC_DRIVER_NAME configuration variable
  • A_MSSQL_PACKETSIZE configuration variable
  • A_MSSQL_PASSWD configuration variable
  • A_MSSQL_ROWCOUNT configuration variable
  • A_MSSQL_SELECT_KEY_ONLY configuration variable
  • A_MSSQL_SEPARATE_LOCK_CONN configuration variable
  • A_MSSQL_SERVER_SPN configuration variable
  • A_MSSQL_SKIP_ALTERNATE_KEYS configuration variable
  • A_MSSQL_STRIP_PATH_INFO configuration variable
  • A_MSSQL_TRANSACTION_LEVEL configuration variable
  • A_MSSQL_TRANSLATE_TO_ANSI configuration variable
  • A_MSSQL_UNLOCK_ON_EXECUTE configuration variable
  • A_MSSQL_UPDATE_PRIMARY_COLS configuration variable
  • A_MSSQL_USE_DROPDOWN_QUERIES configuration variable
  • A_MSSQL_VISION_LOCKS_FILE configuration variable
Parent topic: Appendix B: Acu4GL for Microsoft SQL Server
Related reference
Run-time Configuration Variables
Related information
Setting Up the User Environment


A_MSSQL_ADD_IDENTITY configuration variable

When set to the default of On (true, yes), A_MSSQL_ADD_IDENTITY adds an extra column to any table created by Acu4GL for MSSQL. The extra column includes the identity property and is included on all indexes that are not unique. Otherwise, when A_MSSQL_ADD_IDENTITY is set to False (false, no), no extra column is added.

Note: The COBOL FD should not include the identity column.

Example

A_MSSQL_ADD_IDENTITY TRUE

On keys that allow duplicates, this variable has been found to vastly improve performance. Note that the default value is True for a file that allows duplicates and is False for a file with no duplicate keys.

Parent topic: Configuration File Variables


A_MSSQL_ADD_TIMESTAMP configuration variable

Using a timestamp column is the only way to absolutely ensure that modifications made to a row are not overwriting someone else's changes. When it's reading a table that is open for I/O,Acu4GL for MssQL uses BROWSE MODE if a timestamp column exists. When Acu4GL is creating a table, if the value of A_MSSQL_ADD_TIMESTAMP is TRUE, a timestamp column is included in the table. (Note that your COBOL FD should not include the timestamp column.) While the default value is Off (false, no), this variable can also take values of On (true, yes).

Note: Microsoft discourages the use of BROWSE MODE on Select statements because of performance reasons. Therefore, unless it is absolutely necessary, do not set this variable to On.

Example

A_MSSQL_ADD_TIMESTAMP  1
Note: If you do not use this option, be prepared for REWRITE statements to fail with an error stating that someone else has modified the row. Because of the AcuLocks1 tables, this can happen only from non-COBOL applications. For information about AcuLocks1 tables, see Table Locking.
Parent topic: Configuration File Variables
Related information
Table Locking


A_MSSQL_APPROLE_NAME configuration variable

This variable, in conjunction with A_MSSQL_APPROLE_PASSWD, allows Acu4GL to use approles. Before connecting to a database, set A_MSSQL_APPROLE_NAME to the name of a role. Note that you must also set A_MSSQL_APPROLE_PASSWD to a password for that role. By using these two variables, you set the run time to use this approle.

For more information on approles, please see the Microsoft SQL Server documentation.

Parent topic: Configuration File Variables
Related information
A_MSSQL_APPROLE_PASSWD configuration variable


A_MSSQL_APPROLE_PASSWD configuration variable

This variable, in conjunction with A_MSSQL_APPROLE_NAME, enables use of approles. Before connecting to a database, set A_MSSQL_APPROLE_NAME to the name of a role. Then set A_MSSQL_APPROLE_PASSWD to a password for that role. By using these two variables, you set the run time to use this approle.

For more information on approles, please see the Microsoft SQL Server documentation.

Parent topic: Configuration File Variables
Related information
A_MSSQL_APPROLE_NAME configuration variable


A_MSSQL_CREATE_UNICODE_COLUMNS configuration variable

When A_MSSQL_CREATE_UNICODE_COLUMNS is set to TRUE, the Acu4GL for Microsoft for SQL Server interface creates nchar or nvarchar columns for all new text data. Note that existing tables are not affected.

The default value for this variable is FALSE, meaning that behavior is the same as in prior versions.

Parent topic: Configuration File Variables


A_MSSQL_CURSOR_OPTION_1,2,3 configuration variables

A_MSSQL_CURSOR_OPTION_1
A_MSSQL_CURSOR_OPTION_2
A_MSSQL_CURSOR_OPTION_3

These ACUCOBOL-GT runtime configuration file variables allow you to fine-tune the declaration of cursors. In general, cursors are declared with the following syntax:

DECLARE cursor_name option_1 CURSOR option_2 FOR
  <select....> option_3

In other words, different phrases can go in each of the option_X places. Also, different versions of Microsoft SQL Server allow different options in each of those places. Because of this, Acu4GL allows customization of the cursor declaration via these three variables. The values of these variables are placed verbatim into the declare phrase when building a cursor. Note that any errors in the values of these variables may cause Acu4GL to be inoperable. Be sure to read the Microsoft SQL Server documentation to determine what phrases are allowed in each case.

The default values are as follows (the limit is 65 characters for each option):

OPTION_1: | "SCROLL"
OPTION_2: | blank
OPTION_3: | "For read only"
Note: This variable was added because of an issue in SQL Server 6.5 and SQL Server 7.0 that would return incorrect results if this phrase was not used.
Parent topic: Configuration File Variables


A_MSSQL_DATABASE configuration variable

A_MSSQL_DATABASE specifies the name of the particular database to be accessed. You cannot open any database files until you have set this variable.

Example

A_MSSQL_DATABASE stores

indicates the "stores" database is to be accessed.

Parent topic: Configuration File Variables


A_MSSQL_DEADLOCK_LOOPS configuration variable

Use A_MSSQL_DEADLOCK_LOOPS if user typically open a number of tables at the same time. This configuration variable can be used to instruct Acu4GL to re-execute an INSERT statement that could not execute because a row in the AcuOpen1Tables table was locked, or to return an error if the user chooses not to run the query again.

Valid values are:

0 (the default) | Returns an error 1205 indicating that a table is locked
A positive numeric value. | Re-executes by the number specified by the query that caused the deadlock. Note that it can be as long as 10 seconds until SQL Server detects the deadlock, and the application appears to stop responding while the repeated attempts to re-execute the query are in progress.
-1 or MESSAGE Displays a message box containing the text of the SQL Server error message and the option to rerun the query.
SQL Server has returned an error
(text of message from SQL Server)
Do you want to retry the operation?

If the user answers Yes, the interface reruns the query; if the user answers No, the interface returns an error.

Setting A_MSSQL_DEADLOCK_LOOPS to -1 or MESSAGE is the preferred action; the time it takes to inform users of the problem allows other connections to finish opening the tables, giving the AcuOpenTables1 table time to remove the deadlock. For information about AcuOpenTables1 table, see Table Locking.

Parent topic: Configuration File Variables
Related information
Table Locking


A_MSSQL_DEFAULT_CONNECTION configuration variable

A_MSSQL_DEFAULT_CONNECTION specifies the name of the server to which the run time system connects. If A_MSSQL_DEFAULT_CONNECTION is not set, a server name of localhost is used. To reference tables on a server other than the one specified by this variable, open the file using the following syntax:servername.database.owner.table.

Example

Suppose you have two servers, one named TOM and one named HARRY. If most of the tables you want to access are on the server HARRY, you should set:

A_MSSQL_DEFAULT_CONNECTION  HARRY

For those occasions when you want to access the TOM server, you could open the file this way:

TOM.stores.johndoe.purch1
Parent topic: Configuration File Variables


A_MSSQL_DEFAULT_OWNER configuration variable

In Microsoft SQL Server, tables are named database.user.tablename. The value of A_MSSQL_DEFAULT_OWNER specifies the name of the user. If this variable is set, it must match the owner of a table. Tables are referenced as owner.table, where owner is the value of A_MSSQL_DEFAULT_OWNER. If this variable is set to a value for which owner.table does not exist, the interface fails to access the table.

Note that newly created tables are owned by the users who create them, not the owner named in A_MSSQL_DEFAULT_OWNER. The default value of this variable is blank, causing the interface to call an internal stored procedure to determine the actual owner of the table. Note also that we discourage multiple tables with the same tablename in a single database.

Parent topic: Configuration File Variables


A_MSSQL_DO_NOT_TRANSLATE_CHAR configuration variable

If a SQL Server database is configured with a collation that conflicts with the Locale of the client program, characters that can not be represented in the database's collation are turned into question marks. This was not the behavior prior to version 8.1.2.

Setting this variable to ON, causes all character fields, except those for date fields, to be treated as binary, storing them in the database and retrieving from the database without translation. This provides the behavior seen prior to 8.1.2 and is useful if the client is using a different locale than the database's collation.

The default setting is OFF and means that character fields, except for date fields, will be translated.

Parent topic: Configuration File Variables


A_MSSQL_FAILOVER_PARTNER configuration variable

This configuration variable specifies the name of the failover partner used when multi-subnet failover support is enabled. Refer to your SQL Server documentation for valid values.

Multi-subnet failover support is enabled by setting the A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable to TRUE.

Parent topic: Configuration File Variables
Related reference
A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable
A_MSSQL_SERVER_SPN configuration variable
A_MSSQL_FAILOVER_PARTNER_SPN configuration variable


A_MSSQL_FAILOVER_PARTNER_SPN configuration variable

This configuration variable specifies the name of the failover partner SPN used when multi-subnet failover support is enabled. Refer to your SQL Server documentation for valid values.

Multi-subnet failover support is enabled by setting the A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable to TRUE.

Parent topic: Configuration File Variables
Related reference
A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable
A_MSSQL_SERVER_SPN configuration variable
A_MSSQL_FAILOVER_PARTNER configuration variable


A_MSSQL_IGNORE_GUID_COLUMNS configuration variable

This configuration variable determines the behavior when handling existing tables that contain a column of type GUID.

When A_MSSQL_IGNORE_GUID_COLUMNS is set to its default setting of false (Off, 0, or no), you must use COBOL data items that are at least 36 characters in size for GUID columns, otherwise an error is returned when the row is read. When writing or rewriting a row when the GUID data item is too small, SQL Server may produce an error. If you have a GUID that is larger than 36 characters, Acu4GL will only read the first 36 characters; the rest are padded with spaces.

Note: Older ODBC drivers may not be able to handle GUID column types, in which case, the results of those operations are undefined.

If you set A_MSSQL_IGNORE_GUID_COLUMNS to true (on, 1, or yes), columns of type GUID are ignored for any SELECT, UPDATE, or INSERT statements sent to the server. You do not need to specify a COBOL data item for these columns when reading or writing a row.

Parent topic: Configuration File Variables


A_MSSQL_FAST_ACCESS configuration variable

A_MSSQL_FAST_ACCESS is set from your COBOL program. Files opened while this variable is set to a nonzero value are optimized for forward sequential access.

This option improves the READ NEXT performance in some cases. For example, benchmark testing yielded the following results for the READ AND SKIP operation:

No FAST_ACCESS: | 72.76 seconds
FAST_ACCESS, ROWCOUNT 0: | 148.88 seconds
FAST_ACCESS, ROWCOUNT 10: | 8.09 seconds

(10 is the perfect value for ROWCOUNT in this benchmark, because the program does a START, 10 READ NEXT operations, and then does it again.)

For certain reporting programs, this option can dramatically improve performance. However, please note the following restrictions:

  • Files must be open INPUT or open IO with MASS-UPDATE. FAST_ACCESS boosts performance only when no locking is required. In files that allow locking, a record must be reread after being locked; this prevents an uninterrupted forward sequential traversal.
  • Files opened with FAST_ACCESS use a dedicated connection for reading from the file. Since connections are memory-intensive (both on the client, and on the server), the number of files opened with FAST_ACCESS should be kept to a minimum. In the event that opening a connection fails, the file open continues, but FAST_ACCESS mode is disabled, with the following message appearing in the trace file:
    FAST_ACCESS mode not available.

    Also, a new connection technically uses a new concurrent Microsoft SQL Server license from Microsoft.

  • Files opened with FAST_ACCESS do not participate in transactions and may even cause the run time system to stop responding if transactions are used, especially if the FAST_ACCESS file is updated within the transaction. If you use transactions, do not use FAST_ACCESS. If you use transactions, use FAST_ACCESS only for files open INPUT.
  • Files opened with FAST_ACCESS cannot be read backwards. In other words, READ PREVIOUS does not work with FAST_ACCESS files. If you try to READ PREVIOUS on a file opened with FAST_ACCESS, an error 9/83 with a secondary code of 20 occurs.
  • The ANSI standard states that READ NEXT after a READ returns the next record. Some applications depend on this, and some applications just want to read dynamically from a file, and don't use the positioning facility. Because of this ambiguity, files that are opened with FAST_ACCESS cannot be READ dynamically. If you try to READ on a file opened with FAST_ACCESS, an error 9/83 with a secondary code of 20 occurs.

There are no restrictions on WRITE, REWRITE, and DELETE. However, these operations use the cursor-based connection, not the dedicated connection. For this reason, transactions may stop responding.

While the default value is 0 (off, false, no), this variable can also take values of On (true, yes).

Parent topic: Configuration File Variables


A_MSSQL_LIMIT_DROPDOWN configuration variable

This configuration option is closely related to A_MSSQL_USE_DROPDOWN_QUERIES.

When a sequence of START and READ NEXT/PREVIOUS operations are performed by an application, Acu4GL/MSSQL generates a sequence of queries to return the set of records matching the application's request. To improve performance, the interface generates a sequence of "drop down" queries based upon the key of reference's key segments going from the most specific subset using the most number of segments to the most general using the least number of segments. This functionality is turned on by setting the configuration variable A_MSSQL_USE_DROPDOWN_QUERIES to TRUE.

For example if a key is described by:

    03 MY-ALTKEY.
       05 MY-ALTKEY-SEG1        PIC X(2).
       05 MY-ALTKEY-SEG2        PIC X(2).
       05 MY-ALTKEY-SEG3        PIC X(2).

Then a START followed by a sequence of READ NEXT operations might generate the selection criteria of:

WHERE MY-ALTKEY-SEG1 = :w0 AND MY-ALTKEY-SEG2 = :w1 AND
MY-ALTKEY-SEG3 >= :w3
WHERE MY-ALTKEY-SEG1 = :w0 AND MY-ALTKEY-SEG2 > :w1
WHERE MY-ALTKEY-SEG1 > :w0

This can improve performance because the target for each query is kept to a minimal size. If a set of records is not required, the database does not need to spend the time building the working set. When a "DROP DOWN" does occur however, the subsequent working set can require a large amount of time to process because of the potential magnitude of records. Normally there is not a way for a COBOL application to instruct the interface to stop processing when it has finished with the records based on a given key segment.

To address this, use A_MSSQL_LIMIT_DROPDOWN configuration variable.

This variable allows an application to direct the interface not to perform "drop down" query generation and instead return "end of file" when the records matching the current query have been exhausted.

This variable may be set to one of the following options:

OFF | This is the current default. The interface performs "drop down" queries.
PARTIAL | If the record positioning was performed by a START with a SIZE clause such that the initial positioning was performed using fewer than the total number of columns in the key, the process stops after all records matching the START columns have been exhausted.
FULL | If the record positioning was performed by a START without a SIZE clause, the process stops after all records matching the START columns have been exhausted.
ALL | Regardless of what form of START was used for the initial positioning, the process stops after all records matching the START columns have been exhausted.

This variable is performed at the time of each start, so the application may change its value.

Parent topic: Configuration File Variables
Related reference
A_MSSQL_USE_DROPDOWN_QUERIES configuration variable


A_MSSQL_LOCK_DB configuration variable

A_MSSQL_LOCK_DB specifies the name of the database that holds the lock table. For information about AcuLocks1 tables, see Table Locking.

Parent topic: Configuration File Variables
Related information
Table Locking


A_MSSQL_LOGIN configuration variable

A_MSSQL_LOGIN indicates the user name under which you want to connect to the database system.

Example

To connect to the database with the user name MYNAME, specify A_MSSQL_LOGIN MYNAME in the ACUCOBOL-GT runtime configuration file.

See A_MSSQL_NT_AUTHENTICATION configuration variable for an alternate method to log onto the server (Windows only). See Setting Up a User Account for more information.

Parent topic: Configuration File Variables
Related reference
A_MSSQL_NT_AUTHENTICATION configuration variable
A_MSSQL_PASSWD configuration variable
Related information
Setting Up a User Account


A_MSSQL_MAX_BINARY_LENGTH configuration variable

This configuration variable specifies the maximum size of a COBOL variable that can be used as a BINARY data type in SQL Server. Data items larger than this value become IMAGE types in the server. The default value is 8001.

See the topic Preparing your Programs for more information about data types in AcuSQL.

Parent topic: Configuration File Variables


A_MSSQL_MAX_CHAR_LENGTH configuration variable

This configuration variable specifies the maximum size of a COBOL variable that can be used as a VARCHAR data type in SQL Server. Data items larger than this value become IMAGE types in the server. The default value is 8001.

See the topic Preparing your Programs for more information about data types in AcuSQL.

Parent topic: Configuration File Variables


A_MSSQL_MAX_CHARACTERS configuration variable

A_MSSQL_MAX_CHARACTERS indicates the maximum number of bytes the Acu4GL allows in a table row.

Microsoft SQL Server places a limit on the number of bytes per table row. Acu4GL adheres to this limit, but sometimes it cannot accurately count how many bytes a particular row contains (because of overhead bytes that Microsoft SQL Server adds). This variable enables the developer to set Acu4GL upper bound.

You might want to try reducing this value if a table cannot be created. By reducing the upper bound, you may be able to prevent this problem.

If Microsoft SQL Server increases the maximum number of bytes allowed in a row (in a future release of the product), you can increase the value of this variable to take advantage of the new limit.

The A_MSSQL_MAX_CHARACTERS variable has a default value of 8060.

Parent topic: Configuration File Variables


A_MSSQL_MAX_COLUMNS configuration variable

A_MSSQL_MAX_COLUMNS indicates the maximum number of columns Acu4GL allows in a table. The default value is 1024.

Microsoft SQL Server places a limit on the number of columns per table. Acu4GL adheres to this limit, but sometimes it cannot accurately count how many columns a table contains (because a column has been added to a table without Acu4GL knowledge). This variable enables the developer to set Acu4GL upper bound. You might want to try reducing the upper bound if you discover that a table cannot be created. By reducing the upper bound, you allow for uncountable columns and thus may be able to prevent this problem.

If Microsoft SQL Server increases the maximum number of columns allowed per table (in a future release of the product), you could increase the value of this variable to take advantage of the new limit. Consult your Microsoft SQL Server documentation to decide the new maximum number of columns allowed per table.

Parent topic: Configuration File Variables


A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable

Set to TRUE to enable multi-subnet failover support for your Microsoft SQL Server connection. If set to FALSE (the default) the feature is not enabled, and the other configuration variables relating to multi-subnet failover have no effect.

Parent topic: Configuration File Variables
Related reference
A_MSSQL_SERVER_SPN configuration variable
A_MSSQL_FAILOVER_PARTNER_SPN configuration variable
A_MSSQL_FAILOVER_PARTNER configuration variable


A_MSSQL_NATIVE_LOCK_TIMEOUT configuration variable

This is one of two locking methods available with Acu4GL for MSSQL. The methods are accessed via the A_MSSQL_NATIVE_LOCK_TIMEOUT configuration variable. If A_MSSQL_NATIVE_LOCK_TIMEOUT is set to a positive value, native locking is used. Otherwise, the AcuLocks1 table is used to hold locks.

This locking method enables you to use Microsoft SQL Server native locks if you explicitly code transactions in your COBOL program. You can access this method by setting A_MSSQL_NATIVE_LOCK_TIMEOUT to a positive value. This value is the number of seconds that a connection waits for a timeout to occur. When such a timeout occurs, Acu4GL assumes that the timeout is caused by a locked record, and returns error 99 (record locked). If you set this variable but do not explicitly code transactions in your COBOL program, record locking does not occur. Note that Acu4GL waits the number of seconds specified, and your application may appear to stop responding if the timeout is too long. On the other hand, if the timeout is too short, you may get record locked errors when the network is slow.

Microsoft SQL Server uses a page-locking mechanism, and so this method of locking records may cause your application to return spurious record locked errors caused by a record being locked on the same page as the record you are trying to access. Microsoft SQL Server 7.0 uses row-level locking, but because of the timing issue, using this option is not recommended.

Note: Even with this variable set, the interface still needs the AcuOpenTables1 table. For information about AcuOpenTables1, see Table Locking.
Parent topic: Configuration File Variables
Related information
Table Locking


A_MSSQL_NO_23_ON_START configuration variable

When A_MSSQL_NO_23_ON_START is set to TRUE, START does not detect whether records matching the search criteria actually exist. Because it does not detect the existence of records, it is possible, when using this variable, to do a START without error, and for the next READ NEXT to return END_OF_FILE, contrary to the ANSI standard. The default value is FALSE.

Example

A_MSSQL_NO_23_ON_START TRUE
Parent topic: Configuration File Variables


A_MSSQL_NO_CACHED_READ configuration variable

By default, the Acu4GL for MSSQL run time applies the same READ logic on a previously-read record as is used for the Vision indexed file system. Instead of sending another request to MSSQL to read the same record, the run time gets the record from cache. This behavior is referred to as Cached Read and can improve performance.

A_MSSQL_NO_CACHED_READ controls this behavior. By default cached read is enabled. It can be disabled by setting A_MSSQL_NO_CACHED_READ to true or 1.

If the last operation was a successful READ with LOCK and the next operation is a READ with LOCK on the same key with the same key value then the cached record returneds without accessing the database. A trace file entry is made that says cached read.

Parent topic: Configuration File Variables


A_MSSQL_NO_COUNT_CHECK configuration variable

When performing a REWRITE, the interface checks to see that a record was actually updated. If not, it returns an error 23. Setting this variable to ON disables that check. This improve REWRITE performance, at the risk of missing an error. While the default value is Off (false, no), this variable can also take the value of On (true, yes).

Parent topic: Configuration File Variables


A_MSSQL_NO_DBID configuration variable

The interface stores the Database ID in the AcuLocks1 and AcuOpenTables1 tables, to distinguish different tables in different databases. Sometimes this causes problems. Setting this variable to On causes the interface to use a Database ID of 0, instead of the actual ID of the database. While the default value is Off (false, no), this variable can also take the value of On (true, yes).

For information about AcuLocks1 and AcuOpenTables1, see Table Locking.

Parent topic: Configuration File Variables
Related information
Table Locking


A_MSSQL_NO_RECORD_LOCKS configuration variable

Setting this variable ON causes all READS to be treated as READ NO LOCK, which can improve performance (but has the obvious consequences). While the default value is Off (false, no), this variable can also take the value of On (true, yes).

Parent topic: Configuration File Variables


A_MSSQL_NO_TABLE_LOCKS configuration variable

Setting this variable to On means the interface does not use the AcuOpenTables1 table, which causes all table locking to be disabled. This can improve performance on OPEN and CLOSE statements. While the default value is Off (false, no), this variable can also take the value of On (true, yes).

For information about AcuOpenTables1, see Table Locking.

Parent topic: Configuration File Variables
Related information
Table Locking


A_MSSQL_NT_AUTHENTICATION configuration variable

The A_MSSQL_NT_AUTHENTICATION configuration variable indicates whether Microsoft SQL Server authenticates users based on their Windows login (Windows only).

If this variable is set to True (on, yes), Acu4GL for MSSQL interface attempts to log users on using the Microsoft SQL Server Windows NT authentication mode. (See your SQL Server documentation for information about this authentication mode.) When A_MSSQL_NT_AUTHENTICATION is enabled, the A_MSSQL_LOGIN and A_MSSQL_PASSWD configuration variables are no longer needed or used. (They are still available if you are not using Windows NT authentication mode.) If you have not set up Microsoft SQL Server itself to allow this type of authentication, setting this variable to TRUE causes all login attempts to fail. See your Microsoft SQL Server documentation for information on how to set up this type of authentication.

The default is False (off, no), indicating that Acu4GL does not use Windows NT authentication mode when logging users on and continues to use login and password authentication.

Parent topic: Configuration File Variables
Related reference
A_MSSQL_PASSWD configuration variable
A_MSSQL_LOGIN configuration variable


A_MSSQL_ODBC_DRIVER_NAME configuration variable

This variable lets you specify the ODBC SQL Server driver name for the SQL Server interface. SQL Server is the value set by default. You can change this to any value. However, the results are undefined if changed to a value which is not a valid supported SQL Server ODBC driver on your system.

Supported values include:

  • SQL Server
  • SQL Server Native Client 10.0
  • SQL Server Native Client 11.0
  • ODBC Driver 11 for SQL Server
  • ODBC Driver 12 for SQL Server
  • ODBC Driver 13 for SQL Server
Parent topic: Configuration File Variables


A_MSSQL_PACKETSIZE configuration variable

The A_MSSQL_PACKETSIZE configuration variable sets the size of network packets. Setting this variable can affect performance, since fewer and larger network calls can improve performance.

This variable must be set in the ACUCOBOL-GT runtime configuration file and has no effect if set in a COBOL program via SET CONFIGURATION or SET ENVIRONMENT. The value of this variable is the largest size that the transport layer uses for network packets (although the underlying library may reduce the size specified; this is out of the control of the interface.) The largest value that can be specified is 32767. The default depends on which version of the client libraries are linked into the run time system, although 512 is the most common default.

Use this variable to tune your database performance. To set the packet size to 8192 use:

A_MSSQL_PACKETSIZE   8192

Setting this variable to 0 or to a negative value causes Acu4GL to use the default value.

Parent topic: Configuration File Variables


A_MSSQL_PASSWD configuration variable

The variable A_MSSQL_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_MSSQL_LOGIN.

Examples

If the account with the user name in A_MSSQL_LOGIN has the associated password CW021535, specify:

A_MSSQL_PASSWD  CW021535

in the ACUCOBOL-GT runtime configuration file.

For better security, you can accept a password from the user during program execution; set the A_MSSQL_PASSWD variable based on the response:

ACCEPT RESPONSE NO-ECHO.
SET ENVIRONMENT "A_MSSQL_PASSWD" TO RESPONSE.
Note: If the user has been set up without a password, this variable need not be set.
Parent topic: Configuration File Variables
Related reference
A_MSSQL_NT_AUTHENTICATION configuration variable
A_MSSQL_LOGIN configuration variable


A_MSSQL_ROWCOUNT configuration variable

This variable has an effect only if you are reading on a key that does not allow duplicates, or if you have added an Identity column to the table. A_MSSQL_ROWCOUNT determines how many rows are returned by a SELECT statement sent to the server.

This variable can be used to speed up the Connector. For example, if only reading one record at a time, and reading from a unique key, you can set A_MSSQL_ROWCOUNT to 1, thus speeding up the processing.

If you know you are going to be reading records ten rows at a time, set A_MSSQL_ROWCOUNT to 10. If you don't have any information about how many rows are going to be requested, set this variable to 0, which is the default.

Note: Setting this variable to a non-optional value can actually degrade performance, since the interface may be forced to issue more SELECT statements once the rowcount has been determined. Use caution when setting this variable.
Parent topic: Configuration File Variables
Related information
A_MSSQL_ADD_IDENTITY configuration variable


A_MSSQL_SELECT_KEY_ONLY configuration variable

This variable directs the interface to select key columns only when searching for records. Its use can improve READ performance on large tables with many rows.

When set to True (on, yes), the default value, A_MSSQL_SELECT_KEY_ONLY causes the interface to select only key columns when searching for records, and then select the entire row of the single record that must be returned to the COBOL program. This improves performance on large tables with many rows.

Setting A_MSSQL_SELECT_KEY_ONLY to False (off, no) does not affect how the select is created for files open I/O (since the record must be locked and then the rest of the data fetched), but causes the interface to select all the columns of the table for files open INPUT.

Parent topic: Configuration File Variables


A_MSSQL_SEPARATE_LOCK_CONN configuration variable

When set to TRUE, this variable causes the Acu4GL for MSSQL interface to open two connections to any server it connects to. One of those connections performs all the normal COBOL data work (write, rewrite, read next, etc). Any transactions started affect this first connection.

The second connection does all the internal work needed by the interface to do its normal work, such as updating the lock tables, testing for locks, etc. This connection always remains outside of any transactions, allowing the interface to always handle the internals correctly.

The reason for the configuration variable is that a separate connection to SQL Server requires a separate license from Microsoft.

If you are not experiencing transaction difficulties with table or record locks, then keep this variable set to the default value of FALSE. If you are experiencing frequent deadlocks during record locking or opening of tables, you may be able to solve those by setting this variable to TRUE.

Parent topic: Configuration File Variables


A_MSSQL_SERVER_SPN configuration variable

This configuration variable specifies the name of the server SPN used when multi-subnet failover support is enabled. Refer to your SQL Server documentation for valid values.

Multi-subnet failover support is enabled by setting the A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable to TRUE.

Parent topic: Configuration File Variables
Related reference
A_MSSQL_MULTI_SUBNET_FAILOVER configuration variable
A_MSSQL_FAILOVER_PARTNER_SPN configuration variable
A_MSSQL_FAILOVER_PARTNER configuration variable


A_MSSQL_SKIP_ALTERNATE_KEYS configuration variable

A_MSSQL_SKIP_ALTERNATE_KEYS determines whether alternate keys are used to form indexes during table creation. The default value of this variable is 0, which allows alternate keys. This configuration variable can also take values of 1 (on, true, yes).

If you set this variable to a nonzero value (such as 1), alternate keys are not used to form indexes, which speeds up processing if many writes or rewrites are being performed. (Note that a value of 1 may slow processing if the application is reading sequentially using an alternate key.)

Parent topic: Configuration File Variables


A_MSSQL_STRIP_PATH_INFO configuration variable

This configuration variable addresses a change in the new naming syntax Microsoft SQL Server introduced for servers: Servername\Instancename. Acu4GL for SQL Server treats the naming as a path, and strips the Servername portion.

This is correct behavior. If you use a mix of Vision and SQL Server, and use FILE-PREFIX with a value containing multiple directory levels such as \usr\data\ar, then this information is stripped from the file name before it opens. This configuration variable prevents this

When set to the default value of TRUE (ON, YES, 1), then the interface behaves as it always has. When set to FALSE (OFF, NO, 0), the interface ignores the name.

Note: Setting this variable to FALSE and using FILE_PREFIX with your SQL Server tables can cause unpredictable results. Use caution when using these variables in combination. Connecting to a single server/instance and using the A_MSSQL_DEFAULT_CONNECTION variable with that server/instance value may be a better way to handle an instance on a server that has multiple instances. However, this does not allow you to connect to multiple instances.
Parent topic: Configuration File Variables


A_MSSQL_TRANSACTION_LEVEL configuration variable

Use this configuration variable to indicate the transaction nested level depth for Acu4GL for MSSQL. This is useful when sending embedded SQL Server BEGIN TRANSACTION statements to the server without using the interface (such as by using sql.acu). The default is zero (0).

Parent topic: Configuration File Variables


A_MSSQL_TRANSLATE_TO_ANSI configuration variable

Setting this variable to True (on, yes) causes Acu4GL to call the same translation function used by the Windows run time to translate characters going to the server into the OEM character set, and to translate characters coming from the server to ANSI.

The default is False (off, no), which indicates that Acu4GL does not call the translation function, but passes the data as is to the library.

Parent topic: Configuration File Variables


A_MSSQL_UNLOCK_ON_EXECUTE configuration variable

Setting this variable to True (on, yes) causes all invocations of I$IO using the EXECUTE opcode to unlock all records. Normally, records are unlocked when a transaction finishes, but if users perform their own transaction management, using sql.acu (which calls I$IO using the EXECUTE opcode), the interface never knows to unlock records, because it does not check the text sent to the database to see if it is associated with a transaction. The default value is Off (false, no).

Parent topic: Configuration File Variables


A_MSSQL_UPDATE_PRIMARY_COLS configuration variable

When set to TRUE, this variable causes the Acu4GL for MSSQL interface to update all the fields in a table in files that have only primary key fields. Normally, Acu4GL does not add the primary key fields to updated columns, since these can not be modified. Use this variable to change that behavior.

This variable is useful to update multiple files that have only fields that are in the primary key. The default variable value is FALSE.

Parent topic: Configuration File Variables


A_MSSQL_USE_DROPDOWN_QUERIES configuration variable

Setting A_MSSQL_USE_DROPDOWN_QUERIES to TRUE causes selects sent to the database to be of the drop-down variety, instead of a single large query.

For example, if you have a file with three fields in the primary key, (keyseg1, keyseg2, keyseg3), and your COBOL program does a START, the following query is sent to the database:

select (columns) from (table) where
((keyseg1 = value1 and keyseg2 = value2 and
keyseg3 > value3) or (keyseg1 = value1 and
keyseg2 > value2) or (keyseg1 > value1))
order by keyseg1, keyseg2, keyseg3

If you use drop-down queries, the following collection of queries is sent instead:

select (columns) from (table) where (keyseg1
= value1 and keyseg2 = value2 and keyseg3 >
value3) order by keyseg1, keyseg2, keyseg3

followed by:

select (columns) from (table) where (keyseg1
= value1 and keyseg2 > value2) order by
keyseg1, keyseg2, keyseg3

and:

select (columns) from (table) where (keyseg1
> value1) order by keyseg1, keyseg2, keyseg3

There are advantages and disadvantages to each method. If you use the A4GL_WHERE_CONSTRAINT variable, you should probably set A_MSSQL_USE_DROPDOWN_QUERIES to FALSE, because the WHERE constraint limits the result set sufficiently that the larger query is more efficient. For additional information, see The WHERE Constraint.

If you usually START files and read to the end, you should set A_MSSQL_USE_DROPDOWN_QUERIES to FALSE, because a fewer number of queries need to be sent to the database. On the other hand, if you START files and stop reading after some condition, but have not used the WHERE constraint, you may get more efficient access by setting this variable to TRUE and using the drop-down style of query. In either case, run some tests to see which value makes the most sense for your application.

This variable is accessed only during a positioning operation, so you can set it at different times for different tables.

The default value is FALSE.

Example

A_MSSQL_USE_DROPDOWN_QUERIES TRUE
Parent topic: Configuration File Variables
Related reference
A_MSSQL_LIMIT_DROPDOWN configuration variable
Related information
The WHERE Constraint


A_MSSQL_VISION_LOCKS_FILE configuration variable

This locking method causes the lock table (AcuLocks) to be a Vision file instead of an SQL table. This can be accessed via the configuration variable A_MSSQL_VISION_LOCKS_FILE, which must be set to the full path and name of the Vision file that will hold the lock information. Note that you must also set a configuration variable that specifies this file as a Vision file (using a _host variable). This file must be accessible to all users accessing the Microsoft SQL Server, either through a common directory, or through AcuServer.

Also included with the Acu4GL for Microsoft SQL Server product is a small COBOL program that will manage this Vision file ("lockmgr"). This program should be run with the same runtime that you normally use to access Microsoft SQL Server tables, and with the same configuration variables set. The program detects whether Acu4GL for Microsoft SQL Server is available and detects the A_MSSQL_VISION_LOCKS_FILE variable to determine which file to manage. This program displays all the records in the lockfile and gives options for removing single records (by highlighting the desired record to remove), or removing all shown records, and also for restricting the shown records by PID, Table, and Database. This program also creates the Vision lock file and is the only method of creating the file. You can refresh the display by selecting the Restrict button and then pressing OK without restricting the display further.

If everything is working correctly, there should be no records in this table when there are no users accessing Microsoft SQL Server through Acu4GL. The source for this program is in the "sample/acu4gl" directory.

Parent topic: Configuration File Variables


Using the Database Table

The database table is built and accessed automatically when the COBOL application is executed. To the end user, the interaction between the COBOL and the MSSQL database is invisible; queries are generated and data is exchanged in fractions of a second, and the application proceeds without interruption.

You can also access the database information directly from MSSQL, at your option.

To create a sample COBOL application, see Preparing and Compiling a Program Example.

Parent topic: Appendix B: Acu4GL for Microsoft SQL Server


Table Locking

By default, MSSQL doesn't support the type of record and table locking that COBOL expects. For this reason, the Connector implements its own locking method. This is accomplished with the addition of two tables to a database. You choose the database to hold these tables during installation of Acu4GL.

Before using the locking tables, you must execute the included ms_inst.sql script. (See the installation instructions you used from this manual for the exact procedure. You can find them in the Contents.) If you don't perform this step, the first time you try to execute a COBOL program that opens an MSSQL table, error 11, Lock Table Incorrect, occurs.

AcuLocks1 Table

The first locking table is called AcuLocks1; it holds the record locks. The columns in this table are the

  • DBID
  • Table ID
  • Process ID of the process holding the lock
  • Primary key of the record that is locked

There is a unique index on the DBID, the Table ID, and the Key Value, so that inserts into this table are automatically rejected if another user holds a lock on the row in question. This also gives the DBA the information needed to determine who has locks set, and whether the user in question still has a connection to the server.

AcuOpenTables1 Table

The second locking table is called AcuOpenTables1; it holds information about open tables.

The columns in this table are

  • The DBID
  • The Table ID
  • The process ID (PID) of the process that has the table open
  • The Open Mode (Input, Output, I/O or Extend)
  • Whether Multiple records can be locked
  • Whether the file can be open for I/O by any other users
  • Whether the file can be open at all by any other users
  • Whether Mass Update was specified in the open

There are no indices on this table, but there is a trigger, which reject opens that are not allowed based on other users' open modes.

By using these lock tables, Acu4GL is able to support all the types of locking ordinarily supported. No special configuration variables are required.

This method of locking is all that is needed if no applications other than COBOL programs are going to be using Acu4GL for MSSQL. But if your site has other applications that access the MSSQL databases, you must use a method of locking that is inherent to Microsoft SQL Server.

Another method of locking that Microsoft SQL Server supports internally is the result of time stamping and the use of BROWSE MODE (see the discussion of BROWSE MODE in the Microsoft SQL Server Commands Reference Manual). If a table has a timestamp column, the Connector uses browse mode. This allows the server to detect whether another application has modified a record while locked by the server.

Parent topic: Appendix B: Acu4GL for Microsoft SQL Server


Stored Procedures

A stored procedure is a collection of SQL statements residing on the server, stored as text in a table in the database. Stored procedures provide an efficient environment for Acu4GL because, once they are executed on the server, they don't need to be parsed and optimized each time they are executed. (However, if the server goes down, the stored procedure is parsed and optimized when the procedure is called after the database restarts.)

If you run a set of stored procedures for the database where data is manipulated (your production database), this database must be the setting for A_MSSQL_LOCK_DB. If you run the stored procedures against both the lock database and the production database, the lock database can be the setting for A_MSSQL_LOCK_DB. Note that if you run one version of stored procedures against the lock database and another version against the production database, the stored procedures in the lock database override those in the production database. Therefore, we recommend that you always update your stored procedures with each new installation of Acu4GL for MSSQL, so that these procedures are consistent when you run them against the tables in your database.

Note: If you are updating from an earlier version of Acu4GL, be sure to install the new stored procedures. Stored procedures are always updated to be compatible with older versions of the product, so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software.
  • Developer- or Site-supplied Stored Procedures
  • Built-in Stored Procedures
Parent topic: Appendix B: Acu4GL for Microsoft SQL Server


Developer- or Site-supplied Stored Procedures

This topic provides information on stored procedures you may want to create. It also supplies some example code.

Acu4GL checks for these stored procedures when opening a file and uses them in certain circumstances.

These stored procedures are

  • tablename_insert (where tablename is the name of the table being accessed)

    The INSERT stored procedures takes as arguments all columns in order listed in the XFD. It expects no columns to be returned.

  • tablename_delete

    The DELETE stored procedure takes as arguments the primary key fields in the order they are listed in the XFD. It expects no columns to be returned.

  • tablename_read

    The READ stored procedure takes as arguments the primary key fields in the order they are listed in the XFD (in the key section). It expects the columns to be returned in order of condition. So all condition 0 columns are retrieved first, then condition 1 columns, etc. For each condition, the columns are expected in order given in the XFD

  • tablename_update

    The UPDATE stored procedures takes as arguments all columns in order listed in the XFD. It expects no columns to be returned.

  • tablename_startnnn (where nnn is the key number to start on)

    The STARTnnn stored procedure takes as arguments a mode string (EQ, LE, GT, GE, LT), and then all columns of key nnn in order listed in the XFD. It must execute raiserror 523409 'Record not found' if no rows match the search criteria.

Note: Acu4GL does not create these stored procedures or check their accuracy. It is possible to create stored procedures in such a way as to make Acu4GL for MSSQL completely inoperable. Acu4GL uses these stored procedures for performance reasons only.
  • tablename_delete stored procedure
  • tablename_insert stored procedure
  • tablename_read stored procedure
  • tablename_startnnn stored procedure
  • tablename_update stored procedure
Parent topic: Stored Procedures
Related information
tablename_insert stored procedure
tablename_delete
tablename_read stored procedure
tablename_update stored procedure
tablename_startnnn stored procedure


tablename_delete stored procedure

tablename_delete is used to DELETE a record from an XFD file. The parameters passed to the stored procedure are the values of the primary key, in the order they are listed in the XFD.

Based on the Sample XFD, you might want to create the following stored procedure for deleting records from a file:

create procedure ftestdat_delete
@ft2_key char(4)
as
delete from ftestdat where ftest2_key = @ft2_key

grant execute on ftestdat_delete to public
Parent topic: Developer- or Site-supplied Stored Procedures
Related information
tablename_insert stored procedure
Developer- or Site-supplied Stored Procedures
tablename_startnnn stored procedure
tablename_update stored procedure
tablename_read stored procedure


tablename_insert stored procedure

tablename_insert is used to WRITE a record to the file. The parameters passed to the stored procedure are the values of all the columns in the row, in the order of the columns in the database. The timestamp column and identity column (if present in the table) are not passed to the stored procedure.

Given the Sample XFD, you might want to create the following stored procedure for writing records to a file:

create procedure ftestdat_insert
@ft2_key char(4),
@ft2_key1_seg1 char(2),
@ft2_key1_seg2 char(2),
@ft2_altkey2 char(4),
@ft2_number char(9),
@ft2_info char(10)
as
insert into ftestdat (ftest2_key, ftest2_key1_seg1,
ftest2_key1_seg2, ftest2_altkey2, ftest2_number,
ftest2_info) values (@ft2_key, @ft2_key1_seg1,
@ft2_key1_seg2, @ft2_altkey2, @ft2_number, @ft2_info)
grant execute on ftestdat_insert to public
Parent topic: Developer- or Site-supplied Stored Procedures
Related information
Developer- or Site-supplied Stored Procedures
tablename_startnnn stored procedure
tablename_update stored procedure
tablename_read stored procedure
tablename_delete stored procedure


tablename_read stored procedure

tablename_read is used to read a random record (READ only, not READ NEXT or READ PREVIOUS). The parameters passed to the stored procedure are the values of the primary key, in the order they are listed in the XFD. The expected rowset is the columns in the first table (if secondary tables are used), or the columns of the table (if secondary tables are not necessary).

This stored procedure is very similar to tablename_start.

Parent topic: Developer- or Site-supplied Stored Procedures
Related information
Developer- or Site-supplied Stored Procedures
tablename_insert stored procedure
tablename_startnnn stored procedure
tablename_update stored procedure
tablename_delete stored procedure


tablename_startnnn stored procedure

tablename_startnnn is used to START a file. The nnn value is the key number to start on, and is 0 filled. For example, the start procedure for the primary key for table mytab is "mytab_start000".

Note: If A_MSSQL_NO_23_ON_START is set to Yes, the start stored procedure is disabled.

Because there can be up to 119 alternate keys, the Connector does not search for a start procedure unless, or until, it is used. The parameters passed to the stored procedure are a 2-char mode [it is a varchar(2) field], with one of the following values: ">", ">=", "=", "<=", or "<". The rest of the parameters are the columns of the key used to start. Because the ANSI specification for START includes information about the size of the key being used (and in particular allows partial keys), the start procedure is used only if an entire key is given to the start verb. This procedure is also special in that it does not return data, but needs to raise an error condition if the start fails. The way to raise the error condition from within the stored procedure is to include code similar to the following:

raiserror (523409,16,1 "Record not found")

The code 523409 is very important. It is the code searched for in setting the error condition from within Acu4GL. If you use a different number, your starts may succeed when they should actually fail.

For example, based on the Sample XFD, you can create the following stored procedure to start a file:

create procedure ftestdat_start001
@mode varchar(2),
@ft2_key1_seg1 char(2),
@ft2_key1_seg2 char(2)
as

if exists (select 1 from ftestdat where

(ftest2_key1_seg1 = @ft2_key1_seg1 and
((@mode = ">=" and ftest2_key1_seg2 >=@ft2_key1_seg2) or
(@mode = ">" and ftest2_key1_seg2 > @ft2_key1_seg2) or
(@mode = "=" and ftest2_key1_seg2 = @ft2_key1_seg2) or
(@mode = "<" and ftest2_key1_seg2 < @ft2_key1_seg2) or
(@mode = "<=" and ftest2_key1_seg2 <= @ft2_key1_seg2))))
return
if exists (select 1 from ftestdat where
(((@mode = ">=" or @mode = ">") and
ftest2_key1_seg1 > @ft2_key1_seg1) or
((@mode = "<=" or @mode = "<") and
ftest2_key1_seg1 < @ft2_key1_seg1)))
return
raiserror (523409,16,1 "Record not found")

grant execute on ftestdat_start001 to public

This table shows the codes that can be used when setting the error condition from within Acu4GL.

Code | Message
523401 | No table name given
523402 | Table must be in current database
523403 | Table does not exist
523404 | Internal error - no table id given
523405 | Internal error - Bad object id given
523406 | Table is open by another user
523407 | Table is write-locked by another user
523408 | Table is read-locked by another user
523409 | Record not found
Parent topic: Developer- or Site-supplied Stored Procedures
Related information
A_MSSQL_NO_23_ON_START configuration variable
Developer- or Site-supplied Stored Procedures
tablename_insert stored procedure
tablename_update stored procedure
tablename_read stored procedure
tablename_delete stored procedure


tablename_update stored procedure

tablename_update is used to REWRITE a record from the file. The parameters passed to the stored procedure are the values of all the columns in the row, in the order of the columns in the database. The timestamp column and identity column (if present in the table) are not passed to the stored procedure.

For example, based on the Sample XFD, you might want to create the following stored procedure for rewriting a record:

create procedure ftestdat_update
@ft2_key char(4),
@ft2_key1_seg1 char(2),
@ft2_key1_seg2 char(2),
@ft2_altkey2 char(4),
@ft2_number char(9),
@ft2_info char(10)
as
update ftestdat set
ftest2_key = @ft2_key,
ftest2_key1_seg1 = @ft2_key1_seg1,
ftest2_key1_seg2 = @ft2_key1_seg2,
ftest2_altkey2 = @ft2_altkey2,
ftest2_number = @ft2_number,
ftest2_info = @ft2_info
where ftest2_key = @ft2_key

grant execute on ftestdat_update to public
Parent topic: Developer- or Site-supplied Stored Procedures
Related information
Sample XFD
Developer- or Site-supplied Stored Procedures
tablename_insert stored procedure
tablename_startnnn stored procedure
tablename_read stored procedure
tablename_delete stored procedure


Built-in Stored Procedures

Several stored procedures come with Acu4GL for MSSQL. One, sp_AcuInit, provides a means for customized initialization. sp_AcuInit is not installed; you must create it to use it for connection-time set-up. The others return information based on the AcuOpenTables1 and AcuLocks1 tables.

Note: Names of several stored procedures end in _1, indicating the first version of the stored procedure. Whenever a stored procedure is updated, the extension is updated by one. This is why you can install new stored procedures without overwriting older ones. Be sure to install all stored procedures when you install Acu4GL for MSSQL.
sp_AcuInit | A procedure you can set up to do customized initialization
sp_AcuRemoveUnusedLocks_1 | Determines who is logged in and removes Process IDs that are no longer active on the system
sp_AcuTableReport_1 | Shows who is using the tables in the database at the time this procedure is run
sp_AcuUserCount_1 | Use this to track table and database activity to ensure that your database is running as efficiently as possible
sp_AcuZeroUserCount_1 | Removes all locks on a table and closes it
  • sp_AcuInit stored procedure
  • sp_AcuRemoveUnusedLocks_1 stored procedure
  • sp_AcuTableReport_1 stored procedure
  • sp_AcuUserCount_1 stored procedure
  • sp_AcuZeroUserCount_1 stored procedure
Parent topic: Stored Procedures


sp_AcuInit stored procedure

If the stored procedure sp_AcuInit exists, it is executed when the connection is made to the server. This is a procedure you can set up to do customized initialization. This stored procedure does not take any parameters and does not return any results. This optional stored procedure is executed for all connections by Acu4GL interface to the database, not just for the primary connection.

As an example of customized initialization, you can use this stored procedure to remove stale locks by calling sp_AcuRemoveUnusedLocks_1 (which is installed when all the other stored procedures are installed), or to limit access to the database by certain users during certain hours.

If sp_AcuInit returns an error, the connection is denied and the error is reported to the COBOL program. The method for returning an error is to execute the Transact-SQL statement "raiserror". See your Microsoft SQL Server documentation for information about Transact-SQL and stored procedures.

If the sp_AcuInit procedure exists, it executes whenever Acu4GL makes a new database connection, including FAST_ACCESS connections. Therefore, any customization that you've indicated via sp_AcuInit applies to all connections a transaction makes to the database, not just the primary connection.

Note: The sp_AcuInit procedure executes at connection time. It can exist in any database, but should reside either in the current database or a database in which stored procedures are searched by default (such as master).
Parent topic: Built-in Stored Procedures
Related information
sp_AcuRemoveUnusedLocks_1 stored procedure


sp_AcuRemoveUnusedLocks_1 stored procedure

Use this stored procedure to determine who is logged in and to remove Process IDs that are no longer active on the system. You can call this from sp_AcuInit each time a user connects to the database to ensure that the lock table contains only active locks. This stored procedure must reside in the same database as the AcuOpenTables1 and AcuLocks1 tables; it is placed there automatically when these tables are created during installation.

Parent topic: Built-in Stored Procedures
Related information
sp_AcuInit_1 stored procedure
Table Locking


sp_AcuTableReport_1 stored procedure

Use this stored procedure to learn who is using the tables in the database at the time this procedure is run. Run this procedure before running the sp_AcuZeroUserCount stored procedure, so that you can contact users to inform them that the database will be closing. This stored procedure must reside in the same database as the AcuOpenTables1 and AcuLocks1 tables; it is placed there automatically when these tables are created during installation.

Parent topic: Built-in Stored Procedures
Related information
sp_AcuZeroUserCount_1 stored procedure
Table Locking


sp_AcuUserCount_1 stored procedure

You can run sp_AcuUserCount from the query analyzer to learn how many users have a particular table open. You can use this to track table and database activity to ensure that your database is running as efficiently as possible. This stored procedure must reside in the same database as the AcuOpenTables1 and AcuLocks1 tables; it is placed there automatically when these tables are created during installation.

Parent topic: Built-in Stored Procedures
Related information
Table Locking


sp_AcuZeroUserCount_1 stored procedure

Use sp_AcuZeroUserCount to remove all locks on a table and close it. Be sure to run this stored procedure on all tables in the database if shutting down the database for any reason. This stored procedure must reside in the same database as the AcuOpenTables1 and AcuLocks1 tables; it is placed there automatically when these tables are created during installation.

Parent topic: Built-in Stored Procedures
Related information
Table Locking


Limits and Ranges

The following limits exist when working with MSSQL:
Maximum number of columns per key: | 16
Maximum number of columns: | 1024
Maximum number of bytes in a single row when using Acu4GL for MSSQL: | 8060

To achieve the same sort or retrieval sequence under MSSQL as under the file system, key fields that contain signed numeric data must be preceded by a BINARY XFD directive.

Acu4GL supports the data types shown below; when it's creating tables, the following conversion rules are used, in the sequence shown:

COBOL SQL Server
DATE XFD directive
DATETIME
BINARY XFD directive
VARBINARY(n) (if SIZE < 255)
IMAGE (if SIZE >255)
VAR_LENGTH XFD directive
VARCHAR(n) (if SIZE < 255)
Usage FLOAT
REAL (if SIZE = 4)
Usage DOUBLE
FLOAT (if SIZE = 8)

Any other numeric usage:

PIC 9(n)V9(m)
SMALLINT (if m = 0 and n < 5)
INT (if m = 0 and n < 10)
DECIMAL(n + m, m)(otherwise)

Any other usage:

PIC X(n)
CHAR(n) or NCHAR(n) (if n < 255)
(Note: NCHAR columns are dependent on the variable A_MSSQL_CREATE_UNICODE_COLUMNS set to TRUE)
TEXT (if n > 255)
Note: If the VAR_LENGTH XFD directive is in effect, VARCHAR and NVARCHAR types are created instead.

Other limits are described in Limits and Ranges of the ACUCOBOL-GT documentation.

Parent topic: Appendix B: Acu4GL for Microsoft SQL Server


Runtime Errors

Runtime errors will have this format:

9D/nn

The 9D indicates a file system error and is reported in your FILE STATUS variable. The xx is a secondary error code. These are the secondary errors reported directly from Acu4GL:

9D/01 Read error on dictionary file

An error occurred while reading the XFD file; this probably means the XFD is corrupt. Recompile with -Fx to re-create the dictionary. See Compiler and Runtime Options for additional information on compiler options.

9D/02 Corrupt dictionary file

The dictionary file for one of your COBOL files is corrupt and cannot be read. Recompile with -Fx to re-create the dictionary.

9D/03 Dictionary (.xfd) file not found

The dictionary file for one of your COBOL files cannot be located. Be sure you have specified the correct directory via your XFD_PREFIX runtime configuration file variable. You may need to recompile with -Fx to create the dictionary.

9D/04 Too many fields in the key

There are more than 16 fields in a key. Check your key definitions and restructure the key that is illegal, and then recompile with the -Fx option.

9D/06 Mismatched dictionary file

The dictionary file (.xfd) for one of your files conflicts with the COBOL description of the file FD. The xx indicates a tertiary error code that is defined by the host file system. You can determine the exact nature of the mismatch by referring to the host system’s error values.

The tertiary error code may have any of these values:

  • 01 – mismatch found but exact cause unknown (this status is returned by the host file system)
  • 02 – mismatch found in file’s maximum record size
  • 03 – mismatch found in file’s minimum record size
  • 04 – mismatch found in the number of keys in the file
  • 05 – mismatch found in primary key description
  • 06 – mismatch found in first alternate key description
  • 07 – mismatch found in second alternate key description

The list continues in this manner for each alternate key.

9D/11

ACUCOBOL-GT stored procedures not found or ACUCOBOL-GT lock table missing The installation of Acu4GL for Microsoft SQL Server creates a number of stored procedures and tables. At least one of these was not found.

9D/12

A column of a key is of data type TEXT or IMAGE, which is illegal Columns that are part of an index may not be of type TEXT or type IMAGE. Check your key definition.

9D/13

Internal error Multiple records were found with the same index (this is a Microsoft SQL Server error).

9D/14

DB library function returned an unexpected error dbinit (Microsoft SQL Server) failed. An error message from Microsoft SQL Server is displayed on the terminal.

9D/16

Trying to rename a table across databases RENAME works only within the same database.

9D/17

Cache error (internal error) The internal process cache has been corrupted. Please contact Technical Services.

9D/18

Primary Key error An error occurred when creating the primary key for a secondary table.

9D/19

Table Size Error The table is larger than Microsoft SQL Server will accept, either in the number of columns or in the number of bytes in the row. Use the SECONDARY_TABLE directive to get around this.

9D/20

(no message associated with this error) This error tells you that you are trying to do something with a FAST_ACCESS table that is not allowed. The description of the A_MSSQL_FAST_ACCESS configuration variable details the restrictions for tables opened this way.

9D/21

(no message associated with this error) There was a problem accessing one or more Vision locks files and processing of this request cannot continue. The tertiary error is an error code returned from Vision.

9D/22007

The error sub-code 22007 indicates tha an attempt was made to write non-numeric data into a numeric field (database column). It is reported with error code 9D. For example: report_status called from 3688 [1] 22018 0 - Invalid character value for cast specification No more messages Leaving, Execute Leaving, execute >>>file status = 9D/22007

24

Note that not all database errors are reported as 9D errors. The Acu4GL interface translates the following database errors to file status 24: 1101, 1105, 1118, 1510, 1703, 1803, 4504, 4706. Each of these errors is about the requested operation failing due to space considerations in the database. The runtime trace file must be examined to determine which error occurred and how to resolve it.

Parent topic: Appendix B: Acu4GL for Microsoft SQL Server


Common Questions and Answers

This topic contains some questions and answers specific to Acu4GL for MSSQL.

When I try to open a file for output, I get the error 9/83, with a secondary error of 2714. There is already an object named "*" in the database. Why?
One of your record's data items probably has the same name as an MSSQL reserved word. Locate the column by comparing a file trace of the CREATE TABLE to MSSQL's list of reserved words. Apply the NAME XFD directive to the field in the file descriptor (FD) that is associated with the invalid column, then recompile the program to create a new XFD file.
Can I open tables in different databases?
Yes. Use a file name like:
database.owner.tablename

Note that, because Acu4GL for MSSQL automatically determines an owner, you can also specify a file name like database..tablename. The two dots are mandatory in this case.

Can I use multiple servers (on the same machine or on different machines) on my network?
Yes. Each server has a unique name.
I'm getting an error 9/83, with a secondary error of 11, Micro Focus lock table missing. I know that I added the lock table during installation.
This is probably a permissions problem. All users must have READ, WRITE, UPDATE, and DELETE access to AcuLocks1 (and therefore to the database that contains it). Be sure to check your permissions.
I keep receiving an error message saying that my login is invalid. But I'm sure I'm using the correct username and password.
All usernames, passwords, and database names are case-sensitive. Be sure that you are typing the names exactly as they are set up.
Are there any library routines that do not work with or would not make sense to use with Acu4GL for MSSQL?
Two library routines that either don't work with or do not make sense to use with Acu4GL for MSSQL: C$COPY and C$RECOVER.
Parent topic: Appendix B: Acu4GL for Microsoft SQL Server


Appendix C: Acu4GL for Oracle

  • Oracle Concepts Overview
  • Installation and Setup
  • Oracle's Instant Client
  • Filename Translation
  • Configuration File Variables
  • Using the Database Table
  • Unsupported Features
  • Limits and Ranges
  • Data Type Mapping
  • Runtime Errors
  • Common Questions and Answers
Parent topic: Acu4GL Version 10.2.0 User's Guide


Oracle Concepts Overview

Acu4GL for Oracle is based on the Oracle Call Interface (OCI), an API that makes the code more portable to the maximum number of platforms.

This quick overview of some basic design concepts underlying the Oracle Database Management System relational database system (RDBMS) help to interface your COBOL program to it.

  • Transactions
  • Record Locking Issues in Transactions
  • Acu4GL and Record Locking
  • The open_cursors Parameter
  • Table Ownership
  • Security
Parent topic: Appendix C: Acu4GL for Oracle


Transactions

The Oracle RDBMS is a transaction-based system. All of the work that you perform while using Oracle must occur within a transaction, whether that work is being done through Acu4GL for Oracle or another 4GL application. When you use the Acu4GL, a transaction is implicitly started for you by the database engine itself with the first file I/O operation performed on a file associated with Oracle. Because all operations with Acu4GL occur within a transaction, any record locked during processing remains locked until either a COMMIT WORK or ROLLBACK WORK is issued by Acu4GL. This action results in behavior similar to the LOCK ON MULTIPLE RECORDS clause in COBOL.

The benefits of this transaction management system are best illustrated by an example. A COBOL application that handles order entry might perform these steps to accept an order:

  • Write an invoice record.
  • Update a customer record.
  • Write a payroll record for sales commissions.
  • Update an inventory record.

This series of four file operations is a logical unit. If the program were interrupted and had completed only some of the four file operations, the files would be in an inconsistent state. For example, if the program terminated unexpectedly after it updated the customer record, but before it updated the inventory record, a subsequent run might access non-existent inventory.

The solution to this problem is to provide a method for the programmer to define a set of operations that should either all occur or all not occur. Then, if the program encounters an error or terminates, the files are left in a consistent state.

All file operations that are part of a transaction are logged. Once logged, they can be either committed or rolled back (undone) by the program.

If a program dies or the system fails, the log file can be used to reconstruct complete transactions, returning all files to a consistent state. Transaction logging thus offers these two facilities:

  • It provides the programmer with the ability to define transactions and the ability to commit them or undo them (usually in response to an error condition); this undo facility is called a rollback
  • It provides the ability to reconstruct files into a consistent state after a program dies or system failure occurs; this operation is called recovery
Parent topic: Oracle Concepts Overview


Record Locking Issues in Transactions

Applications that are written for transaction management systems, or that perform work in small operation-based logical units, benefit greatly from Oracle's transaction management systems. Other applications may encounter difficulty with record locking when operating against a system (Oracle) that enforces transaction management.

The difficulty can occur with an application that is performing more than one logical task at a time. Any operation that modifies or reads data in an I/O mode without the WITH NO LOCK phrase causes a lock to be placed in the database system. As a result, the application may have many more record locks present than would be expected by the normal rule of COBOL file locking. The application would act similarly to when the LOCKS ON MULTIPLE RECORDS clause in COBOL is used. This can best be illustrated by an example:

  1. The user is entering a customer's order.
  2. As each line item is entered into the order, the inventory file is modified to reflect that items have been removed from the stock on hand.
  3. The user must switch to a different part of the application to perform a different task, perhaps as a result of a phone call from a new customer.
  4. All of the records that were locked, or modified, by the application before the switch remain locked because the first order is not complete. As no COMMIT or ROLLBACK has been issued, all of the records remain locked until the application ends, thus ending the transaction.
  5. Because one order is open and not yet committed, other applications may be locked out of certain order items if they are still locked by the processing of the first order. The second order entry may be held up until the first order is completed.

Note that the first application is not locked out. A process can read its own locked records.

Parent topic: Oracle Concepts Overview


Acu4GL and Record Locking

Acu4GL provides semi-automated ways to handle transaction logging based on the setting of the COMMIT_COUNT environment variable. You can also directly alter your source code to deal with this issue. Individual users determine how much work they wish to do to conform to the Oracle transaction management system by choosing the method that best fits their needs and resources. The following methods are listed in order of increasing amount of work:

COMMIT_COUNT = 0 (Default)

When you set this variable to zero (0), the run time system tracks the number of logical locks that are currently in effect. When the number of logical locks reaches zero, the run time system assumes that a transaction is complete and issues a COMMIT statement.

COMMIT_COUNT =n

When you set this variable to a nonzero value, the run time system tracks the number of WRITE, REWRITE, and DELETE operations, until the value of COMMIT_COUNT is reached, at which time the run time system issues a COMMIT statement. The READ, START, and READ NEXT operations do not count toward this total, because the run time system is tracking data-altering operations rather than logical record locks. The disadvantage of this method is that when a COMMIT is issued, any record locks held by the run time system are released.

COMMIT_COUNT = –1

No commit is issued by the Connector. When COMMIT_COUNT is set to 1, two alternate ways to perform a commit or rollback are available:

  • Call your Oracle query tool with COMMIT WORK or ROLLBACK WORK.
  • Use the COBOL verbs COMMIT and ROLLBACK, available in Acu4GL for COBOL.

COMMIT_COUNT is set to -1 automatically when you use the transaction management facilities available in ACUCOBOL-GT. A COMMIT WORK is, however, issued on exit from the run time system (for example, on execution of a STOP RUN).

COMMIT Verb in COBOL

This method forces a COMMIT to be sent to Oracle. It can be used in conjunction with other modes of COMMIT handling. For non-ORACLE files, this is equivalent to the UNLOCK ALL verb.

Explicitly Coded Transactions

This method provides the greatest flexibility in that transactions are specifically tailored for the user's application. This method also requires the most work for traditional COBOL programs in which transaction modules may not be clearly defined.

Parent topic: Oracle Concepts Overview
Related information
COMMIT_COUNT configuration variable


The open_cursors Parameter

The Oracle system parameter open_cursors should be set to enhance communication with the Connector. For more information, see Checking System Parameters.

Parent topic: Oracle Concepts Overview
Related information
Checking System Parameters


Table Ownership

Table names in Oracle have the form owner.table_name. If you are the owner of a given table, you can refer to it as just table_name. If you are not the owner, you must refer to it with the owner of the table as a prefix. Acu4GL provides a user-configurable method (the USER_PATH ACUCOBOL-GT runtime configuration file) for implementing this.

Parent topic: Oracle Concepts Overview
Related information
USER_PATH configuration variable


Security

Security is implemented in the Oracle RDBMS. A user is required to log in to the RDBMS before any file processing can occur. The Connector provides both a default and a user-configurable method for implementing this. Oracle's security considerations pose several challenges for COBOL programmers. Because of the various levels of permissions, certain operations are not allowed unless you have database administrator (DBA) privileges. These restricted operations include:

  • Creating a table under another user's name
  • Dropping a table owned by another user

Oracle versions 9i and later also provide additional security levels; however, you must consult the Oracle documentation to determine if any of these permission levels are appropriate for your site.

Generally, it is best for someone with DBA privileges to create and drop the tables, allowing others only the permissions to process information contained in them. A table can be referenced either by owner.table_name or by a public synonym that you have created for the table. See the Oracle documentation for more details on DBA privileges and public synonyms.

Note: By default, Acu4GL always checks to see if a public synonym is available for a file at open time, regardless of what USER_PATH is set to. If the name of a table owned by a current user is the same as a public synonym, the user-owned table is chosen.
Parent topic: Oracle Concepts Overview
Related information
USER_PATH configuration variable


Installation and Setup

The following section covers the client configuration required before using Acu4GL for Oracle on a new system.

Before you begin, you need to have:

  • Access to an already installed and configured Oracle database.
  • Configured any client software (if the server is on a remote machine), and verify a successful connection to the intended database.

The Oracle RDBMS must be installed and configured prior to this, which also includes the setting of any environment variables that may be required (such as ORACLE_HOME, ORACLE_SID, and LD_LIBRARY_PATH) - consult your Oracle documentation for details on this.

Typically, you'll install Oracle client software to connect to a database not on the current machine, and then set up a service name that references the database that you want to connect to. The easiest way to do that is to use Oracle's Net Configuration Assistant. This tool also allows you to test the connection to the database. Some other versions of Oracle may require you to set specific environment variables (such as ORACLE_HOME, and ORACLE_SID); again, consult your Oracle documentation for further details.

Client installation can also be achieved using Instant Client - a lightweight solution to the Oracle client install. If using this client, we recommend downloading the following components to help test your connection:

  • Oracle's SQL*Plus interactive query tool. SQL*Plus allows you to do database work outside of COBOL, including interactive queries, table creation, table modification, and creation of views, constraints, and relationships between tables.
  • Oracle's SCOTT/Tiger test schema. This is a schema that is installed by default on older Oracle versions. It can still be downloaded and installed separately, and is used for testing purposes.
Note: Micro Focus does not provide these downloads.

Once you have successfully connected to your Oracle database, continue with the Acu4GL-specific configuration.

  • Windows Installation Steps
  • UNIX Installation Steps
  • Completing the Installation
  • Checking System Parameters
  • Setting Up a User Account
  • Setting Up the User Environment
  • Designating the Host File System
  • Setting Up the Search Path
  • Handling Transactions
Parent topic: Appendix C: Acu4GL for Oracle


Windows Installation Steps

Typically, you'll install Oracle client software to connect to a database not on the current machine, and then set up a service name that references the database that you want to connect to. The easiest way to do that is to use Oracle's Net Configuration Assistant. This tool also allows you to test the connection to the database. Some other versions of Oracle may require you to set specific environment variables (such as ORACLE_HOME, and ORACLE_SID); again, consult your Oracle documentation for further details.

Client installation can also be achieved using Instant Client - a lightweight solution to the Oracle client install.

Note: You must be using version 9i or later of the Oracle RDBMS, and it must be installed and configured prior to the installation of Acu4GL for Oracle.
  • To Set Up a Service Name for an Oracle Database
Parent topic: Installation and Setup


To Set Up a Service Name for an Oracle Database

If you are using Oracle client software to connect to a database not on the current machine, you must set up a service name for your database. To set this up, you need the following details from your database administrator:

  • Service name
  • Protocol
  • Host name
  • Port

When you have these, you can use Oracle's Net Configuration Assistant, which is supplied with the Oracle client install. After entering the correct details, the wizard enables you to test the connection.

Tip: You can also test the connection using SQL*Plus: use user-name@service-name for the login.

If successful, you are ready to start configuring the Acu4GL client by editing the ACUCOBOL-GT runtime configuration file. These connection details equate to the A_ORA_DATABASE (service name), ORA_LOGIN (user-name), and ORA_PASSWD (password) configuration variables.

Parent topic: Windows Installation Steps
Related reference
A_ORA_DATABASE configuration variable
ORA_LOGIN configuration variable
ORA_PASSWD configuration variable


UNIX Installation Steps

The Acu4GL for Oracle product on UNIX is an add-on module that must be linked with the ACUCOBOL-GT run time system. For this reason, you'll need a C compiler to install the Acu4GL product. To interface, you must use the ACUCOBOL-GT compiler and runtime; the version of the run time must match the version of Acu4GL.

Acu4GL for Oracle is distributed as a tar file, which contains a shell script and a pax file. From a temporary directory, extract the tar file:

tar xvf setup_dbc2.1-32bit.tar

Then execute the shell script as root:

./setup_dbc2.1-32bit.sh

Follow the instructions. If you are installing a 64-bit version, replace the 32-bit above with 64-bit. This copies files from the distribution medium to your product directory structure.

Note that each Acu4GL product has its own license file that must be located in the same directory as the ACUCOBOL-GT runtime. For Oracle, the license file is distributed with the name "runcbl.olc".

Parent topic: Installation and Setup


Completing the Installation

With appropriate installation settings and procedures, Connector for Oracle communicates with versions 9i or later of Oracle.

To install the Acu4GL product, perform the following steps.

Step 1: Install Oracle

The Oracle RDBMS must be installed and configured prior to the installation of Acu4GL for Oracle.

We also recommend:

  • Oracle's SQL*Plus® product, which is an interactive query tool. This is not mandatory, but it gives you quite a bit of flexibility. SQL*Plus allows you to do database work outside of COBOL, including interactive queries, table creation, table modification, and creation of views, constraints, and relationships between tables.
  • Oracle's "scott/tiger" test schema, which can be used for testing. Micro Focus does not provide these products.

Make sure all environment variables Oracle requires, such as ORACLE_HOME, ORACLE_SID, and LD_LIBRARY_PATH (or equivalent, if necessary), are set up in the environment of each user accessing Acu4GL for Oracle (see your Oracle documentation for the list of variables required). Verify Oracle's setup and configuration using an Oracle tool, such as SQL*Plus. Also verify that the PATH references the necessary Oracle subdirectories.

Step 2: Create a new run time system

In the following directions, the term run-time system refers to the run time shared object on systems where the ACUCOBOL-GT run time is a shared object and to runcbl on other systems, where the run time is static. The run time is a shared object on the following systems: AIX 5.1 and later, HP-UX 11 and later, and Solaris 7 and later. To check, look at the contents of the lib subdirectory of your ACUCOBOL-GT installation. If your distribution is a static distribution, complete steps 2a and 2b below. For shared library distributions, continue to step 2c. You must ensure that both the AcuCOBOL lib directory and the Oracle client library are both in your LD_LIBRARY_PATH or LIBPATH variables depending on the system for the runcbl -vv command to list the Acu4GL for oracle version.

Complete steps 2a through 2c below to create a new run time that includes the Oracle Acu4GL product. You may also link your own C routines with the run time system.

2a. Execute the script

The ora_inst script is an interactive shell script that determines which libraries your version of Oracle has, and then creates a makefile suitable for linking Acu4GL for Oracle. In the instructions below, bold italicized text within a message indicates that the script inserts what you had previously typed.

Execute the shell script ora_inst by typing the following command:

sh  ora_inst

You may exit the script at any time by pressing the system interrupt key (usually CTRL+C).

This is the first message that you see:

If this script dies with an error like "VAL=0: command not
found", try executing it with a bourne shell, as in sh ora_inst

If the script does terminate, and if re-entering the command does not work, call Technical Services.

When the script begins executing, the following message is displayed (no response is needed):

We first need to determine where you have installed ORACLE.

If the environment variable ORACLE_HOME has been set, the script continues, and the next message you see is the version inquiry below. If ORACLE_HOME has not been set to the Oracle directory name, the installation script displays this message:

Enter the directory where ORACLE is installed:

Type the name of the directory in which you installed Oracle, and then press Enter.

The script then determines whether a directory by that name exists; if not, the script displays the following message:

entered directory isn't a directory.

and returns to the Enter the directory prompt to give you another chance. After you have entered a legitimate directory name, the script responds with:

Creating Makefile.ora ...
You should now be able to execute a make
with the command make -f Makefile.ora in
the ... ACUCOBOL-GT directory/lib

These are just informative messages.

Be sure to review the makefile.ora file and make adjustments as necessary.

2b. Link the run time system

If you need to link in your own C routines, add them to the SUBS= line of the file Makefile.ora. See Working with C and C++ Programs for details on linking C subroutines.

Make sure you are in the directory containing the ACUCOBOL-GT run time system. Then, at the UNIX prompt, enter the following command:

make clean

to ensure that you have a clean directory in which to build your runtime.

Now enter the following command:

make -f Makefile.ora

or

makerun

This compiles sub.c and filetbl.c and then links the run time system.

Make sure you have correctly set all of the flags specific to your platform correctly before you relink your library and object files. If the make fails because of an out-of-date symbol table, execute the following command:

ranlib *.a

and then execute the make again.

If the make fails for any other reason, call Technical Services.

If you are relinking your run time under SCO UNIX, you must add -lrpc -lsocket to the LIBS section of Makefile.ora. If you place them on a line by themselves, remember to place a backslash at the end of the previous line. You must also remove these two libraries from the ACUSERVER_LIBS line.

2c. Verify the link

Enter the following command:

./runcbl -vv
to verify the link.

This returns version information on all of the products linked into your run time system. Make sure it reports the version of Acu4GL for Oracle.

Shared libraries

If you have relinked the ACUCOBOL-GT run time and receive an error message of this type when you try to execute it:

"Could not load library; no such file or directory"
"Can't open shared library . . . "

this may mean that your operating system is using shared libraries and cannot find them. This can occur even if the shared libraries reside in the same directory in which you are currently located.

If the version of Oracle is not listed in the version information, try using the command ldd coba4ora32.so to determine which shared libraries can not be located.

Different versions of the UNIX operating system resolve this in different ways, so it is important that you consult your UNIX documentation to resolve this error.

Some versions of UNIX require that you set an environment variable that points to shared libraries on your system. For example, on an IBM RS/6000® running AIX® 4.1, the environment variable LIBPATH must point to the directory in which the shared libraries are located. On HP/UX, the environment variable that must be set to point to shared libraries is SHLIB_PATH. On UNIX SVR4, the environment variable is LD_LIBRARY_PATH. Note that the correct version of the ORACLE_HOME/lib should be in your LD_LIBRARY_PATH. This might be ORACLE_HOME/lib64 or ORACLE_HOME/lib, depending on what the default is for your system. If a lib32 directory exists, the 64-bit libraries may be the default. Please refer to your Oracle release notes for more information.

If the version of Oracle is not listed in the version information, you can try using the command ldd coba4ora32.so to determine which shared libraries can not be located.

Be sure to read the system documentation for your operating system to determine the appropriate way to locate shared libraries.

A second way to resolve this type of error is to link the libraries into the run time with a static link. Different versions of the C development system use different flags to accomplish this link. Consult the documentation for your C compiler to determine the correct flag for your environment.

Step 3: Copy runcbl to the correct directory

If the run time system is a statically linked runcbl, copy the new executable to a directory mentioned in your execution path. This file needs to have execute permission for everyone using the run time system. The copy step is not necessary when the run time system is a shared library.

The ACUCOBOL-GT license file for the run time (runcbl.alc) and the license file for the Acu4GL product to Oracle (runcbl.olc) must be copied into the same directory as the run time executable. If you rename your run time executable, be sure to rename your license files to base name, with the extensions unchanged. For example, if you rename your run time to be myprog.bin, the license file for the Acu4GL product for Oracle should be renamed myprog.olc, and the license file for the run time should be renamed myprog.alc.

The remaining files can be left in the directory into which they were installed from the distribution medium.

Parent topic: Installation and Setup


Checking System Parameters

Acu4GL makes use of cursor caching to process Oracle RDBMS data efficiently. A cursor is a prepared query, saved in a parameterized format. When a like function is to be performed on a different record (such as a GET NEXT), the task can be performed by executing the saved query with new parameters. This improves performance by eliminating the need to regenerate the query. You may need to adjust the number of cursors available to your COBOL application.

  • To set the system parameters
Parent topic: Installation and Setup
Related information
To set the system parameters


To set the system parameters

Set the Oracle system parameter OPEN_CURSORS to indicate the total number of cursors you want to have. Look in Oracle's init.ora and initSID.ora, or any other database initialization files used at your site, and add or modify the line:

open_cursors = nnn

The number of cursors can be equal to the number of keys times the number of segments per key for each file. For example, if you have 5 files, each of which has 3 keys, and each key has 3 segments, you should set OPEN_CURSORS to a minimum of "45".

Note: Setting OPEN_CURSORS should be performed only by your system administrator or database administrator, because it affects all applications using the database.
Parent topic: Checking System Parameters


Setting Up a User Account

For Acu4GL for Oracle to be able to communicate with the Oracle database, you must specify a valid user login that has the required read and write access to the database. For this, you can set up either one general account for all Acu4GL users or an account for each individual user. To set up an account, you must have database administrator (DBA) privileges.

Note: You may opt to use Oracle's Enterprise Manager on Windows platforms to simplify the login process. If you decide to use the Enterprise Manager, please refer to your Enterprise Manager documentation instead.
  • To Configure a Login
Parent topic: Installation and Setup


To Configure a Login

Note: You will probably need database administrator privileges to perform the following action.
If you want to specify a database login name other than the system login name, you can grant it the necessary privileges using the following SQL syntax, when connected to the database:
GRANT CONNECT, RESOURCE TO db_login_name IDENTIFIED BY
    password

where db_login_name is the name you want to use to log in to the database.

For more details on login, see your site's DBA and the Oracle Database Administrator's Guide.

Parent topic: Setting Up a User Account


Setting Up the User Environment

To configure the client environment for Acu4GL, you usually use an ACUCOBOL-GT runtime configuration file.

The minimum settings required would be the ORA_LOGIN, ORA_PASSWD, and A_ORA_DATABASE variables; refer to ACUFH Configuration File Variables for additional variables you can include. If you are accessing files that you do not personally own and that do not have public synonyms, you may also need to set USER_PATH.

You use the A_CONFIG environment variable to identify the ACUCOBOL-GT runtime configuration file, which allows you to create your own personalized copy of the file, to avoid impacting other users.

If you are concerned about including passwords in a configuration file, you can set these details in your COBOL program or environment. The following syntax is an example of how you can set a variable within your code:

SET ENVIRONMENT ORA_PASSWD TO user-entry
Parent topic: Installation and Setup


Designating the Host File System

If you are opening an existing file, all file systems linked into the run time system are searched for the named file. If, however, you are creating a new file, you must tell the run time system which file system to use. You accomplish this with one of the following ACUCOBOL-GT runtime configuration file variables.

DEFAULT_HOST filesystem

This designates the file system to be used for newly created files that are not individually assigned. For example,

DEFAULT_HOST ORACLE

means that all new files are Oracle files unless otherwise specified by another ACUCOBOL-GT runtime configuration file variable, which is:

filename_HOST filesystem

where filename is the file name, without any extension, named in the ASSIGN TO clause of your SELECT statement. This configuration variable is used to assign an individual data file to a file system. Any file so assigned use the designated file system, and not the one specified by DEFAULT_HOST. For example,

myfile_HOST ORACLE

means that myfile is under the Oracle file system.

You can use these ACUCOBOL-GT runtime configuration file variables in combination to assign your new files in a default with exceptions manner. For example, this set of entries:

DEFAULT_HOST ORACLE
afile_HOST DB2
bfile_HOST DB2

means that all new files except afile and bfile are assigned to Oracle, and those two files are assigned to DB2.

You can change the values of these variables during program execution by including in your code:

SET ENVIRONMENT "filename_HOST" TO filesystem

or

SET ENVIRONMENT "DEFAULT_HOST" TO filesystem

This enables you to change file systems during the execution of your program. (This is not the typical way to specify a file system; normally it is designated in the ACUCOBOL-GT runtime configuration file and is not changed in the COBOL program.)

Note: Acu4GL for Oracle allows you to create a table with an OPEN OUTPUT statement, just as you can create indexed files. The Oracle equivalent of a data file is a table, not a database. You must create a database for your Oracle tables before you run the COBOL program that creates the tables, just as you must create a directory for your files before you run a COBOL program that creates COBOL data files.
Parent topic: Installation and Setup


Setting Up the Search Path

If you own a file because you created it with OPEN OUTPUT from COBOL, or because you created it using SQL, you don't need to do anything more to access the file. However, if you want to access files that are owned by other users on the system and do not have public synonyms, you must provide the run time system with information on how to locate these files.

The USER_PATH ACUCOBOL-GT runtime configuration file variable is used by the run time system to locate files. The syntax for this variable is:

USER_PATH  user1 [user2]...

where the user argument may be either the name of a user on the system or a period (.), which indicates the files owned by yourself. For example, if you have the following settings:

ORA_LOGIN    =   OPS$ORACLE
ORA_PASSWD   =   DATA_FERIT
USER_PATH   =    barbara scott.

and then attempt to open for I/O the file myfile, the run time system uses the following search path:

OPEN I-O       barbara.myfile
OPEN I-O       scott.myfile
OPEN I-O       ops$oracle.myfile

Remember that another option for allowing access to a file to all users on the system is to create a public synonym for the file.

Parent topic: Installation and Setup
Related information
USER_PATH configuration variable


Handling Transactions

When a COMMIT WORK database command is issued, it terminates a transaction and makes all work permanent and accessible to other users. The Acu4GL for Oracle run time system issues this command automatically when no locks are held, but you can cause it to happen under other conditions by setting the value of the COMMIT_COUNT ACUCOBOL-GT runtime configuration file variable.

For direct control over the transaction logging facility in Oracle, use the transaction management features available with ACUCOBOL-GT; see Transaction Management.

You are now ready to prepare and compile your COBOL program and run the demonstration program. For additional information, see Examples of Preparing and Compiling a Program and The Demonstration Program.

Parent topic: Installation and Setup
Related reference
COMMIT_COUNT configuration variable
Examples of Preparing and Compiling a Program
Demonstration Program
Transaction Management


Oracle's Instant Client

Instant Client is a free-to-download, lightweight Oracle database client designed to allow you to run your applications without installing the standard Oracle client or having an ORACLE_HOME. You can use it in place of the standard Oracle client when using Acu4GL for Oracle.

Setting up Oracle Instant Client can be challenging and should be performed by advanced users only. You will need the Basic Lite and SQL*Plus packages, available from the Oracle web site. Follow Oracle's instructions to install and configure the products.

If you also installed the SCOTT/Tiger test schema, you can test the connection to the Oracle database using SQL*Plus before proceeding with the Acu4GL client install.

  • To Test the Installation of Oracle's Instant Client
Parent topic: Appendix C: Acu4GL for Oracle
Related information
To test the installation of Oracle's Instant Client


To Test the Installation of Oracle's Instant Client

Go to a different directory from the one on which you installed Oracle's Instant Client and enter the following command:

sqlplus scott@bigdb/tiger
select user from dual;

On UNIX, if this test is successful, relink the run time to use the Instant Client. For instructions on relinking, see Completing the Installation. The ora_inst script recognizes the Instant Client structure; just tell it the directory into which you installed the Instant Client when asked for the ORACLE_HOME setting.

On Windows, if this test is successful, you are ready to use the runtime. The Windows run time loads the Oracle Instant Client dynamically from the specified path. To verify that you have loaded the application successfully, enter:

 wrun32 -v

on the command line. You should see "Acu4GL ORACLE/OCI file system" included on the ACUCOBOL-GT window that is displayed.

Parent topic: Oracle's Instant Client
Related information
Completing the Installation


Filename Translation

As you prepare to work with Acu4GL for Oracle, you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and eXtended File Descriptor (XFD) files are formed and work together. For detailed information on XFDs, see XFDs.

When the compiler generates XFD files, it uses lowercase letters to name the XFD file. In addition, the compiler changes hyphens to underscores when naming the XFD file.

Through ACUCOBOL-GT runtime configuration file variables, the run time system translates the file name in the COBOL program into the filename that is passed to the open() function in the run time system. The open() function determines which file system to pass the request to, but does not change the name of the file.

At this point, Acu4GL translates the file name to uppercase letters and changes hyphens to underscores. This new name is the one that Acu4GL uses for references to the database table.

Parent topic: Appendix C: Acu4GL for Oracle


Configuration File Variables

These topics list the run-time configuration file variables that are specific to Oracle. Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in Run-time Configuration Variables.

  • A_ORA_DATABASE configuration variable
  • A_ORACLE_ERROR_FILE configuration variable
  • A_ORA_HINTS configuration variable
  • A_ORA_KEEP_START_CURSOR configuration variable
  • A_ORA_LIMIT_DROPDOWN configuration variable
  • A_ORA_MAX_FILE_CURSORS configuration variable
  • A_ORA_NLS_SORT configuration variable
  • A_ORA_RETURN_SUCCESS_INFO configuration variable
  • A_ORA_USE_PRIMARY configuration variable
  • A_ORA_WAIT_LOCK configuration variable
  • COMMIT_COUNT configuration variable
  • ECN-GL443
  • ORA_LOGIN configuration variable
  • ORA_PASSWD configuration variable
  • USER_PATH (for Oracle) configuration variable
Parent topic: Appendix C: Acu4GL for Oracle


A_ORA_DATABASE configuration variable

A_ORA_DATABASE specifies the name of a network service that you have set up to refer to a database using an Oracle tool such as "Net Configuration Assistant," or by manually editing tnsnames.ora.

Parent topic: Configuration File Variables
Related information
ORA_LOGIN configuration variable
ORA_PASSWD configuration variable


A_ORACLE_ERROR_FILE configuration variable

This configuration file variable allows you to map errors using a text file to supplement the default method of providing errors. By adding the name of the file that contains the actual error mapping to A_ORACLE_ERROR_FILE, database-specific errors are mapped to COBOL errors.

Note: Some messages related to COBOL I/O cannot be supplemented.

Example

A sample syntax for this variable would be:

A_ORACLE_ERROR_FILE=ORCLerrs

where ORCLerrs is a file of a specified format containing a mapping of database-specific errors to COBOL errors. One such entry might be:

1 DUPLICATE_RECORD
Parent topic: Configuration File Variables


A_ORA_HINTS configuration variable

This variable enables the Oracle Hints feature. The default value is 1 (on, true, yes). To turn off this feature, set it to 0 (off, false, no).

Oracle Hints can improve database performance considerably in some situations, by "strongly suggesting" to the Oracle query optimizer that it use a given index to process a query.

Note that keys must use your COBOL development system's naming convention for naming indexes in the database to use this function. For example, the primary key on the file ftest would be named "iftest_0".

Parent topic: Configuration File Variables


A_ORA_KEEP_START_CURSOR configuration variable

When a COBOL application performs a start operation, Acu4GL/Oracle builds a sequence of one or more SQL queries to satisfy the requirements of the start operation. When a result set is found that matches the criteria of the start operation, that key value is saved for use on a subsequent READ NEXT/PREVIOUS operation. The cursor used to locate the target key value is not left open in order to maximize concurrency. When a READ NEXT/PREVIOUS operation is subsequently performed, a new query is generated. This could result in a sequence of queries such as the following.

For the START operation:

WHERE ( partial_key1_seg1 = :w0 AND partial_key1_seg2 = :w1
 ) ORDER BY
    partial_key1_seg1 ASC, partial_key1_seg2 ASC,
partial_key1_seg3 ASC
For the READ NEXT operation:

WHERE ( partial_key1_seg1 = :w0 AND partial_key1_seg2 >= :w1
) ORDER BY
    partial_key1_seg1 ASC, partial_key1_seg2 ASC,
partial_key1_seg3 ASC

The configuration variable A_ORA_KEEP_START_CURSOR was created for this purpose.

Settings

FALSE | The current default. The interface functions as in previous versions.
TRUE | The cursor used for the start operation stays in an open state for use by subsequent operations. Setting this variable to TRUE eliminates the generation of the second SQL query for the READ operation.
Parent topic: Configuration File Variables


A_ORA_LIMIT_DROPDOWN configuration variable

When a sequence of START and READ NEXT/PREVIOUS operations are performed by an application, Acu4GJ/Oracle generates a sequence of queries to return the set of records matching the application's request. To improve performance, the interface generates a sequence of DROP DOWN queries based upon the key of reference's key segments going from the most specific subset using the most number of segments to the most general using the least number of segments.

For example if a key is described by:

03 MY-ALTKEY.
   05 MY-ALTKEY-SEG1        PIC X(2).
   05 MY-ALTKEY-SEG2        PIC X(2).
   05 MY-ALTKEY-SEG3        PIC X(2).

then a START followed by a sequence of READ NEXT operations might generate the selection criteria of:

WHERE MY-ALTKEY-SEG1 = :w0 AND MY-ALTKEY-SEG2 = :w1 AND
MY-ALTKEY-SEG3 >= :w3
WHERE MY-ALTKEY-SEG1 = :w0 AND MY-ALTKEY-SEG2 > :w1
WHERE MY-ALTKEY-SEG1 > :w0

This can improve performance in that the target for each query is kept to a minimal size. If a set of records is not required, the database does not need to spend the time building the working set. When a DROP DOWN does occur however, the subsequent working set can require a large amount of time to process, because it may be an order of magnitude greater number of records. Normally there is not a way for a COBOL application to instruct the interface to stop processing when it has finished with the records based on a given key segment.

The A_ORA_LIMIT_DROPDOWN variable provides this instruction. It allows an application to direct the interface not to perform DROP DOWN query generation and instead return end of file when the records matching the current query have been exhausted.

Settings

OFF | The current default. The interface will perform DROP DOWN queries.
PARTIAL | If the record positioning was performed by a START with a SIZE clause, such that the initial positioning was performed using fewer than the total number of columns in the key, the process will cease after all records matching the START columns have been exhausted.
FULL | If the record positioning was performed by a START without a SIZE clause, the process will cease after all records matching the START columns have been exhausted.
ALL | Regardless of what form of START was used for the initial positioning, the process will cease after all records matching the START columns have been exhausted.

This variable is performed at the time of each start, so the application may change its value.

Parent topic: Configuration File Variables


A_ORA_MAX_FILE_CURSORS configuration variable

This variable allows you to set the maximum number of cursors that the run time is allowed to have per file.

The default value for A_ORA_MAX_FILE_CURSORS is 0, meaning that the run time system uses all of the cursors that it can. Because each file must have access to at least two cursors, set this variable to a value greater than 2 if you want to specify a particular value. If all the allotted cursors for a file have been used, the least recently used cursor for that file is freed.

Note that this variable is read only at startup time, and should, therefore, be set in the ACUCOBOL-GT runtime configuration file.

Parent topic: Configuration File Variables


A_ORA_NLS_SORT configuration variable

This variable forces the sort order of returned records to be in a binary order. Set A_ORA_NLS_SORT to 1 to turn off the default binary order and use the native language sort (NLS) instead. The default is 0, which means that the sort order is not NLS order and will be binary.

This variable must be set before the first database file is accessed.

Parent topic: Configuration File Variables


A_ORA_RETURN_SUCCESS_INFO configuration variable

The Acu4GL/Oracle interface does not return a file error if a SQL operation results in an OCI_SUCCESS_WITH_INFO status code. The text associated with the status would however be printed to the error file if the application is run with tracing.

The A_ORA_RETURN_SUCCESS_INFO causes Acu4GL/Oracle to return an error 9D to the application on this status code. The application can then use the library routine C$RERR to retrieve additional information about the error.

A_ORA_RETURN_SUCCESS_INFO can be set to the following values:

  • If set to the default of FALSE, no file error returns to the application if Acu4GL receives a status code of OCI_SUCCESS_WITH_INFO. The text associated with the status code is however printed to the error file if the application is run with tracing.
  • If set to TRUE, a file status 9D returns to the application, which can then call C$RERR to return additional status codes and the text of the error message. The text associated with the status code is also printed to the error file if the application is run with tracing.
Parent topic: Configuration File Variables


A_ORA_USE_PRIMARY configuration variable

Acu4GL adds the segments of the primary key to the ORDER BY clause when reading on an alternate key that allows duplicates. This is done to insure that the keys are returned in a predictable order should the application change the direction it is reading the information in. Your application can now control whether or not this occurs.

Setting the variable A_ORA_USE_PRIMARY to FALSE will prevent the addition of the primary key segments to the ORDER BY clause for alternate keys allowing duplicates. The default of TRUE maintains the current functionality of adding the primary key segments. This variable is checked at the time of file open and may be set differently for different files.

Parent topic: Configuration File Variables


A_ORA_WAIT_LOCK configuration variable

This configuration variable determines the type of Oracle locks used: wait or nowait locks. The default is FALSE, nowait locks. This variable is read at file open time for each file.

Parent topic: Configuration File Variables


COMMIT_COUNT configuration variable

The value of COMMIT_COUNT indicates the conditions under which you want Acu4GL to issue an automatic COMMIT_WORK operation.

COMMIT_COUNT <value>

Valid values are:

0 | A commit is issued when no locks are held, either because all files that had locked records have been closed, or because a COBOL COMMIT verb has been issued. This is the default value
"n" | A commit is issued after n operations. WRITE, REWRITE, and DELETE count towards n; READ, START, and READ NEXT do not
-1

No commit is issued by Acu4GL when COMMIT_COUNT is set to -1; the alternatives when this is set:

  • Call your Oracle query tool with COMMIT WORK or ROLLBACK WORK
  • Use the COBOL verbs COMMIT and ROLLBACK, available in your COBOL development system

    COMMIT_COUNT is set to "-1" internally when you use the transaction management facilities available in ACUCOBOL-GT.

A COMMIT WORK, however, is issued on exit from the run time system (for example, on execution of a STOP RUN)

For information about supported features, see Supported Features for Oracle Information.

Parent topic: Configuration File Variables
Related information
Supported Features


ECN-GL443

In previous versions, if an Oracle database was created with NLS_CHARACTERSET set to AL32UTF8 and NLS_LENGTH_SEMANTICS to CHAR, a START within a COBOL program using Acu4GL to access the database encountered a 23 error, on a key that should have be found.

Version 8.1.2, ECN-GL443 modified this behavior. the new default behavior of the product is to cause the START to locate the desired record. If you encounter a problem with the new behavior, using the configuration variable ECN_GL443 and setting it to "N" will revert the product back to the original behavior.

Parent topic: Configuration File Variables


ORA_LOGIN configuration variable

ORA_LOGIN indicates the user name under which you want to connect to the database system.

Example

To connect to the database with the user name MYNAME, you would specify:

ORA_LOGIN  MYNAME

in the Acu4GL.

For information on user accounts, see Setting up a User Account.

Parent topic: Configuration File Variables
Related information
ORA_PASSWD configuration variable
A_ORA_DATABASE configuration variable


ORA_PASSWD configuration variable

ORA_PASSWD should be set to the password assigned to the database account associated with the user name specified by ORA_LOGIN.

Example

If the account with the user name has the associated password CW021535, you would specify:

ORA_PASSWD  CW021535

in the ACUCOBOL-GT runtime configuration file or the environment.

For a full login from a client to a remote server, you could have either of the following two settings:

ORA_LOGIN username
ORA_PASSWD userpass
A_ORA_DATABASE remotesrv

or

ORA_LOGIN username@remotesrv
ORA_PASSWD userpass

In this example, remotesrv is the net service name you have set up, as defined in A_ORA_DATABASE configuration variable.

Parent topic: Configuration File Variables
Related information
ORA_LOGIN configuration variable


USER_PATH (for Oracle) configuration variable

USER_PATH indicates the user name or names to be used when Acu4GL searches for files. The order of the names is significant. The syntax for this variable is:

USER_PATH  user1 [user2]...

where the user argument may be either the name of a user on the system, or a period ("."), which indicates the files owned by yourself.

The type of OPEN being issued for the file determines the effects of this setting.

Examples

If an OPEN INPUT or OPEN I/O is issued, and USER_PATH is defined in the ACUCOBOL-GT runtime configuration file, Acu4GL searches for a user of the named file in the following sequence of locations:

  1. The list of users in USER_PATH
  2. The public synonyms

The first valid file is opened.

If USER_PATH is defined and the current user is the owner of the file, the current user must be included as one of the users (as indicated by a "."). If this is not the case, even though the current user has created the table, it is not be found and a file error "35" appears. This circumstance can occur if the file was created with the OPEN OUTPUT phrase and "." is not an element in USER_PATH. When the table is created, the current user is the owner of that table. When the run time system attempts to open the table, the system does not look for tables owned by the current user unless USER_PATH is not set, or unless "." is part of the setting.

If an OPEN INPUT or OPEN I/O is issued, and no USER_PATH variable is in the configuration file, Acu4GL searches for a user of the named file in the following sequence of locations:

  1. The user named for login (ORA_LOGIN or OPS$username)
  2. Public synonyms

Acu4GL opens the first file that has a valid combination of user and file name.

If an OPEN OUTPUT is issued (whether USER_PATH is present or not), a new table is created with the owner being:

  • The name specified in ORA_LOGIN
  • The name constructed by automatic login

For information on automatic login, see Setting Up a User Account, and for information on the search path, see Setting Up the Search Path.

Parent topic: Configuration File Variables


Using the Database Table

The database table is built and accessed automatically when the COBOL application is executed. To the end user, the interaction between the COBOL and the Oracle database is transparent, as though they were part of one process.

You also can access the database information directly from Oracle, at your option.

To create a sample COBOL application, see Examples of Preparing and Compiling a Program.

Parent topic: Appendix C: Acu4GL for Oracle
Related reference
Examples of Preparing and Compiling a Program


Unsupported Features

OPEN ALLOWING READERS is not supported by Oracle. Your ACUCOBOL-GT runtime configuration file determines how to interpret this phrase. Set the variable STRENGTHEN_LOCKS to 1 to cause this phrase to be treated as OPEN ALLOWING NO OTHERS. Set the variable to 0 to cause the phrase to be treated as OPEN ALLOWING ALL. The default value is 0.

Transactions are enforced in Oracle. Within a transaction, records locked by I/O operations that modify, delete, or otherwise result in a COBOL record-lock, remain locked until a COMMIT WORK or a ROLLBACK WORK is issued, or until your COBOL program encounters a COMMIT or ROLLBACK verb. See COMMIT_COUNT configuration variable for more information.

Oracle does not support record encryption, record compression, or alternate collating sequences. You may include these options in your program; however, they are disregarded if specified.

The ACUCOBOL-GT utility program vutil cannot be used with Oracle files. Instead, use utilities supplied by Oracle.

Whenever you are using the library routine RENAME, you must specify that you are using indexed files. This information is passed by the value I in the fourth parameter.

Unless you have DBA privileges, or special privileges introduced in Oracle Version 9i, you cannot:

  • Delete a table you don't own
  • Create a table under another user's name
Parent topic: Appendix C: Acu4GL for Oracle
Related information
COMMIT_COUNT configuration variable


Limits and Ranges

The following limits exist when working with Oracle:

Maximum indexed key size: | 250 bytes
Maximum number of fields per key: | 16
Maximum number of columns: | 254
Maximum length of a char field: | 255
Note: The limits and ranges differ between releases of Oracle.

Other limits described in Limits and Ranges of the ACUCOBOL-GT documentation set apply.

Parent topic: Appendix C: Acu4GL for Oracle


Data Type Mapping

Acu4GL for Oracle supports the following data types.
COBOL | Oracle
PIC X | CHAR
PIC X(n) | CHAR(n)
PIC X(n) | VARCHAR2 (VAR_LENGTH directive is required)
PIC X(n) | RAW(n)
PIC 9(n) | NUMBER(n)
PIC 9(n) | RAW(n)
PIC 9(n)V9(m) | NUMBER(n+m, m)
example: PIC999V99 | NUMBER(5,2)
Oracle | COBOL
CHAR | PIC X
CHAR(n) | PIC X(n)
VARCHAR2 | PIC X(n) (VAR_LENGTH directive is required)
DATE | PIC 9(6) or PIC 9(8)
NUMBER(n) | PIC 9(n)
NUMBER(n, m) | PIC 9(n-m)V9(m)
RAW(n) | PIC X(n) or PIC 9(n) (BINARY directive is required)
example: NUMBER(4,3) | PIC9V999

Internally, Acu4GL for Oracle uses VARCHAR to prevent key fields that are all spaces from being converted to null.

These Oracle data types are not currently supported:

  • LONG
  • LONG RAW
Parent topic: Appendix C: Acu4GL for Oracle


Runtime Errors

This topic lists the Acu4GL error messages that could occur during execution of your program. The topic Performance and Troubleshooting, provides information on compile-time errors and also provides several methods for retrieving runtime errors.

Each message is followed by an explanation and a recommended recovery procedure.

Runtime errors will have this format:

9D/nnnn

The 9D indicates a file system error and is reported in your FILE STATUS variable. The nnnn is a secondary, database-specific error code. These are the secondary errors reported directly from Acu4GL for Oracle:

9D/03 Dictionary (.xfd) file not found

The dictionary file for one of your COBOL files cannot be located. Be sure you have specified the correct directory via your XFD_PREFIX configuration variable. You may need to recompile with the "-Fx option to create the dictionary. See Compiler and Runtime Options for additional information on compiler options.

9D/04

Corrupt dictionary file The dictionary file for one of your COBOL files is corrupt and cannot be read. Recompile with -Fx to re-create the dictionary. Note that this error may be caused by inappropriate application of a directive. Check all directives, and call Technical Services if you have questions.

9D/05

Too many fields in the key (more than 16 for Oracle) Check your key definitions and redefine the key that is illegal, and then recompile with -Fx.

9D/06

Mismatched dictionary file The dictionary file (.xfd) for one of your files conflicts with the COBOL description of the file FD. The xx indicates a tertiary error code that is defined by the host file system. You can determine the exact nature of the mismatch by referring to the host system's error values. The tertiary error code may have any of these values:

01 - mismatch found but exact cause unknown (this status is returned by the host file system)

02 - mismatch found in file's maximum record size

03 - mismatch found in file's minimum record size

04 - mismatch found in the number of keys in the file

05 - mismatch found in primary key description

06 - mismatch found in first alternate key description

07 - mismatch found in second alternate key description

The list continues in this manner for each alternate key.

9D/1001

Invalid Cursor The prepare portion is aged out of cache. Re-enter the code while invalidating the prepare portion.

Parent topic: Appendix C: Acu4GL for Oracle


Common Questions and Answers

What files do I need to link my C routines into Acu4GL?
You need to modify the file makefile.ora to add your C routines to the file and then relink your run time with the command make -f makefile.ora.
On HP-UX platforms, which type of COBOL run time system - non-threaded or multi-threaded - should I use when connecting to the database?
You need to use the multi-threaded RTS, because Oracle is multi-threaded. If you use the non-threaded RTS, you will get a database connection error, because HP-UX does not allow the mixing of multi-threaded and non-threaded code.
On other UNIX/Linux platforms, you can use either run time system.
When I try to open a file for output, I get the error 9/83, with a secondary error of 904 Invalid Column Name. Why?
One of your record's data items probably has the same name as an Oracle reserved word. Locate the column by comparing a file trace of the CREATE TABLE to Oracle's list of reserved words and then apply the NAME XFD directive to the column in question.
I created a table the last time I ran the application, and now I can't find it. Why?
This is probably a file (table) ownership problem. If you were running the application under a different user name when you created the file, that table may not be visible unless the creating user's name is listed in your USER_PATH ACUCOBOL-GT runtime configuration file variable.
Can Acu4GL support a full datetime format?
The finest time granularity that Oracle supports is one second. Fractions of a second are not supported. In order to achieve this, you must be sure the xfd date code is correct and specify a date-time string in your COBOL application, as opposed to just a date. For additional information, see the reference topic Date XFD directive.
Are there any library routines that do not work with or would not make sense to use with Acu4GL?
Yes. There are two. C$COPY and C$RECOVER either don't work with or do not make sense to use with Connector for Oracle.
Parent topic: Appendix C: Acu4GL for Oracle


Appendix D: Acu4GL for ODBC

These topics provide information specific to Acu4GL for ODBC.

  • ODBC Concepts
  • Installation and Setup
  • Filename Translation
  • Decimal Points
  • Configuration File Variables
  • Mixed-case SQL Identifiers
  • Record and Table Locking
  • Limits and Ranges
  • Driver Requirements
  • Data Type Mapping
  • Troubleshooting
  • Common Questions and Answers
Parent topic: Acu4GL Version 10.2.0 User's Guide


ODBC Concepts

With Acu4GL for ODBC, your application can access the most common database formats found on desktop computer systems, as well as relational database management systems on UNIX or Windows servers.

These topics give a brief overview of concepts you’ll need to work with ODBC.

  • What Is ODBC?
  • Origins of ODBC
  • Restrictions
  • ODBC Structure
Parent topic: Appendix D: Acu4GL for ODBC


What Is ODBC?

Open Database Connectivity (ODBC) is a library of standardized data access functions. It’s intended to give programmers a way to access and manipulate data in a variety of data sources.

ODBC operates in a way that is similar to Informix ESQL/C and Oracle Pro*COBOL®. The main difference is that ODBC offers the advantage of being able to access almost any data source.

With traditional call-level interfaces (CLI), you are required to learn the Application Programming Interface (API) for each data source. If you want to port an application from one data source to another, you must write a complete new access module.

ODBC was designed expressly to access almost any data source. It offers a standard API that can be used to manipulate data in a Microsoft Access database on your PC, or connect from your PC to an Oracle database on a UNIX host. It can even access files that are not databases, such as Btrieve data files and Excel spreadsheets.

Parent topic: ODBC Concepts


Origins of ODBC

ODBC is able to access a wide variety of file systems because it takes advantage of their common properties and common standards. For example, most of the popular database systems on the market today bear a strong resemblance to each other, both in functionality and in the methods they use to access data. This is because the major vendors’ products are based in whole or in part on the relational database concepts of E. F. Codd. ODBC makes use of these commonalties.

Shared standards also lend power to ODBC. Several groups have been working to set standards in the UNIX environment, where much of the database technology originated. These groups include the ANSI standards committee, the X/Open consortium, and the SQL Access Group. Together, these groups have devised much of the core technology that Microsoft has organized into ODBC.

Parent topic: ODBC Concepts


Restrictions

ODBC does not make your application instantly portable to any database or data source that has ODBC support. Many layers of software are involved in the data retrieval process, and each layer adds its own restrictions.

The major component that makes an ODBC connection work is the ODBC driver. See ODBC Structure for more information. The driver processes API function calls, submits SQL requests to a specific data source or DBMS, and returns results.

ODBC drivers are available from a variety of vendors and offer very different levels of support and performance. The sources of the data that the drivers connect to also offer very different capabilities in areas such as record locking, file operations, and transaction management. These differences in performance and capability can have a significant impact on your application.

Parent topic: ODBC Concepts
Related information
ODBC Structure


ODBC Structure

A quick overview of the components of ODBC will help you interface your COBOL program to ODBC-compliant data sources.

ODBC requires four components: an ODBC-enabled application, the ODBC driver manager, ODBC database drivers, and data sources. The following diagram indicates how these components work together in a single-tier environment.

Single-tier ODBC architecture

The following diagram indicates how these components work together in a multiple-tier environment.

Multiple-tier ODBC architecture

Application

The application is your COBOL program, or more precisely, the ACUCOBOL-GT runtime system together with Acu4GL for ODBC. The runtime generates the appropriate SQL queries to accomplish the file I/O task that your COBOL program is executing. This includes all file positioning and record locking. When the query results are returned to the ACUCOBOL-GT runtime system, they are mapped either to a COBOL record or to the appropriate COBOL status code, if one exists.

Driver Manager

The driver manager loads the ODBC driver. The driver manager then passes requests to the driver and returns results to the ACUCOBOL-GT runtime system. For the Microsoft Windows environment, the driver manager is called ODBC32.DLL for 32-bit architectures.

The driver manager is typically included with the ODBC driver and is often installed along with the driver. For some products, such as Microsoft Access and Excel, the driver manager is installed automatically if you choose the ODBC support option while installing the product. (The ODBC support option tends to be part of the custom install process.)

Driver

The driver processes ODBC requests and returns data to the driver manager and your application. If necessary, the driver translates the runtime’s SQL request into a form that is understood by the target data source.

Your application is not limited to communicating through just one driver, however. By setting the ACUFH configuration variable A_ODBC_DATASOURCE, you can direct the ACUCOBOL-GT runtime system to connect to a different driver for any given file. Simply set this variable before opening the indexed data file. The Acu4GL interface for ODBC will then handle connecting to the new data source and performing any operations necessary to open the file.

The driver is the most important feature of ODBC. ODBC drivers for a given data source may be available from many different vendors. They vary greatly in performance and in the options they provide for a given data source. Be sure to carefully review a data source driver to determine its level of performance.

Your Acu4GL for ODBC disks include a program that tests your ODBC driver for the various functions the Acu4GL product requires. This program is called DRVTST32.EXE. You initiate it by selecting the appropriate icon in the Acu4GL for ODBC program group. Please see Driver Requirements for instructions on using the driver test program. This topic also describes the minimal requirements that your driver must meet to work with Acu4GL for ODBC.

Data Sources

Data sources are the files or databases accessed by a driver. Each data source must be identified during setup.

Some data sources are simple to identify. For example, to access a text file, you would provide the name and location of the file. Some are more complex, though. For example, to access a UNIX-hosted database such as Oracle, you would identify the Windows drivers, Windows applications, network connections, and database information.

In Windows, you set up an ODBC data source in the Windows control panel, Administrative Tools dialog. After you double-click the Data Sources (ODBC) icon, an ODBC Data Source Administrator dialog is displayed. You must designate the driver, the data source, and any other information necessary to access the data. Setup procedures are described in detail in the Installation section.

The following diagram shows how the Acu4GL product fits into a single-tier environment.

Acu4GL for ODBC in a single-tier environment

The following diagram shows how Acu4GL fits into a multiple-tier environment.

Acu4GL for ODBC in a multi-tier environment

Parent topic: ODBC Concepts


Installation and Setup

The following sections describe the steps you must perform before you begin using Acu4GL for ODBC on a new system:

  • ODBC Installation
  • Installation of Acu4GL for ODBC
  • Setting Up Data Sources
  • Setting Up the User Environment
  • Designating the Host File System
  • Designating the Host Data Source
Parent topic: Appendix D: Acu4GL for ODBC


ODBC Installation

You must have installed and configured ODBC (Windows) or a supported ODBC driver manager (UNIX) before you install Acu4GL for ODBC. These products are not provided by Micro Focus, but may have been installed alongside any ODBC drivers or data sources that you have on your system. For example, if you have installed Microsoft Access on your computer, the Access drivers and ODBC may have been automatically installed.

Windows:

Follow these steps to determine whether you already have ODBC:

  1. Open the Windows control panel.
  2. Double-click the Administrative Tools icon, then select Data Sources (ODBC). (On older versions of Windows, select the 32-bit ODBC icon directly from the control panel.)

    The ODBC Data Source Administrator dialog box is displayed, showing all the data sources currently configured for your system.

    If the ODBC icon is not in your control panel, ODBC is probably not installed on your system. To install ODBC on your system, you have two options:

    • Buy an ODBC driver from a driver or database vendor and install it. ODBC is installed automatically.
    • Buy and install a Windows-based ODBC data source. The ODBC driver and ODBC will be one of the install options.

UNIX:

Note: The use of a driver manager is only supported on a shared libraries build of the extend Interoperability Suite.

The following supported ODBC driver managers are:

  • unixODBC (www.unixodbc.org)
  • DataDirect (www.progress.com)
  • iODBC (www.iodbc.org)

You need to configure the driver manager as per the vendor's instructions, and then when correctly configured, you need to ensure that the lib directory of the driver manager, and the lib sub-directory of your product installation directory is included in the LD_LIBRARY_PATH environment variable.

Parent topic: Installation and Setup


Installation of Acu4GL for ODBC

The Acu4GL product for ODBC is an add-on module. The ODBC Acu4GL product installation includes a .DLL (Windows) or .so (Linux/UNIX) file that is detected at run time.

Note: 32-bit drivers may be able to access a 64-bit database. Consult your driver vendor to be sure.
  • Installation
Parent topic: Installation and Setup


Installation

On Windows, Acu4GL is an installation option within the extend installer. On UNIX, Acu4GL is installed by default when the main installer is run.

Once the installation is complete, refer to the other topics in this section to set up your Acu4GL product for ODBC.

Be sure to set up your data source in the Windows control panel as instructed in Setting Up Data Sources, and then enter the data source name in the configuration variable A_ODBC_DATASOURCE. If your driver requires them, be sure to set A_ODBC_LOGIN and A_ODBC_PASSWD. Also set DEFAULT_HOST. Other configuration variables that may make finding and accessing tables faster and more precise are USER_PATH and A_ODBC_CATALOG.

Parent topic: Installation of Acu4GL for ODBC


Setting Up Data Sources

You will need to set up a data source name for any item you want to be able to access from Acu4GL for ODBC. On Windows, use the ODBC Data Source Administrator to add a data source. The exact steps required for this will vary for each individual driver, but the general steps for setting up an ODBC data source are:

  1. Open the Windows control panel and click Administrative Tools.
  2. Double-click the ODBC Data Sources.

    The ODBC Data Source Administrator dialog is displayed. This dialog lists all the data sources currently configured for your system.

  3. Double-click on the data source you plan to use to access a setup dialog. A subsequent window lets you add a description of the data source and allows you to supply other information the driver requires.

If the data source you want is not listed, choose Add to indicate which driver to use for the data source you will create. Remember, the exact steps required for setting up a driver vary greatly between drivers and driver vendors. Please refer to the driver’s documentation for precise details on this step. We recommend that you test the setup of your new data source. Many data sources come with a testing utility for this purpose.

Parent topic: Installation and Setup


Setting Up the User Environment

In addition to setting the variables required for ODBC, you will need to do the following:

  1. Ensure that your execution path contains the name of the directory in which you placed the runtime executable that includes Acu4GL for ODBC.
  2. Set the A_ODBC_LOGIN and A_ODBC_PASSWD variables, either in your environment or in the ACUCOBOL-GT runtime configuration file, if they are required for your data source. Also, consider whether or not setting the USER_PATH variable would be useful in your set up situation. For security reasons, it is best to set the password variable from your COBOL program by asking the user to enter a password and then executing:
    SET ENVIRONMENT "A_ODBC_PASSWD" TO user-entry
  3. You may want to make and use a personalized copy of the configuration file to avoid impacting other users. The ACUCOBOL-GT documentation describes how to use the A_CONFIG environment variable or the “-c” runtime option to identify a personal configuration file.
  4. Define any other configuration file variables you require for your unique environment. Possible variables define error map file location, locking method, commit count, commit timing, and BINARY/CHAR type conversion.

For detailed information on ACUCOBOL-GT configuration file variables, see Configuration File Variables.

Parent topic: Installation and Setup


Designating the Host File System

Each time the COBOL application creates a new file, it needs to know which file system to use. The run-time checks the file system to use when the file is opened. You provide the name of the file system with one of two run-time configuration file variables. The first is:

DEFAULT_HOST filesystem

This will designate the file system to be used for newly created files that are not individually assigned. For example,

DEFAULT_HOST ODBC

means that all new files will be ODBC files unless otherwise specified by the second configuration variable, which is:

filename_HOST filesystem

where filename is the file name, without any extension, named in the ASSIGN TO clause of your SELECT statement. This configuration variable is used to assign an individual data file to a different file system. Any file so assigned will use the designated file system, and not the one specified by DEFAULT_HOST. For example,

myfile_HOST VISION

means that myfile will be under the Vision file system. The ability to designate a different file system for certain files enables you to tailor your application to a specific customer’s needs or to implement an incremental conversion for a customer. With relational databases, this is particularly useful in that it allows you to tune an application for processing speed and resource requirements.

You can use these run-time configuration file variables in combination to assign your new files in a default with exceptions manner; for example, this set of entries:

DEFAULT_HOST VISION
afile_HOST ODBC
bfile_HOST ODBC

means that all new files except afile and bfile will be assigned to Vision, and those two files will be assigned to ODBC.

You can also change the values of these variables during program execution by including in your code:

SET ENVIRONMENT "filename_HOST" TO filesystem

or

SET ENVIRONMENT "DEFAULT_HOST" TO filesystem

This enables you to change file systems during the execution of your program. This is not the typical way to specify a file system; normally it is designated in the run-time configuration file and is not changed in the COBOL program.

Note:

The Acu4GL for ODBC product allows you to create an ODBC table with an OPEN OUTPUT statement, just as you can create Vision indexed files, if the data source driver allows for table creation. The ODBC equivalent of a Vision file is a table, not a database. You must create a database for your ODBC tables before you run the COBOL program that creates the tables, just as you must create a directory for your files before you run a COBOL program that creates Vision files.

Parent topic: Installation and Setup


Designating the Host Data Source

You must tell the run-time system which data source to use for your ODBC file. You accomplish this by setting the configuration variable A_ODBC_DATASOURCE to the exact name that you set up in the Windows ODBC driver manager. You can set this variable in your COBOL configuration file if using only one data source.

For example, if the data source you want to select is listed in the control panel ODBC window as:

MS Access Databases (Access Data (*.mdb))

you should add the following line to your configuration file:

A_ODBC_DATASOURCE MS Access Databases

If you used the Add option to configure a new data source driver, set A_ODBC_DATASOURCE to the personalized name that you entered in the Add window.

If you do not know the data source name in advance, or if you intend to use more than one data source, you may set the data source name dynamically at run time. In your COBOL program, you would add code similar to this prior to the statement that opens the file:

SET ENVIRONMENT "A_ODBC_DATASOURCE" TO "MS Access Databases"

You are now ready to use the sql.acu program, as outlined in the Getting Started.

After you learn about and use this utility, you next find out about preparing and compiling your COBOL program, followed by learning to use the demonstration program.

Parent topic: Installation and Setup
Related concepts
Using the sqlacu Program
Related information
Preparing and Compiling Your COBOL Program Example


Filename Translation

As you prepare to work with Acu4GL for ODBC, you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together.

When the COBOL compiler generates XFD files, it uses lowercase letters to name the XFD file. In addition, the compiler changes hyphens to underscores when naming the XFD file.

Through configuration variables, the runtime translates the name in the COBOL program into the filename that is passed to the open() function in the runtime. The open() function determines which file system to pass the request to, but does not change the name of the file.

Acu4GL for ODBC translates the name to lowercase letters and changes hyphens to underscores unless the configuration variable, 4GL_COLUMN_CASE, is set. This “new” name is the one that Acu4GL for ODBC will use in the future for references to database tables.

Parent topic: Appendix D: Acu4GL for ODBC
Related information
4GL COLUMN CASE configuration variable


Decimal Points

Acu4GL for ODBC reads the decimal point character from the environment variable DECIMAL_POINT. If DECIMAL_POINT is set, Acu4GL uses that character. If the variable is not set, Acu4GL uses the decimal character that is encoded in the XFD file.

The two most common decimal indicators are the period “.” and the comma “,” characters. The comma is used often in European code and is often indicated in COBOL programs by the "DECIMAL POINT IS COMMA" clause.

Parent topic: Appendix D: Acu4GL for ODBC


Configuration File Variables

These topics list the runtime configuration file variables that are specific to Acu4GL for ODBC. Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in Runtime Configuration Variables.

  • 4GL_COLUMN_CASE configuration variable
  • 4GL_MAX_DATE configuration variable
  • 4GL_MIN_DATE configuration variable
  • 4GL_JULIAN_NULL configuration variable
  • A_ODBC_ALTERNATE_COMMIT_LOGIC configuration variable
  • A_ODBC_CATALOG configuration variable
  • A_ODBC_COMMIT_ON_BEGIN configuration variable
  • A_ODBC_DATASOURCE configuration variable
  • A_ODBC_ERROR_MAP_FILE configuration variable
  • A_ODBC_ISOLATION_LEVEL configuration variable
  • A_ODBC_LOCK_METHOD configuration variable
  • A_ODBC_LOGIN configuration variable
  • A_ODBC_NO_NULL_COLUMNS
  • A_ODBC_PASSWD
  • A_ODBC_PRINT_LOG configuration variable
  • A_ODBC_QUOTE_IDENTIFIERS configuration variable
  • A_ODBC_STRICT_EQUAL configuration variable
  • A_ODBC_TABLE_TYPES configuration variable
  • A_ODBC_UNSIGNED_TINYINT configuration variable
  • A_ODBC_USE_CATALOG configuration variable
  • A_ODBC_USE_CHAR_FOR_BINARY configuration variable
  • A_ODBC_USE_SPACE_IN_DATES configuration variable
  • A_ODBC_USE_SQLCOLUMNS configuration variable
  • A_ODBC_USE_SQLTABLES configuration variable
  • USER_PATH
Parent topic: Appendix D: Acu4GL for ODBC


4GL_COLUMN_CASE configuration variable

When set to unchanged, this variable causes the runtime system to leave the case and hyphen usage of the field names found in XFDs unchanged. XFDs are used with the Acu4GL interface, AcuXDBC, or AcuXML. By default, the run-time system converts all field names to lower case and all hyphens to underscores.

For AcuXML, the case and hyphen usage of the XFD must match the XML file exactly, and 4GL_COLUMN_CASE should be set to unchanged. For Acu4GL, however, you should be aware that most databases do not accept hyphens in column names. If you set this variable to unchanged to protect case, you may need to modify the XFD by hand to replace hyphens with underscores.

Parent topic: Configuration File Variables


4GL_MAX_DATE configuration variable

It is possible that invalid dates can be incorrectly written to the database. Invalid dates are written as NULL, but if the date is in the key, problems can occur. To avoid invalid date problems in this instance, use the 4GL_MAX_DATE configuration variable to set the high-value date.

The format is:

4GL_MAX_DATE = YYYYMMDD

The maximum date for 4GL_MAX_DATE is “20991231” (December 31, 2099).

See also: 4GL_MIN_DATE configuration file variable

Parent topic: Configuration File Variables


4GL_MIN_DATE configuration variable

As noted with the configuration variable 4GL_MAX_DATE, invalid dates can be incorrectly written to the database. Invalid dates are written as NULL, but if the date is in the key, problems can occur. To avoid invalid date problems in this instance, use the 4GL_MIN_DATE configuration variable to set the low-value date.

The format is:

4GL_MIN_DATE = YYYYMMDD

The default date for 4GL_MIN_DATE is “19000101” (January 1, 1900).

See also: 4GL_MAX_DATE configuration file variable.

Parent topic: Configuration File Variables


4GL_JULIAN_NULL configuration variable

This configuration variable indicates whether a Julian date should be considered NULL. Set it to TRUE (ON, YES, 1) to consider a Julian date NULL. The default is FALSE (OFF, NO, 0).

Parent topic: Configuration File Variables


A_ODBC_ALTERNATE_COMMIT_LOGIC configuration variable

The primary purpose of the configuration variable 4GL_COMMIT_COUNT is to provide for applications that must communicate with a transaction-oriented database but have not explicitly coded transactions into their COBOL application.

The configuration variable A_ODBC_ALTERNATE_COMMIT_LOGIC determines how the interface will respond to the setting of 4GL_COMMIT_COUNT. When A_ODBC_ALTERNATE_COMMIT_LOGIC is set to 0 or FALSE (the default), the value of 4GL_COMMIT_COUNT is checked only at startup. The interface will issue a commit when the criteria set by 4GL_COMMIT_COUNT is met, regardless of the current transaction state.

When A_ODBC_ALTERNATE_COMMIT_LOGIC is set to 1, the value of 4GL_COMMIT_COUNT is checked after each WRITE, REWRITE, DELETE, or UNLOCK operation. A commit is issued, however, only if the run time is not currently in a transaction. For example

4GL_COMMIT_COUNT=1
A_ODBC_ALTERNATE_COMMIT_LOGIC=0

Each WRITE operation is committed to the database immediately. This prevents an application from being able to rollback a WRITE.

See Also: 4GL_COMMIT_COUNT runtime configuration variable

Parent topic: Configuration File Variables


A_ODBC_CATALOG configuration variable

This variable indicates the catalog name to be used when Acu4GL searches for objects in the database. Note that not all data sources will support a catalog. Using A_ODBC_CATALOG with other variables, such as USER_PATH and A_ODBC_TABLE_TYPES, can speed up the finding of tables in large databases. It can also prevent an error 9D,14: More than one table with the same name, thereby enabling access to tables with identical names, but with different catalogs.

For example, If USER_PATH and A_ODBC_CATALOG are used, the form of the SQL statement is modified from:

select COL1, ... from TABLENAME ...

to

    SELECT COL1, ... FROM [catalog.][username.]TABLENAME ...

where catalog and username are filled in if provided.

See Also: USER_PATH (for DB2) configuration variable, USER_PATH (for Oracle) configuration variable, and A_ODBC_TABLE_TYPES.

Parent topic: Configuration File Variables


A_ODBC_COMMIT_ON_BEGIN configuration variable

ODBC has no START TRANSACTION method. Everything since the last COMMIT or ROLLBACK is considered part of the current transaction.

To ensure that the previous transaction has been ended before a new one begins, set A_ODBC_COMMIT_ON_BEGIN to a nonzero value. This causes each COBOL START TRANSACTION to first issue a COMMIT to all applicable ODBC drivers in use. This ensures that the previous transaction has been ended before the new one starts.

If this variable is not set, or is set to 0, a COBOL ROLLBACK may affect file I/O that occurred before the most recent COBOL START TRANSACTION. While the default value is 0 (or OFF, FALSE, or NO), this configuration variable can also take values of ON (TRUE or YES).

Parent topic: Configuration File Variables


A_ODBC_DATASOURCE configuration variable

Set A_ODBC_DATASOURCE to the exact name of the data source that you established in the Windows ODBC driver manager. You can set this variable in your COBOL configuration file if you will be using only one data source.

For example, add this line to your configuration file if the data source you want to select is listed in the Windows ODBC driver manager window as MS Access Databases (Access Data (*.mdb))

A_ODBC_DATASOURCE MS Access Databases

If you do not know the data source name in advance, or if you intend to use more than one data source, you may set the data source name dynamically at run time. In your COBOL program, you would add code similar to this prior to the statement that opens the file:

SET ENVIRONMENT "A_ODBC_DATASOURCE" TO "data source name"

There is no default value for this variable. If you do not enter a name, ODBC uses the default ODBC driver.

Parent topic: Configuration File Variables


A_ODBC_ERROR_MAP_FILE configuration variable

Because there are so many drivers available for ODBC, you may find that data source error codes don’t necessarily map well to COBOL error codes. To solve this problem, Acu4GL for ODBC allows you to create an error map file to map native database errors to COBOL errors. Create this file using the guidelines described below, and then use the configuration file variable, A_ODBC_ERROR_MAP_FILE, to indicate the name and location of the file you created.

For example, specify this in the rum time configuration file if the file used for mapping is called MAP, and this file is located in the directory C:\ODBC:

A_ODBC_ERROR_MAP_FILE  c:\ODBC\MAP

There is no default value for this variable.

Guidelines for creating a map file

Although you can check your data source documentation for error code information, the easiest way to determine what error codes need to be mapped to more appropriate COBOL codes is through trial and error. As users use Acu4GL for ODBC, they may report receiving error messages that don’t make sense based on their situation. Research these errors and try to determine a more appropriate COBOL error response.

When you create your error map file, use the following guidelines:

  • Begin comment lines with #. Blank lines are also considered comments.
  • Break the rest of the file into sections, with each section header comprising all the information enclosed in brackets from the data source error function.

    For example, if the data source returns this error:

    OdbcOneInfo: State: S1000, Native Error: -346
[Visigenic][ODBC Informix 5 Driver][Informix]Could not update a row in the table.

    make your section header:

    [Visigenic][ODBC Informix 5 Driver][Informix]
  • Include two fields in each line in the section: the internal error number, and a mapping string.

    Using the same example, if you wanted to map the Visigenic Informix driver error, -346 Could not update a row in the table to the COBOL error, Not found, you would include this line in the section:

    -346 E_NOT_FOUND

    Other Visigenic Informix error maps would follow in the same section. If you use other drivers, you could use multiple sections.

    The valid values for the second field are as follows:

    • E_SYS_ERR
    • E_PARAM_ERR
    • E_TOO_MANY_FILES
    • E_MODE_CLASH
    • E_REC_LOCKED
    • E_BROKEN
    • E_DUPLICATE
    • E_NOT_FOUND
    • E_UNDEF_RECORD
    • E_DISK_FULL
    • E_FILE_LOCKED
    • E_REC_CHANGED
    • E_MISMATCH
    • E_NO_MEMORY
    • E_MISSING_FILE
    • E_PERMISSION
    • E_NO_SUPPORT
    • E_NO_LOCKS

Through experience, we have discovered specific ways to better map errors for some drivers. For a list of these driver error mapping suggestions, look at the file odbcerrs on your installation disks.

Parent topic: Configuration File Variables


A_ODBC_ISOLATION_LEVEL configuration variable

Use the A_ODBC_ISOLATION_LEVEL configuration variable to set the isolation level. The default ordering of isolation levels is:

  • SQL_TXN_READ_COMMITTED
  • SQL_TXN_READ_UNCOMMITTED
  • SQL_TXN_REPEATABLE_READ
  • SQL_TXN_SERIALIZABLE

You can change the isolation level by setting the configuration variable A_ODBC_ISOLATION_LEVEL to an integer in the configuration file. The settings are:

Isolation level | Setting in configuration file
SQL_TXN_READ_UNCOMMITTED | 1
SQL_TXN_READ_COMMITTED | 2
SQL_TXN_REPEATABLE_READ | 3
SQL_TXN_SERIALIZABLE | 4

For example, to set the isolation level to SQL_TXN_READ_COMMITTED, add the following entry to the configuration file:

A_ODBC_ISOLATION_LEVEL 2

If the user-set isolation level is not supported by the driver, the default method of selecting a level is used.

Parent topic: Configuration File Variables


A_ODBC_LOCK_METHOD configuration variable

Use this variable to specify the locking method that the Acu4GL product should use when accessing your data source. Possible values are:

  • none
  • SETPOS
  • SETSTMTOPTION
  • UPDATECOLUMN

For example:

A_ODBC_LOCK_METHOD UPDATECOLUMN

The default value is none, meaning that the Acu4GL product will do nothing special to lock your data. This does not necessarily mean that your data won’t be locked. Locking depends mainly on your data source and driver. No value simply tells Acu4GL for ODBC not to perform any locking functions.

Note: Setting this variable may affect certain ODBC drivers. Locking depends mainly on the data source and the driver. You can use this variable to attempt to induce row locking. If none of the settings cause any rows to be locked, or if the machine stops responding, please report this behavior to Technical Services.
Parent topic: Configuration File Variables


A_ODBC_LOGIN configuration variable

A_ODBC_LOGIN indicates the user name under which you want to connect to the database system. Not all data sources require a user login name. Those that do may have case requirements. Check your data source documentation to determine if login is case-sensitive.

Example

To connect to the database with the user name MYNAME, specify one of these in the run time configuration file.

A_ODBC_LOGIN MYNAME

or

A_ODBC_LOGIN myname

There is no default value for this variable. If no login is specified, none is used.

See also: A_ODBC_PASSWD

Parent topic: Configuration File Variables


A_ODBC_NO_NULL_COLUMNS

When set to TRUE, ON or YES, the interface does not insert NULL into the database. While the default value is OFF (FALSE or NO).

Parent topic: Configuration File Variables


A_ODBC_PASSWD

The variable A_ODBC_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_ODBC_LOGIN. Not all data sources require a password. Those that do may have case requirements. Check your data source documentation to determine if password is case-sensitive.

For example, specify the following in the run time configuration file if the account with the user name in A_ODBC_LOGIN has the associated password CW021535:

A_ODBC_PASSWD  CW021535

For better security, you can accept a password from the user during program execution; set the A_ODBC_PASSWD variable based on the response:

ACCEPT RESPONSE NO-ECHO.
SET ENVIRONMENT "A_ODBC_PASSWD" TO RESPONSE.
Note:

If the user has been set up without a password, this variable need not be set. There is no default value for this variable. If no password is specified, none is used.

Parent topic: Configuration File Variables


A_ODBC_PRINT_LOG configuration variable

This variable is used for debugging only, and is best used under the direction of a Micro Focus SupportLinerepresentative.

See Contacting Micro Focus for information on contacting a Technical Services representative.

Parent topic: Configuration File Variables
Related information
Contacting Micro Focus


A_ODBC_QUOTE_IDENTIFIERS configuration variable

A_ODBC_QUOTE_IDENTIFIERS tells the Acu4GL product whether to test for the IDENTIFIER-QUOTE-CHAR, and to use it if it is found. If this variable is nonzero, and if the driver returns information about the IDENTIFIER-QUOTE-CHAR, all identifiers sent in SQL to the driver will be quoted. This is useful for using Microsoft Excel, for example, if the spreadsheet has column names with quotes or other strange characters. Notice that some drivers mistakenly report that they can handle quoted identifiers, which is why this variable is needed.

If you set this variable to a nonzero value, and start getting errors table not found or column not found, this variable should not be used when communicating with that driver.

The default value is 0 (or OFF, FALSE, or NO). This configuration variable can also take values of ON, TRUE, or YES.

Note:

This variable is useful with Oracle, this variable is not recommended.

See Mixed-case SQL Identifiers for information on using mixed-cased identifiers.

Parent topic: Configuration File Variables


A_ODBC_STRICT_EQUAL configuration variable

When Acu4GL for ODBC executes a START … KEY EQUAL keyval, the interface generates a SELECT statement to select all rows with a key equal to the key columns in keyval. When fetching the data, Acu4GL eventually detects that there is no more data. If A_ODBC_STRICT_EQUAL is set to TRUE at the time the START is executed, the interface returns the error END OF FILE (error 10) at this point. If A_ODBC_STRICT_EQUAL is set to FALSE (the default), Acu4GL for ODBC then generates a new SELECT statement to continue reading records until the end of the file rather than the subset of records represented by keyval, and these records may be discarded by the program. (Note that this is program-dependent behavior.) Setting A_ODBC_STRICT_EQUAL to TRUE causes the interface to stop reading records earlier, which can make SELECT statements generated by Acu4GL for ODBC more efficient.

A_ODBC_STRICT_EQUAL has these conditions:

  • A_ODBC_STRICT_EQUAL must be set to TRUE when the START is executed.
  • The START must be a KEY EQUAL start.
  • There must be no COMMITs between the START and the end of the file. Because most ODBC drivers close all cursors on COMMIT and ROLLBACK (according to the ANSI 92 SQL standard), the interface must regenerate a SELECT the first time it attempts to execute a READ NEXT after a COMMIT or ROLLBACK. For most drivers, this means that the 4GL_COMMIT_COUNT configuration variable should be set to -”, so that no COMMITs are issued by Acu4GL for ODBC. See 4GL_COMMIT_COUNT for additional information.
  • A_ODBC_STRICT_EQUAL is most useful with alternate keys that allow duplicates.
Note:

This same behavior can be accomplished with the 4GL_WHERE_CONSTRAINT, but using A_ODBC_STRICT_EQUAL requires less programming.

The default value is FALSE (or OFF, NO, or 0). This configuration variable can also take the value TRUE, ON, YES, or 1.

Parent topic: Configuration File Variables


A_ODBC_TABLE_TYPES configuration variable

This variable is used to specify a table type (TABLE, VIEW, and so forth) that should be looked for when selecting a database table. Using A_ODBC_TABLE_TYPES with other variables, such as USER_PATH and A_ODBC_CATALOG, can speed up the finding of tables in large databases.

This information is passed to the API function call SQLTables() as the TableType parameter. Please refer to your driver’s documentation for supported types.

for example:

A_ODBC_TABLE_TYPES  TABLE,VIEW

See also: USER_PATH configuration variable, A_ODBC_CATALOG configuration variable

Parent topic: Configuration File Variables


A_ODBC_UNSIGNED_TINYINT configuration variable

Some ODBC drivers may assign the TINYINT data type, a signed 1-byte variable that can store values from -128 to 127, to an internal unsigned type that can store values from 0 to 255. To determine if your ODBC driver does this, set a PIC s99 variable to a negative value and then write a record. If a value out of range message is returned, set A_ODBC_UNSIGNED_TINYINT to a nonzero value. As a result, PIC s99 variables are stored in a larger type (usually INT) that allows negative values.

The default value is 0 (OFF, FALSE, or NO). This configuration variable can also take values of ON, TRUE, or YES.

Parent topic: Configuration File Variables


A_ODBC_USE_CATALOG configuration variable

Not all data sources will support a catalog, or the data sources may return a catalog name that is not useful. For example, Microsoft Access returns the full path to the database, which is not needed since this information is detailed in the datasource.

The default behavior of the runtime is to not use the catalog in the actual SQL queries. This configuration variable enables you to modify this behavior. The default value is FALSE, which causes the catalog portion of the table name to be treated as blank in SQL queries. Setting this variable to TRUE causes the value of the catalog returned by SQLTables ODBC function to be used in subsequent SQL queries.

See also: USER_PATH (for DB2) configuration variable, USER_PATH (for Oracle) configuration variable, and A_ODBC_CATALOG

Parent topic: Configuration File Variables


A_ODBC_USE_CHAR_FOR_BINARY configuration variable

Some data sources have restrictions on the number of binary large objects (BLOBs) that can be placed into a single table. If your data source has such restrictions, specify A_ODBC_USE_CHAR_FOR_BINARY in the configuration file. The possible values for this variable are:

  • 0 = use BINARY type
  • 1 = use CHAR type

If A_ODBC_USE_CHAR_FOR_BINARY is set to a nonzero value, you can store data that uses the BINARY directive as hexadecimal encoded CHAR types. This allows you to work around your data source restriction. The default value is 0 (or OFF, FALSE, or NO), This configuration variable can also take values of ON, TRUE, or YES.

For example:

A_ODBC_USE_CHAR_FOR_BINARY 1
Parent topic: Configuration File Variables


A_ODBC_USE_SPACE_IN_DATES configuration variable

Some ODBC drivers require spaces when sending dates or time stamps to the data source. For data sources that require spaces between the d and the quote ('), set the configuration variable A_ODBC_USE_SPACE_IN_DATES.

For example:

Set MYDATE={d '1999-3-20'}

(note that there is a space between d and ' )

Setting the A_ODBC_USE_SPACE_IN_DATES configuration variable to “1” causes the Acu4GL for ODBC product to use syntax as above, instead of:

Set MYDATE={d'1999-3-20'}

(note that there is not a space between d and ' )

Keep in mind that it is possible that all data sources may allow a space between the d and the ', and that it is always safe to set this variable.

The default value is 0 (or OFF, FALSE, or NO). This configuration variable can also take values of 1 (ON, TRUE, or YES).

For example:

A_ODBC_USE_SPACE_IN_DATES 1
Parent topic: Configuration File Variables


A_ODBC_USE_SQLCOLUMNS configuration variable

For some large databases, the API function SQLColumns(), which is called to get a description of the columns in a table, sometimes takes a long time to execute. If you are experiencing such problems, you can use the API function call SQLDescribeCol() instead, which can improve performance for large databases.

To turn on this new functionality, set the A_ODBC_USE_SQLCOLUMNS configuration variable to FALSE.

The default value of this variable is TRUE, which means the interface will use the SQLColumns() API function.

Parent topic: Configuration File Variables


A_ODBC_USE_SQLTABLES configuration variable

For some large databases, the API function SQLTables(), which is called to get a list of the tables and information about them, sometimes takes a long time to execute. If you are experiencing such problems, you can instruct the interface to build a test SQL query and use the API function call SQLNumResultCols() to determine if the table exists. This may improve performance for large databases.

To turn on this new functionality, set the A_ODBC_USE_SQLTABLES configuration variable to FALSE.

The default value of this variable is TRUE, which means the interface will use the SQLTables() API function.

Parent topic: Configuration File Variables


USER_PATH

USER_PATH indicates the user name or names (schemas) to be used when Acu4GL searches for files. The order of the names is significant. The syntax for this variable is:

USER_PATH  user1 [user2]...

where the user argument may be either the name of a user (schema) on the system, or a period (“.”), which indicates the files owned by yourself.

The type of OPEN being issued for the file determines the effects of this setting.

Examples

If an OPEN INPUT or OPEN I/O is issued, and a USER_PATH variable is defined in the runtime configuration file, Acu4GL searches for a user of the named file in the list of users in USER_PATH. The first valid file is opened.

If USER_PATH is defined and the current user is the owner of the file, the current user must be included as one of the users, as indicated by a “.” or the setting of your login schema (A_ODBC_LOGIN) in the USER_PATH. If this is not the case, even though the current user has created the table, it will not be found and a file error 35 will result. This circumstance can occur if the file was created with the OPEN OUTPUT phrase, and “.” is not an element in USER_PATH. When the table is created, the current user will be the owner of that table. When the runtime attempts to open the table, the runtime will not look for tables owned by the current user unless USER_PATH is not set, or unless “.” or the user’s current schema is part of the USER_PATH setting.

If an OPEN INPUT or OPEN I/O is issued, and no USER_PATH variable is in the runtime configuration file, Acu4GL searches for a user of the named file in the user named for login (A_ODBC_LOGIN). Acu4GL opens the first file that has a valid combination of user and file name.

If an OPEN OUTPUT is issued (whether USER_PATH is present or not), a new table is created with the owner being the name specified in A_ODBC_LOGIN.

Using USER_PATH with other variables such as A_ODBC_CATALOG can speed up the finding of tables in large databases. It can also prevent an error 9D/14: More than one table with the same name, thereby enabling access to tables with identical names, but with different schemas.

For example, If the USER_PATH and A_ODBC_CATALOG are used, the form of the SQL statement will be modified from:

select COL1, ... from TABLENAME ...

to:

SELECT COL1, ... FROM [catalog.][username.]TABLENAME ...

where catalog and username will be filled in if provided.

See Also: A_ODBC_LOGIN and A_ODBC_CATALOG

Parent topic: Configuration File Variables


Mixed-case SQL Identifiers

Identifiers in SQL-92 are not case-sensitive. However, drivers that do not conform strictly to SQL-92 may require mixed-case identifiers.

If your driver enforces a mixed case, do the following:

  1. Compile your source COBOL program with the “-Fc” option to generate mixed-case identifiers in your XFD files.
  2. Modify the filename in your COBOL program to match the target identifier’s case.
  3. In your configuration file, set the configuration variable 4GL_COLUMN_CASE to “UNCHANGED”.

    Possible values are UPPER, LOWER, UNCHANGED.

Parent topic: Appendix D: Acu4GL for ODBC


Record and Table Locking

Acu4GL for ODBC supports record locking for multi-user systems, as long as your ODBC driver supports record locking. To complement your driver’s locking method, Acu4GL for ODBC can initiate three locking sequences:

  • SETPOS
  • SETSTMTOPTION
  • UPDATECOLUMN

You specify which type of locking you want to use with the configuration file variable, A_ODBC_LOCK_METHOD. However, if your driver doesn’t support locking, Acu4GL for ODBC by itself cannot provide locking.

Record locking with ODBC drivers is a semi-random activity. Different ODBC drivers have different capabilities and even implement the same capabilities in different ways. For this reason, you will have to do some experimentation to determine which locking method to specify for A_ODBC_LOCK_METHOD. Only through trial and error will you be able to determine which method will lock records in the most efficient way for your particular ODBC driver.

Parent topic: Appendix D: Acu4GL for ODBC


Limits and Ranges

The following limits exist for the ODBC protocol:

  • Maximum number of columns per key: depends on driver/database
  • Maximum number of columns: depends on driver/database

Acu4GL allows an unlimited number of columns, but the database may have a limit, and the driver may have a smaller limit than the database. If you have too many columns, you will receive a database error on the table create (for example, open output).

To achieve the same sort or retrieval sequence under ODBC as under the Vision file system, place a BINARY directive immediately before each key field that contains signed numeric data. High values and low values can cause problems in key fields. If you want data that uses the BINARY directive to be stored as hexadecimal encoded CHAR types, you can specify A_ODBC_USE_CHAR_FOR_BINARY in the configuration file. Please note that this could potentially increase the size of your key beyond the driver maximum.

Other limits are described in Limits and Ranges of the ACUCOBOL-GT documentation.

Parent topic: Appendix D: Acu4GL for ODBC


Driver Requirements

Your ODBC driver must include the following functions:

  • all Core ODBC driver functions
  • the Level 1 function SQLColumns
  • the Level 1 function SQLTables

Depending on the method of record locking you choose, your driver may also need to support some of the following function calls. See A_ODBC_LOCK_METHOD for more information.

  • SQLSetStmtOption
  • SQLSetScrollOptions
  • SQLExtendedFetch
  • SQLSetPos

To test the capabilities of your ODBC driver, we have included a driver test program on your Acu4GL for ODBC installation disks. You can also consult your driver documentation to ensure that it meets these requirements.

Parent topic: Appendix D: Acu4GL for ODBC


Data Type Mapping

Overview of ODBC data types

ODBC defines certain generic data types, which every data source driver maps to its own internal types. Each driver needs to be queried about which types it supports, because different drivers support different types.

The types that Acu4GL for ODBC uses, if they exist in the driver, are:

  • SQL_CHAR
  • SQL_VARCHAR
  • SQL_DECIMAL
  • SQL_NUMERIC
  • SQL_SMALLINT
  • SQL_INTEGER
  • SQL_REAL
  • SQL_FLOAT
  • SQL_DOUBLE
  • SQL_TINYINT
  • SQL_BIGINT
  • SQL_BINARY
  • SQL_VARBINARY
  • SQL_LONGVARBINARY
  • SQL_DATE
  • SQL_TIMESTAMP

For example, Informix maps these types like this:

SQL_CHAR | CHAR
SQL_VARCHAR | VARCHAR
SQL_DECIMAL | DECIMAL or MONEY
SQL_NUMERIC | no such type
SQL_SMALLINT | SMALLINT
SQL_INTEGER | INTEGER or SERIAL
SQL_REAL | REAL
SQL_FLOAT | no such type
SQL_DOUBLE | FLOAT
SQL_TINYINT | no such type
SQL_BIGINT | no such type
SQL_BINARY | no such type
SQL_VARBINARY | no such type
SQL_LONGVARBINARY | BYTE
SQL_DATE | DATE
SQL_TIMESTAMP | DATETIME YEAR TO FRACTION(5)

Informix also defines a type that ODBC calls SQL_LONGVARCHAR, and Informix calls TEXT, which the Acu4GL for ODBC product doesn’t use.

Notice that Informix has two types that match the ODBC SQL_DECIMAL type, and two that match the SQL_INTEGER type. The Acu4GL product will usually use the first type that it finds that matches an ODBC type, unless there are restrictions on that type. For example, the SERIAL type is limited in that a table can have only one such column, while a typical table may have more than one column of integer data.

So the Acu4GL for ODBC product will use the Informix INTEGER type, instead of the SERIAL type for integer data.

For another example, MS Access maps these types like this:

SQL_CHAR | CHAR
SQL_VARCHAR | TEXT
SQL_DECIMAL | no such type
SQL_NUMERIC | CURRENCY
SQL_SMALLINT | SHORT
SQL_INTEGER | LONG or COUNTER
SQL_REAL | SINGLE
SQL_FLOAT | no such type
SQL_DOUBLE | DOUBLE
SQL_TINYINT | BYTE
SQL_BIGINT | no such type
SQL_BINARY | BINARY
SQL_VARBINARY | VARBINARY
SQL_LONGVARBINARY | LONGBINARY
SQL_DATE | no such type
SQL_TIMESTAMP | DATETIME

Access also defines types, SQL_BIT = BIT and SQL_LONGVARCHAR = LONGTEXT which the Acu4GL for ODBC product doesn’t use.

Mapping COBOL data types to ODBC data types

When the Acu4GL for ODBC product creates a table, it uses what it determines to be the best match of a data type for any particular column.

This means that the database column will be able to hold any data that the COBOL data type can hold, and is as close as possible to the type of data that the COBOL program is using. This determination is based in part on what data types the data source has available. Obviously, if a data source doesn’t support some data type, the Acu4GL for ODBC product can’t use it with that data source. The actual algorithm used is rather complicated, but the general rules are as follows:

  • User preferences take precedence. This means that the XFD directives specified are checked first. Therefore, when data should be of type DATE or BINARY, a DATE or BINARY type is located and used, if the data source supports it.
  • If the COBOL data type is usage float or usage double, a data source type of FLOAT, REAL, or DOUBLE is used, depending on what is available. If none of these is available, the Acu4GL product abides by the next rule.
  • If the COBOL data type is numeric, a numeric type is used in the data source. The numeric type chosen depends on how large the COBOL data type is, and how many digits to the right of the decimal point (if any) there are.
    • For example, if the COBOL data type is PIC 99, the data source types checked for are TINYINT, SMALLINT, INTEGER, BIGINT, DECIMAL, NUMERIC, CHAR. The first of these that exists is the type that will be used for that column.
    • For another example, if the COBOL data type is PIC 9(6)v99, the data source types checked for are DECIMAL, NUMERIC, DOUBLE, FLOAT, REAL, CHAR. Again, the first of these types that exists is the type that will be used for that column.
    • Anything else will use CHAR.

Occasionally, you may encounter a data source type that supports only type CHAR (which is the only data type that is guaranteed to exist, according to the ODBC specification). Under these data sources, all the COBOL data types will be mapped to CHAR types.

Mapping ODBC data types to COBOL data types

Sometimes developers are in a situation where they need to create a COBOL File Description based on an existing data source table. The most important thing to understand in this situation is that there is almost nothing that you can do wrong! When the Acu4GL product opens a data source table, the only thing it checks is that the column names match the COBOL data names.

When the Acu4GL product reads data from the data source, it essentially does a COBOL-style MOVE from the native data type to the COBOL data type, whatever it is. And since most types have a CHAR representation (in other words, you can actually display most data types, using a standard ODBC-capable tool), using PIC X(nn) for each column will work perfectly well.

A better general rule is to use a COBOL type that closely matches the data source data type, but don’t worry about getting an exact fit. So you can use PIC 9(9) whenever the data source has an INTEGER type.

If you have more information about the data source type, you might be able to use a different COBOL representation. For example, if you know that a particular column in an ODBC data source has values only in the range 0 – 999, you could use PIC 999 for your COBOL data. The COMP-type you use is really determined by your own preferences, and should have little bearing on the COBOL data type you choose.

If you want to somehow choose your COBOL data types so that there is a best fit, you can use the following mapping:

SQL_CHAR | PIC X(nn) nn =size of item
SQL_VARCHAR | PIC X(nn) nn = maximum size of item
SQL_DECIMAL | PIC 9(n)v9(m)
SQL_NUMERIC | PIC 9(n)v9(m)
SQL_SMALLINT | PIC 9(5) COMP-5
SQL_INTEGER | PIC 9(9) COMP-5
SQL_REAL | USAGE FLOAT
SQL_FLOAT | USAGE FLOAT
SQL_DOUBLE | USAGE DOUBLE
SQL_TINYINT | PIC 9(3) COMP-5
SQL_BIGINT | PIC 9(9) COMP-5
SQL_BINARY | PIC X(nn)
SQL_VARBINARY | PIC X(nn)
SQL_LONGVARBINARY | PIC X(nn)
SQL_DATE | PIC 9(6) or PIC 9(8)
SQL_TIMESTAMP | USAGE DISPLAY
Note:

The BINARY data types are usually of a form that COBOL can’t understand anyway. You will usually just read these columns, and rewrite them unchanged. If you have more information about the data in the columns, you might be able to do something else, but this requires more knowledge about the columns.

The DECIMAL, NUMERIC, DATE, and TIMESTAMP types usually have special representations in a data source, which really doesn’t match any COBOL data type exactly. When the Acu4GL product binds the data (a technical term), it asks the data source to return it in character form, so the most efficient COBOL data type would probably be USAGE DISPLAY.

Parent topic: Appendix D: Acu4GL for ODBC


Troubleshooting

These topics list the Acu4GL error messages that could occur during execution of your program. Performance and Troubleshooting provides information on compile-time errors and also provides several methods for retrieving runtime errors.

An explanation and a recommended recovery procedure follow each message.

Note:

Often, errors are generated for the simple reason that the ODBC driver version you are using is incompatible with Acu4GL for ODBC. If you encounter errors when using Acu4GL for ODBC, run the driver test program found on your installation disks to determine if you are using a compatible driver version. See Driver Requirements for more details on the driver test program.

  • Runtime Errors
  • Native SQL Errors
Parent topic: Appendix D: Acu4GL for ODBC


Runtime Errors

Runtime errors will have this format:

9D/nn

The 9D indicates a file system error and is reported in your FILE STATUS variable. The nn is a secondary error code. These are the secondary errors reported directly from Acu4GL:

9D/01 Read error on dictionary file

An error occurred while reading the XFD file; this probably means the XFD is corrupt. Recompile with -Fx to re-create the dictionary. See Compiler and Runtime Options for additional information on compiler options.

9D/02 Corrupt dictionary file

The dictionary file for one of your COBOL files is corrupt and cannot be read. Recompile with -Fx to re-create the dictionary.

9D/03 Dictionary (.xfd) file not found

The dictionary file for one of your COBOL files cannot be located. Be sure you have specified the correct directory via your XFD_PREFIX runtime configuration file variable. You may need to recompile with -Fx to create the dictionary.

9D/04 Too many fields in the key

There are more than 16 fields in a key. Check your key definitions and restructure the key that is illegal, and then recompile with the -Fx option.

9D/06 Mismatched dictionary file

The dictionary file (.xfd) for one of your files conflicts with the COBOL description of the file FD. The xx indicates a tertiary error code that is defined by the host file system. You can determine the exact nature of the mismatch by referring to the host system’s error values.

The tertiary error code may have any of these values:

  • 01 – mismatch found but exact cause unknown (this status is returned by the host file system)
  • 02 – mismatch found in file’s maximum record size
  • 03 – mismatch found in file’s minimum record size
  • 04 – mismatch found in the number of keys in the file
  • 05 – mismatch found in primary key description
  • 06 – mismatch found in first alternate key description
  • 07 – mismatch found in second alternate key description

The list continues in this manner for each alternate key.

9D/11 ODBC connection missing needed functionality

Because ODBC has so many implementations, we require certain minimal functionality. This includes the ability to list columns, list primary keys, list existing tables, and support Level 1 SQL. Your ODBC driver lacks one or more of these capabilities.

9D/12 ODBC library function returned an unexpected error

One of the ODBC library functions returned an error that was not expected.

9D/13 Illegal size or type of data for variable xxx

An elementary data item in your FD was larger than 255 bytes, or there is no ODBC type that matches the current data type.

9D/14 More than one table with the same name

When tables were listed, more than one table was found with the same name. Consider whether or not setting the USER_PATH configuration variable will resolve the issue. This variable will enable tables with identical names, but with different ownership (located in a different schema) to be found and accessed.

9D/15 ODBC driver missing needed types

The driver doesn’t support the data types needed for Acu4GL for ODBC.

Parent topic: Troubleshooting


Native SQL Errors

You may encounter the following native SQL errors when using Acu4GL for ODBC. These errors are generated by your data source, so the exact wording and error number will vary.

9D/???? Too many BLOBs (binary large objects)

Some databases have restrictions on how many BLOBs can be placed into a single table. To work around this restriction, specify the configuration variable A_ODBC_USE_CHAR_FOR_BINARY. This allows you to encode binary data in hexadecimal and write it out as CHAR data instead of BINARY.

9D/???? Invalid Column Name OR Reserved Word

You probably specified a column name using a word that has been reserved for your data source. Locate the column by comparing a file trace of the CREATE TABLE to your data source’s list of reserved words. Apply the NAME directive to the field in the FD that is associated with the invalid column, then recompile the program to create a new XFD file.

9D/16 Maximum Length for Literal Characters Exceeded

The interface queries the data source about the maximum size of a character literal in an SQL statement, and if there are any fields in the COBOL data record that exceed that limit, the interface fails to open the file, with an error 9D/16.

Error 9D/16 means that there is at least one COBOL field that exceeds the reported maximum length for character literals, and that you may not be able to insert or update at least one column in the database.

Parent topic: Troubleshooting


Common Questions and Answers

This topic contains some questions and answers specific to Acu4GL for ODBC.

Question

Can I open tables in different databases and share the data?

Answer

Yes. But you must set up the data sources one at a time. For example, you could first set your data source to be Oracle and open Oracle tables, and then you could change the data source to Access and open Access tables.

Remember, you can set up data sources dynamically at run time by adding a line like this before the statement that opens the file:

SET ENVIRONMENT "A_ODBC_DATASOURCE" TO "data source name"

Question

I keep receiving an error message saying that my login is invalid. But I’m sure I’m using the correct username and password.

Answer

All usernames, passwords, and database names are case-sensitive. Be sure that you are typing the names exactly as they are set up.

Question

I’m using Microsoft Access version 2.0, and I’m having trouble accessing/writing tables from my COBOL program.

Answer

Check the version of the Access driver you are using. Microsoft Access version 2.0 requires version 2.0 of the driver. If you are using a previous version of the driver, the runtime will generate errors. To determine the version number of your driver, you can run the Acu4GL for ODBC driver test program DRVTST32.EXE (32-bit version).

Question

I’m noticing some performance degradation when accessing my ODBC data source. What is the cause of this?

Answer

You may notice some performance impact if you were previously accessing Vision indexed files directly. This is because ODBC adds a software layer between your applications and your data sources. In return for minor performance impact, you can reap the benefits of database independence and enhanced portability. Overall performance depends on several factors, including your network configuration and your specific data source.

Question

I wrote data with my Acu4GL for Oracle (or Informix) product. When I try to read it with Acu4GL for ODBC, the data is not the same.

Answer

By necessity, the BINARY data type is implemented differently in Acu4GL for ODBC than it is in Acu4GL for Oracle or Informix. For this reason, writing data with one Acu4GL product and then reading it with another will probably produce different results. Future releases of Acu4GL for Oracle and Informix will address this problem.

Question

When I create a table, I get an error saying I have placed too many BLOBs (binary large objects) in my table.

Answer

Some databases have restrictions about the number of BLOBS that can be placed into a single table. To work around this restriction, you can specify the configuration variable A_ODBC_USE_CHAR_FOR_BINARY. This allows you to encode binary data in hexadecimal and write it out as CHAR data instead of BINARY. See A_ODBC_USE_CHAR_FOR_BINARY for more information on this variable.

Question

Are there any library routines that do not work with or would not make sense to use with Acu4GL for ODBC?

Answer

Yes. The C$COPY and C$RENAME library routines do not work with Acu4GL for ODBC.

Parent topic: Appendix D: Acu4GL for ODBC


Appendix E: Acu4GL for Sybase Information

These topics provide you with the information you need that is specific to Acu4GL® for Sybase Information.

  • Sybase Concepts Overview
  • Installation and Setup
  • Filename Translation
  • Configuration File Variables
  • Record and Table Locking
  • Stored Procedures
  • Limits and Ranges
  • Runtime Errors
Parent topic: Acu4GL Version 10.2.0 User's Guide


Sybase Concepts Overview

A quick overview of some basic design concepts underlying the Sybase Database Management System will help you interface your COBOL program to it.

Servers

A Sybase server is one copy of the database engine executing on a computer. A server has a name, and when a program wants to access the database controlled by a server, the program asks for a connection to that server by name. Multiple servers can be executing on a single machine, controlling different databases. The default name that Sybase gives to a server is SYBASE. Naming of servers is discussed in A_SYB_DEFAULT_CONNECTION.

Table ownership

Table names in Sybase have the form database.owner.table_name. Within Sybase, if you are the owner of a given table, you can refer to it as just table_name. If you are not the owner, you must refer to it with the owner of the table as a prefix. Different owners can thus have tables of the same name. However, this is not true when you use Acu4GL for Sybase.

Acu4GL for Sybase works a little differently. It automatically determines the owner name it will use to reference a table. It is therefore essential that there not be multiple tables with the same name in a single database, even though the tables have different owners. If there are, the Acu4GL for Sybase product will not necessarily find the correct one, and no diagnostic will be issued.

Note that table names include dots (“.”) as separators. Because of this, you must make sure there are no extensions on COBOL file names that will be converted to table names. If you were to have a COBOL file named “IDX1.DAT”, Acu4GL for Sybase would attempt to open a table DAT with owner IDX1. You can avoid this problem either by renaming your COBOL file in your source program, or by using an ACUCOBOL-GT® runtime configuration file entry to map the file name to an allowable file name, such as:

IDX1.DAT  IDX1

If you map your file name to a new name, we recommend that you simply drop the extension to form the new name. Here’s why. The compiler uses the base file name — without the extension — to create the XFD file name (“IDX1.XFD”). The runtime needs to be able to locate this file. But if you’ve mapped the file name to something completely different (such as “MYFILE”), the runtime will look for an XFD file named “MYFILE.XFD”. So you’d have to remember to change the name of “IDX1.XFD” to “MYFILE.XFD” in the XFD directory. Save yourself this extra step by simply dropping the extension when you map the name.

Security

Security is implemented in the Sybase RDBMS. A user is required to log in to the RDBMS before any file processing can occur. Acu4GL for Sybase provides both a default and a user-configurable method for implementing this.

Generally, it is best for someone with Database Administrator (DBA) privileges to create and drop the tables, allowing others only the permissions to add, change, or delete information contained in them.

See the Sybase documentation for more details on DBA privileges.

Alternate REWRITE method

If the above stored procedure is not available, then the update query passed to the database has been optimized to update only dirty columns. This should improve performance.

Parent topic: Appendix E: Acu4GL for Sybase Information


Installation and Setup

The following topics describe several steps that must be performed before you begin using Acu4GL for Sybase on a new system:

  • Sybase RDBMS Installation
  • Acu4GL for Sybase Installation
  • UNIX Client Installations
  • Windows Client and UNIX or Windows NT Server Installations
  • Setting Up a User Account
  • Setting Up the User Environment
  • Designating the Host File System
Parent topic: Appendix E: Acu4GL for Sybase Information


Sybase RDBMS Installation

The Sybase RDBMS must be installed and configured prior to the installation of Acu4GL for Sybase. Acu4GL can interface to Sybase version 11.0 and later.

Sybase’s isql product, which is an interactive query tool, is also necessary for installing the ACUCOBOL-GT stored procedures.

The Acu4GL product does not need isql after installation, but it is a tool that can give you quite a bit of flexibility. It allows you to do database work outside of COBOL, including interactive queries, table creation, table modification, and creation of views, constraints, and relationships between tables.

Micro Focus does not provide these products.

Parent topic: Installation and Setup


Acu4GL for Sybase Installation

The Acu4GL product for Sybase is an add-on module. The Sybase Acu4GL product installation includes a .DLL file that is detected at run time. If you are working in a 32-bit environment, it is not necessary to relink the runtime.

However, the relinking process is necessary for UNIX users, and is explained below in this section.

The Acu4GL product can be executed on a machine that is running UNIX or Windows.

Installation instructions for each of these configurations are given in the following sections. The instructions in the sections that follow describe the steps you must follow on both the client machine and the server machine.

Be sure to use the 64-bit libraries with a 64-bit runtime and 64-bit Acu4GL for Sybase, and the 32-bit libraries with a 64-bit runtime and 32-bit Acu4GL for Sybase.

Parent topic: Installation and Setup


UNIX Client Installations

The Acu4GL product is shipped using either TAR or CPIO format, depending on the type of machine you have. The media label tells you which format has been used. You can start by copying all of the files onto your client machine. If you are using a second machine as your server (this is optional), move the server files (identified below) to that second machine.

You will be installing Acu4GL into the same directory where your ACUCOBOL-GT runtime is located. Change to that directory and type one of the following commands:

tar  xfv device

or

cpio  -icvBd < device

This will copy the files from the distribution medium to your directory. device is the appropriate hardware device name (for example, /dev/rmt0). Sites using Texas Instruments System 1500 should add an uppercase “T” to the cpio options (-icvBdT).

  • UNIX Client Installation Steps
  • UNIX or Windows NT server Installations
Parent topic: Installation and Setup


UNIX Client Installation Steps

Acu4GL communicates with Sybase version 11.0 or later. The client (your application) and the server (the RDBMS) may be located on the same UNIX machine, or on different UNIX machines. The server may also be located on a Windows NT machine.

To install the Acu4GL product, first perform the following steps on the UNIX client machine:

Step 1: Install Sybase client library

The Open Client DB-Library/C from Sybase (version 11.0 or later) must be installed on the client machine before you install Acu4GL for Sybase. Follow the installation instructions in your Sybase documentation.

Step 2: Create a makefile

The script syb_inst is an interactive shell script that determines which libraries your version of Sybase has, and then creates a makefile suitable for linking Acu4GL with an ACUCOBOL-GT runtime for UNIX. It also generates the SQL script used to install ACUCOBOL-GT stored procedures.

Execute the shell script syb_inst by entering the following command on your client machine:

sh  syb_inst
Note:

You may exit the script at any time by pressing the system interrupt key (usually CTRL+C).

If you entered only syb_inst instead of the full command, this message may appear:

VAL=0: command not found
VAL:  Undefined variable

This can be fixed by entering sh syb_inst.

When the script begins executing, you see the following message:

During the execution of this script, we will create an SQL script which you will need to execute from isql, using a command like:

"isql -Usa -Ppassword < syb_inst.sql"

This script will add some stored procedures, and create some tables in a database that you specify during the execution of this script.

In order to implement locking from ACUCOBOL-GT, we need to create a lock table. This should be a pretty small table, but we need to decide which database to create this table in. You should now enter the name of the database you want the lock tables created in. If the database does not exist, it is created.

The following question is asked until you enter a valid database name:

Which database would you like to create this table in?

This database will eventually be located on your server machine. Enter a valid database name. (Invalid names are master, model, temp, or sybsystemprocs.) Names must start with a letter or underscore, must contain only letters, digits, and underscores, and may be up to 30 characters long. Any other entry will be modified.

Next you will see the following message:

Saving any old version of syb_inst.sql...

Old versions of “syb_inst.sql” are saved to “syb_instnnn.sql” where nnn starts at 001 and goes to 999. If a file “syb_inst.sql” exists, you see:

Saving syb_inst.sql as syb_instnnn.sql

for some value of nnn. Then you see:

Creating syb_inst.sql...

This uses the file “syb_inst.in” as a template, and creates “syb_inst.sql”, using the database name you entered above.

You also see:

Creating cblconfig.syb...

This is a sample file of configuration variables you may want to add to your “cblconfig” file.

You then see the following message:

In order to use the Acu4GL for Sybase interface, you need to relink the runtime system.  We are assuming that the Makefile that came with your runtime system still has the "FSI_SUBS=" and "FSI_LIBS=" lines in it, and will base our changes on that Makefile.  However, we will create a new file called Makefile.syb, that has these changes in it.

Do you want to set up the Makefile for this system?

Type y or Y to continue.

You then see the following message:

We next need to determine where you have installed the SYBASE client libraries.

The following prompt is repeated until you enter the directory that contains the Sybase files:

Enter the directory where the SYBASE client libraries are installed

Type the full pathname of the directory containing the Sybase client libraries, and press Enter. Note that this is the directory that contains the Sybase “lib” directory. For example, if the full path for the file “libsybdb.a” is “/usr/sybase/lib/libsybdb.a”, you would type “/usr/sybase”.

The script checks for a file “lib/libsybdb.a” in the directory you entered. You then see one of the following messages:

We seem to have the ACUCOBOL-GT library files in this directory.

We need to find the ACUCOBOL-GT library files...Enter the directory where ACUCOBOL-GT is installed:

If you are asked to enter the directory name, type the full pathname of the directory containing ACUCOBOL-GT, then press Enter.

Before the Makefile is created, we need to check for some alternate optional libraries. You see the message:

Checking for -lnsl or -lnsl_s

If one of the libraries exists, you see:

using -lnsl
    -or-
using -lnsl_s

If you instead see a message like this one:

syb_inst: cc: not found

it’s likely that your PATH environment variable does not include the location of your compiler. In this case, exit from the script, fix the PATH variable, and start the script again.

Finally, you see the message:

Creating Makefile.syb ...
Makefile.syb created.  You should be able to execute
     "make –f Makefile.syb"

and the script exits.

Step 3: Move the makefile

Copy “Makefile.syb” to the ACUCOBOL-GT library subdirectory if it is not already there.

Now you are ready to relink your ACUCOBOL-GT runtime.

Step 4: Link the runtime system

Note:

In the following directions, the term “runtime system” refers to the runtime shared object on systems where the ACUCOBOL-GT runtime is a shared object and to runcbl on other systems, where the runtime is static. The runtime is a shared object on the following systems: AIX 5.1 and later, HP-UX 11 and later, and Solaris 7 and later. To check, look at the contents of the “lib” subdirectory of your ACUCOBOL-GT installation. If the files “libruncbl.so” or “libruncbl.sl” reside in that directory, the runtime is a shared object on your system.

Make sure you are in the directory containing the ACUCOBOL-GT runtime system. Then, at the UNIX prompt, enter the following command:

make clean

to ensure that you have a clean directory in which to build your runtime.

Now enter the following command:

make -f Makefile.syb

This compiles “sub.c” and “filetbl.c” and then links the runtime system.

Step 5: Verify the link

Enter the following command:

./runcbl -vv

to verify the link. This returns version information on all of the products linked into your runtime system. Make sure it reports the version of Acu4GL for Sybase.

Shared libraries

If you have relinked the ACUCOBOL-GT runtime and receive an error message of this type when you try to execute it:

"Could not load library; no such file or directory"

"Can’t open shared library . . . "

this may mean that your operating system is using shared libraries and cannot find them. This can occur even if the shared libraries reside in the same directory where you are currently located.

Different versions of the UNIX operating system resolve this in different ways, so it is important that you consult your UNIX documentation to resolve this error.

Some versions of UNIX require that you set an environment variable that points to shared libraries on your system.

For example, on an IBM RS/6000 running AIX 4.1, the environment variable LIBPATH must point to the directory where the shared libraries are located.

On HP/UX, the environment variable that must be set to point to shared libraries is SHLIB_PATH. On UNIX SVR4, the environment variable is LD_LIBRARY_PATH.

Be sure to read the system documentation for your operating system to determine the appropriate way to locate shared libraries.

A second way to resolve this type of error is to link the libraries into the runtime with a static link. Different versions of the C development system use different flags to accomplish this link. Please consult the documentation for your C compiler to determine the correct flag for your environment.

Step 6: Copy runcbl to the correct directory

If the runtime is a system is a statically linked executable, copy the new executable to a directory listed in your execution path. This file needs to have execute permission for everyone who will be using the compiler or runtime system. The copy step is not necessary when the runtime system is a shared library.

The ACUCOBOL-GT license file for the runtime (“runcbl.alc”) and the license file for the Acu4GL product to Sybase (“runcbl.ylc”) must be copied into the same directory as the runtime executable.

If you rename your runtime executable, be sure to rename your license files to use the same base name, with the extensions unchanged.

For example, if you rename your runtime to be “myprog”, the license file for the Acu4GL product for Sybase should be renamed “myprog.ylc”, and the license file for the runtime should be renamed “myprog.alc”.

The remaining files can be left in the directory to which they were unloaded from the distribution medium.

Step 7: Use rehash

If you are using the C shell, enter the command rehash. This tells the C shell that there is a new executable in the path.

This completes the installation process on the client machine.

Parent topic: UNIX Client Installations


UNIX or Windows NT server Installations

Perform the following steps on the server machine (the client and server may be located on the same machine):

Step 1: Install Sybase

The Sybase server, version 11.0 or later, must be installed and configured on your server machine. Follow the Sybase installation instructions in your Sybase documentation.

Step 2: Move the ACUCOBOL-GT stored procedures

Move “syb_inst.sql” to your server machine (the one hosting the Sybase RDBMS). This file was created in step 2 of the client installation.

Step 3: Install the ACUCOBOL-GT stored procedures

You must have Database Administrator privileges to install the ACUCOBOL-GT stored procedures on the server. (You need to enter the password for the Database Administrator.) Enter the following command:

isql -Usa -Ppassword  <  syb_inst.sql

(“syb_inst.sql” is created during the installation of the client.)

By default, the stored procedures are installed into the master or sybsystemprocs databases. However, you may choose another database in which to store them. Follow these steps if you want to install the stored procedures in a database other than the default:

  1. Before you execute the “syb_inst.sql” query, modify the query file to use the desired database instead of the master or sybsystemprocs database. After you have modified the query file, execute it as described above.
  2. Create in each database that contains tables accessed by Acu4GL the stored procedures that were previously in the master or sybsystemprocs database. Note that the stored procedures are executed without being prefixed by a database name, and Sybase requires that such stored procedures must be in the master or sybsystemprocs database.

The interface also searches for and executes the sp_AcuInit stored procedure from this location. This stored procedure is executed when a connection is made to the database; therefore, sp_AcuInit should reside in the default database for each user if it is not created in the master database. See Built-in Stored Procedures for information on the sp_AcuInit stored procedure.

This completes the setup on the UNIX or Windows NT server machine.

Note:

If you are updating from an earlier version of Acu4GL, be sure to install the new stored procedures. We always update stored procedures in such a way that they are compatible with older versions of the product, so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software. Your new version of Acu4GL for Sybase may not run properly without the corresponding stored procedures.

It can be difficult to maintain multiple copies of stored procedures; therefore, we recommend that you continue to create the stored procedures in the master or sybsystemprocs database. If your installation does not permit this, you do have the flexibility to create the stored procedures elsewhere. However, to facilitate maintenance of the stored procedures, we recommend that you create as few databases as possible.

The following topics describe the next steps you must take before using Acu4GL for Sybase for the first time:

  • Setting Up a User Account
  • Setting Up the User Environment
  • Designating the Host File System
  • Using the “sql.acu” Program
  • Preparing and Compiling Your COBOL Program
  • The Demonstration Program
Parent topic: UNIX Client Installations


Windows Client and UNIX or Windows NT Server Installations

First you must install the files from the installation media onto the client machine. Then follow the instructions below for the appropriate server machine. Finally, some setup steps on the client machine complete the installation.

Instructions for installing your Acu4GL product from the ACUCOBOL-GT CD-ROM are contained on the Quick Start CD booklet that accompanied the product. Please refer to it for installing your products.

Once the installation is complete, please refer to this appendix for setting up your Acu4GL product.

  • UNIX Server Machine Installations
  • Windows NT Server and Windows Client Installations
  • Windows client Installations
Parent topic: Installation and Setup


UNIX Server Machine Installations

To install the Acu4GL for Sybase on a UNIX server machine:

Step 1: Install Sybase

The Sybase RDBMS, version 11.0 or later, must be installed and configured before you install Acu4GL for Sybase. Follow the Sybase installation instructions in your Sybase documentation.

Sybase’s isql product, which is an interactive query tool, is also necessary for installing the ACUCOBOL-GT stored procedures.

The Acu4GL product does not need isql after installation, but it’s a tool that can give you quite a bit of flexibility. It allows you to do database work outside of COBOL, including interactive queries, table creation, table modification, and creation of views, constraints, and relationships between tables.

Micro Focus does not provide these products.

Step 2: Copy files

Copy “syb_inst”, “syb_cfg.in”, and “syb_inst.in” to your UNIX server machine.

Step 3: Create stored procedures

The file “syb_inst” is an interactive shell script that generates the SQL script used to install ACUCOBOL-GT stored procedures.

Execute the shell script “syb_inst” by entering the following command on your server machine:

sh  syb_inst
Note:

You may exit the script at any time by pressing the system interrupt key (usually CTRL+C).

If you entered only syb_inst instead of the full command, this message may appear:

VAL=0: command not found
VAL:  Undefined variable

This can be fixed by entering sh syb_inst.

When the script begins executing, you will see the following message:

During the execution of this script, we will create an SQL script which you will need to execute from isql, using a command like:

"isql -Usa -Ppassword < syb_inst.sql"

This script will add some stored procedures, and create some tables in a database that you specify during the execution of this script.

In order to implement locking from ACUCOBOL-GT, we need to create a lock table. This should be a pretty small table, but we need to decide which database to create this table in. You should now enter the name of the database you want the lock tables created in. If the database does not exist, it is created.

The following question is asked until you enter a valid database name:

Which database would you like to create this table in?

This database will eventually be located on your server machine. Enter a valid database name. (Invalid names are master, model, temp, or sybsystemprocs.) Names must start with a letter or underscore, must contain only letters, digits, and underscores, and may be up to 30 characters long. Any other entry will be modified.

Next you see the following message:

Saving any old version of syb_inst.sql...

Old versions of “syb_inst.sql” are saved to “syb_instnnn.sql” where nnn starts at 001 and goes to 999. If a file “syb_inst.sql” exists, you see:

Saving syb_inst.sql as syb_instnnn.sql

for some value of nnn. Then you see:

Creating syb_inst.sql...

This uses the file “syb_inst.in” as a template, and creates “syb_inst.sql”, using the database name you entered above.

You also see:

Creating cblconfig.syb...

This is a sample file of configuration variables you may want to add to your cblconfig file.

You then see the following message:

Do you want to set up the Makefile for this system?

Type n or N to quit the script.

Step 4: Install the ACUCOBOL-GT stored procedures

You must have Database Administrator privileges to install the ACUCOBOL-GT shared procedures on the server. (You need to enter the password for the Database Administrator.) Enter the following command:

isql -Usa -Ppassword  <  syb_inst.sql

By default, the stored procedures are installed into the master or sybsystemprocs databases. However, you may choose another database in which to store them. Follow these steps if you want to install the stored procedures in a database other than the default:

  1. Before you execute the “syb_inst.sql” query, modify the query file to use the desired database instead of the master or sybsystemprocs database. After you have modified the query file, execute it as described above.
  2. Create in each database that contains tables accessed by Acu4GL the stored procedures that were previously in the master or sybsystemprocs database. Note that the stored procedures are executed without being prefixed by a database name, and Sybase requires that such stored procedures must be in the master or sybsystemprocs database.

The interface also searches for and executes the sp_AcuInit stored procedure from this location. This stored procedure is executed when a connection is made to the database; therefore, sp_AcuInit should reside in the default database for each user if it is not created in the master database. See Built-in Stored Procedures for information on the sp_AcuInit stored procedure.

This completes the setup on the UNIX or Windows NT server machine.

Note:

If you are updating from an earlier version of Acu4GL, be sure to install the new stored procedures. We always update stored procedures in such a way that they are compatible with older versions of the product, so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software. Your new version of Acu4GL for Sybase may not run properly without the corresponding stored procedures.

It can be difficult to maintain multiple copies of stored procedures; therefore, We recommend that you continue to create the stored procedures in the master or sybsystemprocs database. If your installation does not permit this, you do have the flexibility to create the stored procedures elsewhere. However, to facilitate maintenance of the stored procedures, We recommend that you create as few databases as possible.

Parent topic: Windows Client and UNIX or Windows NT Server Installations


Windows NT Server and Windows Client Installations

Complete the following steps to install the Acu4GL product on a Windows NT server machine.

Step 1: Install SQL Server

Sybase, version 11.0 or later, must be installed and configured on the Windows NT server machine before you install Acu4GL for Sybase on the client machine. Follow the instructions from your RDBMS vendor.

The isql product, which is an interactive query tool, is also necessary for installing the ACUCOBOL-GT stored procedures. The Acu4GL product does not need isql after installation, but it is a tool that can give you quite a bit of flexibility. It allows you to do database work outside of COBOL, including interactive queries, table creation, table modification, and creation of views, constraints, and relationships between tables.

Micro Focus does not provide these products.

Step 2: Copy the batch file

The file “syb_inst.cmd” is a batch file from Micro Focus that will create the “syb_inst.sql” file, which is the collection of stored procedures necessary for executing the Acu4GL product. Copy “syb_inst.cmd” to your server machine into a directory of your choice.

Step 3: Execute the batch file

To execute the batch file, enter

SYB_INST LockDatabase

where LockDatabase is the database you want to use for the internal ACUCOBOL GT lock tables. If this database does not already exist, it will be created.

Everyone who will use the Acu4GL for Sybase product must have write access to this database. This step creates “syb_inst.sql”, which is the collection of stored procedures necessary for executing the Acu4GL product.

Step 4: Install the ACUCOBOL-GT stored procedures

You must have Database Administrator privileges to do this step. You need to enter the password for the Database Administrator.

Type:

ISQL -USA -Ppassword  <  SYB_INST.SQL

Another way to accomplish the same result is to use ISQL/W to execute syb_inst.sql as a query. See your Sybase documentation for how to do this.

By default, the stored procedures are installed into the master or sybsystemprocs databases. However, you may choose another database in which to store them. Follow these steps if you want to install the stored procedures in a database other than the default:

  1. Before you execute the “syb_inst.sql” query, modify the query file to use the desired database instead of the master or sybsystemprocs database. After you have modified the query file, execute it as described above.
  2. Create in each database that contains tables accessed by Acu4GL the stored procedures that were previously in the master or sybsystemprocs database. Note that the stored procedures are executed without being prefixed by a database name, and Sybase requires that such stored procedures must be in the master or sybsystemprocs database.

The interface also searches for and executes the sp_AcuInit stored procedure from this location. This stored procedure is executed when a connection is made to the database; therefore, sp_AcuInit should reside in the default database for each user if it is not created in the master database. See Built-in Stored Procedures for information on the sp_AcuInit stored procedure.

This completes the setup on the UNIX or Windows NT server machine.

Note:

If you are updating from an earlier version of Acu4GL, be sure to install the new stored procedures. We always update stored procedures in such a way that they are compatible with older versions of the product, so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software. Your new version of Acu4GL for Sybase may not run properly without the corresponding stored procedures.

It can be difficult to maintain multiple copies of stored procedures; therefore, we recommend that you continue to create the stored procedures in the master or sybsystemprocs database. If your installation does not permit this, you do have the flexibility to create the stored procedures elsewhere. However, to facilitate maintenance of the stored procedures, we recommend that you create as few databases as possible.

Parent topic: Windows Client and UNIX or Windows NT Server Installations


Windows client Installations

Complete the following steps to install the Acu4GL product on a Windows client machine.

Step 1: Choose your communication method

Be sure to choose your communication method at the client machine. To do this, follow the Sybase instructions for selecting a Net-Library.

After you make your selection, you will be prompted for directory names and for the server internet address or host name. The installation utility will then make an entry in the SQL.INI file, which points to the server. The SQL.INI file is located in the INI subdirectory under the directory where your Net-Library is stored.

The name of the server that is placed into SQL.INI is the name you must use in your COBOL configuration file with the variable A_SYB_DEFAULT_CONNECTION. Any name listed in brackets in that file can be used as a server name.

Step 2: Verify that your client is communicating with your server

To verify that you are connected, use the Sybase client utility SYBPING to ping the server. Make sure you receive a response to the ping.

The following sections describe the next steps to take before using Acu4GL for Sybase for the first time:

  • Setting Up a User Account
  • Setting Up the User Environment
  • Designating the Host File System
  • Using the “sql.acu” Program
  • Preparing and Compiling Your COBOL Program
  • The Demonstration Program
Parent topic: Windows Client and UNIX or Windows NT Server Installations


Setting Up a User Account

Acu4GL for Sybase must be able to connect to a user account. You may either set up one general account for all users or an account for each individual user. To set up an account, you must have DBA privileges.

See sp_addlogin and Sybase sp_adduser in the Sybase Commands Reference Manual.

Parent topic: Installation and Setup


Setting Up the User Environment

The user’s account should have been set up correctly to access the Sybase RDBMS system. This includes environment variables such as SYBASE and DSQUERY. See your Sybase documentation for more details.

In addition to setting the variables required for Sybase, you will need to do the following:

  • Ensure that your execution path contains the name of the directory in which you placed your newly linked Acu4GL runtime executable.
  • Set the A_SYB_LOGIN and A_SYB_PASSWD variables, either in your environment or in the ACUCOBOL-GT runtime configuration file (if you don’t do this, Acu4GL will use your UNIX login name as your Sybase login name, and no password). For security reasons, it is best to set the password variable from your COBOL program by asking the user to enter a password and then executing:
    SET ENVIRONMENT "A_SYB_PASSWD" TO user-entry

You may want to make and use a personalized copy of the configuration file to avoid impacting other users. The ACUCOBOL-GT User’s Guide describes how to use the A_CONFIG environment variable, or the “-c” runtime option, to identify a personal configuration file.

Parent topic: Installation and Setup


Designating the Host File System

If you are opening an existing file, most, but not all, file systems linked into the run-time will be searched for the named file. If, however, you are creating a new file, you must tell the run-time which file system to use. You accomplish this with one of two run-time configuration file variables; the first is:

DEFAULT_HOST filesystem

This designates the file system to be used for newly created files that are not individually assigned. For example,

DEFAULT_HOST SYBASE

means that all new files will be Sybase files unless otherwise specified by the second configuration variable, which is:

filename_HOST filesystem

where filename is the file name, without any extension, named in the ASSIGN TO clause of your SELECT statement. This configuration variable is used to assign an individual data file to a file system. Any file so assigned uses the designated file system, and not the one specified by DEFAULT_HOST. For example:

myfile_HOST VISION

means that myfile will be under the Vision file system.

You can use these run-time configuration file variables in combination to assign your new files in a default with exceptions manner; for example, this set of entries:

DEFAULT_HOST VISION
afile_HOST SYBASE
bfile_HOST SYBASE

means that all new files except afile and bfile will be assigned to Vision, and those two files will be assigned to Sybase.

You can also change the values of these variables during program execution by including in your code:

SET ENVIRONMENT "filename_HOST" TO filesystem

or

SET ENVIRONMENT "DEFAULT_HOST" TO filesystem

This enables you to change file systems during the execution of your program. This is not the typical way to specify a file system; normally it is designated in the run-time configuration file and is not changed in the COBOL program.

Note:

The interface to Sybase allows you to create a Sybase table with an OPEN OUTPUT statement, just as you can create Vision indexed files. The Sybase equivalent of a Vision file is a table, not a database. You need to create a database for your Sybase tables before you run the COBOL program that creates the tables, just as you need to create a directory for your files before you run a COBOL program that creates Vision files.

You are now ready to use the sql.acu program. You can find information on this program in Using the sql.acu Program.

After you learn about and use this utility, you will next find out about preparing and compiling your COBOL program, followed by learning to use the demonstration program. See Preparing and Compiling a Program Example and Demonstration Program for additional information.

Parent topic: Installation and Setup


Filename Translation

As you prepare to work with Acu4GL for Sybase, you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together.

When the ACUCOBOL-GT compiler generates XFD files, it uses lowercase letters to name the XFD file. In addition, the compiler changes hyphens to underscores when naming the XFD file.

Through configuration variables, the runtime translates the file name in the COBOL program into the filename that is passed to the open() function in the runtime. The open() function determines which file system to pass the request to, but does not change the name of the file.

However, Acu4GL for Sybase needs the name of the file to find the appropriate XFD file. To do this, Acu4GL for Sybase changes the name of the file to lowercase letters and changes hyphens to underscores. Note, however, that this is performed only on a local copy of the file. Once the XFD file is found, the filename reverts to the name that was originally passed to the open() function. Characters that are illegal in identifiers, such as a hyphen (“-”), are trapped by the database, and Acu4GL for Sybase will neither find the file nor create a new one.

Parent topic: Appendix E: Acu4GL for Sybase Information


Configuration File Variables

This topic lists the runtime configuration file variables that are specific to Acu4GL for Sybase. Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in Runtime Configuration Variables

  • A_SYB_ADD_IDENTITY configuration variable
  • A_SYB_ADD_TIMESTAMP configuration variable
  • A_SYB_CHECK_DELETE_SP configuration variable
  • A_SYB_CHECK_INSERT_SP configuration variable
  • A_SYB_CHECK_READ_SP configuration variables
  • A_SYB_CHECK_UPDATE_SP configuration variable
  • A_SYB_CURSOR_OPTION_1, A_SYB_CURSOR_OPTION_2, A_SYB_CURSOR_OPTION_3 configuration variables
  • A_SYB_DATABASE configuration variable
  • A_SYB_DEADLOCK_LOOPS configuration variable
  • A_SYB_DEFAULT_CONNECTION configuration variable
  • A_SYB_EXTRA_PROC configuration variable
  • A_SYB_FAST_ACCESS configuration variable
  • A_SYB_FORCED_INDEX configuration variable
  • A_SYB_LOCK_DB configuration file
  • A_SYB_LOGIN configuration variable
  • A_SYB_MAX_BINARY_LENGTH configuration variable
  • A_SYB_MAX_CHAR_LENGTH configuration variable
  • A_SYB_MAX_CHARACTERS configuration variable
  • A_SYB_MAX_COLUMNS configuration variable
  • A_SYB_NATIVE_LOCK_TIMEOUT configuration variable
  • A_SYB_NO_COUNT_CHECK configuration variable
  • A_SYB_NO_DBCLOSE configuration variable
  • A_SYB_NO_DBID configuration variable
  • A_SYB_NO_RECORD_LOCKS configuration variable
  • A_SYB_NO_TABLE_LOCKS configuration variable
  • A_SYB_NO_23_ON_START configuration variable
  • A_SYB_PACKETSIZE configuration variable
  • A_SYB_PASSWD configuration variable
  • A_SYB_ROWCOUNT configuration variable
  • A_SYB_SELECT_KEY_ONLY configuration variable
  • A_SYB_SKIP_ALTERNATE_KEYS configuration variable
  • A_SYB_TRANSACTION_LEVEL configuration variable
  • A_SYB_TRANSLATE_TO_ANSI configuration variable
  • A_SYB_UNLOCK_ON_EXECUTE configuration variable
  • A_SYB_USE_DROPDOWN_QUERIES configuration variable
  • A_SYB_VISION_LOCKS_FILE configuration variable
Parent topic: Appendix E: Acu4GL for Sybase Information


A_SYB_ADD_IDENTITY configuration variable

When it is set at the default of TRUE, A_SYB_ADD_IDENTITY adds an extra column to any table created by the Acu4GL for Sybase product. The extra column has identity property and is included on all indexes that are not unique.

When A_SYB_ADD_IDENTITY is set to FALSE, an extra column is not added. While the default value is FALSE (OFF, NO), this configuration variable can also take values of TRUE (ON , YES).

Note: The COBOL FD should not include the identity column.

For example:

A_SYB_ADD_IDENTITY TRUE

On keys that allow duplicates, this variable has been found to vastly improve performance. Note that the default value is TRUE for a file that allows duplicates, and is FALSE for a file with no duplicate keys.

Parent topic: Configuration File Variables


A_SYB_ADD_TIMESTAMP configuration variable

Using a timestamp column is the only way to absolutely ensure that modifications made to a row are not overwriting someone else’s changes. (See the discussion of BROWSE MODE in the Sybase Commands Reference Manual.) When reading a table that is open for I/O, the Acu4GL for Sybase product uses BROWSE MODE if a timestamp column exists. When the Acu4GL product is creating a table, if the value of A_SYB_ADD_TIMESTAMP is 1, a timestamp column is included in the table.

Note: Your COBOL FD should not include the timestamp column.

While the default value is OFF (FALSE, NO), this configuration variable can also take values of ON (TRUE, YES).

For example:

A_SYB_ADD_TIMESTAMP  1

See also: BROWSE MODE in the Sybase Commands Reference Manual .

Parent topic: Configuration File Variables


A_SYB_CHECK_DELETE_SP configuration variable

This configuration variable controls whether the Acu4GL for Sybase interface checks for the tablename_delete stored procedure when opening a table. If A_SYB_CHECK_DELETE_SP is set to FALSE (NO, OFF, 0), the Acu4GL interface does not check for the stored procedure. Therefore, even if tablename_delete exists, it is not used if A_SYB_CHECK_DELETE_SP is set to FALSE. The default is TRUE (YES, ON, 1) to check for the stored procedure.

Parent topic: Configuration File Variables


A_SYB_CHECK_INSERT_SP configuration variable

This configuration variable controls whether the Acu4GL for Sybase interface checks for the tablename_insert stored procedure when opening a table. If A_SYB_CHECK_INSERT_SP is set to FALSE(NO, OFF, 0), the Acu4GL interface does not check for the stored procedure. Therefore, even if tablename_insert exists, it is not used if A_SYB_CHECK_INSERT_SP is set to FALSE. The default is TRUE (YES, ON, 1) to check for the stored procedure.

Parent topic: Configuration File Variables


A_SYB_CHECK_READ_SP configuration variables

This configuration variable controls whether the Acu4GL for Sybase interface checks for the tablename_read stored procedure when opening a table. If A_SYB_CHECK_READ_SP is set to FALSE (NO, OFF, 0), the Acu4GL interface does not check for the stored procedure. Therefore, even if tablename_read exists, it is not used if A_SYB_CHECK_READ_SP is set to FALSE. The default is TRUE(YES, ON, 1) to check for the stored procedure.

Parent topic: Configuration File Variables


A_SYB_CHECK_UPDATE_SP configuration variable

This configuration variable controls whether the Acu4GL for Sybase interface checks for the tablename_update stored procedure when opening a table. If A_SYB_CHECK_UPDATE_SP is set to FALSE (NO, OFF, 0), the Acu4GL interface does not check for the stored procedure. Therefore, even if tablename_update exists, it is not used if A_SYB_CHECK_UPDATE_SP is set to FALSE. The default is TRUE (YES, ON, 1) to check for the stored procedure.

Parent topic: Configuration File Variables


A_SYB_CURSOR_OPTION_1, A_SYB_CURSOR_OPTION_2, A_SYB_CURSOR_OPTION_3 configuration variables

These configuration variables allow you to fine-tune the declaration of cursors in the Acu4GL for Sybase product. In general, cursors are declared with the following syntax:

DECLARE cursor_name option_1 CURSOR option_2 FOR
   <select....> option_3

In other words, different phrases can go in each of the option_X places. Also, different versions of Sybase allow different options in each of those places. Because of this, the Acu4GL product allows customization of the cursor declaration via these three variables. The values of these variables are placed verbatim into the declare phrase when building a cursor. Note that any errors in the values of these variables may make your Acu4GL product inoperable. You should refer to the Sybase documentation to determine what phrases are allowed in each case.

The default values are as follows (limit is 65 characters for each option):

  • OPTION_1: “SCROLL”
  • OPTION_2: blank
  • OPTION_3: “For read only”

Users of Sybase version 11 should set the value of OPTION_3 to "at isolation read uncommitted" to prevent page locks.

Parent topic: Configuration File Variables


A_SYB_DATABASE configuration variable

A_SYB_DATABASE specifies the name of the specific database to be accessed. You cannot open any database files until you have set this variable.

Example

A_SYB_DATABASE stores

This indicates a database named stores is to be accessed.

Parent topic: Configuration File Variables


A_SYB_DEADLOCK_LOOPS configuration variable

Use A_SYB_DEADLOCK_LOOPS if you expect that more than one user will be opening a lot of tables at the same time. This configuration variable can be used to instruct Acu4GL to re-execute an INSERT statement that could not execute because a row in the AcuOpenTables table was locked, or to return an error if the user chooses not to run the query again.

The default for A_SYB_DEADLOCK_LOOPS is 0, which causes the interface to return an error 9D/1205 indicating that a table is locked.

Set A_SYB_DEADLOCK_LOOPS to a positive numeric value to cause Acu4GL for Sybase to re-execute by the number specified the query that tried to open the table, and, thus, caused the deadlock. Note that it can be as long as 10 seconds until Sybase detects the deadlock, and the application appears not respond while the repeated attempts to re-execute the query are in progress.

Set A_SYB_DEADLOCK_LOOPS to -1 or MESSAGE to cause Acu4GL for Sybase to display a message box containing the text of the Sybase error message and the option to rerun the query.

Sybase has returned an error
(text of message from Sybase)
Do you want to retry the operation?

If the user answers yes, the interface reruns the query. If the user answers no, the interface returns an error 9D. Setting A_SYB_DEADLOCK_LOOPS to -1 or MESSAGE is the preferred action. This represents the time it takes to inform users of the problem allows other connections to finish opening the tables, giving the AcuOpenTables table time to remove the deadlock.

Parent topic: Configuration File Variables


A_SYB_DEFAULT_CONNECTION configuration variable

A_SYB_DEFAULT_CONNECTION specifies the name of the server to which the runtime will connect. Acu4GL for Sybase checks this variable only if the DSQUERY environment variable has not been set. (Note that Sybase recommends assigning a value to the DSQUERY environment variable.) If neither DSQUERY nor A_SYB_DEFAULT_CONNECTION is set, the default server is named SYBASE, just as for isql. To reference tables in another server, open the file servername.database.owner.table.

Example

Suppose you have two servers, one named TOM and one named HARRY. If most of the tables you want to access are on the server HARRY, you should set:

A_SYB_DEFAULT_CONNECTION  HARRY

For those occasions when you want to access the TOM server, you could open the file this way:

TOM.stores.johndoe.purch1

See also: The Sybase documentation on isql.

Parent topic: Configuration File Variables


A_SYB_EXTRA_PROC configuration variable

A_SYB_EXTRA_PROC can be used to keep modifications to the AcuLocks table out of transactions. If these modifications are kept out of transactions, users can read a record, even if they cannot REWRITE it. Otherwise, they are locked out. A_SYB_EXTRA_PROC works by creating a separate connection for these modifications.

When this variable is set to a nonzero value, an extra connection is used for the following three procedures:

  • Modifying the AcuLocks table
  • Modifying the AcuOpenTables table
  • Modifying the IMAGE data. Note that two connections are required when updating IMAGE or TEXT data. This is a major reason for setting A_SYB_EXTRA_PROC.

The default value is 0 (OFF, FALSE, NO). A nonzero value can also be represented by ON (TRUE, YES).

If this variable is set to On, the extra connection is used to send TEXT or IMAGE data to the server. The first connection is used to deliver non-TEXT and non-IMAGE data to the server. When a WRITE or REWRITE is executed, the interface program INSERTS or UPDATES the non-TEXT and non-IMAGE data by using placeholder data in the TEXT or IMAGE columns.

The TEXT or IMAGE data is then sent using the extra connection established with the A_SYB_EXTRA_PROC configuration variable. If the first connection is inside a transaction, the second connection is locked out of the row that is added or updated. The result is that it is not possible to WRITE or REWRITE records containing TEXT or IMAGE data while inside a transaction.

Note: Large columns cannot be used in conjunction with transaction management, because any column larger than 255 bytes (254 characters) is automatically converted to a TEXT or IMAGE column when the table is created. If you have TEXT or IMAGE columns in your table, WRITEs and REWRITEs fail unless this variable is set to ON.

See also: Record and Table Locking.

Parent topic: Configuration File Variables


A_SYB_FAST_ACCESS configuration variable

A_SYB_FAST_ACCESS is a configuration variable that is set from your COBOL program. Files opened while this variable is set to a nonzero value are optimized for forward sequential access. While the default value is 0 (OFF, FALSE, NO), this configuration variable can also take values of ON (TRUE, YES).

This option improves the READ NEXT performance in some cases. For example, testing the benchmark program iobench.cbl in three different ways, yielded the following results for the READ AND SKIP operation:

No FAST_ACCESS: | 72.76 seconds
FAST_ACCESS, ROWCOUNT 0: | 148.88 seconds
FAST_ACCESS, ROWCOUNT 10: | 8.09 seconds

(10 is the perfect value for ROWCOUNT in this benchmark, because the program does a START, 10 READ NEXT operations, and then does it again.)

For certain reporting programs, this option can dramatically improve performance. However, please note the following restrictions. Files must be open INPUT or open IO with MASS-UPDATE. FAST_ACCESS gives a performance boost only when no locking is required. In files that allow locking, a record must be reread after being locked; this prevents an uninterrupted forward sequential traversal.

Files opened with FAST_ACCESS use a dedicated connection for reading from the file. Since connections are memory-intensive (both on the client and on the server), the number of files opened with FAST_ACCESS should be kept to a minimum. In the event that opening a connection fails, the file open still continues, but FAST_ACCESS mode is disabled, with the following message appearing in the trace file:

FAST_ACCESS mode not available.

Also, a new connection technically uses a new concurrent Sybase license from Sybase.

Files opened with FAST_ACCESS do not participate in transactions, and may even cause the runtime to hang if transactions are used, especially if the FAST_ACCESS file is updated within the transaction. We suggest that if you use transactions, you don’t use FAST_ACCESS. At the minimum, if you use transactions, we suggest that you use FAST_ACCESS only for files open INPUT.

Files opened with FAST_ACCESS cannot be read backwards. In other words, READ PREVIOUS does not work with FAST_ACCESS files. In fact, if you try to READ PREVIOUS on a file opened with FAST_ACCESS, you get an error 9D/20.

The ANSI standard states that READ NEXT after a READ will return the next record. Some applications depend on this, and some applications just want to read dynamically from a file, and don’t use the positioning facility. Because of this ambiguity, files that are open with FAST_ACCESS cannot be READ dynamically. If you try to READ on a file open with FAST_ACCESS, you get an error 9D/20.

There are no restrictions on WRITE, REWRITE, and DELETE. However, these operations use the cursor-based connection, not the dedicated connection. This is the reason transactions may not complete.

Parent topic: Configuration File Variables


A_SYB_FORCED_INDEX configuration variable

A_SYB_FORCED_INDEX causes the Acu4GL product to attempt to use an actual index that matches the key used with the table. For this variable to have any effect, the index matching the key must be a unique index.

While the default value is 0 (OFF, FALSE, NO), this configuration variable can also take the value of YES (ON, TRUE). If you don’t use the forced-index feature, the Acu4GL product adds an ORDER BY clause to the SELECT, which can add to processing time.

Sybase does not guarantee that an index is used if this variable is set to 1, so the order of records returned to the COBOL program is not guaranteed to be correct in that case. Because of this, it is recommended this variable not be set to setting this variable to 0 (OFF, FALSE, NO).

Parent topic: Configuration File Variables


A_SYB_LOCK_DB configuration file

A_SYB_LOCK_DB specifies the name of the database that holds the lock table.

See also: Record and Table Locking.

Parent topic: Configuration File Variables


A_SYB_LOGIN configuration variable

A_SYB_LOGIN indicates the user name under which you want to connect to the database system.

Example

To connect to the database with the user name MYNAME, specify the following in the run time configuration file:

A_SYB_LOGIN  MYNAME

If A_SYB_LOGIN is not set, on Windows the run time uses the value of your USER environment variable as your Sybase login name. On UNIX systems, the run time uses your UNIX login name as your Sybase login name. For this automatic login to succeed, you must have set up a user with the same name as your computer login name.

See also: A_SYB_PASSWD and Setting Up a User Account.

Parent topic: Configuration File Variables


A_SYB_MAX_BINARY_LENGTH configuration variable

This configuration variable specifies the maximum size of a COBOL variable that can be used as a BINARY data type in ACU4GL for Sybase. Data items larger than this value become IMAGE types in the server. The default value is 8001.

See the topic Preparing your Programs for more information about data types in AcuSQL.

Parent topic: Configuration File Variables


A_SYB_MAX_CHAR_LENGTH configuration variable

This configuration variable specifies the maximum size of a COBOL variable that can be used as a VARCHAR data type in ACU4GL for Sybase. Data items larger than this value become IMAGE types in the server. The default value is 8001.

See the topic Preparing your Programs for more information about data types in AcuSQL.

Parent topic: Configuration File Variables


A_SYB_MAX_CHARACTERS configuration variable

A_SYB_MAX_CHARACTERS indicates the maximum number of bytes Acu4GL allows in a table row.

Sybase places a limit on the number of bytes per table row. The Acu4GL product adheres to this limit, but sometimes it cannot accurately count how many bytes a particular row contains (because of overhead bytes that Sybase adds). This variable enables the developer to set the Acu4GL product’s upper bound.

You might want to try reducing it if you discover that a row cannot be added to a table. By reducing the upper bound, you may be able to prevent this problem.

If Sybase increases the maximum number of bytes allowed in a row (in a future release of the Sybase product), you can increase the value of this variable to take advantage of the new limit.

The A_SYB_MAX_CHARACTERS variable has a default value of 1962.

Parent topic: Configuration File Variables


A_SYB_MAX_COLUMNS configuration variable

A_SYB_MAX_COLUMNS indicates the maximum number of columns Acu4GL allows in a table.

Sybase places a limit on the number of columns per table. The Acu4GL product adheres to this limit, but sometimes it cannot accurately count how many columns a table contains (because a column has been added to a table without the Acu4GL product’s knowledge). This variable enables the developer to set the Acu4GL product’s upper bound. You might want to try reducing the upper bound if you discover that a table cannot be created for some reason. By reducing the upper bound, you allow for uncountable columns and thus may be able to prevent this problem.

If Sybase increases the maximum number of columns allowed per table (in a future release of the Sybase product), you can increase the value of this variable to take advantage of the new limit.

The A_SYB_MAX_COLUMNS variable has a default value of 250.

Parent topic: Configuration File Variables


A_SYB_NATIVE_LOCK_TIMEOUT configuration variable

This is one of two locking methods available with Acu4GL for Sybase. The methods are accessed via two configuration variables: A_SYB_VISION_LOCKS_FILE and A_SYB_NATIVE_LOCK_TIMEOUT. The lock method used is determined as follows: If A_SYB_VISION_LOCKS_FILE is set to the name of a Vision file that can be open I/O and has the correct structure, the Vision file is used to hold lock information. If A_SYB_NATIVE_LOCK_TIMEOUT is set to a positive value, native locking is used. Otherwise, the AcuLocks table is used to hold locks.

This locking method enables you to use Sybase native locks if you explicitly code transactions in your COBOL program. You can access this method by setting the configuration variable A_SYB_NATIVE_LOCK_TIMEOUT to a positive value. This value is the number of seconds that a connection waits for a timeout to occur. When such a timeout occurs (for any reason), the Acu4GL product assumes that timeout was caused by a locked record and returns error 99 (record locked). If you set this variable but do not explicitly code transactions in your COBOL program, record locking does not occur. Note that the Acu4GL product waits the number of seconds specified, and your application may seem to not respond if the timeout is too long. On the other hand, if the timeout is too short, you may get record locked errors when the network is slow.

Sybase uses a page locking mechanism, and so this method of locking records may cause your application to return spurious record locked errors because of a record being locked on the same page as the record you are trying to access. If a future version of Sybase implements row-level locking, this locking method may be the preferred method.

See also: A_SYB_VISION_LOCKS_FILE and Record and Table Locking.

Parent topic: Configuration File Variables


A_SYB_NO_COUNT_CHECK configuration variable

When doing a REWRITE, the interface checks to see that a record was actually updated. If the record was not updated, the interface returns an error 23. Setting this variable to ON causes that check not to happen. This improves performance on REWRITE, at the risk of missing an error. While the default value is OFF (FALSE, NO), this configuration variable can also take the value of ON (TRUE, YES).

Parent topic: Configuration File Variables


A_SYB_NO_DBCLOSE configuration variable

When the run time is shutting down, the interface closes all the open connections, as per the Microsoft documentation. Sometimes, with some network drivers, this takes a significant amount of time. Setting this variable ON causes the interface not to close the connections. Though this can speed up the runtime (during shutdown), we don’t recommended it, because the Microsoft documentation is not being followed. While the default value is OFF (FALSE, NO), this configuration variable can also take the value of ON (TRUE, YES).

Parent topic: Configuration File Variables


A_SYB_NO_DBID configuration variable

The interface stores the Database ID in the AcuLocks and AcuOpenTables tables, to distinguish different tables in different databases. Sometimes this causes problems. Setting this variable ON causes the interface to use a Database ID of 0, instead of the actual ID of the database. While the default value is OFF (FALSE, NO), this configuration variable can also take the value of ON (TRUE, YES).

Parent topic: Configuration File Variables


A_SYB_NO_RECORD_LOCKS configuration variable

Setting this variable to ON causes all READS to be treated as READ NO LOCK, which can improve performance (but has the obvious consequences). While the default value is OFF (FALSE, NO), this configuration variable can also take the value of ON (TRUE, YES).

Parent topic: Configuration File Variables


A_SYB_NO_TABLE_LOCKS configuration variable

Setting this variable to ON causes the interface not to use the AcuOpenTables table, which causes all table locking to be disabled. This can improve performance on OPEN and CLOSE statements. While the default value is OFF (FALSE, NO), this configuration variable can also take the value of ON (TRUE, YES).

Parent topic: Configuration File Variables


A_SYB_NO_23_ON_START configuration variable

When A_SYB_NO_23_ON_START is set to a nonzero value, START does not detect whether records actually exist. Because it does not detect the existence of records, it is possible, when using this variable, to do a START without error, and for the next READ NEXT to return END_OF_FILE, contrary to the ANSI standard.

For example:

A_SYB_NO_23_ON_START number

where number can be a zero or nonzero value.

While the default value is 0, (OFF, FALSE, NO) this configuration variable can also take values of the value of ON (YES, TRUE).

Parent topic: Configuration File Variables


A_SYB_PACKETSIZE configuration variable

A_SYB_PACKETSIZE sets the size of network packets. Setting this variable can affect performance, since fewer and larger network calls can improve performance.

This variable must be set in the configuration file. It has no effect if it is set in a COBOL program via SET CONFIGURATION or SET ENVIRONMENT. The value of this variable is the largest size that the transport layer uses for network packets (although the underlying library may reduce the size specified; this is out of the control of the interface.) The largest value that can be specified is 32767. The default depends on which version of the client libraries is linked into the run time, although 512 is the most common default.

Use this configuration variable to tune your database performance. To set the packet size to 8192 use:

A_SYB_PACKETSIZE 8192

Setting this variable to 0 or to a negative value causes the Acu4GL product to use the default value.

Parent topic: Configuration File Variables


A_SYB_PASSWD configuration variable

The variable A_SYB_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_SYB_LOGIN.

Examples

If the account with the user name in A_SYB_LOGIN has the associated password CW021535, you would specify the following in the run time configuration file:

A_SYB_PASSWD CW021535

For better security, you can accept a password from the user during program execution; set the A_SYB_PASSWD variable based on the response:

ACCEPT RESPONSE NO-ECHO.
SET ENVIRONMENT "A_SYB_PASSWD" TO RESPONSE.
Note: If the user has been set up without a password, this variable need not be set.
Parent topic: Configuration File Variables


A_SYB_ROWCOUNT configuration variable

This variable has an effect only if you are reading on a key that does not allow duplicates, or if you have added an Identity column to the table. A_SYB_ROWCOUNT determines how many rows are returned by a SELECT statement sent to the server.

This variable can be used to speed up the Acu4GL product. For example, if you know you will be reading only one record at a time and reading from a unique key, you can set A_SYB_ROWCOUNT to 1, thus speeding up the processing.

If you know you are going to be reading records ten rows at a time, set A_SYB_ROWCOUNT to 10. If you don’t have any information about how many rows are going to be requested, set this variable to 0, which is the default.

Note: Setting this variable to a non-optional value can actually degrade performance, since the interface may be forced to issue more SELECT statements once the row count has been determined. Use caution when setting this variable.

See also:A_SYB_ADD_IDENTITY

Parent topic: Configuration File Variables


A_SYB_SELECT_KEY_ONLY configuration variable

This variable directs the interface to select key columns only when searching for records. Its use can improve READ performance on large tables with many rows.

When set to the default value TRUE, A_SYB_SELECT_KEY_ONLY causes the interface to select only key columns when searching for records, and then select the entire row of the single record that must be returned to the COBOL program.

Setting A_SYB_SELECT_KEY_ONLY to FALSE does not affect how the select is created for files open I/O (since the record must be locked, and then the rest of the data fetched), but it causes the interface to select all the columns of the table for files open INPUT. While the default value is 0 (OFF, FALSE, NO), this configuration variable can also take the value of ON (TRUE, YES).

Parent topic: Configuration File Variables


A_SYB_SKIP_ALTERNATE_KEYS configuration variable

A_SYB_SKIP_ALTERNATE_KEYS determines whether alternate keys are used to form indexes during table creation. The default value of this variable is 0, which means it’s okay to use alternate keys.

If you set the variable to a nonzero value such as 1, alternate keys are not used to form indexes, which speeds up processing if many writes or rewrites are being performed. A value of 1 may slow processing if the application is reading sequentially using an alternate key.)

While the default value is 0 (OFF, FALSE, NO), this configuration variable can also take the value of ON (TRUE, YES).

You can load a great deal of data into a table rapidly with this variable set to 1, and then create the missing indexes using isql.

See also: The Sybase documentation on isql

Parent topic: Configuration File Variables


A_SYB_TRANSACTION_LEVEL configuration variable

Use this configuration variable to indicate the transaction nested level depth for Acu4GL for Sybase. This is useful when sending embedded BEGIN TRANSACTION statements to the server without using the interface (such as by using sql.acu). The default is zero (0).

Parent topic: Configuration File Variables


A_SYB_TRANSLATE_TO_ANSI configuration variable

Setting this variable to ON(TRUE, YES), causes the Acu4GL interface to call the same translation function used by the Windows runtime to translate characters going to the server into the OEM character set, and to translate characters coming from the server to ANSI.

The default is OFF (FALSE, NO), which indicates that the Acu4GL interface does not call the translation function, but passes the data as is to the library.

This variable applies only to the Windows version of the Acu4GL for Sybase interface.

Parent topic: Configuration File Variables


A_SYB_UNLOCK_ON_EXECUTE configuration variable

Setting this variable to ON causes all invocations of I$IO using the EXECUTE opcode to unlock all records. Normally records are unlocked when a transaction finishes. But if users perform their own transaction management using sql.acu (which calls I$IO using the EXECUTE opcode), the interface never knows to unlock records, because it doesn’t check the text sent to the database to see if it associated with a transaction. While the default value is 0 (OFF, FALSE, NO), this configuration variable can also take the value of ON (TRUE, YES).

Parent topic: Configuration File Variables


A_SYB_USE_DROPDOWN_QUERIES configuration variable

Setting A_SYB_USE_DROPDOWN_QUERIES to a nonzero value causes select queries sent to the database to be of the drop-down variety, instead of a single large query. This variable is accessed only during a positioning operation, so you can set it at different times for different tables. For example, if you have a file with three fields in the primary key (keyseg1, keyseg2, keyseg3), and your COBOL program performs a START, the following query is sent to the database:

select (columns) from (table) where
((keyseg1 = value1 and keyseg2 = value2 and
keyseg3 > value3) or (keyseg1 = value1 and
keyseg2 > value2) or (keyseg1 > value1))
order by keyseg1, keyseg2, keyseg3

If you use drop-down queries, the following collection of queries is sent instead:

select (columns) from (table) where (keyseg1
= value1 and keyseg2 = value2 and keyseg3 >
value3) order by keyseg1, keyseg2, keyseg3

When that set is finished, the interface sends:

select (columns) from (table) where (keyseg1
= value1 and keyseg2 > value2) order by
keyseg1, keyseg2, keyseg3

And when that set is finished, the interface sends:

select (columns) from (table) where (keyseg1
> value1) order by keyseg1, keyseg2, keyseg3

There are advantages and disadvantages to each method. If you use the A4GL_WHERE_CONSTRAINT variable, you should probably set A_SYB_USE_DROPDOWN_QUERIES to 0, because the WHERE constraint limits the result set sufficiently that the larger query will be more efficient. See The WHERE Constraint for additional information.

If you usually START files and read to the end, you should set A_SYB_USE_DROPDOWN_QUERIES to 0, because a fewer number of queries need to be sent to the database. On the other hand, if you START files and stop reading after some condition, but haven’t used the WHERE constraint, then you may get more efficient access by setting this variable to 1 and using the drop-down style of query. In either case, we recommend that you run some tests to see which value of this variable makes the most sense for your application. While the default value is 0 (OFF, FALSE, NO), this configuration variable can also take the value of ON (TRUE, YES).

Example

A_SYB_USE_DROPDOWN_QUERIES number

where number is a zero or nonzero value.

Parent topic: Configuration File Variables


A_SYB_VISION_LOCKS_FILE configuration variable

This is one of two locking methods available with Acu4GL. The methods are accessed via two configuration variables (A_SYB_VISION_LOCKS_FILE and A_SYB_NATIVE_LOCK_TIMEOUT). The lock method used is determined as follows: if A_SYB_VISION_LOCKS_FILE is set to the name of a Vision file that can be open I/O and has the correct structure, this method is used; if A_SYB_NATIVE_LOCK_TIMEOUT is set to a positive value, then this method is used. Otherwise, the AcuLocks table is used to hold locks.

A_SYB_VISION_LOCKS_FILE causes the lock table (AcuLocks) to be a Vision file instead of an SQL table. This can be accessed via the configuration variable A_SYB_VISION_LOCKS_FILE, which must be set to the name of the Vision file that will hold the lock information. You must also set a configuration variable that specifies this file as a Vision file (using a _host variable). This file must be accessible to all users accessing the Sybase SQL server, either through a common directory or through AcuServer.

Also included with the Acu4GL for Sybase product is a small COBOL program that will manage this Vision file (lockmgr). This program should be run with the same runtime that you normally use to access Sybase tables, and with the same configuration variables set. The program detects whether Acu4GL for Sybase is available, and detects the A_SYB_VISION_LOCKS_FILE variable to determine which file to manage. This program displays all the records in the lockfile, and provides options for removing single records (by highlighting the desired record to remove) or removing all shown records, and also for restricting the shown records by PID, Table, and Database. You can refresh the display by clicking the Restrict button and then clicking OK without restricting the display further.

If everything is working correctly, there should be no records in this table when there are no users accessing the Sybase SQL server through Acu4GL. The source for this program is in the sample/acu4gl directory.

See also: Record and Table Locking.

Parent topic: Configuration File Variables


Record and Table Locking

By default, Sybase doesn’t support the type of record and table locking that COBOL expects. For this reason, the Acu4GL for Sybase product implements its own locking method. This is accomplished with the addition of two tables to a database. You choose which database will hold these tables during installation of the Acu4GL for Sybase product.

Before using the locking tables, you need to execute the included “syb_inst.sql” script. See the installation instructions you used from this manual for the exact procedure. If you don’t perform this step, the first time you try to execute a COBOL program that opens a Sybase table, you receive error 9D/11, ACUCOBOL Lock Table Incorrect.

The first locking table is called AcuLocks; it holds the record locks. The columns in this table are the DBID, the Table ID, the Process ID of the process holding the lock, and the primary key of the record that is locked. There is a unique index on the DBID, the Table ID, and the Key Value, so that inserts into this table are automatically rejected if another user holds a lock on the row in question. This also provides the Database Administrator the information needed to determine who has locks set, and whether the user in question still has a connection to the server.

The second locking table is called AcuOpenTables; it holds information about open tables. The columns in this table are:

  • the DBID
  • the Table ID
  • the process ID (PID) of the process that has the table open
  • the open mode (input, output, I/O, or extend)
  • whether multiple records can be locked
  • whether the file can be open for I/O by any other users
  • whether the file can be open at all by any other users
  • whether Mass Update was specified in the open

There are no indices on this table, but there is a trigger, which automatically rejects opens that are not allowed based on other users’ open modes.

By using these lock tables, the Acu4GL for Sybase product is able to support all the types of locking ordinarily supported by ACUCOBOL-GT. No special runtime configuration variables are required.

This method of locking is all that is needed if no applications other than COBOL programs are going to be using the Acu4GL for Sybase product. But if your site has other applications that access the Sybase databases, you must use a method of locking that is inherent to Sybase.

The only method of locking that Sybase supports internally is the result of time stamping and the use of BROWSE MODE (see the discussion of BROWSE MODE in the Sybase Commands Reference Manual). If a table has a time stamp column, the Acu4GL for Sybase product uses browse mode. This allows the server to detect whether another application has modified a record while an ACUCOBOL-GT application has had it locked.

Parent topic: Appendix E: Acu4GL for Sybase Information


Stored Procedures

A stored procedure is a collection of SQL statements residing on the server, stored as text in a table in the database. Stored procedures provide an efficient environment for Acu4GL because, once they are executed on the server, they do not need to be parsed and optimized each time they are executed. (If the server goes down, however, the stored procedure is parsed and optimized again the first time the procedure is called after the database restarts.)

If you run a set of stored procedures for the database in which data is manipulated (your production database), this database must be the setting for A_SYB_LOCK_DB. If you run the stored procedures against both the lock database and the production database, the lock database can be the setting for A_SYB_LOCK_DB. Note that if you run one version of stored procedures against the lock database and another version against the production database, the stored procedures in the lock database override those in the production database. Therefore, we recommend that you always update your stored procedures with each new installation of Acu4GL, so that these procedures are consistent when you run them against the tables in your database.

These topics discuss two types of stored procedures:

  • Procedures that you may want to add to Acu4GL for Sybase
  • Procedures provided in Acu4GL for Sybase that you, as the developer or administrator, may find useful
Note:

If you are updating from an earlier version of Acu4GL, be sure to install the new stored procedures. We always update stored procedures in such a way that they will be compatible with older versions of the product, so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software.

  • Developer- or Site-supplied Stored Procedures
  • Built-in Stored Procedures
Parent topic: Appendix E: Acu4GL for Sybase Information


Developer- or Site-supplied Stored Procedures

This topic provides information on stored procedures you may want to create. It also supplies some example code.

The Acu4GL for Sybase interface checks for these stored procedures when opening a file and will use them in certain circumstances, such as when A_SYB_NO_23_ON_START is set to “ No.”

These stored procedures are

  • tablename_insert (where tablename is the name of the table being accessed)
  • tablename_delete
  • tablename_read
  • tablename_update
  • tablename_startnnn (where nnn is the key number to start on)
Note:

The Acu4GL for Sybase product does not create these stored procedures or check their accuracy. Thus, it is possible to create stored procedures in such a way as to make the Acu4GL for Sybase product completely inoperable.

The Acu4GL product uses these stored procedures for performance reasons only.

Sample XFD

Sample code for developer-supplied stored procedures is based on the following example of an XFD:

XFD,03,FTEST2-FILE,FTESTDAT
# ftestdat.xfd - generated by ACUCOBOL-GT v4.2 Alpha 1
   (8/22/99)
# Generated Sun Aug  22 07:54:28 1999
00031,00031,003
01,0,004,00000
01
FTEST2-KEY
01,1,004,00004
02
FTEST2-KEY1-SEG1
FTEST2-KEY1-SEG2
01,0,004,00008
01
FTEST2-ALTKEY2
000
0006,00006
00000,00004,16,00004,+00,000,000,FTEST2-KEY
00004,00002,16,00002,+00,000,000,FTEST2-KEY1-SEG1
00006,00002,16,00002,+00,000,000,FTEST2-KEY1-SEG2
00008,00004,16,00004,+00,000,000,FTEST2-ALTKEY2
00012,00009,00,00009,+00,000,000,FTEST2-NUMBER
00021,00010,16,00010,+00,000,000,FTEST2-INFO
  • tablename_insert
  • tablename_delete
  • tablename_read
  • tablename_update
  • tablename_startnnn
Parent topic: Stored Procedures


tablename_insert

tablename_insert is used to WRITE a record to the file. The parameters passed to the stored procedure are the values of all the columns in the row, in the order of the columns in the database. The timestamp column and identity column (if present in the table) are not passed to the stored procedure.

Given the XFD above, you might want to create the following stored procedure for writing records to a file:

create procedure ftestdat_insert
@ft2_key char(4),
@ft2_key1_seg1 char(2),
@ft2_key1_seg2 char(2),
@ft2_altkey2 char(4),
@ft2_number char(9),
@ft2_info char(10)
as
insert into ftestdat (ftest2_key, ftest2_key1_seg1,
ftest2_key1_seg2, ftest2_altkey2, ftest2_number,
ftest2_info) values (@ft2_key, @ft2_key1_seg1,
@ft2_key1_seg2, @ft2_altkey2, @ft2_number, @ft2_info)

grant execute on ftestdat_insert to public
Parent topic: Developer- or Site-supplied Stored Procedures


tablename_delete

tablename_delete is used to DELETE a record from the file. The parameters passed to the stored procedure are the values of the primary key, in the order they are listed in the XFD.

Based on the sample XFD, you might want to create the following stored procedure for deleting records from a file:

create procedure ftestdat_delete
@ft2_key char(4)
as
delete from ftestdat where ftest2_key = @ft2_key

grant execute on ftestdat_delete to public
Parent topic: Developer- or Site-supplied Stored Procedures


tablename_read

tablename_read is used to read a random record (READ, not READ NEXT or READ PREVIOUS). The parameters passed to the stored procedure are the values of the primary key, in the order they are listed in the XFD. The expected rowset is the columns in the first table (if secondary tables are used) or the columns of the table (if secondary tables are not necessary).

This stored procedure is very similar to tablename_start.

Parent topic: Developer- or Site-supplied Stored Procedures


tablename_update

tablename_update is used to REWRITE a record from the file. The parameters passed to the stored procedure are the values of all the columns in the row, in the order of the columns in the database. The timestamp column and identity column (if present in the table) are not passed to the stored procedure.

For example, based on the sample XFD, you might want to create the following stored procedure for rewriting a record:

create procedure ftestdat_update
@ft2_key char(4),
@ft2_key1_seg1 char(2),
@ft2_key1_seg2 char(2),
@ft2_altkey2 char(4),
@ft2_number char(9),
@ft2_info char(10)
as
update ftestdat set
ftest2_key = @ft2_key,
ftest2_key1_seg1 = @ft2_key1_seg1,
ftest2_key1_seg2 = @ft2_key1_seg2,
ftest2_altkey2 = @ft2_altkey2,
ftest2_number = @ft2_number,
ftest2_info = @ft2_info
where ftest2_key = @ft2_key

grant execute on ftestdat_update to public
Parent topic: Developer- or Site-supplied Stored Procedures


tablename_startnnn

tablename_startnnn is used to START a file. The nnn value is the key number to start on, and will be 0 filled. For example, the start procedure for the primary key for table mytab will be “mytab_start000”.

Note:

If A_SYB_NO_23_ON_START is set to “Yes,” the start stored procedure is disabled.

Because there can be up to 119 alternate keys, the Acu4GL product does not search for a start procedure unless, or until, it is used. The parameters passed to the stored procedure are a 2-char mode [it is a varchar(2) field], with one of the following values: >, >=, =, <=, or <. The rest of the parameters are the columns of the key used to start. Because the ANSI specification for START includes information about the size of the key being used (and in particular allows partial keys), the start procedure is used only if an entire key is given to the start verb. This procedure is also special in that it does not return data, but needs to raise an error condition if the start fails. The way to raise the error condition from within the stored procedure is to include code similar to the following:

raiserror 22006 “Record not found”

The code 22006 is very important. It is the code searched for in setting the error condition from within the Acu4GL product. If you use a different number, your starts may succeed when they should actually fail.

For example, based on the sample XFD, you might want to create the following stored procedure to start a file:

create procedure ftestdat_start001
@mode varchar(2),
@ft2_key1_seg1 char(2),
@ft2_key1_seg2 char(2)
as

if exists (select 1 from ftestdat where

(ftest2_key1_seg1 = @ft2_key1_seg1 and
((@mode = “>=“ and ftest2_key1_seg2 >=@ft2_key1_seg2) or
(@mode = “>“ and ftest2_key1_seg2 > @ft2_key1_seg2) or
(@mode = “=“ and ftest2_key1_seg2 = @ft2_key1_seg2) or
(@mode = “<“ and ftest2_key1_seg2 < @ft2_key1_seg2) or
(@mode = “<=“ and ftest2_key1_seg2 <= @ft2_key1_seg2))))
return
if exists (select 1 from ftestdat where
(((@mode = “>=“ or @mode = “>“) and
ftest2_key1_seg1 > @ft2_key1_seg1) or
((@mode = “<=“ or @mode = “<“) and
ftest2_key1_seg1 < @ft2_key1_seg1)))
return
raiserror 22006 “Record not found”

grant execute on ftestdat_start001 to public
Parent topic: Developer- or Site-supplied Stored Procedures


Built-in Stored Procedures

Several stored procedures come with Acu4GL for Sybase. One, sp_AcuInit, provides a means for customized initialization. The others return information based on the AcuOpenTables and AcuLocks tables.

Note: Note:

You will see that the names of several stored procedures end in “_1”, indicating the first version of the stored procedure. Whenever a stored procedure is updated, the extension is updated by one. This is why you can install new stored procedures without overwriting older ones. Be sure to install all stored procedures when you install Acu4GL for Sybase.

  • sp_AcuInit
  • sp_AcuRemoveUnusedLocks_1
  • sp_AcuTableReport_1
Parent topic: Stored Procedures


sp_AcuInit

If the stored procedure sp_AcuInit exists in the master database, it is executed when the connection is made to the server. This is a procedure you can set up to perform customized initialization. This stored procedure does not take any parameters and does not return any results. This optional stored procedure is executed for all connections by the Acu4GL interface to the database, not just the primary connection.

As an example of customized initialization, you can use this stored procedure to remove stale locks by calling sp_AcuRemoveUnusedLocks_1 (which is installed when all the other Acu4GL stored procedures are installed) or to limit access to the database by certain users during certain hours. If sp_AcuInit returns an error, the connection is denied and the error is reported to the COBOL program. The method for returning an error is to execute the Transact-SQL statement “raiserror”. See your database documentation for information about Transact-SQL and stored procedures.

Parent topic: Built-in Stored Procedures


sp_AcuRemoveUnusedLocks_1

Use this stored procedure to determine who is logged in and to remove Process IDs that are no longer active on the system. You can call this from sp_AcuInit each time a user connects to the database to ensure that the lock table contains only active locks. This stored procedure must reside in the same database as the AcuOpenTables and AcuLocks tables; it is placed there automatically when these tables are created during installation.

Parent topic: Built-in Stored Procedures


sp_AcuTableReport_1

Use this stored procedure to learn who is using the tables in the database at the time this procedure is run. Run this procedure before running the sp_AcuZeroUserCount stored procedure, so that you can contact users to inform them that the database will be closing. This stored procedure must reside in the same database as the AcuOpenTables and AcuLocks tables; it is placed there automatically when these tables are created during installation.

Parent topic: Built-in Stored Procedures


Limits and Ranges

The following limits exist for the Sybase file system:

  • Maximum number of columns per key: 16
  • Maximum number of columns: 250
  • Maximum number of bytes in a single row when using Acu4GL for Sybase: 1962

To achieve the same sort or retrieval sequence under Sybase as under the Vision file system, key fields that contain signed numeric data must be preceded by a BINARY directive.

Acu4GL for Sybase supports the data types shown below. When it’s creating tables, the following conversion rules are used, in the sequence shown:

COBOL | Sybase
DATE directive | DATETIME
BINARY directive
  • VARBINARY(n) (if SIZE < 255)
  • IMAGE (if SIZE > 255)
VAR_LENGTH directive | VARCHAR(n) (if SIZE < 255)
Usage FLOAT
  • REAL (if SIZE = 4)
  • FLOAT (if SIZE = 8)

Any other numeric usage:

  • PIC
  • 9(n)V9(m)
  • SMALLINT (if m = 0 and n < 5)
  • INT (if m = 0 and n < 10)
  • DECIMAL(n + m, m)(otherwise)

Any other usage:

  • PIC
  • X(n)
  • CHAR(n) (if n < 255)
  • TEXT (if n > 255)

Other limits are described in Limits and Ranges of the ACUCOBOL-GT documentation.

Parent topic: Appendix E: Acu4GL for Sybase Information


Runtime Errors

This topic lists the Acu4GL error messages that could occur during execution of your program. The Compiler and Runtime Options topic provides information on compile-time errors and also provides several methods for retrieving runtime errors.

An explanation and a recommended recovery procedure follow each message.

Runtime errors have this format:

9D/nn

The 9D indicates a file system error and is reported in your FILE STATUS variable. The nn is a secondary error code. These are the secondary errors reported directly from Acu4GL:

9D/01 Read error on dictionary file

An error occurred while reading the XFD file; this probably means the XFD is corrupt. Recreate the XFD file.

9D/02 Corrupt dictionary file

The dictionary file for one of your COBOL files is corrupt and cannot be read. Recompile with -Fx to re-create the dictionary. See Compiler and Runtime Options for additional information on compiler options.

9D/03 Dictionary (.xfd) file not found

The dictionary file for one of your COBOL files cannot be located. Be sure you have specified the correct directory via your XFD_PREFIX runtime configuration file variable. You may need to recompile with -Fx to create the dictionary.

9D/04 Too many fields in the key

There are more than 16 fields in a key. Check your key definitions and restructure the key that is illegal, and then recompile with -Fx.

9D/05 (no message associated with this error)

A date given to the Acu4GL interface is invalid and cannot be converted.

9D,06 Mismatched dictionary file

The dictionary file (.xfd) for one of your files conflicts with the COBOL description of the file FD. The xx indicates a tertiary error code that is defined by the host file system. You can determine the exact nature of the mismatch by referring to the host system’s error values.

The tertiary error code may have any of these values:

01 – mismatch found but exact cause unknown (this status is returned by the host file system)

02 – mismatch found in file’s maximum record size

03 – mismatch found in file’s minimum record size

04 – mismatch found in the number of keys in the file

05 – mismatch found in primary key description

06 – mismatch found in first alternate key description

07 – mismatch found in second alternate key description

The list continues in this manner for each alternate key.

9D/11 ACUCOBOL-GT stored procedures not found

or

ACUCOBOL-GT lock table missing

The installation of Acu4GL for Sybase creates a number of stored procedures and tables. At least one of these was not found.

9D/12 A column of a key is of data type TEXT or IMAGE, which is illegal

Columns that are part of an index may not be of type TEXT or type IMAGE. Check your key definition.

9D/13 Internal error

Multiple records were found with the same index (this is a Sybase error).

9D/14 DB library function returned an unexpected errordbinit

(Sybase) failed. An error message from Sybase is displayed on the terminal.

9D/16 Trying to rename a table across databases

RENAME works only within the same database.

9D/17 Cache error (internal error)

The internal process cache has been corrupted. Please contact Technical Services.

9D/18 Primary Key error

This means there was an error when creating the primary key for a secondary table.

9D/19 Table Size Error

The table is larger than Sybase will accept, either in the number of columns or in the number of bytes in the row. Use the SECONDARY_TABLE directive to get around this.

9D/20 (no message associated with this error)

This error tells you that you are trying to do something with a FAST_ACCESS table that is not allowed. See A_SYB_FAST_ACCESS to learn the restrictions for tables opened this way.

9D/21 (no message associated with this error)

There was a problem accessing one or more Vision locks files and processing of this request cannot continue. The tertiary error is an error code returned from Vision.

Parent topic: Appendix E: Acu4GL for Sybase Information


Appendix F: Acu4GL for DB2

  • DB2 Concepts Overview
  • Installation and Setup
  • Filename Translation
  • Decimal Points
  • Configuration File Variables
  • Record and Table Locking
  • Limits and Ranges
  • Data Type Mapping
  • Runtime Errors
  • Common Questions and Answers
Parent topic: Acu4GL Version 10.2.0 User's Guide


DB2 Concepts Overview

This quick overview of some basic design concepts underlying the DB2 relational database management system (RDBMS) helps to interface your COBOL program to it.

  • Transactions
  • Record-locking Issues in Transactions
  • Acu4GL and Record Locking
Parent topic: Appendix F: Acu4GL for DB2


Transactions

The DB2 RDBMS is a transaction-based system. All of the work that you perform while using DB2 must occur within a transaction, whether that work is being done through the Acu4GL for DB2 or another application. When you use Acu4GL for DB2, a transaction is implicitly started for you by the database engine itself with the first file I/O operation performed on a file associated with DB2. Because all operations with Acu4GL for DB2 occur within a transaction, any record locked during processing remains locked until either a COMMIT WORK or ROLLBACK WORK is issued by Acu4GL. This action results in behavior similar to the LOCK ON MULTIPLE RECORDS clause in COBOL.

The benefits of this transaction management system are best illustrated by an example. A COBOL application that handles order entry might perform these steps to accept an order:

  • Write an invoice record
  • Update a customer record
  • Write a payroll record for sales commissions
  • Update an inventory record

This series of four file operations is a logical unit. If the program were interrupted and had completed only some of the four file operations, the files would be in an inconsistent state. For example, if the program terminated unexpectedly after it updated the customer record, but before it updated the inventory record, a subsequent run might access non-existent inventory.

The solution to this problem is to provide a method for the programmer to define a set of operations that should either all occur or all not occur. Then, if the program encounters an error or terminates, the files are left in a consistent state.

All file operations that are part of a transaction are logged. Once logged, they can be either committed or rolled back (undone) by the program.

If a program dies, or the system fails, the log file can be used to reconstruct complete transactions, returning all files to a consistent state. Transaction logging gives the ability to:

  • Define and commit transactions, or undo them (usually in response to an error condition); this undo facility is called a rollback
  • Reconstruct files into a consistent state after a program dies or system failure occurs; this operation is called recovery
Parent topic: DB2 Concepts Overview


Record-locking Issues in Transactions

Applications that are written for transaction management systems, or that perform work in small operation-based logical units, benefit greatly from DB2's transaction management systems. Other applications may encounter difficulty with record locking when operating against a system (DB2) that enforces transaction management.

The difficulty can occur with an application that is performing more than one logical task at a time. Any operation that modifies or reads data in an I/O mode without the WITH NO LOCK phrase causes a lock to be placed in the database system. As a result, the application may have many more record locks present than would be expected by the normal rule of COBOL file locking. The application would act in a manner similar to when the LOCKS ON MULTIPLE RECORDS clause in COBOL is used. This can best be illustrated by an example:

  1. The user is entering a customer's order.
  2. As each line item is entered into the order, the inventory file is modified to reflect that items have been removed from the stock on hand.
  3. The user must switch to a different part of the application to perform a different task, perhaps as a result of a phone call from a new customer.
  4. All of the records that were locked, or modified, by the application before the switch remain locked because the first order is not complete. As no COMMIT or ROLLBACK has been issued, all of the records remain locked until the application ends, thus ending the transaction.
  5. Because one order is open and not yet committed, other applications may be locked out of certain order items if they are still locked by the processing of the first order. The second order entry may be held up until the first order is completed.

Note that the first application is not locked out. A process can read its own locked records.

Parent topic: DB2 Concepts Overview


Acu4GL and Record Locking

Your DB2 database may be set up for wait-level locks. The DB2 universal database products have the ability to time-out a lock and send an error return code to the waiting application. See your database administrator for details. (This SQL code would be placed in ERROR_MAP_FILE.)

Acu4GL provides semi-automated ways to handle transaction logging based on the setting of the 4GL_COMMIT_COUNT environment variable. You can also directly alter your source code to deal with this issue. Individual users determine how much work they wish to do to conform to Oracle's transaction management system by choosing the method that best fits their needs and resources. The following methods are listed in order of increasing amount of work:

4GL_COMMIT_COUNT = 0 (Default)

When you set this variable to zero, the run time system tracks the number of logical locks that are currently in effect. When the number of logical locks reaches zero, the run time system assumes that a transaction is complete and issues a COMMIT statement.

4GL_COMMIT_COUNT = n

When you set this variable to a nonzero value, the run time system tracks the number of WRITE, REWRITE, and DELETE operations, until the value of 4GL_COMMIT_COUNT is reached, at which time the run time system issues a COMMIT statement. The READ, START, and READ NEXT operations do not count toward this total, because the run time system is tracking data-altering operations rather than logical record locks. The disadvantage of this method is that when a COMMIT is issued, any record locks held by the run time system are released.

4GL_COMMIT_COUNT = -1

No commit is issued by Acu4GL. When 4GL_COMMIT_COUNT is set to -1, alternate ways to perform a commit or rollback include:

  • Call your database query tool with COMMIT WORK or ROLLBACK WORK.
  • Use the COBOL verbs COMMIT and ROLLBACK.

COMMIT_COUNT is set to -1 automatically when you use the transaction management facilities available in ACUCOBOL-GT. A COMMIT WORK is, however, issued on exit from the run time system (for example, on execution of a STOP RUN).

COMMIT VERB IN COBOL

This method forces a COMMIT to be sent to DB2. It can be used in conjunction with other modes of COMMIT handling. For non-ORACLE files, this is equivalent to the UNLOCK ALL verb.

EXPLICITLY CODED TRANSACTIONS

This method provides the greatest flexibility in that transactions are tailored specifically for the user's application. This method also requires the most work for traditional COBOL programs in which transaction modules may not be clearly defined.

For additional information, see Record and Table Locking.

Parent topic: DB2 Concepts Overview
Related information
A_DB2_ERROR_MAP_FILE configuration variable
4GL_COMMIT_COUNT configuration variable
Record and Table Locking


Installation and Setup

The following section covers the client setup required before you begin using Acu4GL for DB2 on a new system.

Before you begin, you need to have:

  • Access to an already installed and configured DB2 database.
  • Configured any client software (if the server is on a remote machine), and verify a successful connection to the intended database.

You should consult your DB2 documentation for help with these tasks.

Once you have successfully connected to your DB2 database, continue with the Acu4GL-specific configuration.

  • Windows Installation Steps
  • UNIX Installation Steps
  • Sample ACUCOBOL-GT runtime configuration file
  • Setting Up the User Environment
  • Designating the Host File System
  • Designating the Host Data Source
Parent topic: Appendix F: Acu4GL for DB2


Windows Installation Steps

The DB2 RDBMS, version 8.2.0 or higher, must be installed and configured prior to the installation of Acu4GL for DB2. Consult your DB2 documentation if you have any questions regarding this step.

You also should have the client software installed and configured, along with any database aliases, before installing Acu4GL for DB2.

Note: Acu4GL for DB2 requires DB2 client software version 6.01 or higher on the client machine. The bin directory of your DB2 client software must be in your PATH.

Installation from CD or Download

The ACUCOBOL-GT main Windows installer is used to instal Acu4GL for DB2. The installer will guide you through the install steps.

Once the installation is complete, refer back to the appendix for set up information.

Acu4GL for DB2 is a windows ".DLL" ("a4db232.dll") that is loaded at run time from the "bin" directory of your ACUCOBOL-GT product distribution.

Parent topic: Installation and Setup


UNIX Installation Steps

The Acu4GL for DB2 product on UNIX is an add-on module that must be linked with the ACUCOBOL-GT runtime system. For this reason, you'll need a C compiler to install the Acu4GL product. To interface, you must use the ACUCOBOL-GT compiler and runtime, and the version of the runtime must match the version of Acu4GL.

The Acu4GL product is shipped using either TAR or CPIO format, depending on the type of machine you have. The label on the medium shipped to you tells you which format has been used.

From your Acucorp directory, choose where you want to install the Acu4GL product (or create a new directory for it) and then enter one of the following commands:

tar xfv device

Or:

cpio -icvBd < device

This will copy the files from the distribution medium to your ACUCOBOL-GT directory structure. device is the appropriate hardware device name (for example, /dev/rdiskette or /dev/rmt0). Sites using Texas Instruments System 1500 should add an uppercase "T" to the cpio options (-icvBdT).

Licenses

Each Acu4GL product has its own license file, which must be located in the same directory as the ACUCOBOL-GT runtime. For DB2, the license file is distributed with the name "runcbl.klc".

Installation Steps

  1. Install DB2. The DB2 RDBMS, version 6.01 must be installed and configured prior to the installation of Acu4GL for DB2.
  2. Create a new runtime system by performing the following steps.
    Note: In the following directions, the term "runtime system" refers to the runtime shared object on systems where the ACUCOBOL-GT runtime is a shared object and to runcbl on other systems, where the runtime is static. The runtime is a shared object on the following systems: AIX 5.1 and later, HP-UX 11 and later, and Solaris 7 and later. To check, look at the contents of the "lib" subdirectory of your ACUCOBOL-GT installation. If the files "libruncbl.so" or "libruncbl.sl" reside in that directory, the runtime is a shared object on your system.
    1. Link the runtime system. Edit the Makefile in the "lib" subdirectory. Change the CFLAGS file to read as follows:
      CFLAGS = $(ACUSERVER_FLAGS) $(ACUCONNECT_FLAGS)
   $(ACUSQL_FLAGS) -DACU4GL -DUSE_DB2
    2. Edit the FSI_SUBS line to read as follows:
      FSI_SUBS = a4db2.o
    3. Edit the FSI_LIBS line to read as follows:
      FSI_LIBS = $(ACU_LIBDIR)/libexpat.a <ibm DB2
  directory>/lib/libdb2.so
    4. Make sure you are in the directory containing the ACUCOBOL-GT runtime system. Then, at the UNIX prompt, enter the following command:
      make

      This compiles "sub.c" and "filetbl.c", and then links the runtime system.

      Note: Make sure you have set all of the flags specific to your platform correctly before you relink your library and object files. If the make fails because of an out-of-date symbol table, execute the following command: ranlib *.a and then execute the make again. If the make fails for any other reason, call Technical Services.
  3. Veryify the link. Enter the following command:
    ./runcbl -vv

    This returns version information on all of the products linked into your runtime system. Make sure it reports the version of Acu4GL for DB2.

Shared Libraries

If you have relinked the ACUCOBOL-GT runtime and receive an error message of this type when you try to execute it:

"Could not load library; no such file or directory" "Can't open shared library . . . "

Tthis may mean that your operating system is using shared libraries and cannot find them. This can occur even if the shared libraries reside in the same directory in which you are currently located.

Set the environment variable LD_LIBRARY_PATH to find these shared libraries.

Parent topic: Installation and Setup


Sample ACUCOBOL-GT runtime configuration file

The cblconfi.db2 file is a sample ACUCOBOL-GT runtime configuration file. This file demonstrates the following:

  • Setting the DEFAULT_HOST to DB2
  • Designating an error map file used to map DB2's errors into COBOL errors
  • Setting the configuration variables required for ACUCOBOL-GT runtime configuration file for DB2 interface

Modify the cblconfi.db2 file to configure your individual login, password, and database (or database alias). These ACUCOBOL-GT runtime configuration file variables are:

  • A_DB2_LOGIN
  • A_DB2_PASSWD
  • A_DB2_DATASOURCE

The sample error mapping file is placed in the etc subdirectory of your installation directory.

Note: Be sure to set A_DB2_ERROR_MAP_FILE to the full path of the error map file.
Parent topic: Installation and Setup
Related information
Runtime Configuration Variables


Setting Up the User Environment

You must use the sample ACUCOBOL-GT runtime configuration file, described in Sample ACUCOBOL-GT runtime configuration file, and error map file as your template. These files contain important settings for DB2:

  • A_DB2_USE_CHAR_FOR_BINARY
  • Error mappings

In addition to setting the variables required for DB2, you need to perform certain steps, as detailed in To Set Up The User Environment.

  • To Set Up The DB2 User Environment
Parent topic: Installation and Setup
Related reference
A DB2 USE CHAR FOR BINARY configuration variable
Related information
Sample ACUCOBOL-GT runtime configuration file
To Set Up The User Environment


To Set Up The DB2 User Environment

  1. Create a plain text file that will serve as your ACUCOBOL-GT runtime configuration file.
  2. Within the ACUCOBOL-GT runtime configuration file, set the A_DB2_LOGIN and A_DB2_PASSWD variables, like so:
    A_DB2_LOGIN user-name
A_DB2_PASSWD passwd
    Note: Alternatively, you may not want to specify such details in a file. In which case, you can either set them as environment variables, or set the password variable from your COBOL program by prompting the user to enter a password and then executing:
    SET ENVIRONMENT "A_DB2_PASSWD" TO user-entry
  4. Set the A_DB2_DATASOURCE variable using one of the methods mentioned in the previous step.
  5. Define any other ACUCOBOL-GT runtime configuration file variables you require for your unique environment. For example, consider whether or not setting the USER_PATH variable would be useful in your setup situation.
  6. Set the A_CONFIG environment variable to identify your ACUCOBOL-GT runtime configuration file.
Parent topic: Setting Up the User Environment
Related reference
A_DB2_LOGIN configuration variable
A_DB2_PASSWD configuration variable
Run-time Configuration Variables
Configuration File Variables


Designating the Host File System

When your COBOL application opens an existing file, most file systems linked into the run time system are searched for the named file. However, each time the COBOL application creates a new file, it needs to know which file system to use. You provide the name of the file system with one of two run time configuration file variables. The first is:

DEFAULT_HOST filesystem

This designates the file system to be used for newly created files that are not individually assigned. For example,

DEFAULT_HOST DB2

means that all new files are DB2 files unless otherwise specified by the second ACUCOBOL-GT runtime configuration file variable, which is:

filename_HOST filesystem

where filename is the file name, without any extension, named in the ASSIGN TO clause of your SELECT statement. This variable is used to assign an individual data file to a different file system. Any file so assigned uses the designated file system, and not the one specified by DEFAULT_HOST. For example,

myfile_HOST VISION

means that myfile is under the VISION file system, and:

myfile_HOST DB2

means that myfile is under the DB2 file system. The ability to designate a different file system for certain files enables you to tailor your application to a specific customer's needs or to implement an incremental conversion for a customer. With relational databases, this is particularly useful in that it allows you to tune an application for processing speed and resource requirements.

You can use these run time configuration file variables in combination to assign your new files in a default with exceptions manner; for example, this set of entries:

DEFAULT_HOST VISION
afile_HOST DB2
bfile_HOST DB2

means that all new files except afile and bfile are assigned to data, and those two files are assigned to DB2.

You can also change the values of these variables during program execution by including in your code:

SET ENVIRONMENT "filename_HOST" TO filesystem

or

SET ENVIRONMENT "DEFAULT_HOST" TO filesystem

This enables you to change file systems during the execution of your program. This is not the typical way to specify a file system; normally it is designated in the run time configuration file and is not changed in the COBOL program.

Note: Acu4GL for DB2 allows you to create a DB2 table with an OPEN OUTPUT statement, just as you can create indexed files. The DB2 equivalent of an indexed file is a table, not a database. You must create a database for your DB2 tables before you run the COBOL program that creates the tables, just as you must create a directory for your files before you run a COBOL program that creates indexed files.
Parent topic: Installation and Setup


Designating the Host Data Source

You must tell the run time system which data source to use for your DB2 file. You accomplish this by setting the ACUCOBOL-GT runtime configuration file variable A_DB2_DATASOURCE. You can set this variable in your configuration file if using only one data source.

If you don't know the data source name in advance, or if you intend to use more than one data source, you may set the data source name dynamically at run time. In your COBOL program, you would add code similar to this prior to the statement that opens the file:

SET ENVIRONMENT "A_DB2_DATASOURCE" TO "DB2 Database"
Parent topic: Installation and Setup
Related reference
A DB2 DATASOURCE configuration variable
Preparing and Compiling Your COBOL Program Example
Demonstration Program


Filename Translation

As you prepare to work with Acu4GL, you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and eXtended File Descriptor (XFD) files are formed and work together. For detailed information on XFDs, see XFDs.

When the compiler generates XFD files, it uses lowercase letters to name the XFD file. In addition, the compiler changes hyphens to underscores when naming the XFD file.

Through ACUCOBOL-GT runtime configuration file variables, the run time system translates the name in the COBOL program into the filename that is passed to the open() function in the run time system. The open() function determines which file system to pass the request to, but does not change the name of the file.

Acu4GL translate the name to uppercase letters and changes hyphens to underscores. File extensions are stripped, based on the setting of 4GL_IGNORED_SUFFIX_LIST. This new name is the one that Acu4GL uses for references to database tables.

Parent topic: Appendix F: Acu4GL for DB2
Related reference
XFDs
4GL IGNORED SUFFIX LIST configuration variable


Decimal Points

Acu4GL reads the decimal point character from the environment variable DECIMAL_POINT. If DECIMAL_POINT is set, Acu4GL uses that character. If the variable is not set, Acu4GL uses the decimal character that is encoded in the XFD file.

The two most common decimal indicators are the period “.” and the comma “,” characters. The comma is used often in European code and is often indicated in COBOL programs by the DECIMAL POINT IS COMMA clause.

Parent topic: Appendix F: Acu4GL for DB2


Configuration File Variables

These topics list the runtime configuration file variables that are specific to Acu4GL for DB2. Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in Runtime Configuration Variables.

  • A_DB2_ALTERNATE_COMMIT_LOGIC configuration variable
  • A_DB2_CATALOG configuration variable
  • A_DB2_COMMIT_ON_BEGIN
  • A_DB2_DATASOURCE configuration variable
  • A_DB2_ERROR_MAP_FILE configuration variable
  • A_DB2_ISOLATION_LEVEL configuration variable
  • A_DB2_LOCK_METHOD configuration variable
  • A_DB2_LOGIN configuration variable
  • A_DB2_PASSWD configuration variable
  • A_DB2_STRICT_EQUAL configuration variable
  • A_DB2_TABLE_TYPES configuration variable
  • A_DB2_USE_CATALOG configuration variable
  • A_DB2_USE_CHAR_FOR_BINARY configuration variable
  • A_DB2_USE_SQLCOLUMNS configuration variable
  • A_DB2_USE_SQLTABLES configuration variable
  • USER_PATH (for DB2) configuration variable
Parent topic: Appendix F: Acu4GL for DB2


A_DB2_ALTERNATE_COMMIT_LOGIC configuration variable

The primary purpose of the configuration variable 4GL_COMMIT_COUNT is to provide for applications that must communicate with a transaction-oriented database but have not explicitly coded transactions into their COBOL application.

A_DB2_ALTERNATE_COMMIT_LOGIC determines how the interface responds to the setting of 4GL_COMMIT_COUNT.

Value | Result
0 or FALSE (the default) | The value of 4GL_COMMIT_COUNT is checked only at startup. The interface issues a commit when the criteria set by 4GL_COMMIT_COUNT is met, regardless of the current transaction state
1 | The value of 4GL_COMMIT_COUNT is checked after each WRITE, REWRITE, DELETE, or UNLOCK operation. A commit is issued; however, only if the run time is not currently in a transaction

Example

4GL_COMMIT_COUNT=1
A_DB2_ALTERNATE_COMMIT_LOGIC=0

Each WRITE operation is committed to the database immediately. This prevents an application from being able to rollback a WRITE.

Parent topic: Configuration File Variables
Related information
4GL_COMMIT_COUNT configuration variable


A_DB2_CATALOG configuration variable

This variable indicates the catalog name to be used when Acu4GL searches for objects in the database. Note that not all data sources support a catalog. Using A_DB2_CATALOG with other variables, such as USER_PATH and A_DB2_TABLE_TYPES, can speed up the finding of tables in large databases. It can also prevent an error 9/14: More than one table with the same name, thereby enabling access to tables with identical names, but with different catalogs.

For example, If USER_PATH and A_DB2_CATALOG are used, the form of the SQL statement is modified from:

select COL1, ... from TABLENAME ...

to:

SELECT COL1, ... FROM [catalog.][username.]TABLENAME ...

where catalog and username are filled in if provided.

Parent topic: Configuration File Variables
Related information
A_DB2_TABLE_TYPES configuration variable
USER_PATH configuration variable


A_DB2_COMMIT_ON_BEGIN

DB2 has no START TRANSACTION method. Everything since the last COMMIT or ROLLBACK is considered part of the current transaction.

To ensure that the previous transaction has been ended before a new one begins, set A_DB2_COMMIT_ON_BEGIN to a nonzero value. This causes each COBOL START TRANSACTION to first issue a COMMIT. This ensures that the previous transaction has been ended before the new one starts.

If this variable is not set, or is set to 0, a COBOL ROLLBACK may affect file I/O that occurred before the most recent COBOL START TRANSACTION. While the default value is 0 (off, false, no), this configuration variable can also take values of On (true, yes).

Parent topic: Configuration File Variables


A_DB2_DATASOURCE configuration variable

Set A_DB2_DATASOURCE to the exact name of the host data source. You can set this variable in your COBOL ACUCOBOL-GT runtime configuration file if using only one data source.

Example

A_DB2_DATASOURCE stores

If you don't know the data source name in advance, or if you intend to use more than one data source, you may set the data source name dynamically at run time. In your COBOL program, you would add code similar to this prior to the statement that opens the file:

SET ENVIRONMENT "A_DB2_DATASOURCE" TO "data source name"

There is no default value for this variable.

Parent topic: Configuration File Variables


A_DB2_ERROR_MAP_FILE configuration variable

Set A_DB2_ERROR_MAP_FILE to the name of the file that maps database-specific errors to COBOL errors. This variable allows you to map errors using a text file to supplement the default method of providing errors. Create the file using the guidelines described in To create an error map, and then use this variable to indicate the name and location of the file you created.

Example

If the file used for mapping is called db2.err, and this file is located in the directory C:\DB2, you would specify:

A_DB2_ERROR_MAP_FILE  c:\DB2\db2.err

There is no default value for this variable.

  • To create an error map
Parent topic: Configuration File Variables
Related information
To create an error map


To create an error map

Create an error map file to map DB2 error messages to COBOL error responses. This file is optional.

Although you can check your data source documentation for error code information, the easiest way to determine which error codes need to be mapped to more appropriate COBOL codes is through trial and error. As users use Acu4GL DB2, they may report receiving error messages that don't make sense based on their situation. Research these errors and try to determine a more appropriate COBOL error response.

When you create your error map file, use the following guidelines:

  • Begin comment lines with "#". Blank lines are also considered comments
  • Break the rest of the file into sections, with each section header comprising all the information enclosed in brackets from the data source error function.

    The following example leads to the entry in the sample DB2 error file:

      OdbcOneInfo: State: 23505, Native Error: -803
  '[IBM][CLI Driver][DB2/NT]SQL0803N One or more values in the INSERT statement, UPDATE statement, or foreign key update caused by a DELETE statement are not valid because they would produce duplicate rows for a table with a primary key, unique constraint, or unique index.  SQLSTATE=23505'
  Setting f_errno = 19
Leaving, error
***File system error value = -803 ***
>>>file status = 9S,-803
  • Include two fields in each line in the section: the internal error number, and a mapping string.

    Using the same example, you would include this line in the error_map file:

    -803 E_DUPLICATE

    The valid values for the second field are as follows:

    E_SYS_ERR
E_PARAM_ERR
E_TOO_MANY_FILES
E_MODE_CLASH
E_REC_LOCKED
E_BROKEN
E_DUPLICATE
E_NOT_FOUND
E_UNDEF_RECORD
E_DISK_FULL
E_FILE_LOCKED
E_REC_CHANGED
E_MISMATCH
E_NO_MEMORY
E_MISSING_FILE
E_PERMISSION
E_NO_SUPPORT
E_NO_LOCKS
Parent topic: A_DB2_ERROR_MAP_FILE configuration variable


A_DB2_ISOLATION_LEVEL configuration variable

Use the A_DB2_ISOLATION_LEVEL variable to set the isolation level. The default ordering of isolation levels is:

  1. SQL_TXN_READ_COMMITTED
  2. SQL_TXN_READ_UNCOMMITTED
  3. SQL_TXN_REPEATABLE_READ
  4. SQL_TXN_SERIALIZABLE

You can change the isolation level by setting this variable to an integer in the ACUCOBOL-GT runtime configuration file. The settings are:

Isolation level | Setting in ACUCOBOL-GT runtime configuration file
SQL_TXN_READ_UNCOMMITTED | 1
SQL_TXN_READ_COMMITTED | 2
SQL_TXN_REPEATABLE_READ | 3
SQL_TXN_SERIALIZABLE | 4

For example, to set the isolation level to SQL_TXN_READ_COMMITTED, add the following entry to the ACUCOBOL-GT runtime configuration file:

A_DB2_ISOLATION_LEVEL 2

If the user-set isolation level is not supported by the driver, the default method of selecting a level is used.

Parent topic: Configuration File Variables


A_DB2_LOCK_METHOD configuration variable

Use this configuration variable to specify the locking method that Acu4GL for DB2 should use when accessing your data source. Possible values are:

  • None
  • SETPOS
  • SETSTMTOPTION
  • UPDATECOLUMN

The default is UPDATECOLUMN.

Example:

A_DB2_LOCK_METHOD UPDATECOLUMN

SETPOS

Specify SETPOS as your lock method to tell the Connector to perform the following locking sequence:

  • When setting up a statement handle for accessing the DB2 data source, Acu4GL calls a function called SQLSetScrollOptions, with values (SQL-CONCUR-LOCK, SQL-SCROLL-KEYSET-DRIVEN, 1)
  • When fetching rows from the data source, Acu4GL calls SQLExtendedFetch instead of SQLFetch
  • Finally, the Connector calls SQLSetPos, with the values (1, SQL-POSITION, SQL-LOCK-EXCLUSIVE)

If any of these functions do not exist, A_DB2_LOCK_METHOD reverts to None.

Note: Even if these functions do exist, there is no guarantee that any rows lock using this sequence of calls. Contact your database vendor to determine whether or not this sequence is effective for your data source.

SETSTMTOPTION

This option is similar to SETPOS, except a function called SQLSetStmtOption performs the task of SQLSetScrollOptions and has more functionality.

In particular, when using this method of locking, Acu4GL calls SQLSetStmtOption a number of times, with values (SQL-CONCURRENCY, SQL-CONCUR-LOCK), (SQL-CURSOR-TYPES, SQL-CURSOR-KEYSET-DRIVEN), and (SQL_KEYSET-SIZE, 1). Again, if the function does not exist, A_DB2_LOCK_METHOD reverts to None.

UPDATECOLUMN

Specifying UPDATECOLUMN as your lock method performs an entirely different type of locking. Instead of trying to lock a row while reading it, this method creates a new statement handle for the data source. Then, after fetching the data from the data source, it resubmits an SQL query to select the same row (based on the primary key) and adds an UPDATE clause. Last, it fetches the data from the data source. This method has the most overhead, but it is much more likely to succeed in locking records.

Parent topic: Configuration File Variables


A_DB2_LOGIN configuration variable

A_DB2_LOGIN indicates the user name under which you want to connect to the database system. Not all data sources require a user login name. Those that do may have case requirements. Check your data source documentation to determine if login is case-sensitive.

Example

To connect to the database with the user name MYNAME, you could specify:

A_DB2_LOGIN  MYNAME

or

A_DB2_LOGIN  myname

in the Acu4GL. There is no default value for this variable. If no login is specified, none is used.

Parent topic: Configuration File Variables
Related information
A_DB2_PASSWD configuration variable


A_DB2_PASSWD configuration variable

A_DB2_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_DB2_LOGIN. Not all data sources require a password. Those that do may have case requirements. Check your data source documentation to determine if password is case-sensitive.

Examples

If the account with the user name in A_DB2_LOGIN has the associated password CW021535, you would specify:

A_DB2_PASSWD  CW021535

in the Acu4GL.

For better security, you can accept a password from the user during program execution; set the A_DB2_PASSWD variable based on the response:

ACCEPT RESPONSE NO-ECHO.
SET ENVIRONMENT "A_DB2_PASSWD" TO RESPONSE.
Note: If the user has been set up without a password, this variable need not be set. There is no default value for this variable. If no password is specified, none is used.
Parent topic: Configuration File Variables
Related information
A_DB2_LOGIN configuration variable


A_DB2_STRICT_EQUAL configuration variable

When Acu4GL for DB2 executes a START ... KEY EQUAL keyval, the interface generates a SELECT statement to select all rows with a key equal to the key columns in keyval. When fetching the data, Acu4GL eventually detects that there is no more data.

If A_DB2_STRICT_EQUAL is set to True at the time the START is executed, the interface returns the error END OF FILE (error 10) at this point. If A_DB2_STRICT_EQUAL is set to False (default), Acu4GL then generates a new SELECT statement to continue reading records until the end of the file rather than the subset of records represented by keyval, and these records may be discarded by the program. (Note that this is program-dependent behavior.)

Setting A_DB2_STRICT_EQUAL to True causes the interface to stop reading records earlier, which can make SELECT statements generated by Acu4GL more efficient.

Note the following conditions:

  • A_DB2_STRICT_EQUAL must be set to True when the START is executed
  • The START must be a KEY EQUAL start
  • There must be no COMMITs between the START and the end of the file. Because DB2 closes all cursors on COMMIT and ROLLBACK (according to the ANSI 92 SQL standard), the interface must regenerate a SELECT the first time it attempts to execute a READ NEXT after a COMMIT or ROLLBACK. This means that 4GL_COMMIT_COUNT should be set to -1, so that no COMMITs are issued by Acu4GL
  • A_DB2_STRICT_EQUAL is most useful with alternate keys that allow duplicates

While the default value is False (off, no, 0), this variable can also take the value True (on, yes, 1).

Note: This same behavior can be accomplished with the 4GL_WHERE_CONSTRAINT, but using A_DB2_STRICT_EQUAL requires less programming.
Parent topic: Configuration File Variables
Related information
4GL_COMMIT_COUNT configuration variable
4GL_WHERE_CONSTRAINT configuration variable


A_DB2_TABLE_TYPES configuration variable

This variable is used to specify a table type (such as TABLE or VIEW) to search for when selecting a database table. Using A_DB2_TABLE_TYPES with other variables, such as USER_PATH, can speed up finding tables in large databases.

This information is passed to the API function call SQLTables() as the TableType parameter. Please refer to your driver’s documentation for supported types.

Example

A_DB2_TABLE_TYPES  TABLE,VIEW
Parent topic: Configuration File Variables
Related information
USER_PATH configuration variable
A_DB2_CATALOG configuration variable


A_DB2_USE_CATALOG configuration variable

Not all data sources support a catalog, or the data sources may return a catalog name that is not useful. The default behavior of the run time is to not use the catalog in the actual SQL queries. This configuration variable lets you modify this behavior.

The default value is FALSE, which causes the catalog portion of the table name to be treated as blank in SQL queries. Setting this variable to TRUE uses the catalog value returned by SQLTables ODBC function subsequent SQL queries.

Parent topic: Configuration File Variables


A_DB2_USE_CHAR_FOR_BINARY configuration variable

Some data sources have restrictions on the number of binary large objects (BLOBs) that can be placed into a single table. If your data source has such restrictions, specify A_DB2_USE_CHAR_FOR_BINARY in the ACUCOBOL-GT runtime configuration file. Possible values for this variable are:

0 | use BINARY type
1 | use CHAR type

A nonzero value for A_DB2_USE_CHAR_FOR_BINARY lets you store data that uses the BINARY XFD directive as hexadecimal encoded CHAR types. This lets you work around your data source restriction. While the default value is 0 (off, false, no), this variable can also take values of On (true, yes).

Because of current limitations of the interface, you must set this variable to 1, or the database returns an error on file creation. This has been set for you in the sample ACUCOBOL-GT runtime configuration file cblconfig.db2. Do not change this setting.

Example

A_DB2_USE_CHAR_FOR_BINARY 1
Parent topic: Configuration File Variables


A_DB2_USE_SQLCOLUMNS configuration variable

For some large databases, the API function SQLColumns(), which is called to get a description of the columns in a table, sometimes takes a long time to execute. If you are experiencing such problems, you can use the API function call SQLDescribeCol() instead, which can improve performance for large databases.

To turn on this new functionality, set A_DB2_USE_SQLCOLUMNS to FALSE. The default value for this variable is TRUE.

Parent topic: Configuration File Variables


A_DB2_USE_SQLTABLES configuration variable

For some large databases, the API function SQLTables(), which is called to get a list of the tables and information about them, sometimes takes a long time to execute. If you are experiencing such problems, you can instruct the interface to build a test SQL query and use the API function call SQLNumResultTables() to determine if the table exists. This may improve performance for large databases.

To turn on this new functionality, set the A_DB2_USE_SQLTABLES configuration variable to FALSE. The default value of this variable is TRUE, which means the interface uses the SQLTables() API function.

Parent topic: Configuration File Variables


USER_PATH (for DB2) configuration variable

USER_PATH indicates the user name or names (schemas) to be used when Acu4GL searches for files. The order of the names is significant. The syntax for this variable is:

USER_PATH  user1 [user2]...

where the user argument may be either the name of a user (schema) on the system, or a period (“.”), which indicates the files owned by yourself.

The type of OPEN being issued for the file determines the effects of this setting.

Examples

If an OPEN INPUT or OPEN I/O is issued, and a USER_PATH variable is defined in the ACUCOBOL-GT runtime configuration file, Acu4GL searches for a user of the named file in the list of users in USER_PATH. The first valid file is opened.

If USER_PATH is defined and the current user is the owner of the file, the current user must be included as one of the users, as indicated by a “.” or the setting of your login schema (A_DB2_LOGIN) in the USER_PATH. If this is not the case, even though the current user has created the table, it is not found and a file error 35 occurs. This circumstance can occur if the file is created with the OPEN OUTPUT phrase, and “.” is not an element in USER_PATH. When the table is created, the current user is the owner of that table. When the run time attempts to open the table, it does not look for tables owned by the current user unless USER_PATH is not set, or unless “.” or the user's current schema is part of the USER_PATH setting.

If an OPEN INPUT or OPEN I/O is issued, and no USER_PATH variable is in the ACUCOBOL-GT runtime configuration file, Acu4GL searches for a user of the named file in the user named for login A_DB2_LOGIN). Acu4GL opens the first file that has a valid combination of user and file name.

If an OPEN OUTPUT is issued (whether USER_PATH is present or not), a new table is created with the owner being the name specified in A_DB2_LOGIN.

Using USER_PATH with other variables such as A_DB2_CATALOG can speed up the finding of tables in large databases. It can also prevent an error 14: More than one table with the same name, thereby enabling access to tables with identical names, but with different schemas.

For example, If using both USER_PATH and A_DB2_CATALOG , the form of the SQL statement changes from:

select COL1, ... from TABLENAME ...

to:

SELECT COL1, ... FROM [catalog.][username.]TABLENAME ...

where catalog and username are filled in if provided.

Parent topic: Configuration File Variables
Related information
A_DB2_LOGIN configuration variable
A_DB2_CATALOG configuration variable


Record and Table Locking

With Acu4GL, records are locked in a Wait mode. An application trying to read a locked record does not respond until the record becomes available.

DB2 Universal Database products have the ability to time-out a lock and send an error return code to waiting applications. See your database administrator for additional information.

Parent topic: Appendix F: Acu4GL for DB2


Limits and Ranges

The following limits exist when working with DB2:
Maximum number of columns per key: | 16
Maximum number of columns: | 500
Maximum index size: | 255
Maximum record size: | 4005
Note that these limits may be further constrained by your database configuration. For example, the size of your page affects the maximum row size. Some limits are given here, but please refer to your database documentation for additional information.
Page Size | Maximum Row Size | Maximum Column Count | Maximum Index Size
4K | 4,005 | 500 | 255
8K | 8,101 | 1,012 | –
16K | 16,293 | 1,012 | –
32K | 32,677 | 1,012 | –

To achieve the same sort or retrieval sequence under DB2 as under the file system, place a BINARY XFD directive immediately before each key field that contains signed numeric data. High values and low values can cause problems in key fields. If you want data that uses the BINARY XFD directive to be stored as hexadecimal encoded CHAR types, you can specify A_DB2_USE_CHAR_FOR_BINARY in the ACUCOBOL-GT runtime configuration file.

Other limits are described in Limits and Ranges of the ACUCOBOL-GT documentation.

Parent topic: Appendix F: Acu4GL for DB2


Data Type Mapping

The table below shows the mappings used by Database Connectors when interacting with DB2. Note how some mappings use a combination of the data type and XFD directive. For additional information on XFD directives, see Using XFD Directives .

If you are in a position where you need to create a COBOL file descriptor (FD) based on an existing data source table, use these mappings as a guide; although, getting them correct is not critical, as when Database Connectors opens an existing data source, mapping is carried out by matching the COBOL data names with the column names.

If you do need to accurately represent your data in the COBOL program, setting your data items as PIC X(nn) will work perfectly well (since most DB2 data types have a CHAR representation). For INTEGER types, use PIC9(9), or if you know the range of an INTEGER column (say, 0 to 999), you can match it more closely (by using PIC 9(3)).

COBOL Data Type | Acu4GL for DB2
Date (DATE XFD directive applied) | date
binary (BINARY XFD directive applied) | char (2 * x)
varchar (VAR_LENGTH XFD directive applied) | varchar
float | float
pic 9(4) | smallint
pic 9(9) | integer
pic 9(10) | decimal(10,0)
pic 9(x)v9(y) | decimal (x + y, y)
pic x(254) | char
pic x(255) | or greater must apply VAR_LENGTH XFD directive
Parent topic: Appendix F: Acu4GL for DB2
Related reference
Using XFD Directives
DATE XFD directive
BINARY XFD directive
VAR LENGTH XFD directive


Runtime Errors

This topic lists the Acu4GL error messages that could occur during execution of your program. The topic Compiler Errors provides information on compile-time errors and also provides several methods for retrieving runtime errors.

An explanation and a recommended recovery procedure follow each message.

Runtime errors will have this format:

9D/nn

The 9D indicates a file system error and is reported in your FILE STATUS variable. The xx is a secondary error code. These are the secondary errors reported directly from Acu4GL:

9D/01 Read error on dictionary file

An error occurred while reading the XFD file; this probably means the XFD is corrupt. Recompile with -Fx to re-create the dictionary.

9D/02 Corrupt dictionary file

The dictionary file for one of your COBOL files is corrupt and cannot be read. Recompile with -Fx to re-create the dictionary.

9D/03 Dictionary (.xfd) file not found

The dictionary file for one of your COBOL files cannot be located. Be sure you have specified the correct directory via your XFD_PREFIX runtime configuration file variable. You may need to recompile with-Fx to create the dictionary.

9D/04 Too many fields in the key

There are more than 16 fields in a key. Check your key definitions and restructure the key that is illegal, and then recompile with -Fx.

9D/06 Mismatched dictionary file

The dictionary file (.xfd) for one of your files conflicts with the COBOL description of the file FD. The xx indicates a tertiary error code that is defined by the host file system. You can determine the exact nature of the mismatch by referring to the host system's error values. The tertiary error code may have any of these values:

01 - mismatch found but exact cause unknown (this status is returned by the host file system)

02 - mismatch found in file's maximum record size

03 - mismatch found in file's minimum record size

04 - mismatch found in the number of keys in the file

05 - mismatch found in primary key description

06 - mismatch found in first alternate key description

07 - mismatch found in second alternate key description

The list continues in this manner for each alternate key.

9D/12 DB2 library function returned an unexpected error

One of the DB2 library functions returned an error that was not expected.

9D/13 Illegal size or type of data for variable nnn

An elementary data item in your FD was larger than 255 bytes, or there is no DB2 type that matches the current data type.

9D/14 More than one table with the same name

When tables were listed, more than one table was found with the same name. Consider whether or not setting the USER_PATH configuration variable will resolve the issue. This variable will enable tables with identical names, but with different ownership (located in a different schema) to be found and accessed.

Parent topic: Appendix F: Acu4GL for DB2


Common Questions and Answers

This topic contains some questions and answers specific to Acu4GL for DB2.

On HP-UX platforms, which type of COBOL run time system - non-threaded or multi-threaded - should I use when connecting to the database?
You need to use the multi-threaded RTS, because DB2 is multi-threaded. If you use the non-threaded RTS, you will get a database connection error, because HP-UX does not allow the mixing of multi-threaded and non-threaded code.
On other UNIX/Linux platforms, you can use either run time system.
I'm noticing some performance degradation when accessing my DB2 data source. What is the cause of this?
You may notice some performance impact if you were previously accessing indexed files directly. This is because DB2 adds a software layer between your applications and your data sources. In return for minor performance impact, you can reap the benefits of database independence and enhanced portability. Overall performance depends on several factors, including your network configuration and your specific data source.
Are there any library routines that do not work with or would not make sense to use with Acu4GL for DB2?
Yes. The C$COPY and C$RENAME library routines do not work with DB2.
Parent topic: Appendix F: Acu4GL for DB2


AcuBench Version 10.2.0 User's Guide

  • Introduction
  • Getting Started
  • Workbench Concepts
  • Customize Your Working Environment
  • Version Control
  • Working with Projects
  • Project Settings
  • Working with Data at the Project Level
  • Working with Programs
  • Working with Data at the Program Level
  • Configuring the Code Editor
  • Working with Source Code
  • Configuring the Screen Designer
  • Working with Screens
  • Controls, Menus, and Toolbars
  • Configuring the Report Composer
  • Working with Reports
  • The Report Controls and Property Reference
  • Working with ACUCOBOL-GT Utilities
  • The AcuBench Integrated Debugger
  • Looking for Something?: Search and Replace
  • Toolbar Reference
  • Keyboard Reference Shortcut
  • Appendix: Bringing Existing Code Into AcuBench
Parent topic: extend Product Guides


Introduction

  • Product Overview
  • Companion Products
  • Product Support
Parent topic: AcuBench Version 10.2.0 User's Guide


Product Overview

Restriction: AcuBench no longer supports Windows XP or Windows Server 2003 (or any Windows platforms that pre-date these). This is because AcuBench utilizes a number of third-party libraries that have ceased to be supported on those platforms.

Welcome to the AcuBench® integrated development environment for COBOL from Micro Focus. AcuBench is a member of the extend® family of interoperability solutions. AcuBench extends and enhances the ACUCOBOL-GT® development system with a powerful suite of graphical tools for data, program, interface, and report design. With AcuBench you can develop and maintain your COBOL applications in a developer friendly Microsoft Windows environment and deploy your applications on any of the more than 600 platforms supported by Micro Focus.

Some of AcuBench's major features include:

  • a single, integrated user interface
  • a powerful and flexible workspace, project, program development model
  • extensive automated code generation capabilities that simplify the development of screens, reports, Working-Storage and Linkage section items, FDs and SELECTs, and other key program areas
  • specialized designers and editors for creating and maintaining:
    • data layout definitions (file descriptors)
    • data set associations
    • event procedures
    • Working-Storage items
    • Linkage section items
    • run-time configuration files
  • support for the ACUCOBOL-GT Thin Client technology, which lets you display your server-based application on graphical display hosts
  • an integrated source level debugger
  • graphical interfaces to ACUCOBOL-GT utilities
  • support for many third-party version control systems
  • a graphical interface that lets you design HTML and plain-text reports

AcuBench includes key project management supports for:

  • concurrent development of multiple projects
  • multiple project configuration management
  • multiple project and file level compilation settings (modes)
  • project level run-time and environment settings
  • automated inclusion of COBOL COPY files
  • access to external programs and utilities

Key code development features include:

  • user configurable, COBOL-sensitive source code editor
  • automated code completion capabilities (prompts for completing some phrases and easy insertion of template code)
  • paragraph, variable, COPY file, and constant lists
  • quick access to COPY files
  • ability to bookmark code for ease of navigation
  • search functions to find strings either in a specified directory structure or within a set of AcuBench objects

Key screen development capabilities include:

  • support for ActiveX controls
  • graphical and character-based screen designers
  • templates for graphical and character-based screens, plus the ability to create additional user-defined templates
  • graphical and character screen import capabilities
  • customizable control defaults and Property windows
  • in-line editing of event and embedded procedures

Integrated User Interface

The workbench presents all of its primary capabilities in an integrated main application window. This user-configurable window contains several interior windows for viewing projects; working with data; working with programs and their components, including screens and reports; and for monitoring several types of system output (compilation messages, version control actions, search results, and more). There are also special windows for coding embedded procedures and working with the integrated debugger. You can control the visibility, size, and placement of all interior windows and toolbars.

Project-centered Application Development

A project model is used to support AcuBench application development. Each element of a COBOL application, large or small, is identified, added to, and tracked by AcuBench as a project. As a result, applications enjoy a standard structure that makes them easier to manage and maintain. This architecture allows AcuBench to handle many aspects of application development for you. For example, when you direct AcuBench to build (compile) a project, AcuBench automatically determines which elements of the project must be recompiled to make the project current.

Parent topic: Introduction


Companion Products

AcuBench is interlinked with other members of Micro Focus's extend family of solutions. The following sections briefly describe the technologies most closely related to AcuBench.

ACUCOBOL-GT

ACUCOBOL-GT is an ANSI 1985 COBOL compiler designed to provide a powerful development environment for a wide range of computers. Fast compile speed, clear error messages, and a multi-window source level debugger work together to provide a high performance, easy to use COBOL development platform. Portable object code, a generic interface to a variety of file systems, and a device-independent terminal interface help to simplify the distribution of applications developed with ACUCOBOL-GT.

In addition to portable object code, ACUCOBOL-GT can generate and execute object files that contain native instructions for specific types of processors. This enables you to optimize the use of CPU resources on the host machine while maintaining full portability within the same family of processors.

Complete access to the ACUCOBOL-GT development system, including all of its utilities, is available from within the AcuBench integrated development environment.

AcuConnect®

AcuConnect is a client/server technology that is an integral part of extend’s distributed computing solution. AcuConnect lets you implement a client/server system in which the client piece can be as thin or as thick as you need.

Developers using AcuBench can take advantage of Micro Focus’s Thin Client technology, allowing them to work in a user-friendly Windows environment and compile to and run from a UNIX, Linux, or Windows server. The thin client implementation of AcuConnect lets you run the user interface (UI) portion of your application on a graphical display host while the rest of the application and data reside on the server.

Parent topic: Introduction


Product Support

If you have a question about AcuBench, or if you encounter unexpected behavior during its use, extend’s Product Support specialists are ready to assist you. Before contacting Product Support, be prepared to provide the following information:

  • the version of the Windows operating environment that you are using
    Restriction: AcuBench no longer supports Windows XP or Windows Server 2003 (or any Windows platforms that pre-date these). This is because AcuBench utilizes a number of third-party libraries that have ceased to be supported on those platforms.
  • the version of AcuBench that you are using
  • the version of the ACUCOBOL-GT compiler and runtime that you are using

You can display the AcuBench and ACUCOBOL-GT version information in AcuBench. From the Help menu select About AcuBench. In the information box, click the Runtime version and Compiler version buttons to display runtime and compiler version information.

You can reach extend Product Support in the United States Monday through Friday from 6:00 a.m. to 5:00 p.m. Pacific time, excluding holidays. You can also raise and manage product issues online and follow the progress of the issue or post additional information directly through the website.

Parent topic: Introduction


Getting Started

  • Introduction
  • About AcuBench Documentation
  • Related Documents
  • Notation
  • Sample Programs
  • System Requirements
  • Installing and Uninstalling AcuBench
  • Navigating the User Interface
  • Printing in the Workbench
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

The following sections include several topics that can help you get started using AcuBench. A general description of the contents of the AcuBench User’s Guide and some related documentation is provided, along with tips on the notation used in these documents. System requirements and installation procedures are defined, and the locations of some helpful sample programs are also given.

Parent topic: Getting Started


About AcuBench Documentation

All AcuBench functions and capabilities and directions for their use are documented in this AcuBench User’s Guide. The topics in this guide are organized into the following general areas:

Introducing AcuBench Documentation sections include:
  • Introduction
  • Getting Started
  • Workbench Concepts
  • Customize Your Working Environment
  • Version Control
Working with Projects Documentation sections include:
  • Working with Projects
  • Project Settings
Working with Data Files | Includes Working with Data at the Project Level
Working with Programs | Includes Working with Programs
Program File Handling | Includes Working with Data at the Program Level
Editing Source Code Documentation sections include:
  • Configuring the Code Editor
  • Working with Source Code
Working with Screens Documentation sections include:
  • Configuring the Screen Designer
  • Working with Screens
  • Controls, Menus, and Toolbars
Working with Reports Documentation sections include:
  • Configuring the Report Composer
  • Working with Reports
  • The Report Controls and Property Reference
Helpful Tools Documentation sections include:
  • Working with ACUCOBOL-GT Utilities
  • The AcuBench Integrated Debugger
  • Looking for Something?: Search and Replace
Reference Documentation sections include:
  • Toolbar Reference
  • Keyboard Reference Shortcut
Bringing Existing Code into AcuBench | Appendix A

Accessing on-line documentation

You can access the online version of the AcuBench User’s Guide by selecting Help > extend Documentation Set from the drop-down menu. This also provides access to the other individual manuals of the extend documentation set, including the ACUCOBOL-GT four-book manual set.

AcuBench also provides extended support for context-sensitive help. Click or highlight the text, control, property, or other item about which you wish to learn more, then press F1 in any part of the IDE. AcuBench opens the most appropriate page of the associated reference or user’s guide that it can locate.

For example, if you are designing a screen and click a push button control, then press F1, the ACUCOBOL-GT documentation opens in your default Web browser, showing the page from the ACUCOBOL-GT User Interface Programming manual that contains information about the attributes and properties of push button controls.

This context-sensitive help provides especially detailed information in the following interfaces:

  • Code Editor
  • Event Editor
  • Screen Designer Property Window
  • Project > Settings dialog

Any time that a manual is open in your Web browser, you can use the full-text search facility to navigate to the information you need. If you have reached the manual through the context-sensitive help facility, you can bring up the table of contents by clicking the Show In Contents button at the top, right-hand corner of the documentation frame.

Parent topic: Getting Started


Related Documents

ACUCOBOL-GT and COBOL are documented in four manuals that together are called the ACUCOBOL-GT documentation set. The four-volume set is shipped on the Acucorp product CD-ROM. The books in this set include:

  • Book 1, ACUCOBOL-GT User's Guide

    The ACUCOBOL-GT User's Guide describes how to compile and run programs with ACUCOBOL-GT. Some chapters offer programming suggestions for both new and experienced programmers. The ACUCOBOL-GT User's Guide also describes the ACUCOBOL-GT runtime debugger and file utilities.

  • Book 2, ACUCOBOL-GT User Interface Programming

    The ACUCOBOL-GT User Interface Programming book details ACUCOBOL-GT controls and discusses user interface development issues.

  • Book 3, ACUCOBOL-GT Reference Manual

    The ACUCOBOL-GT Reference Manual describes COBOL program structure and details every verb included in the language.

  • Book 4, ACUCOBOL-GT Appendices

    The ACUCOBOL-GT Appendices include host-specific information and descriptions of all library routines and configuration variables.

If you are using the print documentation, a fifth book, the ACUCOBOL-GT Combined Indices, contains a combined index for the entire four-book documentation set.

Parent topic: Getting Started


Notation

In this AcuBench User's Guide, menu selections are frequently shown as a series of strings separated by > characters. For example, you might see:

  • To create a new file click File > New.

In the case of cascading menus, you would see:

  • To turn on debugger file tracing, click Debug > Trace Options > Trace File.

Program names that are run by typing the name at a command prompt are shown as vutil.

When citing a label or option that appears in a dialog box, the text appears as: Name of object file (o) is an option on the Project > Settings > Compiler dialog box.

Parent topic: Getting Started


Sample Programs

The AcuBench product materials include two sample workspaces called samples and reports.

The samples workspace contains sample programs, COPY files, screens, resource files, and other program elements intended to demonstrate many of AcuBench's and the compiler's capabilities. The reports workspace contains a number of graphical and text-only reports created using the AcuBench Report Composer.

The sample workspaces are located in %PUBLIC%\Documents\Micro Focus\extend x.x.x\sample\acubench. We recommend that you familiarize yourself with the sample projects, programs, source code, and related files.

Other helpful sample programs are available for download in the Support area of the Micro Focus Web site. Open your Web browser and navigate to www.microfocus.com, and then select Support > Examples and Utilities > ACUCOBOL-GT® Samples for a list and brief description of these programs.

Parent topic: Getting Started


System Requirements

See the System Requirements section of the extend Release Notes for detailed system requirements information.

For detailed information on supported operating systems, see the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx

Parent topic: Getting Started


Installing and Uninstalling AcuBench

Before you install AcuBench, be sure that the host machine meets the minimum requirements specified in the previous section. Note that AcuBench Version 8.x requires the Micro Focus Version 8.x compiler and runtime.

AcuBench is delivered on CD-ROM. In addition to the CD-ROM, you must have two license codes (the product code and product key) to successfully install the product. You should find the license codes in your product materials. If they are not included, contact your Micro Focus extend Sales Professional.

The setup program starts automatically when you insert the CD-ROM into your drive. If the setup program does not start, go to the Windows Start menu, select Run, and enter the device name of your CD-ROM followed by setup.exe. For example:

D:\setup.exe

Follow the instructions on the screen and enter the license codes when prompted.

CAUTION:
To avoid the unintentional overwriting and loss of existing AcuBench projects, files, and executables, install this version into a new folder.

AcuBench can be installed on systems that also have an earlier version of the workbench installed. You do not need to move or uninstall the earlier version in order to use that version and the new version. Note that the new version does not automatically find and use the .ini file options used by the earlier version. If you want the current version of AcuBench to use the options specified in a .ini file from a previous version, use the Tools > OptionsLoad command to load the previous version’s .ini file into the current version’s Application Data folder.

If you reinstall the same version of AcuBench for any reason, note that the existing .ini file in the Application Data folder is not overwritten at installation. For example, if you want to revert to the installation defaults in the AcuBench.ini file, you would need to delete the existing .ini file before reinstalling AcuBench.

To uninstall AcuBench, use the Add/Remove Program applet in the Windows Control Panel.

Parent topic: Getting Started


Navigating the User Interface

Access to most AcuBench functions is provided directly in the main application window. The size and layout of most screen elements is customizable. User interface elements, such as toolbars and sub-windows, can be moved, docked, undocked, made visible, or hidden at your discretion. Position and visibility attributes are retained from session to session so that the main application window has the same configuration and appearance as when you ended your last session.

The title bar displays the name of the application (AcuBench), followed by the name of the workspace, the name of the current file, and the name of the current project. It also indicates whether your current project is using thin client functions.

The drop-down menus on the menu bar provide access to all workbench functions, configuration options, and online documentation. Access to Micro Focus utilities, such as AXDEFGEN, cblutil, and vutil, is available on the Tools pull-down menu.

The AcuBench toolbars provide push button access to the most frequently used workbench functions. You can display or hide each toolbar via the View drop-down menu, or by right-clicking a toolbar. You determine which toolbars display and which buttons appear on each toolbar using the Tools > Customize dialog box, discussed in The Customize Dialog. This interface also allows you to create new, custom toolbars.

By default, each of these features appears at the top of the AcuBench interface when you open the application. The result is an interface that looks much like the following:

  • The Toolbars
  • The Workspace Window
  • The Development Window
  • The Screen and Report Component Toolboxes
  • The Output Window
  • The Status Bar
Parent topic: Getting Started


The Toolbars

By default, AcuBench displays the Standard, Project, Editor, and Align toolbars at startup. When you use the AcuBench integrated debugger, the toolbar is displayed, as well.

You can display, hide, resize, and move the toolbars. Toolbars that are not dockedunder the menu bar or to the edge of the window are called floating toolbars.

When you place the mouse pointer over a toolbar button for more than a second, a tool tip is displayed, showing the button's descriptive title. At the same time, a short description of the button's function is also displayed in the status bar.

Manipulating toolbars

You can manipulate the AcuBench toolbars to suit your needs.

To move a toolbar to a new position:

  1. Place the mouse pointer within the toolbar, but not over a button.
  2. Click and drag the toolbar to the desired location.

To display or hide a toolbar, you can do any of the following:

  • Click the toolbar’s name in the View > Toolbars menu. If a toolbar is visible, a marked check box appears next to its name in the menu listing.
  • Right-click any toolbar, then select the name of the toolbar that you want to hide or display.
  • Open the Tools > Customize interface and click the toolbar’s name. If a toolbar is visible, a marked check box appears next to its name on the Toolbars tab.

To reshape a toolbar:

  1. Position the pointer on the edge of the floating toolbar so that the pointer changes to a double-headed arrow.
  2. Down click and drag to alter the shape.
Parent topic: Navigating the User Interface


The Workspace Window

The Workspace window provides three different views of project components: the Structure view, the File view, and the Data view. Each of these views is represented by a tab at the bottom of the window; click a tab to switch from view to view.

These three views make up the primary interface for working with project elements in AcuBench, as follows:

  • The Structure view shows AcuBench program structure files, with interfaces to the graphical designers used to generate program code. Program structure files and the Structure view are discussed in Working with Programs.
  • The File view shows all physical files associated with an AcuBench project. Interacting with files and folders in the File view is discussed in Adding Folders to a Project through Moving Components Among Projects and Folders.
  • The Data view lists AcuBench data layout files, used to generate FD and SELECT statements and define file handling code at the project level. Data layout files and the Data view are discussed in Working with Data at the Project Level.
Parent topic: Navigating the User Interface


The Development Window

All open project files, screens, and active editors (such as the Event Editor or File Designer) are displayed in the Development window. When you have more than one file or editor open in the Development window, each one is assigned to a tab, displayed at the top or bottom of the window.

To shift the focus from one file or editor to another in the Development window, click the appropriate tab (highlighted above). You can also use the Ctrl+F6 keyboard shortcut to scroll through open editors, or use the Window drop-down menu.

Parent topic: Navigating the User Interface


The Screen and Report Component Toolboxes

The AcuBench interface includes two toolboxes, one for the Screen Designer and one for the Report Composer. The Screen Component Toolbox contains the palette of Micro Focus screen controls. If you have defined ActiveX controls for use with your project, these also appear in the toolbox. The Screen Component Toolbox is discussed in detail in Drawing Controls with the Component Toolbox.

The Report Component Toolbox contains the controls, or elements, that you can use to design different sections of a report. Some report controls are similar to screen controls. The Report Component Toolbox is covered in Adding Report Controls.

Parent topic: Navigating the User Interface


The Output Window

All workbench standard output is displayed in the Output window, which has five tabbed panes: Build, Debug, Find in Files, Launch Tools, and Version Control. Each pane captures the output messages related to its label. For example, the Build pane displays messages generated by parsing, building, and compiling. The Debug pane captures output generated from the debugger (but not program output).

To print the contents of the current tab of the Output window, right-click inside the pane and select Print.

Parent topic: Navigating the User Interface


The Status Bar

The status bar displays various information pertaining to the current state and activities of the workbench.

Parent topic: Navigating the User Interface


Printing in the Workbench

In addition to source code files and other text documents, AcuBench's print function allows you to print hard copies of screen forms, report forms, and the contents of the Output window. Select File > Print or click the Print icon on the Standard toolbar. This opens a standard Windows print dialog that allows you to select a printer, specify a page range, and so on.

Use the AcuBench File > Print Setup command to change printers, select an output tray, change paper orientation, and so on. Like the Print dialog, the Print Setup dialog is a standard Windows interface.

When you print a text file, rather than a screen or report form, you can use the File > Page Setup command to customize the appearance of the printed page, including the header and footer, if any. This command opens a Page Setup dialog box that also allows you to specify a page style, margin sizes, and other options.

The Header and Footer fields of the of the Page Setup dialog box can take a text string or any of the special options described in the following table. You can either manually enter the code for any of the special options, or click the arrow button to the right of the field and select an option from the pop-up list.

Option | Description
Full Path Filename &U | Prints the full path and file name in the header or footer
Filename &F | Prints the file name in the header or footer
Page Number &P | Prints the page number in the header or footer
Current Time &T | Prints the time the document was printed in the header or footer
Current Date &D | Prints the date the document was printed in the header or footer
Left Align &L | Prints the header in a left alignment or footer
Center &C | Prints the header in a center alignment or footer
Right Align &R | Prints the header in a right alignment or footer

You can also set the following additional options to determine the appearance of your print output:

Option | Description
Style | Select any of the following styles from the drop-down list: Black and White prints your document in black and white. Color prints your document in color. Zebra prints your document using alternating gray and white stripes.
Print line number | Check this check box if you want the line numbers of your file to print on your document.
Frame | Click None if you do not want to print a frame around your document, or Inner to print a simple, single-line box around each page of text.
Margins | Allows you to specify margin settings for your printed document. Set the left, right, top, and bottom margins in measurements of inches.
Parent topic: Getting Started


Workbench Concepts

  • AcuBench Concepts
  • Project Management, Organization, and Structure
  • Automatic Code Generation
  • AcuBench File Types
  • Development Approaches
  • Using Thin Client Technology with AcuConnect
Parent topic: AcuBench Version 10.2.0 User's Guide


AcuBench Concepts

Several fundamental concepts shape AcuBench’s organization, structure, and approach. These ideas include:

  • an organizational model that groups programs within projects and projects within workspaces

  • an emphasis on automated code generation

These concepts, as well as a discussion of development approaches, are described in the topics that follow.

Parent topic: Workbench Concepts


Project Management, Organization, and Structure

In AcuBench, application development is organized into three levels of structure: workspace, project, and program.

The central unit is the project. An AcuBench project includes all of the files and resources needed to build, test, and deploy an application. Every project has its own compile, runtime, and environment settings (in fact, projects can have many sets of settings, called modes). Every project is autonomous, although it can coexist and share resources with other projects.

To provide greater development flexibility, projects inhabit a larger working environment called the workspace. The workspace hosts one or more projects and provides a common work area that supports the concurrent development of multiple projects. The workspace layer also makes it possible to standardize AcuBench default settings (for code generation, graphical user interface and report design, and general environment behavior, among other options) across projects.

A Workspace window displays components of each project in the workspace, providing easy and organized access to project components, options, and settings. Through this window, you can instantly switch between projects and quickly copy components from one project to another. Each project's state information is preserved and each project's unique settings (compiler, runtime, and environment options) are maintained. Projects can, but do not have to, share files. Projects are not formally related in any way, other than belonging to the same workspace.

Every project has at least one program and can have many programs. A program may be a single COBOL source file, a source file and its COPY files and resources, or a source file augmented by a program structure file. When you work in AcuBench, the program structure file is what makes it possible to use the many graphical design tools and editors (excluding the Code Editor) designed to streamline code development. Only programs that include a program structure file appear in the Workspace window's Structure tab.

We recommend that all AcuBench users read Development Approaches. If you intend to use AcuBench's design tools and code generation facilities, it is also important that you read Automatic Code Generation.

The workspace, project, and program concepts are discussed in more detail in the sections that follow.

  • The Workspace
  • Projects
  • Programs
Parent topic: Workbench Concepts


The Workspace

In AcuBench, each project and all of its associated files and resources belong to a workspace. Put another way, a workspace is a container for projects. The workspace is used to keep track of member projects and their files, options, and settings. It is also an interface that organizes, displays, and allows for interaction with project elements. The workspace is implemented in the form of a workspace file and a Workspace window.

The workspace file is created and maintained by AcuBench. In it is a list of member projects, project files, and project compile, runtime, and environment settings. Workspace files have the suffix .pjt. You should never directly edit a workspace file.

The Workspace window is a sub-window of the AcuBench main application window. It presents each project's components in several views. You can interact with the project elements displayed in the Workspace window in many ways. Each node in the window has a context-sensitive right-click pop-up menu that offers a selection of actions appropriate for the associated object.

The Workspace window has three tabs at the bottom that allow you to select from among three workspace views. Each view uses a Windows Explorer-style tree view to display its contents.

Only COBOL programs that have a program structure file appear in the workspace Structure view. The Structure view displays access points to program areas that have a corresponding workbench development tool, such as screens (Screen Designer), reports (Report Composer), Working-Storage (Working Storage Editor), Linkage section (Linkage Section Editor), Event paragraphs (Event Editor), and data sets (Data Set Designer).

If you are importing an existing program, you do not have to create a program structure file. However, if you do not, your program is not displayed in the Structure view, and you cannot use the workbench tools that generate code.

The workspace File view displays each project's member files. Project files are grouped into related types, such as Source, Screen, Report, Copy, Object, Remote Object, List, Resource, and FD files. Files can be opened or executed by double-clicking their name or icon. You can also define additional file groupings. For information on how to do this, see Adding Folders to a Project.

The workspace Data view shows each project's file descriptors (also called data layouts). File descriptors are created with the workbench File Designer. For information about the File Designer, see Working with Data at the Project Level.

The workspace concept and Workspace window simplify many aspects of working with project components. By double-clicking nodes in the various views, or by selecting options from the right-click pop-up menus, you can initiate most common workbench activities.

A workspace information file (.wif) is used to record workspace configuration and state information. The workspace information file is a binary file that is maintained by AcuBench in the same directory as the workspace project file (.pjt).

Parent topic: Project Management, Organization, and Structure


Projects

A project is the fundamental component that you create when you start to develop a program under AcuBench. Once created, you populate the project with all of the files and resources needed to build, debug, and deploy one or more programs.

You can create multiple projects in the same workspace. When a workspace is open, all of its member projects are displayed in the Workspace window.

You can have multiple programs in the same project. However, compiler, runtime, and environment settings are generally made at the project level. While it is possible to set compiler settings for each individual program in a project, two programs that have different runtime or environment settings should probably be placed in separate projects.

You can use the File > Save Project function to export information about an existing project into a project file (.pjf). This file retains all project-related information that is stored in a workspace file and replaces all relative path names with full path names. A project saved as a .pjf can be physically separated from the workspace where it resides, facilitating the sharing of projects among development team members. Note, however, that once a .pjf is created, it is static. In other words, you have to manually select the Save Project option to update the contents of a .pjf file.

If you are going to transfer projects between workspaces, you can use the Tools > Options > Environment > General interface to set an option that directs the workbench to automatically copy project files to a new project directory when you add a project to a workspace. This option is also available in the Open Project dialog.

Parent topic: Project Management, Organization, and Structure


Programs

Because of the sophisticated code generation capabilities of AcuBench, the definition of what constitutes a program has grown. Without AcuBench, a program is, at its simplest, a COBOL source file and its COPY files (if any). In AcuBench, a program can still be just a COBOL source file and its COPY files, but it can also be something more.

If you plan to use any of AcuBench's automated code generation facilities, your program must have a program structure file. Programs created in AcuBench using the File > New > Program command are automatically give a program structure file. For information about using AcuBench's code generation with source code created outside the workbench, see Bringing Existing Code Into AcuBench.

All of the development work that is done with workbench tools that generate code, such as the Screen Designer or File Designer, is stored in the program structure file. When you generate code for the program, based on the information in the program structure file, several COPY files are created and some code may be generated directly into the program file (you have control over what files are created and what code is generated). It is important to understand that vital program information is stored in the program structure file (in a non-COBOL representation), and that a program that uses automated code generation facilities cannot be constituted without it. In a very real sense, the program structure file is as much a part of the program as the COBOL program source file (.cbl).

For a discussion of program development approaches, see Development Approaches.

Parent topic: Project Management, Organization, and Structure


Automatic Code Generation

The Workspace Structure view provides a visual interface to most of AcuBench's automatic code generation facilities. Each icon in the program tree that appears in the Structure view – Screen, Report, Working Storage, Linkage Section, Event Paragraph, Data Set – can be used to open a graphical designer, which stores its code in a program structure file. When you select a program in the Structure view and select the Generate command, AcuBench opens the program structure file and uses that file to create screen, report, Working-Storage, Linkage, event, and file-handling COBOL code.

The COBOL code that AcuBench generates from the program structure file is, by default, placed into a .cbl source file and several COPY files. Tags in the source file tell AcuBench where to place generated code. The area outside of these tags is reserved for manual editing. This means that, by default, all code between the AcuBench tags is deleted and recreated every time you generate code, but code that you have added outside of the tags is preserved. The various AcuBench tags and their purposes are discussed in Program Tag Options.

Changes made to a single AcuBench designer may cause code to be generated in several COPY files. When you use the Screen Designer to add a status bar control to a graphical screen, for example, AcuBench's default code generation produces a combination of Screen Section, Working-Storage, and Procedure Division code in .scr, .wks, and .prd COPY files. Ways to customize code generation behavior and affect the naming and use of COPY files are discussed in Controlling Code Generation and Generate Document Options.

The program structure file also makes it possible for AcuBench to handle sometimes subtle interactions between the different graphical designers. When you create an entry field control in the Screen Designer, for example, AcuBench creates a Working-Storage variable to hold the contents of that field. The variable appears in the Screen Designer Property sheet for the control and in the Working-Storage Designer's graphical interface. When code is generated, Screen Section code associates the variable with the control's VALUE property and the variable definition appears in the Working-Storage Section.

If you want AcuBench to generate file-handling code, you need to create one or more data layout files, in addition to the program structure file. A data layout file is an AcuBench-specific file from which file descriptions, SELECT statements, custom extended file descriptors, and sort descriptions are created. For each data file that you plan to use with a project, you create one data layout file. Data layout files are discussed in more detail in Defining Data Files for Use in Projects and Programs.

Once you have created a data layout file at the project level, you can define data sets for each program in the project. A data set is a program-level definition specifying how an individual program will use a given data file. Based on your specifications, AcuBench uses the data set definition to determine what kind of file-handling code (OPEN, READ, and WRITE paragraphs, for example) to generate in the Procedure Division. Data sets are discussed in more detail in Using the Data Set Designer.

  • Generated COPY Files
  • Controlling Code Generation
Parent topic: Workbench Concepts


Generated COPY Files

Depending on the workbench tools used to develop the program, AcuBench may generate the following files:

  1. program.scr (screen COPY file), containing:
    • Screen section description entries
    • If needed, CHARACTER or GRAPHICAL syntax to distinguish between graphical and character-based screens with the same name
    • Syntax to support event procedures, exception procedures, and/or embedded (before/after) procedures, when defined.
  2. program.mnu (menu COPY file), containing menu bar descriptions and calls to W$MENU.
  3. program.evt (event and embedded procedure COPY file). This file contains code that you add in the Event Editor and code that AcuBench generates for event and exception handling. The portion of the code that is created by AcuBench does not appear in the Event Editor and is not intended for modification.
  4. program.prd (Procedure Division COPY file), containing:
    • Program initialization and exit routines
    • If one or more screens has been created in the Screen Designer, screen-handling routines
    • If a screen uses exception or termination values, an exception-processing routine.
  5. program.wrk (Working-Storage COPY file), containing:
    • Variables defined for control properties
    • Variables defined in the Working Storage Editor
    • When a data set is defined for the program, the file status data item
  6. program.lks (Linkage Section COPY file), containing variables defined in the Linkage Editor
  7. program.cbl, a source code file in which most code is generated between tag sets. This source file includes:
    • Attributes and comments from the Program Properties dialog
    • COPY statements for generated files
Parent topic: Automatic Code Generation


Controlling Code Generation

To refine your control over automated code generation, you can:

  1. Set code generation options in the Tools > Options > Code Generator dialog.
  2. Add or remove tag pairs from the program. The workbench cannot insert code into areas that are not tagged. If you remove a tag pair, AcuBench does not insert code in that area. Code generation is restored to an area if the tags are reinserted.

    You can control whether specific tag pairs are automatically generated or suppressed via the Tools > Options > Code Generator > Program Tag interface. For more information about this dialog, see Program Tag Options.

For information on the following facilities, see:

File Designer | Chapter 8
Data Set Designer, Working-Storage Editor, Linkage Editor | Chapter 10
Screen Designer | Chapters 13 and 14
Event Editor | Chapter 14

Note that to use these facilities, your program must have a program structure file. If you want AcuBench to generate COPY statements into the program file, you must update your program to include AcuBench tags.

Parent topic: Automatic Code Generation


AcuBench File Types

A number of different file types are created and used by AcuBench . Some of these files are COBOL COPY files, produced by AcuBench's code generation facility, as discussed in the previous section. Others, however, are non-COBOL files used to define AcuBench workspaces and projects, store workspace state information, determine basic workspace settings, define template information, transfer compiler and runtime settings between projects, generate programs and data handling code, and so on.

Especially when you are using a version (source) control system, as discussed in Version Control, it can be vital to know what each file contains and how it is used by AcuBench. Because this information is particularly useful in a version control context, the reference includes two tables: one listing files generally tracked by version control, and one listing files that do not need to be tracked (either because the information they contain is relevant only to a single user, or because the files are completely recreated on generation from another file). Note that projects developed in the workbench may contain additional file types that are not AcuBench-specific (such as MIcro Focus .def or .acu files, user-defined COPY files, and resource files).

Commonly tracked files are:

Extension | Description
.pjt | The workspace project file includes information about the projects within a workspace and the location of programs within each project.
.pjf | The individual project file contains the location of all programs within a single project. By default, project information is stored in and read from the workspace project file (.pjt).
.psf | The program structure file contains the information AcuBench needs to generate a program.
.cbl | Default extension for COBOL source code. Note that source generated by AcuBench is recreated from the .psf file when you generate.
.dlt | Data layout files contain the definitions that AcuBench uses to create FD, SL, and SD COPY files, as well as user-defined file handling code.
.ini | AcuBench .ini files contain information about default program and control properties and code templates, as well as information about the overall appearance of the workspace and its editors.
.pof | Project option files contain project settings, including compiler and run-time flags, AcuBench environment settings, and library options.
.stf | Screen template files can be used to create a consistent look and feel for a user interface.
.prf | Program option files store the default properties assigned to new AcuBench programs, including key status values and code generation options (shown in the Program Properties interface).
.wtf | Report template files can be used to create a consistent look and feel for reports across an application or set of programs.

Files that are not usually tracked:

Extension | Description
.wif | The workspace information file contains the current state of the AcuBench workspace, including such things as which windows are open and which breakpoints are set.
.evt | Event paragraph COPY file, generated from the .psf file and accessed through the Event Editor.
.lks | Linkage section COPY file, generated from the .psf file and accessed through the Linkage Editor.
.mnu | Menu COPY file, generated from the .psf file and accessed through the Menu Designer dialog box in the Screen Designer.
.prd | Procedure Division COPY file, generated from the .psf file. The code that is generated into this file comes from a number of the AcuBench editors and designers, including the Screen Designer and File Designer.
.rpt | Report COPY file, generated from the .psf file and accessed through the Report Composer
.scr | Screen Section COPY file, generated from the .psf file and accessed through the Screen Designer.
.wrk | Working-Storage COPY file, generated from the .psf file and accessed through the Working-Storage Designer.
.fd | File description COPY file, generated from the .dlt file and accessed through the File Designer.
.sl | SELECT statement COPY file, generated from the .dlt file and accessed through the File Designer.
.sd | Sort COPY file, generated from the .dlt and accessed through the File Designer.
Parent topic: Workbench Concepts


Development Approaches

AcuBench supports a wide variety of approaches to developing and maintaining COBOL applications. The approach that you use is determined by the set of workbench tools you employ, the needs of your application, and your approach to software development. If you plan to use workbench tools that automatically generate code, such as the Screen Designer and File Designer, some elements of your program's content and structure are determined by the methods used by those tools. For a description of the workbench's approach to automated code generation, see Automatic Code Generation.

The following sections discuss general development approaches. Included in each discussion are specific instructions on how to establish a workbench project that best supports that development approach.

The first section focuses on applications that are new or migrating to AcuBench, and that intend to make use of the workbench's automated code generation tools.

The second section focuses on the traditional development approach, which foregoes the use of any of the workbench's automated code generation facilities (no use of the Screen Designer, File Designer, Data Set Designer, Working Storage Editor, Linkage Editor, or Event Editor). The developer must write every line of application code. This approach does not restrict the use of non-code generating workbench facilities in any way.

The third section provides additional tips for developers working with large applications, made up of a great many programs and COPY files. It focuses on maximizing performance while taking advantage of AcuBench's code generation tools.

  • General Considerations
  • Developing New Applications
  • Developing Programs That Do Not Use Code Generating Tools
  • Working with Large Applications
Parent topic: Workbench Concepts


General Considerations

Regardless of the approach you use, there are several details of project setup that you should attend to every time you create a new project. Each item below is discussed in detail in the sections that follow.

  • You should check and adjust, if desired, the project prefix settings.
  • If you change the default name of a project subdirectory, you may need to check and adjust certain project settings.
  • Consider placing your project files directly in the project directories.
  • You may want to customize the default keyboard shortcut settings.
  • You should review all compile, runtime, and environment settings and, if possible, test your project setup by compiling and running the application before you begin making significant changes to your application code.
  • Project Prefix Settings
  • Project Directories
  • Placing Files in the Project Directory
  • Keyboard Shortcut Settings
  • Setting Options and Testing
Parent topic: Development Approaches


Project Prefix Settings

Before you create a new project, open the Options dialog box (select Tools > Options) and examine the default prefix values in Environment > Prefix. The prefix values are the various strings used to determine the base name for new files created by the workbench. For example, the default program prefix is Program. When you create a new AcuBench program, the workbench takes that prefix and appends a number to create a unique program name. As a result, if you accept all of the default names suggested by AcuBench, your first program is called Program1, the second is called Program2, and so on. Note that we do recommend renaming your programs as you create them to assign more descriptive names.

The prefix values are workbench-level settings (as opposed to workspace- or project-level settings) and are applied to all new projects and files.

Parent topic: General Considerations


Project Directories

When you create a project, you can change the name of any project subdirectory. You can choose to omit a subdirectory altogether (by making that entry field blank). To modify or eliminate a subdirectory for an individual project during project creation, click the More Info button on the File > New > Project dialog box.

You can also change the base directory structure used for all new AcuBench projects in the Tools > Options interface under Environment > Prefix. Changes to the Working directories area affect the names of the directories used to hold the different sorts of files associated with a project by default. For more information, see Prefix Options.

Note that renaming or eliminating a subdirectory does not change the name of the corresponding folder in the Workspace window. However, the logical link between the Workspace folder and the corresponding directory is updated so that the correct related files are displayed.

If you change a name or eliminate a directory, you may need to adjust some of your project settings.

  • If you change the name of the object directory, or eliminate it, you may need to change the argument for Name of object file (o) in the Standard Options catalog of the Compiler tab.

    In most instances, this should be set to: %objectdir%\@.acu.

  • If you change the name of the list directory, or eliminate it, you may need to change the argument for Name of list file (Lo) in the Listing Options catalog of the Compiler tab.

    In most instances, this should be set to: %listdir%\@.lst.

Note: For more information about %objectdir%, %listdir%, and similar macros, see Prefix Options.
Parent topic: General Considerations


Placing Files in the Project Directory

When you use the Add/Remove Files function to add files to your project, you can specify files that are located on your hard drive or on any network drive that your Windows operating system recognizes. AcuBench creates a logical link to the file so that it can be accessed through the File view of the Workspace window while remaining in its original location on disk. To facilitate use of a source control system, or to make it easier to move a project from machine to machine, you may instead want to copy or move files into your AcuBench project directory structure before adding them to the project.

Parent topic: General Considerations


Keyboard Shortcut Settings

The workbench offers a great deal of flexibility in the definition of keystroke shortcuts. You can even define the same keystroke combination to perform different tasks depending on whether you're working in the Screen Designer or the Code Editor. Keystroke shortcut definitions are defined for AcuBench as a whole, rather than for individual workspaces. It is possible, however, to create multiple settings files (specifically, .ini files) and then load the appropriate file according to the task you wish to perform or the workspace or project with which you plan to work (for more information, see The Tools > Options Dialog in Customize Your Working Environment). For step-by-step instructions on how to change keystroke definitions, see Keyboard Options in the same chapter. For a complete list of workbench commands and default keystroke shortcut definitions, see Keyboard Shortcut Reference.

Parent topic: General Considerations


Setting Options and Testing

Soon after the new project is created, it is a good idea to open the Project Settings dialog box to review the settings of all compiler and runtime options. You should also review the definitions of the environment variables.

After you have populated the project with the application files, and after you have reviewed the compiler and runtime switches, but before you start making changes to your program, it is a good idea to attempt to compile and run the application or a sub-component of the application.

CAUTION:
If you are going to use workbench tools that automatically generate code, there are some circumstances in which you should be careful to protect existing files from being overwritten. Read the following information carefully to understand the risks.

When the workbench generates code, except when working with the .cbl file (discussed below), it completely rewrites the target file. All files that the workbench creates are given names based on the program name, as discussed in Generated COPY Files. If you have a file in your project with the same name as one that might by generated by the workbench, you should rename the file.

You can determine which files are generated by changing the settings in the Tools > Options > Code Generator > Generate Documents interface.

The .cbl file is a special case. Whenever you have a program with a program structure file, AcuBench tags are added to the .cbl file for code generation purposes. By default, in the Tools > Options > Code Generator interface, under Generate Documents, the first and second check boxes on the page are marked. Marking the first check box, Program file, determines that AcuBench will use the tags in the .cbl source file to generate code into the source code document. If you de-select this option, the currently existing .cbl file is not changed in any way going forward. The second check box, Regenerate tagged area only, indicates that only the tagged areas of the .cbl file are changed. Any code that you have manually added to the .cbl source file is preserved during code generation as long as this box is marked.

If you choose to generate the program file but do not choose the Regenerate tagged area only option, your .cbl file will be completely overwritten when you generate code. It is therefore very important that you pay careful attention to your Generate Document settings.

Parent topic: General Considerations


Developing New Applications

If you are developing a new application and intend to use AcuBench tools that generate code, such as the Screen Designer or File Designer, there are several issues that you should consider before you create your project. Of tantamount importance is that you read and become thoroughly acquainted with Automatic Code Generation. This section provides essential information about the AcuBench code generation model, and it outlines the associated program organization and structure.

When creating a new project:

  1. Use the Tools > Options interface to set up code generation behavior, establish guidelines for building new project directory structures, and create the .ini file that will be used to standardize the development environment for the members of your development team. See The Tools > Options Dialog for more information about the Tools > Options interface. For information about the importance of the .ini file, see Version Control.
  2. Use File > New > Project to create, name, and assign directories for a new project. Detailed, step-by-step instructions for creating a new project in either a brand new workspace or an existing workspace can be found in Creating a Project.
  3. Establish the runtime, compiler, and environment settings that will be used by programs in this project. Multiple sets of settings, called modes, can be created for each project. In addition, modes created in one project can be imported by other projects. For more information, see Project Settings.
  4. Determine which data files will be used by programs in the project and create data layout files to define those data files for use with AcuBench code generation. When you create data layout files, AcuBench code insight features, as well as the Drag-and-Drop interface for quick screen and report design, among other features, are made significantly more useful. The process of creating data layout files is discussed in Defining Data Files for Use in Projects and Programs.
  5. Create new programs for your project with File > New > Program. This command creates a program structure file. When you generate the program for the first time, a .cbl source file is created.

    You can also add existing program structure files, COBOL source files, COPY files, resources, and so on to your project. All of these options are discussed in Working with Projects and Working with Programs.

Parent topic: Development Approaches


Developing Programs That Do Not Use Code Generating Tools

This is the approach that is most like traditional COBOL program development, except that you're working in a sophisticated integrated development environment. This approach foregoes the use of the Screen Designer and other AcuBench tools that generate code. Therefore, these projects do not need or make use of program structure files, nor do they make use of the Structure view of the Workspace window (project files are accessed in the File view). You, and other members of the development team, are responsible for writing all COBOL code. This approach in no way restricts your use of the Micro Focus COBOL language, or the non-code generating workbench tools, such as the Code Editor's code completion facilities (see Using Code Insight Functions ) or the Configuration File Editor, to name only two.

There is nothing unusual about creating a project for the traditional development approach. For step-by-step instructions, see Creating a Project. There are, however, a couple of important details to remember.

  1. When you create the project, use the Blank project template. The Blank template does not create a program structure file (which you do not need).
  2. When you use the Add/Remove Files interface to select the COBOL source files that you will be adding to your project, make sure that you have not marked the option to create a program structure file for each program. In other words, look at the Files in project frame and verify that the check box in the Create .PSF column for each program that you intend to add to your project is not marked.

    If you don’t intend to create a program structure file for any of your existing programs, you can disable the Create PSF option at the workspace level. In the Tools > Options > Environment > Miscellaneous interface, locate the Automatically create a program structure file area and deselect the When adding a source file check box. When you do this, all Create PSF check boxes in the Add/Remove Files dialog are unmarked by default.

Parent topic: Development Approaches


Working with Large Applications

Although there is no hard limit on the number of programs that can reside within an AcuBench workspace, when you are developing a large application, it is generally more efficient to use multiple small workspaces.

In AcuBench terms, a large application is defined by the combination of:

  • The number of lines of generated code
  • The number of controls on screens and in reports
  • The number of Working-Storage variables maintained by AcuBench
  • The number of external COPY files parsed at generation time

This means that if you are using AcuBench without code generation, you can have a great many programs without affecting the performance of the workbench. (Note that you may still want to divide your application between multiple workspaces for ease of maintenance.) But as you design graphical interfaces in AcuBench and make use of the workbench's code generation and automation features, it is increasingly important to keep your workspaces small and efficient.

Regardless of the composition of your large application, any time you have multiple developers working in AcuBench, it is important to use version (source) control software. For more information on this topic, see Version Control.

  • Factors that Affect Performance
  • Organizing Your Workspace
  • The Command-line Interface to AcuBench
Parent topic: Development Approaches


Factors that Affect Performance

When you expand a program in the Structure view of the AcuBench workspace, the program is loaded into memory. Programs are also loaded into memory at generation time (if they are not already resident in memory). This means that when you generate a workspace, every program in the workspace that has a .psf is loaded into memory. Once loaded, programs remain in memory until you exit AcuBench. This is done to speed up code generation and other automation features of the IDE.

Some of the automation features include the following:

  • Automatic generation of Working-Storage variables for screens
  • Automatic check for variable definitions within external COPY files before adding new variables to Working-Storage

When a program is loaded, AcuBench searches the program's screens and reports for properties that should be defined in Working-Storage. If AcuBench cannot find those definitions in any COPY file or FD, those properties are automatically added to Working-Storage. This feature:

  • Makes it easy to recover when a variable is accidentally deleted
  • Helps to avoid compiler errors
  • Extends AcuBench's screen and report management capabilities

The feature is also CPU-intensive and memory-intensive. As a result, the feature can be disabled using the Force variable check on load option in the Tools > Options interface. For more information, see General Environment Options. However, we recommend creating smaller projects and taking advantage of AcuBench's automation tools.

Parent topic: Working with Large Applications


Organizing Your Workspace

As you work in AcuBench, remember that workspace organization is entirely virtual, and that an AcuBench project is a virtual grouping of related programs. This means that although AcuBench creates a default directory structure for a project, only AcuBench-generated code needs to reside within that structure. Remember that:

  • Your project directory structure can be as simple as a single folder
  • Multiple projects can share a single project directory
  • Programs and COPY files can reside outside of the project folder

All of this makes it possible for you to manage your entire large application within a single version control project, while maintaining multiple AcuBench projects.

The AcuBench .ini file provides a means of standardizing screens, reports, code generation options, and other properties of the workbench environment across multiple workspaces. For more information, see The Tools > Options Dialog.

At the project level, project options files (.pof) allow you to create compiler, runtime, and environment settings once, then import them into other new or existing projects. For more information, see Project Settings.

Parent topic: Working with Large Applications


The Command-line Interface to AcuBench

To make it easier to manage multiple small projects, AcuBench has a command-line interface that allows you to generate and build workspaces from the Windows cmd shell.

The AcuBench command-line interface allows you to generate and build an entire workspace, or any program within a workspace. By default, whichever project mode is currently active for the project (as recorded in the .pjt file) is used to determine the compiler settings used for the build.

Tip: To ensure that you know which project mode you are using, you can create multiple copies of the PJT file. To do this, set a project mode (such as Release) in AcuBench, then save and close the workspace. Make a copy of the PJT file and give it a new name (Prj1-Release.pjt). Repeat the process for each of the project modes that you want to invoke from the command line. When you want to build a project in a particular mode, refer to the appropriate PJT file.

It is important to remember that only a single instance of each AcuBench version can run on a given machine. This means that you must close the IDE before using the command-line interface.

Building a Workspace

The syntax for building a workspace using the command-line interface is as follows:

[acupath]\acubench.exe /build [projectdir]\[workspace.pjt]

For example, if you have AcuBench installed in the default directory, and you would like to generate and build a workspace called Project1, use the following command:

C:\Program Files (x86)\Micro Focus\extend x.x.x\acubench\acubench.exe /build C:\project1\project1.pjt

where x.x.x is the extend version number.

From the command-line interface, the /build and /rebuild flags are interchangeable. With either parameter, AcuBench checks whether code has changed since the last build. If any part of the program has changed, the code is regenerated and compiled. This is the same behavior that you get when you execute a Build Workspace command from the AcuBench Build menu.

Generating a Workspace

The syntax for generating a workspace using the command-line interface is as follows:

[acupath]\acubench.exe /generate [projectdir]\[workspace.pjt]

For example, if you have AcuBench installed in the default directory, and you would like to generate a workspace called Project1, use the following command:

C:\Program Files (x86)\Micro Focus\extend x.x.x\acubench\acubench.exe /generate C:\project1\project1.pjt

AcuBench regenerates the code but does not build the programs. This is the same behavior that you get when you execute a Regenerate Workspace command from the AcuBench Build menu.

The Log File

All output messages generated during the build are recorded in a file called build.log, placed in the project directory for the workspace being built. If this log file does not exist, it is created. If the log file already exists, messages generated by the new build are appended to the existing log. The log file also includes the start and end times for the build.

Building a Single Program

To generate and build a single program in a project, the syntax is as follows:

[acupath]\acubench.exe /build [projectdir]wkspc.pjt prg.psf

Generating a Single Program

To generate a single program in a project, the syntax is as follows:

[acupath]\acubench.exe /generate [projectdir]wkspc.pjt prg.psf

Using a Build Script

To generate and build multiple workspaces at the same time, you can create Windows script (batch) files. In the following example, using extend 10.0.0, the script builds three programs residing in two workspaces and prints compiler success or failure messages to the screen:

@echo off
rem -------------------------------------------------------------
set bench_10="C:\Program Files (x86)\Micro Focus\extend 10.0.0\acubench\acubench"
echo *************************************************************
echo ... now building program1
%bench_10% /build C:\project1\sample1.pjt program1.psf
IF %errorlevel%==0 ECHO Success.
IF NOT %errorlevel%==0 ECHO Fail.
echo.
echo ... now building program5
%bench_10% /build C:\project1\sample1.pjt program5.psf
IF %errorlevel%==0 ECHO Success.
IF NOT %errorlevel%==0 ECHO Fail.
echo.
echo ... now building sample25
%bench_10% /build C:\demos\demos.pjt sample25.psf
IF %errorlevel%==0 ECHO Success.
IF NOT %errorlevel%==0 ECHO Fail.
echo.

Likewise, a script file could be used to build several complete workspaces and create a log file, or send a message to the system administrator when the builds are complete.

Modifying the AcuBench Skeletons

Important: We advise you to make a backup copy of AcuBench.Bin before attempting this procedure.

You can extract all of the skeletons from AcuBench.Bin by executing acubench with the /extract option:

acubench /extract AcuBench.Bin

This results in a number of .asp files (for example, AcuCbl.asp), which can be modified. After modifying them, you need to rebundle the files back into AcuBench.Bin, with the /bundle option:

acubench /bundle AcuBench.Bin
Parent topic: Working with Large Applications


Using Thin Client Technology with AcuConnect

If you want to enjoy the benefits of centralized application maintenance and the performance characteristics of a thin architecture, then you can use Micro Focus's Thin Client technology with AcuConnect®. In a thin client environment, ACUCOBOL-GT programs running on a number of UNIX/Linux, or Windows servers can present a graphical interface on a Windows display host that is running AcuBench. UNIX and Linux users can enjoy the stability and security of their multi-user environments and the graphical nature of Microsoft Windows.

For a full list of platforms that are supported with Micro Focus’s thin client technology, visit the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx.

Thin client operations allow great flexibility in your development environment. For example, assume your source code is stored on a UNIX or Linux application host and protected by a version control system. You check needed files out to a Windows display host running the workbench and edit your source using Code Editor functions. Source is compiled in the workbench and object code is directed to the remote server. Remote debugging capabilities let you test your application, which is displayed on the Windows client while it is running on the UNIX or Linux server. When you finish your work, you check your source files back in to the server.

You use the Build > Use Thin Client menu command to signal the workbench that you want to use thin client functions. Before you compile for thin client, you need to set additional project properties, project settings, and runtime options, and create an alias that contains your thin client command line. You can create object files or libraries in a remote server directory and maintain a UNIX runtime configuration file. Debug your application with the AcuBench integrated debugger or the ACUCOBOL-GT runtime debugger. The commands you now use to develop your project locally (including Compile, Build, Execute, and Debug) help you develop your project in a thin client environment. For information about setting up a remote project, see Working with Projects.

If your program is already a graphical application, you have a little conversion work to perform for thin client operations. If your application is character-based, then you have some development options:

  1. Maintain your character-based application on a UNIX or Linux host.
  2. Migrate your character-based application to graphical.
  3. Develop a new graphical user interface for your UNIX or Linux server-based application.

If you want to maintain your character-based application, you can work with it as is in the workbench with thin client. Note that some display limitations may apply when you choose to maintain your character interface. Certain functions may not appear as expected, and other unsupported functions may not display at all. You may decide to alter your code to work around any unacceptable behavior. Limitations are described in Limitations in Thin Client Environments.

If you decide to migrate your character-based program to graphical, Micro Focus's thin client solution can play an important role. Start with the ACUCOBOL-GT Character-to-GUI Wizard, which can convert your character screens to graphical whether or not your program uses a Screen section. Add other screens to your application using the Screen Designer. Include ActiveX controls in your interface as well as ACUCOBOL-GT's standard controls. For information about the Character-to-GUI Wizard, see Bringing Existing Code Into AcuBench. For more information about ACUCOBOL-GT's thin client technology, refer to the AcuConnect User's Guide.

If you choose to change the look of your interface completely, you can develop a new graphical interface for your application from scratch. The AcuBench graphical Screen Designer provides access to a wide range of graphical technology, including standard and ActiveX controls. The Screen Designer's interface and functions are described in Configuring the Screen Designer, Working with Screens, and Controls, Menus, and Toolbars.

Parent topic: Workbench Concepts


Customize Your Working Environment

  • Introduction
  • The Tools > Options Dialog
  • Setting Environment Options
  • Setting Code Editor Options
  • Setting Screen Designer Options
  • Setting Code Generator Options
  • Setting Data Designer Options
  • Setting Report Writer Options
  • The Customize Dialog
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

Many elements and attributes of the AcuBench interface can be customized to suit your preferences. Workbench windows and toolbars can be positioned directly with the mouse, or hidden and displayed via the View menu or the element’s right-click menu. Toolbars can be created or changed and links can be added to external applications (such as a calculator, for example, or a Web browser). Keyboard shortcuts used to invoke workbench commands can be added, modified, and removed. And that’s only the beginning.

Many aspects of AcuBench's basic functionality can be customized to adapt the working environment to your preferences. Code generation behaviors, default directory structures, default properties for screens, reports, and controls, and other important workbench features can be adapted to your standards to suit your needs.

Toolbar creation and editing, and the creation of links to external applications, is handled through the Tools > Customize interface. This interface is discussed in The Customize Dialog.

Other customizable aspects of AcuBench can be viewed and modified in the Tools > Options dialog box, introduced in The Tools > Options Dialog and discussed throughout the greater part of this chapter.

Parent topic: Customize Your Working Environment


The Tools > Options Dialog

The Options dialog box organizes customizable workbench options into six main categories: Environment, Code Editor, Screen Designer, Code Generator, Data Designer, and Report Writer. Each of these categories is represented as an item in a tree view along the left side of the interface. Each tree can be expanded to reveal sub-categories of information that can be customized for each major category. When you select an item in the tree, options related to that item appear on the right side of the interface.

Some options displayed here pertain to user interface customization. Others allow you to configure support for such functions as workspace build behavior, Version Control system support, and Code Insight (code completion), as well as to create template code and set screen and report defaults, and more.

It is important that you take the time to get acquainted with all of the options available in the Options dialog box.

Using the Tools > Options dialog

To change your workspace options, open the Tools menu and select Options. The tree view on the left side of the screen lists each of the major categories that you can customize. Click the plus sign to the left of a category to expand the tree and see all of the available subcategories for that option. Select an item in the tree, then make your changes to the options listed on the right side of the window, according to the information provided in this chapter.

When you are finished making changes, click OK to save your changes. More information about different ways to save and reuse your Tools > Options settings appear later in this section.

Saving option settings

Option settings are automatically saved when you click OK to close the dialog. They are saved to a file called AcuBench.ini, located in your Application Data directory. When AcuBench is launched, the settings are read and applied to the current workspace.

You can save the current settings to a specified file by clicking the Save button at the bottom of the dialog. You determine the file name and path; AcuBench automatically assigns the file an extension of .ini. Because the file contains important default settings for screens and reports, as well as code templates and build options, it can be useful to create a customized .ini file to be shared by all members of the development team.

CAUTION:
Do not remove the AcuBench.ini file that resides in the AcuBench installation directory.

Loading option settings

When you change workstations, update to a new version of AcuBench, or make changes to the AcuBench .ini file that your team uses for consistency management, you can load your customized .ini file at any time. You do not need to have a workspace open to load a new AcuBench .ini file.

To load the file:

  1. Open the Tools > Options interface and click the Load button at the bottom of the screen.
  2. Navigate to the directory containing the file, select the file, and click Open.
  3. Click OK to close the Tools > Options interface.

Some changes, like automatic save times and color settings, go into effect immediately. Others, like control property defaults, are applied to new elements added to a workspace, but are not retroactively applied to existing program elements.

Parent topic: Customize Your Working Environment


Setting Environment Options

The Environment configuration options are organized into the following subcategories:

General | Workbench startup options
Template | Options for configuring the File > New dialog box and an interface for adding file templates
Version Control | An interface for defining version control system commands
Build | Used to determine what actions AcuBench performs before parsing, building/compiling, and executing
Debug | Defines some AcuBench integrated debugger behavior
Keyboard | An interface for assigning keyboard shortcuts to workbench commands and changing existing shortcuts
Prefix | Defines the default folder names and file locations associated with new projects
Miscellaneous | Options that control how the COPYPATH variable is defined, and whether an imported source file is automatically converted to an AcuBench program
  • General Environment Options
  • Template Options
  • Version Control Options
  • Build Options
  • Debug Options
  • Keyboard Options
  • Prefix Options
  • Miscellaneous Environment Options
Parent topic: Customize Your Working Environment


General Environment Options

The options in the General category allow you to control:

  • the timing of the automatic save function
  • the Recently Used Files list
  • what the workbench loads when it is first started or opens a workspace
  • how AcuBench handles adding existing projects to new workspaces
  • whether AcuBench validates screen- and report-related variables when a program is loaded into memory
  • the default source file format
  • the translation of ASCII extended characters to Windows ANSI extended characters

Use the following procedures to set General Environment options, as needed:

  1. Select the General category of the Environment options.
  2. Automatic save option: To disable the default automatic save setting, clear the Automatic save check box. You can change the default time setting by entering a new value (from 1 to 120) in the text box. The automatic save function applies to source files (.cbl), workspace files (.pjt), program structure files (.psf), and data layout files (.dlt). The automatic save function updates disk files and saves information to the registry, allowing AcuBench to restore your project to a consistent state after an unexpected program interruption.
  3. Recently used lists: To change the size of the Recently used file list or the Recently used workspace list, enter an integer value between 1 and 8 in the corresponding entry field.
  4. On start-up options: In the On start-up section, select a radio button to specify what the workbench displays or loads when it is first started.
  5. On add project option: Normally, if you add an existing project to a new workspace (using the Open Project command), AcuBench does not move or copy the project’s files from their existing location. To change this behavior, and have AcuBench make a copy of the existing project’s files within the new workspace’s directory structure, select the Copy project files to new project directories check box.
  6. On open workspace option: This option determines how AcuBench behaves when a workspace is opened. Enable the check box to direct the workbench to reopen the documents that were open the last time the workspace was open.
  7. Force variable check on load option: If this option is selected, when AcuBench loads a program into memory, it automatically verifies that all variables associated with screen or report controls exist, whether in an AcuBench-generated COPY file or FD, or in an external COPY file. If a variable does not exist, AcuBench creates it in Working-Storage. To bypass the variable check, de-select this option.
  8. Default source format: Specify the default source format type by selecting a radio button in the Default source format group.
  9. Extended ASCII characters: Enable Translate to ANSI/OEM to cause the workbench to translate extended ASCII characters that originate in the OEM environment to Windows ANSI extended characters. Characters are retranslated back to OEM when the document is saved.
Parent topic: Setting Environment Options


Template Options

When you work in AcuBench, you are provided with a series of default templates, used as the basis for creating new programs, data layout files, screens, reports, and files. In addition to these defaults, you have the option to create your own custom screen, report, and file templates. Using custom templates can help you to maintain a consistent code structure and program appearance across an application or application suite.

The Template portion of the Tools > Options interface lets you determine how both the AcuBench default templates and your own custom templates are made available for your use. You can even entirely disable the File > New dialog box that allows you to choose the base template for programs, data layout files, screens, reports, and files, such that basic, default characteristics are always used when you create a new program item.

The process of creating templates is discussed elsewhere in this manual. Source file templates are discussed in Using Source Code Templates, screen templates are discussed in Adding Screen Templates, and report templates are described in Adding Report Templates. All files added using this dialog box are displayed in the New File, New Screen, or New Report template group, depending on the template type.

Follow these steps to set Template options:

  1. Select the Template category of the Environment options.
  2. Use File/New options: Toggle the check boxes in the Use New > File dialog when creating group to control when the File > New dialog is displayed. By default, these are all selected, indicating that a File > New interface containing the available AcuBench templates is displayed whenever you create a new program element.

    When you de-select an option, the File > New dialog does not appear when you opt to create a new element of the specified type. Instead, a default element type is automatically created. The defaults are:

    Program | Standard Program (a program structure file with an empty screen)
    Screen | Blank Graphical (an empty graphical screen)
    Report | Blank Graphical (an empty graphical report)
    File | Source Template (a very basic file with COBOL divisions and AcuBench tags)
    FD/SL | Blank (launches the File Designer, bypassing the Import option)
  3. Customize Template interface: To add templates that you have created to the File > New dialog, first select the type of template from the Template for drop-down box.
    1. Click Add and provide a descriptive title for the template that you want to use.
    2. Click the browse button to navigate to the location of the template file, then select the file, and click Open.
    3. Add a detailed description of the template in the large entry field at the bottom of the Add New Template File interface.
    4. Click OK. When you exit the Tools > Options interface, you can use the File > New command to verify that your template has been added to the appropriate interface.

    To remove a template that you have previously added to the interface, select the template icon and click Delete. To modify the title, file path, or description of a template, select its icon and click Modify.

    You cannot change the set of default templates using this interface.

Parent topic: Setting Environment Options


Version Control Options

The Version Control options allow you to define commands to work with your version control system. A complete description of the Version Control interface is contained in Version Control.

Parent topic: Setting Environment Options


Build Options

The Build options allow you to control some aspects of how the workbench behaves when you run tools, compile programs, execute object files, or build/rebuild the workspace.

Use the following procedures to set Build options:

  1. Select the Build category of the Environment options.
  2. When running tools option: Enable Always save all documents to automatically save all open documents before performing such actions as reparsing, generating code, or compiling, among others.
  3. For the three options under When compiling programs that include generated source code:
    • Enable Always generate code if program structure file is modified to generate code before compiling any time that the program structure file has been modified since the last generate action.
    • Enable Prompt before generating source code to direct the workbench to always display a confirmation dialog before starting code generation.
    • Enable Jump to Event Editor when browsing to direct AcuBench to open the Event Editor when you click a compilation error message caused by code in the program’s .evt COPY file.
  4. For the two options under When executing source (.cbl) or object files:
    • Enable Always re-compile if the original source file is modified to direct the workbench to recompile a modified source file before executing the associated program.
    • Enable Prompt before re-compiling source file if you want the workbench to display a prompt that asks if you want to recompile a modified source file.
  5. For the two options under When building or reparsing the workspace:
    • Enable Always generate modified program (.psf) files to direct AcuBench to first generate code for all programs (.psf files) in the workspace that have been modified since the last build/rebuild or reparse, before starting the new build/rebuild or reparse.
    • Enable Always generate modified FD/SL (.dlt) file to direct the workbench to generate new FD and SL files and update any user-modified file-handling code for all data layout files (.dlt) that have been modified since the last build/rebuild or reparse, before starting the new build/rebuild or reparse.
Parent topic: Setting Environment Options


Debug Options

The Debug options allow you to specify whether AcuBench should perform the same save and code generation actions, prior to starting a program in the debugger, that are performed prior to a build/rebuild. Because you have the option to modify code in the debugger, this option can provide a handy way to speed up the testing of new changes. Consider the following case:

  • In the Tools > Options > Build interface, you have specified that AcuBench should generate code before compiling or recompiling source code.
  • In the Tools > Options > Debug interface, you have specified that the integrated debugger should follow build options.
  • As you are debugging a program in the integrated debugger, you make some changes to your event code.
  • When you exit and re-enter the debugger, AcuBench checks for changes, regenerates your program, compiles, and restarts the debug process. You can immediately test your changes to the code.

There is an important caveat for those considering this option. If you have selected Always save all documents in the Tools > Options > Build interface, having the debugger use the build options may have a significant impact on performance. Because saving a file changes its timestamp, this combination of options causes AcuBench to perform a detailed check for code changes in every file every time you enter the debugger.

This interface also lets you determine whether the current line of execution in the debugger is highlighted and what the highlight color is.

To set Debug options, perform the following steps, as needed:

  1. Select the Debug category of the Environment options.
  2. Enable the Follow the options specified in ‘Build’ page check box to direct the workbench to apply the settings in the Build category to the set of actions taken prior to starting a program in the debugger.
  3. Enable the Colorize line of execution check box if you want the current line of execution in your code to be highlighted. Choose a highlight color in the drop-down box to the right of the check box.
Parent topic: Setting Environment Options


Keyboard Options

The Keyboard options allow you to view, define, redefine, or remove the keyboard shortcut keys associated with workbench commands. A complete list of workbench commands and their default keyboard shortcut settings is provided in Keyboard Shortcut Reference.

At the top of the Keyboard options screen, next to the Categories label, is a drop-down list of three command categories: Main, Code Editor, and Screen Designer. Main is a superset of Code Editor and Screen Designer.

You can set Keyboard options as follows:

  1. Select the Keyboard category of the Environment options.
  2. Select the category of commands that you want to view or modify.

To view a shortcut key definition, locate the command of interest in the list. The shortcut key definition, if any, is displayed in the column to the right of the command.

Use the following procedures to assign a shortcut key:

  1. Locate the command of interest in the list and click it. Note that a short description of the command is displayed to the right of the Currently assigned to label near the bottom of the screen.
  2. Click in the Shortcut key entry field.
  3. Enter the desired key or key combination by pressing keys on the keyboard. As you press each key, the keystroke appears in the entry field.

    Look under the Currently assigned to label to see if that key (or key combination) is already defined for another command. It is possible to assign the same key to more than one command. However, doing so is only desirable when the commands can only be activated in mutually exclusive states. For example, the key combination Ctrl+G might be defined in the Code Editor to perform a GotoLine command and in the Screen Designer to toggle the grid (ToggleGrid). Because you can’t be actively working in both the Code Editor and Screen Designer at the same time, typing Ctrl+G is never ambiguous, and the correct action is always performed. In the case where the commands do not belong to mutually exclusive states, the results are undefined.

  4. Click Assign.

To remove a shortcut key, locate the desired command and click it. Note that a short description of the command is displayed to the right of the Currently assigned to label. Click Remove.

To restore the default shortcut definitions, click Reset All.

Parent topic: Setting Environment Options


Prefix Options

The Prefix options allow you to determine the naming convention used to provide default names for new projects and files and the default directory paths established for those elements. These default directory paths are used to create a directory structure for each new project that you create. You can change this structure only when you are creating a new project, when you click the More Info button. Once a project has been created, the directory structure can no longer be changed.

Use the following procedures to set your default Prefix options:

  1. Select the Prefix category of the Environment options.
  2. File prefix fields: For each file type, enter the string to be used as the default base name for creating new files of that type.
  3. Working directory fields: For each working directory, enter the desired folder name in the entry field.

Each of the working directory entries in this interface has a corresponding macro, which you can use as a shorthand method of referring to the directory path in other AcuBench interfaces, such as the Project Settings interface. These macros include the following:

Macro | Definition
%sourcedir% | The path assigned in the Source directory field
%screendir% | The path assigned in the Screen directory field
%reportdir% | The path assigned in the Report directory field
%copylib% | The path assigned in the Copylib directory field
%objectdir% | The path assigned in the Object directory field
%listdir% | The path assigned in the List directory field
%resdir% | The path assigned in the Resource directory field
%layoutdir% | The path assigned in the FD directory field

If you are using the default project directory structure, the following syntax:

.\object\@.acu

is functionally equivalent to:

%objectdir%\@.acu

Note that, by default, these working directory macros, rather than full directory paths, are used in COPYPATH definition that appears on the Environment tab of the Project Settings window.

Parent topic: Setting Environment Options


Miscellaneous Environment Options

Although somewhat obscured by their placement in this category, the Miscellaneous options include three very important options that affect:

  • how the COPYPATH environment variable is defined
  • whether when a source file is added to a project, tags are inserted in the file and a program structure file is created

The definition of the COPYPATH environment variable determines where AcuBench looks for COPY files and whether and which files are found. COPYPATH's correct definition is essential to a successful build. For a detailed discussion of the COPYPATH environment variable, see The COPYPATH Environment Variable.

Use the following steps to set Miscellaneous options, as needed:

  1. Select the Miscellaneous category of the Environment options.
  2. For the two options under COPYPATH:
    • Enable When adding a COPY file to automatically modify the definition of COPYPATH to include the path to the new COPY file. COPYPATH is defined on the Environment tab of the Project Settings window.
    • Enable When modifying COPY path in Add/Remove files dialog to modify the definition of COPYPATH when it is changed via the Add/Remove Files dialog.
  3. Under the Automatically create a program structure file option, enable When adding a source file to the project’s source folder to direct AcuBench to create a program structure file for any source file that is added to a project. As a part of this process, the source file is modified to include a set of AcuBench tags (see Automatic Code Generation). Note that only programs that have a program structure file are able to use the Screen Designer and other tools that generate code.

    Keep in mind that in the Add Program dialog, you can specify, on an individual basis, whether a program structure file should be created for any given program being added. For an introduction to AcuBench programs, see Programs. More detail is available in Working with Programs. For a discussion of adding source files to a project, see Adding an Existing Source File.

Parent topic: Setting Environment Options


Setting Code Editor Options

The Code Editor portion of the Tools > Options dialog box provides interfaces for customizing both the appearance and the functionality of the Code Editor. This includes options that determine the behavior of Code Editor tools, including the Code Completion pop-up window and the AcuBench paragraph, variable, constant, and COPY file lists.

  • Code Editor General, Format, Tabs, and Keyword Options
  • Code Insight Options
  • Paragraph List, Variable List, Constant List, and COPY File List Options
Parent topic: Customize Your Working Environment


Code Editor General, Format, Tabs, and Keyword Options

General options for the Code Editor let you determine Line Number pane width, Code Editor line length, ASCII code settings, and behavior of the editor’s vertical block select function.

For ANSI format programs, you can also preserve existing information in the Identification Area.

Format options can be used to change the colors that identify each ANSI display field (Sequence Number area, Indicator area, area A, area B, and Identification area). You can also customize the appearance of code text types (Comment, Keyword, String, Number, and Text) and designate the text string that is inserted in ANSI format columns 73-80 when you modify source code.

Format options also allow you to change the default column settings of your file. The default settings are the ANSI-specified standard settings. If you are working with terminal source format, you may want to change these default settings. An explanation of terminal source format is found in The ACUCOBOL-GT User's Guide.

Tabs options allow you to direct that the editor support the tabs in your source code or automatically convert the tabs in your code to spaces. You can also set up to 32 custom tab stops.

Finally, Keyword options give you the ability to add, delete, and modify keyword sets. You can also determine how far the next line after the keyword will be indented, if at all.

Note that these keyword settings affect only the workbench’s colorization and auto-indent functions. Adding or deleting a keyword in a default list does not affect the behavior of the ACUCOBOL-GT compiler. To change the list of reserved words recognized by the compiler, use the -R flag, described in The ACUCOBOL-GT User's Guide.

The Code Editor General, Format, Tabs, and Keyword options are described in Configuring the Code Editor.

Parent topic: Setting Code Editor Options


Code Insight Options

The Code Insight functions are intended to facilitate source code creation, especially when working with graphical screens and reports. The code parameter feature displays hints (similar to the tool tips that appear when the mouse hovers over a button on a toolbar) for using certain COBOL verbs. Code completion provides pop-up lists of options to help complete some code statements and internal library routine calls. Code parameters and code completion are available for the following verbs: CALL, PERFORM, READ, WRITE, START, DELETE, REWRITE, OPEN, CLOSE, CHAIN, MODIFY, INQUIRE, DESTROY, and GO. For more information about using these functions, see Using Code Insight Functions.

With code templates, you can create a library of commonly used code paragraphs or sections. This list of templates can be accessed from within the Code Editor using the hotkey Ctrl+J.

You can set Code Insight options using the following procedures:

  1. Select the Code Insight category of the Code Editor options.
  2. Select the Code Completion feature if you want the workbench to display a list of possibilities for completing your code statement.
  3. Select Code Parameters if you want AcuBench to display a pop-up hint that generally describes the function of the verb you have entered.
  4. Use the Code Template text box to define frequently used code as atemplate that can be inserted into your source code with a mouse click. Approximately 20 default templates are available in the workbench. These templates may be modified directly in the dialog’s Code window.
    • Click New to add a new template to the list, then enter the code for the new template in the Code window. You can either paste code from the Code Editor or another source, or type directly into the window.
    • Add a pipe sign (|) in your code to position the cursor when the template is used. If you include multiple pipe signs, the cursor appears at the first pipe sign in the last line of the code template text. Use a double pipe sign to indicate that the following text should be inserted as a comment.
    • You can display the current list of code templates when working in the Code Editor by pressing Ctrl+J or selecting the Edit > Advanced > Code Template command.
Parent topic: Setting Code Editor Options


Paragraph List, Variable List, Constant List, and COPY File List Options

The Paragraph List, Variable List, Constant List, and COPY File List options allow you to specify how each of these pop-up lists is sorted, and to determine which columns of information are displayed in the box. Because each of these lists functions in a similar manner, the configuration options for each list are likewise similar.

You can set the options Paragraph, Variable, Constant, and COPY File lists as follows:

  1. Click the appropriate category from the Code Editor options.
  2. In the Sort By area, sorting lists (Constant, COPY File, Paragraph, and Variable) select one of the available radio buttons to determine how the pop-up list will be sorted.
    • To sort items in order of their occurrence in the program, select the Occurrence in the program radio button.
    • To list items in alphabetical order, select the Alphabetically radio button.
    • The Paragraph List has the following unique options:
      • To sort COPY file names alphabetically and have paragraph names sorted by occurrence within each COPY file, select Occurrence within alphabetic sort of copybooks.
      • To sort COPY file names alphabetically and have paragraph names sorted alphabetically within them, select Alphabetically within alphabetical sort of copybooks.
    • The Variable List has the following unique options:
      • To sort variable names by level number, select the Level number radio button.
      • To sort variables by picture clause, select Picture description.
    • The Constant List has the following unique option:
      • To sort constants by value, select Value.
    • The COPY Files List has the following unique options:
      • To sort COPY files alphabetically by directory, select the Directory radio button.
      • To sort COPY files based on the names of the files in which they are declared, select Declared file.
  3. In the Show option area, check one or more of the available check boxes to determine what information will appear in the pop-up list.

    The Paragraph, Variable, and Constant lists all have the option to display the name of the COPY file in which the program element is declared. To select this option, select The name of the copybook.

    • The Variable List has the following additional options:
      • To display level numbers, select Level number.
      • To display picture clauses, select Picture description.
      • If you want to see FILLER data items in the Variable List, select Include FILLER data item, as well.
    • The Constant List has the following additional option:
      • Select Value to see each constant's value in the Constant list.
    • Finally, the COPY File List has the following options:
      • To display each COPY file's directory, check the Directory check box.
      • To see the file in which each COPY file is declared, select Declared file.
Parent topic: Setting Code Editor Options


Setting Screen Designer Options

You can set Screen Designer features, including grid behavior, control property default values, and control property visibility options in the Screen Designer portion of the Options dialog box.

These options are discussed in detail in Configuring the Screen Designer.

Parent topic: Customize Your Working Environment


Setting Code Generator Options

The Code Generator options allow you to control which files are generated and, in some cases, what parts of a file are generated when you initiate a Generate action. You can also determine the default program tags you want AcuBench to generate, including extern tags, which allow the automatic generation of .def and COPY file statements for external files. For a detailed discussion of workbench code generation facilities, see Automatic Code Generation.

  • Generate Document Options
  • Program Tag Options
Parent topic: Customize Your Working Environment


Generate Document Options

The Generate Document options let you determine the automatic code generation behavior you want AcuBench to perform. You can also change the default file extensions for generated files in this interface. When you change a default file extension, that change is also reflected in the Program Properties dialog box. Note that changes to these settings made on the Code Generation tab of the Program Properties dialog box override the default settings made in this Options > Generate Document interface. For information about this dialog box, see AcuBench Program Properties.

Set any desired Generate Document options as follows:

  1. Select the Generate Document category of the Code Generator options.
  2. The list of options under Generated documents are selected by default. These options have the following functions:
    • When Program file is selected, and Regenerate tagged area only is not selected, AcuBench generates code for the program source file, replacing the existing program_name.cbl file. You can change the default file extension (.cbl) in the associated entry field.
    • When both Program file and Regenerate tagged area only are selected, AcuBench generates code in the tagged portions of the program file (.cbl) only. This preserves any code that you may have added outside of the AcuBench tags.
    • When Working storage is selected, AcuBench generates the Working-Storage COPY file (.wrk). You can change the default file extension in the associated entry field.
    • When both Working storage and Exclude variables in program file are selected, AcuBench does not generate Working-Storage items in the .wrk file for variables that are already declared in the program file (.cbl).
    • When Event paragraph is selected, AcuBench generates the Event Paragraph COPY file (.evt). You can change the default file extension in the associated entry field.
    • When both Event paragraph and Exclude paragraphs in program file are selected, AcuBench does not generate paragraphs that are already included in the program file. The workbench assumes that a paragraph in the program file with the same name as a paragraph that could be generated in the .evt file suppresses the paragraph that could be generated.
    • When Screen section is selected, the workbench generates a Screen Section COPY file (.scr). You can change the default file extension in the associated entry field.
    • When Report section is selected, the workbench generates a Report COPY file (.rpt). You can change the default file extension in the associated entry field.
    • When AcuBenchProcedure division is selected, generates a Procedure Division COPY file (.prd). You can change the default file extension in the associated entry field.
    • When Menu paragraph is selected, AcuBench generates a Menu Paragraph COPY file (.mnu). You can change the default file extension in the associated entry field.
    • When Linkage section is selected, AcuBench generates a Linkage Section COPY file (.lks). You can change the default file extension in the associated entry field.
  3. For the two Attributes of generated files options:
    • Select Program file as read-only to cause the source program file (.cbl) to be created as a read-only file.
    • Select Copy book as read-only to cause all generated COPY files to be created as read-only files. This is the recommended behavior.
  4. Screen Control Focus option: Set a value for the ACCEPT-CONTROL variable (from 0 to 4) in the ACCEPT-CONTROL value entry field. The default value is 1. If you do not want an ACCEPT-CONTROL statement generated at all, select (none). For information about the purpose of ACCEPT-CONTROL, see General Rule 4 of the topic Special-Names Paragraph.
  5. Generated document format options: Select the Merge to one program file radio button if you want all of your AcuBench-generated code, including COPY files, written to a single program file. Note that AcuBench can handle approximately 200,000 total lines. If your files total more than this amount, the merged file may fail to produce.

    Set the Split to multiple copy files radio button if you want AcuBench to maintain your COPY files in separate files.

  6. Attributes of Data Set code generation option: Select Link file close to open if you want AcuBench to automatically generate a Close I/O paragraph for a data set when the Open option is already set. This code generation option is especially helpful if you are updating your Version 5.x AcuBench project to Version 6.x or later.
Parent topic: Setting Code Generator Options


Program Tag Options

To support automated code generation, if you choose, AcuBench places special comment tags in your COBOL source file. These tags reserve areas of your program for code generated by AcuBench. For example, if you use the Screen Designer to create a screen for your program, every time you generate code for the program, the workbench creates a COPY file that describes the screen, and a COPY statement is inserted between the copy-screen tags in your program's Screen section. You can control whether specific tag pairs are automatically generated or suppressed via the Tools > Options > Code Generator > Program Tag interface.

AcuBench tags always have the format:

*{Bench}tag-name
*{Bench}end

When working with programs that include AcuBench-generated code, always be sure to add any user-defined code outside of the {Bench} tags. Everything between the tags is deleted and re-created every time you generate the program, but code outside the tags is preserved (unless you have specifically elected otherwise in your Code Generator options).

If you were to use all of AcuBench's facilities for automatically generating code, your program could have the following set of tags in your source file (.cbl):

*{Bench}prg-comment
* Demo.cbl
* Demo.cbl is generated from C:\Sample\Demo.Psf
*{Bench}end
 IDENTIFICATION              DIVISION.
*{Bench}prgid
 PROGRAM-ID. Demo.
 AUTHOR. ljones.
 DATE-WRITTEN. Wednesday, January 04, 2006 9:54:03 AM.
 REMARKS.
*{Bench}end

Program description comments and program ID information is pulled from settings in the Project > Properties dialog.

A Special Names definition COPY file is included whenever ActiveX controls are used in a screen created in the Screen Designer:

 ENVIRONMENT DIVISION.
 CONFIGURATION SECTION.
 SPECIAL NAMES.
*{Bench}activex-def
 COPY "MSChart.def".
 COPY "Acuclass.Def".
     .
*{Bench}end

In the example above, the program uses the MSChart ActiveX control, so AcuBench has added references to two required definition files between the activex-def {Bench} tags.

If in your Windows environment you have "," (comma) defined as the decimal symbol, a DECIMAL POINT IS COMMA statement is inserted between the decimal-point tags, which the code generator places directly after any ActiveX tags in the Special Names section.

*{Bench}decimal-point
*{Bench}end

COPY statements to include SELECT statement (.sl) COPY files generated by the File Designer are inserted between the file-control tags:

 INPUT-OUTPUT SECTION.
 FILE-CONTROL.
*{Bench}file-control
 COPY Demo.SL
*{Bench}end

COPY statements to include file descriptor (.fd) COPY files generated by the File Designer are inserted between the FILE tags:

 DATA DIVISION.
 FILE SECTION.
*{Bench}file
 COPY Demo.FD
*{Bench}end

COPY statements to include standard ACUCOBOL-GT definition (.def) COPY files are inserted between the acu-def tags:

     WORKING-STORAGE SECTION.
    *{Bench}acu-def
     COPY "acugui.def".
     COPY "acucobol.def".
     COPY "crtvars.def".
     COPY "activex.def".
     COPY "showmsg.def".
    *{Bench}end

COPY statements to include Working-Storage (.wrk) COPY files containing items defined by the graphical design tools are inserted between the copy-working tags:

    *{Bench}copy-working
     COPY Demo.wrk
    *{Bench}end

COPY statements to include external .def files are inserted between the extern-def tags:

    *{Bench}extern-def
     COPY externalfile.def
    *{Bench}end

COPY statements to include Linkage section (.lks) COPY files containing items defined in the Linkage Editor are inserted between the linkage tags:

     LINKAGE SECTION.
    *{Bench}linkage
     COPY Demo.lks
    *{Bench}end

COPY statements to include screen (.scr) COPY files created by the Screen Designer are inserted between the copy-screen tags:

     SCREEN SECTION.
    *{Bench}copy-screen
     COPY MainMenu.scr
     COPY Orders.scr
     COPY Invoices.scr
    *{Bench}end

A Procedure Division header with a USING phrase is generated between the linkpara tags when linkage items are defined in the Linkage Editor:

    *{Bench}linkpara
     PROCEDURE DIVISION USING order-id.
    *{Bench}end

A declarative section with code to handle standard file error conditions is inserted between the declarative tags when data sets are defined with the Data Set Designer. You can also control what is generated inside the declarative tags via the Event Editor. For more information, see Associating Code with Screen Elements in Working with Screens.

    *{Bench}declarative
     DECLARATIVES.
     INPUT-ERROR SECTION.
         USE AFTER STANDARD ERROR PROCEDURE ON INPUT.
     ...
     END DECLARATIVES.
    *{Bench}end

An insertion point for user-defined code to be executed before the program's initial routine is added at the start of the Acu-Main-Logic paragraph. When Before Program code is defined in the Event Editor, AcuBench generates the necessary PERFORM statement between the tags.

    *{Bench}entry-befprg
         PERFORM Before-Orders-Program
    *{Bench}end

Code to call the program's main screen (a paragraph included in the .prd file generated by the Screen Designer) is inserted between the run-mainscr tags:

    *{Bench}run-mainscr
         PERFORM Acu-MainMenu-Routine
    *{Bench}end

COPY statements that include procedure, event, and menu (.prd, .evt, .mnu) COPY files are inserted between the copy-procedure tags:

    *{Bench}copy-procedure
     COPY Demo.prd
     COPY Demo.mnu
     COPY Demo.evt
    *{Bench}end

COPY statements to include corporate external Procedure Division COPY files are inserted between the extern-cpy tags:

    *{Bench}extern-cpy
     COPY externalcopyfile.cpy
    *{Bench}end

If you want to view or print a report, a call to the master print paragraph is inserted between these tags:

    *{Bench}reportname-masterprintpara
    *{Bench}end

Including and excluding tags

Tags are included in a new program when you generate the program the first time. If you use the Code Generator > Program Tag section of the Tools > Options interface to indicate that you do not want certain tags created, then later change your mind, the missing tags will not be added to programs that you have previously generated. You can add the tags manually, after which AcuBench will generate any corresponding code between the tags.

Tags are inserted into an existing program if you specify that AcuBench should create a program structure file when you add the program to the project. For more information about creating a program structure file when adding a program, see Creating a PSF for an Existing Program. As a general rule, the workbench inserts tags at the end of each relevant section (such as the Screen section). If the workbench cannot determine where the end of a section is, it does not insert any tags.

In addition to the typical range of tags, you can also direct the workbench to generate extern tags, which contain COPY statements for external .def and COPY files. Note that standard ACUCOBOL-GT .def and COPY file statements are generated inside acu-def and copy-procedure tags.

You can set Program Tag options as follows:

  1. Select the Program Tag category of the Code Generator options.
  2. Set the Default Tag Name check boxes for the tag pairs that you want AcuBench to generate automatically. Clear check boxes for the tag pairs you don’t want generated.

    Note that the selected tags are added to new AcuBench programs, or to programs for which a new program structure file is being created. If tags are added or removed from the list in the Tools > Options interface, no change occurs in existing AcuBench programs. If you manually add an appropriate set of tags to an existing program, the code generation facility will generate any corresponding code between those tags.

  3. Select Use External Working Storage Copy File Tag if you want the workbench to generate tags for an external COPY file. These tags are generated into the .cbl file, in the Working-Storage section, just after the {Bench}acu-def tags.

    Enter the file name in the associated Copy File List box, using the Browse button to navigate to the desired COPY file. Use the Delete and Delete All buttons to remove files from the list.

  4. Select Use External Procedure Division Copy File Tag if you want AcuBench to generate tags for a COPY file. These tags are generated in the .cbl file, in the Procedure Division, just after the {Bench}copy-procedure tags.

    Enter the COPY file name in the associated Copy File List box, using the Browse button to navigate to the desired COPY file. Use the Delete and Delete All buttons to remove files from the list.

Parent topic: Setting Code Generator Options


Setting Data Designer Options

The Data Designer configuration options allow you to specify the inclusion or exclusion of comments in files created by the data design tools (File Designer, Working Storage Editor, and Linkage Editor). In addition, you can select the colors used to display linked items (items brought in via a COPY statement) included with the data designers. This interface also lets you determine level-number interval settings for the graphical file designers. You can also set Graphical FD, WS, and Linkage Data Designer options.

To set General Data Designer options, use the following steps:

  1. Click the General category of the Data Designer options.
  2. Comment options: Select a radio button to specify the inclusion or exclusion of comments in files created by the data design tools.
  3. Enter a default prefix to be applied to any new I/O paragraphs in the Function prefix entry field.
  4. Copy file color options: Specify the colors used to show linked data items in a data structure (included via the Link to file option of the Add Item list).

    Linked items may themselves include items via COPY statements. Items included as the result of nested COPY statements are also shown in a contrasting color. You can set the color used at each level by double-clicking in the Text Color field of the desired level and selecting a color.

You can set Graphical FD, WS, and Linkage Data Designer options with the following procedures:

  1. Click the Graphical FD, Graphical WS, or Graphical Linkage category of the Data Designer options.
  2. If desired, change the default element prefix in the Element Prefix entry field.
  3. Set the level-number intervals for the second, third, and fourth subitem levels for code generated by the File Designer. You cannot change the first level setting.
  4. Enter an interval for any levels past the fourth level.

    Your level-number sequence, along with a preview of element names using the prefix convention you have chosen, is shown in the display box.

Parent topic: Customize Your Working Environment


Setting Report Writer Options

You can set Report Composer features, including grid behavior, report control property default values, and report control property visibility options in the Report Writer portion of the Options dialog box.

These options are discussed in the chapter Configuring the Report Composer.

Parent topic: Customize Your Working Environment


The Customize Dialog

The Tools > Customize dialog box can be used to modify any of the default AcuBench toolbars, create custom toolbars for AcuBench, or establish links to external applications. This dialog box contains three tabs: Toolbars, Commands, and Tools.

The Toolbars tab allows you to create, delete, or reset a toolbar. It also provides an alternate mechanism for controlling which toolbars are hidden or displayed.

The Commands tab lists all of the commands in AcuBench that can be placed on a toolbar, including the links you've established to external applications (listed in the Launch Tools category).

The Tools tab hosts the interface that allows you to establish and configure links to external applications.

  • Customizing AcuBench Toolbars
  • Accessing External Applications
Parent topic: Customize Your Working Environment


Customizing AcuBench Toolbars

One method through which the AcuBench workspace can be adapted to your individual patterns of use is through the ability to customize existing toolbars and create new ones.

If you have modified a toolbar and want to return to the default settings, you can select a toolbar on the Toolbars tab of the Customize window and click Reset. To return all toolbars to their default settings, click Reset All.

Selecting a toolbar name in the Toolbars list makes it visible on the screen; de-selecting a toolbar name hides that toolbar.

You can delete any toolbar that you have created by selecting the toolbar name in the Toolbars list and clicking Delete. You cannot delete any of the default, AcuBench toolbars.

To create a new toolbar

  1. Click Tools > Customize.

    The dialog box opens with the Toolbars tab selected.

  2. Click New.

    A New Toolbar dialog box opens.

  3. Enter a descriptive name for your new toolbar, then click OK.

    The name of your new toolbar is added to the list of toolbars in the dialog box, and a small, floating toolbar appears just below the toolbar area of the workspace.

  4. Follow the instructions below to build your toolbar. As with any other toolbar, you can dock your custom toolbar(s) at the top of the screen, or in a variety of other locations in the workspace.

To add buttons to a toolbar

  1. On the Commands tab of the Customize dialog box.

  2. Select a type of command from the Categories list box on the left side of the screen. A list of icons associated with the category that you have selected appears in the Buttons frame on the right of the screen.
  3. Click a button from the list to see a description of the associated functionality in the Description frame.
  4. Drag a button from the Buttons frame to a toolbar to add that command to the toolbar.
  5. When you are finished using the Customize dialog box, click Close.

To remove buttons from a toolbar

  1. Make sure that you are in the Commands tab of the Customize dialog box.
  2. Drag the button from the toolbar to any part of the Customize dialog box.

To add or remove spacers from a toolbar

  1. Make sure that you are in the Commands tab of the Customize dialog box.
  2. To add a spacer character to the left of an existing button, click the button and drag it slightly to the right, then release the mouse button.
  3. To remove a spacer character from a toolbar, click the button to the right of the character and drag it slightly to the left (overlapping the spacer character), then release the mouse button.
Parent topic: The Customize Dialog


Accessing External Applications

When you are working in AcuBench, it may be useful to have easy access to external applications, like Windows Explorer, or a calculator. The Tools tab of the Customize interface allows you to create a link to such external applications. Once the link has been made, you can launch the associated application from a menu within the workbench, or by adding a launch button to any toolbar.

Add a link to an external application as described below:

  1. Click the New button in the upper right of the Menu contents list box.
  2. In the empty field created for the new list item, enter the name that you want to associate with the application. This is the name that is added to the Tools > Launch Tools menu and the text of the tool tip that is displayed when the mouse pointer is held over the command icon on the toolbar.
  3. Enter the full path of the external executable that you want to access from within AcuBench in the Commands field, or use the browse button to the right of the field to navigate to the executable.
  4. The Arguments field is used to specify switches or parameters to apply to the executable each time the application is started. You have the choice to leave this blank or enter any options that you want to pass.

    The arrow button to the right of the field expands to provide the following set of default arguments:

    Argument | Description
    File Path {FilePath} | The full path name of the files that arecontained in the current project or folder.
    File Directory {FileDir} | The directory for the files contained in the current project or folder.
    File Name {FileName} | The name of the selected file or files.
    Current Directory {CurDir} | The current directory containing the AcuBench application.
    Workspace Path {WkspPath} | The full path name for the current workspace.
    Project Directory {ProjectDir} | The directory containing the current project.
    Project Name {ProjectName} | The name of the current project.

    The %directory_code% AcuBench macros can also be used in this interface.

  5. If applicable, enter the full path to the directory that the applicationwill use as its working directory in the Working Directory field.

    By default, the working directory is the same as the location of the application. Three of the tokens used in the Arguments field can also appear in the working directory field. These are {FileDir}, {CurDir}, and {ProjectDir}.

  6. Click Close to save your changes and exit the Customize interface.

    Note that text in the Context menu field is not used at this time.

Parent topic: The Customize Dialog


Version Control

  • Version Control Overview
  • The Version Control Interface
  • Adding Commands to the Menu Command List
  • Modifying the Command List
  • Saving the Command List
  • Command Variables
  • Issuing Version Control Commands
Parent topic: AcuBench Version 10.2.0 User's Guide


Version Control Overview

AcuBench provides support for third party version control systems that include a Windows command-line interface.

Version (source) control systems help developers manage and maintain projects by creating a database of project files and resources, which the version control system monitors and protects. In a team environment, this is essential to allow multiple developers to work in the same project without overwriting or otherwise interfering with one another’s work. Developers view and modify project files and resources locally, then return their changes to the version control system. The system logs changes so that prior versions of an item are easily retrieved or restored, and integrates each developer’s changes with changes made by the rest of the team.

Most version control systems support the following basic actions:

  • Create project
  • Create subproject
  • Add files to a project
  • Check files out of a project
  • Update local files with other developers' logged changes
  • Check revised files into a project
  • Retrieve version history for a project and its files

Version control systems perform a number of useful functions. Their automatic logging facilities can be useful in creating a complete and detailed project history. Version control can also be used to help with consistency management (maintaining a consistent look and feel between modules in an application), and make it easy to branch and merge code (allowing testing of an upcoming release, for example, without affecting the code base for the current release). Version control systems do not take the place of good planning and communication, but they can make managing team contributions to an application significantly easier.

  • Working with Version Control in AcuBench
  • Preliminary Considerations
Parent topic: Version Control


Working with Version Control in AcuBench

The AcuBench interface to version control software allows you to define commands that call your version control system directly or that execute your version control batch files. These commands are placed on the Version Control menu item that is accessed when you right-click a project or file node in the Workspace window.

When you select and run a version control command, AcuBench passes the defined command string and arguments to the Windows command shell for execution. By default, the command is echoed to the AcuBench Output window, which is also used to display console messages from the version control system.

Note: If your version control system does not have a Windows command-line interface, it cannot be accessed through AcuBench

When adding version control commands to the AcuBench interface, keep in mind that there are some commands that are better issued from outside AcuBench, or after AcuBench has been shut down. For example, changes to a particular program or file can easily be committed to the version control repository from within AcuBench. But a project commit (writing all changes made to a project to the version control repository) is better issued from the command line, after AcuBench has been closed, to ensure that all changes to the workspace project file (.pjt) have been written to disk.

Parent topic: Version Control Overview


Preliminary Considerations

As you define your projects, instead of trying to group all of your programs into a single, large workspace, create logical groupings of related programs. Because the AcuBench project and workspace concepts are entirely virtual, these groupings do not affect the creation of object files or the execution of the final application. Placing extremely large numbers of programs into a single workspace, however, can have a negative impact on AcuBench's performance, and can make managing the version control repository more complicated.

Before importing a project into the version control repository, consider the following:

  • Will each developer have a custom set of project modes (.pof files) and one or more unique Tools > Options INI files, or will these files be created for and tracked with each project?

    Creating and tracking customized project modes can help to create consistency in the building and testing process. Since .ini files created in the Tools > Options interface contain the defaults for screens, reports, and controls, maintaining a centralized .ini can help with consistency management. For more information about creating project modes, see Project Settings. For more information about the .ini file, and the Tools > Options interface used to modify the file, see The Tools > Options Dialog.

  • Will each program be generated into a single .cbl file or several different COPY files (the AcuBench default)?

    Because all of the information generated into AcuBench COPY files is stored in the program structure file (.psf), which must be tracked if you are using AcuBench code generation, it is more efficient to generate separate COPY files with version control. If all code is generated into the source (.cbl) file, then the same information is being tracked twice.

  • How will the project directory be structured?

    Do you plan to use the default directories created by AcuBench, or are you using an existing directory structure? Keep in mind that some version control systems require all project files to reside a single directory structure (a main project directory plus subdirectories).

Parent topic: Version Control Overview


The Version Control Interface

You define, view, and maintain version control commands in the Tools > Options > Environment > Version Control window.

Note: The Tools > Options > Environment > Version Control interface has substantially changed from Version 5.0. However, all Version Control commands defined in Version 5.0 projects are fully retained and can be modified and maintained in the revised interface.
  • Displaying the Version Control Window
  • The Version Control Interface Fields
Parent topic: Version Control


Displaying the Version Control Window

You can display the version control window using the following steps:

  1. On the AcuBench menu bar, select Tools > Options to open the Options dialog.
  2. Click the plus sign (+) next to the Environment menu item to view its subitems.
  3. Click Version Control to display the Version Control configuration window.
Parent topic: The Version Control Interface


The Version Control Interface Fields

The following fields appear in the Version Control window:

Menu command list

Displays the names of the commands that you have defined for your version control system in the Menu contents field. These are the menu items that will appear in the Version Control right-click menu. You can add, delete, and reorder commands using the four buttons at the top-right of the Menu command list. To modify a name, double-click the name and make your changes.

Fundamental source control commands

Displays the command line(s) defined for the name selected in the Menu command list. Commands are defined in the Command, Argument, and Working directory fields and cannot be directly altered in this area. You can add or delete commands using the buttons at the top of the Fundamental source control commands list. To modify the definition of a command, select the command, then modify the values in the Command, Argument, and Working directory fields.

Command

In this field, enter the full path to and executable file name of your version control system software, or your batch file. You can search for the executable file by clicking the button next to the Command field.

Arguments

In this field, enter the appropriate arguments for the version control command. These arguments are sent to the version control system executable identified in the Command field. Arguments consist of commands recognized by your version control system. You may include any of a variety of variables defined by AcuBench. The values of these variables depend on the directory and file structure of your workspace. See the description included in Command Variables.

Working directory

In this field, enter the path for the working directory from which the version control command must be executed. This directory must match the directory information set in your version control system. For example, if you have the working directory in your version control system set to C:\Checkout, then Working directory in AcuBench must also be set to C:\Checkout.

Use Output Window

When this option is enabled (checked), standard output from version control commands is redirected to the Version Control tab of the Output window.

Ask Argument

When this option is enabled (checked), a Command Arguments dialog box is displayed before AcuBench executes the version control command. The Command Arguments dialog allows the user to add arguments to the version control command.

This option can be uniquely set for every command listed in the Fundamental source control commands list. In addition, you can use any of the variables described in Command Variables to build your command-line argument.

Parent topic: The Version Control Interface


Adding Commands to the Menu Command List

You can define a version control command as follows:

  1. Click the New button at the top-right of the Menu command list and enter the name of the new command in the Menu contents field. This is the name that will appear on the Version Control pop-up menu.
  2. With the new command still selected, click in the Fundamental source control commands area and click the New button. Define the command in the Command, Argument, and Working directory fields. Note that any command listed on the Menu command list can have multiple version control actions (commands) defined for it. To define another command, again click the New button in the Fundamental source control commands list and define the command in the Command, Argument, and Working directory fields. Commands are executed in the order they appear in the list. How to change the order is described in Modifying the Command List.
Parent topic: Version Control


Modifying the Command List

To delete or reorder your version control commands, first open the Tools > Options > Environment > Version Control dialog.

To delete a command from the Menu command list, select the command that you want to remove from the list and click the Delete button at the top-right. Note that all of the associated commands in the Fundamental source control commands list are also deleted.

Delete a command from the Fundamental source control commands list as follows:

  1. Select the menu command with which the fundamental command is associated.
  2. In the Fundamental source control commands list, select the command that you want to delete and click the Delete button at the top-right of the list. Note that the Menu command item is not removed.

To reorder the command names on the Version Control menu, in the Menu command list, select the command that you want to move up or down in the list and use the Move Up or Move Down arrow buttons to change the order. You can move only one command at a time.

Parent topic: Version Control


Saving the Command List

To save your work in the current workspace, click OK.

To save your work in a separate .ini file, click Save at the bottom of the Options (Version Control) window and specify a name.

CAUTION:
If you overwrite the AcuBench.ini file, you are changing the default options that will be loaded by any new AcuBench workspaces that you create.
Parent topic: Version Control


Command Variables

The following list describes the AcuBench-defined variables that you can include in the Arguments and Working directory fields. To insert a variable, click the right-arrow button to the right of the entry field and select the desired variable from the list. AcuBench assigns values to these variables based on the state of your current workspace.

Variable | Description
File Path{FilePath} | The full path and name of the currently selected file or folder.
File Directory{FileDir} | The full path to the directory of the currently selected file.
File Name{FileName} | The name of the currently selected file.
Current Directory{CurDir} | The path and name of the directory in which the AcuBench executable is located.
Target Directory{TargetDir} | The path to the target project or folder. When source files are checked out, they are stored in the target directory until you check the files back in.
Workspace Path {WkspPath} | The full pathname and file name of the current workspace.
Workspace Name {WkspName} | The name of the current workspace.
Project Directory {ProjectDir} | The full path to the current project, excluding the name of the project file.
Project Name {ProjectName} | The name of the current project.
Folder Name {FolderName} | The name of the current folder.
Comment {Comment} | Include a comment defined by your version control system.
Parent topic: Version Control


Issuing Version Control Commands

Once you have added commands to the Version Control interface, a new menu option, Version Control, is added to the pop-up menu that appears when you right-click a project node in any Workspace Window view, a program node in the Structure view, a file in the File view, or a data layout in the Data view.

The context for each command that you issue depends partially on which file is selected when you right-click and partially on the arguments that you have specified for the command. If, for example, you have specified that a commit command has {ProjectDir} specified, the entire project will be committed to the version control repository, regardless of which file you have selected. If, however, a commit command has {FileName} or {FileDir} specified, only the currently selected file is committed.

This means that you may define multiple menu options for a single version control command, each specifying a different context. As an alternative, you can specify the Ask Arguments option and manually specify a context each time you issue the command.

When you issue a version control command, AcuBench's default behavior is to echo the command to the Output window, followed by the message Command sent, waiting for completion. Any messages sent back by the version control software are also displayed in the Output window. When the command is completed, AcuBench adds the message Command completed—DONE at the end of output listing.

The following example provides an idea of what appears in the Output window when you issue a version control command. Here, the CVS log command was used to return information about the AcuVet project. (CVS is a free, open-source, third-party version control system.) The example includes only a portion of what was returned by the version control software.

=== cvs.exe -d :pserver:jramos@midas:/home/cvsroot log C:\AcuVet ...		===
     Command sent, waiting for completion...
     =============================================================================
     cvs server: Logging C:/AcuVet
     RCS file: /home/cvsroot/acuvet/AcuVet.pjt,v
     >Working file: C:/AcuVet/AcuVet.pjt
     ...
     ----------------------------
     revision 1.2
     date: 2006/07/27 21:56:42; author: jramos; state: Exp; lines: +1 -1
     Fixed the problems with the individual pet treatment history report.
     Both the complete report and the individual report are part of the
     "graph-rpt" program. Both are accessed from the "Treatment History"
     interface. Use the button with the printer icon to print the
     complete report and the button with the "T" icon to print the
     individual report.
     ----------------------------
     revision 1.1
     date: 2006/07/20 19:38:52; author: bsmith; state: Exp;
     branches: 1.1.1;
     Initial revision
     ----------------------------
     revision 1.1.1.1
     date: 2006/07/20 19:38:52; author: bsmith; state: Exp; lines: +0 -0
     Creating a new testing project for AcuVet.
     =============================================================================
     ...Command completed - DONE.

If the Output window displays an error message, rather than the expected result, it's a good idea to double-check the context in which you are issuing the command. Some commands, for example, might work only when issued from the project directory or the root directory.

Parent topic: Version Control


Working with Projects

  • Introduction
  • Working at the Workspace Level
  • Working with Projects
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

Project development with AcuBench is organized into workspace, project, and program units.

An AcuBench workspace is a container for one or more projects. Physically, it consists of a dedicated file (workspace_name.pjt) that is created when the first project is created in or added to a new workspace. The workspace file records and maintains each member project's configuration and build options (the values of items set in Project > Settings), as well as other project-specific information and workspace configuration settings. The workspace concept is discussed in more detail in The Workspace.

An AcuBench project is a collection of all the files needed to build, run, and debug one or more programs, including all source files, COPY files, screen definition files, resource files (such as bitmaps and audio files), listing files, and object files. Each project has a set of dedicated folders for organizing project files. Each project's configuration and build options are recorded in the workspace file.

When a new project is established, AcuBench creates a home directory and a set of sub-directories for the project. You can specify which sub-directories are created, as well as sub-directory names, in the Tools > Options interface, under Environment > Prefix. Files can be added to the project with the Add > Remove Files function. Project files can reside directly in the project sub-directories or elsewhere on the file system, including on a network drive. AcuBench maintains logical links to project files.

Keep in mind that you control what’s included in the project, which may be expanded to include ancillary items, or restricted to only those elements that are essential to the construction of the final product.

Support for the concurrent development of two or more projects is provided via the workspace structure. Projects that you want to work on concurrently must be members of the same workspace. To create multiple projects in the same workspace, see Creating a Project.

Parent topic: Working with Projects


Working at the Workspace Level

Having the workspace layer in AcuBench provides a means by which you can work with multiple projects simultaneously. This includes the capability to generate code for every program in a workspace, regardless of how many projects are in the workspace. It also provides a means for building all of the programs in a workspace.

It is worth noting that although there are no set limits on the number of programs that can reside in a single workspace, the code generation process is both memory-intensive and CPU-intensive. Also, a number of the handy automation features that AcuBench provides are likewise resource-intensive, so it's best to keep your workspace down to a reasonable size.

  • Creating a Workspace
  • Opening a Workspace
  • Saving a Workspace
  • Building a Workspace
  • Rebuilding a Workspace
  • Regenerating a Workspace
  • Stopping a Build
  • Closing a Workspace
Parent topic: Working with Projects


Creating a Workspace

Workspaces are created indirectly. To create a workspace you must create a project. The following conditions determine when a new workspace is created:

  1. When you create a new project, if no workspace is open, AcuBench automatically creates a new workspace, giving it the same name as the new project.
  2. If when you create a new project, a workspace is already open, you have the option of adding the new project to the current workspace or creating the project in a new workspace.

When a new workspace is created, it is automatically assigned the same name as the project that creates it. To avoid confusion, you may want to rename the project from which the workspace takes its name by right-clicking the project icon in any view of the Workspace window and selecting Properties. In the Project Properties interface, use the Project name entry-field to specify a new name for the project, then click OK.

To create a new project, see the section Creating a Project.

Parent topic: Working at the Workspace Level


Opening a Workspace

Click File > Open Workspace.

To open an existing workspace, select Open Workspace from the File menu. If you recently opened the workspace, you may also be able to open the workspace by clicking the workspace name in the File menu’s Recent Workspaces list.

Note: You do not open individual projects. Every project is a member of a workspace, and it is the workspace that is opened, closed, and saved.
Parent topic: Working at the Workspace Level


Saving a Workspace

To save all changes made to the current workspace, select Save Workspace from the File menu.

Note: When you click Save from the File menu, rather than Save Workspace, only the document that has focus is saved.
Parent topic: Working at the Workspace Level


Building a Workspace

Rather than compiling your source programs one at a time, you can instruct AcuBench to compile all source files in a workspace (including their dependent COPY files) that have been modified since the last build. To do this, you can select Build Workspace from the Build menu or click the Build button on the Project toolbar.

To recompile all programs in the project, regardless of whether they have modified since the last build, use the Rebuild Workspace command, discussed in Rebuilding a Workspace.

By default, each program in the project is compiled according to the compile option settings of the selected project mode. To override the project-level compile settings, right-click the source file in the File view and select Program Compile Options.

During the build, the Output window displays the file name, compiler command line, and either a success (completed) message or list of errors for each file as it is compiled.

If your workspace contains both local and remote objects, you must execute the Build or Rebuild Workspace command twice, once for local projects and once for the remote projects (after selecting the Build > Use Thin Client command). Note that for remote objects, the Build command causes the workbench to check the timestamp that the compiler places in the object file, not the UNIX file creation timestamp.

You can specify some attributes of the build and rebuild process through settings in the Tools > Options > Environment > Build dialog. In that dialog, you can specify such actions as whether the workbench always saves all files or generates code prior to starting compilation.

Parent topic: Working at the Workspace Level


Rebuilding a Workspace

To instruct AcuBench to unconditionally compile all source files in the workspace, regardless of modification date, use the Rebuild Workspace command. Either select Rebuild Workspace from the Build menu or click the Rebuild button on the Project toolbar.

In all other behaviors, the Rebuild command operates exactly like the Build command. For more details, see Building a Workspace.

Note that when you use the command-line interface to build a workspace, the behavior described here is always used, regardless of whether you use the build or rebuild command.

Parent topic: Working at the Workspace Level


Regenerating a Workspace

Use the Build > Regenerate Workspace command to cause all the code-generating elements of a workspace to be regenerated, including every program and screen, Working-Storage and Linkage Section items, all Event Editor code, and all code derived from each data set.

To streamline the process of regenerating and rebuilding a workspace, you can have AcuBench automatically regenerate the workspace each time that you issue a Build Workspace or Rebuild Workspace command. To do this, open the Tools > Options interface, expand the Environment tree, and select Build. Under When building or reparsing the workspace, mark the box next to Always generate modified program (.psf) files before compiling source files.

If you use the AcuBench command-line interface to build a workspace, the workspace is automatically regenerated before source programs are compiled.

You can stop code generation by pressing Enter or Esc.

Parent topic: Working at the Workspace Level


Stopping a Build

You can stop a build or rebuild in progress. To stop a build, click the Stop Build button on the Project toolbar. The Output window displays the names of all files compiled, as well as any error messages generated during the build up to the stopping point.

Parent topic: Working at the Workspace Level


Closing a Workspace

To close a workspace, select Close Workspace from the File menu. If you made changes to components of the workspace that have not yet been saved, a dialog is displayed that asks whether you want to save the changes.

Parent topic: Working at the Workspace Level


Working with Projects

Although you can create an empty project, projects are generally made up of programs and their COPY files and resources. Projects also contain data definitions and data handling code that can be used by any or all of the programs in that project. In addition, each project includes at least one set of compiler and runtime options.

By default, AcuBench creates a project directory and a series of subdirectories for each project. New programs created within the project are placed in the project directory, and generated COPY files are added to the appropriate subdirectories. The project grouping, however, is a virtual construct. Programs and files that appear in AcuBench's Workspace window do not need to reside within the default directory structure. In other words, it is possible to add existing programs to a project without moving those programs and their COPY files to the default project directory.

  • Creating a Project
  • Project Properties
  • Adding Folders to a Project
  • Adding Files to a Project
  • Removing Files From a Project
  • Moving Components Among Projects and Folders
  • Deleting a Project
Parent topic: Working with Projects


Creating a Project

When you create a project, AcuBench creates the infrastructure for the project, including a set of folders (working directories). Optionally, you can create a project that includes a templated source file, a templated screen, and a program structure file (.psf). You can also create a project with object files directed to a remote server. For more information about projects, see Projects.

Once a project is created, you can change the name of the project, but you cannot change the name of the project's working directory or the names of any of the sub-directories.

Before you create a project, you need to decide whether to add the new project to the current workspace (if a workspace is open) or to create it in a new workspace. If you want to work on the new project concurrently with another project, open the workspace that contains that project before creating the new project.

Create a new project using the following procedures:

  1. Click New from the File menu, and then click the Project tab.

    This opens the New dialog window with the Project tab selected.

  2. Click a project template.

    The Standard Project template creates a project and a program. The program, in addition to the program structure file, gets a standard graphical screen.

    The Blank template creates only an empty project structure, to which you can add programs and files.

  3. Enter the name of the project in the Project name field. By default, the project directory is given the same name as the project, as shown in the Location field.

    Note that you can change the default path, and that multiple projects can reside in the same directory. Also note that the only files that must reside in this project directory are the workspace project file (.pjt) and the workspace information file (.wif).

  4. Select one of the two radio buttons near the bottom of the Project tab to either include the project in the current workspace (this option is disabled if no workspace is open), or to create the project in a new workspace.
  5. If you want to change the name of any of the standard project directories, click the More Info button and make the desired changes in the Project Information dialog box.

    This dialog box is populated with information based on the project name that you have entered and the default project directory structure defined in the Tools > Options > Environment > Prefix interface. Information that you change in the Project Information dialog box applies only to the individual project. To make changes to the default directory structure established for any new project that you create, use the Tools > Options interface, as described in Prefix Options.

    In the top portion of the Project Information dialog box, you can change the name of the project and the project directory. In the middle portion of the dialog box, you can change the default location for each of the file types (source, screen, report, and so on) associated with an AcuBench project.

  6. If you want your project's object files to reside on a remote server, use the remote settings area of the Project Information dialog box to enter the server name, port number, and remote object directory for your project.

    You can use the Validate button (located at the upper right corner of the remote settings area) to determine whether AcuBench can make the remote connection. If the remote server is up and AcuConnect is running, the validation should succeed. If it does not succeed, you will receive one of the following error messages:

    • ACUCOBOL-GT cannot connect to servername. This may indicate, among other things, that the server name that you entered is invalid, that you do not have a network connection, or that the server is not listening on the specified port.
    • remotedirectoryname is invalid, or does not exist. This may indicate that the specified directory does not exist, that you are using incorrect directory syntax, or that you do not have permissions to access the directory.
  7. Click OK to create the project.

To add files and resources to your project, click the Add/Remove Files button on the Project toolbar. See Adding Files to a Project.

Note: By default, you do not open, close, and save individual projects. Every project is a member of a workspace, and it is the workspace that isopened, closed, and saved.

It is possible, however, to save information about a single project in a project file (.pjf). Just right-click the project icon and select Save Project - projectname. You can then move or copy the project to a new workspace using the File > Open Project command).

Parent topic: Working with Projects


Project Properties

A project's properties include its name, its location, and the names of its local and remote working directories. These properties are established when the project is created, and some of them, including the project's location, cannot be changed.

You can view the project's properties and change the project's name in the Project Properties dialog box. You can also establish settings to use with the AcuConnect Thin Client at the bottom of the dialog box's General tab. In addition to specifying a server, port, and remote object directory, you can also determine whether the thin client settings will apply at compile time, run time, or both.

The Project Properties dialog box also includes a Library tab that is used to specify the primary module and module type when you create an object library. For information about creating object libraries, see Library Settings, and The Object File Utility.

Note: For information about setting project compile, runtime, and environment options, see Project Settings.

To display project properties, right-click the desired project node in the Workspace window and select Properties from the pop-up menu.

You can rename a project as follows:

  1. Open the Project Properties dialog by right-clicking the desired project node and selecting Properties from the pop-up menu.
  2. Enter the new project name in the Project Name field and click OK.

Although the new project name appears in the Workspace window’s views, the name of the workspace project file (workspace_name.pjt) is not changed. If you have created an individual project file (project_name.pjf) for the project, the existing file is not affected by the change. The next time that you issue a Save Project command, you are given the option to change the name of the .pjf file.

Parent topic: Working with Projects


Adding Folders to a Project

You can add folders to the set of default project folders. Such folders can be used for any purpose that you choose.

Add a new folder using the following steps:

  1. In the workspace File view, right-click the project node that you want to add a folder to and select New Folder from the pop-up menu.

  2. Specify a name for the new folder in the Folder name field.
  3. Enter the file extensions that you want to associate with the folder in the File extensions field. For example, if you want a folder specifically for bitmap graphics and icons, enter *.bmp; *.ico in this field. You must enter a value. You can use “*.*” to indicate all file extensions.
  4. Specify a location where files associated with the folder will reside. Click the Browse button (“...”) to the right of the field to navigate the file system to select a location. If the specified location does not exist, it is created automatically. For example, to create a new physical folder for documentation files in the same location as your default project folders, your location specification might look like:
    c:\development\project1\documentation

    A new physical folder named documentation is created when you click OK to complete the dialog.

    Note: Note that only new files created in the workbench or files that you physically move to the folder are actually located there. When you add an existing file to the folder with the Add/Remove File function, AcuBench simply creates a logical link to the file.
  5. Enable the Show full path name check box to cause the full path name of files in this folder to display in the File view.
  6. Click OK to create the folder.
Parent topic: Working with Projects


Adding Files to a Project

Although you open, close, and save the workspace, you add files to and remove files from individual projects. The Add/Remove Files function is the vehicle for adding files to and removing files from a project.

CAUTION:
Because you can have multiple projects in the same workspace, there is the potential for inadvertently adding files to or removing files from the wrong project. Select the target project in the Workspace window before initiating the Add/Remove Files function. To select a project in the Workspace window, click the desired project node, or one of its subnodes, in any workspace view. Alternatively, you can select the target project in the insert into combo box at the bottom of the Add/Remove Files dialog.

The Add/Remove Files dialog has several tabs, one for each category of file type (by default: Source, Screen, Report, Copylib, Object, List, Resource, and FD).

This topic gives an overview of the steps involved in adding any file to a project. Specific information about adding source files to a project is provided in Adding an Existing Source File.

Note: To move a file from one project or folder to another project or folder, simply select it in the File view and drag it to the target folder. A similar cut-copy-and-paste function is not supported.

You can add a file to a project as follows:

  1. Right-click a folder in the File view and select Add/Remove Files. This opens the Add/Remove Files dialog with the tab appropriate to the selected folder in the foreground.

    You can also select the desired project in the Workspace window and click the Add/Remove Files icon on the Project toolbar, or select the Add/Remove Files option on the Project menu.

  2. Navigate to the folder containing the file to be added. A list of files that match the suffixes in the Files of type field is displayed in the Files list (top left).

    If the wrong file types are listed, use the Files of type drop-down box to select a different set of file extensions. The available file extensions reflect the file types associated with the project in the properties for each File view folder.

  3. Select the file to be added in the Files list. The file must be highlighted.

    To select multiple consecutive files, hold down the Shift key and click the files. To select multiple non-consecutive files, hold down the Ctrl key as you click.

  4. To add the selected file(s), click Add. To add all of the files in the specified directory, click Add all. The added files now appear in the Files in project list box.
  5. When you have finished adding files, click OK to close the Add/Remove Files dialog.
Parent topic: Working with Projects


Removing Files From a Project

You can remove files from a project with the Add/Remove Files dialog box. Note that although the files are removed from the project, they are not deleted from the disk.

CAUTION:
Because you can have multiple projects in the same workspace, there is the potential for inadvertently removing files from the wrong project. Always select the target project in the Workspace window before initiating the Add/Remove Files function.

The Add/Remove Files dialog box has several tabs, one for each category of file type (by default: Source, Screen, Report, Copylib, Object, List, Resource, and FD).

You can remove files from a project as follows:

  1. Select the desired project in the Workspace window and click the Add/Remove Files icon on the Project toolbar, or select the Add/Remove Files option on the Project menu. The Add/Remove Files dialog box is displayed.
  2. Click the tab that corresponds to the type of file to be removed.
  3. In the Files in project list, select the files to be removed and click the Remove button.

    You can quickly remove all of the files of a selected type by clicking the Remove All button.

  4. When you are done, click OK to accept the changes and close the dialog box. If you click Cancel, your changes are not recorded.
Note: You can quickly remove all of the files of a selected type by clickingthe Remove All button.

To empty a folder, right-click the folder that you want to remove all files from in the File tab of the Workspace window. Select Empty from the pop-up menu.

Parent topic: Working with Projects


Moving Components Among Projects and Folders

From within the Workspace window, you can easily move a program, screen, file, or data layout from one project or folder to another in the same workspace.

Moving a Program, Screen, Report, or Data Layout to Another Project

In the Workspace window, locate the project component to be moved and drag-and-drop it on the target project node. The component is placed in the appropriate area. If a component of the same name is already present in the target project, the item is not moved and a message is displayed.

Moving a File to Another Folder or Project

In the File view, locate the file to be moved and drag-and-drop it on the destination folder. The file is removed from the initial folder and placed in the target folder.

Note: The file is not physically moved; rather the logical link is simply changed. Also note that the workbench does not restrict the type of file that can be moved into another folder, nor does it generate a warning when the file type differs from the type that the target folder is designed to host. As a result, it is easy to move, intentionally or unintentionally, a file of one type into a folder meant for another type (for example, a source file into the Object folder).
Parent topic: Working with Projects


Deleting a Project

To delete a project from a workspace, right-click the project node in the Workspace window and select Delete from the pop-up menu. You can also select the project node and press the Delete key.

Parent topic: Working with Projects


Project Settings

  • Introduction
  • Modes
  • Compiler and Runtime Settings
  • Working with Runtime Configuration Files
  • Environment Settings
  • Library Settings
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

AcuBench provides an interface for specifying compiler, runtime, library, and environment settings at the project level. You can create multiple sets of settings and switch between them quickly and easily to change how programs in your projects are built and executed.

  • You can define distinct project option settings for each AcuBench project.
  • You can have individual compile options for any COBOL source file.
  • You can define sets of settings (modes) that enable you to quickly shift to settings that meet special needs, such as settings that support debugging work, or settings that build the program for 64-bit systems.
  • You can save modes that you create and load the saved modes into other projects.

You specify these settings in the Project Settings interface, which can be accessed in any of the following ways. First click a project icon in any Workspace window view, then:

  • Click Settings from the Project menu.
  • Click the Settings button on the Project toolbar.
  • Right-click the project icon and click Settings from the pop-up menu.

The Project Settings interface opens with the Compiler tab selected and the three other tabs (Runtime, Environment, and Library) in the background. All projects residing in the current workspace are listed in a tree view on the left side of the screen, and a field above the tabs indicates which project is currently selected. It is important to note which project you are working in, because settings created for one project in a workspace are not automatically transferred to other projects in the same workspace. All programs in a project, however, use the settings established at the project level unless you specifically define special settings for an individual program.

The Project Settings interface looks like this:

Parent topic: Project Settings


Modes

In , the term mode is used to refer to a set of project settings. Each project must have at least one mode and may have many modes. The ability to have multiple modes makes it easy to quickly switch from one set of compiler switches, for example, to another. This can provide a straightforward way for you to compare the effects of different compiler, runtime, and environment settings on program performance.

By default, AcuBench provides a Release mode, containing very simple compiler and runtime command lines and basic environment settings, and a Debug mode, which adds the -Ga compiler flag to include all available debugging information in the compiled object.

When you make changes to an existing mode or add a new mode in the Project Settings interface, the changes are saved in the workspace project file (.pjt) for the affected project. If you create an individual project file (.pjf), these settings are carried over to that file.

You can also store each mode in a project options file (.pof). Project options files and methods for creating them are discussed in Saving a Mode as a POF.

  • Working with Modes
  • Adding a Mode
  • Removing a Mode from a Project
  • Saving a Mode as a POF
  • Reusing a POF
  • Switching Between Modes
Parent topic: Project Settings


Working with Modes

In the Project Settings dialog box, above the tree view listing all of the projects in the current workspace, a Settings For drop-down list displays the current mode. If you have more than one mode defined for a project, or more than one project defined in a workspace, it is essential to make sure that you are working in the correct mode for the correct project.

Settings made to a mode in one project do not affect any other project, even if both projects have a mode with the same name. Likewise, changes made to one mode in a project do not affect any other mode in the same project.

Consider the following. You have a workspace containing two projects: MainPrj and Alternate. You have defined a custom Production mode for MainPrj and want to change the FILE_PREFIX setting for that mode. If you enter the Project Settings dialog box and click Production mode, but fail to notice that Alternate is selected as a project, when it comes time to execute a program in MainPrj, you will either receive a file error or access the wrong set of data files, because the FILE_PREFIX setting will be incorrect.

Parent topic: Modes


Adding a Mode

  1. In the Project Settings window, click a project in the tree view, then click the Add/Remove Mode button (to the right of the Settings For drop-down list, above the tree view list).

    This opens the Add/Remove Project Mode dialog box.

  2. Click Add. This opens the Add Project Mode dialog box.

  3. Enter a name for the new mode, then select one of the radio buttons in the Copy settings from area to determine which existing mode, if any, to use as the basis for the new mode.
    • To create a new mode based on the default settings established in the default.pof file, select Default settings.
    • To create a new mode based on another mode defined in this project, select Existing mode, then select a mode from the drop-down list.
    • To create a new mode based on an existing .pof file, select Existing .pof file, then click the browse (...) button to navigate to the location of the file on disk.

    POF files are discussed in Saving a Mode as a POF.

  4. Click OK, then click Close.

    This returns you to the Project Settings interface to begin entering settings for your new mode.

Parent topic: Modes


Removing a Mode from a Project

To remove a mode from a project:

  1. In the Project Settings window, click a project in the tree view, then click the Add/Remove Mode button (to the right of the Settings For drop-down list, above the tree view list).
  2. Click a mode in the Add/Remove Project Mode list, then click Remove.
  3. An AcuBench message asks you to confirm the removal of the mode. Click Yes.
  4. Click Close to return to the Project Settings interface.
Parent topic: Modes


Saving a Mode as a POF

A project options file (.pof) is a text file used to store project modes. Project modes currently in use in a project are stored in the workspace project file (.pjt) and updated every time you click OK to save your settings and exit the Project Settings interface.

Note that project options files are static. In other words, once you write options to a POF, those options are not automatically updated when you change the corresponding mode in the project from which the POF was created. To update the settings in a POF, you must explicitly save the changes to a file.

There are two ways to save a mode as a POF:

  • Click Save As to specify a file name and location for the new settings file. This file can later be used to add a new mode to any AcuBench project.
  • Click Save as default at the bottom of the Project Settings window to write your changes to a file called default.pof in the AcuBench installation directory. Every new project that you create will take its settings from this file.

    The mode saved in default.pof is always called Release, and it is always used to create a second default mode, called Debug, by adding the -Ga compiler flag to the existing compiler command line.

Parent topic: Modes


Reusing a POF

As discussed in To add a mode to a project, when you add a new mode to a project, you have the option to base that mode on an existing POF file, specified through the Add New Project Mode interface. This is one of two ways to make use of an existing POF.

When you are working in the Project Settings interface, you can click Reference to replace settings used in the current mode with settings from a POF. Although this changes the compiler, runtime, environment, and library settings for the mode that you have selected, the name of the mode stays the same.

Parent topic: Modes


Switching Between Modes

Once you have defined modes for your project, you can easily switch between them as you work in AcuBench. The Project toolbar lists all of the modes defined for projects in your workspace in a drop-down list.

To change the current mode, first select a project in any Workspace window view, then select a mode from the drop-down box. The next time that you compile or execute programs in the project, the new settings are used.

Parent topic: Modes


Compiler and Runtime Settings

Settings established on the Compiler tab of the Project Settings dialog box are, by default, applied to each program in the specified project at compile time. You can override these project-level settings at the individual program level, however.

Settings defined on the Runtime tab of the Project Settings dialog box are applied to each program in the specified project when the program is executed.

Both of these two tabs are constructed in a similar manner. A Catalog drop-down list at the top of the tab lists categories of options that you can modify. Each compiler catalog corresponds to a topic under Compiler and Runtime of the ACUCOBOL-GT User's Guide. Each of the options in the four run-time catalogs is also documented there, but because there are many fewer runtime options than compiler options, the documentation does not separate them into individual topics.

When you select a catalog, the compiler and runtime command-line options (also called switches or flags) that correspond to that catalog are displayed on the tab. For example, the --javaclass, --javamain, --netdll, and --netexe compiler options can be found on the Interoperability catalog of the Compiler tab, and the --wait and --restart runtime options can be found on the Thin Client catalog of the Runtime tab. In most cases, you can mark a check box or select a radio button to add a flag. Occasionally, an entry field or dialog box may also be associated with an option.

As you make changes to your settings, the corresponding runtime or compiler command line appears in the Project Options field at the bottom of the screen. This field is disabled, preventing you from making changes to this command line directly.

An Additional options field in the top, right corner of the Runtime and Compiler tabs allows you the option of entering command-line flags directly. While it is preferable, in most instances, to use the various catalog options to change your settings, it is sometimes necessary to use the Additional options field to invoke a switch has not been added to the AcuBench interface.

Text that you enter in the Additional options field is added to the command line in the Project Options field at the bottom of the screen as you type. This makes it possible for you to verify that the command line you are entering is correct.

Note: The -Po precompiler option was discontinued with the Version 8.0 AcuSQL. The Version 8.0 AcuBench strips the -Po if it is found in the project when it is being opened. If you are using Version 8 AcuBench with a pre-Version 8.0 compiler, you will need to add -Po back manually in the Additional options field.
Parent topic: Project Settings


Working with Runtime Configuration Files

AcuBench includes an integrated Configuration File Editor (CFE) that allows you to open and edit any Micro Focus runtime configuration file. With the CFE, you no longer need to access the host system's text editor to create new configuration files or modify a configuration variable.

The CFE provides a list of most of the available configuration variables, along with an interface that allows you to add your own user-defined variables. Both types of variables can be listed and modified within the CFE in the same manner. You can also press F1 when highlighting a variable to jump to the variable's help entry.

The CFE is accessed through the Runtime tab of the Project Settings interface. When the Common Options catalog is selected, the Alternate configuration file name (-c) option allows you to specify a configuration file that will be used when you execute programs in your project. Enter a path and file name here, then click the Edit button to launch the CFE.

When you enter a path to a configuration file that already exists, the CFE opens and parses the selected file, even if the file was not created in AcuBench.

Currently the CFE has one notable limitation. Although it can be used to add or remove a configuration variable, it cannot be used to comment out or uncomment a variable (place or remove a "#" in front of a variable).

  • Editing Configuration Files
  • User-defined Variables
Parent topic: Project Settings


Editing Configuration Files

When you edit a configuration file, the Configuration file entries list on the right side of the screen shows ACUCOBOL-GT configuration variables, organized by category. These categories include:

  • FileSystem, which includes operating system environment variables such as those relating to the default host, file names, or to the Vision file system.
  • GT, which lists ACUCOBOL-GT compiler-related configuration variables.
  • Licensing, which holds license management configuration variables.
  • Runtime, which includes runtime configuration variables.
  • User Defined, which lists other variables defined in the configuration file.

Variables to which a value has been assigned appear in the Editing entry drop-down list in the top, left portion of the screen. When you select an option from this list, the CFE highlights the variable name in the tree view along the left side of the interface and shows the value assigned to the variable in the Value list in the top, right portion of the screen.

To add or change the value of a configuration variable, do the following:

  1. Locate the variable in the interface using one of the following methods:
    • If a value has already been assigned to the variable, select the variable from the Editing entry drop-down list.
    • Navigate the tree view on the left side of the screen to locate the variable you want to edit.
    • Enter the configuration variable name or some portion of it in the Find entry field, then click Find or press Enter.

      Note that this find function searches from the beginning of the word only. This means that the string key can be used to search for the KEYBOARD and KEYSTROKE variables, but not for the HOT_KEY variable.

  2. Double-click in the Value area to change the variable’s value. The behavior of the Value field varies depending on the value that you have selected.
    • If the variable takes a directory path (or multiple paths) as its value, a browse (...) button will appear in the field. When you click this button, a dialog opens, allowing you to navigate to the path. This can help to prevent typing and syntax errors
    • With variables like KEYSTROKE, which can appear multiple times in a file, assigning unrelated values, multiple lines of entry are enabled in the Value column.
  3. If you want to associated a comment with the selected variable in your configuration file, click in the Comment field.

    Remember that while the editor allows you to add comments about existing variables, it does not provide a method for commenting or uncommenting the variables themselves.

  4. To remove a configuration variable from the configuration file, highlight the entry in the Value column, then press Delete. If you have previously assigned a comment to the variable, use the Delete or Backspace key to remove that, as well.

    Configuration variables that are not assigned a value are removed from the configuration file.

  5. To save your changes, click OK.

    Your changes are written to the specified text file.

Parent topic: Working with Runtime Configuration Files


User-defined Variables

In addition to the standard set of ACUCOBOL-GT configuration variables, the CFE allows you to add your own variables. If you are using multiple file systems, for example, to access data, you may need to add filename_HOST entries for various data files that your programs access. You might also want to define your own variables to help set user access privileges or otherwise adapt the behavior of your programs in different environments.

To add a new configuration variable to the CFE:

  1. In the Configuration file entries tree view, right-click the User Defined category and click New from the menu.
  2. Enter the variable name.
  3. Click in the Value column, then enter a value for your variable.

    If you have accidentally entered the name of a variable that has already been defined in this file, the existing variable value will appear in the Value list.

  4. To add a comment to the variable definition in the configuration file, click in the Comment box and add text.
  5. To delete a user-defined variable from both the configuration file and the Configuration file entries tree, right-click the variable name and click Delete.
  6. When you finish editing the file, click OK to save the entry and close the CFE.

    Once user-defined variables have been added, they are stored in the User Defined category in the Configuration file entries tree view. You can locate and edit them as you would pre-defined variables.

Parent topic: Working with Runtime Configuration Files


Environment Settings

The Environment tab of the Project Settings window is used to set the environment variables that apply to the selected project. You can view, add, modify, or delete environment variables in this interface.

Five environment variables are predefined by default. They are:

ACUPATH | Defines the path to the ACUCOBOL-GT executable files (for example, c:\Program Files\Micro Focus\extend x.x.x\AcuGT\bin).
CODE_PREFIX | Defines directories to search when a program name is specified without a full path. See Compiler and Runtime.
COMPILERNAME | Defines the name of the compiler executable file (by default, ccbl32.exe).
COPYPATH | Defines one or more paths that AcuBench searches to locate COBOL COPY files (see The COPYPATH Environment Variable).
RUNNAME | Defines the name of the runtime executable file (by default, wrun32.exe).

Other variables are added when AcuBench verifies that it can connect to a specified remote server and port:

THINNAME Defines the name of the thin client executable (by default, acuthin.exe).

As with the RUNNAME executable, the executable defined by THINNAME and the directory defined by CLASSPATHDIR must be located in ACUPATH.

CAUTION:
The value of variables defined in the Environment tab take precedence over the values of corresponding variables defined in the run-time configuration file. This is especially important to note if you have set CODE_PREFIX in your configuration file. For more information, see Introduction and Compiler and Runtime and Configuration Variables.
  • Working with Environment Variables
  • The COPYPATH Environment Variable
Parent topic: Project Settings


Working with Environment Variables

You can use the Environment tab of the Project Settings dialog to add, modify, and delete environment variables.

To add an environment variable for the current project:

  1. Click the New button in the top, right corner of the Environment tab. This is the first of the three available buttons.

    The Variable and Value fields below the Environment variables list are cleared.

  2. Enter a variable name in the Variable field.
  3. Enter a value in the Value field.
  4. Click the Set button. (Set is the third of the buttons in the top, right portion of the Environment tab.) The new environment variable is added to the list and the Variable and Value fields are cleared.

To change the value of an existing environment variable, select the variable in the Environment variables list, then make the necessary changes in the Value field. When you are finished, click Set to save your changes.

To remove an environment variable, select the variable from the Environment Variables list and click Delete (the second of the three buttons in the top, right portion of the Environment tab).

Parent topic: Environment Settings


The COPYPATH Environment Variable

The value of the environment variable COPYPATH is used by AcuBench (and the ACUCOBOL-GT compiler) to search for COBOL COPY files. When AcuBench (or the compiler) needs to access a COPY file, it searches, from first to last, the directories specified in COPYPATH.

You can define COPYPATH to specify one or more relative or absolute directory paths. By default, COPYPATH is set to the relative paths of the project's screen, COPY, resource, report, and FD folders (%screendir%, %copydir%, %resdir%, %reportdir%, and %layoutdir%). It also includes the absolute path of C:\Program Files\Micro Focus\extend x.x.x\AcuGT\sample\def), which contains the ACUCOBOL-GT .def COPY files supplied with your system.

Note: A copy of these .def COPY files can also be found in the default samples directory, which is %PUBLIC%\Documents\Micro Focus\extend x.x.x\sample.

You can change the value of COPYPATH in one of two ways:

  1. Use the Environment tab of the Project Settings dialog box.
  2. Add new paths as you add new source files to your project.

    The exact method by which new paths are added when you add source files to your project is determined by the settings that you have chosen in the Environment > Miscellaneous category of the Tools > Options dialog box, discussed in Customize Your Working Environment. If both Automatically modify COPYPATH options are selected:

    • When you add a new source file and select the Automatically parse program for COPY files option, COPYPATH is updated each time a new COPY file directory is identified.
    • When you use the Copy Path button in the Add/Remove Files dialog box to indicate a new COPY file location, that path is added to the COPYPATH definition.

Special Notes on Changing COPYPATH

  • Use caution when changing the value of COPYPATH. Changing the value of COPYPATH can potentially affect every source file in the project. For example, if you change the definition of COPYPATH to remove a path that holds a COPY file needed by the project, some files may no longer compile.
  • If you add a path that holds a COPY file that has the same name as a COPY file in another directory that is also defined in COPYPATH, the COPY file used is the first COPY file found (the paths are searched from first to last).
  • If you have a file or set of files that need a special COPY directory setting that you do not want to add to the definition of COPYPATH, you can specify that path on a file-by-file basis using the Directories to be searched for COPY (Sp) option in the Source Options catalog of the Project Settings dialog box.
Parent topic: Environment Settings


Library Settings

An object library is a file that contains a group of one or more compiled ACUCOBOL-GT programs and its associated resource files (such as bitmaps and WAV files). Ordinarily, if you wanted to create an object library, you would invoke cblutil, the object file utility (discussed in Working with ACUCOBOL-GT Utilities and Compiler and Runtime). If, however, you want to automatically create an object library every time you build a project, you can use the Library tab of the Project Settings window to define the modules of that library file.

To specify that you intend to build an object library at compile time, mark the Build as library check box. When you do this, all of the object files in your project are marked for addition to the library. You can add additional object files or libraries (residing in other projects or directories) in the Additional modules list. When you build the project, AcuBench invokes cblutil using the command line shown in the Library options field at the bottom of the Library tab.

Although the Library tab provides a method for changing the order of additional modules added to the object library from outside the project, it does not provide a means for ordering the modules within the project, nor for declaring a primary module. The process of declaring a primary module for the object library is performed in the Project Properties interface:

To specify a primary module:

  1. Right-click the project icon in the Workspace window and select Properties.
  2. In the Project Properties interface, select the Library tab.

    The Library tab lists all of the object files associated with the current project.

  3. In the Program File list, double-click an item to select it as the primary module. The item that you select is indicated by a check mark and added to the Primary library module derived from field.

    To change the item selected as the primary module, double-click another item in the Program File list.

  4. When you are finished, click OK to save your changes.

The changes that you make in this Project Properties interface are used to update the cblutil command line in the Project Settings interface. You can see this change in the Library options field at the bottom of the Library tab of the Project Settings window.

To retrieve information about an object file or object library in an AcuBench project, right-click the object in the File view and select Properties. The information shown here includes the file size and compile date, whether or not the object includes debugging symbols, and the names of any resources (like image files) included in the object. You can also view this information using cblutil, as described in ACUCOBOL-GT Utilities.

Parent topic: Project Settings


Working with Data at the Project Level

  • Introduction
  • Defining Data Files for Use in Projects and Programs
  • Creating Data Layout Files
  • Working in the File Designer
  • Copying DLT Files Between Projects
  • Tips for Working in the Data View
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

AcuBench includes a set of specialized tools for working with data files and user-defined items. These tools are designed to simplify the creation and maintenance of data-related program elements. Graphical user interfaces, many of which support drag-and-drop editing and syntax checking, make it easy to create, edit, and review data descriptions. At your direction, the information added to these interfaces is used to generate the related code. For an overview of code generation concepts, see Automatic Code Generation.

The data-related development tools are collectively referred to as the data design tools. The first tool, the File Designer, is accessed through the Data tab of the Workspace window and used at the project level to describe the structure of data files used in a project (and to generate FD, SL, SD, and XFD files, as well as file-handling code). The remaining three tools—the Data Set Designer, the Working Storage Editor, and the Linkage Editor—are accessed through the Structure view and used at the program level to define how an individual AcuBench program uses data.

This chapter discusses the process of using the File Designer to define data files for use by any program (or all programs) in an AcuBench project. The program-level data design tools are discussed in Working with Data at the Program Level.

Parent topic: Working with Data at the Project Level


Defining Data Files for Use in Projects and Programs

As described in Workbench Concepts, programs in AcuBench are organized into projects. A project is a group of interrelated programs, some or all of which may make use of a shared set of COPY files, resources, and data files. For this reason, when you set out to define data files for use by AcuBench programs, the first step is to create a definition at the project level.

The project-level definition for a data file is created in the File Designer, which is accessed through the Data view of the workspace.

This definition is stored in a data layout file, or DLT. The DLT contains information that AcuBench uses to generate SELECT, File Description, and Sort COPY files, as well as extended file descriptions (XFDs). These files can be used by any program within the project for which the DLT has been defined.

The DLT also contains information about whether and how to generate file handling code in those programs that make use of the data file. You can choose to use no generated file handling code, to use default generated code, or to use code paragraphs that you write and store in the DLT.

If you are working with multiple projects that share one or more data files, you need to define the data layout for each file only one time. Once the DLT has been created in one project, you can easily add it to other projects.

The process of defining data files for use at the project level is as follows:

  1. In the Workspace window’s Data view, use the File Designer to do one of the following:
    • Create a new data layout file from scratch (see Creating a DLT from Scratch.)
    • Create a new data layout file from existing File Description (FD) and SELECT COPY files (see Creating a DLT from a Single FDSL Pair and Creating DLTs from Multiple FDSL Pairs)
    • Open an existing data layout file, described in a different project
  2. Use the File Control, Definition, and Key tabs of the File Designer to create or update the FD, SELECT, and SORT definitions for the file (see Adding File Control Information, Adding a File Description, and Defining Key Information).
  3. Use the IO Handling tab of the File Designer to specify whether AcuBench should generate file handling code for the file (see Defining File Handling Behavior).

    This is also where you enter any custom file handling code that you would like AcuBench to associate with the data file and make available to any program that uses the file.

  4. Use the XFD tab of the File Designer to establish any XFD directives that you would like to include in an extended file descriptor (see Designing a Custom XFD).

  5. Close the File Designer, then generate new FD and SELECT COPY files from the new or revised data layout file. To do this, right-click the icon for your new DLT in the Data view and select Generate FD/SL from the pop-up menu.

    The COPY files are assigned a .fd and .sl extension and, by default, placed in the project’s FD folder.

Once you have generated your FD and SELECT COPY files, you are ready to define how individual programs in your project will access your data files. This is accomplished using the Data Set Designer, described in Using the Data Set Designer.

Parent topic: Working with Data at the Project Level


Creating Data Layout Files

There are two basic methods for creating a new data layout file:

  • You can start from scratch, defining your FD, SELECT, and other file information in a blank data layout.
  • You can create COPY files from you existing FD and SELECT statements and use these as the basis for creating a new data layout file. There are two tools that you can use to accomplish this: one for creating a single DLT, one for automating the process of creating multiple DLTs.

If you are starting from existing code but do not already have .fd and .sl COPY files, they are easily created by extracting the code from your program and placing the file description and SELECT statement code in separate files. The primary advantages of doing this are:

  • You can use the File Designer to maintain the file description and SELECT statement.
  • You can designate the .fd and .sl files as a data set for the program (via the Data Set Designer), which enhances the functionality of the Screen Designer and Report Composer interfaces and causes standard file handling code to be generated. For more information, see Using the Data Set Designer.
  • Creating a DLT from Scratch
  • Creating a DLT from a Single FD/SL Pair
  • Creating DLTs from Multiple FD/SL Pairs
Parent topic: Working with Data at the Project Level


Creating a DLT from Scratch

To create a brand new data layout file, do the following:

  1. Select New from the File menu and click the FD/SL tab or right-click the Project node in the Data view and select New FD/SL from the pop-up menu.

    The default FD/SL name, unique prefix, and location settings shown in the New interface are based on settings specified in the Tools > Options interface, under Environment > Prefix.

  2. Select the Blank icon to create a new data layout that will be used to create a new file description and new SELECT statement.
  3. In the FD/SL name field, enter a descriptive name for your data layout. This will be used as the base name for the new .fd and .sl COPY files generated by AcuBench.
  4. Specify a location for the new DLT. By default, the data layout and the FD and SL COPY files are all placed in the FD folder for the current project. If you specify a different location for the DLT, the FD and SL COPY files are still placed in the FD folder.
  5. If you do not want to add the new data layout to the current project, use the Add to existing project drop-down box to select another project.
  6. When you are finished, click OK to create the data layout and open it in the File Designer.

    You are now ready to define your data layout, as described in Working in the File Designer.

Parent topic: Creating Data Layout Files


Creating a DLT from a Single FD/SL Pair

If you have COPY files containing FD and SELECT information, you can use the files to create a data layout file, regardless of whether or not the COPY files were created by AcuBench. The COPY file containing FD information must have an .fd extension and the COPY file containing the SELECT statement must have an .sl extension.

The .fd and .sl COPY files that you use can reside on any local or mapped drive. If you use COPY files that do not reside in the current project directory, when you generate your project (or the DLT), the newly regenerated COPY files are placed in their original location and will overwrite any files of the same name located in that directory. The DLT, however, is created in the directory specified in the New FD/SL interface (by default, the project's FD directory).

  1. Select New from the File menu and click the FD/SL tab or right-click the Project node in the Data view and select New FD/SL from the pop-up menu.
  2. Select the Import from Files icon to specify that you have already defined an FD and SELECT statement that will be used to create a new data layout file.
  3. Enter a name and location for the data layout file, as described in the previous procedure.
  4. Click OK.

    The Import FD/SL Files dialog box opens, asking you to specify the location of the .fd and .sl COPY files that you want to use to create the new data layout.

  5. Enter the path to the COPY files, or use the browse button to the right of the entry fields to navigate to the directory containing each COPY file.
  6. Click OK to create the data layout and open it in the File Designer. You can now make changes to the data layout file, if needed, as described in Working in the File Designer.
Tip: To change the name of an existing DLT, right-click the icon for the DLT in the Data view and click Properties. This can be especially useful for the import function, because you enter a name for the DLT before specifying your FD and SL COPY files. Note that changing the name of the DLT does not affect the name of the generated FD and SL files.
Parent topic: Creating Data Layout Files


Creating DLTs from Multiple FD/SL Pairs

If you have several FD and SELECT COPY files that you would like to bring into AcuBench at the same time, there is an interface to help streamline this process. To use this process, your COPY files must have .fd and .sl extensions, and the COPY files must be added to the project before they are used to create a DLT. The process of adding the files to the project is included in the procedure that follows.

Note that although the COPY files must be added to the project, this can be done without changing their physical location on disk. You have the option to copy your .fd and .sl files into the AcuBench project directory structure, but this is not required.

It is important to remember that when you generate an AcuBench project or DLT, the new FD and SL COPY files created by the generate process are placed in whatever directory or directories held the original .fd and .sl files. If you do not want your original COPY files overwritten, it is a good idea to move a master copy to another location, or make a copy of the files within the AcuBench project directory.

The DLT file is placed in the directory specified in the Tools > Options interface, under Environment > Prefix. By default, this is the project's FD directory.

To add multiple .fd and .sl pairs to an AcuBench project, do the following:

  1. Place your .fd and .sl COPY files in a directory recognized by the Windows operating system. This may be the FD directory of the AcuBench project, another directory on your local hard drive, or a remote directory serving as a Windows mapped drive.

    Remember that when you generate a DLT, newly generated FD and SL COPY files will be placed in the directory or directories that you select in this step. If multiple developers will be using these COPY files, you may want to make the directory or directories read-only, to avoid having one person’s changes to a DLT affect everyone’s COPY files.

  2. In the Workspace window’s File view, right-click the FD folder and select Add/Remove Files.
  3. Navigate to the directory containing your COPY files, select the files you want to use, and click Add. Repeat this process for any additional directories containing .fd and .sl COPY files.

    When you are finished adding files, click OK.

  4. In the Data view, right-click the project icon and select Associate FD/SL Files.

  5. In the Associate FD/SL Files interface, click an FD file and its corresponding SL file, then click Associate. The pair is added to the Associated FD/SL Files list in the middle of the interface.
  6. Repeat this process until all of the COPY files have been associated, then click OK.

    All of the new DLT files appear listed in the Data View. AcuBench uses the base name of the .fd and .sl COPY files to create the DLT name. Section Working in the File Designer, describes how to make changes to a DLT, if needed.

Parent topic: Creating Data Layout Files


Working in the File Designer

The File Designer, accessed through the workspace's Data view, is used to create, view, and modify data layout files. The designer interface consists of five tabbed screens:

  • The File Control tab contains most of the information used to generate a SELECT statement.
  • The Definition tab contains the information used to generate a file description (FD).
  • The Key tab contains key information for the file (if applicable).
  • The IO Handling tab is used to determine which types of file handling code, including declaratives, are associated with a data file at the project level.
  • The XFD tab is used to add XFD directives and otherwise customize the XFD generated for a file (when needed).

To open the File Designer, you must either create a new data layout file (as described in Creating a DLT from Scratch through Creating DLTs from Multiple FDSL Pairs) or open an existing data layout file. To open an existing DLT, go to the Data view and double-click the DLT name. You can also right-click the project node and select Open data_layout_name from the pop-up menu.

  • Adding File Control Information
  • Adding a File Description
  • Defining Key Information
  • Defining File Handling Behavior
  • Designing a Custom XFD
Parent topic: Working with Data at the Project Level


Adding File Control Information

When the File Designer opens, the File Control tab is selected by default. This tab is used to construct most of the SELECT statement that will be generated into the associated .sl COPY file. (Key information is entered in a different File Designer tab). Selections made and information entered in this interface must conform to the ACUCOBOL-GT rules for a File-Control paragraph SELECT statement. See Environment Division for more information.

Use the File Control tab to view or edit the following information:

  1. The File name field displays the name of the current data layout file. The file name is established when you create a new data layout and cannot be changed here. To change the name, right-click the DLT in the Data view and select Properties.
  2. The Optional check box is used to indicate whether the SELECT statement should contain an OPTIONAL phrase. If this box is marked and a program invoking the data file cannot locate the file, a new, empty data file is created with the characteristics defined in the FD and SELECT.
  3. The Device and Name fields are used to create the ASSIGN TO phrase of the SELECT statement. First select a device from the drop-down list, then enter a file name or variable. If name is a literal, such as clientfile.dat, the file name must appear between quotation marks.
  4. Select a file format from the Format drop-down list. Other options in the File format area vary depending on the file format that you choose (NONE, Binary Sequential, Line Sequential, Relative, Indexed, or Sort).
    • If you have selected Relative format, the Key name field is enabled. Enter a name for the data item that will hold the value of the relative key.
    • Choose a value from the Access mode drop-down list to determine how the file will be accessed.
    • Select a value from the Lock mode drop-down list to determine what type of file locking is used with this file.
    • Enter a file status variable in the File status field. The value that you enter here is added to Working-Storage automatically.
  5. Add a comment in the Comment field, if desired.
  6. Click the Advanced button to add additional file control information, if needed. The options available in the Advanced dialog depend on the file format that you have specified, and the Advanced button is disabled when you specify a SORT file. The Advanced Options for Indexed File screen contains all of the possible options available on the Advanced interface. The interfaces for relative and sequential files contain a subset of these options:

    • If you want to enable encryption or compression, mark the With check box, then mark the Encryption and/or Compression check boxes. If you enable compression, you must also specify a compression factor.
    • To include the RESERVE phrase in your SELECT statement, mark the Reserve check box. You can then either select the No radio button or select the Number radio button and enter a number. Mark the Alternate check box to add an ALTERNATE AREA phrase.
    • To include a COLLATING phrase, mark the Collating check box, then enter the name of an alphabet declared in SPECIAL-NAMES in the Alphabet entry field.
To continue creating or editing your DLT, continue with Adding a File Description.
Parent topic: Working in the File Designer


Adding a File Description

The Definition screen is used to define the file’s record structure. Items entered here are used to create the FD generated into the .fd COPY file. Information entered in this interface must conform to the ACUCOBOL-GT rules for a file description entry. See for more information.Data Division.

Data items are added, removed, or modified in the Data item definition list. Note that you can copy and paste fields from another DLT or from a text file to build a file description in this interface.

To create or modify a file description, select the Definition tab and do the following:

  1. To add a field, click either the Add Item button or the graphical Add button (the only graphical button enabled when the Data item definition list is empty).

    The graphical Add icon looks like this:

    If you use the graphical Add button, a 01 level item is automatically created. If you use the Add Item button, you can select the level number of your first field, or use items from a COPY file. Linking and importing items from a COPY file is discussed in Linking and Importing COPY files.

  2. Double-click in the Field Name column to edit the default field name, as needed.
  3. Click or tab through the remaining columns of the field definition to add PIC, USAGE, VALUE, and other phrases, as needed.

    If you are adding an Occurs phrase, see Occurs Syntax Dialog for help navigating the Occurs interface.

    In addition to the basic field information defined in the first seven columns of the Data item definition list, you can click in the More column to further refine your field definition. These additional options are discussed in The Field Dialog.

  4. When you are ready to create the next field, you can use the Add Item button, the graphical Add, Add Sub-Item, or Add Item Before buttons.

    In most instances, if you create a field, then want to change its level number, you can double-click in the Level column and type a new value. If the value is not permitted, AcuBench displays an error message. In some instances, the field is read-only, and the level number cannot be changed.

    The default level number assigned to a new item or sub-item can be changed in the Data Designer section of the Tools > Options interface, under Graphical FD.

    Note that you can cut, copy and paste, or drag-and-drop items to make changes to a record.

  5. To delete an item, click the graphical Delete button. You can also delete all of your field definitions with the Delete All button.
  6. To specify additional definition information for the file, click the Advanced button.
    Option | Description
    Declared | This area lets you select file declaration options.
    External | Enable this check box to include the IS EXTERNAL phrase.
    Global | Enable this check box to include the IS GLOBAL phrase.
    Detailed attribute | This area lets you select file description entry phrases.
    Block Enable this check box to include the BLOCK CONTAINS phrase. Available only for sequential files.

    Enter the minimum and maximum block size in the entry fields to the right. Enable the appropriate radio button to specify physical record size in terms of either logical records or characters.

    Code-Set Enable this check box to include the CODE-SET phrase. Available only for sequential files.

    Enter the name of the desired SPECIAL-NAMES character set in the Name entry field.

    Label | Enable this check box to include the LABEL-RECORDS phrase. This phrase is ignored by the compiler.
    Linage Enable this check box to include the LINAGE phrase. Available only for sequential files.

    In the entry fields to the right, specify the number of lines on a page, the line number where the footing area begins on the page, and the numbers of lines in the top and bottom margins.

    Record Enable this check box to include the RECORD phrase.

    Specify the record size in the Record area to the right. Enable the Contain radio button to specify the size of a fixed- or variable-length record. Enable Varying in Size to specify the size of a variable-length record.

    Value of File-ID

    Enable this check box to include the

    VALUE-OF-FILE ID phrase.

    Enter the file’s external name in the Name entry field to the right.

    Value of label | Enable this check box to include the VALUE OF LABEL phrase. This phrase is ignored by the compiler.

    When you are finished entering File Definition Information, you can do one of the following:

    • If this DLT describes an indexed file, continue to Defining Key Information to define key information.
    • To determine what file handling code AcuBench can generate for this data layout, continue to Defining File Handling Behavior.
    • If you want to create a custom XFD for the data file, continue to Designing a Custom XFD.
    • If you are finished creating your data layout file, close the File Designer, then right-click the icon for your new DLT in the Data view and select Generate FD/SL from the pop-up menu. The information in your data layout file is now available to the programs in your project.
  • Linking and Importing COPY files
  • Occurs Syntax Dialog
  • The Field Dialog
Parent topic: Working in the File Designer


Linking and Importing COPY files

When you use the Add Item button to add fields to your FD, you have the option to link to or import an existing COPY file containing all or some of your field definitions.

The Link COPY File option creates a logical link to an existing COPY file. When you generate your FD and SELECT, a COPY statement is added to the FD to bring in the linked items. Information from the COPY file appears in colored text in the Data item definition area. If you link to multiple COPY files, the contents of each file appears in a different color. Linked items cannot be modified in the File Designer.

Alternatively, the Import COPY File option makes a copy of the items in the specified .fd file. There is no link or dependency on the imported file. Imported items appear in the default text color (usually black) and can be edited in the File Designer.

If part of your record definition includes a link to a COPY file and you want to instead import those fields, you can easily make the switch. To perform the conversion, select a field in the linked portion of the record and double-click in the More field. Click the button that is displayed. In the Field dialog that appears, enable the Convert Link to Import check box and click OK.

Parent topic: Adding a File Description


Occurs Syntax Dialog

If you want to specify an OCCURS clause for a field, you can either enter a number in the Occurs field or press the browse (...) button to open the Occurs Syntax dialog box. This dialog box contains graphical interfaces for constructing more complex OCCURS phrases.

The options available in this interface include:

Option | Description
Field name | Displays the field name of the selected item.
Occurs clause | Check this check box to include an OCCURS clause in the data definition.
Occurs | Lets you specify the type of OCCURS phrase.
Fixed | Select this radio button to use a fixed-size OCCURS phrase. Specify a positive integer value in the Size entry field.
Variable | Select this radio button to include a variable-sized OCCURS phrase. Specify a minimum size, maximum size, and DEPENDING ON variable in the adjacent fields.
Key | Check this check box to include the KEY IS phrase.
Available fields | Lists all of the items that can be specified in the Key list. Use the right arrow button to add an item to the Key list.
Key list | Lists all of the selected keys. Remove a selected item with the left arrow. Remove all items with the double-left arrow.
Order | Double-click an item's Order field to set ASCENDING or DESCENDING.
Order button | Opens the Modify Key Item Order dialog box, which allows you to change the order of the items in the Key list.
Indexed by | Check this check box to include the INDEXED BY phrase.
Index name | Type the name of the index and click the right arrow to place it on the Index list.
Index list | The list of index items. Remove a selected item with the left arrow. Remove all items with the double-left arrow.
Parent topic: Adding a File Description


The Field Dialog

To further refine your field definition, double-click the More column for the field. This opens a Field dialog box, which includes the following options:

Option | Description
Global | Check this check box to include the IS GLOBAL phrase.
Special Names | Click a special name type from the drop-down list to include the IS SPECIAL-NAMES phrase.
Sign | Click a sign position from the drop-down list to include the SIGN IS phrase.
Synchronize | Check this check box and click a position from the adjacent drop-down list to include the SYNCHRONIZED phrase.
Justified right | Check this check box to include the JUSTIFY RIGHT phrase.
Blank when zero | Check this check box to include the BLANK WHEN ZERO phrase.
Copy file | This section is enabled only if the selected item is part of a linked COPY file.
Convert Link to Import | Check this check box to convert from a linked COPY file to an import.
Name | Displays the name of the linked COPY file.
Comment | Type a comment in this field.
Parent topic: Adding a File Description


Defining Key Information

If you are creating a data layout for an indexed file, you can use the File Designer's Key tab to specify one or more keys. Rules for primary and alternate keys can be found in Environment Division.

All of the fields that you define in the Description tab appear in the Fields description list in the bottom, left portion of the interface. Use this list to build your key(s) as follows.

  1. In the Fields description list, double-click an item to add it to the Selected Fields list. You can also click an item (or Shift-click or Ctrl-click to select multiple items), then click the right arrow (>) to add them to the Selected Fields list. To add all fields to the list, click the >> button.

    All fields in the Selected Fields list when you create a new key are added to the key. If you have mistakenly added a field to the list, use the left arrow (<) button to remove it. To clear the Selected Fields list, use the << button.

  2. To add the fields in the Selected Fields list as a key, click the Add button (first in the set of four to the right of the Key list label). You can also right-click in the Key list area and select Add. The selected fields appear in the Key list.

    This two-step process for creating keys makes it easier to add split keys, constructed from multiple non-contiguous fields.

  3. To add or change a key name, double-click in the Key Name field and enter the name.
  4. To change key type (unique primary, primary allowing duplicates, unique alternate key, alternate key allowing duplicates), double-click in the Type field and select an option from the drop-down list.
  5. To insert a comment, click in the Comment field and then click the button that appears.

To change a key for an indexed file:

  1. In the Key list select the key that you want to change. Note that the key fields of the selected key are listed in the Selected Fields list.
  2. Add or subtract items from the Selected Fields list until you have the fields that you want.
  3. Change the key by clicking the Modify button (second in the set of four to the right of the Key list label).

To remove a key, select the key in the Key list, then click the Delete button (third in the set of four buttons to the right of the Key List label). To clear all of the key definitions and start again, use the Delete All button (the fourth button in the set).

When you are finished defining and editing key information, you can do any of the following:

  • To determine what file handling code AcuBench can generate for this data layout, continue to Defining File Handling Behavior.
  • To create a custom XFD for the data file, continue to Designing a Custom XFD.
  • If you are finished creating your data layout file, close the File Designer, then right-click the icon for your new DLT in the Data view and select Generate FD/SL from the pop-up menu. The information in your data layout file is now available to the programs in your project.
Parent topic: Working in the File Designer


Defining File Handling Behavior

The File Designer IO Handling tab allows you to assign I/O code and declaratives to a data layout file. This interface also lets you determine whether and how I/O paragraphs are generated by AcuBench.

To determine what file handling code, if any, AcuBench will generate, do the following:

  1. In the IO Paragraphs area of the screen, select one of the three radio buttons.
    • By default, Use Default Code Generation is selected. This causes AcuBench to generate default paragraphs for basic file operations, like OPEN, READ, WRITE, and so on.
    • If you want AcuBench to generate your own, custom file handling paragraphs for one or more file operations, select Use User-defined IO Paragraphs.
    • If you want to handle all file operations manually within your code, and do not want AcuBench to generate any I/O paragraphs, select Do Not Generate Any IO Paragraphs.
  2. If you have selected the first or third radio button, skip to the end of this section.

    If you have chosen to use user-defined I/O paragraphs, continue to step 3.

  3. In the User-defined IO Paragraphs list on the bottom portion of the screen, the File Designer displays a list of file operations for which AcuBench normally generates code. Double-click in the Value column next to any of these paragraph descriptions to add a new paragraph.

    You can also define your own new paragraph types. To do this, click the Add button (the third of the three buttons to the right of the User-defined IO Paragraphs label). Double-click in the Item column to enter a description of the paragraph type, then double-click in the Value column and continue with the next step.

  4. Enter a paragraph name. If you have already defined custom paragraphs in this DLT, they will appear listed when you expand the Value drop-down list.
  5. Click the browse (...) button to enter the Event Editor.
  6. Add code to your paragraph.
  7. When you are finished, you can either close the Event Editor to return to the IO Handling tab or select another paragraph type from the Message list at the top of the Event Editor window and create additional paragraphs.

To remove a paragraph that you have added for one of the default file operations, click the paragraph name, then click the Clear Paragraph button (the second of the three buttons to the right of the User-defined IO Paragraphs label).

If you have added your own paragraph type and want to remove both the new description and its associated paragraph, select the item and select Delete (the first of the three buttons to the right of the User-defined IO Paragraphs label).

When you are finished defining file handling behavior in this DLT, you can do either of the following:

  • To create a custom XFD for the data file, continue to Designing a Custom XFD.
  • If you are finished creating your data layout file, you can make the information in your data layout file available to the programs in your project.
Parent topic: Working in the File Designer


Designing a Custom XFD

The File Designer XFD tab lets you add XFD directives to your FD to design an extended file descriptor (XFD) for your data files. XFD files are commonly used to map fields in a record to columns in a table. If you are using AcuXDBC, for example, or reading or writing XML data with AcuXML, XFD files help map the data for translation between file formats. AcuBench can also make use of one XFD directive, the NAME directive, to make some of its Screen Designer and Report Composer interfaces more readable.

Regardless of whether or not you have made changes to this tab, you can create an XFD file for any data file described in an AcuBench data layout file.

General information about XFDs can be found in File Processing.

To add XFD directives to your FD, do the following:

  1. Select an item in the Field Name list on the left side of the interface.

    The options available on the right side of the interface are enabled or disabled depending on your selection.

  2. If you have selected the FD statement, the File Directive field is enabled. Enter a base name from which the XFD name will be formed. The default name is based on the ASSIGN TO clause of the SELECT statement.
  3. If you have selected a field in your FD, several fields are enabled. Which fields are enabled depends on whether or not the selected field is a group item. Use the information immediately following this procedure to assign directives to data items.
  4. When you finish adding XFD directives, close the File Designer, then right-click the icon for your new DLT in the Data view and select Generate FD/SL from the pop-up menu. The information in your data layout file is now available to the programs in your project.

    To view the FD (including the XFD directives that you have specified), you can right-click the icon for your DLT in the Data view and select View dlt-name.fd.

  5. To generate an XFD, right-click the data layout icon and select Make XFD File. The XFD is generated into the directory containing your FD, SL, and DLT files.

Name Directive

XFD NAME directives can be used to assign a name to a field in a file. This is often used to add a descriptive, formatted, or shortened name to a field, in order to create a more readable table. You can also elect to have alternate names specified with the NAME directive appear in the AcuBench Drag and Drop, Make Radio Button, and Autoload interfaces used to create screen and report controls. These names are then also used as the default title or label associated with the control.

To define a new name for a field, enter the name in the Name Directive field.

If you want the name specified by the NAME directive to appear in AcuBench interfaces:

  1. Open the Tools > Options interface and select the Screen Designer category.
  2. Mark the Apply XFD Names to Drag & Drop check box.
  3. Select the Report Writer category and mark the Apply XFD Names to Drag & Drop check box.
  4. Click OK to save your changes.

By default, data items in the Drag and Drop interface are listed using the field names defined in the file description. For more information about the Drag and Drop interface, see Drawing Controls with Drag-and-Drop, which pertains to screen design, and Using Drag-and-Drop, which discusses report design.

Use Group Directive

The USE GROUP directive allows you to enter a group item into the XFD as a single field, instead of using the elements contained in the group. This field is only enabled if you have selected a group item.

You can use the USE GROUP directive in conjunction with the NAME directive to assign a single name for the entire group.

Data Type Directive

When you mark the Data Type Directive check box, you can specify a format for the data item other than that established by the PICTURE clause. This means that you can have a database treat a numeric data item as alphanumeric, for example, or have a date item stored as numeric appear in a formatted date format. Select one of the following formats:

  • Alpha indicates that the selected fields should be treated as alphanumeric.
  • Binary specifies that the data in the field could be alphanumeric data of any classification. Absolutely any data is allowed.
  • Date marks the selected data field or group as a date. Enter the date format in the entry field to the right of the Date radio button.
  • Numeric treats the selected data item as an unsigned integer.
  • Var-Length designates the data item as having a variable length.

When Directive

The WHEN directive is used when you want to include multiple record definitions or REDEFINES in the XFD file. When you mark the corresponding check box, a field is enabled, allowing you to enter WHEN directive syntax. Click the ellipsis button to display the Expression Builder dialog, where you can also construct WHEN directive syntax.

You can use the Table Name field to add an optional tablename clause to the WHEN directive. If you assign a table name, the data that immediately follows the WHEN directive and meets the specified condition will be considered as a separate table.

Comment Directive

You can use COMMENT directives to include comments in your XFD field. Mark the Comment Directive check box, then enter a comment in the associated entry field.

Parent topic: Working in the File Designer


Copying DLT Files Between Projects

Once you have created a data layout file in one project, you can quickly and easily add that DLT to any other AcuBench project, whether or not the other project resides in the same workspace as the original project. It is important, however, to understand the distinction between sharing a DLT between projects and copying a DLT into multiple projects.

When you add a data layout file to a project, you generate new FD and SL files from that DLT. These are generated into the FD folder for the current project, so that if your projects reside in different directories, each has its own set of FD and SL COPY files. The original DLT file, however, is not moved from its original location. This means that if you create a DLT in one project, then add it from another project without making a copy of the original DLT, both projects point to the same file on disk. In this case, if you make a change to the DLT in either project, that change is reflected in both projects.

To open a data layout file defined in a different project:

  1. In the Data view, right-click the project node and select Add FD/SL from the pop-up menu.
  2. In the Add Data Layout to Project window, navigate to the location of the existing DLT. Select the file and click Open.
  3. Expand the project node (if necessary) and right-click the DLT name to generate new FD and SL COPY files for the project. This makes the information in your data layout available to programs in your project.
Parent topic: Working with Data at the Project Level


Tips for Working in the Data View

When you add an existing AcuBench program to a new project, or copy a program from one project to another, it is a good idea to verify that any DLT files referenced by the program exist within the project before you attempt to generate the program. Any time a program contains data set definitions, you will need the data layout file and its associated FD and SL COPY files to successfully generate and compile that program.

If you generate a program before all of the DLT files that it needs have been added to the project, AcuBench identifies missing, required data fields and adds them to Working-Storage. Later, when you add the missing DLT to the project, you will receive errors caused by the duplicate field names. This can be solved by deleting the duplicate names from Working-Storage, but it's preferable to avoid the problem altogether.

  • Useful Data View Functions
  • Data Layout Properties
Parent topic: Working with Data at the Project Level


Useful Data View Functions

When you right-click a DLT icon in the Data view, the pop-up menu that appears provides shortcuts to a number of useful functions.

Viewing FD and SL COPY Files

You can open and view the FD and SL COPY files generated from the DLT with the View base-name.fd and View base-name.sl options, or open the File Designer to view the selected DLT using the Open dlt-name option.

File Handling Code and the Event Editor

When you use the IO Handling tab to define file handling code associated with a DLT, that code is edited in the Event Editor. If you are working in the Structure view, however, your file handling code does not appear when you open the Event Paragraph. To edit or add to your file handling code, right-click a DLT in the Data view and select Event Editor.

When you launch the interface in this way, the name of the DLT that you have selected appears in the Control field at the top of the Event Editor window, and the IO handling paragraphs associated with the DLT appear in the Message field. In addition, any file handling paragraphs that you have already created appear in the editor window.

Note that when you use this method to open the Event Editor, code that you have added to the Event Paragraph through the Structure view is hidden.

Creating a New XFD

You can create an extended file descriptor (XFD) from a DLT at any time. Just right-click the DLT and select Make XFD File. AcuBench invokes the ACUCOBOL-GT compiler in the background to create an XFD for the specified file. The XFD is placed in the project’s FD directory.

Refreshing the DLT

If you have made a change to an FD or SL COPY file, you can add that change to the DLT. This option is especially useful if you have created the DLT from your own .fd and .sl COPY files and are accustomed to maintaining these files outside of AcuBench.

Parent topic: Tips for Working in the Data View


Data Layout Properties

To change the name or unique prefix associated with a DLT, right-click the DLT name and select Properties.

The Data Layout Properties dialog box also lists the name of the data file associated with the file definition, as well as the path and filename for the DLT file and its FD and SL COPY files. This can be especially useful when you are working with shared DLT or FD/SL COPY files to verify that you are working with the correct version of the correct file. Once the DLT has been created, these paths cannot be changed.

Parent topic: Tips for Working in the Data View


Working with Programs

  • Introduction
  • Creating an AcuBench Program
  • Adding and Creating Basic Source Files
  • Generating a Program
  • Compiling a Program
  • Executing a Local Program
  • Executing a Remote Program
  • Debugging a Program
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

AcuBench projects can contain two kinds of programs. AcuBench programs have a program structure file and appear in the Structure view of the Workspace window. This type of program contains AcuBench-generated code. Non-AcuBench programs appear as source files, COPY files, and object code only in the File view of the Workspace window. The AcuBench code generator does not generate any code for these programs.

Parent topic: Working with Programs


Creating an AcuBench Program

In AcuBench, creating a program means creating a program structure file. For more information, see Programs. After the program structure file is created, you generate to create a program source file (.cbl). The source file can then be modified to include those parts of the program that are not generated by AcuBench

This topic describes the process of creating a new AcuBench program.

To add an existing program to a project and in the process create a program structure file, see Creating a PSF for an Existing Program.

To add an existing source file without creating a program structure file, see Adding an Existing Source File.

To create a new source file without creating a program structure file, see Creating a File.

Create a new program as follows:

  1. Select New from the File menu and click the Program tab. You can also right-click the project node in the Structure view and select New Program.

  2. Select a program template.

    The Standard Program template includes code for a standard graphical screen.

    The Blank template does not include a screen.

  3. Enter the name of the new program in the Program name field.

    The read-only File name field is updated to show the name of the program structure file that will be created for your new program.

  4. Enter a location for the program structure file (PSF) in the Location field. To browse for a directory path, click the button to the right of the field.

    By default, the new program structure file is placed in the base directory for the current project.

  5. If you want an existing source file to be associated with a new program, enter the file name in the Base Source File entry field or click the browse button to navigate to the file you want to use. The selected source file is renamed to that shown in the Program Name entry field and copied into the source directory of the current project. AcuBench program tags are generated when the program is added to the project. Although program tags are added to the source file, a run-mainscr tag is not generated. You need to create a main screen and the code to call that screen.
  6. Select the project to which the new program will be added (this field is set to the current project, by default).
  7. Click OK.

You should note that when an existing source file is selected in the New > Program dialog, the Code Generation options in its Program > Properties area are selected, and the Regenerate tagged area only selection in the Tools > Options > Code Generator > Generate Document dialog should be cleared. Ensure that any automatic code generation capabilities that you don’t want are disabled.

If CRT STATUS is declared in your existing source file template, you should ensure that the Do Not Generate CRT STATUS variable in .wrk check box in the Program Properties dialog is set.

  • Adding an AcuBench Program to a Project
  • AcuBench Program Properties
Parent topic: Working with Programs


Adding an AcuBench Program to a Project

When you add an existing AcuBench program to a project, you are actually adding only the existing program structure file (PSF) to the project. The COBOL source file (.cbl) and associated COPY files are not added. In addition, adding a PSF to a project creates a pointer, or logical association, between the project and the PSF. It does not move or copy the PSF from its current location into the project directory.

As a result, when you add an existing PSF to a project, consider the following:

  • If you have one PSF file in a central location, and that PSF is added to multiple projects, changes made to the program in one project will overwrite changes made to the PSF in another project. In most cases, you should copy a PSF into your project directory before adding it to a project.
  • If you have manually added code to the COBOL source file associated with a PSF and want to preserve this code in the new project, you must copy the existing .cbl file into the Source folder (or equivalent) for the new project.
  • If you have manually added code to the .cbl file associated with a PSF and do not want that code to appear in your new project, do not copy the .cbl file. In this instance, the PSF acts as a sort of program template from which you can build a new program.

To add a program structure file to a project, use these steps:

  1. In the Structure view of the Workspace window, right-click the project to which you want to add the program and select Add Program from the pop-up menu. The Add Program to Project dialog is displayed.
  2. In the dialog, locate and specify the name of the program structure file that you want to add and click OK.
  3. To add the associated program file (.cbl), use the Add/Remove function.

To add a plain source file, use the Add/Remove Files function described in Adding an Existing Source File.

Parent topic: Creating an AcuBench Program


AcuBench Program Properties

Programs have a variety of properties, including several that specify how code is generated for the program. These properties are set in the Program Properties dialog, which opens when you right-click the program node in the Workspace window Structure view and select Properties from the pop-up menu.

The Program Properties dialog has four tabs: General, Output Files, Key Status, and Code Generation. The General tab includes options for changing the program name, specifying a logo (splash) screen, and assigning an icon to the program, among other properties. The Output Files tab displays the names of the files that are automatically generated for the program and their last modification date (you can control the set of files that are generated for all projects in the workspace in the Tools > Options > Code Generation dialog). The Key Status tab is used to define the program’s CRT STATUS variables. The Code Generation tab lets you define the code generation characteristics of a program. These settings override the workspace level settings when that program code is generated, unless the Follow project default options check box is set. Detailed descriptions of each tab and their options are given in the next section.

A program options file (.prf) stores default settings for a standard program, shown on the Program Properties Key Status and Code Generation tabs. These settings can be saved as default, saved as another file, or loaded from an existing options file with the Reference function.

To set program properties:

  1. Right-click the program node in the Structure view of the Workspace window and select Properties from the pop-up menu.
  2. Review and set values in each tab of the Program Properties dialog.
  3. When you are finished, click OK to accept the settings and close the dialog.

General Properties

Option | Description
Program name | Specifies the program name. Use this field to change the program name whenever necessary.
On program startup, set logo screen to: | Specifies the name of the screen to display as a splash screen when the program first starts. If a screen is specified in this field, when you generate the program, AcuBench includes a DISPLAYstatement in the ACU-INITIAL-ROUTINE of the .prd COPY file.
Display Time | Specifies the amount of time, in seconds, that the logo screen appears on the screen before the main application window is displayed. Takes a value between 1 and 300.
On program startup, setmain screen to: | Specifies the name of the program’s main screen. All screens that appear in the Structure view for the program are listed; the first screen created in or added to the program is selected by default. AcuBench adds a DISPLAY statement for the selected screen to the ACU-INITIAL-ROUTINE of the .prd COPY file.
Icon File | Specifies the name of the icon file to be displayed in the upper-left corner of the main window. If a bitmap file is specified in this field, AcuBench includes code to load and display the bitmap in the ACU-INITIAL-ROUTINE of the .prd COPY file.
Description | Text entered in this field is placed in the REMARKS section of the program source file (.cbl) between the *{Bench} prgid tags.
Prompt when program exits | Enable this check box to cause the program to prompt for confirmation when the program is closed with the window’s close button (in the window’s upper right corner). AcuBench generates support code in the program’s .prd COPY file.
Set as initial program | Enable this check box to designate the program as the main (initial) program.

Output Files Properties

Option | Description
File name | Displays the name of the program file.
Generated output files: | Lists the names of all files generated by AcuBench for the program. Click an entry to display the last modification date (the last time the file was generated).

Key Status Properties

The Key Status tab is used to define or import CRT STATUS variables. CRT STATUS items are generated into the program’s .wrk COPY file when the program is generated. Variables defined here are visible to the Screen Designer and other workbench facilities.

Option | Description
Field Name (entry field) | Enter the name of the CRT STATUS variable. This name is used in the name IS SPECIAL-NAMES CRT STATUS ... statement that is generated in the .wrk COPY file. It is also used in the EVALUATE statements (WHEN name = exception_value) generated in the .prd COPY file. This field must contain a value, even if you set the Do not generate... check box. The name is set to Key-Status by default.
Pic (entry field) | Lets you enter the PICTURE description of the Key-Status variable. Pic9(4) is the default value.
Usage (entry field) | Lets you select a USAGE format from a drop-down list.
Import (button) | Imports level-88 CRT STATUS variables from an existing program. Pressing this button opens a dialog box that lets you locate and select the file containing the variables that you want to import. Note that when you import existing variables from the program’s source so that they can be generated into the .wrk COPY file, you should later comment out or remove the CRT STATUS variable declarations in the program source so as to eliminate duplicates.
Insert (button) | Displays a dialog for defining a new CRT STATUS item.
Delete (button) | Deletes the selected CRT STATUS item.
Select all (button) | Causes all items on the CRT STATUS list to be selected.
CRT STATUS variable list | Lists all of the currently defined CRT STATUS items. Double-click on any item in the list to edit that item.
Do not generate CRT STATUS variable in .wrk file | Activate the associated check box to disable the generation of CRT STATUS variables in the program’s Working Storage (.wrk) COPY file.

Code Generation Properties

The Code Generation tab has the same options as the Tools > Options > Code Generator > Generate Document dialog, and it prefills with the defaults that are set in the Tools > Options interface. See Generate Document Options for more information about these default settings. If you change any setting in the Code Generation tab after clearing the Follow project default options check box, that setting overrides the corresponding Tools > Options setting for that individual program. Setting the Follow project default options check box directs AcuBench to use the settings in the Tools > Options > Generate Document dialog. In the latter case, the remaining options on the Code Generation tab are disabled.

Code generation properties also include the following options not included in the Tools > Options interface:

Option | Description
Generate source format | This section lets you determine the format for your source file.
ANSI source format | Enable this radio button to have your source file generated in ANSI source format.
terminal source format | Enable this radio button to have your source file generated in terminal source format.
Parent topic: Creating an AcuBench Program


Adding and Creating Basic Source Files

AcuBench provides an interface through which you can add existing source or COPY files to a project or create text-based files of any type. This makes it easy to include new or existing source files that do not include a program structure file in your project. It also provides a way for you to associate notes or code skeletons to a project for reference or documentation purposes.

  • Creating a File
  • Adding an Existing Source File
  • Adding COPY Files
  • Working with Files in the File View
  • File Properties
  • Reparsing Source Files
Parent topic: Working with Programs


Creating a File

You can create a source file or plain text file from the File menu as follows:

  1. Select New from the File menu and click the File tab, or right-click any folder in the File view of the Workspace window and select the New File option. In the latter case, the default file name that appears in the New dialog is automatically given the file extension associated with the selected folder (.scr for a screen file, for example).

    No matter how you access the New dialog, you are provided with the option of using either of two default templates. If you have added custom templates in the Tools > Options > Environment > Template interface, discussed in Template Options, these are also listed here.

  2. Select a file template.

    The Source Template includes standard COBOL divisions and sections.

    The Blank Text template is completely empty.

  3. Specify a name for the new file. If you used the File > New command to open the New dialog, the default extension is .cbl.
  4. Specify a location for the new file. If you used the File > New command to open the New dialog, the default location is the Source directory for the current project. If you used a File view right-click menu to open the dialog, the default location is the folder on which you right-clicked.
  5. Determine whether the file should be added to the current project, another project in the current workspace, or a new project. By default, Add to existing project is selected.
  6. To add AcuBench tags to the new file and create a program structure file, mark the box next to Create Program Structure File (.PSF).
  7. When you are finished making changes to the dialog, click OK to create the new file.
Parent topic: Adding and Creating Basic Source Files


Adding an Existing Source File

When you add COBOL source files to the project, you have the option of directing AcuBench to automatically search for and add all COPY files named in the source code. To do this, enable the Automatically parse program for COPY files check box for each source file being added that you want parsed. After you click OK, AcuBench parses the program, identifying COPY files and searching the directories specified in the COPYPATH environment variable to locate them on disk. AcuBench then adds these COPY files to the project, listing the file names in the project’s File view Copylib folder. The physical files remain in their original location on disk.

Note: To move a file from one project or folder to another project or folder, simply select it in the File view and drag it to the target folder. A similar cut-copy-and-paste function is not supported.

You can add a source file to a project as follows:

  1. Select the desired project and click the Add/Remove Files button on the Project toolbar, or select the Add/Remove Files option on the Project menu. You can also right-click the project’s Source folder in the File view and select Add/Remove Files.

    This opens the Add/Remove Files dialog with the Source tab selected.

  2. Verify that the Files of type field, at the bottom of the uppermost frame in the dialog, shows the correct type of file to be added. Because you are adding a source file, the default extensions are .cbl and .cob (unless you have established custom settings for the project).
  3. From the Drives drop-down list, select the drive on which the file is located.

    You can also use the Network button to map a network drive on which your source files are located.

  4. In the tree view (above the Drives list, top right), navigate the file system until you open the folder that contains the file to be added.
  5. Select the file to be added in the Files list. The file must be highlighted.

    To select multiple, non-consecutive files, hold down the Ctrl key and click each of the files that you want to select.

  6. To add the selected file or files, click Add. To add all of the files in the specified directory, click Add all. The added files now appear in the Files in project list box.
  7. To have AcuBench parse the file to automatically add all referenced COPY files to the project, mark the Automatically parse program for COPY files check box and modify the COPYPATH environment variable, if necessary. See Adding COPY Files for more information.

    Parsing is performed after you finish adding files and click OK to close the dialog.

  8. When you have finished adding files, click OK to close the Add/Remove Files dialog.

    The new source file(s) and their associated COPY files (if applicable) are now visible in the File view, and you can use the compiler and runtime settings that you have established for the project to compile and execute the programs. You can also use the Code Editor to view and make changes to your code.

Parent topic: Adding and Creating Basic Source Files


Adding COPY Files

Typically, COPY library files are automatically added to your project when you add source files to the project. To ensure that this happens, make sure that the Automatically parse program for COPY files check box is enabled when you add a source file, as described in the previous section.

When AcuBench performs its parsing, it searches for COPY files in the directories defined in the COPYPATH environment variable. Any change to the definition of COPYPATH can affect whether a COPY file is found. A procedure for changing the COPYPATH definition is found in the following subsection.

After AcuBench has finished a successful parse, any COPY files that it finds are added to the project’s File view Copylib folder. You can reparse a source file at any time by right-clicking the source file icon (in the File view) and selecting Reparse from the pop-up menu.

Adding or removing COPYPATH directories

By default, COPYPATH is set to the relative paths of the project’s screen, COPY, resource, and layout (FD) folders, as well as the absolute path to the ACUCOBOL-GT sample directory and its .def (COPY files) folder (C:\Program Files\Micro Focus\extend x.x.x\AcuGT\sample\def, for example).

To redefine COPYPATH to include other directories, do one of the following:

  • If you are working in the Add/Remove Files dialog, click the Copy Path button.

    1. Navigate to the desired directory in the Directory list box and then click Add. The new path is added to the list of currently defined directories in the Default copy path(s) list.
    2. Repeat this procedure for every directory that you want to add to COPYPATH.
    3. When you are done, click OK. The Add Copy Path dialog is closed, returning you to the Add/Remove Files dialog.
    4. You can remove a path from COPYPATH by selecting the path from the Default copy path(s) list and clicking Remove.
  • If you are not currently working in the Add/Remove Files dialog, you can change the COPYPATH settings for the project in the Project Settings interface. Select the Environment tab, then follow the steps outlined in Working with Environment Variables.
CAUTION:
Any change to the COPYPATH definition affects every file in the project. If a directory is removed from the COPYPATH definition and a program in the project has a COPY file located in that directory, that program will fail to compile.
Parent topic: Adding and Creating Basic Source Files


Working with Files in the File View

When you work with files in the File view of the Workspace window, you do not have the option of using AcuBench's code-generating tools, but you can perform typical File menu functions like opening, closing, saving, and deleting files. In addition, you can compile source files (in the project's File view Source folder) and execute object files (in the project's File view Object folder)

Opening a File

To open any file associated with an AcuBench project, go to the File tab of the Workspace window and right-click the file you want to open, then select Open.

Saving a File

To save the contents of the file that has focus, select Save filename from the File drop-down menu. Filename is the name of the file that has current focus. To give another open file focus, either click the window containing the file or select the file from the Window drop-down menu.

To save the file to another name, select Save As from the File drop-down menu and specify a name. If no file extension is specified, the first extension listed in the Save as type field is appended automatically.

Closing a File

To close the file that has current focus, select Close from the File drop-down menu or click the Close icon button located at the far right of the main menu bar.

Deleting a File

To remove a file from a project, right-click the file and select Delete filename from the pop-up menu (filename is the name of the selected file). Although the file no longer appears in any Workspace Window view, it is not removed from its location on disk.

To remove a file from the project and delete it from disk, right-click the file and select Delete From Disk from the pop-up menu. The file is moved to the Windows Recycle Bin.

Parent topic: Adding and Creating Basic Source Files


File Properties

Files that belong to an AcuBench project have three basic properties: file name, file type, and last modification timestamp. If the file is a program source file, it has a list of output files and a COPY file list. If the file is a remote object file, the dialog box contains information about the remote file.

To view file properties, in the Workspace window's File view, right-click the file of interest and click Properties from the pop-up menu.

Option | Description
File name | Displays the full path and name of the file.
File type | Displays the file type.
Last modified | Displays the file's most recent modification timestamp.

Additional fields for source files (not displayed for remote files):

Option | Description
Output Files tab | Lists the name of the compiled object file.
Copy Files tab | Lists all of the COPY files referenced in the file.
Parent topic: Adding and Creating Basic Source Files


Reparsing Source Files

When a source file is added to a project, you can direct AcuBench to parse the source file to identify and add all COPY files referenced by the program to the current project. In the course of development, you may make changes to the source file that introduce new COPY files. When this is true, you should reparse your source file so that the new COPY files are added to the project and found during compilation.

To reparse a file, right-click the desired source file in the Workspace window’s File view, and select Reparse from the pop-up menu. When reparsing is complete, a confirmation message is displayed in the Output window.

To reparse all source files in the workspace, select Reparse All from the Build drop-down menu. As the reparsing process proceeds, status messages are displayed in the Output window.

Note: AcuBench uses the directories named in the COPYPATH environment variable to look for COPY files. Directories are searched in the order defined (first to last). If the -Sp compile option is set on the file, the directories associated with the option are searched to locate COPY files. The value of COPYPATH is ignored. To check or set the -Sp option, right-click the file and select Program Compile Options from the pop-up menu. Select Source Options from the catalog drop-down list and locate the option labeled Directories to search for COPY.
Parent topic: Adding and Creating Basic Source Files


Generating a Program

If a program is displayed in the Structure view of the Workspace window (meaning that it has a program structure file) and you are using workbench tools or options that directly or indirectly specify code (such as the Screen Designer or options in the Program Properties dialog box), you need to generate code for the program before you compile the program. Several settings affect what files are created and what code is generated. For a complete discussion of code generation and programming, see Automatic Code Generation.

To generate code for a program, right-click the program in the Structure view of the Workspace window and select Generate Source from the pop-up menu. Status and error messages are displayed in the Output window.

Parent topic: Working with Programs


Compiling a Program

To compile a single, local program, select a program node in the Structure view of the Workspace window, or select a source file from the Source folder in the File view, then right-click and select Compile. You can also use the Compile button on the toolbar, the Ctrl+F7 keyboard shortcut, or the Build menu’s Compile option.

The compile action applies the file-level or project-level settings established in the Project Settings dialog box. The compiler command line and any error messages or warnings are displayed in the AcuBench output window.

--------- Compiling Program1.cbl ----------
--------- Compile options = -o .\object\@.acu -x -Ga
Program1.acu - Completed: 0 Error(s), 0 Warning(s).

After compiling, the compiled object is added to the Object folder in the File view of the Workspace window. You can right-click the File view icon associated with an object file and click Properties to retrieve information about the object. This information includes the compiler version, the file size and compile date, whether or not the object includes debugging symbols, and the names of any resources (like image files) included in the object. You can also view this information using cblutil, as described in Working with ACUCOBOL-GT Utilities.

  • Compiling Programs to a Server
  • Compiling Multiple Programs
  • Remote Precompiling with Boomerang
Parent topic: Working with Programs


Compiling Programs to a Server

If you are using AcuConnect or AcuServer, you can have AcuBench copy an object file to the server after compiling. There are two ways to do this:

  • With the thin client implementation of AcuConnect and the Use Thin Client toggle button.
  • With AcuServer or the distributed processing implementation of AcuConnect and the Use Remote Compile toggle button.

Just as there are two methods for placing the object file on the server, there are two ways to specify a remote destination for a compiled object: the Project Properties interface and the Project Settings interface. Settings that you specify in the Project Properties interface are automatically picked up by the Project Settings interface, but the reverse is not true. This means that if you use certain remote settings for testing and a different set of remote settings for production, you can specify the most commonly used set of options in the Project Properties interface, then create a special mode in the Project Settings interface for the less frequently used case.

To use the Project Properties interface to specify remote compiler settings:

  1. Right-click the project node in any Workspace window view and select Properties.
  2. Provide the server name and port on which your AcuConnect or AcuServer listener resides.
  3. Specify the directory in which the compiled object(s) should be placed.
  4. Mark the appropriate check box next to Apply to to indicate whether the settings you have provided should be used at compile time, execution time, or both. Note that execution options only apply if you are using the AcuConnect Thin Client.
  5. Click Test to verify the connection, then click OK to save your changes. The next time you compile a program in the project for which you have specified remote compiler settings, the object will be placed on the remote server.

To use the Project Settings interface to specify compiler settings for a specific project mode (or for an individual source file):

  1. Expand the Build menu and mark either the Use Thin Client or the Use Remote Compile toggle button.
  2. Right-click the project node in any Workspace window view and select Settings.
  3. Select the project mode that you want to modify, then select the project or program to which you want to apply the remote settings.
  4. In the Standard Options catalog of the Compiler tab in the Project Settings window, enter server, port, and remote directory information.
  5. When you are finished, click OK to save your settings.

    The next time you compile a program using this mode, the compiled object is placed in the specified server location.

When you use any remote compile option, the object file is listed in the Remote Object folder in the File view. Just as with local object files, you can right-click the object file icon in the File view and click Properties to retrieve information about the compiled object.

Parent topic: Compiling a Program


Compiling Multiple Programs

To compile all of the programs in a workspace, expand the Build menu and select either Build Workspace (F7) or Rebuild Workspace. The Build Workspace option compiles only those programs that have changed since the last compile operation. Rebuild Workspace compiles every program in the workspace, regardless of whether or not it has changed since the last compile.

If you are using AcuBench code generation, you can use the Tools > Options interface to specify that the Build and Rebuild operations also generate (or regenerate) the programs in the workspace before compiling. To change your Build/Rebuild options, expand the Environment tree and click Build.

Note that if you are using remote compile options, you may want to use the Build or Rebuild command twice, once to create local object files and once to create remote object files.

Parent topic: Compiling a Program


Remote Precompiling with Boomerang

If you have set up and configured Boomerang on a remote server, you can take advantage of an AcuBench interface to the Boomerang client utility. The Boomerang utility sends source files to a remote server for preprocessing, then returns the precompiled source to the local machine for compiling.

For detailed information about the Boomerang utility, including server setup and configuration, see Debugger and Utilities.

To access the Boomerang utility from within AcuBench:

  1. Open the Project Settings interface, select the Compiler tab, and open the Pre-compiler Options catalog.
  2. Mark the check box next to Generic or Boomerang Precompiler (-Pg), then click Browse to open the Add Precompile Commands interface.

  3. Select the Boomerang tab, then click the Add (“+”) button.
  4. Use the fields on the tab to enter server, port, and alias information.

    Note that you can specify multiple local and remote precompiler command lines, as needed. The updated precompiler command line appears in the Precompile Commands-Arguments field near the top of the Add Precompile Commands window.

  5. If you have added multiple precompiler command lines, you can use the arrow keys to determine the order that the commands will be passed through the compiler.
  6. When you are finished, click OK to save your changes. The Project Options field at the bottom of the Compiler tab lists the updated compiler command line. Note that you must click OK to close the Project Settings window and save your changes. If you click Cancel, any changes to your precompiler settings are lost.

Note that status and any error messages are returned to the output window.

Parent topic: Compiling a Program


Executing a Local Program

In the Workspace window, right-click the program name, program source file, or program object file and select Execute. If you have enabled the Allow Parameters option in the Build menu or Project toolbar, this opens the Execute with Parameters dialog box to allow you to specify program parameters.

You can use the Parameters combo box to enter your command line parameters or expand the box to see and select from a list of previously used parameters. The combo box holds up to twenty previous command lines.

Parent topic: Working with Programs


Executing a Remote Program

If you have established remote settings for your project in order to compile to and run from a remote server using the AcuConnect Thin Client, you can execute your remote programs as follows.

  1. Verify that the Use Thin Client option is selected: expand the Build menu or look at the Project toolbar to see that the Use Thin Client button is in pressed position.
  2. Select the program that you want to execute and select Execute from the Build menu. You can also right-click the program and select the Execute command from the pop-up menu, or use the Ctrl + F5 keyboard shortcut.
  3. If this is the first time that you have executed the program since your last build, the Create Alias Entry dialog box will appear.

    AcuBench pre-fills the dialog box with a default alias name and working directory.

    The dialog box also displays server and port information, taken from the Project Properties dialog box, and an execution command line, taken from the Thin Client Options set on the Runtime tab of the Project Settings window. This information cannot be changed in this interface.

    When you are finished making changes, click Create to update the server alias file and execute the program.

Parent topic: Working with Programs


Debugging a Program

To start a program in the workbench integrated debugger, select the program in the Workspace window and select Go from the Debug drop-down menu. For a complete description of the integrated debugger, see The AcuBench Integrated Debugger.

To use the ACUCOBOL-GT runtime debugger, select the Build/Debug (Runtime) command or right-click the program node in the Workspace window File view and select Debug (Runtime). The runtime debugger is described in detail in Debugger and Utilities of the ACUCOBOLGT User's Guide.

  • Debugging with the Thin Client
  • Debugging a Transaction Processing (TP) Application
Parent topic: Working with Programs


Debugging with the Thin Client

If you are using the AcuConnect Thin Client, you can use the AcuBench integrated debugger or the runtime debugger to debug a program running on the server.

To debug a remote program using the thin client:

  1. Verify your thin client settings on the Runtime tab of the Project Settings window (in the Thin Client Options catalog), then click OK to close the Project Settings interface.
  2. Expand the Build menu and select the Use Thin Client command.
  3. Start the integrated debugger (Debug/Go) or the runtime debugger (Build/Debug Runtime). If you have not yet created an alias file entry for the program to be debugged, you are prompted to do so via the Create Alias Entry dialog described in The AcuBench Integrated Debugger.
  4. Step through the program as usual.
Parent topic: Debugging a Program


Debugging a Transaction Processing (TP) Application

You can use AcuBench to prepare for debugging in a transaction processing environment, as long as this capability is supported by the vendor of that environment. (See your vendor's documentation for details.) You must have ACUCOBOL-GT's Thin Client technology installed on the local Windows client and AcuConnect running on the server.

You use a special acuthin parameter, wait, to start an acuthin process on your local machine and have it wait for instructions to open a debugging window. The program executes as initiated through the transaction management environment, not AcuBench. AcuBench provides an interface for enabling this acuthin behavior, but does not otherwise interact with the debugging process.

For more information about using the acuthin --wait option for debugging, see Terminal Manager and Working with Transaction Processing Systems.

To debug a transaction processing application:

  1. Expand the Tools menu and select Thin Client (--wait). This opens the Thin Client (--wait) window.

  2. In the Port field underAdd new AcuThin (--wait), specify the port where AcuConnect is listening. AcuConnect needs to have been configured to communicate with clients over this port.
  3. Select the (--restart) checkbox if you want the thin client to restart itself after each debug session. If a transaction requires multiple COBOL programs to run, this allows you to debug them all. You might want to do this if you have pseudo-conversational transactions, for example, where COBOL programs repeatedly complete and then restart. In this case, you would want acuthin to continually restart as well.
  4. Click Start to start an acuthin process on the client. The thin client waits for the transaction server to start the runtime.
    Note: On UNIX servers, you must set the environment variable A_DEBUG_USING_THIN to a non-zero numeric value before the transaction server can start the runtime with debugging via the thin client. No additional environment settings are required for Windows servers.
  5. A runtime debugger screen automatically appears. Debug your application with all the usual runtime debugger options.
  6. When you are finished with your debugging session, stop the currently running acuthin process (the one in the wait state) by selecting the process and clicking Stop.

For more information about using the acuthin --wait option for debugging, see see Terminal Manager and Working with Transaction Processing Systems.

Parent topic: Debugging a Program


Working with Data at the Program Level

  • Introduction
  • Using the Data Set Designer
  • Using the Working-Storage and Linkage Editors
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

Chapter Working with Data at the Project Level introduced the concept of the data layout file, used to describe data files at the project level for the purpose of generating, among other things, file descriptions, SELECT statements, and file handling code. This chapter discusses ways to define data for use at the program level, using the three graphical interfaces: the Data Set Designer, the Working Storage Editor, and the Linkage Editor.

The Data Set Designer is a tool that determines how a data file will be accessed by a given program, and what information from the corresponding data layout file (DLT) will be used by the program. Data sets created with this designer contain a variety of information, including the file open mode, what form of locking to use, and whether AcuBench should generate the code for file operations (such as READ and WRITE).

The Working Storage and Linkage Editors provide graphical tools that you can use to add Working-Storage and Linkage data items to your program. In addition, when you create certain screen and report items in the graphical designers, AcuBench automatically adds needed data items (such as handles) to Working-Storage and displays these in the Working Storage Editor.

Parent topic: Working with Data at the Program Level


Using the Data Set Designer

The Data Set Designer allows you to identify a set of data files to be used by a program (data sets are associated with programs). Before a data set can be defined, the data files themselves must be defined using the File Designer. When you create a data set, you select from the set of data layout files that are associated with the project.

There are four benefits to creating data sets for your program:

  1. The components of each data set are made visible to the Screen and Report Designers. This means that when you want to specify a data item in a control variable, you can select a data file field name from the list of program variables (under the name of the data set).
  2. When you generate code, AcuBench generates a set of standard file handling paragraphs for each data set. These paragraphs include OPEN, READ, WRITE, and REWRITE.
  3. Via the Event tab of the Data Set Designer's Property window, you can launch the Event Editor to develop BEFORE and AFTER procedures for the data set's associated OPEN, READ, WRITE, and REWRITE routines.
  4. You can create associations between fields in data sets such that the field of one data set is marked as related to a field in a second data set. When you do this and generate code for the program, a standard reference routine is generated that performs a MOVE of the value of the first data item into the referenced (second) data item.

The following sections describe some basic Data Set Designer operations.

  • Creating a Data Set
  • Opening an Existing Data Set
  • Creating a BEFORE or AFTER Procedure
  • The Data Set's Property Window
  • Generating File Handling Code
Parent topic: Working with Data at the Program Level


Creating a Data Set

Define data for use with an individual program in a project as follows:

  1. In the Structure view of the Workspace window, open the desired Program node and right-click the Data Set node (note that data sets are defined for programs, not projects). Click New Data Set from the menu.

    A Data Set Designer window is opened with a new data set icon.

  2. Display the Property window by clicking View > Property Window.
  3. In the Property window, specify a descriptive name for the data set in the Name field, then use the Data Layout drop-down list to select the DLT associated with this data set.

    It is best to assign a data set name that is different from your data layout name. If your data layout name is clients, for example, you might call your data set clients-ds. Both the data layout name and the data set name appear in the Event Editor's Message drop-down list, so assigning different names helps to prevent confusion.

  4. If a primary key has been defined in the selected DLT, this value appears in the Key drop-down list. If multiple keys have been defined in the DLT, you can expand the list and select a different key.

    Because each data set represents a specific manner in which a data file will be used by your program, a DLT with multiple keys may be associated with multiple data sets. In other words, if you have defined more than one key for a file in your DLT, you can define one data set for each key that the program will use to perform file operations.

  5. To create an association between a field in the current data set and a field in a different data set, click in the Value column of the Referenced Data Set field and then click the browse (...) button that appears. The Set Reference-Field dialog is displayed.

    Select a data set from the list on the left, then click the right-arrow icon to move the data set name to the list on the right. If the default reference field is not correct, click in the Reference Field column and select the correct field from the drop-down list.

    This generates a paragraph similar to the following that you can perform as needed:

    Acu-cl-ds-Ref-pet-ds.
    INITIALIZE pet-record OF pets
    MOVE cl-client-id OF clients TO pet-owner-id OF pets
    PERFORM Acu-pet-ds-Read.

    When you are finished, click OK.

  6. Right-click in the Data Set Designer window and click Referenced FD/SL Files to open the Data Set Member Files interface. For information about this interface, see Generating File Handling Code.

    Here, you can determine whether or not AcuBench will generate OPEN code for each data file associated with a data set in your program. You can also determine an open mode (Input, I/O, Extend, or Output), specify a locking mode, and determine what data handling code will be generated within this program.

    By default, the type of file handling code that AcuBench generates is based on the open mode that you select. If you select Output mode, for example, AcuBench's default behavior is to generate WRITE code but not READ code. Expand the IO Operation drop-down list for each file to select or de-select code paragraphs to be generated.

    When you are finished, click OK.

  7. Use the Property window's Event tab to specify or create (via the Event Editor) BEFORE and AFTER procedures as needed for each file handling operation (DELETE, READ, REWRITE, or WRITE) associated with the data set.
  8. When you are finished, generate the program.

    The file handling code that you have specified is generated, and the data items described in the data layout file are made available to the other AcuBench design interfaces (for use, for example, with tools like the Screen Designer and Report Composer Drag-and-Drop interface).

Parent topic: Using the Data Set Designer


Opening an Existing Data Set

You can open an existing data set in the Data Set Designer as follows:

  1. In the Structure view of the Workspace window, open the desired Program node, then expand its Data Set node to see a list of available data sets.

  2. Double-click either the Data Set node or any of the listed data sets. The Data Set Designer opens, showing an icon for each data set.
  3. Select the desired data set icon.
  4. Display the Property window by selecting Property Window from the View menu.
  5. View or modify the data set’s properties as desired.
Parent topic: Using the Data Set Designer


Creating a BEFORE or AFTER Procedure

You can use the AcuBench Event Editor to code BEFORE and AFTER procedures for file operations. By default, this code is generated in the program's .evt COPY file.

To add code to be executed before or after file operations on a particular file, do the following:

  1. In the Structure view of the Workspace window, open the desired Program node and double-click the Data Set node. The Data Set Designer window opens, showing an icon for each data set.
  2. Select the desired data set, then click the Event tab of the Property window.

    If the Property window is not visible, select Property Window from the View menu, or click the Property Window button on the Standard toolbar.

  3. In the Event tab, locate the type of procedure that you want to add in the Item list and click in the adjacent Value field. If you have already written the paragraph that you would like invoked before or after the selected file operation, select that paragraph from the Value drop-down list. Otherwise, click the browse (...) button, accept or modify the name in the Add Paragraph dialog, and click OK.

    The program’s .evt file is opened in the Event Editor and a new paragraph is inserted. Code the rest of the procedure.

    Procedures that you enter here are performed immediately before or after the associated AcuBench file handling paragraph is executed. A Before Read paragraph, for example, is performed immediately before the Acu-datasetname-Read (or Read-Next or Read-Prev) paragraph, each time the latter paragraph is invoked.

  4. When you are finished coding a BEFORE or AFTER paragraph, you can close the Event Editor to return to the Data Set Designer. If you are planning to add more BEFORE and AFTER code, you can select another paragraph type from the Message drop-down list at the top of the design window and continue adding code.
Parent topic: Using the Data Set Designer


The Data Set's Property Window

The Data Set's Property window is used to define the essential values for the data set. This Property window has the following options:

Option | Description
The drop-down list | Select a data set name from the drop-down list at the top of the window to set that data set’s values.
Alphabetic tab
  • This tab lists the data set's properties in alphabetical order.
  • (Name) Enter or modify the name for the data set in this field.
  • Key Select a key for the data layout from the drop-down list.
  • Referenced Data Set Click in the Value field and then on the ellipsis button to open the Set Reference-Field dialog (described in step 5 of Creating a Data Set).
Categorized tab | This tab presents the same options as the Alphabetic tab, but they are grouped into categories.
Event tab This tab is the access path to the Event Editor.
  • Item list - The list of BEFORE and AFTER procedures that are typical for a data set
  • Value - The name of the actual BEFORE or AFTER procedure for this item. To launch the Event Editor, select a procedure from the list, click in the Value field, and click the ellipsis button that appears.
Parent topic: Using the Data Set Designer


Generating File Handling Code

When you create a data set in the Data Set Designer, you determine what sort of file handling code AcuBench will generate in a given program. As you work with your program, you can change what code will be generated in the Data Set Member Files dialog box. The Data Set Member Files dialog box lists all of the data sets defined for a program, as well as information about the file handling code currently specified for each data set.

To open this dialog, go to the workspace Structure view, open the desired Program node, right-click the Data Set node, and select the Referenced FD/SL Files command.

To change the OPEN code generated for the file, do any of the following:

  • In the Open Option portion of the dialog, mark the check box next to the data file name in the Open column to have AcuBench generate OPEN code for the file. If this check box is marked, an Acu-Open-file paragraph is generated, by default, into the .prd COPY file. Remove the check mark to stop generating this code paragraph. If the box is not marked, changing other open option details for the data set has no effect.
  • the Exclusive column, mark the check box to indicate that a file can only be opened by one program at a time.
  • In the Mode column, select an open mode (INPUT, OUTPUT, EXTEND, I/O). The default mode is I/O.
  • In the Locking column, select a lock mode from the drop-down list. The default locking mode is None.

To change the I/O handling code generated for a file, do the following:

  • In the IO Option portion of the dialog, click a file’s I/O Operation field, then expand the drop-down list.

    The list shows all of the file operations that can be performed on the file, based on the open mode selected in the top portion of the screen.

    Note that this list is populated based on the file handling operations defined in the file’s DLT. This means that if you selected the Do not generate any IO Paragraphs radio button on the I/O Handling tab of the File Designer, nothing will appear in the I/O Operation field.

  • Mark the check box next to an I/O function to have AcuBench generates a paragraph to perform the selected function. Remove the check mark to cause AcuBench to stop generating code for performing the selected operation.
Parent topic: Using the Data Set Designer


Using the Working-Storage and Linkage Editors

The Working-Storage Editor and Linkage Editor each provide a specialized interface for defining and maintaining Working-Storage and Linkage section data items. Though these are separate editors, they have identical user interfaces (similar to the File Designer's Definition tab). Therefore, they are documented together here.

  • The Working-Storage Editor
  • The Linkage Editor
  • The Working-Storage and Linkage Editor Interface
Parent topic: Working with Data at the Program Level


The Working-Storage Editor

The Working-Storage Editor is an interactive, graphical editor for defining and maintaining data items that are local to the program and not components of a data file (that is, Working-Storage items). Use the Working-Storage Editor to add, remove, or modify Working-Storage items. Items defined in this editor are generated into the program's .wrk COPY file (program.wrk), as are Working-Storage items needed by screen controls and other screen elements. Note that the entire contents of the program's Working-Storage COPY file are recreated by AcuBench every time the program is generated. You should never modify the .wrk file directly.

When you add screens, reports, screen controls, and report controls in the Screen Designer and Report Composer interfaces, and when you add a data set to a program, AcuBench generates supporting data items and structures, as needed, into the Working-Storage Section. These items may include handles, value variables, file status variables, and so on.

Each Working-Storage item that AcuBench generates is added to the graphical editor. This means that you can modify or delete the generated variables items. Be aware, however, that changing an AcuBench-generated data item in the Working Storage Editor does not automatically update the corresponding Screen Designer or Report Composer property, so you should exercise caution when making such changes.

Parent topic: Using the Working-Storage and Linkage Editors


The Linkage Editor

The Linkage Editor is an interactive, graphical editor for defining data items that are passed from a calling program (that is, Linkage items). Use the Linkage Editor to add, modify, or remove Linkage section data items. Items defined in this editor are generated into the program's .lnk COPY file (program.lnk). The entire contents of the .lnk file are recreated by AcuBench every time the program is generated. Never directly modify the file.

Parent topic: Using the Working-Storage and Linkage Editors


The Working-Storage and Linkage Editor Interface

To open the Working Storage or Linkage editor, go to the workspace Structure view, open the desired Program node, right-click the Working-Storage or Linkage node, and select Open from the pop-up menu.

The Data Description Entry buttons (from right to left, Delete, Delete All, Add Item Before, Add, Add Sub-item, and Add Item) have the exact same function as the corresponding buttons on the Definition tab of the File Designer. In fact, each of the columns in the Working Storage and Linkage Editor interfaces exactly corresponds to a column in the Data item definition list on the Definition tab. Moreover, the Link COPY File and Import COPY File options function the same in both interfaces, and the Occurs Syntax and More dialog boxes are the same. For information, then, about adding data items to the Working Storage and Linkage Editors, see Adding a File Description.

Parent topic: Using the Working-Storage and Linkage Editors


Configuring the Code Editor

  • Introduction
  • Establishing Keyboard Shortcuts
  • Customizing the Code Editor Interface
  • Setting Print Layout Options
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

The Code Editor is a highly configurable tool, intended to make working with code as straightforward and comfortable as possible for the COBOL developer. In order to make the tool work for you, you can establish your own keyboard shortcuts for any Code Editor function, change the appearance of the editor, and configure the behavior of various editor functions. For the most part, this configuration is accomplished through the Tools > Options interface, although some settings are configured in other parts of the workbench.

Parent topic: Configuring the Code Editor


Establishing Keyboard Shortcuts

In the Tools > Options interface, under Environment > Keyboard, you can set up keyboard shortcuts that affect all aspects of the AcuBench interface. You can also set up specific keyboard shortcuts for the Code Editor interface.

To add, remove, or change a keyboard shortcut associated with a Code Editor function:

  1. Expand the Tools menu and select Options.
  2. Expand the Environment tree and select Keyboard.
  3. Open the Category drop-down list and select Code Editor.

    The list of commands shows only those functions specific to the Code Editor, as well as the keyboard shortcut (if any) currently assigned to each function.

    Note that in some cases, a common function (like Copy or Paste) will appear to have no associated keyboard shortcut. In these cases, the command is associated with a shortcut at the Main level. Shortcuts defined at the Main level apply across the workbench, unless overridden by a shortcut assigned in a specific context.

  4. Select a function in the list, then click in the Shortcut key entry field.

    If a keyboard shortcut is currently assigned to the selected function, this shortcut appears in the field. In most cases, a description of the function appears under the Assign and Remove push buttons.

  5. On the keyboard, type the combination of keys that you want to assign to the selected function. The key combination appears in the entry field.

    Note the Currently assigned to field under the entry field. If you enter a keystroke that has already been assigned to another function, this field displays the name of that function.

  6. To assign the keystroke that you have specified to the function that you have selected, click Assign. The new keyboard shortcut appears next to the function name.
  7. To remove a keyboard shortcut that has already been assigned to a function, select the function in the Command list, then click Remove.
Parent topic: Configuring the Code Editor


Customizing the Code Editor Interface

The first four sub-items under Code Editor in the Tools > Options interface provide a way for you to customize the general appearance and behavior of the Code Editor.

  • Configuring Basic Editor Functions
  • Modifying Editor Appearance
  • Customizing Tab Stops
  • Configuring Keyword Behaviors
Parent topic: Configuring the Code Editor


Configuring Basic Editor Functions

Configure basic Code Editor functionality in the General interface: the width of the line number pane, the line length associated with text in the Code Editor, the end of line character, and the behavior of the editor's vertical block select function.

You can choose to display a line number pane to the right of the Code Editor window. The number of digits that can be displayed in this pane depend on the pane width. To modify the width of the line number pane from the default (4), enter a new value (from 1 to 6) in the Line number pane width text box.

By default, the Code Editor sets the basic line length for editor text at 318 columns. In most cases, if Code Editor text is pasted into another text editor, any trailing spaces are stripped from each line. Some editors, however, preserve the extra spaces, which can lead to line wrapping issues or other undesirable behavior.

To change the default Code Editor line length, enter a value up to 2048 in the Line Length entry field. Note that if you open an existing file that contains lines longer than the new limit that you have specified, AcuBench shows a warning message, then wraps any long lines to the new length.

As a Windows editor, the Code Editor's default behavior is to set the end-of-line marker in your files to an ASCII carriage return/linefeed (CR/LF) character. If you plan to save your file in a UNIX environment, you may want to set your end-of-line marker to an ASCII linefeed (LF) character. To toggle between these two end-of-line markers, mark either the Save Record Delimiter as CR/LF or the Save Record Delimiter as LF option.

The Virtual Space option affects two different aspects of the editor. When the Virtual Space check box is not checked and you use the vertical block select function, as described in Working with Blocks of Code, the column is always precisely the width of the last line in the text block. In addition, lines of text created in the editor are not padded with spaces to the line length indicated in the Line length field.

When Virtual Space is checked (the default), you have more flexibility in determining the width of a column selected with the vertical block select function. In addition, all lines in your file are padded with spaces, as needed, to reach the line length indicated in the Line length field.

The HOME key goes to column 1 option controls the behavior of the HOME key whilst the cursor is positioned in the Code Editor. When it is not checked (the default), using the HOME key toggles between column 1 and the first non-space character of the current line. When the option is checked, the HOME key positions the cursor on column 1 of the current line only.

Parent topic: Customizing the Code Editor Interface


Modifying Editor Appearance

The appearance of the Code Editor window, including the appearance of the text in the window, is configured in the Code Editor > Format section of the Tools > Options interface. This interface allows you to specify two sets of appearance options: one for files opened in terminal format and one for files opened in ANSI format. Note that this interface determines only display characteristics for the different file formats; it doesn't affect the format of any file.

As you make changes, a small window near the bottom of the Tools > Options interface shows your changes. Use the scroll bar at the bottom of the window to see changes to the Identification Area.

To begin editing Code Editor appearance settings, open the Source format drop-down list at the top of the screen and select either ANSI Format or Terminal Format. Note that the remaining options on the page change depending on which format you have selected.

Modify Code Option

If you are configuring the ANSI format settings, you can elect to have the Code Editor insert a specified character string in columns 73–80 when a line of code is added or modified.

Note that inserting the specified string is the only task performed by the Modify Code function. Once the string has been placed in columns 73–80, the Code Editor does not maintain the string. This means that if the length of the source line changes, for example, the original modification marker may slip out of the identification area.

Preserve contents of Identification Area

If you are configuring the ANSI format settings, you can elect to preserve the contents of the Identification area. When the Preserve contents of the Identification Area check box is checked, existing text in this area is unaffected by editing in other areas.

Color Options

By default, when an ANSI format file is opened in the Code Editor, the Indicator Area, Area A, and the Identification Area are each assigned a different background color. In addition, comments are shown in green text, reserved words are shown in blue, literal strings are shown in red, and all other text is shown in black. You can disable all color functions or you can change the default color settings.

To disable all color functions, clear the Enable foreground and background color settings check box.

To change the default color settings, do the following:

  1. Select an ANSI code area (Sequence Number Area, Indicator Area, Area A, Area B, or Identification Area) or text type (Comment, Keyword, String, Number, or Text) from the list box.
  2. The Background field displays the current background color associated with the selected item. To change this color, expand the drop-down list and select a color from the list.

    To select a color not on the list, select User-defined. This opens a color palette dialog window. You can either select a color in the default palette or click Define Custom Colors. When you have made your selection, click OK.

  3. If it is possible to associate a foreground color with the selected item, the Foreground list is enabled. Repeat the process used in the previous step to select a foreground color.
  4. If you have selected an ANSI code area, you can change the column width of any area in the Column fields. Note that if you change a column setting, you are simply redefining the size of the background color display. You are not redefining any particular area (for example, area A) for the compiler. Columns may not overlap.

Font Options

By default, text displayed in the Code Editor appears in the Courier New typeface, with a size of 10 points. To change the display font, click the Font button. The Font dialog box appears.

Select the font, style, and size that you want, then click OK. Once you have clicked OK again to close the Options dialog, your text appears in the Code Editor in the new font.

Parent topic: Customizing the Code Editor Interface


Customizing Tab Stops

By default, when you are working in ANSI format, the Code Editor has tab stops set at columns 7, 8, 12, 73, and 80. When you are working in terminal format, no default tab stops are set. You have the option to add, remove, or change the existing tab stops for each ANSI and terminal format file in the Code Editor > Tabs section of the Tools > Options interface. You can also determine whether pressing the Tab key inserts a tab character or inserts the number of spaces needed to move to the next tab stop.

To customize your tab settings:

  1. Open the Tools > Options interface, expand the Code Editor tree, and select the Tabs tree item.
  2. To determine basic tab behavior, first select one of the two radio buttons near the middle of the screen.

    To preserve the tab character in your source code, select Keep Tabs. You can then elect to display a special character to indicate the location of a tab. This can be any non-blank character entered in the Display tab character with entry field. The default character is ^.

    To replace tab characters with spaces, select Insert spaces.

  3. By default, if no tab stops are set, pressing the tab key advances the cursor eight (8) columns. To change this default, enter a number between 1 and 64 in the Tab size entry field.

    Note that any tab stops that you have set override the Tab size setting. In other words, when you press Tab, the cursor moves to the next tab stop, if any. If there is no tab stop, the cursor moves forward the number of columns indicated in the Tab size field. Likewise, when you press Shift+Tab, the cursor moves back to the previous tab stop, or, if there is no tab stop, moves back the number of places indicated in this field.

  4. To add, change, or remove tab stops, first select either ANSI Format or Terminal Format in the Source format entry field. You can establish different sets of tab stops for each source format.
  5. To add tab stops, enter each desired setting in the Tabs entry field and click Add. Your new settings appear in the list box. You can set up to 32 tab stops.

    To delete a tab stop, select the setting you want to delete, and click Delete. The setting disappears from the list box.

Parent topic: Customizing the Code Editor Interface


Configuring Keyword Behaviors

By default, the Code Editor displays ACUCOBOL-GT reserved words in blue, while ordinary text is shown in black. In addition to changing the color used to mark reserved words, discussed in Modifying Editor Appearance, you can add words to a keyword list, or remove words from that list, in order to determine how those words are displayed in the Code Editor. You can also determine how far the next line after the keyword will be indented, if at all.

These keyword lists affect only the workbench's colorization and auto-indent functions. Adding or deleting a keyword in a default list does not affect the behavior of the ACUCOBOL-GT compiler. To change the list of reserved words recognized by the compiler, use the -R flag, described in ACUCOBOL-GT User's Guide.

You can modify the set of keywords recognized by the AcuBench Code Editor as follows:

  • To add an entire keyword set, click Add.

    In the Add Keyword Set dialog, enter the name of the new set in the Keyword set name text box, then select one of the three radio buttons to indicate the source of the new keyword set. Select None to create an original keyword set, Exist set to base your new keyword set on an existing set, or External set to import a keyword set.

    If you are importing an external keyword set, click the browse button to navigate to the location of the .ini file containing the keyword set you want to use.

  • To delete a keyword set, select the set that you want to delete in the Keyword set drop-down box. Click Delete.
  • To add or delete a keyword from an existing set, first select a set from the Keyword set drop-down box.

    If you are adding a keyword, use the New (Ins) push button at the top of the Keyword list box to add your new keyword.

    If you are deleting a keyword, select the keyword and click the Delete button at the top of the Keyword list box.

To determine the automatic indenting behavior associated with Code Editor keywords, select one of the three Auto indent radio buttons near the bottom of the dialog box.

  • If you want the cursor to return to column 1 of the next line after each carriage return, select None.
  • To have a carriage return send the cursor to the next line at the location of the first non-blank character in the previous line, select First non-blank token.
  • To use the custom settings in the Indent value column of the keyword list to determine cursor positioning after each carriage return, select Customized. If the indent value is set to zero, when you press Enter, the cursor indents the next line to the same position as the current line (that is, the behavior described for First non-blank token is used). If the indent value is set to a non-zero value, the next line is indented that number of columns beyond the indenting used by the current line.

    To modify keyword indent values, double-click in the Indent value column and enter the number of characters to indent the next line.

Parent topic: Customizing the Code Editor Interface


Setting Print Layout Options

When you print text files that you have opened in the Code Editor, you can use a standard Windows print dialog box to select a printer and manipulate printer settings. In addition to these standard options, AcuBench provides a Page Setup interface that allows you to standardize the layout and formatting used when you print Code Editor documents. You can set a standard header and footer, choose between print styles, determine the default paper and margin sizes, add a frame around the printed text, and specify whether or not to include line numbers in the printout.

To access the Page Setup dialog, expand the File menu and select Page Setup.

To see what your document will look like with the settings that you have selected, you can either select Print Preview from the File menu, or click the Print Preview button on the Project toolbar. The Print Preview button looks like this:

  • Setting Headers and Footers
  • Setting Page Appearance
Parent topic: Configuring the Code Editor


Setting Headers and Footers

By default, when you print a file that is open in the Code Editor, a header and footer are added to each page. The default header prints the file name, centered, and the default footer shows the page number, also centered.

To change the header and footer settings, open the Page Setup dialog and edit the contents of the Header and Footer entry-fields. You can enter a literal value and/or a combination of special characters, as indicated in the following tables. You can also click the arrow button to the right of the field and select values corresponding to the special characters from a list.

Header and footer values are indicated by the following characters:

Value | Character
Full Path Filename | &U
Filename | &F
Page number | &N
Current time | &T
Current date | &D

Alignment positions for header and footer items are represented by the following:

Position | Character
Left align | &L
Center | &C
Right align | &R
Parent topic: Setting Print Layout Options


Setting Page Appearance

In addition to modifying the header and footer information in your printed documents, you can use the Page Setup dialog box to format the appearance of the printed page. You can, for example, choose to print with zebra-style shading, for readability, or to add line numbers.

To make changes to the appearance of the printed page:

  1. Open the Page Setup dialog.
  2. By default, Code Editor text is printed in simple black and white format. To change this, expand the Style list and select another option.
    • If you have a color printer and want your printed output to retain the text color settings used in the Code Editor, select Color.
    • To add shading to alternating lines of printed text, select Zebra. A light gray shading is used.
  3. To add line numbers to the printed text, mark the Print line number check box.
  4. To add a frame around the printed text, select a style from the Frame list box.
    • The Inner option, available in all circumstances, places a frame around the text of the file.
    • The Outer and Both options are available when you have elected to print line numbers. Outer places a frame around all body text, including line numbers. Both places one frame around the file text and one frame around the line numbers.
  5. To change the default document margins, enter the measurements you want in the Left, Right, Top, and Bottom boxes.
  6. When you are finished making changes, click OK.

    To see what the output file will look like with your changes, select File > Print Preview.

Parent topic: Setting Print Layout Options


Working with Source Code

  • Introduction
  • Working with Files
  • The Code Editor Window
  • Basic Editor Functions
  • COBOL-Friendly Editing Functions
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

When you double-click a source file or COPY file in the Workspace window's File view, or when you create a new file, the file opens in the AcuBench Code Editor. You can then scroll through the file, type in changes, and use the standard Windows editing functions, search, select all, copy and paste, and so on, to manipulate the text.

In addition to these basic functions, the Code Editor offers a wealth of tools to help streamline code development and maintenance processes. Color-coded text and columns, line markers, and custom tab settings provide visual cues to reduce typing errors. Pop-up lists of program elements, such as variables and paragraph names, help with recall. Editor commands make it possible to select a vertical column of text, change the indentation of multiple lines of selected code, or instantly comment or uncomment an entire block of code. And that's only the beginning.

This chapter begins with a general discussion of working with files in AcuBench, then focuses on the specifics of working with source code in the Code Editor.

Parent topic: Working with Source Code


Working with Files

Most of the files associated with your project (listed in the File view of the Workspace window) can be opened in the Code Editor. The obvious exceptions are binary files, like ACUCOBOL-GT object files and bitmaps.

Note that if you are using AcuBench code generation, many of the files in your File view Copylib folder, as well as the files in your Screen and Report folders, are likely to be read-only files. You can open these files in the Code Editor, but are encouraged to make changes in the graphical designers associated with the Structure view.

To open a file listed in the File view, double-click the file name or right-click the file name and select Open filename. The file opens in the Code Editor window, whose title bar shows both the name of the file and the name of the project with which the file is associated.

To save changes to a file, select Save from the File menu, click the Save icon on the Standard toolbar, or use the default keyboard shortcut: Ctrl+S. If you want to save your changes in a new file (or find that you have been working in a read-only file), select the Save As option from the File menu, then specify a name and path for the new file.

If you are working with a source file, you can save your changes and compile with the Ctrl+F7 keyboard shortcut (or right-click the filename in the File view and select Compile filename.

Note that while you can open and save any text file in the Code Editor, you can compile only source files associated with a project in the current workspace. If you try to compile a file not associated with a project, an AcuBench prompt appears, asking you whether to add the file to the current project or cancel the compile request.

  • Creating a New File
  • File Formats
Parent topic: Working with Source Code


Creating a New File

When you want to add a new file to a project, the most straightforward method is to right-click a folder in the File view and click New File. The file is, by default, given a file extension that corresponds to the file type associated with the folder you select and added to that folder in the project. For example, if you right-click the Source folder and click New File, the file is given a .cbl extension and placed in the Source folder. If you click the same command while clicking the Copylib folder, the default extension is .cpy and the file is added to the Copylib folder. You do not have to use the default settings.

At the same time that the new file is added to the project, it is opened in the Code Editor.

By default, two file templates appear in the New File interface: Blank Text and Source Template. The Blank Text template creates an entirely empty file. The Source Template file contains the very basic skeleton of a COBOL program with some error-handling information.

You are not limited to the default templates. In fact, any text file that you create can be used as a template file. Use the Environment > Template section of the Tools > Options interface to add your template file to the New File interface.

Parent topic: Working with Files


File Formats

The Code Editor can work with text in either terminal or ANSI format. By default, the Code Editor makes a clear, visual distinction between files opened in terminal format and files opened in ANSI format. In addition to having code starting in column 1, files opened in terminal format are shown in black and white. In files opened in ANSI format, code starts in column 8, background colors mark the Indicator Area, Area A, and Identification Area, and code text is color coded.

When you have a file open in the Code Editor, you can switch between ANSI and terminal formats. To do this, select ANSI to Terminal Format or Terminal to ANSI Format from the Format menu. Note that while this changes the appearance of the text in the Code Editor, it does not change the existing spacing or position of text in the file.

Parent topic: Working with Files


The Code Editor Window

When you open a file in the Code Editor, the text of the file is displayed according to the settings established in the Tools > Options interface under Code Editor > Format. In addition, the editor's title bar lists, by default, the full path and file name of the open file, and a ruler bar indicates each column and tab stop. You also have the option of displaying two additional information areas: one that lists line numbers and one that shows where you've placed bookmarks in your code.

All of these options are configured through the View menu:

  • To determine whether the Code Editor title bar displays only the name of the open file or the full path and file name, unmark or mark the Full Path Filename menu option.
  • To show or hide the ruler bar at the top of the Code Editor window, mark or unmark the Ruler Bar option.
  • To show or hide a vertical pane listing line numbers for the open file, mark or unmark Line Number Pane. The number of digits shown in this pane can be configured through the Tools > Options interface, as described in Configuring Basic Editor Functions.
  • To show or hide a vertical pane on which you can place markers to highlight lines of code, mark or unmark Bookmark Pane. The use of bookmarks is discussed in Using Bookmarks.
Parent topic: Working with Source Code


Basic Editor Functions

When you are working in the Code Editor, you can access all of the standard Windows editing functions through the Edit menu, the Standard toolbar, the Editor toolbar, a right-click pop-up menu, and keyboard shortcuts.

The first group of Standard toolbar buttons let you create a new file, open an existing file, save a single file, or save all files. Other buttons (highlighted in the illustration), allow you to print a file; preview print output; cut, copy, and paste selected text; and undo or redo previous editor actions.

The Editor toolbar provides access to a combination of basic and advanced Code Editor functions.

The first group of Editor toolbar controls lets you enter a search string, find the next instance of a search string, search multiple files for a string, replace a string, or replace a string in multiple files. See Looking for Something?: Search and Replace for more information. Other buttons let you place and navigate between bookmarks (Using Bookmarks), change the indentation of lines of text (Changing Case and Indenting Lines), view lists of paragraphs, variables, and constants declared in the program (Using Paragraph, Variable, and Constant Lists), open a COPY file (Working with COPY Files), and determine the scope of a selected code statement (Using Code Insight Functions).

Edit menu commands let you undo or redo previous actions; cut, copy, paste, and delete text; select all text in a file; search for a text string and replace that string, if desired; jump to the a specific point in the file (Edit > Go To); add, remove, and navigate between bookmarks (Edit > Bookmarks); and access a sub-menu of advanced Code Editor functions (Edit > Advanced).

By default, the editor uses the standard Windows keyboard shortcuts for basic functions, such as cut (Ctrl+X), copy (Ctrl+C), paste (Ctrl+V), and select all (Ctrl+A). You can modify these shortcuts, if desired, in the Tools > Options interface, as described in Establishing Keyboard Shortcuts.

The Code Editor also uses the same navigation keystrokes as many other Windows editors. The arrow keys, for example, can be used to move left or right one character at a time, or up or down one line at a time. The End key moves the cursor to the end of the current line, while the Home key moves you to the beginning of the current line.

Useful navigation keystrokes include:

To move (to): | Default keyboard command
Forward one word | Ctrl+Right arrow
Back one word | Ctrl+Left arrow
Top of the file | Ctrl+Home
Bottom of the file | Ctrl+End

Keyboard shortcuts also make it easy to select text without using the mouse. These shortcuts include the following:

Desired Selection | Keyboard Command
Next character | Shift+Right arrow
Previous character | Shift+Left arrow
Entire preceding line | Shift+Up arrow
Entire following line | Shift+Down arrow
Preceding multi-line entry | Shift+Up arrow until the desired multi-line entry is selected
Following multi-line entry | Shift+Down arrow until the desired multi-line entry is selected
  • Using Bookmarks
  • Changing Case and Indenting Lines
  • Viewing Multiple Sections of Your File
  • Merging Data From Another File
Parent topic: Working with Source Code


Using Bookmarks

Bookmarks provide another useful method for navigating through your code. The Code Editor allows you to insert these markers in your source code for reference purposes, then jump forward and backward from maker to marker. These markers do not alter your code. They simply allow you to move around in your file more easily. The Code Editor displays an icon in the Bookmark pane to indicate that a line is bookmarked.

Bookmarks also function as AcuBench debugger breakpoints in your code. More detailed information about breakpoint behavior can be found in The AcuBench Integrated Debugger.

Bookmarks are visible only in the Bookmark pane, so that Code Editor window component should be open if you want to see the marks. However, you can still move easily among your bookmarked lines of code, even if you cannot see the marks. Navigation between bookmarks is not affected by icon visibility.

When you work with source files and COPY files in the Code Editor, bookmarks are automatically saved in the workspace file when you close the editor. Note that while you can also use bookmarks in the Event Editor, those bookmarks are ephemeral, lasting only as long as the editor window is open. If your bookmarks vanish unexpectedly, verify which editor you are using. The Event Editor is discussed in Working with Screens.

To insert a bookmark in your text, go to the line you wish to mark and click the Toggle Bookmark button in the Editor toolbar. You can also expand the Edit menu and select Bookmark > Toggle Bookmark or use the Ctrl+T keyboard shortcut. Use the same command to remove a bookmark.

When you add a bookmark, if the bookmark pane is visible, a bookmark icon appears next to the selected line. You can show or hide the bookmark pane by marking or unmarking the Bookmark Pane check box in the View menu.

To move the cursor to the previous bookmarked line in your code, use the Previous Bookmark button on the Editor toolbar. To move the cursor to the next bookmarked line of code, use the Next Bookmark button. To clear all the bookmarks from the active document, use the Clear All Bookmarks button.

Parent topic: Basic Editor Functions


Changing Case and Indenting Lines

The Code Editor allows you to change the case of one or more words or to indent one or more lines without retyping any code.

To capitalize an uncapitalized selection, choose the Format > Capitalize command. To change an uppercase selection to lowercase, choose the Format > Lowercase command, and to change a lowercase selection to uppercase, choose the Format > Uppercase command.

To move the current line to match the indenting of another line of text, do one of the following:

  • To change the indent of the selected line to match that of the next line, choose the Format > Indent to Next command.
  • To change the indent of the selected line to that of the previous line, choose the Format > Indent to Previous command.
Parent topic: Basic Editor Functions


Viewing Multiple Sections of Your File

A splitter bar makes it possible for you to see (and edit) different parts of your file simultaneously. Each half of the split window has its own scroll bars (horizontal and vertical) for easy movement through your code in either view.

The splitter appears as a small bar above the upper scroll bar arrow on the right side of a Code Editor window. When you drag the bar downward, you open an additional view of the active document, initially at the beginning of the active document. Use the scroll bars or any relocating command in the Edit menu (such as the bookmark commands or the Edit > Go To command) to move to another location in either display.

You can also split your source file window by using the Window > Split command. When you use this command, the cursor changes to a double-arrow that is located at the top of a Code Editor window. Drag the cursor down to open another view of your file.

Parent topic: Basic Editor Functions


Merging Data From Another File

While you are working in the Code Editor, you can easily insert the contents of another file into the current document that you are editing. To do this:

  1. Position your cursor in the location where you want to insert the file.
  2. Choose the Edit > Advanced > Insert File command. The Insert File dialog box appears.
  3. Locate and select the file you want to insert.
  4. Click Open. The data appears at the cursor’s location.
Parent topic: Basic Editor Functions


COBOL-Friendly Editing Functions

When you work with ANSI format files in the Code Editor, by default, the editing area is divided into five segments: the sequence area, indicator area, Area A, Area B, and identification area. As discussed in Modifying Editor Appearance, you can determine whether and how these columns are given visual markers in the editor.

  • Adding and Removing Line Items
  • Working with Tabs
  • Working with Blocks of Code
  • Using Code Insight Functions
  • Using Paragraph, Variable, and Constant Lists
  • Working with COPY Files
  • Using Source Code Templates
  • Navigating Between Error Lines
Parent topic: Working with Source Code


Adding and Removing Line Items

An additional Code Editor tool can be used to have AcuBench automatically add or modify line numbers in the sequence area. This function is only available when you are working with ANSI format files.

To add line numbers to the sequence area:

  1. Open the Format menu and select Sequence Number. The Sequence Number dialog opens.

  2. To add numbering to your file (or re-number the file), select the Make radio button and continue with step 3.

    To clear all existing numbering from your file, select the Clear radio button, then click OK to return to the editor window.

  3. To determine how lines in your file will be numbered, enter a starting number and interval in the appropriate entry fields. By default, the file is numbered from one by one, meaning that the first line in the file is assigned number 00001, the second line is assigned number 00002, and so on.
  4. In the Line range area, select a radio button to determine whether all lines in the file, a highlighted selection of lines, or a specific line range will be given numbers.
  5. When you are finished, click OK to number or re-number the file.
Parent topic: COBOL-Friendly Editing Functions


Working with Tabs

When you are working in ANSI-format files, the Code Editor, by default, places tab stops at columns 7, 8, 12, 73, and 80. Use the Tab key to move the cursor to the next tab stop, or the Shift+Tab shortcut to move to the previous tab stop.

As described in Customizing Tab Stops, you can set up to 32 custom tab stops. You can also set a default tab interval that determines how far the cursor moves when you press the Tab key and no tab stop is set. If you specify a tab size of 3, for example, each press of the Tab key moves the cursor forward 3 spaces. This can be useful for maintaining consistent indenting when working with IF or EVALUATE statements, for example.

Tabs may also be used to move blocks of text in your code. Highlight the lines of code you want to move and press the Tab key. The entire block of text shifts to the next tab stop (or to the tab size interval that you have specified).

Parent topic: COBOL-Friendly Editing Functions


Working with Blocks of Code

The Code Editor offers several useful tools for manipulating blocks of code. For example, as described in Working with Tabs, you can move multiple lines of text with a single press of the Tab key (or the Shift+Tab shortcut). You can also use a single command to add or remove comment markers from an entire block of text, or use a simple key/mouse combination to select, move, copy, and paste a vertical block (or column) of text.

Comment and uncomment block

To comment out a block of code, perform the following steps:

  1. Select the text.
  2. Expand the Format menu and select Comment Block.

    This adds an asterisk character (*) in column 7 and moves each line right one column.

To uncomment a block of code, perform the following steps:

  1. Select the text.
  2. Expand the Format menu and select Uncomment Block.

    This removes an asterisk character and moves each line left one column.

Vertical block select

To select a vertical column of text, position the cursor at the start of the first item in the column, then hold down the Alt key while clicking and dragging with the mouse. You can then copy the column of text to the clipboard and paste it to another file, either within AcuBench or in another editor. Note that when you paste a vertical block of text into a third-party editor, AcuBench adds a comment, **AcuBench Column Block**, at the head of the column.

When you paste a vertical block into AcuBench, note that the column does not overwrite any existing text. Instead, existing text is moved over the number of columns necessary to make room for the pasted block.

Consider the following example. Suppose you have a list of error codes and the corresponding error messages. You might set up several lines of code like the following:

WHEN "" MOVE "" TO text-message

You could then select the error codes in a vertical block, position the cursor between the first set of quotation marks, and paste the block. Each line would be moved to get a result like:

WHEN "01" MOVE "" TO text-message
WHEN "02" MOVE "" TO text-message
WHEN "03" MOVE "" TO text-message

You could next perform the same operation with the string representing the message to get a result like:

WHEN "01" MOVE "File not found " TO text-message
WHEN "02" MOVE "Incorrect file type" TO text-message
WHEN "03" MOVE "File locked " TO text-message

Note the spaces in the first and third lines. With a vertical block of text, the exact width of the vertical block is preserved, regardless of the length of individual lines in the block.

Parent topic: COBOL-Friendly Editing Functions


Using Code Insight Functions

The workbench provides various features to help you keep track of your COBOL code. The first of these, called code parameters, provides pop-up tips explaining the syntax and basic usage rules for some COBOL verbs. This feature may be helpful for novice COBOL programmers.

The second code insight function is called code completion. When this feature is enabled, you can pause briefly after typing various COBOL verbs to see an alphabetical list of possibilities for completing your statement. For example, if you type:

CALL "

AcuBench provides a list of programs and library routines that you might want to call. Likewise, if you type MODIFY and a space, code completion provides a list of screen controls and handles on which you might want to perform a modify operation. In the latter case, after you choose an item to modify, a second pop-up box provides a list of applicable properties to be modified.

Code and parameter completion are available for the following verbs: CALL, CHAIN, CLOSE, DELETE, DESTROY, GO, INQUIRE, MODIFY, OPEN, PERFORM, READ, REWRITE, START, and WRITE.

By default, code completion is enabled, while code parameters are disabled. You can change these settings in the Tools > Options window. More information about the Tools > Options dialog box can be found in Code Insight Options.

Two other features can provide additional insight into existing code. If you have code with a good deal of nesting, or code that doesn't use indentation, or if you are having trouble parsing a statement, you can use the Find Scope and Verb Block Match commands to determine the scope, or range, of a particular statement.

To highlight the block of code corresponding to a specific statement (for example, all lines of code pertaining to a single PERFORM statement):

  1. Position the cursor anywhere within the statement or phrase.
  2. Select Find Scope from the Edit > Advanced menu (or the Editor toolbar).

    AcuBench highlights all lines of code affected by, or included in, that statement.

Similarly, you can use the Verb Block Match command to move the cursor from one end of a match verb block to the other. If you position the cursor at the start of a READ statement, for example, and select this command from the Edit > Advanced menu (or Editor toolbar), the cursor jumps to the end of the line containing the corresponding END-READ.

The workbench recognizes the following list of matched verbs as pairs:

Initial | Final
Add | End-Add
Call | End-Call
Evaluate | End-Evaluate
If | End-If
Perform | End-Perform
Read | End-Read
Return | End-Return
Rewrite | End-Rewrite
Search | End-Search
Start | End-Start
String | End-String
Write | End-Write
Parent topic: COBOL-Friendly Editing Functions


Using Paragraph, Variable, and Constant Lists

AcuBench maintains lists of the paragraphs, variables, and constants defined in your program. These lists make it easy to jump to the line of code where the paragraph, variable, or constant is defined, or to insert the paragraph, variable, or constant name into your code. When you open a list, it appears in a modeless window that allows you to work in the editor window while the list is displayed.

You can easily access any of these lists while working in the Code Editor or Event Editor using any of the following methods:

  • Right-click anywhere in the editor window and select the appropriate command: List Paragraphs, List Variables, or List Constants.
  • Open the Edit menu and select Advanced, then select the appropriate command: List Paragraphs, List Variables, or List Constants.
  • Select the appropriate button on the Editor toolbar:

The lists display the following information:

  • The Paragraph List contains the name of each paragraph and the COPY file in which it appears. You can control whether the COPY file column is visible and how the paragraphs are sorted via the Tools > Options > Code Editor > Paragraph List interface.
  • The Variable List contains the name, level number, and picture value of each variable, as well as the COPY file in which it appears. You can control which columns are visible, how the variables are sorted, and whether blank FILLER data items are listed in the box via the Tools > Options > Code Editor > Variable List interface.
  • The Constant List contains the name and value of each constant, as well as the COPY file in which it appears. You can control which columns are visible and how the constants are sorted via the Tools > Options > Code Editor > Constant List interface.

Each of the aforementioned Tools > Options interfaces is described in Paragraph List, Variable List, Constant List, and COPY File List Options.

You can easily insert into your code any paragraph name, variable, or constant that appears on one of these lists. Position the cursor in your code where you want the item name to appear. In the pop-up list, select a name, right-click, and choose Paste. Note that you can change the cursor’s position in the code and paste an item multiple times. You can also double-click an item name to insert it at the cursor’s location.

Each of the lists offers a variety of additional functions:

  • To jump to an item in the list, start typing its name. With each letter you type, the cursor jumps to the first matching item. For example, if you type the letter a, the cursor jumps to the first item beginning with that letter. If you next type c and u, the cursor jumps to the first (or next) item beginning with “acu”. If you mistype, use the backspace key to clear the search buffer.

    When the last item in the list that matches your search string is reached, the search resumes at the top of the list.

  • To copy an item name to the Windows clipboard, select the item name in the list, right-click, and select Copy to Clipboard.
  • To move the cursor to the line of code where a paragraph, variable, or constant is defined, select the item, right-click, and select Go to Definition.
  • If you modify your code while the list box is open, you can update the Paragraph List with the Refresh command.
Parent topic: COBOL-Friendly Editing Functions


Working with COPY Files

AcuBench also maintains a list of the COPY files currently declared in your program. You can view the COPY File List box via the Edit > Advanced > List COPY Files command.

The COPY File List functions much like the Paragraph, Variable, and Constants Lists. In addition to the name of each COPY file, the list box contains columns showing each COPY file's directory and the name of the file in which it is declared. You can control which columns are visible and how the COPY files are sorted via the Tools > Options > Code Editor > COPY File List interface, which is described in Paragraph List Variable, List Constant List, and COPY File List Options. You can also determine the sort order by clicking the column headings in the list box.

To insert a COPY file name into your code, position the cursor in your code where you want the COPY file name to appear. In the COPY File List box, select a name, right-click in the list box, and choose Paste. Note that you can change the cursor’s position in the code and paste a COPY file name multiple times.

If you are using the COPY File List and want to open a COPY file, just double-click the file name. You can also easily open a COPY file without opening the COPY File List. Just select the COPY statement in your code and do either of the following:

  • Select Open COPY File from the Edit > Advanced menu.
  • Click the Open COPY File push button on the Editor toolbar.

The Copy to Clipboard, Go to Definition, and Refresh commands described at the end of the previous section are also available when you are working in the COPY File List.

Parent topic: COBOL-Friendly Editing Functions


Using Source Code Templates

You can add an existing source code file to your project as a template through the Tools > Options > Environment > Template interface. The Add function displays the Add New Template File dialog box, with which you locate the source code file you want to use as a template. An icon for your template appears in the Customize Template for box in the Tools > Options > Environment > Template interface and in the File > New > File dialog box. After you have added a template to your project, you can modify or delete that file via the Tools > Options > Environment > Template interface. More information about the Tools > Options > Environment > Template dialog box can be found in Template Options.

Another source code template function allows you to insert a small section of frequently used code directly into your text. You define these small templates in the Tools > Options > Code Editor > Code Insight interface. Information about defining code templates in the Tools > Options dialog box can be found in Code Insight Options.

You can insert a small source code template into your source code as follows:

  1. Place the cursor where you want to insert your code template. Choose the Edit > Advanced > Code Template command. A list box containing all currently defined code templates appears.
  2. Browse the list box for the desired template.
  3. Double-click a name; the code template is inserted at the cursor’s location.
Parent topic: COBOL-Friendly Editing Functions


Navigating Between Error Lines

When you compile your source files, any compiler errors are listed in the Output window. You can double-click an error in the Output window to jump to the corresponding line in your source file. Once the source file is open in the Code Editor, you can use the Edit > Go To menu to navigate between compilation errors. To go to the previous error line in the Output window error list, expand the Go To submenu and select Previous Error. To move the cursor to the next error line, select Next Error.

Parent topic: COBOL-Friendly Editing Functions


Configuring the Screen Designer

  • Introduction
  • Customizing the Screen Designer Interface
  • Establishing Screen and Control Defaults
  • Adding Screen Templates
  • Configuring Keyboard Shortcuts
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

As you prepare to design a user interface for your AcuBench program, it is important to ensure that all of the required foundation elements have been put in place. When you use the Standard Project template (which opens with a blank screen in the Screen Designer), it is tempting to jump right in to designing screens. But keep in mind that the process of creating a user interface is significantly easier if you have defined data layout files for your project and created data sets within your program.

With this in mind, before you begin designing and working with your screens, you should:

  1. Create an AcuBench project (discussed in Working with Projects).
  2. Define one or more data layout files in the Data view (discussed in Working with Data at the Project Level).
  3. Create a new AcuBench program (discussed in Working with Programs).
  4. In the Structure view, define one or more data sets for use by the program (discussed in Working with Data at the Program Level).

Once you have completed those four steps, you are ready to start working in the Screen Designer. The Working with Screens describes how to use the Screen Designer to create user interfaces for your AcuBench programs.

Parent topic: Configuring the Screen Designer


Customizing the Screen Designer Interface

The Screen Designer interface, accessed through the workspace Structure view, is made up of a design window and two companion tools. The central design window displays the screen form on which you place controls to create a character-based or graphical user interface for your program. The tools are the Screen Component Toolbox, which displays all of the standard ACUCOBOL-GT screen controls and available ActiveX controls that can be added to your screen form. The Property window displays a configurable list of properties associated with the selected screen or control.

The appearance of the design window and the contents of the Property window are configured through the Screen Designer section of the Tools > Options interface. This topic addresses the options for customizing the appearance of the design window. Property window configuration is discussed in Establishing Screen and Control Defaults.

By default, when you create a new screen or open an existing screen in the Screen Designer, the screen form appears covered with a grid of black dots. This grid does not directly correspond to any generated COBOL code, but instead acts as a visual aid to help you position and align controls on the screen.

To configure the appearance and behavior of this grid:

  1. Open the Tools > Options interface, expand the Screen Designer tree, and select General.
  2. To change the size of the cells making up the grid, enter a number between 3 and 20 in the Grid width and Grid height fields. (You can either select the value from the drop-down list or type the entry in the field.)

    By default, the size of each grid cell is set to a width and height of 10 pixels. This corresponds to the default value for the screen CELL SIZE property.

  3. If you would like each control that you place on the screen form to automatically align to the grid boundaries, mark the Snap to grid check box.

    Note that even when this option is selected, you can still select a control and move it in any direction one pixel at a time by using the keyboard’s arrow keys.

You can also configure one additional Screen Designer behavior through this interface. If, when you draw a new control under an existing control in the Screen Designer, you would like the new control’s left boundary to align to the left boundary of the existing control, mark the Auto alignment check box. This automatic alignment occurs when the boundaries of the two controls are within 5 pixels of each other horizontally.

Parent topic: Configuring the Screen Designer


Establishing Screen and Control Defaults

In the Tools > Options > Screen Designer interface, the Default and Visibility screens let you determine not only the default properties given to any new screen or control created in the Screen Designer window, but also which properties appear in the Property window for each screen item. This means that if you want all entry fields to show only uppercase text, and you don't want anyone to change that setting, you can set the default case in the property sheet to Upper, then remove the Case property from the property window entirely.

Certain properties that appear in the property sheet cannot have default values assigned. Location properties, for example, cannot have a default value, because they are dependent on where you position a control on the screen form.

Some properties do not appear on the property sheet at all. For the most part, these properties are not part of the initial state of the control, and therefore cannot be described in the Screen Section. Such properties include the SELECTION-TEXT property, used to determine what text the user has selected within an entry field, and the RESET-LIST property, used to delete the items that currently exist within a list box. Because a user selection occurs after the creation of the control, and a list is cleared only after it has both been created and loaded with data, it wouldn't make sense to set either of these properties as part of the control's Screen Section definition.

For each control property that does appear in the Screen Designer Property window, you can determine the default value as follows:

  1. Open the Tools > Options interface, expand the Screen Designer tree, and select the Default category.
  2. Select an item from the Controls list. This list contains all of the screen items to which properties can be assigned. This includes the screen itself, menus, and toolbars, as well as each of the standard ACUCOBOL-GT controls. In some instances, control sections (such as menu items and tree view items) also have their own configurable property defaults.

    The Properties list (to the right of the Controls list) is updated to show the properties associated with your selection.

  3. To change the default value assigned to a property, select the property from the Properties list, then click in the Value column next to the property name.

    Depending on the property, clicking in the Value column may enable an entry field, reveal a drop list, or enable a push button used to invoke a configuration interface. A push button marked with three dots (“...”) is used to indicate that you can launch an additional interface to help you make your selection.

Note that changes to the default properties in the Tools > Options interface do not affect existing screens or controls, whose properties have already been established and generated into code. Any new screen or control that is created, however, will take on the default characteristics that you specify.

To determine which of the available screen and control properties appears in the Screen Designer Property window, do the following:

  1. Open the Tools > Options interface, expand the Screen Designer tree, and select the Visibility category.

    This interface lists all available control properties (rather than just properties for a single control type) in alphabetical order.

  2. By default, all properties in the list are displayed in the Property window. To remove a property from the list, clear the check box next to the property description, or select the property and click Clear.

    To add a property to the list that had previously been removed, mark the corresponding check box or select the property description and click Set.

  3. In addition to adding or removing properties from the list one at a time, you can add or remove an entire category of properties. The check boxes that appear directly under the Set and Clear buttons list the available property categories. When you clear one of these check boxes, the check boxes corresponding to all of the properties in that category are likewise cleared. When you mark one of these check boxes, all of the properties in that category are likewise marked.

The changes that you make in this interface are saved in your personal acubench.ini file when you click OK. If you want to save your changes to another file, you must click Save. To abort all changes, click Cancel.

Parent topic: Configuring the Screen Designer


Adding Screen Templates

When you create a new screen in AcuBench, you have the option to choose between several default templates (such as the blank graphical screen and blank character screen). In addition to these defaults, you have the option to create your own screen templates. Using custom screen templates can help you maintain a consistent look and feel across an application or application suite, and is an important part of consistency management.

The process of creating a screen template, described in Working with Screens, is very simple. Once you have the template file (.stf), you can use the Tools > Options interface to add the template to the list that appears in the New Screen dialog.

To add a template to the New Screen dialog:

  1. Open the Tools > Options interface, expand the Environment tree, and select Template.

    More information about the Tools > Options > Environment > Template dialog box can be found in section Template Options.

  2. In the Customize template section of the interface, select Screen from the Template for drop-down box.
  3. Click Add to open the Add New Template File dialog.
  4. Enter a short, descriptive title in the Template title entry field, then click the browse (...) button next to the Template file entry field.
  5. Navigate to the directory containing your .stf, select the file, and click Open.
  6. Add a more verbose description of the template file in the Description field.
  7. Click OK to save your changes, then click OK again to close the Tools > Options interface.

    The next time you create a new screen, your template appears in the New Screen dialog, along with your description.

Tip: When you add templates to the New Screen interface, a pointer is placed in the INI file, used to locate the .stf file on disk. If you move the STF, AcuBench will no longer be able to locate the template and you will receive an error message. This means that if you are sharing a template among a team of developers, the STF should reside in a shared folder or be made part of your version control project.
Parent topic: Configuring the Screen Designer


Configuring Keyboard Shortcuts

As in the Code Editor, you can specify a custom set of keyboard shortcuts for use in the Screen Designer environment. These keyboard shortcuts can be used to perform basic editing operations (cut, copy, paste), move controls on the screen, and shape and align controls.

To add or change a keyboard shortcut associated with a Screen Designer function:

  1. Open the Tools > Options menu, expand the Environment tree, and select Keyboard.
  2. Open the Category drop-down list and select Screen Designer.

    The list of commands shows only those functions specific to the Screen Designer, as well as the keyboard shortcut (if any) currently assigned to each function.

    As with the Code Editor shortcuts, some common functions (like Copy or Paste) appear to have no associated keyboard shortcut. These functions have been assigned a shortcut at the Main level, which applies unless overridden by a shortcut assigned in a specific context.

  3. Select a function in the list, then click in the Shortcut key entry field.

    If a keyboard shortcut is currently assigned to the selected function, this shortcut appears in the field. In most cases, a description of the function appears under the Assign and Remove push buttons.

  4. On the keyboard, type the combination of keys that you want to assign to the selected function. The key combination appears in the entry field.

    Note the Currently assigned to field under the entry field. If you enter a keystroke that has already been assigned to another function, this field displays the name of that function.

  5. To assign the keystroke that you have specified to the function that you have selected, click Assign. The new keyboard shortcut appears next to the function name.

To remove a keyboard shortcut that has already been assigned to a function, select the function in the Command list, then click Remove.

Parent topic: Configuring the Screen Designer


Working with Screens

  • Introduction
  • Creating a New Screen
  • Getting Started with Screen Design
  • Adding Controls to a Screen
  • Configuring Control Properties
  • Positioning and Aligning Controls
  • Refining Your Screen
  • Associating Code with Screen Elements
  • Working with Screen Templates
  • Generating a Screen
  • Testing Screens
  • Creating a Logo Screen
  • Creating Dual User Interfaces
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

Once you have created your data layout files and data sets and configured the Screen Designer environment, you are ready to start building a graphical user interface. To facilitate this process, the Screen Designer offers a WYSIWYG, drag-and-drop environment for creating character-based and graphical screens. In the designer, you can:

  • Draw, position, and manipulate screen elements
  • Configure screen and control properties and styles
  • Associate code with screens and screen items

When you add a new screen to your program, AcuBench generates the Procedure Division code necessary to display and accept that screen. As you drag and drop controls onto the screen form, AcuBench builds a Screen Section description of the screen. Each change that you make, laying out the screen and defining interface-handling code, is recorded in the program structure file (PSF) and used to generate the COBOL code to drive your program's user interface. In other words, as you work in the Screen Designer, you are doing more than describing the appearance of a screen. You are building a fully functional user interface to your application.

This chapter discusses the process of creating new screens, designing screen layout, changing screen and control properties, associating code with screen elements, and generating screen handling code.

Note that this chapter does not discuss methods for importing existing character-based or graphical screens into the Screen Designer. These methods are discussed in Bringing Existing Code Into AcuBench.

Parent topic: Working with Screens


Creating a New Screen

When you create a new project using the Standard Project template, a program containing a blank, graphical screen is automatically created within the project. Similarly, if you create a new AcuBench program within your project using the Standard Program template, the program includes a single blank, graphical screen.

If you have created an AcuBench program that does not include a screen, or if you want to add additional screens to a program, you can use either of two methods: select a template from the New Screen interface, or open a screen template file that you have previously created. This topic discusses the first method. The second method is discussed in Working with Screen Templates.

To add a new screen to your AcuBench program using the New Screen interface:

  1. In the Workspace window’s Structure view, expand the node (tree) associated with the program to which you want to add a screen.
  2. Right-click the Screen folder and select New Screen.

    The New Screen dialog appears, listing the available screen templates.

  3. Select a screen template. By default, seven templates appear on this screen. You can also use the Tools > Options interface to add additional, custom templates to this interface (see Adding Screen Templates).

    The default templates include the following:

    Template | Description
    Blank Graphical | A blank graphical screen
    Standard Graphical | A graphical screen that contains an OK button, a Cancel button, and a main menu
    Graphical Password | A graphical screen with entry fields and push buttons for collecting user login data
    Blank Character | A blank character-based screen
    Standard Character | A character-based screen with an OK button, a Cancel button, and a main menu
    Character Password | A character-based screen for collecting user login data
  4. Fill in the Form Name entry field with a descriptive name for your screen. Adding a descriptive name can help to minimize confusion and simplify maintenance, especially in programs with multiple screens.

    It is also possible to change the screen name after the screen has been added to your program. Just enter a new value in the (Name) field of the screen’s property sheet.

    Note that when you change the name of a screen after the screen has been created, the prefix appended to the name of any existing controls is updated to reflect the change. The new prefix is automatically set to the first 10 characters of the screen name. See the next step for more information about prefixes.

  5. The Unique Prefix entry field is filled in automatically with the first ten characters of your screen name, but you can change the default value. The Screen Designer uses this prefix for its default control and variable naming scheme.

    As with the screen name, you can change the screen prefix after the screen has been created. To do this, right-click the screen form in the Screen Designer and select Change Prefix.

  6. By default, the screen will be added to the current program when you click OK. If desired, you can use the radio buttons near the bottom of the New Screen window to add the screen to a different program.
  7. When you are finished making changes, click OK.

    The new screen form is opened in the Screen Designer, and an icon for the new screen is added to the program’s Screen node in the Workspace window’s Structure view. When needed, you can double-click the Structure view icon to open the screen in the Screen Designer.

Parent topic: Working with Screens


Getting Started with Screen Design

When you open a screen in the Screen Designer, the design interface comprises three main windows: the Design window, the Property window, and the Screen Component Toolbox.

  • The Design window displays a screen form. The screen form is a blank slate on which you can draw controls to build a user interface.
  • The Property window lists the properties, events, and code insertion points associated with the selected screen element. Properties range from basic, such as size and position of the selected item, to advanced, dictating the style and behavior of the item.
  • The Screen Component Toolbox lists all of the available controls (such as entry fields and grids) and other screen items (including menus and toolbars) that can be added to the selected screen form. If you are working with a character-based screen, the toolbox shows a subset of the controls available for use with a graphical screen.

The first step in creating your user interface is to configure the screen itself. While screen properties can be set after controls have been added to the screen, some screen properties, such as Font, are inherited by controls added to the screen. By setting these properties at the start, you can save time and streamline the design process.

  • Setting Basic Screen Form Properties
  • Creating a Resizable Screen
Parent topic: Working with Screens


Setting Basic Screen Form Properties

Screen properties are configured in the Screen Designer Property window. The Property window comprises a drop-down list box, which lists all of the elements that make up the current screen, and three tabs. The first two tabs, labeled Alphabetic and Categorized, list the available ACUCOBOL-GT properties for the screen element that appears in the drop-down list. The third tab, Event, lists all of the events, exceptions, and code insertion points associated with the selected screen element.

If you have the Screen Designer open and do not see the Property window, open the View menu and click Property Window.

To configure screen properties:

  1. Make sure that the screen form is selected in the Design window.

    The screen name should appear in the drop-down list box at the top of the Property window.

  2. Click the Alphabetic tab of the Property window.

    As you become comfortable working in the Screen Designer, you may find it easier to work in the Categorized tab. Both tabs list all of the same properties, only the order is different. For ease of navigation, these preliminary steps use the alphabetical ordering.

  3. Scroll to the top of the Property list and verify that the control's AcuBench (Name) property is an accurate description of the screen.

    The (Name) property acts as a screen handle, and is used to refer to the screen throughout the generated COBOL code.

    If you want to change the screen name, click in the Value column and type in a new name. The screen name listed in the Structure view is automatically updated when you tab or click out of the field.

    Changing the screen name also changes the unique prefix associated with the screen. Any existing control whose name includes the unique prefix is updated to indicate the new unique prefix. This prefix is the first 10 characters of the new screen name. You can change the unique prefix at any time by right-clicking the screen form and clicking Change Prefix.

  4. By default, screen controls use the font setting defined at the screen level. It is therefore a good idea to set the screen font setting before adding controls. To change the screen font, scroll to the Font property and click in the Value column. You can either click one of the default fonts from the drop-down list or click the browse (...) button to open a Font dialog box that lists all available system fonts.

    The default screen font is Small Fonts, which corresponds to the default Windows system font.

  5. The Title property is used to set the text that appears on the screen's title bar at run-time. To set the screen title, scroll to the Title property, click in the Value column, and enter a literal value.

    When you click or tab away from the field, the title bar on the screen form is updated to reflect your changes.

  6. Continue making changes as desired. Properties that you may want to configure include:
    • System Menu, used to determine whether or not a default system menu appears when you click the small title bar icon in the top, left corner of the screen
    • Title Bar, used to indicate whether or not a title will include a title bar. A window without a title bar cannot be moved by the user.
    • Window Type, used to specify which of the four basic window types (Standard, Initial, Independent, Floating) to use for this window. A program can have only one Standard or Initial window.

For more information about windows, screens, and their properties, refer to ACUCOBOL-GT User Interface Programming; additionally, refer to ACUCOBOL-GT Reference Manual, which details the syntax of the DISPLAY INITIAL WINDOW and DISPLAY FLOATING WINDOW statements, and provides a comprehensive list of window properties.

Parent topic: Getting Started with Screen Design
Related reference
ACUCOBOL-GT User Interface Programming
ACUCOBOL-GT Reference Manual


Creating a Resizable Screen

If you plan to allow your users to resize screens at run-time, you can simplify the process of handling that screen with a layout manager. A layout manager is a tool that, given a certain set of rules, determines how the size and placement of screen controls change as the size of the screen shifts. The exact rules vary by layout manager; you can write your own or use the one provided as part of your ACUCOBOL-GT installation, called LM_RESIZE.

This topic describes how to use built-in AcuBench support for LM_RESIZE to create a resizable screen. For information about layout managers in general, as well as detailed information about the ACUCOBOL-GT resize layout manager, see Layout Managers.

To create a resizable screen that uses LM_RESIZE as its layout manager, do the following:

  1. Click the screen form in the Screen Designer.
  2. In the Alphabetic tab of the Property window, scroll to the Auto Resize property. This property must be disabled in order to use a layout manager, so verify that its value is FALSE.

    If Auto Resize has been set to TRUE, click in the Value column and use the drop-down list to change its value.

  3. Still in the Property window, scroll to the Resizable property and set its value to TRUE.
  4. Finally, to specify a layout manager, scroll up to the Layout Manager property and change its value to LM_RESIZE.

    When you generate your program, AcuBench automatically creates a COPY file called lmresize.def to support layout manager functions within your program.

    AcuBench also assigns a unique Layout Manager Handle property to the screen. You can change the name of the handle, but keep in mind that if you have multiple resizable screens in your application, each layout manager handle must be unique.

When you generate your program, AcuBench automatically creates a COPY file called lmresize.def to support layout manager functions within your program.

Note that AcuBench also assigns a unique Layout Manager Handle property to the screen. You can change the name of the handle, but keep in mind that if you have multiple resizable screens in your application, each layout manager handle must be unique.

Later, as you add controls to your screen, you can use the Layout Data property to determine exactly how the resize manager handles that control when the screen size changes. The Layout Data property is discussed in Layout Data Control Property.

Note that in order for the layout manager to function properly, you must also change the screen's Auto Resize property to FALSE.

The resize layout manager facility is demonstrated in an AcuBench sample project located in the Support area of the Micro Focus Web site.

Parent topic: Getting Started with Screen Design


Adding Controls to a Screen

Once you have set the basic properties for your screen, the next step is to add functionality by placing screen controls on your screen. A control is a screen element used to provide information to the user and/or receive input from the user. In the Screen Designer, you add controls to a screen form by selecting them from the Screen Component Toolbox and drawing them on the screen.

Control icons may be viewed in a list with labels or as bitmap push buttons with pop-up hints. To toggle between these views, right-click in the Screen Component Toolbox and select List View.

In addition to the Selector, a Menu Designer, and a Toolbar Designer, the toolbox contains the following standard controls for graphical screens:

  • bar
  • bitmap
  • check box
  • combo box
  • date entry
  • entry field
  • frame
  • grid
  • label
  • list box
  • push button
  • radio button
  • scroll bar
  • status bar
  • tab
  • tree view
  • Web browser

Character-based screens cannot include the bitmap, date entry, grid, status bar, tab, or Web browser controls. When you work in a character screen, the Screen Component Toolbox icons for these controls are disabled.

The Screen Component Toolbox also has a section for the ActiveX controls that you want to use in your screens. ActiveX controls are available only for graphical screens. More information about the addition of ActiveX controls to your Screen Component Toolbox can be found in ActiveX Controls.

  • Drawing Controls with the Component Toolbox
  • Drawing Controls with Drag-and-Drop
  • Creating Autoload Controls
Parent topic: Working with Screens


Drawing Controls with the Component Toolbox

The Screen Designer lets you draw standard and ActiveX controls directly on a graphical or character-based screen form as follows:

  1. With a screen form open in the Screen Designer, click a control icon in the Screen Component Toolbox.

    The icon is highlighted to indicate that it has been selected. You can change the selected control type by clicking another icon in the toolbox.

  2. Move the pointer to the screen form. The pointer changes from an arrow to a crosshair.
  3. Position your pointer on the screen form, then hold down the left mouse button and drag the outline that appears to size your control.

    If you release the mouse button before you have finished sizing your control, click and drag any of the small, dark blue squares that appears in the frame surrounding the control. When a control is selected, you can also use the Shift+Arrow keyboard shortcut to resize it one pixel at a time, or Ctrl+Shift+Arrow to resize it one cell at a time. (The default screen cell size is 10 pixels by 10 pixels.)

Parent topic: Adding Controls to a Screen


Drawing Controls with Drag-and-Drop

If you have defined one or more data sets within your program, as discussed in Working with Data at the Program Level, the data items from the corresponding FD are listed in the Screen Designer Drag and Drop pop-up window. This window also lists Working-Storage, Linkage, and other data items defined in your program.

By default, this interface lists the field names as they are declared in the program. If, however, you have used the XFD tab of the File Designer to assign a Name directive to a field, you can elect to have that name appear in the Drag and Drop interface instead of the field name. When you choose this option, the Title property for any control that has a Name directive will show that name, rather than the actual field name. For information about enabling this option, see Designing a Custom XFD.

The Drag and Drop interface allows you to select a control type and one or more data items, then draw the control on the screen. AcuBench automatically adds the data item to the control's Property sheet as a Value Variable, generated Screen Section code to assign the item as the control's VALUE property. In addition, if you select a combo box, grid, list box, paged grid, or paged list box control type, additional code is generated to populate the control with data when the screen is loaded. These controls, referred to as autoload controls, are discussed in Creating Autoload Controls.

To use the Drag and Drop window to add controls to your screen:

  1. Right-click the screen form and select Drag-and-Drop from the pop-up window. You can also select the Drag-and-Drop command from the View menu.
  2. From the drop-down list in the top, left portion of the interface, select a data source category. By default, All Names is selected, indicating that all Working-Storage, Linkage, and FD items defined in the Structure view appear in the list.
  3. From the drop-down list in the top, right portion of the screen, select a control type.
  4. Select one or more fields from the list of data items. To select non-contiguous items, hold down the Ctrl key as you click.
  5. When you have selected all of the items that you want to draw on the screen, lift up the mouse button, position the pointer over any of the highlighted fields, then hold down the mouse button while dragging the pointer to the screen form.

    In most cases, when you release the mouse button, the control(s) is/are drawn on the screen. If you have chosen either a radio button control or one of the autoload control types, a second interface appears, allowing you to configure the behavior of the selected control. In these circumstances, when you click OK in the secondary interface, the control is drawn on the screen.

Using Drag-and-Drop to Create Radio Buttons

Radio button controls are used when the user must select one and only one of a series of options. As a result, each individual radio button control is placed within a group, and the run-time ensures that only one member of the group at a time can be selected.

When you use Drag-and-Drop to create a radio button, the initial steps are the same as any other control. You select a control type and a data item, then drag the data item to the screen. When you do this, the Make Radio Button dialog box appears.

This interface represents a group of radio buttons. You add individual radio button controls to the group corresponding to each of the available options.

To add items to the group of radio buttons:

  1. By default, the name of the selected data item appears as the first and only radio button in the group. To change the name of the first radio button to something more descriptive, double-click the field name in the Prompt list and add a more descriptive name.

    The name listed here is assigned as the control’s title, which appears next to the radio button on the screen.

  2. Click the Add button. The Add button is the first of the three buttons just above the Prompt list, on the right side of the interface.
  3. The new radio button is assigned the default name Radio1. As with the first radio button, double-click in the Prompt field to enter a more descriptive name for the button.
  4. Repeat this process until you have added all necessary group items.
  5. When you are finished, click OK. The group of radio buttons that you have described is drawn on the screen. You can now size and position the controls on the screen.
Parent topic: Adding Controls to a Screen


Creating Autoload Controls

As with radio buttons, when you use the Drag and Drop window to create a combo box, grid, or list box, a secondary interface opens. This interface is called the Autoload window.

The Autoload window lets you add or remove data items associated with the control and determine how data items are loaded into the control and displayed at runtime. It is important to note that, unlike other controls created through the Drag-and-Drop interface, autoload controls can be associated only with data items from a data set (defined in an FD). This means that you cannot use the Autoload feature to load a control with data from a table in Working-Storage. In addition, each autoload control can take its data from only a single data set (FD). Autoload controls can only be associated with data sets that are associated with indexed files.

Once an autoload control has been generated, any additional controls created by the autoload (like labels) cannot be changed, because that part of the code will not be regenerated.

If you use the Drag-and-Drop function to create a combo box, grid, or list box and select items from multiple data sets or from non-FD data items, the Autoload interface is not displayed and the generated code associated with autoload controls is not created. A control is drawn on the screen, but the code to load the control is not generated. You must manually add the code needed to load the control.

When you create an autoload control, the list in the bottom, right portion of the Autoload window allows you to customize the code generated to load the control. If you want to read data into a list box control from an indexed file, for example, you can specify a key, a start value, and a read direction, as well as a code to use when certain conditions (AT END, ADD ITEM) are encountered.

When you have finished defining the control data in the Autoload window and click OK, AcuBench draws the control on the screen form. You can then position, resize, or align the control just like any other screen control.

You can create five types of controls using the Autoload function: combo box, grid, list box, paged grid, and paged list box. Note that because the code used to load and navigate through a paged control is quite different from that used with a typical grid or list box, the Autoload function requires you to distinguish between the paged and unpaged styles when the control is created. This means that if you use the control's property sheet to change its STYLE property after autoload code has been created, data will no longer automatically appear in the control, and you may receive compiler errors.

  • Creating an Unpaged Autoload Control
  • Creating a Paged Autoload Control
  • Modifying Autoload Controls
  • Understanding the Generated Code (Unpaged Controls)
  • Understanding the Generated Code (Paged Controls)
Parent topic: Adding Controls to a Screen


Creating an Unpaged Autoload Control

When you create an unpaged control–a combo box, list box, or grid–using the Autoload interface, the list in the bottom, right portion of the window provides a number of ways for you to modify the generated code used to load data into the control at runtime.

The steps are as follows:

  1. Open the Drag and Drop window and click Combo-Box, Grid, or List-Box from the list of controls.
  2. Click one or more fields from a single data set in the list of available data items.

    Note that combo boxes take only a single data field (loaded into a single column of data).

  3. Click OK.

    This opens the Autoload interface.

  4. On the left side of the screen, verify that you have chosen the intended data set and data fields.

    To change data sets, use the arrow keys next to the Source entry-field. To add data fields to the control, select the new field, then click the right arrow symbol. To remove data fields from the control, highlight the item in the Selected list and click the left arrow symbol.

  5. Use the list in the bottom, right portion of the screen, shown here, to determine how the generated code will load data into the control at run-time.

    The interface is similar to that of the Screen Designer Property window:

    You can enter variable names, paragraph names, or condition clauses to be inserted into the AcuBench-generated load paragraph for the control. The options are as follows:

    Option | Description
    Start Key | Specifies which key to use when reading data into the control from a file
    Start Value | The value used to start reading the record. The default is low-value
    Start Value Variable | If you want the start value to vary depending on some condition, you can specify a start value variable. AcuBench adds this variable to Working-Storage and uses it during code generation
    Start Value Variable Pic | The picture clause for the start value variable that you have specified
    Start Direction Determines the KEY clause of the START phrase. By default, the value is >=:
       START filename KEY >= keyname
    Invalid Key Perform | Allows you to specify a paragraph to be performed when an INVALID KEY condition is encountered
    Read Direction | Determines whether a file is read start to end or end to start. The default value is next
    Perform Until Condition | Allows you to enter the end condition for the PERFORM statement used to load the control. Uses the same syntax as the Expression Builder. The default is not valid-filename. valid-filename is an AcuBench-generated file status condition
    End Value Variable | Used with Perform Until Condition to specify when to stop loading information into the control. Enter a variable to be used to determine the end condition for the PERFORM statement used to load the control. AcuBench adds this variable to Working-Storage
    End Value Variable Pic | The picture clause for the end value variable
    At End Perform | Allows you to specify a paragraph to be performed when an AT END condition is encountered
    Not At End Perform | Allows you to specify a paragraph to be performed when a NOT AT END condition is encountered
    Add Item Condition | Creates a condition to determine whether or not to add a record to the control. Uses the same syntax as the Expression Builder
  6. When you have finished making changes, click OK.

    AcuBench draws the control on the screen form.

The code generated to load unpaged controls is generated into the .prd COPY file and should not be modified directly.

Parent topic: Creating Autoload Controls


Creating a Paged Autoload Control

Much of the code for paged controls is generated into the Event Paragraph and made available for direct editing. This code is created once, then left untouched to preserve any modifications that you might make. Because you can customize the code directly, rather than going through a graphical interface, the list in the bottom, right portion of the Autoload window is very simple for paged controls. It contains the only two options that affect the portion of the autoload code generated into the write-protected .prd file.

The initial steps used to create paged autoload controls are similar to the steps used to create unpaged controls, with the following differences:

  1. Open the Drag-and-Drop window and click Paged Grid or Paged List-Box as the control type.
  2. In the Autoload window, you can modify the Start Key selection or add an Invalid Key Perform Paragraph.

    The other options listed for unpaged controls do not appear.

  3. When you are finished, click OK. AcuBench draws the control on the screen form and immediately adds code to the Event Paragraph to control how data is loaded into the control. When you generate your program, a very small amount of additional code is generated in the .prd COPY file to manage some portions of the autoload process for the paged control. The code in the .prd file should not be modified directly.

The code added to the Event Paragraph when the control is drawn on the screen is appended to whatever event code you have already created. To allow you to make free use of this autoload code, AcuBench does not modify or regenerate the code once it has been created. This means that any changes that you make will be preserved when the program is generated. Because AcuBench does not retain control of this code once it has been added to the Event Paragraph, if you delete the control with which the code is associated, you must manually delete the code.

Note that code added to the Event Paragraph for your use is not deleted if you delete the paged control from the screen form. Like event code that you create, the AcuBench-created autoload code must be manually deleted from the Event Paragraph when it is no longer being used.

As a corollary to this, Working-Storage items associated with a paged autoload control must also be manually deleted. Because you are free to make changes to these variables to support modifications to the code in the Event Paragraph, AcuBench does not retain control over these variables and will not delete them.

CAUTION:
If you delete a paged autoload control, but do not delete the associated code in the Event Paragraph, you will receive compiler errors. Also, you must delete any Working-Storage items associated with the deleted control before creating another paged autoload control with the same name. If you do not, undefined behavior is likely to result.
Parent topic: Creating Autoload Controls


Modifying Autoload Controls

Although you cannot change an autoload control's style from PAGED to UNPAGED (or vice-versa), you can customize other aspects of the control's appearance or behavior using the Property window, just as for other controls. You can change the control font, background colors, column sizes, overall height and width, layout data information, event and exception procedures, and so on, without affecting the automatically-generated code used to load the control at run-time.

To make it easier to modify the code generation for controls created using the Autoload window, a special property has been added to the Property window for combo box, grid, and list box controls. This property, Autoload, indicates whether a control has been created using the Autoload feature. If Autoload is set to 1, AcuBench is generating the code to load the control. If Autoload is set to 0, the control is being loaded manually. This special property is used only by the Screen Designer and does not appear in the Screen Section definition for the control. If you have created a control manually, you cannot set its Autoload property to 1 to prompt AcuBench to start generating the code for the control. Instead, open Drag-and-Drop and create a new control using the Autoload feature.

To modify the data portion of a control created through the Autoload interface:

  1. Click the control in the Screen Designer.
  2. In the Property window, next to the Autoload property, click in the Value column.
  3. Click the Browse (...) button to open the Autoload window for the selected control.

    You can now change which fields are displayed in the control, which direction the data file is read, or even which FD is used to read records into the control.

Note that if you make changes to a control's layout that are tied to the data in the control (modifying the text of the heading cells in a grid or changing column widths in a grid or list box), those changes will be lost if you open the Autoload dialog box and change your field selections. Other sorts of property changes, such as selecting a new background color or adjusting the font, are not affected by modifications made through the Autoload interface. Changes cannot be made to additional controls created by the Autoload interface, such as labels.

Parent topic: Creating Autoload Controls


Understanding the Generated Code (Unpaged Controls)

Although the code generated for each control type is different, based on the unique characteristics of the control, the code generated for each of the unpaged controls is very similar. The first example shows the code generated into the Procedure Division (.prd) COPY file for a grid control that takes its data from a data file called clients. The second example shows the code skeleton from which the first sample was generated.

Generated Code Sample: Grid

MOVE LOW-VALUE TO cl-client-id.
START clients, KEY >= cl-client-id
   INVALID KEY
      PERFORM Invalid-Key-Paragraph
END-START.
PERFORM UNTIL NOT valid-clients
   READ clients NEXT RECORD
      AT END
         PERFORM At-End-Paragraph
      NOT AT END
         IF 2>1
            PERFORM Not-At-End-Paragraph
         END-IF
   END-READ
END-PERFORM.
MODIFY clients-gd, MASS-UPDATE = 0.

Generated Code Skeleton: Grid

MOVE [Start Value / Variable] TO [Start Key].
START [Filename], KEY [Start Direction] [Start Key]
   INVALID KEY
      PERFORM [Invalid Key Perform]
END-START.
PERFORM UNTIL [Perform Until Condition] [End Value / Variable]
   READ [Filename] [Read Direction]
      AT END
         PERFORM [At End Perform]
      NOT AT END
         IF [At Item Condition]
            PERFORM [Not At End Perform]
         END-IF
   END-READ
END-PERFORM.
MODIFY [Control-Name], MASS-UPDATE = 0.
Parent topic: Creating Autoload Controls


Understanding the Generated Code (Paged Controls)

The code used to load data into a paged control differs significantly from that used to load data into an unpaged control. In the latter case, all data from the specified source is loaded into the control (and into memory) when the control is displayed on the screen. With a paged control, however, only the data visible in the control (that is, a single page of data) is loaded into memory. This can result in a dramatic performance improvement when the data source contains large numbers of records.

Note that the method used to load data into a paged grid is substantially different from the method used to load data into a paged list box, because of fundamental differences in the control type.

Generated Event Paragraph Code Sample: Paged Grid

* Autoload paged control code generated by Drag-And-Drop
 Screen1-Gd-1-Ev-Msg-Paged-Next.
     PERFORM event-data-2 TIMES
        READ clients NEXT RECORD
           AT END
              MOVE event-action-fail TO event-action
              EXIT PARAGRAPH
        END-READ
     END-PERFORM.
     PERFORM ACU-Screen1-Gd-1-Autoload-Add.
* Autoload paged control code generated by Drag-And-Drop
 Screen1-Gd-1-Ev-Msg-Paged-Prev.
     PERFORM event-data-2 TIMES
        READ clients PREVIOUS RECORD
           AT END
              MOVE event-action-fail TO event-action
              EXIT PARAGRAPH
        END-READ
     END-PERFORM.
     PERFORM ACU-Screen1-Gd-1-Autoload-Load.
     MODIFY Screen1-Gd-1, INSERTION-INDEX=2,
     RECORD-TO-ADD = Screen1-Gd-1-Autoload.
* Autoload paged control code generated by Drag-And-Drop
 Screen1-Gd-1-Ev-Msg-Paged-First.
     MOVE LOW-VALUES TO cl-client-id
     START clients, KEY >= cl-client-id
        INVALID KEY
           MOVE event-action-fail TO event-action
     END-START.
* Autoload paged control code generated by Drag-And-Drop
 Screen1-Gd-1-Ev-Msg-Paged-Last.
     MOVE HIGH-VALUES TO cl-client-id
     START clients, KEY <= cl-client-id
        INVALID KEY
           MOVE event-action-fail TO event-action
    END-START.

Generated Event Paragraph Code Sample: Paged List-Box

* Autoload paged control code generated by Drag-And-Drop
 Screen1-Lb-1-Ev-Ntf-Pl-Next.
     PERFORM Screen1-Lb-1-get-next-item .
* Autoload paged control code generated by Drag-And-Drop
 Screen1-Lb-1-Ev-Ntf-Pl-Prev.
     PERFORM Screen1-Lb-1-get-prev-item .
* Autoload paged control code generated by Drag-And-Drop
 Screen1-Lb-1-Ev-Ntf-Pl-Nextpage.
     MODIFY Screen1-Lb-1, MASS-UPDATE = 1
     PERFORM Screen1-Lb-1-Get-Next-Item
             Screen1-Lb-1-page-size times
     MODIFY Screen1-Lb-1, MASS-UPDATE = 0.
* Autoload paged control code generated by Drag-And-Drop
 Screen1-Lb-1-Ev-Ntf-Pl-Prevpage.
     MODIFY Screen1-Lb-1, MASS-UPDATE = 1
     PERFORM Screen1-Lb-1-Get-Prev-Item
             Screen1-Lb-1-page-size times
     MODIFY Screen1-Lb-1, MASS-UPDATE = 0.
* Autoload paged control code generated by Drag-And-Drop
 Screen1-Lb-1-Ev-Ntf-Pl-First.
     MOVE LOW-VALUES TO cl-client-id
     START clients, KEY NOT < cl-client-id
     END-START.
     SET Screen1-Lb-1-READING-FORWARDS TO TRUE
     MODIFY Screen1-Lb-1, MASS-UPDATE = 1
                          RESET-LIST = 1.
     PERFORM Screen1-Lb-1-get-next-item
             Screen1-Lb-1-page-size times
     MODIFY Screen1-Lb-1, MASS-UPDATE = 0.
* Autoload paged control code generated by Drag-And-Drop
 Screen1-Lb-1-Ev-Ntf-Pl-Last.
     MOVE HIGH-VALUES TO cl-client-id
     START clients, KEY NOT > cl-client-id
     END-START.
     SET Screen1-Lb-1-READING-BACKWARDS TO TRUE
     MODIFY Screen1-Lb-1, MASS-UPDATE = 1
                          RESET-LIST = 1.
     PERFORM Screen1-Lb-1-get-prev-item
             Screen1-Lb-1-page-size times
     MODIFY Screen1-Lb-1, MASS-UPDATE = 0.
* Autoload paged control code generated by Drag-And-Drop
 Screen1-Lb-1-get-next-item.
     EVALUATE TRUE
         WHEN Screen1-Lb-1-at-start
             MOVE low-value to cl-client-id
             START clients, key not < cl-client-id
             END-START
             ADD 1 to Screen1-Lb-1-page-size
                 GIVING Screen1-Lb-1-number-reads-needed
         WHEN Screen1-Lb-1-at-end
              EXIT paragraph
         WHEN Screen1-Lb-1-reading-backwards
              MOVE Screen1-Lb-1-page-size to
                   Screen1-Lb-1-number-reads-needed
         WHEN Screen1-Lb-1-reading-forwards
              MOVE 1 to Screen1-Lb-1-number-reads-needed
     END-EVALUATE.
     PERFORM Screen1-Lb-1-number-reads-needed times
        READ clients next record
             AT END
                SET Screen1-Lb-1-at-end TO TRUE
                EXIT PARAGRAPH
        END-READ
     END-PERFORM.
     INITIALIZE Screen1-Lb-1-Autoload
     PERFORM Acu-Screen1-Lb-1-Autoload-Load
     MODIFY Screen1-Lb-1, item-to-add = Screen1-Lb-1-Autoload
     SET Screen1-Lb-1-reading-forwards TO TRUE.
* Autoload paged control code generated by Drag-And-Drop
 Screen1-Lb-1-get-prev-item.
     EVALUATE TRUE
        WHEN Screen1-Lb-1-at-end
           MOVE high-value to cl-client-id
           START clients, KEY NOT > cl-client-id
           END-START
           ADD 1 TO Screen1-Lb-1-page-size
                 GIVING Screen1-Lb-1-number-reads-needed
        WHEN Screen1-Lb-1-at-start
           EXIT paragraph
        WHEN Screen1-Lb-1-reading-forwards
           MOVE Screen1-Lb-1-page-size TO
                Screen1-Lb-1-number-reads-needed
        WHEN Screen1-Lb-1-reading-backwards
           MOVE 1 TO Screen1-Lb-1-number-reads-needed
     END-EVALUATE.
     PERFORM Screen1-Lb-1-number-reads-needed times
        READ clients previous record
           AT END
              SET Screen1-Lb-1-at-start TO TRUE
              EXIT PARAGRAPH
        END-READ
     END-PERFORM.
     INITIALIZE Screen1-Lb-1-Autoload
     PERFORM Acu-Screen1-Lb-1-Autoload-Load
     MODIFY Screen1-Lb-1, insertion-index = 1
     ITEM-TO-ADD = Screen1-Lb-1-Autoload
     SET Screen1-Lb-1-reading-backwards TO TRUE.
Parent topic: Creating Autoload Controls


Configuring Control Properties

When you select a control in the Screen Designer, the Property window lists the control's name and all of the properties currently associated with that control. The properties listed vary according to the control type, so the properties listed for a bitmap control, for example, are going to be very different from the properties listed for an entry field.

When you select multiple controls in the Screen Designer, the Property window lists only those properties that apply to all of the selected controls. If you change one of these properties, the change is applied to every one of the selected controls.

The default Property settings for each control type, as well as the properties that appear in the Property window, can be configured through the Tools > Options interface, as discussed in Establishing Screen and Control Defaults.

Detailed information about all of the available control properties can be found in ACUCOBOL-GT User Interface Programming.

To change control property settings in AcuBench:

  1. In the Screen Designer, select the control on the screen form. The control name appears in the drop-down list at the top of the Property window.

    Note that if you have selected multiple controls, only the name of the last control selected is shown.

  2. Use the Alphabetic or Categorized tab of the Property window to scroll through the available properties and find the one you wish to change.
  3. Click in the Value column next to the property description to change the control’s property settings. In some cases, this activates an entry field in which you can type the new value. In other cases, you may select the value from a drop-down list, or click a browse (...) button to open a secondary interface used to specify a property value. In general, the first property changed for each control is the (Name) property from the AcuBench default to something more descriptive. As with the screen itself, this (Name) property is used to assign a control name used to refer to the control programmatically. AcuBench also uses this value to construct the default names for paragraphs and variables associated with the control, so assigning a descriptive name plays an important role in keeping your code readable and intuitive. If you are tempted to skip this step and use the default names, imagine trying to code a screen full of entry fields called Screen1-Ef-1, Screen1-Ef-2, Screen1-Ef-3, and so on. Now imagine an entire application full of screens and fields using that same default naming convention.
  • Associating Data with a Control
  • Layout Data Control Property
  • Controls: Related References
Parent topic: Working with Screens


Associating Data with a Control

When you use the Drag and Drop interface, controls that you draw on the screen are automatically associated with data items, usually from graphical Working-Storage or from a data set. You can also manually associate a value or variable with a screen control.

In the Screen Section, the VALUE property determines what data, if any, is associated with a given control. In the AcuBench Screen Designer, two Property window items are associated with this property. The Value property entry is used to set a fixed, initial value shown in the control when in the screen is displayed. The Value Variable property is used to tie the control to a variable data item, which may or may not contain a value when the screen is displayed. When these two properties are both set, the Value property is used to set the initial value for the specified Value Variable.

If you need to change the Exception Variable and the Exception Value, make sure that you change the Exception Variable first and then the Exception Value, because that might cause the Exception Variable to disappear from Working Storage.

To associate a variable with a control without using the Drag and Drop interface:

  1. In the Screen Designer, select a control on the screen form.
  2. Scroll through the Property window until all four value properties (Value, Value Multiple, Value Picture, and Value Variable) are visible.
  3. Click in the Value column of the Property window next to the Value Variable listing and do one of the following:
    • To create a new Working-Storage variable associated with the selected control, type a variable name in the field. When you tab or click away from the field, AcuBench automatically adds the new variable to graphical Working-Storage.
    • To select from a list of variables already assigned to other controls on the screen, expand the drop-down list and choose a value.
    • To select from a list of data items associated with your program’s data sets, graphical Working-Storage, and so on, click the browse (...) button and select an item from the interface.
  4. When you make an entry for the Value Variable property, the Value Picture property is updated to reflect the PICTURE clause associated with that variable.

    If you have entered a new variable name, a default value appears in this field. To change the value, click in the Value column next to the Value Picture property and enter a new value. AcuBench automatically updates the variable definition in graphical Working-Storage.

  5. If you want to set an initial value for the specified variable, click in the Value column for the Value property and enter the appropriate literal value.

If you select an entry field, for example, and assign a Value Variable property of ws-name, a Value Picture property of X(30), and a Value property of <Enter Name Here>, AcuBench generates the following code:

  • In graphical Working-Storage (and the .wrk COPY file):
    77 ws-name PIC X(30) VALUE IS "<Enter Name Here>".
  • In the .scr COPY file:
    03 main-scr-name-ef, Entry-Field, ...
   VALUE ws-name.
Parent topic: Configuring Control Properties


Layout Data Control Property

As mentioned in Creating a Resizable Screen, when you want the resize layout manager to change a control's appearance when a screen is resized, you set that control's Layout Data property to a non-zero value. The different Layout Data property values and how they affect a control's behavior are described in Resize Manager LAYOUT-DATA Values. When Layout Data is the default value of 0, no code is generated.

In AcuBench, these values are set via the Layout Data Settings dialog box, which you access by clicking in the Layout Data value box in the Property window.

Note that you can set either a resize or a move value for each axis (x or y), but you cannot set both values for any axis. Minimum and maximum dimensions for a control (height and width) are also set in this dialog box. See Minimum and Maximum Control Dimensions for detailed information about these settings.

Parent topic: Configuring Control Properties


Controls: Related References

In most instances, controls are simple to create and manage. In some cases, however, they are complex. In addition to the information contained in this chapter, detailed information pertaining to Property window items is located in the following volumes and chapters in the ACUCOBOL-GT documentation set:

  1. Graphical Controls provides an overview of controls. It also describes the creation and use of bitmap buttons and the general use of paged list boxes.
  2. Supporting Concepts and Related Issues, contains background material concerning issues related to the creation of controls and screens.
  3. Control Types Reference describes individual controls in detail, including styles and properties and how they can be set. It also lists the events that can be associated with each control.
  4. Events Reference describes in detail the events that can be generated when you use windows and controls in an event-driven environment.
  5. Screen Description Entry contains syntax rules and general rules for the components of a screen description entry.
  6. Common Screen Options describes options that are common to Screen section entries and the ACCEPT, DISPLAY, and MODIFY verbs. It also includes the phrases used to specify a control's common properties.
  7. Procedure Division Statements contains the DISPLAY control-type format of the DISPLAY verb. It also contains syntax and general rules for the use of this DISPLAY verb format.

A general overview of ActiveX and OLE programming issues appears in Using ActiveX Controls and COM Objects.

Parent topic: Configuring Control Properties


Positioning and Aligning Controls

Once you have added controls to your screen, you can use arrow-key shortcut combinations, the Align menu, or the Align toolbar to fine-tune the size and position of those controls.

You can use the following keystrokes to position and resize controls:

  • Use the left, right, up, or down arrow controls to move the selected control(s) one pixel at a time in the specified direction.
  • Hold down the Ctrl key and use the arrow keys to move the selected control one cell at a time in the specified direction.
  • Hold down the Shift key and use the arrow keys to resize the control one pixel at a time (the up and down arrows move the bottom border of the control, making the control taller or shorter; the left and right arrows move the right border of the control, making it wider or narrower).
  • Hold down the Ctrl and Shift keys and use the arrow keys to resize the control one cell at a time.

When you use most of the Align commands, a group of selected controls is repositioned in relation to the last control selected, known as reference control. The reference control is marked by the small, dark blue boxes (handles) on the control frame. (The handles on other selected controls are white, with a blue border.)

The Align commands that adjust controls in relation to one another include:

  • Make Same Size (Width, Height, or Both) , used to resize all of the selected controls to the width, height, or width and height of the reference control. From left to right, these are the third, forth, and fifth buttons on the Align toolbar.
  • Align Control (Left, Right, Top, or Bottom), used to align the selected controls to the left, right, top, or bottom border of the reference control From left to right, these are the sixth through ninth buttons on the Align toolbar.
  • Space Evenly (Across or Down), used to adjust controls so that a consistent amount of horizontal or vertical space appears between the selected controls. This control is enabled only when three or more controls are selected.
  • Adjacent (Horizontal or Vertical), used to align the selected controls so that the borders of the controls are immediately adjacent to one another in either the horizontal or vertical direction. This is useful, for example, in positioning buttons on a toolbar. These options appear just to the left of the Lock button on the Align toolbar.

The Align commands that can be used to position either a single control or multiple controls include:

  • Align Control (Center Horizontal, Center Vertical, or To Grid), used to center one or more controls on the screen, or to align the control(s) to the closest grid point on the screen form. Center Horizontal and Center Vertical are the first two buttons on the Align toolbar; Align To Grid appears just to the right of the Align Bottom button.
  • Lock Controls, a toggle switch used to lock controls in place on the screen form so that they cannot be accidentally moved, or to unlock controls to allow further positioning. A locked control cannot be dragged, centered, or sized, nor can it be used as the dominant control when a group of controls is selected. The selection handles on a locked control are white instead of dark colored.
  • Size to Content, used to adjust the borders of the control to match the content of the control. This is frequently used with controls like labels and radio buttons to match the control precisely to the size of its label, eliminating unused space. This option does not appear on the Align toolbar, but does have a keyboard shortcut: Shift+F7.

By default, when you work in the Screen Designer, a grid of dots appears on the screen form to help you to position your controls. The size of each square in this grid corresponds to the screen's CELL SIZE property (by default, 10 pixels by 10 pixels). You can toggle whether or not this grid is visible with the View Grid command, accessed through the Align menu or toolbar. To help you place items on this grid, you can enable a set of control positioning guides with the Toggle Guide command. These positioning guides become visible when you click a control on the screen form, or click to draw a control on the screen.

Parent topic: Working with Screens


Refining Your Screen

As you work with and refine your screen, a number of useful editing functions are available to help you as you work. Most of these functions, like Undo/Redo or Cut/Copy/Paste, can be invoked with keyboard shortcuts. You can also use the Edit menu or the Screen Designer right-click pop-up menu to access most editing commands.

Remember that most keyboard shortcuts can be customized through the Tools > Options interface, as discussed in Configuring Keyboard Shortcuts.

Keep in mind that you can use the Tab key to navigate through the controls in your screen. Press Tab to move through the controls on the screen from lowest tab order number to highest. Press Shift+Tab to move backward through the controls. Screen control tab order is discussed in more detail in Determining Control Tab Order.

  • Basic Editing Commands
  • Determining Control Tab Order
Parent topic: Working with Screens


Basic Editing Commands

AcuBench uses the standard set of commands and keyboard shortcuts to invoke basic editing commands. These commands include the following:

  • To reverse your most recent action, choose the Edit/Undo (Ctrl+Z) command. You can restore the action that you reversed by choosing Redo (Ctrl+Y). The workbench supports multiple undo and redo actions, in reverse order until the last save performed.

    You can also use the Undo and Redo buttons on the Standard toolbar.

  • To cut and copy controls to the clipboard, select the control(s) that you want to cut or copy and choose the Edit/Cut (Ctrl+X) or Edit/Copy (Ctrl+C) commands. Cut removes the control from the screen and places it on the clipboard. Copy adds a duplicate of the selected control to the clipboard.
  • After you cut or copy a control to the clipboard, you can paste it to a screen form (Edit/Paste or Ctrl+V). If you paste the control from one screen form to another, the control is placed in the same location on the new screen that it occupied on the original screen. After pasting a control, you can move it to any location in the screen form.

    A pasted control retains many of the original control’s properties. However, it does not retain such unique properties as ID, name, and tab order. The Screen Designer assigns default unique properties, which you can change.

    After pasting multiple, identical controls, you can quickly change an individual property value so that it is unique for each control copy. Select all the control copies that you want to have unique variable names (for example, select five identical entry fields) and change the desired variable name in the Property window. AcuBench detects the multiple selection and asks if you want to give each selected control a unique name for that property. With a Yes response, AcuBench automatically increments the number in the variable name for each control so it is unique.

Parent topic: Refining Your Screen


Determining Control Tab Order

Control tab order is determined by the order in which controls are drawn on the screen. The first control that you draw is assigned a tab order of 1, the next is given tab order number 2, and so on. These tab order numbers correspond to the order in which controls appear in the Screen Section definition for the screen.

When a user presses the Tab key to move through the screen, tab order determines the default behavior for moving the cursor. Unless you have defined alternate behavior for the Tab key (or otherwise added special keystroke handling code), when the user presses Tab, the cursor moves to the next ACCEPT field on the screen.

As you cut, paste, and move controls around a screen form in the Screen Designer, you are likely to need to make adjustments to the controls' tab order. These changes can be made quickly and easily through the Reset Controls' Tab Order dialog box.

To view and adjust controls’ tab order, do the following:

  1. Select the Tab Order command from the Screen Designer right-click menu or the Align menu to open the Reset Controls’ Tab Order dialog. (You can also use the Ctrl+D keyboard shortcut.)

    The dialog box lists all of the controls on your screen in tab order, next to the tab order number.

    The tab order numbers also display on the screen design form.
  2. Change the tab order on your screen by selecting a control and using the up and down arrows.

    Note that changing the tab order also changes the order that controls appear in the Screen Section. In other words, the user tabs through controls on the screen in the order that those controls appear in the program’s Screen Section definition.

  3. You can also use the Send to Back and Send to Front commands in the Screen Designer right-click pop-up menu. Send to Back gives the selected control the lowest tab order number, reordering all other controls accordingly. Send to Front gives the selected control the highest tab order number. These controls are not enabled when more than one control is selected.

Note that if you create a frame and place controls inside that frame, the tab order within the frame exists exclusively of the controls outside of it. In this instance, you cannot create a tab order outside of a frame and continue it inside of the frame. The tab order inside of the frame starts at 1. You can, however, change the tab order within the frame itself. Tab order is continuous if you draw a frame around controls that already exist.

Parent topic: Refining Your Screen


Associating Code with Screen Elements

Once you have added controls to the screen form and made any necessary configuration changes, the next step is to add the code to make the user interface function. The Screen Designer interface used to associate code with screens and screen controls is the Event Editor.

The Event Editor interface is very similar to that of the Code Editor. The main visible difference is at the top of the Event Editor window, where three fields indicate the screen element to which the code applies, the type of code being associated with the screen element, and the name of the paragraph containing that code.

You can use these fields to navigate through the Event Editor, to list the code paragraphs already associated with a given screen element, or to create a new paragraph associated with the screen element.

  • Entering the Event Editor
  • Event Procedures, Embedded Procedures, and Code Insertion Points
Parent topic: Working with Screens


Entering the Event Editor

When you are working in the Screen Designer, the most straightforward way to use the Event Editor is often through the Event tab of the Property window. The Event tab lists all of the event, exception, and embedded procedures associated with the selected screen element type, as well as any AcuBench code insertions points defined for the screen element. These procedures and insertion points are discussed in the next section.

To enter the Event Editor from the Event tab of the Property window:

  1. Select a screen element in the Screen Designer.
  2. Expand the Event Procedure or Exception Procedure tree, if necessary, and select a procedure type.
  3. Click in the Value column next to the procedure type, then click the browse (...) button.

    An Add Paragraph dialog opens in the foreground, while the Event Editor opens in the background.

  4. Enter a name for the paragraph you plan to create, then click OK. To enter the Event Editor without creating a paragraph, click Cancel.
  5. The fields at the top of the screen show the selected control, procedure type, and paragraph name. You can now begin entering code.

You can also enter the Event Editor at any time by double-clicking the Event Paragraph node for any program in the Structure view. If you open the Event Editor using this method, the fields at the top of the screen remain blank.

In some cases, you can enter the Event Editor by double-clicking a control on a screen form in the Screen Designer. In these cases, the Add Paragraph dialog appears, indicating the default paragraph type associated with the selected control. Edit the paragraph name as desired and click OK to enter the Event Editor. (If you click Cancel, no paragraph is created, but you still enter the Event Editor.)

Parent topic: Associating Code with Screen Elements


Event Procedures, Embedded Procedures, and Code Insertion Points

The procedures and code insertion points listed on the Event tab of the Screen Designer Property window vary according to the type of control selected. Display-only controls, such as bars, frames, and entry fields, for example, do not have any procedures or code insertion points associated with them. In general, the more complex the control (and therefore the more ways a user can respond to a control), the more event and exception procedures can be associated with a control.

If you select a screen, for example, and expand the list in the Event tab of the Property window, you see the following procedures and insertion points:

The code insertion points are unique to AcuBench screens. These procedures (Before Create, After Create, Before Initdata, After Initdata, Before Routine, and After Routine) can be defined and inserted around generated code paragraphs. Before Create code that you define, for example, is performed just before the AcuBench-generated DISPLAY code for the screen. You might insert a paragraph here to load the data you want to see when the screen is displayed. After Initdata code is performed just after the AcuBench-generated Initdata code used to define the data structure for complex screen controls, like combo boxes, grids, and tree view controls. You might insert a paragraph here to manually load data into any of these controls.

Event, exception, and embedded procedures, on the other hand, can be assigned to ACUCOBOL-GT screens and controls regardless of whether or not you are working in AcuBench. These procedures follow the structure and rules discussed in Events Reference and Data Division.

One special AcuBench embedded procedure type is the Link-To paragraph. A Link-To paragraph is a way to assign a specific exception value to certain screen elements. When a user clicks a screen element that has a Link-To value assigned, the specified exception is sent to the program, which then performs the procedure associated with that exception.

Both Link-To and Cmd-Clicked procedures are invoked when the user clicks a screen element. In the former case, a manually-assigned exception value is generated, updating the Key-Status data structure and invoking a procedure associated with the specified value.

        WHEN Key-Status = 211
           PERFORM Client-Scr-Pets-Pb-Link

When a Cmd-Clicked exception procedure has been assigned to a screen element and a user clicks the control, an Event-Occurred message (exception value 96) is sent to the program, which then determines which control generated the exception, which event actually occurred, and whether or not a procedure exists to respond to that event.

Parent topic: Associating Code with Screen Elements


Working with Screen Templates

When you create a new screen in the Screen Designer, the default New Screen interface provides you with a list of default screen templates (like Standard Graphical and Blank Character). In addition to these defaults, you can create and use your own screen templates. When you create screen templates, you have the option to either add them to the New Screen dialog box (as described in Adding Screen Templates ), or to access them with the Add Screen command.

The process used to create a screen template file (.stf) is very straightforward. First, use the Screen Designer to create a screen, as usual. When you are finished, right-click the screen form and select Generate STF Document. In the Save As dialog box, navigate to the folder where you want your template stored.

If you elect not to add your template to the New Screen dialog box, you can use the Add Screen command to create a new screen based on a template. To do this:

  1. In the Structure view, right-click the Screen icon and select Add Screen.
  2. In the Add Screen to Program dialog, navigate to the directory containing your screen template, select the .stf, and click Open.

    The new screen opens in the Screen Designer.

When you use the New Screen interface to select a template and create a new screen, you have the option to change the screen's name and unique prefix at the start. When you use the Add Screen command, however, your new screen is assigned the same name and unique prefix that you used when you designed the template. As a result, your first step after using the Add Screen command should be to change the screen name in the Property window. This will also update the screen's unique prefix to match up to the first ten letters of the screen name. To assign an alternative unique prefix, right-click the screen form and select Change Prefix. When you change a screen’s unique prefix in the Change Prefix dialog, you can choose whether or not the changed prefix is assigned to existing controls.

Parent topic: Working with Screens


Generating a Screen

As discussed in Program Tag Options, when you create an AcuBench program that includes a program structure file, AcuBench adds tags to the source (.cbl) file to indicate the placement of generated code. When you design a screen, then use the Build > Generate command to generate COBOL code, AcuBench uses these tags to add the Screen Section, Working-Storage, and Procedure Division code needed to display the screen and make it function. If you are using the default code generation options (generating code into multiple COPY files), you will see several COPY statements added to the source file. These refer both to AcuBench-generated COPY files and to the ACUCOBOL-GT definition files used for screen handling.

Depending on the elements that you have added to your screen, the generated COPY files may include a Screen Section COPY file (.scr), an event paragraph file (.evt), and a menu paragraph file (.mnu). The code generation process will also add screen DISPLAY and ACCEPT information to the Procedure Division file (.prd), and update the Working-Storage file (.wrk).

AcuBench generates the Procedure Division code needed to DISPLAY and ACCEPT each screen in your program. This code is invoked through an Acu-screen-Routine paragraph. AcuBench automatically generates the code needed to invoke this routine for the program's main screen at startup. You add the code needed to perform the appropriate screen routine for each of the other screens in your program.

See Testing Screens for information about invoking secondary screens in a program without the need to write code.

Parent topic: Working with Screens


Testing Screens

When you want to view and interact with the screen you have designed, use the Build > Execute command. If there are multiple screens in your program, AcuBench generates the code to execute just one of them. Although Screen Section entries and DISPLAY statements are added to the generated code for every screen, only the first screen's code is executed automatically. To test additional screens, you have two options:

  • Add code, associated with a push button or other control, to call the remaining screens in your program:
    PERFORM Acu-LookupScreen-Routine.
  • Use the Program Properties interface to change the main screen for the program. AcuBench generates the code to execute whichever screen is currently set as the main screen.

To change the default screen displayed at runtime:

  1. Right-click the program node in the Structural view and select Properties.
  2. Under On program startup, set main screen to, select a screen from the drop-down list.
  3. Click OK to save your changes. When you execute your program, the selected screen is displayed.
Parent topic: Working with Screens


Creating a Logo Screen

You have the option to define a logo screen—often called a splash screen—for each AcuBench program that you create. A logo screen is displayed briefly before the program's main screen is displayed. As its name implies, a logo screen is often used to display a company or application logo.

When you design a logo screen in the Screen Designer, AcuBench can generate the code to automatically display the screen for a specified period of time before showing the main screen.

  1. Right-click the program node in the Structure view and select Properties.
  2. On the General tab of the Program Properties window, under On program startup, set logo screen to, select a screen from the combo-box.

  3. Use the Display Time entry field to specify how long the logo screen will be displayed before the main application window appears. You can specify a value between 1 and 300, indicating a display time between 1 and 300 seconds.
  4. Click OK.
Parent topic: Working with Screens


Creating Dual User Interfaces

It is possible to have both character-based and graphical screens in the same program. Moreover, for each screen in your user interface, you can have both a graphical and a character-based version, each with the same name. When two versions of a screen with the same name appear in the same application, the run-time chooses which to display based on the capabilities of the run-time environment.

To facilitate the process of creating a dual graphical/character interface for your programs, the Screen Designer allows you to copy screen items between graphical and character-based screen forms. You can lay out a screen on one type of screen form, then copy and paste all of the controls onto the other type of screen form.

When you copy and paste controls between screen types, however, there are some considerations to keep in mind:

  • Graphical screen elements use pixels for positioning, while character screen elements use cells. This means that when an item is moved from one screen type to the other, the positioning will not remain exactly the same.
  • Graphical screens can contain more types of screen elements (including toolbars, bitmaps, and so on) than character screens. Graphical screen elements cannot be copied onto character screens.
Parent topic: Working with Screens


Controls, Menus, and Toolbars

  • Introduction
  • Standard Controls
  • ActiveX Controls
  • Using the Menu Designer
  • Using the Toolbar Designer
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

This chapter provides more detail about the controls and other screen elements that can be used to create a user interface in the AcuBench Screen Designer. It starts with an overview of the ACUCOBOL-GT standard controls, then discusses the basics of ActiveX controls. Next, it talks about the process of adding menus and toolbars to your screens. (Both character-based and graphical screens may include a menu; only graphical screens can include a toolbar.)

The information contained in this chapter is supplemental to the information in Books 2 and 3 of the ACUCOBOL-GT documentation set pertaining to menus, graphical controls, and toolbars. In most cases, this chapter focuses on the AcuBench-specific aspects of using the various screen elements, although some more general principles are included.

  • Properties of Screen Elements
  • Events Overview
Parent topic: Controls, Menus, and Toolbars


Properties of Screen Elements

All components of a screen element are properties. When we talk about screen controls, these properties are classified into two groups: common properties and special properties. Common properties apply to many types of controls, and include:

size | title | value
color/intensity | font | visible/invisible
enabled/disabled | ID |

Note that some common properties have a special meaning (or no meaning) for some control types. (A bar control, for example, wouldn't have a title, value, or font.)

Each control also has its own set of special properties. Special properties give a control a special attribute or capability. For example, an entry field can have the special properties Max-Text or Max-Lines, which determine how many characters or lines of information users will be permitted to enter in that field. All special properties require a value. Max-Text, for example, takes a numeric value that specifies the maximum number of characters that can be entered in the field. Some special properties are used by more than one control type. For example, the special properties that apply to bitmap buttons are also used by the push button, radio button, and check box controls.

Styles are a special type of property that affects the appearance or behavior of a control. For example, some of the styles that apply to a radio button include Bitmap, Framed, and Notify. Styles do not take a value. Most styles apply to only a certain type of control, although a few are common to all controls.

The process of setting control properties is discussed in Configuring Control Properties.

Parent topic: Introduction


Events Overview

In addition to setting appearance and behavior properties of a screen item, you can associate code with the item to determine its functionality. Just as each screen element is associated with a certain set of properties, it is also associated with a certain set of events. An event is a user action to which the screen item is capable of responding. If a user enters information into an entry field, for example, the entry field is capable of recognizing each keystroke that the user types as a Notify-Changed event. Likewise, a push button control can recognize a mouse click as a Command-Clicked event. You can choose to capture these events and write code to respond appropriately to the user action.

In AcuBench, the Event tab of the Property window provides an interface that both lists the events to which a given control can respond and allows you to enter code to handle that event. For more information about adding event code in AcuBench, see Associating Code with Screen Elements. For a more general discussion of events and event handling, see ACUCOBOL-GT User Interface Programming.

Parent topic: Introduction


Standard Controls

When you are working in the Screen Designer, the Screen Component Toolbox lists the standard and ActiveX controls available for use. If you are working with a graphical screen, all of the standard controls are available for you to use. If you are working with a character-based screen, those controls that are available only with graphical windows appear disabled in the Screen Component Toolbox. The sections that follow provide summary descriptions of each of the standard controls.

When you are working with ActiveX controls, the list of controls that appears in the ActiveX portion of the Screen Component Toolbox depends on which controls you have installed and registered. A detailed description of an ActiveX control can usually be found in the vendor documentation that accompanies it. More information about programming with ActiveX controls can be found in Working with Windows Technologies.

The size and location of most controls on a screen form can be changed. To change the size, click the control to select it, then drag a corner of the handle that appears. You can also use the keyboard shortcuts Shift+Arrow and Ctrl+Shift+Arrow to change the size of a control or window. To change a control’s location, click the control and drag it to the desired position on the screen form. You can also use the arrow keys or the Ctrl+Arrow keyboard shortcut to move items on the screen form. Note that status bar size and location cannot be changed. A status bar automatically grows and shrinks horizontally to match the width of the owning window.

  • Selector
  • Bar
  • Bitmap
  • Check Box
  • Combo Box
  • Date Entry
  • Entry Field
  • Frame
  • Grid
  • Label
  • List Box
  • Push Button
  • Radio Button
  • Scroll Bar
  • Status Bar
  • Tab
  • Tree View
  • Web Browser
Parent topic: Controls, Menus, and Toolbars


Selector

When you first open the Screen Designer, the Selector is highlighted in the Screen Component Toolbox and the mouse pointer is a white arrow.

When you select any control in the Toolbox and move the mouse to the screen form, the mouse pointer becomes a crosshairs. After you draw a control on the screen, the mouse pointer returns to being an arrow, and the Selector icon appears highlighted in the Toolbox. When the Selector is chosen, you can select, move, and resize controls already drawn on the screen form.

If you have selected a control type in the Screen Component Toolbox and decide that you don't want to draw that control on your screen, you can cancel your selection by clicking the Selector icon.

Parent topic: Standard Controls


Bar

The bar control allows you to draw a horizontal, vertical, or diagonal bar in the screen form at design time.

Parent topic: Standard Controls


Bitmap

Available only in graphical environments, a bitmap is a graphic (*.bmp, *.jpg, *.jpe, or *.jpeg) that can be added to a screen in order to enhance its appearance, for example, or to add a company logo. A bitmap can also be added to a push button, radio button, or check box control.

A bitmap control is rectangular and non-transparent by default. To display a bitmap so that it appears non-rectangular, or to make sure that some portion of a bitmap matches the background color of the screen, use the Transparent Color property. In the Property window, click the button next to the Transparent Color property to open the Choose Transparent Color dialog box. As you move your mouse over the bitmap, the dialog box shows the RGB value of the current color. When you click a spot on your bitmap, the color of that spot is set as the transparent color, and when the program executes, that color does not appear (in other words, the background color of the screen shows through). For more information about bitmaps and the Transparent Color property, see Control Types Reference.

Parent topic: Standard Controls


Check Box

A check box control includes a selection box and a text label. When a user selects the control, a check mark appears in a check box. Typically, check boxes are used when you need to provide the end user with a limited number of choices from which any number may be selected, or when you want to present the end user with an option that may be turned on or off. Check boxes are also used to give the end user a Yes/No or True/False option.

Parent topic: Standard Controls


Combo Box

A combo box is an input control that combines a list box and an entry field. Typically, it contains several options in the list portion of the combo box, and the end user can select the needed option with the mouse pointer, or write the needed option in the entry field portion of the combo box. You can create three kinds of combo boxes: drop-down (users can type in the entry-field portion of the control and use a button to reveal the list, which is otherwise hidden), drop-list (users must make a selection from the drop-down list and cannot type in the entry-field), and static list (the list is permanently displayed on the screen).

When you draw a drop-down or drop-list combo box control in the Screen Designer, remember to include space for the data in the list. In other words, do not draw the control exactly the size of the entry-field portion of the control. Instead, select the control and drag the selection handle downward, leaving an “empty” space under the control. If this extra space overlaps other controls on the screen form, when users expand the list at runtime, it temporarily overlaps the other control.

Parent topic: Standard Controls


Date Entry

Available only in Microsoft Windows environments, the date entry control provides a convenient way for users to enter date or time values. Depending on the format that you choose, the date entry may include a graphical calendar from which users can select a date.

Four standard date and time formats are listed for the Display Format property in the property sheet for the control. You can also enter a custom Display Format for the control, combining various date and time elements.

Note: Although the property sheet lists a Short-Date value format of YYMMDD, the actual Short-Date format is dependent on Windows operating system settings. See Control Types Reference for more information.

Some restrictions apply to the use of this control. See Control Types Reference for details about the styles and properties available for this control.

Parent topic: Standard Controls


Entry Field

An entry field control is used for accepting data from the end user, such as multiple lines of text. Typically, it is the field where an end user enters information, such as a name and address. You can create either single line or multiline entry fields in the Screen Designer.

Parent topic: Standard Controls


Frame

A frame control is a box used for grouping related controls together. You can put controls into frames to visually separate them from other controls or to group related controls together. For example, it is a common practice to enclose radio button groups within a frame.

When you draw controls directly on a frame, you cannot drag them out again. They are grouped inside of it. This allows you to move a frame and have the controls remain inside of it.

When you create a frame first and then add controls into it, you can copy and paste those controls within it. Note that if you select this frame and delete it, the controls are also deleted. If you create controls first and then put a frame around them, however, you cannot select the controls within that frame to copy and paste or move them, unless you move the frame away from the controls. You can delete this frame without deleting the controls inside.

When users tab through controls on a screen, the order of the cursor movement depends on the tab order established for those controls. When you create controls inside a frame control, the tab order of the frame control itself is part of the tab order for the entire screen, but items within the frame have their own, distinct tab order. The tab order for controls inside of each frame starts at 1 in the Property window. To change the tab order of controls within a frame, right-click the frame and select Tab Order.

Parent topic: Standard Controls


Grid

Available only in graphical environments, the grid control is a two-dimensional table of data fields. Each element of this table, called a cell, can hold text, a bitmap, or both. Grids are relatively complex controls with many properties that you can use to customize their appearance and behavior.

Grids are organized into rows, columns, and records. In a grid, a row is a grouping of cells that appear on one line in the control. A record is one or more rows that are treated as a logical unit. A column identifies a particular cell in a record. By default, a record occupies one row in a grid, but you can arrange for a record to wrap around to the next row when it passes the right edge of the grid. When this occurs, a record occupies more than one row in the grid. You might want to construct a grid like this when you want to see many fields in a data record at once. Alternatively, you can have the grid use scroll bars to access cells past the right edge of the control. Column, row, and record numbers all start at 1.

Grids come in two formats: with horizontal scrolling and without. When you opt for horizontal scrolling, each record may occupy only one row in the grid. Grids with horizontal scrolling appear much like a spreadsheet. Without horizontal scrolling, a record may occupy more than one row. In either case, vertical scroll bars appear automatically when needed.

The grid operates in two different modes: navigate mode and entry mode. While the grid is in navigate mode, the arrow keys move the cursor around the grid. This mode is the default. The grid shifts to entry mode when the user starts to modify data. In this mode, the arrow keys are used to edit the current cell's data. When the user finishes a cell, the grid returns to navigate mode.

The exact set of keys understood by the grid depends on the host system. Under Windows, the following keys are used in navigate mode:

Up/Down arrow | Moves the cursor to the same column in the previous/next record
Left/Right arrow | Moves the cursor to the previous/next column in the record
Home | Moves to the first column in the record
Ctrl+Home | Moves to the first column of the first record
Page up/Page down | Moves the cursor up/down one page
Shift+Enter | Moves the cursor to the first column of the next record
Tab (with USE-TAB) | Moves the cursor right, wrapping to the next record when at the last cell in the record
Backtab (with USE-TAB) | Moves the cursor left, wrapping to the previous record when at the first cell in the record
End | Moves to the last column in the record
Ctrl+End | Moves to the first column in the last record
Enter | Shifts to entry mode for the current cell; highlights the contents for editing
Any printable character | Shifts to entry mode for the current cell; overwrites the contents with the character

When the grid is in entry mode, the user types into an entry field control. All of the editing keys usable by an entry field are usable here. The user leaves entry mode by typing Enter or Tab/Backtab, or by clicking another cell with the mouse.

Clicking a mouse on a cell moves the cursor to that cell. Clicking the selected cell shifts to entry mode. So double-clicking any cell has the effect of modifying that cell's contents. The first click moves the cursor and the second click shifts modes.

You should note that the Property window Value cell for the Row-Dividers property accepts only a single digit. You cannot enter multiple values in the workbench for Row-Dividers.

Paged Grid

Sometimes you may want to use a grid control to view a large number of records. When this is the case, a normal grid is impractical. Just loading all the records into the grid could take an excessive amount of time. To handle this case, the grid supports a Paged style. When you use this style, the grid holds only as many records as can be seen on the screen. This is called a page of data. Four buttons that get the next/previous record and the next/previous page of records replace the vertical scroll bar. When the user clicks one of these buttons, the control sends a message to the program asking for the appropriate data. The program itself must supply the needed data. This data typically comes from an indexed file, and the appropriate program logic is to do one or more READ NEXT/PREVIOUS statements to retrieve the data.

The grid control communicates requests for more data via events. More information about grid events can be found in Events Reference.

Paged grids never hold more data than they can display. When adding a record to a full page, the control deletes the top non-heading record when a record is added to the end of the grid. This causes the grid's contents to scroll upwards. When adding a record to any other position, the last record in the grid is deleted. This causes all records after the one being added to scroll downwards.

Note that the current cell is not changed when the grid is paged. In other words, if the grid's cursor is at row 2, column 3, it is at row 2, column 3 after the user clicks the "next record" button. This action effectively moves the cursor to a new record, even though its physical location has not changed. Unlike other forms of cursor movement, this does not generate any additional events. If you are performing special actions when the cursor enters a new cell (for example, displaying related information outside of the grid), then you should perform these actions in response to paging events as well as cursor-movement events.

Parent topic: Standard Controls


Label

The label control allows you to display a simple string of text on the screen form. This text cannot be changed by the end user, although it can be changed by the application at run-time. The label control is typically used to display permanent labels for entry fields, explanatory notes, or titles. It can also be used to show changing activities, such as the time or the progress of a file-copying activity. Labels may occupy multiple lines. When a label is displayed on multiple lines, it uses word-wrapping, if possible, so that words are not broken across lines.

Parent topic: Standard Controls


List Box

A list box is a rectangular list from which an end user can select one or more items. A list box does not allow direct data input. If the list box contains many items, the user can navigate through it with a scroll bar.

Paged List Box

The standard list box control provides a convenient way for a program to implement a look-up facility for a group of items. It is also tempting to extend this type of use into a method for locating records in a data file. Unfortunately, this doesn't work well when the file contains too many records. The programmer runs into two main problems:

  1. The standard list box has a limited capacity, usually fewer than 2000 items.
  2. It takes too long to load the list box with the entire set of items.

Also, if the number of items is very large, the user may have a difficult time locating a particular item. There are two reasons for this:

  1. The resolution of the scroll bar's slider is too coarse.
  2. The search mechanism is too primitive (for example, a single-character match on the first byte of the record).

The paged list box is a variation of the standard list box that solves all of these problems. A paged list box works by managing only a limited number of records at a time. When it needs more records, it requests them from the controlling program. Paged list boxes are intended to be used in conjunction with a large, ordered data source, typically records stored in an indexed file.

More information about how to use paged list boxes can be found in ACUCOBOL-GT User Interface Programming.

Parent topic: Standard Controls


Push Button

A push button is used to carry out an action when clicked by the user. It typically returns a unique value when selected, and its border changes, indicating that it has been selected. A common use for a push button is an OK or Exit button.

Parent topic: Standard Controls


Radio Button

A radio button is used to select an option, usually from a group of radio buttons. Unlike a check box, only one radio button in a group may be selected at a time. When a radio button is selected, it displays a black center to indicate that it has been selected. Typically, a group of radio buttons would be used to indicate a choice, such as a payment method (for example, cash, check, or credit card).

Because radio buttons always function in sets, if you want multiple sets of radio buttons in a screen, you should draw each set of buttons inside a frame control. When a set of radio buttons is inside a frame, clicking one of the buttons clears the other buttons in the set.

Parent topic: Standard Controls


Scroll Bar

The scroll bar allows end users to change the viewing area in a list or on a form. Scroll bars can also be used to move through a range of values by increments. Typically, a scroll bar is either a vertical or horizontal slider bar with arrows attached at each end.

Parent topic: Standard Controls


Status Bar

Available only in graphical environments, the status bar control allows you to create a status bar at the bottom of your screen. You can define up to 128 panels in your status bar, depending on how many items you want to track on your screen. Each screen may have only one status bar.

You define the panels in a status bar in the Panel description area of the Panel Setting dialog box. To display this dialog box, click in the Panels' Setting value column in the status bar control Property window.

Parent topic: Standard Controls


Tab

Available only in graphical environments, the tab control combines a box with a tab for a control that looks like a file folder. The user clicks any tab to bring it forward. The program typically places different screen elements in the box, depending on the tab selected.

Tabs can be oriented horizontally at the top or bottom of the control, or they can be oriented vertically at the left or right of the control, via the control's Tab Orientation property. Note that if the tab page is filled to its outer edges, you may have to make slight resizing or repositioning adjustments when you change the tab orientation.

When a user clicks a tab, the program is informed of the new selection and the tab's appearance is updated. The behavioral distinction between tabs and push buttons is that a tab responds immediately when clicked, and a push button responds with the clicked event only when the mouse button is released. You may allow the user to activate the tabs with the keyboard by accepting the tab control as any other control, but you need not do so if you wish to provide only a mouse interface.

When you create a tab control in the Screen Designer, there are a few special features to keep in mind. First, note that you can select either the entire tab control (the highlight frame and handles outline the control) or a page of the control (the highlight frame and handles define a rectangular region that does not include the tab portion of the control).

Note also that when you have selected a tab control or one of its pages, the Property window indicates the nature of the current selection. If the entire control is selected, the Property window entry begins with Tab Control (followed by the control name). If a tab control page is selected, the Property window entry begins with Page (followed by the page name).

The tab control uses the following special editing commands:

  • To add a new page to the tab control, make sure that the entire control is selected, then right-click and select Insert New Page (near the bottom of the right-click menu).
  • Once your control contains multiple pages, you can select Next Page or Previous Page from the right-click pop-up menu to navigate the control. If the entire control is selected, you can also switch between pages of the control by clicking the tab portion of the control.
Parent topic: Standard Controls


Tree View

The tree view control presents hierarchical data in a list. This list is indented to show the parent and child relationships in the data. Users can expand or collapse items in the list to view or hide subsidiary items.

In a tree view control, an ID is assigned to each element when it is added to the control. This provides a unique way to identify each item and allows for duplicate items at different points in the hierarchy without any confusion. Tree view IDs are declared in Working-Storage as USAGE POINTER data items. Tree View Designer functions are explained in detail in the following sections.

Using the Tree View Designer

Create a tree view for a screen by dragging a tree view control from the Screen Component Toolbox to any location in the screen form. When you add a tree view control to the screen, the Tree View Designer dialog box appears. This dialog box lets you add, delete, and move tree view items.

Creating a tree view for a screen

  1. In the Screen Component Toolbox, click the tree view control icon.
  2. Move the pointer to the screen form. The pointer changes to a crosshair.
  3. In the screen form, drag the left mouse button to add a tree view control.
  4. If the Tree View Designer does not appear automatically, double-click the tree view control box you have placed on the screen form. The text marker is highlighted in the dialog box.

The tree view control has two Property windows. The first one you see is available when you enter tree information in the Tree View Designer. It governs the individual tree and children properties. The second Property window is more extensive, and is available when you enter the tree and children information. It governs the more global behavior of the tree view control.

Adding a tree item to a tree view

  1. In the Tree View Designer, double-click the text marker. A new text field appears in place of the text marker at the left side of the dialog box. If the tree view already has tree items, the new item appears below and at the same level as the selected tree item.
  2. If you want to add a tree item before a selected entry, right-click in the designer and select the Insert Item Before command.
  3. Enter a name for the new tree item from the keyboard. Press Enter.

Adding a child item to a tree view

  1. Highlight the tree item that needs a submenu and click the Insert a sub-item button. You can also right-click in the designer and select the Insert Sub-item command. The cursor drops to a lower field, enabling you to type in the name of a child item.
  2. Once you have entered all of the child items for a particular tree item, you can enter the next tree item and child items by selecting the text marker below the last child item.

Adding bitmaps to a tree view

The Tree View Designer makes it easy to add bitmap icons to items in a tree view control.

  1. In the Screen Designer, select the tree view control on the screen.
  2. In the Property window, click the Value column next to the Bitmap property, then click the browse button.
  3. Navigate to the location of the bitmap or bitmap strip that you want to use, then click Open.
  4. In the Tree View Designer, select an item in the tree, then use the Property window to enter a value for the Bitmap Number property. If you are using a single bitmap image, rather than a bitmap strip, this number is 1. If you are using a bitmap strip, enter the number corresponding to the position of the icon that you wish to use.

Deleting an item from a tree view

  1. In the Tree View Designer, select and highlight the tree item or child that you want to delete.
  2. Click Delete.

Moving an item in a tree view

  1. In the Tree View Designer, select the tree or child that you want to move.
  2. Click the Move item up or Move item down button, depending on where you want the item to move. You can also right-click in the designer and select the Move Up or Move Down command.
Parent topic: Standard Controls


Web Browser

Available only in graphical environments, the Web browser control uses the run-time to browse the Web; invoke e-mail, telnet, and FTP services; and display multimedia and other file types. It also allows users to view Windows folders and files. It is used just like any other ACUCOBOL-GT control.

The Web browser control is installed with Microsoft Internet Explorer. It allows the user to view the main window of the Microsoft Internet Explorer on a screen created by the Screen Designer. It provides the functionality for displaying Web pages containing HTML, scripting, and ActiveX controls and Java applet content.

Parent topic: Standard Controls


ActiveX Controls

AcuBench makes it easy to include ActiveX controls in graphical programs designed to run in Microsoft Windows. Once you have installed the control on your system, you can add it to the Screen Component Toolbox, then place it on your screen form just like a standard control.

Note that ActiveX controls that you include in your program must be installed and licensed in accordance with the vendor’s requirements both on your development system and on every system on which the program is deployed. Use the AXDEFGEN utility to help you license your ActiveX controls for distribution.

General information about how to use ActiveX controls in your application can be found in Using ActiveX Controls and COM Objects.

  • Adding ActiveX Controls to the Component Toolbox
  • Using ActiveX Controls in Your Screen
  • Removing an ActiveX Control from the Component Toolbox
Parent topic: Controls, Menus, and Toolbars


Adding ActiveX Controls to the Component Toolbox

  1. Make sure that the control that you want to use is installed and registered on your system. If the control is installed but not registered, you can use the Microsoft Windows regsvr32 command to add the control to the Windows registry. The syntax is:
    regsvr32 control-name.ocx
  2. In the AcuBench Screen Designer, click the ActiveX bar in the Screen Component Toolbox.

    This hides the list of standard controls, opening an area that can be populated with ActiveX controls.

  3. Right-click in the Screen Component Toolbox and click ActiveX Control Components. This opens the ActiveX Control Components window, which lists all of the ActiveX controls currently installed and registered on your system.

    This is the same list that appears when you use AXDEFGEN, the ACUCOBOL-GT ActiveX definition generator. AcuBench uses AXDEFGEN to perform necessary ActiveX-handling tasks behind the scenes. This means that you don't have to access the utility directly when you are working in AcuBench.

  4. Scroll through the list of ActiveX components to find the control(s) that you would like to use and check the check box next to each control.
  5. When you are finished selecting controls, click OK.

    An icon is added to the ActiveX section of the Screen Component Toolbox for each control that you have selected.

Note: During code generation, AcuBench automatically adds an @ symbol to the ActiveX's control name. This avoids possible errors that can result from ActiveX control names that are identical to AcuBench control names, or to COBOL reserved words.
Parent topic: ActiveX Controls


Using ActiveX Controls in Your Screen

The process of working with ActiveX controls in the Screen Designer is very similar to that of working with standard controls. To add an ActiveX control to a screen, do the following:

  1. Select the control in the Component Toolbox, then draw it on the screen form.

    If you have an appropriate license, a graphical representation of the control appears on the screen form. If the control requires a design time license that you do not have, AcuBench shows a warning message, then draws a gray placeholder on the screen. In this case, the control will display normally at runtime, but you may have trouble changing control properties or coding the control. If this happens, see the control vendor for licensing information.

  2. Once an ActiveX control is placed on a screen, its initial properties (state) can be configured in the Property window. In addition, most ActiveX controls include a special interface for property configuration. If the vendor has provided such an interface, you can access it by right-clicking the control on the screen form and selecting ActiveX Control Properties.
  3. If you use an ActiveX control’s special property interface to configure the control, AcuBench saves your settings in a resource file, program.res. This file must be included when the program is deployed, or the control is displayed with its standard, default values.
Parent topic: ActiveX Controls


Removing an ActiveX Control from the Component Toolbox

Use the following steps to remove a control from the ActiveX Screen Component Toolbox:

  1. Click the ActiveX bar in the Screen Component Toolbox and then right-click in the toolbox. Click the ActiveX Control Component command from the pop-up menu. The ActiveX Control Components dialog box is displayed.
  2. Find the item on the list that you want to remove and click in the adjacent check box to remove the check mark.
  3. Repeat for other items that you want to remove.
  4. Click OK.

All list items that do not have a check mark in the check box are removed from the ActiveX control group in the Screen Component Toolbox, but they are not removed from the Windows registry or uninstalled from the system.

Parent topic: ActiveX Controls


Using the Menu Designer

The Menu Designer is a tool that allows you to create a menu bar or pop-up menu for a screen. Menus typically consist of menu titles, menu items, and separator bars. When you double-click the Menu Designer icon on your screen, the Menu Designer window appears. The Menu Designer window is the same for both graphical and character-based screens. The Screen Designer lets you create multiple menus for a screen, but a screen can use only one menu bar (displayed at the top of the screen) at a time.

  • Creating a Menu
  • Building the Menu
  • Adding Menu Functionality
  • Enabling the Menu
Parent topic: Controls, Menus, and Toolbars


Creating a Menu

If you used the Standard Graphical or Standard Character template to create your screen, the Menu Designer icon appears on the screen by default. This default menu contains a single menu item (Exit) and is defined as the screen's main menu. (A main menu is displayed as a menu bar along the top of the window at run time.)

If you have created a blank screen, or are using another template that does not include a default menu, drag a Menu item from the Screen Component Toolbox to any location in the screen form. The Menu control icon does not appear when you run your screen, so its exact location in the screen form is not important.

When you draw a Menu icon on the screen form, the Menu Designer interface opens automatically. You can also enter this designer at any time by double-clicking an existing Menu icon on a screen form.

The Menu Designer interface lets you add, delete, and move menu items. It also provides an interface (through the Event tab of the Property window) for associating code with each menu item.

Parent topic: Using the Menu Designer


Building the Menu

To add, remove, or change items in your menu, use the following steps:

  1. In the Menu Designer, double-click the menu text marker (<<...>>).

    A text field appears in place of the menu text marker.

  2. Enter the name of your menu item in the text field.

    To underline one character in the menu item name, indicating that the letter is a hot key, place the ampersand (&) character before the letter you want underlined. (For example, E&xit, indicates that the exit shortcut is Alt+X.)

  3. Press Enter or Tab to complete the menu item.

    The text marker moves to the next line. You can now repeat the previous steps to create another menu item at the same level as the first, or use the steps that follow to add a menu subitem.

  4. With a menu item selected, right-click and select Insert a sub-item. You can also use the Insert a sub-item button at the top of the Menu Designer window.

    The cursor drops to a submenu field, enabling you to type in the name of a submenu item.

  5. Once you have entered all of the submenu items for a particular menu item, you can enter the next menu item and submenu items by selecting the menu text marker below the last submenu item.

    The Menu Designer allows a maximum of four levels of submenu items (five including the main menu).

  6. If you want to add a menu item before an existing item, highlight the existing item and click the Insert item before button at the top of the Menu Designer window. You can also right-click in the dialog box and select the Insert Item Before command. The new item appears aboveand at the same level as the selected menu item.
  7. To insert a separator between menu items, highlight a menu item, right-click, and select Insert Separator command. A separator is inserted before the selected menu item.

    Note that you can also create a separator by entering a single hyphen (-) character as the text of a menu item. AcuBench automatically changes the Separator property of that item to TRUE, creating a separator.

  8. If you want to remove an item from the menu that you are creating, highlight the menu item that you want to delete and press Delete.
  9. To move a menu item up or down, select the item and drag it to the appropriate spot in the menu, or use the up and down arrow buttons at the top of the Menu Designer window.
Parent topic: Using the Menu Designer


Adding Menu Functionality

The process for associating code with menu items in AcuBench is very straightforward. As you add items to your menu in the Menu Designer, AcuBench automatically associates an exception value with each item. You can either use this default value or use the Property window to enter a different exception value. To associate a menu item with code, select the menu item, then use the Event tab of the property window to create a Link To paragraph for that item.

When you build a menu, it is a good idea to associate keyboard shortcuts with each menu command. There are two ways to do this:

  1. Place the & character in front of a letter of the menu item in the Menu Designer. Users can invoke that menu item by pressing the Alt key and the designated letter.
  2. Use a runtime configuration file to assign a keyboard shortcut to each exception value associated with a menu item.

When you use a runtime configuration file to assign a keyboard shortcut, the steps are as follows:

  1. Add your item name in the menu designer, then enter the special character combination \t and the keyboard shortcut that you want to associate with the item. The result should look something like this:
    Add\tCtrl+A

    At runtime, the \t becomes a tab character, adding appropriate spacing between the menu item and its keyboard shortcut.

  2. Make a note of the exception value associated with your menu item. If you prefer, you can change the Exception Value property associated with the item in the Property window.
  3. To add a configuration file entry to tie the menu item to the keyboard shortcut that you have specified, open your configuration file. (In AcuBench, this generally means opening the Project Settings window, selecting the Runtime tab, and clicking Edit to open the Configuration File Editor.)
  4. Add an entry for the KEYSTROKE configuration file entry that specifies the exception value and the keyboard shortcut that you want to associate. The entry should look something like this:
    KEYSTROKE Exception=1003 ^A

    In the example, when the user presses Ctrl+A, an exception of 1003 is generated. Any code associated with that exception (key-status) value is then executed.

    More information about the KEYSTROKE configuration variable can be found in The KEYSTROKE Variable.

  5. Back in the menu designer, use the Event tab of the Property window to create a Link To paragraph associated with the menu item. This paragraph is invoked when a user selects the menu item or uses the keyboard shortcut associated with the menu item.

Parent topic: Using the Menu Designer


Enabling the Menu

The Screen Designer lets you create multiple menus for a screen. You determine whether the menu appears as a menu bar at the top of the screen or as a right-click pop-up menu. Note that while a screen can have only one menu bar (or main menu), you can assign pop-up menus to any control on the screen that is not a display-only control. So your might assign one menu bar and one pop-up menu for your screen, then have additional pop-up menus associated with a grid control and an entry field that appear on the screen. You can also assign the same pop-up menu to multiple screens or controls.

To add a menu bar (main menu) to your screen:

  1. Select the Menu icon on the screen form.
  2. In the Property window, make sure that the menu’s Style property is set to Static Menu.

    Make a note of the Handle Variable property associated with the menu.

  3. Select the screen form in the Screen Designer.
  4. In the Property window, scroll to the Main Menu property.
  5. Click in the Value field and expand the drop-down list, then select the handle of the menu that you want to use as your screen’s main menu.

When you select a MAIN MENU handle, the generated code causes this menu to display at the top of your window. The code is put into the .cbl program generated. For example, if a screen is called form1 and the static menu handle is FORM1-MN-1-MENU, the code in form1.cbl is:

    PERFORM BUILD-Form1-MN-1-MENU.

This code generates form1.mnu, which contains:

    CALL "w$menu" USING WMENU-SHOW, MENU-HANDLE.

Pop-up menus do not display via calls to W$MENU like this. They show up automatically when you right-click the control. The code that is generated for the pop-up menu is just a single line of code in the form1.prd file, as follows:

    MOVE menu-handle TO Form1-MN-2-Handle

To define a pop-up menu for use with a screen or control, do the following:

  1. Select the Menu icon on the screen form.
  2. In the Property window, make sure that the menu’s Style property is set to Pop-Up Menu.

    Make a note of the Handle Variable property associated with the menu.

  3. Select the screen form or screen element in the Screen Designer.
  4. . In the Property window, scroll to the Pop-Up Menu property.
  5. Click in the Value field and expand the drop-down list, then select the handle of the menu that you want to use as a pop-up menu.
Parent topic: Using the Menu Designer


Using the Toolbar Designer

The Toolbar Designer is a utility that allows you to design and create toolbar controls for a screen. The Toolbar Designer is available only for graphical screens. A toolbar is a collection of controls arranged in a row below a screen's menu bar (if present), or at the top of the window if no menu bar exists.

The size of a Toolbar Designer can be changed through use of the left mouse button. To change the size, click the box surrounding the Toolbar Designer and drag a corner of it until it becomes the size you need.

When you draw controls directly on a toolbar, you cannot drag them out again; they are grouped inside of it. This allows you to move a toolbar and have the control remain inside it. You can copy a control that is in a toolbar and paste it outside of the toolbar if you want to remove it and use it elsewhere.

The Screen Designer lets you create multiple toolbars for a screen, and a screen can use more than one toolbar at a time. More information about using more than one toolbar at a time can be found later in this chapter.

  • Creating a Toolbar
  • Using More Than One Toolbar
Parent topic: Controls, Menus, and Toolbars


Creating a Toolbar

You can use the following steps to create a toolbar for a screen:

  1. In the Screen Component Toolbox, click the Toolbar Designer button.
  2. Move the pointer to the screen form. The pointer changes to a crosshair.
  3. Click anywhere in the screen form to add a Toolbar Designer window. By default, the window appears at the top of your screen form. Adjust the Toolbar Designer’s properties in the Property window as desired. The Toolbar Designer generates no events.
  4. Draw controls in the Toolbar Designer window. You can put any type of control in a toolbar except a menu or another toolbar. Controls should be placed in a single row, and they should not overlap.
Parent topic: Using the Toolbar Designer


Using More Than One Toolbar

The Screen Designer lets you create multiple toolbars for a screen and allows a screen to use more than one toolbar at a time.

To use multiple toolbars on a screen, create the toolbars, then place them in the order you want them to be seen on your screen, from top to bottom. When you run your screen, the toolbar you placed at the top appears at the top of the screen, below the menu bar. Below that toolbar appear any other toolbars you created in the top-to-bottom order that you placed them on the screen form.

Parent topic: Using the Toolbar Designer


Configuring the Report Composer

  • Introduction
  • Customizing the Report Composer Interface
  • Establishing Report and Control Defaults
  • Adding Report Templates
  • Report Keyboard Shortcuts
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

The AcuBench Report Composer is an interface for report design and layout that is very similar in appearance and behavior to the AcuBench Screen Designer. The interface includes a graphical design window onto which you can drag and drop report elements to lay out a report. As you add elements to the report, you can use a Property window to configure the appearance and behavior of the element and an Event Editor to tie code to the element.

Before you begin to design your report, you may want to complete the following preparatory steps:

  1. If you are using relative, sequential, or Vision indexed files for your data, use the File Designer to create data layout files.
  2. If you have created data layout files, define the corresponding data sets for your program.

    Note that these first two steps are not required. You can use the Report Composer to design reports regardless of what data format you are using. If, however, you are able to create data layout files and data sets to describe your data to AcuBench, the IDE provides tools to greatly simplify the report design process.

  3. Configure the Report Composer interface, as described in this chapter.

This chapter discusses your options for customizing the tool to suit your needs. The next chapter provides detailed instructions for using the tool.

Parent topic: Configuring the Report Composer


Customizing the Report Composer Interface

The Report Composer design window displays a report form similar in behavior and appearance to the screen form that appears in the Screen Designer. You add elements to this form to design your report.

By default, a grid of dots is displayed over each report form. This grid can be used to help you align elements of the report, creating precise columns and rows of printed output. The default size of each grid cell is 10 pixels by 10 pixels.

You can change the default grid behavior, as well as other report measuring behaviors, in the Tools > Options interface. To do this:

  1. Open the Tools > Options interface, expand the Report Writer tree, and click General.
  2. If desired, use the Grid width and Grid height entry fields to change the size of each grid cell. The measuring unit is pixels.
  3. To force new report elements to align with grid cell boundaries, check the Snap to grid check box. In a graphical report, you can still adjust the position of the control one pixel at a time using the arrow keys.
  4. To simplify the process of aligning report elements in relation to one another, check the Auto alignment check box. When this function is turned on,
    • if you position a report control underneath another control, and
    • the horizontal position of the two controls is within 5 pixels of one another, then
    • the new control's left boundary automatically aligns with the existing control's left boundary.
  5. To control measuring behavior in the generated code, use the radio buttons in the Unit group: to measure sizes and distances in inches, select the Inch radio button; to measure in centimeters, select Centimeter.
  6. In HTML reports, you have the option to choose whether embedded spaces in control titles or values are collapsed or preserved. To automatically collapse spaces, check the Collapse Spaces check box. To preserve embedded spaces, uncheck the box.
    Note: Entry fields have a special Display Type property, used, among other things, to control spacing behavior. If the Collapse Spaces option is checked in the Tools > Options interface, the Display Type property is used. If the check box is not checked, values in the entry field are treated as though the Keep Spaces option were selected, regardless of the actual value set for the Display Type property.
  7. If you have used the XFD tab of the File Designer to apply a NAME directive to any fields in your data files, you can choose to have the contents of the NAME directive appear in the Drag and Drop interface, rather than the actual field name. To enable this behavior, check the Apply XFD Names to Drag & Drop check box.

    For more information about creating XFDs and the XFD NAME directive, see Designing a Custom XFD.

Parent topic: Configuring the Report Composer


Establishing Report and Control Defaults

When you work in the AcuBench Report Composer, each element of the report (the report itself, each report section, and each report control) is associated with properties that appear in a Property window. You can determine the default setting for each of these properties and specify whether each property appears in the Property window. To enforce certain default settings, you could, for example, set the property default, then hide those properties in the Property window, causing the default property to always be used.

You can set the default properties and determine whether or not the property appears in the Property window through the Tools > Options interface.

To set default properties for report elements:

  1. Open the Tools > Options interface, expand the Report Writer tree, and click Default.

  2. Click a report element from the Controls list. The properties corresponding to the selected element appear in the Properties list on the right.
  3. Scroll through the Properties list to view the available properties and their default settings. To change a setting, click in the Value column next to the property name and enter your change.

    In some cases, a drop-down list and/or push button may appear when you click in the Value column for a report element. In this case, you can select an item from a list or click the button to open a secondary interface to define the property setting.

    The result of any change to a report element's defaults is reflected in the Property window each time you create a new element of that type.

To determine which properties appear in the Property window when you work in the Report Composer interface, do the following:

  1. In the Tools > Options interface, expand the Report Writer tree and click Visibility.

  2. To remove an individual property from the Property window, uncheck the check box next to the property name in the large list box. To show the property in the Property window, check the check box.

    You can also click one or more items in the list, then use the Set and Clear buttons to add or remove properties from the Property window.

  3. To remove an entire category of properties from the Property window, uncheck any of the Show check boxes (under the Set and Clear buttons).

    If you have removed a category from the Property window, you can add it back by checking the corresponding check box. Each property belongs to only one category.

Parent topic: Configuring the Report Composer


Adding Report Templates

When you create a new report in AcuBench, you have the option to choose

between two default templates (Blank Graphical and Blank Character). You can also create your own report templates and add them to the New Report dialog.

Using custom templates can simplify the process of report design and help you maintain consistency in your application output. You can, for example, create a template that includes a header or watermark containing your company logo, or that prints address or confidentiality information across the top or bottom of each page.

The process of creating a report template is described in Creating Report Template Files. Once you have the template file (.wtf), you can use the Tools > Options interface to add the template to the New Report dialog.

To add a template to the New Report dialog:

  1. Open the Tools > Options interface, expand the Environment tree, and select Template.

    More information about the Tools > Options > Environment > Template dialog box can be found in Template Options.

  2. In the Customize template section of the interface, select Report from the Template for drop-down box.
  3. Click Add to open the Add New Template File dialog.
  4. Enter a short, descriptive title in the Template title entry field, then click the browse (...) button next to the Template file entry field.
  5. Navigate to the directory containing your .wtf, select the file, and click Open.
  6. Add a more verbose description of the template file in the Description field.
  7. Click OK to save your changes, then click OK again to close the Tools > Options interface.

    The next time you create a new report, your template appears in the New Report dialog, along with your description.

Tip: When you add templates to the New Report interface, a pointer is placed in the INI file, used to locate the .wtf file on disk. If you move the template file, AcuBench will no longer be able to locate the template and you will receive an error message. This means that if you are sharing a template among a team of developers, the template file should reside in a shared folder or be made part of your version control project.
Parent topic: Configuring the Report Composer


Report Keyboard Shortcuts

Report-related keyboard shortcuts are configured in the Tools > Options interface. Expand the Environment tree and click Keyboard. The Report Composer keyboard shortcuts appear in the Main category. For information about changing keyboard shortcuts, see Keyboard Options.

Parent topic: Configuring the Report Composer


Working with Reports

  • Introduction
  • Adding a Report
  • Formatting the Report
  • Adding Report Controls
  • Configuring Control Properties
  • Setting Print Conditions
  • Using Events to Populate a Report with Data
  • Creating Report Template Files
  • Sample Reports
  • Deploying in a Thin Client Environment
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

When you want to create a report in AcuBench, a logical starting point is the definition of the data that you want processed and formatted into that report. After you have determined the information that your report should contain, you can design its appearance. The following general steps describe how to create a report in AcuBench:

  1. Create or open the project and set up your work environment.
  2. If you are working with data in sequential, relative, or Vision indexed files, create and refine your data layout (.dlt) in the File Designer.
  3. If you have created one or more data layout files, create the corresponding data set(s) in the Data Set Designer.
  4. Create a new report, then use the Report Composer interface to refine the report layout.
  5. Make one-time modifications to the generated code.
  6. Compile and run the program to generate the report.

This chapter discusses the types of reports that you can create with the Report Composer, the interfaces used to design a report, and the process of creating the report from start to finish.

  • Report Concepts: The Big Picture
  • Report Types
Parent topic: Working with Reports


Report Concepts: The Big Picture

What does it mean to design a report in the AcuBench Report Composer? At its core, a report generated by AcuBench functions like any other report written in COBOL:

  1. A sequential read is performed on one or more data sources.
  2. The program evaluates what to do next: print a footer, print a header, print a line of output, and so on.
  3. The data is extracted. User-defined conditions determine whether data is moved to the print line and written to the print file.
  4. The process repeats.

You can add layers of complexity, with headers and footers, nested breakpoints, multiple detail sections, and graphical report elements like grids and images. The basic report process, however, doesn't change.

Parent topic: Introduction


Report Types

The AcuBench Report Composer can be used to create two basic types of reports: character and graphical.

A character report is a line sequential file with carriage return breaks at the end of each line, output to a standard print file. The print file can be stored on disk, viewed, or directed to a physical printer. Character reports include only text characters. They do not include graphical elements, such as bitmaps, grids, and tables. (They can, however, include simple lines, constructed from standard characters like hyphens, underscores, or asterisks.)

A graphical report is an HTML file, generated into the directory specified with the FILE_PREFIX configuration variable. The HTML file can be opened and viewed in a Web browser, or printed to a printer device directly from the COBOL program. Graphical reports can contain elements like bitmap and JPG files, as well as check boxes, radio buttons, grids, and tables.

In comparison with graphical reports, character reports:

  • Include significantly fewer output lines, so the report can be produced more quickly
  • Have lower memory requirements
  • Do not require a browser for viewing

Graphical reports, on the other hand:

  • Can include more complex elements, including grids and tables
  • Provide more formatting options, including shading, colors, and images
  • Can include HTML features like hypertext links, for added functionality

If you are printing very large reports, like a warehouse inventory report or a bank transaction report, you might choose a character report format to reduce overhead. If you are printing a client invoice or requisition form, on the other hand, you might choose a graphical report in order to allow for more complex formatting and for graphical elements like logos or bar codes.

Parent topic: Introduction


Adding a Report

Once you have created an AcuBench program, the process of adding a new report is very straightforward:

  1. In the Structure view, expand the node for the program to which you want to add a report.
  2. Right-click the Report node for the program, then click New Report. The NewReport interface is displayed.

  3. Select a report template from the list at the top of the screen. The options you see depend on whether you have used the Tools > Options interface to add your own templates to the dialog as described in Adding Report Templates.
  4. Enter a descriptive name for the new report in the Form name field, then modify the Unique prefix field, if necessary.
  5. Verify that the report is being added to the correct project and program, then click OK.

    The new report opens in the Report Composer design interface, and an icon for the report is added to the program's Report node in the Structure view. You can open the report when needed by double-clicking this icon.

If you have report templates that do not appear in the New Report interface, you can use those templates to create a report using the Add Report command. This is discussed in more detail in Creating Report Template Files.

Parent topic: Working with Reports


Formatting the Report

When you create a new report using either of the default templates, the report opens with three default sections: a page header, a page footer, and a detail section. You can add or remove sections to determine the basic structure of your report, then configure report and section properties.

Note that you can add or remove sections at any point in the report creation process. Remember, however, that when you remove a section, any report controls that you have placed in that section and any properties that you have specified for that section are lost.

  • Adding or Removing Report Sections
  • Configuring Report and Section Properties
Parent topic: Working with Reports


Adding or Removing Report Sections

An AcuBench-generated report can contain the following sections:

  • Report Header
  • Report Footer
  • Page Header
  • Page Footer
  • Group Header (may include multiples)
  • Group Footer (may include multiples)
  • Detail section (may include multiples)

A report header is printed one time, at the very beginning of a report. It might contain information like the title of the report, the name of the person printing the report, and the date the report is being printed.

A report footer is printed at the very end of a report. It might include information like the time the report was completed, or a “completion” message to indicate that all necessary pages were printed.

A page header and page footer appear at the top and bottom of each page of the report. If you expect that the report you create will be printed to a device, having a page header and page footer can help to ensure the existence of proper page breaks. For this reason, even if you do not include any information in the page header or footer, it can still be useful to create the sections.

A group is a method of dividing up the data in your report according to breakpoints. You may want to preface a portion of your report with information about the items that follow, and/or conclude a portion of the report with summary or total information.

For example, if you are printing a daily report to summarize the transactions performed by five cashiers, the cashier ID might be a breakpoint. You could list the cashier ID first (group header), then, after listing the transactions, tally the daily total (group footer).

The detail section is the main body of your report. In a very simple report, you might read a record in a data file, print the record, then read the next record and repeat the process. In AcuBench terms, each of those printed records corresponds to a detail line.

In fact, a single detail line may include more than one physical row of output. You might have very long records, or construct a print line with data from multiple sources, or simply need a more readable layout that splits data items over multiple physical rows on the page. A detail section can contain as many physical rows as you need to print all of the data in the print line.

You also have the option to create multiple detail sections. When you have multiple detail sections, all of them correspond to one print line (or WRITE statement). In most cases, you can achieve the output results that you want with a single detail section. But the option to break the detail information for your report into different detail sections provides flexible shading options for readability and the option to set individual print conditions and before and after paragraphs for different segments of the same print line.

You can add or remove report sections with the Section Controller as follows:

  1. Right-click the report form in the Report Composer design window and click Section Controller. The Section Controller interface is displayed.

  2. Use the Header & Footer area to determine which header and footer sections, if any, will be included in your report. To add a section, check the check box to the left of the section name.

    If you are adding a page header and page footer to help regulate page breaks, make sure that the Count Height check box to the right of the section name is also checked (with a red check mark). This prompts AcuBench to generate code to keep track of page height when positioning items on the page.

  3. If you want to add additional detail sections to your report, use the Detail Section area of the Section Controller. (A report must have at least one detail section.)

    Click the New button (the third of the five buttons above the Detail Section list) to add a new detail section. Use the arrow keys to change the order of sections in the report. Use the Delete and Delete All buttons to remove sections.

    Remember that no matter how many detail sections you have, all of them correspond to one print line (WRITE statement), as described previously in this section.

  4. To add breakpoints to your report, use the Group Section area of the Section Controller. To define a group, you must specify the field or records on which the report will break, then specify whether the report should include a group header (marking the start of the group), a group footer (marking the end of the group), or both. You cannot create a group section (set a breakpoint) without displaying either a group header or group footer.

    You can specify more than one group (breakpoint) in your report. If you have multiple groups, they are nested in the order that they appear in the Section Controller interface. So if you have created group headers and footers for two group items, for example, you will see the header for the first group, followed by the header for the second group, followed by the detail section. When all of the necessary detail lines have printed, you'll see the group footer for the second group, followed by the group footer for the first group.

    • Use the Type column to specify whether the report will break on a field or on records.
    • Use the Grouped By column to specify the field or records on which the report will break.

      If the report will break on a field, clicking the browse (...) button in the Grouped By field opens a list of the data items defined in your DLTs, graphical Working-Storage, and definition files. If the report will break on records, clicking this button opens the Expression Builder.

    • Use the Show What column to specify whether you want a group header, a group footer, or both.
    • Use the Count Height column to cause AcuBench to generate additional positioning code to control where group headers and/or footers are printed in relation to their corresponding detail section(s).
  5. When you are finished making changes, click OK. The report form is updated to include the sections that you have specified.

    To abandon your changes without updating your report, click Cancel.

Parent topic: Formatting the Report


Configuring Report and Section Properties

Each report and report section has configurable properties that you can modify through a Property window. By default, the Property window is displayed any time you open the Report Composer interface. If you have closed the Property window, you can open it again by clicking View > Property Window, or by clicking the Property Window button on the Standard toolbar.

To configure properties of a report, expand the drop-down list at the top of the Property window, then scroll to the first entry (Report: reportname) and click it. The Property window lists the properties associated with the entire report.

Properties that apply to the report as a whole include the following:

Property | Description
(Name) | The name used by AcuBench to refer to the report (by default, Report1). This name appears in a number of paragraph names in the generated report code.
Num Columns (N-Top) | If you are using an N-Top style report, this determines the number of columns used. The AcuBench default is 1. This property is disabled for a Standard-style report.
Output File Name | The name of the file written to disk. By default, this is the name specified with the (Name) property with an .html extension.
Output File Variable | A variable used to hold the name of the file written to disk.
Paper Size | Click the browse (...) button to open a dialog box that allows you to select a paper size, set margins, and specify header and footer information. The default paper size is Letter.
Report Style | There are two options: Standard or N-Top. If you plan to print your report to a device, select Standard. When you select N-Top, the report is configured to be viewed in a browser with a horizontal scroll bar. Because N-Top is a display orientation only, reports with this property are not meant to be printed.
Target Browser | Select from Specify Internet Explorer or Standard HTML options.
Title | The title entered here appears in the title bar when the report is viewed with a Web browser. It also appears in the first line of the print preview. Note that this title does not appear if you display the report with a Web browser control inside an ACUCOBOL-GT screen.
Watermark | Use this property to select a graphic as a background image for the report. Bitmap (.bmp or .dib), JPG, and GIF formats are supported.
Watermark Style | Select from three options: None, Center, or Tile. If you select None, the default, the Watermark property is ignored and no image is printed.

When you work in the Report Composer interface, each report section is indicated by a gray bar, which appears above the section. This bar indicates the section type and name and may include additional information about the section. To change the properties for a section, click this section bar. The name of the section appears in the drop-down box at the top of the Property window.

Section properties include the following:

Property | Description
(Name) | The default section name is derived from the report name. You can change this name if desired.
Color | The default value for this property is 131329, foreground black on background white. Setting this property at the section level colors the background of the report and sets default colors for all report controls in the section.
Color Variable | Instead of setting a color value, you can specify a variable that will hold the color settings for the section.
Font | Setting the Font property at the section level sets the default font for all controls in the section.
Lines | This property represents the amount of space in a standard page that is reserved for printing a report section. This space is measured in either inches or centimeters, according to the Tools > Options settings that you have specified. For more information, see Customizing the Report Composer Interface.
Print After Page Footer | This property is available only for the report footer section. It determines whether the report footer prints before or after the page footer. The default value is FALSE.
Print Before Page Header | This property is available only for the report header section. It determines whether the report header prints before or after the page header. The default value is FALSE.
Print Condition A print condition can be use to determine when a particular section is printed. AcuBench uses the condition that you enter here to construct an IF statement in the generated code. This means that your entry is something like:
  user-name NOT = "chris"

You can type the print condition directly into the drop-down list in this property's Value cell (use Ctrl+Enter to move the cursor to a new line), or click the browse (...) button to open the Expression Builder interface. The Expression Builder is discussed in the section Setting Print Conditions.

Size | Specify the width of the page in which this section is printing. As with the Lines property, the width is measured in either inches or centimeters, according to the Tools > Options settings that you have specified. For more information, see Customizing the Report Composer Interface.
Skip Page after Print | Select TRUE or FALSE to determine whether a page break is printed after the selected report section.
Skip Page before Print | Select TRUE or FALSE to determine whether a page break is printed before the selected report section.
Visible | Select TRUE or FALSE to determine whether the specified control or section is printed. Selecting FALSE for a group section prevents the controls in the group from printing, but does not inhibit detection of the breakpoint.
Visible Variable | Specify the name of the variable that will hold the Visible setting for the selected report section.
Zebra | This property applies only to the detail section. Enter a value between 1 and 16 to alternate different background colors for each physical row of the detail section. The specified background color alternates with white. The default value is 0.
Parent topic: Formatting the Report


Adding Report Controls

Report controls are elements that you can use to determine report layout and to format the data that will populate the report. Some of these controls affect the look and feel of the report, but are not directly related to report data (report line, box, and image). Other controls are concerned primarily with positioning and formatting data (report check box, date time, entry field, grid, occurs, radio button, and table). You choose the combination of controls that you need to create a useful and appropriate presentation for your data.

Report controls are listed in the Report Component Toolbox. If you are creating a graphical report, all of the controls in the Component Toolbox are enabled. If you are creating a character report, controls that include a graphical element appear disabled.

The Component Toolbox includes the following types of controls:

Report Label | Generally holds information describing another report element.
Report Entry Field | A holder for data read into the report.
Report Line | Adds a horizontal or vertical line to a report. Can be used to delineate columns or underscore totals, for example.
Report Radio Button | Used to indicate the value of a piece of report data when only one of a group of options can be selected.
Report Check Box | Used with data that is either true or false. The box is checked when the corresponding data item has a value of 1 and unchecked when the item value is 0.
Report Box | Draws a box, similar to the screen frame, around a report section or element. Does not include the grouping component of a frame control.
Report Image | Used to add one or more .bmp or .jpg images to a report.
Report Grid | Used to provide a standard heading/column layout to data in your report. Can be used to add multiple records or database table rows to a single report detail section.
Report Occurs | Uses the OCCURS clause in a data table or array to create a line and column table layout for the data in the report.
Report Data Time | Offers several formats for adding date or time information to the report.
Report Table | Provides a method for structuring the output of a line of data. The table can have a vertical or horizontal orientation, and connects a header to a row of report data. The data can include literals, variables, and images.
  • Using the Report Component Toolbox
  • Using Drag-and-Drop
  • Positioning and Alignment
Parent topic: Working with Reports


Using the Report Component Toolbox

Add report controls to a report form in the same manner that you add a screen control to a screen form using the Screen Component Toolbox:

  1. Click a control icon in the Component Toolbox.
  2. Move the pointer to the report form. The pointer icon becomes a crosshairs.
  3. Position the pointer on the form, then hold down the left mouse button and drag the mouse to specify the dimensions of the control. When you are finished, release the mouse button.

    The control appears on the report form.

Parent topic: Adding Report Controls


Using Drag-and-Drop

As in the Screen Designer, if the data used to populate your report resides in graphical Working-Storage, data files described by a data layout file and data set, or AcuBench-recognized COPY files, you can use the Drag-and-Drop interface to add controls to your report. When you use this method to create controls, the controls are automatically associated with the selected data item(s).

To add a control to the report form using the Drag-and-Drop interface:

  1. Right-click anywhere on the report form and select Drag and Drop.

  2. Use the drop-down list on the left, if desired, to list the data items you want to use, then select a control type from the drop-down list on the right.
  3. Highlight one or more data items in the Field list, then position the mouse over one of the selected items, hold down the left mouse button, and drag the selection to the report form.

    The specified control or set of controls is added to the report form.

Parent topic: Adding Report Controls


Positioning and Alignment

In general, the same set of align functions is available for report controls as for screen controls. Use the Align menu and Align toolbar to size and position controls, either individually or in relation to one another.

When laying out report controls, it is important to remember that white (empty) space on the report for is preserved at runtime. This means that any extra padding that you leave above and below report controls is translated into empty space on the page when you print or view the completed report. As you finalize the layout of your report, remember to resize each report section to its content.

For detailed information about positioning and aligning controls, see Positioning and Aligning Controls.

Parent topic: Adding Report Controls


Configuring Control Properties

By configuring the controls that you have added to your report, you can determine exactly how data appears in the final report output. An entry field holding price information, for example, can be configured to apply an edited monetary format to a numeric field. A label containing header information can be given a bold typeface.

Although the principle of assigning properties to a report control is similar to that of configuring screen control properties, there are some significant differences:

  • Each screen control property corresponds to a property entry in the Screen Section definition of the control. There is no parallel report control definition section; instead, property entries help to define how the procedure code used to print the control is generated.
  • There tend to be fewer properties associated with a report control than with a screen control. Because a report entry field only displays data, rather than displaying and accepting information, it can’t be enabled or disabled, for example, or have a minimum or maximum text setting. Likewise, since a report is formatted for a pre-selected page size, resize settings are unnecessary.
  • Report controls can be associated with a print condition that determines whether or not it is printed during any given execution of the print loop. Similarly, report entry fields have a Print if Repeat property that lets you specify a general rule for how to handle consecutive records that contain the same data. You can either choose to always print the field (set Print as Repeat to TRUE) or to not print duplicate fields (set Print as Repeat to FALSE).

When you select a control on the report form, the Property window is updated to list the properties specific to that control. To change a property, click in the Value column. In some cases, you can type a new value in an entry field. In other cases, you can either select an option from a drop-down list or click a button (...) to open a secondary interface used to configure the property value.

More information about the report controls and their properties can be found in The Report Controls and Property Reference.

Parent topic: Working with Reports


Setting Print Conditions

Print conditions allow you to establish rules that determine when a given report element is printed. You might want to create a sales report listing only those sales people who have not met their quota, for example, or create an inventory report for restocking purposes that lists only items of which there are five or fewer remaining. Likewise, in some circumstances, you might want to print an entry field control only if it contains a positive (or non-zero) value, or you might print either of two labels, depending on the value of some field in the current record.

To set a print condition for a given report section or control, do the following:

  1. Select the report section or control.
  2. In the property sheet, click in the Value column next to the Print Condition property.
  3. Enter a simple condition (my-counter = 1 or zip-code NOT = 01003) or click the browse (...) button to open the Expression Builder.

    The Expression Builder is a graphical interface that you can use to build print conditions. Click data elements and expression symbols to construct a condition statement. When AcuBench generates the code, this expression is added to an IF statement used to determine whether or not the given report element should be printed.

Parent topic: Working with Reports


Using Events to Populate a Report with Data

Once you are satisfied with the design and layout of your report, your next step is to populate the report with data and possibly manipulate the output in some fashion. This is accomplished by writing code for events that perform these types of functions. These events are associated with the report itself and its elements, and are accessed from the Events tab. There are three types of events:

Before and After Print events: These type of paragraphs are tied specifically to individual elements of your report and the report itself. They allow you to code instructions for what you want to do before and after each report is generated.

BeforeDoPrint and AfterDoPrint events: These events are only associated with the report itself. They provide the code for performing READs and READ NEXTs, and initializing and resetting print loops. These paragraphs are what populates the report with data. Using these events from the Report Writer makes them part of the .psf file, which provides several advantages. These advantages, as well as coding samples are described in BeforeDoPrint and AfterDoPrint Event Paragraphs.

LoadGridInit and LoadGridNext Print events: These Grid control events provide the code for performing READs and READ NEXTs, and initializing and resetting print loops for grid controls. These paragraphs are what populates the grid with data. Using these events from the Report Writer makes them part of the .psf file, which provides several advantages. These advantages, as well as coding samples are described in LoadGridInit and LoadGridNext Event Paragraphs.

Note: The BeforeDOPrint, AfterDoPrint, LoadGridInit and LoadGridNext events are new features of version 8.1 that provide a better way of coding reports. However, reports created with older versions of AcuBench are supported and can be regenerated without making any changes to your code. See Existing Reports Imported from Earlier Versions of AcuBench for details.

The following sections describe the process of adding and coding these types of events.

  • Adding Report and Report Element Events
  • Before and After Event Paragraphs
  • BeforeDoPrint and AfterDoPrint Event Paragraphs
  • LoadGridInit and LoadGridNext Event Paragraphs
  • Generating Report Files and Code
  • Working with Data from Multiple Sources
  • Printing the Report
Parent topic: Working with Reports


Adding Report and Report Element Events

This topic describes the process of adding and coding event paragraphs that populate a report with data and possible manipulate the data or the report in some fashion. The event paragraphs are summarized in Using Events to Populate a Report with Data and detailed in subsequent topics.

To add event paragraphs to a report, or report element such as graphical control or section, do the following:

  1. Select the report element on the report form or the control on the form, or use the drop-down list at the top of the Property window to scroll to the desired element.
  2. Select the Event tab of the Property window.
  3. Click next to the paragraph type that you want to create.
    • If you are creating a new paragraph, click the browse (...) button to specify a name for the paragraph and enter the Event Editor.
    • If you are pointing to an existing paragraph, select the paragraph name from the drop-down list.
  4. If you are creating a new paragraph, the Add paragraph dialog appears, showing a default name for the paragraph (for example, report-element-Before-Print). You can either accept this name or enter a new name, then click OK to enter the Event Editor.

    To cancel without creating a paragraph, click Cancel. You still enter the Event Editor, but no new paragraph is created.

  5. Enter the code for your new paragraph. For detailed paragraph descriptions, coding suggestions, and samples, see: Before and After Event Paragraphs, BeforeDoPrint and AfterDoPrint Event Paragraphs, and LoadGridInit and LoadGridNext Event Paragraphs.
Parent topic: Using Events to Populate a Report with Data


Before and After Event Paragraphs

Every report, report section, and report control can be assigned a Before Print and After Print paragraph. These events are used to perform initialization tasks before report generation and next or additional tasks after report generation.

Examples include:

  • Open a relational database.
  • Perform a calculation just before printing a total in an entry field.
  • Move a numeric value from a COMP data type to a DISPLAY type (to show a monetary amount, for example).
  • Update the color variable associated with an entry field (to show negative values in red, for example, in an expense tracking report).
  • Update the page number in a page header or footer.
  • Ask the user to confirm that report generation should start.

An After Print paragraph is your last chance to intervene before leaving the just-printed report element and moving on to the next one. You might use an After Print paragraph to:

  • Add the data that’s just been printed in a field to a running tally.
  • Save a piece of data into Working-Storage before moving on to print the next item.
  • Initialize a data item that has just been printed.
Parent topic: Using Events to Populate a Report with Data


BeforeDoPrint and AfterDoPrint Event Paragraphs

Only the report itself contains BeforeDoPrint and AfterDoPrint events. You can provide paragraph names and code for these events using the steps described in Adding Report and Report Element Events. The code in these paragraphs perform READs and READ NEXTs, and initialize and reset print loops. They enable you to code instructions for what you want to do before and after each record is generated.

For example, you might define a BeforeDoPrint paragraph similar to this:

Myreport-BeforeDoPrint.
           move low-values to sales-key
           start sales key >= sales-key
           read sales-key next
                at end
                move 0 to Myreport-DOPRINTRTN-LOOP
           end-read
           .

And an AfterDoPrint paragraph that looked like this:

Myreport-AfterDoPrint.
      read sales-key next
           at end
           move 0 to Myreport-DOPRINTRTN-LOOP
      end-read
      .
Note: Included with AcuBench are several sample reports such as report1a that utilize these event paragraphs. See Sample Reports for details on locating and using AcuBench sample reports.

To read data from a database with AcuSQL, the equivalent basic code might look like this:

PERFORM UNTIL sqlcode NOT = 0
   EXEC SQL
      FETCH my-cursor INTO :C-RECORD
   END-EXEC
   IF sqlcode = 0
      PERFORM Acu-RPT-report-DO-PRINT-RTN
   END-IF
END-PERFORM.

These events were created so that all of your report generation code will be part of the .psf (project structure file). This is has two major advantages:

  1. All of your report generation code can be generated from your .psf file, which means your manual code will not be lost in the regeneration process.
  2. You will only need to check in your .psf file into your version control system, as opposed to also having to check in the .cbl file.
Parent topic: Using Events to Populate a Report with Data


LoadGridInit and LoadGridNext Event Paragraphs

Similar to the report element itself, the Grid control contains LoadGridInit and LoadGridNext print events. You name and code these paragraphs using the steps described Adding Report and Report Element Events. The code in these paragraphs is used to initialize and READ data into your Grid control.

For example, you might define a LoadGridInit paragraph similar to this:

Myreport-LoadGridInit.
           move low-values to sales-key
           start sales key >= sales-key
           read sales-key next
                at end
                move 0 to myreport-mygrid-LOADGD-SW
           end-read
           .

And a LoadGridNext paragraph similar to this:

Myreport-LoadGridNext.
           read sales-key next
                at end
                move 0 to myreport-mygrid-LOADGD-SW
           end-read
           .
Note: Included with AcuBench is a sample report called report1h that utilize these event paragraphs. See Sample Reports for details on locating and using AcuBench sample reports.

The same advantages of using the events described in BeforeDoPrint and AfterDoPrint Event Paragraphs, apply to these events as well.

Parent topic: Using Events to Populate a Report with Data


Generating Report Files and Code

Once you have finished working in the Report Composer to create the code that populates your report, the next step is to generate your program. Varying degrees of code modification will then be necessary. The exact code changes required will depend on whether or not you defined and coded report and report element events, as described in Adding Report and Report Element Events.

When you generate the program, AcuBench places your event code in the .evt copybook. The rest of the report generation code is written to the .rpt copybook. (By default, this COPY file is placed in the Report folder in the File view.)

The following sections detail the code that is generated under several different circumstances including:

  • Whether or not you defined BeforeDOPrint and AfterDoPrint events
  • Whether or not you defined LoadGridInit and LoadGridNext events
  • Existing reports imported from an earlier version of AcuBench

These sections also describe the code modifications that are necessary under each circumstance.

  • Reports Generated using BeforeDoPrint and AfterDoPrint events
  • Reports Generated Without BeforeDoPrint and AfterDoPrint Events
  • Grids Generated With LoadGridInit and LoadGridNext
  • Grids Generated Without LoadGridInit and LoadGridNext Events
  • Generating Existing Reports from Earlier Versions
Parent topic: Using Events to Populate a Report with Data


Reports Generated using BeforeDoPrint and AfterDoPrint events

If you defined BeforeDoPrint and AfterDoPrint events, as described in BeforeDoPrint and AfterDoPrint Event Paragraphs, the program's .cbl source file will contain the code to populate the data, and will look something like this:

      REPORT-COMPOSER SECTION.
      *{Bench}Myreport-masterprintpara
       Acu-RPT-Myreport-MASTER-PRINT-LOOP.

      *Before do print paragraph
              PERFORM Myreport-BeforeDoPrint
           PERFORM UNTIL Myreport-DOPRINTRTN-LOOP = 0
               PERFORM ACU-RPT-Myreport-DO-PRINT-RTN
      *After do print paragraph
               PERFORM Myreport-AfterDoPrint
        END-PERFORM
           .
      *{Bench}end

Note that the Before and After do print paragraphs are inside AcuBench tags, which enables your code to become part of the AcuBench generated code.

With BeforeDoPrint and AfterDoPrint events, there is also a new variable generated for each report. Its definition is:

77 Myreport-DOPRINTRTN-LOOP PIC 9 VALUE 0

This variable is the switch that starts and stops the loop. To start the loop and thus the printing of data, you need to add a line of code similar to this one at the beginning of the PERFORM Myreport-BeforeDoPrint paragraph:

MOVE 1  TO Myreport-DOPRINTRTN-LOOP
Parent topic: Generating Report Files and Code


Reports Generated Without BeforeDoPrint and AfterDoPrint Events

If you did not define and code BeforeDoPrint and AfterDoPrint events, as described in BeforeDoPrint and AfterDoPrint Event Paragraphs, your .cbl source file will look something like this:

*{Bench} report-masterprintpara
 Acu-RPT-report-MASTER-PRINT-LOOP.
 .
*{Bench}end
*

To add the code to read data into your report, you will need to manually code a DO-PRINT-RTN paragraph after the last AcuBench tag. For example:

PERFORM Acu-RPT-report-DO-PRINT-RTN.

Be aware that doing so will mean that this code will not be part of the .psf file. If the .cbl file is lost, the Read code is also lost. Also, it becomes necessary to perform version control on both the .cbl and .rpt files. For these reasons it is recommended defining BeforeDoPrint and AfterDoPrint events from within the Report Composer.

Parent topic: Generating Report Files and Code


Grids Generated With LoadGridInit and LoadGridNext

If you defined LoadGrid events, the code to populate the grid is automatically added to the .cbl source file and looks something like this:

*{Bench}myreport:mygrid:-dogridrtn
       Acu-mygrid-TABBODY.
           PERFORM Acu-Initialize-mygrid
      *(Bench}initial grid load para
           PERFORM mygrid-LoadGridInit
           PERFORM UNTIL myreport-mygrid-LOADGD-SW = 0
                PERFORM Acu-mygrid-TabbodyPrintLoop
      *(Bench}next grid load para
              PERFORM mygrid-LoadGridNext
           END-PERFORM.

           PERFORM Acu-CLOSE-mygrid
           .
      *{Bench}end
      *

With LoadGrid events, there is also a new variable generated for each report. It's definition is as follows:

77 myreport-mygrid-LOADGD-SW PIC 9 VALUE 0.

This variable is the switch that starts and stops the loop. To start the loop and thus the printing of data, you need to add a line of code similar to this one at the beginning of the PERFORM mygrid-LoadGridInit paragraph:

MOVE 1  TO myreport-mygrid-LOADGD-SW
Parent topic: Generating Report Files and Code


Grids Generated Without LoadGridInit and LoadGridNext Events

If you did not create LoadGrid events, AcuBench still adds lines to the .cbl source file that you can use to read multiple records into the control. The code for this paragraph, Acu-report-grid-TABBODY, is generated between {Bench} tags. One PERFORM statement is isolated in such a way as to allow you to add code to populate the grid with data.

*{Bench}Report1:Report-Grid:-dogridrtn
       Acu-Report-Grid-TABBODY.
           PERFORM Acu-Initialize-Report-Grid
      *(Bench}initial grid load para

           PERFORM UNTIL Report-Report-Grid-LOADGD-SW = 0
              PERFORM Acu-Report-Grid-TabbodyPrintLoop
      *(Bench}next grid load para

           END-PERFORM
           PERFORM Acu-CLOSE-Report-Grid
           .
      *{Bench}end

For the same reasons as described with the report control, it is recommended that you define the code to populate the grid in the Report Composer via the Grid event tab.

Parent topic: Generating Report Files and Code


Generating Existing Reports from Earlier Versions

Before and after do print events are a new feature in version 8.1. However, reports created with previous versions of AcuBench are still supported by AcuBench. When you regenerate the report with version 8.1 the only change made to your original code is the insertion of an additional line containing a period (.) within the bench tags. This will not cause any compilation issues. Your .cbl source file will look something like this:

*{Bench}report-masterprintpara
    Acu-RPT-report-MASTER-PRINT-LOOP.
        .
   *{Bench}end
   *
        PERFORM Acu-RPT-report-DO-PRINT-RTN.

If you want start coding using the new style you can go into the report composer and define the BeforeDoprint & AfterDoPrint events. You then can either manually delete the source outside the tags (starting with the PERFORM Acu-RPT-report-DO-PRINT-RTN.) or delete the source file and regenerate. Note however that once you remove your original code from the .cbl source file it cannot be brought back.

LoadGridInit and LoadGridNext events are also a new feature in version 8.1. However, reports with grids created with previous versions of AcuBench are still supported by AcuBench. When you regenerate the report with version 8.1 no changes are made to the AcuBench grid tags in your .cbl file.

If you want to start using these new grid events you will need to define and code them as described in Adding Report and Report Element Events and remove the previous tags by editing the .cbl source file or deleting the .cbl file itself. The new grid tags will only be generated if the old grid tags have been removed. Drawing a new grid control would insert the new tag for that control in the source, which makes it possible to have a mix of new and old style grid tags in the same source file.

Parent topic: Generating Report Files and Code


Working with Data from Multiple Sources

If you are retrieving data from several sources, the code gets more involved, but the central concept remains the same: you supply the code to retrieve the data needed to print one line of the report (regardless of whether that line is a record from a single data file or a collection of related data), then perform a generated routine to print that output in the format that you designed in the graphical Report Composer interface.

The code that follows demonstrates the process of populating a report with data from three indexed files. The report lists all of the clients of a veterinary clinic (recorded in a file called clients), all of the pets belonging to each client (recorded in a file called pets), and all of the treatments received by each pet (recorded in a file called trecord). In the interest of clarity, the file handling code has been simplified, leaving out INVALID KEY and AT END status checking.

The basic process retrieves data from the first file and uses that data to retrieve information from the second file. The data from the second file, in turn, is used to retrieve data from the third file. With all of the data in place, the print routine is executed to print a line (including group headers, group footers, and a detail section) of the report. The process then repeats until the entire report has been printed.

       create-history-report.
           MOVE LOW-VALUES TO cl-client-id.
           START clients KEY >= cl-client-id.
           PERFORM UNTIL ws-client-status = "10"
              READ clients NEXT RECORD
              IF ws-client-status NOT = "10" AND
                 ws-client-status NOT = "02"
                 PERFORM get-pets-for-client
              END-IF
           END-PERFORM.
      *
       get-pets-for-client.
           MOVE cl-client-id TO pet-owner-id.
           START pets KEY = pet-owner-id.
           PERFORM UNTIL pet-owner-id NOT = cl-client-id
              READ pets NEXT RECORD
              IF pet-owner-id = cl-client-id
                 PERFORM get-pet-treatment-history
              END-IF
           END-PERFORM.
      *
       get-pet-treatment-history.
           MOVE pet-id TO tr-pet-id.
           START trecord KEY = tr-pet-id.
           PERFORM UNTIL tr-pet-id NOT = pet-id
              READ trecord NEXT RECORD
              IF tr-pet-id = pet-id
                 PERFORM Acu-RPT-comp-rpt-DO-PRINT-RTN
              END-IF
           END-PERFORM.
Parent topic: Using Events to Populate a Report with Data


Printing the Report

Before compiling and executing the program to create the report, you need to decide which forms of print output you intend to use. In the generated .rpt COPY file, AcuBench creates paragraphs that you can call to start the report process. These include:

  • Acu-report-PRINT-TOFILE starts the report process and creates an output file on disk. If you are creating a graphical report, you can use this routine, then display the report on a graphical screen using the Web browser control. This can be significantly faster than using the preview function.
  • The Acu-report-PREVIEW paragraph executes the code to create the report, then opens a preview window to display the report. Using this option requires you to have Internet Explorer, version 4.0 or later, installed on the machine running the report. Because of the overhead involved in communicating with Internet Explorer, this option is significantly slower than other options.
  • The Acu-report-DO-PRINT paragraph executes the code to create the report, then sends the report to the default printer. You can use this paragraph as a template if you want to send the report to a different printer device.
Note: Both the PREVIEW and the DO-PRINT paragraphs require a DLL ( AcuBenchPrint.dll) that is automatically added to your AcuBench project when you create a report. If you are deploying in a thin client environment and using either of these routines to create and either preview or print the report, this DLL must be copied to the display host (client). For more information, see Deploying in a Thin Client Environment.

To create your report, then, you need one line of code:

    PERFORM Acu-report-PRINT-TOFILE.

Or:

    PERFORM Acu-report-Preview.

Or:

    PERFORM Acu-report-DO-PRINT.

Where you add this code depends on how you are invoking the report. If your program does nothing but create the report, add the PERFORM statement after the PERFORM Acu-Initial-Routine statement in the .cbl source file. If the report is created in response to a push button click or menu selection, add the PERFORM statement to the appropriate exception or link-to paragraph.

Parent topic: Using Events to Populate a Report with Data


Creating Report Template Files

Any report that you create in the AcuBench Report Composer can be saved as a template file and used as the foundation for future reports. To create a report template:

  1. Create and refine your report in the Report Composer.
  2. Right-click anywhere on the report form and select Generate WTF Document. A Save As dialog opens.
  3. Navigate to the directory in which you want to store the template file, enter a name for the file, and click Save.

Once you have create a report template, there are two ways that you can use the template to create a new report:

  • Add the report to the New Report interface, as described in Adding Report Templates. When you use this option, each time that you create a new report, your template appears along with the two default templates in the New Report dialog.
  • In the Structure view, right-click the Report node for the program in which you want to create a report, then select Add Report. In the Add Report to Program dialog, navigate to the folder containing your report template, select the template file, and click Open.
Parent topic: Working with Reports


Sample Reports

Some sample reports have been created to help you get started with the Report Composer function. By default, these are placed in the %PUBLIC%\Documents\Micro Focus\extend x.x.x\sample\acubench directory. The samples include both character and graphical reports, and each report builds on the functions learned in the previous report. Together, the reports demonstrate the range of available report controls, from a simple report containing only report labels and entry fields to complex reports with tables and grids. The sample reports all use the same Vision indexed data files: sales.dat and sales.vix; the data resides in the project's Data subdirectory.

The Reports sample project contains the following graphical report programs:

Program | Description
Report1a | This is a simple report that contains only entry fields and labels.
Report1b | This report is designed in landscape orientation and is ordered into columns. It includes labels, entry fields, and a date time control.
Report1c | This report includes group headers and a report occurs control.
Report1d | This report includes a report header and report footer, as well as report check box and radio button controls.
Report1e | This report demonstrates some uses for group footers.
Report1f | This report includes a report image control and a report table.
Report1g | This is an example of an N-Top report.
Report1h | This report demonstrates basic use of the grid control.
Report1i | This report provides a more advanced example of the report grid control, showing how to use the generated TABBODY code to load data into the control.

The Reports sample project also includes the following character report programs:

Program | Description
Report2a | This is a simple report that contains only entry fields and labels.
Report2b | This report is designed in landscape orientation and is ordered into columns. It includes labels, entry fields, and a date time control.
Report2c | This report includes group headers and a report occurs control.
Report2d | This report includes both page and report headers and footers, as well as nested group headers. It is presented in a landscape orientation.
Report2e | Building from Report2d, this report also includes nested group footers.
Parent topic: Working with Reports


Deploying in a Thin Client Environment

AcuBench users running in a thin client environment with AcuConnect can print graphical reports from a UNIX application host. There are two different methods for accomplishing this:

  1. Include a screen with a Web browser control in the deployed application, and use the control's built-in functionality to display and print HTML reports.
  2. Use the AcuConnect "@[DISPLAY]: notation in conjunction with the CODE_MAPPING configuration variable and the C$COPY library routine to access the preview and print functions included in the AcuBenchPrint.dll library file.

The topics that follow discuss each of these options and provide implementation information.

  • Using a Web Browser Control to Display and Print Reports
  • Using AcuBenchPrint.dll to Display and Print Reports
Parent topic: Working with Reports


Using a Web Browser Control to Display and Print Reports

The ACUCOBOL-GT Web browser control, described in Control Types Reference, is a useful tool when you deploy a program that includes graphical reports. The Web browser control can parse and display both character and graphical reports, though its advantages are most clearly seen with graphical reports.

All you need to use this method to display and print reports are a screen containing a Web browser control and a program containing a report. The basic steps are as follows:

  1. Design the screen and the report. Make sure that you know the output file name and path for the report.
  2. Include code to perform the generated Acu-report-Print-ToFile paragraph.
  3. Move the name and path of the generated report file to the value variable associated with the Web browser control.
    MOVE "c:\reporting\data\pets.html" TO ws-browser-url.
  4. Add code to print the report. To allow the user to choose from various printers on the network, the code looks like this:
    MODIFY my-browser-control, PRINT=1

Information about printing to a default printer or giving the user the option to perform page setup operations can be found in Control Types Reference.

There are significant advantages to using this method to display and print reports:

  • It's significantly faster than the Acu-report-Preview process.
  • The Web browser control displays the report in full color and at 100% resolution.
  • Any hyperlinks or other interactive aspects of the report are fully available to the user.
  • You control the size of the Web browser control window.
Parent topic: Deploying in a Thin Client Environment


Using AcuBenchPrint.dll to Display and Print Reports

When you invoke the Acu-report-Preview and Acu-report-DO-PRINT routines, AcuBench uses a library called AcuBenchPrint.dll to call the Internet Explorer functions needed to preview or print the report. This means that if you want to use AcuBench functions to preview or print a report in a thin client environment, you need to first copy the report and DLL to the report host, then perform a preview or print routine.

The general steps involved are as follows:

  1. Place AcuBenchPrint.dll on the display host (either as part of your thin client installation or using C$COPY with @[DISPLAY] notation).

    This DLL should be placed in the same directory as the thin client executable (acuthin.exe).

  2. Use the CODE_MAPPING configuration variable to expose the function calls in the DLL.
  3. Use the C$COPY library routine with @[DISPLAY:] notation to copy the HTML file from the application host to a location on the display host.
  4. Add a line of code to reset the PRT-FULLFILENAME variable, which AcuBenchPrint.dll uses to locate the HTML file.

The following example demonstrates the code used to perform steps 3 and 4. In the sample program, the user pushes a button to create the report, which is then displayed with the preview function:

ReportPB-Link.
        IF IS-REMOTE
              PERFORM ACU-REPORT1-THINPREVIEW
            ELSE
              PERFORM ACU-REPORT1-PREVIEW
            END-IF.
    *
     ACU-REPORT1-THINPREVIEW.
         PERFORM Acu-Report1-PRINT-TOFILE
    *
         CALL "C$COPY" USING
                "/home/data/Report1.html",
                "@[DISPLAY]:C:\Localdata\Report1.html".
    *
         PERFORM Acu-Report1-PRINT-PARA
    *
         STRING
          "C:\Localdata\Report1.html", delimited by size,
          X"00", delimited by size,
          into PRT-FULLFILENAME.
    *
         SET ENVIRONMENT "DLL_CONVENTION" to "1"
         CALL "AcuBenchPrintDummy"
           ON EXCEPTION CALL "AcuBenchPrint.dll" END-CALL
         END-CALL
         CALL "AcuBenchPrintExecWBPreview" USING
            BY CONTENT PRT-FULLFILENAME,
            BY CONTENT PRINT-BROWSER-PARA,
            BY CONTENT ACU-PAPER-HEADER,
            BY CONTENT ACU-PAPER-FOOTER,
            BY CONTENT ACU-PAPER-SIZE,
            BY VALUE ACU-PAPER-ORIENTATIONINT,
            BY CONTENT ACU-PRINTER-NAME
         END-CALL
         .

The push button code uses the IS-REMOTE flag in the TERMINAL-ABILITIES structure to test whether the program is running locally or on a remote server. If it is running remotely, a paragraph called Acu-Report1-ThinPreview is executed.

The code in the Acu-Report1-ThinPreview paragraph starts by executing the AcuBench-generated PRINT-TOFILE paragraph. It then calls C$COPY to transfer the HTML file to the local machine. Next, it uses a STRING statement to reset the PRT-FULLFILENAME parameter to the location of the HTML file on the client machine. (Note that the PRT-FULLFILENAME string is terminated by low-values.) Finally, with code copied from the AcuBench-generated Acu-Report1-Preview paragraph (found in the .rpt COPY file), it calls the DLL and invokes the preview function.

With CODE_MAPPING set to on, the configuration file can contain instructions for mapping these calls to AcuBenchPrint.dll, which, in our sample, is located in the C:\Localdata directory on the client machine, as shown:

CODE_MAPPING ON
DLL_CONVENTION 1

ACUBENCHPRINT.DLL
@[DISPLAY]:C:\Localdata\AcubenchPrint.DLL
ACUBENCHPRINTDUMMY @[DISPLAY]:AcuBenchPrintDummy
ACUBENCHPRINTEXECWBPREVIEW
@[DISPLAY]:AcuBenchPrintExecWBPreview

The complete sample code for this example can be found in the Support section of the Micro Focus Web site. For detailed information about the @[DISPLAY]: notation and other thin client functions, refer to the AcuConnect User's Guide.

Parent topic: Deploying in a Thin Client Environment


The Report Controls and Property Reference

  • Introduction
  • Common Report Control Properties
  • The Report Box
  • The Report Check Box
  • The Report Date Time
  • The Report Entry Field
  • The Report Grid
  • The Report Image
  • The Report Label
  • The Report Line
  • The Report Occurs
  • The Report Radio Button
  • The Report Table
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

Whatever their other functions, both screens and reports provide a means of presenting data to the user. In either context, a control is a tool used to present a data item (or selection of data items), or to affect the appearance of data being presented.

Because of this similarity of purpose, there is a high degree of correspondence between screen controls and report controls. The bar control, for example, draws a vertical or horizontal line on a screen. The report line control, similarly, prints a vertical or horizontal line on a report. A screen grid control and report grid control both organize data into lines and columns with an optional heading row.

Report control properties, like their screen control counterpoints, can be divided in to common and special properties. Common properties apply to many or all control types, while special properties have meaning for one or few control types.

Parent topic: The Report Controls and Property Reference


Common Report Control Properties

Unless indicated otherwise, the control properties in the following list are common to all report controls. A property marked with an asterisk (*) can have its default value set in the Tools > Options > Report Writer > Default dialog. For a description of this interface, see Establishing Report and Control Defaults.

(Name)

The default name is derived from your report name. For example, for Report1, the default name for the first label would be Report1-RwLa-1. You can change this name if desired.

Border Color

This property is not available for the check box, line, or radio button report controls.

A drop-down box allows for the selection of non-zero values from 1 to 16 that correspond to border colors. The default value for this property is 0.

When the Border Style property is set to Boxed, the Border Color and Border Width properties combine to determine the presentation of the border around the report control.

Border Style

This property is not available for the check box, line, or radio button report controls.

A drop-down box allows for the selection of Boxed or No Box. For most controls, the default value for this property is Boxed. However, for the label and table report controls, the default value is No Box. Also, note that the No Box setting is ignored by the report box control.

When this property is set to Boxed, the Border Color and Border Width properties combine to determine the presentation of the border around the report control.

Border Width

This property is not available for the check box, line, or radio button report controls.

The Border Width property allows for the entry of an integer between 1 and 20, representing a width measurement in pixels. The default value for this property is None.

When the Border Style property is set to Boxed, the Border Color and Border Width properties combine to determine the presentation of the border around the report control.

Color*

The default value for this property is foreground black on background white.

The Value cell for this property has an ellipsis push button that opens the Color Setting dialog. Foreground and background colors can be set in this interface. The Color property setting of a report control overrides the Color setting of its parent section.

Color Variable*

The Value cell for this property has an ellipsis push button that opens the Select Variable interface. If a variable is selected in this dialog, subtle modifications to the generated code occur, such that it references the Color Variable instead of the Color value directly. This property has no initial default value.

Column

This property determines the location of the report control with respect to the left margin of the page. The unit of measure (inches or centimeters) is set in the Tools > Options > Report Writer > General interface.

Font*

This property is not available for the box, image, line, and occurs report controls.

A drop-down box displays several choices for font. The default value is Default Font. The push button in the Value cell causes the Font dialog to appear.

The Font property setting for a report control overrides the Font property setting of its parent section.

Hyperlink

This property applies to report date time controls, entry fields, images, and labels. It is used to assign a hyperlink to the control when it is displayed in a Web browser. A hyperlink may reference either a local HTML file or a Web site.

To reference a local HTML file, click the ellipsis push button in the Value cell to display the Open dialog box. Navigate to the location of the local file and select it.

To reference a Web site, enter the entire address in the Value cell (e.g., http://www.microfocus.com). If you omit the http:// prefix, AcuBench interprets the entry as a file name. In the latter case, the result is a File not found error message when you attempt to access the link.

This property has no default value.

Hyperlink Variable

This property applies to report date time controls, entry fields, images, and labels. The Value cell for this property has an ellipsis push button that opens the Select Variable interface. If a variable is selected in this dialog, subtle modifications to the generated code occur, such that it references the Hyperlink Variable instead of the Hyperlink value directly. This property has no default value.

Line

The Line property determines the location of the report control with respect to the beginning of the parent section. The unit of measure (inches or centimeters) is set in the Tools > Options > Report Writer > General interface.

Lines

This property is not available for the line report control.

The Lines property represents the height of the report control.

Note that the standard unit of measure used by Lines is set in the Tools > Options > Report Writer > General dialog. In this dialog, you can select Inch (the default) or Centimeter in the Unit frame.

Print Condition

A print condition can be used to make the printing of a report control conditional. Print conditions are discussed in detail in Setting Print Conditions.

Size

This property represents the width of the report control.

Note that the standard unit of measure used by Size is set in the Tools > Options > Report Writer > General dialog. In this interface, you can select Inch (the default) or Centimeter in the Unit frame.

Title

This property determines the text portion of the report check box, label, or radio button.

Title Variable

This property applies to the report check box, label, and radio button controls. The Value cell for this property has an ellipsis push button that opens the Select Variable interface. If a variable is selected in this dialog, subtle modifications to the generated code occur, such that it references the Title Variable, instead of the Title value directly. This property has no default value.

Visible*

A drop-down box allows the selection of TRUE or FALSE. Selecting FALSE inhibits the printing of the report control. The default value is 1:TRUE.

Visible Variable*

The Value cell for this property has an ellipsis push button that opens the Select Variable interface. If a variable is selected in this dialog, subtle modifications to the generated code occur, such that it references the Visible Variable instead of the Visible value directly. This property has no initial default value.

Parent topic: The Report Controls and Property Reference


The Report Box

The report box is similar to the ACUCOBOL-GT standard frame control. A report box, however, does not have a title, and does not perform any special grouping function for controls displayed inside the box. Like the report line, this report element is useful for highlighting some portion of the report text. You might, for example, place a box around the report title as a way of framing the text, or place a box around a group of entry fields or radio buttons in the detail section to make them stand out from the rest of the page.

The report box does not have special properties. All report box properties are described in Common Report Control Properties.

Parent topic: The Report Controls and Property Reference


The Report Check Box

The report check box is similar to the ACUCOBOL-GT standard check box control. It is used to display items that are either selected or unselected, true or false. If the variable associated with the control has a value of 1, the box is marked (contains a check mark). If the associated variable value is 0, the box appears unmarked (no check mark).

The report check box Property window contains the following special properties in addition to the properties described in Common Report Control Properties.

Value

This property must be set to 0 or 1. A value of 0 (the default) indicates that the report check box is not selected in the report. A value of 1 indicates that the check box is selected.

The report check box is a stylistic display device. You need to code for the conditions that cause a particular check box to be selected. A logical place to perform this check is in a Before-Print paragraph for a report check box. For example, to manipulate a Sales Quota check box, the following code can be used in the Before-Print paragraph:

ADD heavy-equipment-sales TO supplies-sales
    GIVING total-salesperson-sales.
IF  total-salesperson-sales > sales-quota
    MOVE 1 to pr-quota
ELSE
    MOVE 0 TO pr-quota
END-IF.

When you display a report check box in Internet Explorer, the check box can be toggled by clicking it. For an example of this report control, refer to sample Report 1d in the sample reports area.

Value Variable

The Value cell for this property has an ellipsis push button that opens the Select Variable interface. If a variable is selected in this dialog box, subtle modifications to the generated code occur, such that it references the Value Variable instead of the Value value directly. This property has no default value.

Parent topic: The Report Controls and Property Reference


The Report Date Time

The report date time, like the screen date entry control, is used to present formatted date and time information. In a report, this information is likely most useful in a header or footer.

The report date time Property window contains the following control-specific properties in addition to the properties described in Common Report Control Properties.

Date Format

This property determines how a date is displayed in the report date time. The default value for this property is mm/dd/yyyy. A drop-down box allows the selection of the following formats:

  • yyyy/mm/dd
  • mm/dd/yyyy
  • dd/mm/yyyy
  • yy/mm/dd
  • mm/dd/yy
  • dd/mm/yy
  • yyyy/mm
  • mm/yyyy
  • yy/mm
  • mm/yy
  • mm/dd
  • dd/mm
  • None

Date Picture Format

This property defines the format in which dates are stored in Working-Storage. The default value for this property is MMDDYYYY. A drop-down box allows the selection of the following formats:

  • YYYYMMDD
  • YYYYDDMM
  • MMDDYYYY
  • DDMMYYYY
  • YYMMDD
  • YYDDMM
  • MMDDYY
  • DDMMYY
  • YYYYMM
  • MMYYYY
  • YYMM
  • MMYY
  • MMDD
  • DDMM
  • None

Justification

A drop-down box allows the selection of Center, Left, Right, or Unaligned. The default value for this property is Unaligned.

Print If Repeat

A drop-down box allows the selection of TRUE or FALSE. The condition is applied when consecutive records contain the same data values. When this property is set to TRUE (the default), both data values print. When it is set to FALSE, the second (and subsequent) same data values do not print.

Time Format

This property determines how time is displayed in the report date time. The default value for this property is None. A drop-down box allows the selection of the following formats:

  • hh:mm:ss
  • hh:mm
  • hh
  • mm:ss
  • mm
  • ss
  • tt hh:mm:ss
  • tt hh:mm
  • tt hh
  • None

Note that tt is replaced by am or pm, hh by hours, mm by minutes, and ss by seconds.

Time Picture Format

This property defines how time is stored in Working-Storage. The default value for this property is None. A drop-down box allows the selection of the following formats:

  • HHMMSS
  • HHMM
  • HH
  • MMSS
  • MM
  • SS
  • None

Value Picture

If you select an existing variable for Value Variable, Value Picture inherits the picture of the existing variable. If you create a new variable for Value Variable, you can create a picture clause for that variable here. If you leave Value Picture blank, a picture of X(30) is assigned to the new variable. This property has no default value.

Value Variable

The Value cell for this property has an ellipsis push button that opens the Select Variable interface. The Value Variable is not directly referenced by the generated code, but may be used by the user. This property has no default value.

Parent topic: The Report Controls and Property Reference


The Report Entry Field

The report entry field corresponds to the ACUCOBOL-GT standard entry field control. Whereas a report label contains only literal values, a report entry field displays the value of a variable data item (its Value Variable property). When an entry field is tied to a file descriptor (FD) field, a simple READ NEXT statement can be used to update the field for printing. With formatted data or breakpoints, there may be additional coding considerations.

The report entry field Property window contains the following control-specific properties in addition to the properties described in Common Report Control Properties.

Display Type

A drop-down box allows the following selections:

Collapse (the default) | Allows only one space between two strings.
Keep Space | Keeps any amount of space between two strings.
Preformatted | Keeps any format settings.

AcuBench generates the <PRE> and </PRE> HTML tags to maintain the text format.

Horizontal Spacing

The Value cell allows the entry of a digit with two decimal places. The default value for this property is 0.00. Increasing this number enlarges the spaces between characters printed inside the report entry field.

Justification

A drop-down box allows the selection of Center, Left, Right, or Unaligned justification for the report entry field. The default value for this property is Unaligned.

Print If Repeat

A drop-down box allows the selection of TRUE or FALSE. The condition is applied when consecutive records contain the same data values. When this property is set to TRUE, both data values print. When it is set to FALSE, the second (and subsequent) same data values do not print. The default value is TRUE.

Value

This property can be a numeric or alphanumeric value. The value prints inside the report entry field. If a Value Variable is used, this numeric/alphanumeric is preserved as the initial Value of the Value Variable.

Value Picture

The Value Picture default value varies, depending on whether a Value property has been specified. If a Value has been specified, the Value Picture is derived from the Value. If no Value is specified, a default of X(30) is used.

Value Variable

The Value cell for this property has an ellipsis push button that opens the Select Variable interface. If a variable is selected in this dialog box, subtle modifications to the generated code occur, such that it references the Value Variable instead of the Value value directly. This property has no default value.

Parent topic: The Report Controls and Property Reference


The Report Grid

When you create a graphical report, you have the option to include a report grid, which is similar in appearance and function to the ACUCOBOL-GT standard grid control.

The report grid can be used when you want to display data in a standard column layout with a heading. Unlike the report table control, a report grid is always oriented with a heading row above one or more rows of data. The grid can be a single heading row with a single line of data (the grid is the result of one READ statement) or the grid can contain several rows of data (each grid line is the result of one READ statement).

Information about the code used to populate a grid with multiple rows of data can be found in Using Events to Populate a Report with Data.

The report grid Property window contains the following control-specific properties in addition to the properties described in Common Report Control Properties.

Auto Resize

A drop-down box allows the selection of TRUE or FALSE. With a setting of TRUE (the default), a report grid automatically expands to fit the data content size. The FALSE setting should be used with caution. When this property is set to FALSE, the report grid uses the Lines property to determine its size, which may be inadequate to contain all your data.

Column Headings

A drop-down box allows the selection of TRUE or FALSE.

A setting of TRUE (the default) provides the user a place to enter a heading row for grid column titles.

A setting of FALSE removes the heading row. When Column Headings is set to FALSE, you can use the Page Header section of the report to provide the titles for the grid columns.

Columns' Setting

The Value cell for this property has an ellipsis push button that opens the Columns' Setting dialog box. Click the Add push button in this interface to add a row with the following default settings:

Column | Default Setting
Name | RwGd-1-Col-1
Pic | X(80)
Width | 1.00
Align | Unaligned

In the Name column, use the ellipsis push button to select a variable from graphical Working-Storage or from a data set. Set the Picture clause accordingly. In the Head column, type the column title. Width uses the unit of measure set in the Tools > Options > Report Writer > General interface. Use the Align column to set justification. Double-click in the More column to open a More dialog box, in which you can set Color, Font, and Hyperlink properties.

Repeat this procedure as needed for all of the fields you wish to have in your report grid.

Heading Color

The default setting for this property is foreground black on background gray. The Value cell for this property has an ellipsis push button that opens the Color Setting dialog box. Foreground and background colors can be set in this interface.

Row Color Pattern

The Value cell for this property has an ellipsis push button that opens the Row Color Pattern dialog box. The Add push button in this interface opens the Color Setting dialog box, in which you can select background and foreground colors. You can observe your chosen pattern in the Preview area on the right of the Row Color Pattern interface.

Up and Down arrows permit you to rearrange color patterns you have defined, and a Remove button lets you delete color patterns.

Repeat this procedure to edit existing colors or to extend the Row Color Pattern.

Show Grid Line

A drop-down box allows the selection of TRUE or FALSE. A setting of TRUE (the default) causes subsequent lines in a grid to be separated by a line. A setting of FALSE removes all grid lines in the grid.

Parent topic: The Report Controls and Property Reference


The Report Image

Available only for graphical reports, the report image corresponds to the ACUCOBOL-GT standard bitmap control. You use the Open dialog box to position a report image in the Report Composer window.

Note that in addition to placing one or more image controls on a report, you can also specify a Watermark property for the report (discussed in Configuring Report and Section Properties) or display images in a report table control.

The report image Property window contains the following control-specific properties in addition to the properties described in Common Report Control Properties.

Bitmap

The Value cell for this property has an ellipsis push button that displays the Open dialog box, from which you can navigate to *.bmp files. The Bitmap property records the name of the selected bitmap file. If the selected bitmap is not in a directory contained in the COPYPATH environment setting, the full path to the bitmap is recorded here.

Bitmap Path

A drop-down box allows the selection of Full Path, Dynamic Full Path, and User Defined. These property selections affect how the bitmap file is located:

With the Full Path setting (the default), the browser uses the full path of the bitmap (as recorded when it was selected in the Report Composer) to locate the bitmap file.

When you set this property to Dynamic Full Path a call to the C$FULLNAME library routine is used to derive the full path of the bitmap file. The bitmap can be stored in any of the FILE-PREFIX directories named. The browser uses the full path of the bitmap to locate the bitmap file.

With the User Defined setting, the browser searches for the bitmap in the same directory as the HTML file.

Bitmap Position

A drop-down box allows the selection of Center, Left Top, Left Bottom, Right Top, and Right Bottom. Use these settings to position your bitmap in the report image control (when the Bitmap Style property is set to Ratio).

Bitmap Style

A drop-down box allows the selection of Stretch and Ratio. This property has no default value.

When Bitmap Style is set to Ratio, the bitmap’s height-to-width ratio is preserved inside the space allocated for the bitmap. If the bitmap display is smaller than the space allocated for it, the positioning function is similar to the justification of a text field, orienting to left, right, top, bottom, and center.

When Bitmap Style is set to Stretch, the bitmap height-to-width ratio is altered if necessary to fit the bitmap into the space allocated for it. Note that when Bitmap Style is set to Stretch, the Bitmap Position property setting is ignored.

Print If Repeat

A drop-down box allows the selection of TRUE or FALSE. This condition is applied when consecutive records contain the same data values. When this property is set to TRUE (the default), both data values print. When it is set to FALSE, the second (and subsequent) same data values do not print.

Value Variable

The Value cell for this property has an ellipsis push button that opens the Select Variable interface. The Value Variable is not directly referenced by the generated code, but may be used by the user.

Parent topic: The Report Controls and Property Reference


The Report Label

The report label is similar to the ACUCOBOL-GT standard label control. The title of a report label, however, must be a literal value. You cannot associate a variable with a report label control. If you want to use a variable to display text in a report, use the report entry field control

The report label Property window contains the following control-specific properties in addition to the properties described in Common Report Control Properties.

Justification

A drop-down box allows the selection of Center, Left, Right, or Unaligned justification for the report label. The default value for this property is Unaligned.

Parent topic: The Report Controls and Property Reference


The Report Line

The report line is similar to the ACUCOBOL-GT bar control. This report element can be useful in a report's header and footer sections, for example, for underscoring column headings or totals. The report line Property window contains the following control-specific properties in addition to the properties described in Common Report Control Properties.

Kind

A drop-down box allows the selection of HORIZONTAL and VERTICAL. The default value is HORIZONTAL.

Size (Lines)

This property represents the width of a horizontal report line or the height of a vertical report line.

Note that the standard unit of measure used by Size is set in the Tools > Options > Report Writer > General dialog box. In this interface, you can select Inch (the default) or Centimeter in the Unit frame.

Width

The value of this property is a unit of measure in pixels. The default value is 1. For a horizontal line, this measure is the width of the line from top to bottom. For a vertical line, this measure is the width of the line from left to right.

Parent topic: The Report Controls and Property Reference


The Report Occurs

The report occurs control lets you take advantage of the OCCURS clause to display report information in a table or array. It is available only for graphical reports. The report occurs Property window contains the following control-specific properties in addition to the properties described in Common Report Control Properties.

Auto Resize

A drop-down box allows the selection of TRUE or FALSE. A setting of TRUE (the default) automatically expands a report occurs to fit the data content size. The FALSE setting should be used with caution. When this property is set to FALSE, the report occurs uses the Lines property to determine its size, which may be inadequate to contain all your data.

Column Headings

A drop-down box allows the selection of TRUE or FALSE.

A setting of TRUE (the default) provides the user a place to enter a heading row for occurs column titles.

A setting of FALSE removes the heading row. When Column Headings is set to FALSE, you can use the Page Header section of the report to provide the titles for the occurs columns.

Columns' Setting

The Value cell for this property has an ellipsis push button that opens the Columns' Setting dialog box.

In this interface, when you select the dominant occurs data item, the drop-down box at the top of the screen lists all the possible candidates in your graphical Working-Storage and data sets. To be a candidate, the data item must contain an OCCURS clause. The occurs displays in the top portion of the dialog box.

Level | Field Name | Picture | Usage | Occurs
03 | Notes |  |  | 8
05 | Note-Date | X(10) |  |
05 | Note-Initials | X(3) |  |
05 | Note-Text | X(60) |  |

To transfer Note-Date, Note-Initials, and Note-Text from this table into the Occurs Columns table below, double-click them.

Name | Picture | Head | Width | Alignment | More
Note-Date | X(10) | Note-Date | 1.00 | Unaligned |
Note-Initials | X(3) | Note-Initials | 1.00 | Unaligned |
Note-Text | X(60) | Note-Text | 1.00 | Unaligned |

In the Head column, you can replace the listed name with a column title of your choosing. Width uses the unit of measure set in the Tools > Options > Report Writer > General interface. Use the Alignment column to set justification. Double-click in the More column to open a More dialog box in which you can set Color, Font, and Hyperlink properties.

Repeat this procedure as needed for all of the fields you wish to have in your report occurs.

Note that the Occurs Columns interface is similar to the Grid Columns interface and also allows you to add and remove fields.

Row Color Pattern

The Value cell for this property has an ellipsis push button that opens the Row Color Pattern dialog box. The Add push button in this interface opens the Color Setting dialog box, in which you can select background and foreground colors. You can observe your chosen pattern in the Preview area on the right of the Row Color Pattern interface.

The Up and Down arrows permit you to rearrange color patterns you have defined, and a Remove button lets you delete color patterns.

Repeat this procedure to edit existing colors or to extend the Row Color Pattern.

Show Grid Line

A drop-down box allows the selection of TRUE or FALSE. A setting of TRUE (the default) causes subsequent lines in a report occurs to be separated by a grid line. A setting of FALSE removes all grid lines in the report occurs.

Parent topic: The Report Controls and Property Reference


The Report Radio Button

The report radio button is similar to the ACUCOBOL-GT standard radio button control. Like the ACUCOBOL-GT standard control, the report radio button can be assigned to a group and given a value within that group. The report radio button Property window contains the following control-specific properties in addition to the properties described in Common Report Control Properties.

Group

The Group property setting is included for user documentation purposes. Radio buttons in the same group should be handled together, so that the selection or deselection of report radio buttons is coordinated.

Value

This property must be set to 0 or 1. A value of 0 (the default) indicates that the report radio button is not selected in the report. A value of 1 indicates that the report radio button is selected in the report.

The report radio button is a stylistic display device. You need to code for the conditions that cause a particular radio button to be selected. A logical place to perform this check is in a Before-Print paragraph for a report radio button. The follow example shows one way to handle a group of radio buttons displaying credit card information:

INITIALIZE ws-credit.
EVALUATE card-type
   WHEN "M"
      MOVE 1 TO ws-mastercard
   WHEN "V"
      MOVE 1 TO ws-visa
   WHEN "A"
   MOVE 1 TO ws-amex
END-EVALUATE.

For another approach, refer to sample Report1d in the Reports sample project.

Value Picture

This property affects the picture clause of the generated value variable. It must be a numeric value. The default value for this property is X(1).

Value Variable

The Value cell for this property has an ellipsis push button that opens the Select Variable interface. If a variable is selected in this dialog box, subtle modifications to the generated code occur, such that it references the Value Variable instead of Value directly. This property has no default value.

Parent topic: The Report Controls and Property Reference


The Report Table

In a graphical report, the report table allows you to format your detail section in a grid-like table. This control is not available in character reports.

At its simplest, a report table displays the result of a single READ statement (or equivalent) with corresponding header information. You can control whether the data is printed with a horizontal or vertical orientation. This can provide a useful way to align and group header and body information.

A report table can also be used to display images. Any cell in a table can be associated with an image file or image variable. The use of an image variable in a table is demonstrated in the Report1f sample program. In the sample, a group section has been established to organize the report data by state. A table displayed in the group header shows an image of the state flag associated with the selected state.

Additionally, a report table can be used to display multiple lines and columns of literal values. Multiline labels are not supported in reports, but a multiline table with no grid lines or border can be used to create the effect of a multiline label.

The report table Property window contains the following control-specific properties in addition to the properties described in Common Report Control Properties.

Bitmap Path

A drop-down box allows the selection of Full Path, Dynamic Full Path, and User Defined. These property selections affect how the bitmap file is located.

With the Full Path setting (the default), the browser uses the full path of the bitmap (as recorded when it was selected in the Report Composer) to locate the bitmap file.

When you set this property to Dynamic Full Path, a call to the C$FULLNAME library routine is used to derive the full path of the bitmap file. The bitmap can be stored in any of the FILE-PREFIX directories named. The browser uses the full path of the bitmap to locate the bitmap file.

With the User Defined setting, the browser searches for the bitmap in the same directory as the HTML file.

Note that in the Table Setting dialog, the Cell Setting tab has a Type column, in which you can indicate that a table cell should contain an image. The Cell Setting tab then allows you to locate the bitmap file which should be displayed in that cell.

The Bitmap Path property applies to all image files so designated in the table.

Cell Padding

Cell padding adds blank space between the text in a cell and the horizontal grid lines above and below that text. The unit of measure for this property is pixels. Values of 1 through 5 are permitted, with a default value of 1.

Cell Spacing

Cell spacing adds blank space between the vertical grid lines and horizontal grid lines in a table cell. The unit of measure for this property is pixels. Values of 1 through 5 are permitted, with a default value of 1.

Merge Cell

Merge Cell lets you remove column dividers from a row.

The Value cell for this property has an ellipsis push button that opens the Merge Cell dialog box. In this interface, click the left-most column of the adjacent columns you wish to merge, and drag your mouse across the columns you want to merge. Click Merge Cell and OK to return to the Report Composer window.

To restore the columns to the way they were, select the merged cell and click the Recover Cells push button.

Note that the Merge Cell operation removes any column titles or values from the selected columns. A Restore Cell operation restores the individual cells that you merged, but maintains only the title or value of the left-hand cell where you started the merge operation. Restore Cell is not an undo operation.

Also note that if you perform a Merge Cell operation on a table, you cannot subsequently perform the Table Rearrange function.

Show Grid Line

A drop-down box allows the selection of TRUE or FALSE. A setting of TRUE (the default) causes table cells to be separated by a grid line. A setting of FALSE removes all grid lines inside the table.

Table Rearrange

A table may be rearranged in any number of ways by row or by column and still retain an identical number of cells. For example, a 4 x 2 cell table may be rearranged as a 2 x 4, a 1 x 8, or an 8 x 1 cell table.

The Value cell for this property has an ellipsis push button that opens the Table Rearrange dialog box.

In a column measure rearrangement, the cells are selected from left to right, top to bottom, and reconfigured so that the same cells are displayed top to bottom, left to right.

In a row measure rearrangement, cells are selected from top to bottom, left to right, and reconfigured so that the same cells are displayed left to right, top to bottom.

Note that the Table Rearrange function is disabled if a Merge Cell operation has been performed.

Table Setting

The Value cell for this property has an ellipsis push button that opens the Table Setting dialog box, with tabs for Column Setting, Row Setting, and Cell Setting.

The Column Setting tab lets you set column width, alignment, color, color variable, and font. In the Row Setting tab, you can set row height, alignment, color, color variable, and font. The Cell Setting tab lets you set each cell’s type, data, pic, and alignment, along with elements in the More dialog.

  • Table Setting Dialog's Column Setting Tab
  • Table Setting Dialog's Row Setting Tab
  • Table Setting Dialog's Cell Setting Tab
Parent topic: The Report Controls and Property Reference


Table Setting Dialog's Column Setting Tab

Column Width

This setting represents the width of the table column. The standard unit of measure is set in the Tools > Options > Report Writer > General interface.

Alignment

A drop-down box allows the selection of Center, Left, Right, or Unaligned. This field defaults to Unaligned.

Color

The default value of 0 allows the column to inherit the color of the table. Double-click in the Color cell to activate an ellipsis push button that opens the Color Setting dialog box. Foreground and background colors can be set in this interface.

Color Variable

Double-click the Value cell to activate an ellipsis push button that opens the Select Variable interface. If a variable is selected in this dialog box, subtle modifications to the generated code occur, such that it references the Color Variable instead of the Color value directly. This field has no default value.

Font

A drop-down box displays several choices for font. The default value for this cell is Default Font. You can also double-click in the Font cell to activate an ellipsis push button that opens the Font dialog box.

The column Font setting of a table overrides the Font property setting of its parent control.

Parent topic: The Report Table


Table Setting Dialog's Row Setting Tab

Row Height

This cell represents the height of the table row. The standard unit of measure is set in the Tools > Options > Report Writer > General interface.

Alignment

A drop-down box allows the selection of Middle, Top, Bottom, or Unaligned. This field defaults to Unaligned.

Color

The default value of 0 allows the row to inherit the color of the table. Double-click the Color cell to activate an ellipsis push button that opens the Color Setting dialog box. Foreground and background colors can be set in this interface.

Color Variable

Double-click the Value cell to activate an ellipsis push button that opens the Select Variable interface. If a variable is selected in this dialog box, subtle modifications to the generated code occur, such that it references the Color Variable instead of the Color value directly. This field has no default value.

Font

A drop-down box displays several choices for font. The default value for this cell is Default Font. You can also double-click in the Font cell to activate an ellipsis push button that opens the Font dialog box.

The row Font setting of a table overrides the Font property setting of its parent control.

Parent topic: The Report Table


Table Setting Dialog's Cell Setting Tab

Cell

This field contains the coordinates of the table cell, presented in the format (X,Y). In this format, the cells in a table's top row would have the coordinates (1, 1), (1, 2), (1, 3), and so on. The cells of the table's second row would have coordinates of (2, 1), (2, 2), (2, 3), and so on.

Type

The selection of Type affects the behavior of the Data and Pic columns. A drop-down box allows the selection of Text, Variable, Image, and Data Image. This field defaults to Text.

Data

The contents of this field depend on the settings in the Type column. When the Type setting is Text, Data contains a character string, which is constant. When the Type setting is Variable, Data contains a variable selected from the Select Variable interface. When the Type setting is Image, Data contains a bitmap selected from the Open Files of Type*.bmp interface. When the Type setting is “Data Image, Data contains a variable selected from the Select Variable interface.

Pic

This field is used only when the Type setting is Variable or Data Image. It displays the picture clause of the variable represented in the adjacent Data cell.

Alignment

A drop-down box allows the selection of Top-Left, Top-Center, Top-Right, Center-Left, Center, Center-Right, Bottom-Left, Bottom-Center, Bottom-Right, or Unaligned. This field defaults to Unaligned.

More

Double-click in the More cell to open the More dialog box. You can set Color, Color Variable, Font, Hyperlink, and Hyperlink Variable properties in this interface.

Parent topic: The Report Table


Working with ACUCOBOL-GT Utilities

  • ACUCOBOL-GT Utilities.
  • The Object File Utility
  • Using vio
  • Using logutil
  • Using vutil
  • Using acu4glfd
  • XML Support in AcuBench
Parent topic: AcuBench Version 10.2.0 User's Guide


ACUCOBOL-GT Utilities.

AcuBench provides access to several of the ACUCOBOL-GT® tools and utilities through the Tools drop-down menu. Most of these utilities have a default command-line interface, but AcuBench provides an additional, graphical interface to each one. You access the graphical interface when you choose a utility from the Tools menu.

The tools and utilities accessed through the Tools menu include the following:

  • cblutil, the object file utility
  • vio, the file transfer utility
  • logutil, the transaction log file utility
  • vutil, the Vision file utility
  • xml2fd, used to parse XML documents to produce FD and SELECT COPY files
  • AXDEFGEN, the ActiveX definition generator
  • NETDEFGEN, the .NET definition generator
  • acu4glfd, used by the Acu4GL® family of interfaces to produce FD and SELECT COPY files for interoperating with relational database management systems

The first four utilities listed above (cblutil, vio, logutil, and vutil) are described in detail in Debugger and Utilities. The next three utilities (AXDEFGEN, NETDEFGEN, and xml2fd) are discussed in A Guide to Interoperating with ACUCOBOL-GT. The final utility, acu4glfd, is described in Working with COBOL.

This chapter offers an overview of the utilities available from within AcuBench, describing any AcuBench-specific behaviors of the tool. It does not give detailed information about the general capabilities or uses of each utility. See the appropriate document (listed above) if you need more information about the functionality provided by any utility.

Parent topic: Working with ACUCOBOL-GT Utilities


The Object File Utility

AcuBench offers a graphical interface to the ACUCOBOL-GT object file utility, cblutil. This utility can be used to assemble individual object files into object libraries, display information about object files, and translate portable object files (or libraries) into a native code format.

Note: This section describes only the AcuBench graphical interface to cblutil. For a complete description of cblutil functions, see Debugger and Utilities.
  • Object Libraries
  • Creating an Object Library
  • Retrieving Information About Objects
  • Generating Native Code
Parent topic: Working with ACUCOBOL-GT Utilities


Object Libraries

An object library is a file that contains a group of one or more compiled ACUCOBOL-GT programs and its associated resource files (such as bitmaps and WAV files). Object libraries can simplify the distribution of an application by reducing the number of files involved. They can also help improve performance by reducing the number of directory operations performed by runcbl when it is loading object modules.

When you create an object library, the first module (compiled object) that you specify is called the primary module. When the library is loaded via a CALL statement or because it is the first program of the run unit, the primary module is the program that is loaded and run. Other modules in the library can be loaded by subsequent CALL statements.

You should keep several things in mind when you work with the cblutil object library utility:

  • A module that has the same name as a module already in the library will automatically replace the module of the same name. Therefore, before you build your library be careful to check that all modules have unique names.
  • We recommend that you place related object files in the same object library. For example, specify the main program of a run unit as the primary module and then add some or all of its subprograms.
Parent topic: The Object File Utility


Creating an Object Library

To access the object file utility from within AcuBench, open the Tools menu and select Cblutl. The Cblutl32 window opens with the Library tab selected.

The Library tab of the Cblutl interface is used to create an object library. The options contained in this interface correspond to the cblutil -lib command.

To use this interface to create a library file:

  1. Use the options in the Parameters section to build a cblutil command line.
    • Check the Name of object library (-o) check box and provide a name for the library you want to create in the entry field.
    • Specify whether you want the utility to operate silently or in verbose mode with the Verbose mode (-v) check box.
    • Use the Delete modules after they have been added to the library (-r) check box to indicate how modules in the library are treated after the library is created.
    • To include a comment in the compiled object, use the Insert comment (-c) field. Comments that include spaces must either be set off by quotation marks or include an escape character before each space.

    You access the object file utility from within AcuBench through the Tools menu.

  2. In the Additional modules area, use the New (+) button to add modules to the library. When you click this button, a browse (...) button appears in the field. You can use the browse button to navigate to your object files on disk, or type the path and file name in the field.

    To remove a module from the library, click the Delete button.

  3. Use the Up and Down arrow buttons to re-order the modules as needed. The first item in the list will be the primary module at run time.
  4. Click Apply to create your object library. Unless you have specified a different path in the Name of object library (-o) field, the library is created in the same directory as the primary module.

    Information about the object library that you have created appears in the box located below the Options entry field.

Parent topic: The Object File Utility


Retrieving Information About Objects

To display information about an object file (equivalent to the ACUCOBOL-GT cblutil -info command), you use the Information tab of the Cblutl32 dialog box.

Here, you can specify one or more object files or object libraries and view information about how each was created and what resources are included in the object. As you make changes in the interface, the Options field displays the command line for the information function.

To retrieve information about an object file or object library:

  1. Use the New (+) button, then specify the name of the module(s) whose information you would like to view. You type a path and file name in the field or use the browse (...) button to navigate to the file.

    Note that by default, the utility looks for files with a .acu, .cbx, or .obj extension. Expand the Files of type drop-down list in the Select Object File dialog to change the extension to .lib or other file extensions.

    To remove a module from the list, click Delete (“X”).

  2. To see the compiler options used to create each object in a library, as well as any comment information included in the object or library, mark the Show extended file information (-x) check box.
  3. Click Apply to activate the information function. Information from the header of the selected object file appears in the box located below the Options field.
Parent topic: The Object File Utility


Generating Native Code

To translate ACUCOBOL-GT portable object modules into native code object modules, you use the Native Code tab of the Cblutl32 window. This is equivalent to invoking the cblutil -native command.

To create a native object or library:

  1. Use the Parameters section of the interface to specify the type of native code that you want to create.
    • Provide a name for your object library in the entry field to the right of the Name of object library (-o) check box.
    • Specify the processor type for which you want your object optimized.
    • Select optimization options and indicate whether or not the utility should operate in verbose mode using the check boxes to the right of the Produce Native Code area.
  2. Specify the module(s) that you want translated into native code in the Additional Modules entry box. As in the other Cblutl32 interface, use the New, Delete, and arrow buttons to arrange modules.

    The Options entry field displays the command line for the native code function.

  3. Click Apply to generate native code object modules.

Note that you can also transform portable objects to native code from the File view of the Workspace window. Right-click an object in the Object folder and select Native Code.

In the Translate Portable Object Code to Native Code interface, select a processor type and a series of commands to pass to cblutil. Click Translate to create the native object file.

Parent topic: The Object File Utility


Using vio

vio is a file transfer and archive utility that allows you to create file archives and access archive content. vio is well suited for moving files to different operating systems because it is available on most platforms supported by ACUCOBOL-GT and because it automatically adjusts for certain machine-dependent aspects, such as byte-swapping. It also easily handles multiple volumes.

vio runs in two modes: input mode and output mode. Use output mode to create an archive. Use input mode to read and extract from an archive. Each mode has a distinct set of options. For a complete description of vio, including its options, see File Transfer Utility — vio.

The vio Interface

You launch vio by clicking the Vio command from the Tools drop-down menu. AcuBench displays the Vio Utility dialog box.

The Vio Utility dialog box includes two tabs, Input and Output. Select the mode that you want to use by clicking the corresponding tab. You can switch between tabs at any time.

Note: Use caution when specifying full path names. Some operating systems do not interpret or translate full paths properly. It is preferable, in most cases, to use relative path names when transferring files to a different operating system.
  • Output Mode
  • Input Mode
Parent topic: Working with ACUCOBOL-GT Utilities


Output Mode

When you want to create a file archive, click the vio Output Mode tab.

Create a vio archive using the following steps:

  1. From the Archive entry field drop-down list, select the target storage device. Selecting File causes the archive to be placed on the system hard disk.
  2. In the entry field to the right of the Archive drop-down list, enter the path and name of the archive, or click the ellipsis button to navigate to an existing file.
  3. In the Parameters section, select the options that you want. The Option field displays the command line that reflects the options chosen. You cannot directly edit the contents of this field. For a complete description of all vio options, see File Transfer Utility — vio.
  4. Build the list of files to be archived in the Collect files area. Click the Add files button in this area to build your list. The Add Files dialog allows you to browse the file system to locate the file(s) you want to add. Use the Delete button to remove a selected file. Select the Include Subdirectories check box to include all files and subdirectories in the current directory. Repeat this procedure until all the files you want have been added.
  5. To toggle the file type of any file on the list, select the file from the list and click the Toggle mode button. The current designated file type for any file on the list is indicated under the Mode heading
  6. To build the archive, click the Start collect button.
  7. When you are finished, click Close to exit vio.
Parent topic: Using vio


Input Mode

When you want to read and extract from a file archive, click the vio Input Mode tab.

You can read and extract a vio archive as follows:

  1. Select the device that hosts the archive file from the Archive drop-down list. Select File if the archive is located on a system disk.
  2. In the entry field to the right of the Archive drop-down list, enter the path and name of the archive file, or click the ellipsis button to navigate to the archive file
  3. In the Parameters section, select the desired options. The Option field displays the command line that reflects the options chosen. You cannot directly edit the contents of this field. For a complete description of all vio options, see File Transfer Utility — vio.
  4. Read the archive. Click View to read the archive file and display its contents.
  5. Extract the archive. In the Extract to entry field at the bottom of the vio window, enter the path of the target directory, or click the ellipsis button to navigate to a target directory.

    To extract the contents of the archive to the target directory, click the Start Extract button at the far right of the Extract files label. The contents of the archive are placed in the target directory.

Click Close to exit vio.

Parent topic: Using vio


Using logutil

ACUCOBOL-GT provides basic transaction management facilities, including extended COBOL transaction syntax and transaction logging capabilities. The utility program logutil is used to examine and edit ACUCOBOL-GT transaction log files built specifically for the Vision file system.

This section provides a description of the graphical interface to logutil provided by AcuBench. For a complete description of ACUCOBOL-GT transaction management facilities, see Transaction Management. For a complete description of the command line interface to logutil, as well as the report format, see logutil.

The graphical interface to logutil

To launch logutil from within AcuBench, select the Logutil command from the Tools drop-down menu. AcuBench displays the Log Utility dialog.

You can generate a report from a transaction log file as follows:

  1. Enter the name of the log file in the Log file field. You can either type the name directly into the field or use the browse (...) button to navigate to and select the file.
  2. In the Parameters section, select your options. The Option field displays the command line that reflects the options chosen. You cannot directly edit the contents of this field. For a complete description of all logutil options, see logutil.
  3. To start the report, click Start. The results are displayed in the lower portion of the window.

    To interrupt a report that is in progress, click the Stop button (the Start button becomes a Stop button after the search begins).

  4. When you are finished, click Close to exit the utility.
Parent topic: Working with ACUCOBOL-GT Utilities


Using vutil

The ACUCOBOL-GT Vision file utility, vutil, is used with Vision indexed files to extract file structure information, extract records, rebuild corrupted files, retrieve deleted records, and more. When you work in AcuBench, you can interact with this utility through a graphical interface accessed from the Tools menu. This section describes that graphical interface to vutil.

For a complete description of the command line utility and its functions, see Vision File Utility — vutil.

Note: vutil does not make use of the runtime configuration file. Settings made in a runtime configuration file do not affect vutil in any way.

The basic steps involved in invoking any vutil function are as follows:

  1. To open vutil, select the Vision File Utility command from the Tools drop-down menu.

    The graphical Vision File Utility dialog includes several tabs, each of which provides access to a different vutil function. To select a function, simply click the corresponding tab.

  2. Because vutil operates on Vision indexed files, each vutil function requires that you specify the name of a Vision file. You can either type the name of the file in the Data file (or Source file or File name) field, or click the browse (...) button to navigate to the file.

    As long as the vutil dialog is open, the name of each file specified is added to a drop-down list associated with the file name field. You can easily select a previously referenced file from this list.

  3. If you have chosen a function that can take parameters, use the Parameters section to build your vutil command line.

    An Option field displays the command line that reflects the options chosen. Note that you cannot directly edit the contents of this field.

  4. Click Start to perform the operation that you have specified. The results of the operation appear in the area near the bottom of the dialog.

    To stop a vutil function that is in progress, click the Stop button (the Start button becomes a Stop button when a vutil function is in progress). If you attempt to select another vutil tab while the current action is in progress, the message Vision File Utility is running. Please wait. is displayed.

  5. To close the vutil interface, stop or allow the current action to complete and click Close.
  • Increasing the Maximum File Record Size
  • Examining File Information
  • Testing File Integrity
  • Modifying Keys
  • Rebuilding Files
  • Resetting User Counts
  • Creating Empty Files
  • File Size Summary
  • Extracting Records
  • Unloading to Other File Types
  • Loading a File
  • Converting Indexed Files
  • B-Tree Listing
  • Testing for Vision File Locking Compatibility
Parent topic: Working with ACUCOBOL-GT Utilities


Increasing the Maximum File Record Size

The vutil augment function is accessed on the Augment tab. The augment function lets you increase the maximum record size of a Vision file. This option is useful if you want to add fields to a record without having to rebuild the entire data file.

Parent topic: Using vutil


Examining File Information

The vutil information function is accessed on the Information tab. The information function extracts basic information from the specified Vision file. All extracted information is displayed in the bottom half of the tab.

Parent topic: Using vutil


Testing File Integrity

The vutil test file function is accessed on the Testing File tab. The test file function checks a Vision file for integrity. Integrity is examined on such points as whether a file is corrupt and whether it has a non-zero user count. Testing for file integrity should be one of the first actions taken in assessing data file problems.

Parent topic: Using vutil


Modifying Keys

Restriction: You can only modify keys in Vision files that are version 6 or later, and that are not encrypted.

The vutil function in which you can add, delete, or modify keys in an existing Vision file is available from the Update Key tab.

The tab contains the following options:

Option | Description
File name | The Vision file in which to modify the keys.
Operation | Select the required operation to perform on the file.
Key number | The key number to add, delete, or modify
Quiet mode (-q) | Check this option to suppresses the warning message that is generated informing you that the file is modified in place.
Define Key Information | When adding or modifying a key, you need to supply the number of segments, and the size and offset of those segments within the key.
List | Displays the command line equivalent of the selected options. See Modifying Keys in an Existing Vision File for details on the command line utility.
Start | Click Start to run the operation. If Quiet Mode is unchecked, a confirmation message displays in the bottom pane. Enter Y in the Input field and click Send to continue with the operation.

Comments:

Due to the nature of these operations, you should not perform them on a Vision file without backing it up beforehand. Any failure during the modification of the key structure could leave the file in an unrecoverable state, and requiring you to revert to a backup.

Before performing any of the modification operations, the Vision file is marked as broken, with a 97 sub-code (98,97 file status). Upon successful completion of the operation, this code is removed.

If a new or modified key is specified to not allow duplicate key values, and duplicate key values are found when the key is indexed, the setting will be overridden and the key will allow duplicate key values.

When altering the key structure of a file to allow duplicate key values, be aware that data may not be retrieved in the order that you expect when using that key. To distinguish duplicate key values, a unique value is assigned to each record containing the duplicate data. Usually, this happens as the record is written to the file, and so records can be retrieved using this data, in chronological order. By introducing duplicate keys on an existing file, the unique values must be assigned en masse, in the order that the records currently sit in the file; therefore, retrieving records using the key will not necessarily return them in the order in which they were written.

Parent topic: Using vutil


Rebuilding Files

The vutil rebuild file function is accessed on the Rebuild File tab. The rebuild file function recreates or rebuilds the specified indexed file. You should rebuild a file that has become corrupt, or one that contains a large number of deleted or lost records that you want to remove from the file. The vutil rebuild function has many options that allow you to control how the rebuilt file is created.

Note that the -m, -s, and -r options are not available in the graphical interface to vutil. To invoke these options, use the command-line interface to the utility.

Parent topic: Using vutil
Related reference
Rebuilding Files (command-line interface)


Resetting User Counts

The vutil reset function is accessed on the Resetting tab. This function allows you to reset the user count of the specified files to zero. The reset function eliminates the need to rebuild the file when the file has a non-zero user count and you are certain that the file is not corrupted.

Parent topic: Using vutil


Creating Empty Files

The vutil function that allows you to create a new, empty file is accessed on the Create File tab. The create file function is equivalent to performing an OPEN OUTPUT on a file in COBOL.

When you use the Create File tab of the Vision File Utility interface, there are a few points to keep in mind:

  • If you specify the name of an existing file when you invoke this function, that file will be overwritten.
  • By default, vutil creates the new file in Vision Version 6 format. If you want another format, use the Vision file format check box and drop-down list to make an alternate selection.
  • You can use the Define Key Information push button to open a special interface used to create, delete, and define keys for the new file. Use the buttons at the top of the screen to create or delete keys. Double-click in any key field to change its value.

For a complete description of the vutil create function, see Vision File Utility — vutil. For general information about Vision files, see Indexed Files - Vision.

Parent topic: Using vutil


File Size Summary

Use the File Size tab to access the vutil file size function, which reports summary disk usage information for the Vision file. Information returned includes total file size, the number of allocated records in use, the number of empty records, and the percentage of allocated records in use.

Parent topic: Using vutil


Extracting Records

The vutil extract record function is accessed on the Extract tab. The extract function allows you to display records stored in the specified file. The target file cannot be encrypted. If you attempt to use the extract function to view a record in an encrypted file, the message encrypted, extract not allowed is displayed.

After you enter a file name, specify extract parameters, and start the record extraction, the records matching your parameters are displayed in the field at the bottom of the Vision File Utility window.

Parent topic: Using vutil


Unloading to Other File Types

The vutil unload function is accessed on the Unload File tab. The unload function creates a binary sequential or line sequential file from the specified Vision indexed file.

Parent topic: Using vutil


Loading a File

The vutil load function is accessed on the Load File tab. The load file function creates an indexed file from a binary sequential file, relative file, or line sequential file.

Parent topic: Using vutil


Converting Indexed Files

The vutil convert function is accessed on the Convert tab. The convert function allows you to convert an indexed data file created by C-ISAM or RM/COBOL-85 into a Vision indexed file. This is useful when you are moving data from a C-ISAM or RM/COBOL-85 application to an ACUCOBOL-GT application.

Note: Because the Vision file replaces the original C-ISAM or RM/COBOL-85 file, be sure that you have a backup copy of the original file.

The convert function has a number of limitations. It does not convert files that have:

  • Record or block sizes greater than 32 KB
  • More than 120 keys
  • Individual keys larger than 250 bytes
  • Non-ASCII characters or collating sequence (RM/COBOL-85)
  • Split keys (RM/COBOL-85)
  • A single key with more than 16 segments (Vision Version 4) or more than six segments (Vision Version 3) (C-ISAM)
  • A primary key that allows duplicates (C-ISAM)
Note: When converting files you must have plenty of available disk space to accommodate the differences in file size between the original file type and the converted file type. You must also allow vutil space to copy the file during the conversion process.
Parent topic: Using vutil


B-Tree Listing

The vutil tree function is accessed on the B-Tree Info tab. The tree function outputs B-tree structure information for the specified file. It is used primarily as an aid in debugging suspected Vision file problems.

Parent topic: Using vutil


Testing for Vision File Locking Compatibility

Use the WTest tab to test a file system for the ability to perform atomic file operations, which is a requirement when you set V_LOCK_METHOD 2.

To test a file system in which you plan to access Vision files using the V_LOCK_METHOD 2 variable, specify an existing directory on that file system.

Also, specify a duration (in seconds) for the test to run. If no value or a value less than 30 is specified, the test will run for 30 seconds.

If the test fails, as clearly indicated by the output message, you should no set V_LOCK_METHOD 2 on that file system. If you do so, it will likely cause spurious file errors or file corruption.

Parent topic: Using vutil
Related reference
Testing for Vision File Locking Compatibility (command-line interface)
V_LOCK_METHOD


Using acu4glfd

A Windows utility called acu4glfd helps you create file descriptions (.fd) and SELECTS (.sl) for use with extend's Acu4GL interfaces. It can also determine a unique index, which it uses as the primary key.

Because this utility uses ODBC technology to obtain table information to list table fields, you need to have Acu4GL installed for the run-time to access the table.

You access this utility's interface via the Tools > acu4glfd command. You need to choose and connect to a data source. When the tables contained in the data source are displayed, users can direct the utility to create FDs and SELECTs.

More information about this utility can be found in Creating File Descriptors and SELECT Statements.

Parent topic: Working with ACUCOBOL-GT Utilities


XML Support in AcuBench

The ACUCOBOL-GT runtime has a file system interface for XML files, called AcuXML, that seamlessly converts XML data to COBOL data and vice versa. Information about working with XML data can be found in Working with XML Data.

When you make use of the AcuXML interface, you can use the xml2fd utility to derive an FD and SELECT statement from an XML file. When a file of type XML is selected, the import process must pass through the xml2fd utility. This utility's interface helps to guide you through the import of the XML file to an FD file, which is written into a project's .fd folder and imported into the AcuBench graphical File Designer.

xml2fd also returns a list of the lines where it's guessing about the data type. This prints to an stderr file and can be viewed in the Output window. The graphical File Designer is displayed, along with Output window information. When you click on a line in the Output window, the cursor is positioned at the line in the File Designer where the guessing occurred. You can then change the Picture clause, if desired, prior to regenerating the code.

To use xml2fd from within AcuBench, do the following:

  1. Select Xml2FD from the Tools menu, or right-click a project node in the Data view and select XML2FD.

    When you invoke xml2fd from the Data view, the utility understands the context of the project and prefills the -d option entry field with the name of the directory in which the FD and SL are stored.

    When xml2fd is invoked from the Tools menu, it does not have this context information, and therefore does not prefill the -d entry field.

  2. If necessary, click the browse (“...”) button next to the Output directory (-d) field to navigate to the directory into which you want the FD and SL to be generated.

    Use the -f and -s options if you prefer to generate the FD and SL into separate directories.

    Note that selecting -d causes -f and -s to be disabled, because they are mutually exclusive options. Likewise, if -f or -s is selected, -d is disabled.

    In the absence of any instructions (-d, -f, or -s) about where to write the output, output is written to the current working directory, typically the root of the active project.

  3. Set the -n option to specify the number of records to be read by the utility before it arrives at field descriptions in the FD. In very large XML files, it may not be desirable to read the entire file to derive the FD. On the other hand, it may be necessary to read more than one record to confirm a best guess for intended field descriptions in a record. The value of -n must be numeric and greater than 0.
  4. If you want to add a standard prefix to data items in the FD, use the -p option.
  5. Use the -o option with a numeric value greater than 0 to instruct xml2fd to look for cases within the record where it is appropriate to assign an OCCURS clause. The value that you specify provides a default number to assign in the OCCURS clause. In complex cases where an FD has more than one OCCURS clause and where the number of OCCURS differs, users must manually change the generated representation of the FD in the graphical designer.
  6. As you make changes in the XML2FD Utility window, the Options field displays the xml2fd command line that you are constructing. Verify this command line, then click Start to build the FD and SELECT.

    The Output window prints the output of xml2fd. More information about this utility can be found in XML-to-FD Utility.

Parent topic: Working with ACUCOBOL-GT Utilities


The AcuBench Integrated Debugger

  • The Debugger Interface
  • Debug Mode Compile Options
  • Entering the Debugger
  • Debug Menu Commands
Parent topic: AcuBench Version 10.2.0 User's Guide


The Debugger Interface

The integrated debugger provides most of the functional capabilities of the ACUCOBOL-GT runtime debugger, as well as a few AcuBench-specific features. Most notably, the integrated debugger offers you the ability to modify your code during debug, without leaving the debugger interface.

This chapter describes in detail those elements of the debugger interface that are unique to AcuBench. It also notes equivalencies between AcuBench and runtime debugger functions. For more information about those equivalent functions, see Runtime Debugger, which includes extended descriptions of debugger functions.

Note that if you prefer to use the ACUCOBOL-GT runtime debugger, instructions on how to access it from within AcuBench are included in Debugging a Program.

Integrated debugger functions appear in a Code Editor window in the development area of the workspace. The debugger interface also uses the Output window, usually displayed at the bottom of the screen, to display various output messages generated by the debugger. These messages may include such things as tracing information, information about breakpoints, and error messages.

When using the integrated debugger, you may want to open the File tab of the Workspace window. The File tab provides a tree view representation of your project's Source, Screen, Report, Copy, Object, List, Resource, FD, and Remote files. For more information about project files, see Creating a Project.

You can toggle the Output and Workspace windows on and off from the View menu or the Standard toolbar, or close them by clicking the Close button on each window. You can also resize windows by dragging their borders with the mouse.

The AcuBench integrated debugger offers several features to assist you in debugging your code:

  • The current line of execution is highlighted, and if the Line Number pane is visible, its line number is marked. You can toggle the highlighting and specify the highlight color in the Tools > Options > Environment > Debug dialog box, described in this manual in Debug Options.
  • You can make changes to your code while debugging. The changes do not affect the current execution of the program, but you can test the changes simply by restarting the debugger, as described in Starting Stopping and Navigating the Debugger.
  • Three specialized windows give you information about your code as you debug: Watch, Stack Info, and Memory. These windows can be displayed in the Output window or as floating windows, either one at a time or together, in any combination.
  • A Quick Watch window lets you select any variable in the source code and display its current value.
  • Using AcuConnect® with ACUCOBOL-GT's Thin Client technology, you can debug a program that resides on a remote server using the same AcuBench debug commands that are used to debug a local program.
  • Debug Menu and Toolbar
  • Debugger Output
  • Watch Window
  • Stack Info Window
  • Memory Window
Parent topic: The AcuBench Integrated Debugger


Debug Menu and Toolbar

AcuBench debug commands can be accessed from the Debug menu and the Debug toolbar. You can also create keyboard shortcuts for many debug commands. A complete list of user-definable shortcuts is found in Keyboard Shortcut Reference. Descriptions of the debug commands appear later in this chapter.

As with other workbench toolbars, the Debug toolbar can be customized by selecting Toolbars > Customize from the View menu. To display or hide the Debug toolbar, select Toolbars > Debug from the View menu. You can also toggle the display by right-clicking in the toolbar area and choosing Debug or by selecting Customize > Toolbars from the Tools menu and then setting or clearing Debug in the Customize dialog box.

Parent topic: The Debugger Interface


Debugger Output

Debugger messages appear in the Output window, which usually appears at the bottom of the AcuBench screen. If you have created an error file and are capturing trace information, you can also elect to display this information in the Output window.

Note that if you choose to send trace information to the Output window but no runtime error file exists, unusual screen behavior and additional undefined behaviors will result.

To send tracing information to the Output window:

  1. Use the Project Settings dialog to establish an error file. On the Runtime tab, first select the I/O options catalog, then mark the File to be opened for error message (-e) check box. Don’t forget to add an error file name in the entry field.
  2. Close the Project Settings interface.
  3. Open the Debug menu, expand the Trace Option sub-menu, and select Trace to Debug Window.

    Now, when you turn on the debugger’s tracing options, all generated trace information is sent both to the error file and to the Output window.

Parent topic: The Debugger Interface


Watch Window

The Watch window displays any program variables that you have selected. When you add a variable to the Watch window, the variable name appears in the Variable column, to the left of the variable's value. As the program executes, any changes to the values of the listed variables are displayed.

Note: Placing a watch on a variable does not cause the debugger to break when the value of the variable changes. If you want to monitor a variable and break when its value changes, use the Monitor tab of the Breakpoints window. For details, see Monitoring Variables Using the Breakpoints Dialog Box.

After you start a program in the AcuBench integrated debugger, you can set a watch in either of two ways:

  1. Use the Watch Window toolbar button to open the Watch window, or select Debug Window/Watch from the View menu. Double-click in a blank area of the Watch window to open a blank entry field, then enter the variable name.

    After you enter the name, the value displays automatically in the adjacent field.

  2. Select the desired variable name in your code, then right-click and select Add to Watch Window. You can also invoke this command from the Variable List by selecting a variable name in the box, right-clicking, and choosing Add to Watch Window.

    Note that the Watch window must already be open in order for this command to have an effect.

Once you have added variables to the Watch window, you can choose whether their values are displayed in standard alphanumeric format or hexadecimal format. To toggle between formats, right-click anywhere in the Watch window and select or de-select the Hexadecimal Display check box in the pop-up menu.

The Watch window can also be used to ACCEPT a variable as you debug. With the debugger window active, simply type a new value for the variable in the Value column of the Watch window. Note that you are able to add variables or change values in the Watch window only after you have entered or re-entered the debugger. When the program is in an ACCEPT loop, the Watch window remains visible, but is not enabled for editing.

To remove a variable from the Watch window, highlight the variable and press the Delete key.

Quick Watch Window

If the Watch window is not open, you can still retrieve the value of a variable by performing a quick watch. When you perform a quick watch, the selected variable and its value appear in a Quick Watch window. You can either close the Quick Watch window after viewing a variable's value, or click the Add Watch button to add the variable to the Watch window. If you add a watch on a variable when the Watch window is closed, AcuBench automatically opens the Watch window.

To perform a quick watch on a variable:

  • Double-click the desired variable in the Code Editor to open a Quick Watch window.
  • Highlight the desired variable in the Code Editor and click the Quick Watch toolbar button.
  • Right-click the desired variable in the Code Editor and select Quick Watch.

You can view the values of up to seven previously selected variables by choosing from the drop-down box at the top of the Quick Watch window.

Parent topic: The Debugger Interface


Stack Info Window

The Stack Info window is equivalent to the ACUCOBOL-GT debugger's View Perform Stack command. The window lists all of the nested paragraphs leading up to the current statement, from the beginning of the program or thread. As your program executes, the Stack Info window displays the source file name, line number, and paragraph.

By default, the Stack Info window displays the full path to a particular file. To toggle the display between the full path name and just the file name, right-click inside the Stack Info window and select Full Path Filename.

To position the cursor at a specific paragraph in your code, double-click the file path in the Stack Info window.

When you start a program in the debugger, you can view the Stack Info window either by choosing Debug Window > Call Stack from the View menu or with the Call Stack toolbar button. As your program executes, stack information (file path, line number, and paragraph name) appears in the window.

Parent topic: The Debugger Interface


Memory Window

The Memory window offers the same features as the ACUCOBOL-GT run-time debugger's Memory Usage command, displaying the amount of program, file, window, overhead, and total memory used by your program, including standard and paged memory.

After starting your program in the debugger, open the Memory window by selecting Debug Window > Memory from the View menu or by using the Memory Window toolbar button. Memory status information is displayed automatically in the categories mentioned above.

Parent topic: The Debugger Interface


Debug Mode Compile Options

In AcuBench, a mode is a set of compile options, runtime options, environment variables, and library options for a project. Debug Mode is one of two predefined modes in the workbench. In Debug Mode, the Include all debugging information (-Ga) compile option is automatically set, as well as the standard Name of object file (-o) and Ignore CBLFLAGS environmental variable (-x) options. For remote debugging, the Name of remote object file (-o) option is also set.

To select Debug Mode, use the Project > Set Active Mode command or select Debug Mode from the list box on the Project toolbar. You can also select Debug Mode in the Project Settings dialog box. More information about modes and how to add and delete them in AcuBench can be found in Modes.

AcuBench allows three levels of debugging: source, symbolic, and low. Source level debugging lets you view your source code while you are debugging. With symbolic debugging, your source code is hidden, but the Output window displays any error messages and warnings. To access the low-level debugging function from within AcuBench, compile with the -d option. Refer to the ACUCOBOL-GT User's Guide for further information on these three levels of debugging.

Before you enter the AcuBench debugger, you should compile your program with at least one of the following compile options available from the Project Settings dialog box:

-Ga | Turns on all debugging options
-Gd | Includes the source code in the compiled object file
-Gl | Includes line number information
-Gs | Includes extra symbol information for symbolic debugging. This allows AcuBench to traverse the symbol table of the COBOL program and show group data items in a tree view control
-Gy | Includes minimal symbol information for basic symbolic debugging

You can change debug compiler options in the Project Settings dialog box. Simply select the Compiler tab, choose Debugger Options from the catalog drop-down list box, clear the -Ga option, and select from among the other listed options.

Parent topic: The AcuBench Integrated Debugger


Entering the Debugger

To enter the AcuBench debugger, select the program in either the File view or the Structure view of the Workspace window, then select Go from the Debug menu. You can also click the Go button on the Debug toolbar or use a shortcut key (F8 by default). Note that the first time you select Go, the debugger opens the program source file and places the cursor at the first line of execution. When you select Go a second time, the program resumes execution from its current location. The program transfers control to the debugger when it reaches a breakpoint.

If your source file is already open in the Code Editor, you can launch the debugger by clicking on the editing window and selecting Go from the Debug menu.

Note that when your program is launched, a corresponding button is added to the Windows taskbar. When the program displays and accepts a screen, that screen does not automatically appear in the foreground. Click the button on the taskbar to shift focus from AcuBench to the running program.

Once a program has begun execution in the debugger, control is returned to the debugger in one of the following ways:

  • When a breakpoint is reached.

    User-defined breakpoints are discussed in more detail later in this chapter.

  • When a STOP statement executes that is not a STOPRUN.

    This behavior is similar to a breakpoint. Execution halts and the debugger cursor displays on a specific line. If you have not compiled with any debugging options, symbols and source are unavailable.

  • When the debugger steps through the program and reaches the step count.
  • When the Debug > Interrupt command is selected.
  • When a monitored variable changes.

If the Output window is closed, it pops up over the lower portion of the screen when you enter the debugger. You can open it at other times by selecting Output Window from the View menu or by clicking the Output Window toolbar button. When you quit or exit the debugger, the Output window remains open until you close it by toggling the Output Window button or View menu command, or by clicking the window’s Close button.

Parent topic: The AcuBench Integrated Debugger


Debug Menu Commands

The AcuBench Debug drop-down menu includes all the commands needed for debug functions. AcuBench also allows you to define keyboard key-combination shortcuts for many debug commands. For more information, see Keyboard Options. Debug commands are described in the following topics.

Note that while you are debugging, any function selected from the toolbar affects the active debugging session. For example, if you click Go while Checkbox.cbl is selected, and then select Combo.cbl and click Go a second time, the debugger behaves as though you have clicked Go a second time for Checkbox.cbl. Compile and Execute functions are disabled during a debug session. Therefore, if you want to perform any build-related functions, you must first exit the debugger.

  • Tracing Functions
  • Starting, Stopping, and Navigating the Debugger
  • Debugger Scripts
  • Breakpoints
  • Debugging Threaded Applications
  • Quick Watch
Parent topic: The AcuBench Integrated Debugger


Tracing Functions

The Debug menu's Trace Option commands generate output messages that describe operations performed in a given domain during program execution. You can invoke the various trace functions only through the Debug menu's Trace Option commands. Each function is described briefly below. More information about trace functions can be found in section Runtime Debugger of the ACUCOBOL-GT User's Guide.

Trace File toggles file tracing on and off. Output trace information includes all file-related operations performed at runtime. Trace level for this command can be set from 1 to 10 via the Trace Level dialog box described below.

Trace Paragraphs toggles paragraph tracing on and off. Output trace information includes all paragraphs and sections entered at runtime.

Trace Screens toggles screen tracing on and off. Trace output includes information about DISPLAYs of Screen section items and about CREATEs, DISPLAYs, MODIFYs, and INQUIREs of ActiveX objects. Trace level for this command can be set from 1 to 10 via the Trace Level dialog box described below.

Trace Flush toggles trace flushing on and off if you are writing to an error file. With this command, the error file is flushed to disk after each WRITE operation.

Trace General toggles general tracing on and off. Trace output includes information on operations not covered by either the Trace File or Trace Screens command. Trace level for this command can be set from 1 to 10 via the Trace Level dialog box described below.

Trace Levels displays the Trace Level dialog box, in which you can set the level of detail in the output messages generated.

Trace levels can be set for the Trace File, Trace Screens, and Trace General commands. The higher the trace level, the greater the amount of debugging information sent to the error file. Therefore, an entry of 10 generates maximum output and an entry of 1 generates minimum output. An entry of 0 (the default) generates no output. The extra information is useful primarily to the extend Technical Support department.

To designate an error file to receive trace level output, select the File to be opened for error message (-e) option in the Project Settings > Runtime > I/O options dialog box. Indicate the name of the error file in the adjacent entry field. Note that if you set a trace level of 10, and see no output, this can mean that program execution included no output triggers.

Trace to Debug Window toggles the display of trace output messages in the Output window. The trace information displayed may be the result of any trace command except Trace Levels. You should establish an error file before you use this command. See Debugger Output for information about directing output to an error file.

Parent topic: Debug Menu Commands


Starting, Stopping, and Navigating the Debugger

The Debug menu contains a number of navigation commands used to start, stop, and control the execution of your program in the debugger. Some of these commands are assigned default keyboard shortcuts; others have not been assigned shortcuts. In either case, you can create your own customized keyboard shortcuts for the navigation commands, as described in Keyboard Options.

Go, which is equivalent to the ACUCOBOL-GT debugger’s Run/Continue command, starts the selected program in the debugger. If your files are out of date, you may be prompted to recompile them (depending on the build options that you have specified). If you select the Go command a second time, it resumes execution of your program from the cursor’s current location. The program returns to the debugger when it reaches a breakpoint.

Restart ends the current debugging session and begins a new session with the same program. When you select Restart, the debug cursor returns to the first statement in the code. Restart is useful when you want to repeat the session or when you have altered lines of code and want to rebuild and begin a session from the first statement.

To have the debugger automatically rebuild your program when you restart, select Follow the options specified in the 'Build’ page in the Environment/Debug section of the Tools > Options window. To customize the Build rules for your project, go to the Environment/Build section of the Tools > Options window.

Exit Debugger halts the current debugging session but leaves the debugger open. It is equivalent to the ACUCOBOL-GT File > Exit command. Quit Debugging halts the debugging session and exits the debugger. It is equivalent to the ACUCOBOL-GT File/Quit command.

Interrupt stops execution of the application and returns control to the debugger, just like the Ctrl+Break shortcut. It creates a pause similar to that caused by a breakpoint, with one caveat: if the program is in a PERFORM or ACCEPT loop, the Interrupt command is not received until an exception occurs or the action completes.

After receiving the Interrupt command, the debugger cursor displays on the current line of execution. Note that you should use Go, rather than Restart, to continue debugging after using the Interrupt command.

Auto Step lets you execute step commands repeatedly until the program’s end. You can change the speed at which the command executes, from 1 (slowest, approximately 3 seconds per step) to 9 (fastest, several steps per second). When you select a speed level in the Standard area of the dialog, the actual speed is displayed in milliseconds per step. You can also use the Customize area to set a custom speed, specified in milliseconds per step.

Step Into allows you to step to the next statement in your program. You can use this command to step into a new thread when it is created. If you want to continue to track the original thread, use the debugger’s Step Over command.

Step Over allows you to step over the next statement in your program. Use this command if you want to track a single thread rather than stepping into a new thread each time one is created.

Step Out Paragraph runs your program until it returns to the point at which the command was invoked. It is equivalent to the ACUCOBOL-GT debugger’s Run/Go until Paragraph Returns command.

Step Out Program runs your program until it exits to its calling program. It is equivalent to the ACUCOBOL-GT debugger’s Run/Go until Program Exits command.

Skip to Line moves the current program location to the line containing the cursor. Further execution of your program proceeds from this line. The current program location does not change unless the cursor line contains a verb. This command is equivalent to the ACUCOBOL-GT debugger’s Run/Skip to Cursor Line command.

Use this command with care, because the skipped lines are not executed. You may skip important sections of code and experience unexpected results.

Run to Cursor sets a temporary breakpoint at the current cursor line (or the closest previous line with a verb) and continues execution of your program. It is equivalent to the ACUCOBOL-GT debugger’s Run/Go to Cursor Line command.

Parent topic: Debug Menu Commands


Debugger Scripts

A debugger script file contains keyboard input and menu selection information to automate the process of debugging a program.

To record a script, select Record Script rom the Debug menu. This command is equivalent to the ACUCOBOL-GT debugger’s File > Record Script command, and turns on a recorder that saves all of your keyboard input and menu selections to the file that you specify.

When the recorder is running, the Record Script menu option is replaced by a Stop Recorder option. Use this to end your recording. If you do not end your recording, nothing is saved in the file.

While the recorder is active, you cannot use the mouse for anything except selecting menu items.

The recorder can save up to 4096 characters of information. Normal keystrokes use one character. Special keys such as function keys and menu selections can use up to 4 characters.

To run a debugger script file, select Run Script from the Debug menu. This causes all input (debugger and program) to be read from the script. Control returns to the keyboard when the script is finished. This command is equivalent to the ACUCOBOL-GT runtime debugger’s File > Run Script command.

Parent topic: Debug Menu Commands


Breakpoints

A breakpoint is a location in your program’s code that you designate. When a breakpoint location is reached during program execution, control is returned to the debugger before the code at the breakpoint is executed.

Enabled breakpoints appear as red thumbtack icons in the Line Number pane of the debugger’s Code Editor window. Disabled breakpoints appear as yellow thumbtack icons.

Bookmarks that you set in your source code when you are working in the Code Editor automatically become breakpoints when you enter the debugger. These locations are marked with a standard bookmark icon, rather than the breakpoint thumbtack. Note that bookmarks are not included in the list of breakpoints displayed in the Debug > Breakpoints dialog box.

Breakpoints are most easily set and managed using the Debug toolbar buttons.

  • To set or remove a breakpoint, use the Toggle Breakpoint push button.
  • To temporarily disable a breakpoint, use the Disable Breakpoint push button.
  • To remove all breakpoints, use the Clear All Breakpoints push button.

You can also set, modify, and delete breakpoints using the Breakpoints dialog box. To do this, select Breakpoints from the Debug menu.

The Breakpoints dialog displays a list of all the breakpoints set in your code, including the file name, line number, skip count, and expression associated with the breakpoint, as well as whether the breakpoint is currently enabled. With the buttons in the upper right corner of the tab, you can view the code associated with a breakpoint, modify or delete a breakpoint, delete all breakpoints, or add a new breakpoint. Selecting the New or Modify button opens the Breakpoint Details dialog. The Breakpoint Details dialog allows you to enter or modify the file name, line, skip count, and expression of the breakpoint. You can also enable or disable a breakpoint and set monitors on variables using this interface.

All of these functions are described in the following topics.

  • Setting a Breakpoint using the Breakpoints Dialog Box
  • Modifying a Breakpoint using the Breakpoints Dialog Box
  • Deleting Breakpoints using the Breakpoints Dialog Box
  • Viewing a Breakpoint with the Breakpoints Dialog Box
  • Monitoring Variables Using the Breakpoints Dialog Box
Parent topic: Debug Menu Commands


Setting a Breakpoint using the Breakpoints Dialog Box

  1. Click Debug > Breakpoints to open the Breakpoints dialog box.
  2. On the Location tab, click New (the button in the top, right corner of the tab) or double-click in the window.

    The Breakpoint Details dialog box appears. By default, the Enable check box is checked.

  3. Fill in the file name, line number, expression, and skip count for your breakpoint.

    Use the Browse push button if necessary to locate your file name.

  4. Click OK to return to the Breakpoints dialog box.

    The location of your new breakpoint appears in the dialog box.

  5. Click OK.
Parent topic: Breakpoints


Modifying a Breakpoint using the Breakpoints Dialog Box

  1. Click Debug > Breakpoints to open the Breakpoints dialog box.

    The Location tab displays a list of the current breakpoint locations, along with each breakpoint's file name, line number, skip count, and expression.

  2. Click Modify (the second of the five buttons in the top, right portion of the tab).

    The Breakpoint Details dialog box appears. Here, you can enable or disable a breakpoint, change the file name, or alter the line number, expression, or skip count.

  3. Click OK to return to the Breakpoints dialog box.

    The modifications to your breakpoints are now reflected in the Breakpoints list.

  4. Click OK.
Parent topic: Breakpoints


Deleting Breakpoints using the Breakpoints Dialog Box

  1. Click Debug > Breakpoints to open the Breakpoints dialog box.
  2. On the Location tab of the dialog box, click the breakpoint you want to delete.
  3. Click Delete (the third of the five buttons in the top, right portion of the tab). To remove all your breakpoints, click Delete All (next to the New button).
  4. Click OK.
Parent topic: Breakpoints


Viewing a Breakpoint with the Breakpoints Dialog Box

  1. Click Debug > Breakpoints to open the Breakpoints dialog box.
  2. On the Location tab of the dialog box, click the breakpoint location you want to view.
  3. Click View Source (the first of the five buttons in the top, right portion of the tab).

    This command positions the cursor at the indicated breakpoint in your source code.

Parent topic: Breakpoints


Monitoring Variables Using the Breakpoints Dialog Box

The Monitor tab of the Breakpoints dialog box lets you monitor value changes in the variables in your program. The Monitor tab lists all the variables that you want to monitor, and allows you to add variables to the list or delete variables from the list.

To monitor a variable while debugging:

  1. Select Breakpoints from the Debug menu to open the Breakpoints dialog box, then select the Monitor tab.

  2. To add a new variable to monitor, click New or double-click in the window.
  3. Enter the name of the variable to monitor.
  4. Click OK.

You can use the Delete and Delete All push buttons to remove monitors on variables.

Parent topic: Breakpoints


Debugging Threaded Applications

The Debug menu's Threads option opens the Threads dialog box, which displays a list of the threads in the program being debugged. This list includes the file name and the location of each thread.

By default, the Run all threads check box is checked, which means the debugger runs all threads simultaneously.

  • Use the Step Into command to step into a new thread when it is created.
  • Use Step Over when you want to trace a single thread in your program.

    Note that breakpoints in other threads remain active and can transfer control to the debugger. When a thread other than the current thread returns control to the debugger, that thread becomes the current thread.

To execute only one thread at a time, disable the Run all threads check box and click Go. In this case, to switch between threads, select the thread you want from the Threads dialog box and click Go.

If you enable the Show full path name check box in the Threads dialog box, the list of threads includes the file’s full path. Disable this check box if you want the dialog box to list only the file name.

While the Threads dialog box provides a useful tool for controlling how the debugger navigates between threads, the act of single-stepping through a program, by its nature, interferes with the natural threading behavior of the runtime. As a result, if you are trying to debug a threading issue, you may receive a more accurate picture of your program's behavior by enabling paragraph tracing and running the program with an error file than by stepping through the program line-by-line.

Parent topic: Debug Menu Commands


Quick Watch

If you select a variable in the Code Editor and then use the Debug > Quick Watch command, a Quick Watch window appears, displaying the variable's current value. For more information about the Quick Watch window, see Watch Window.

Parent topic: Debug Menu Commands


Looking for Something?: Search and Replace

  • Introduction
  • Find
  • Find in Files
  • Find in Objects
  • Replace
  • Replace in Files
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

When you are working in AcuBench, a variety of search and replace options are available to allow you to locate a text string within the current document, within the AcuBench graphical designers associated with a project, or within the files in a specified directory structure.

Parent topic: Looking for Something?: Search and Replace


Find

To search for a string in the document currently open in the Code Editor or Event Editor, do one of the following:

  • Open the Edit menu and select Find.
  • Right-click in the editor window and select Find.
  • Use the default Ctrl + F keyboard shortcut.

This opens the Find dialog, in which you can enter a search string and set a variety of options for the search.

The Find What combo box displays the string to be used in the search. If text is selected in the editor when you open the Find dialog, that text will appear selected in the combo box. If you are performing multiple searches, you can expand the combo box to see and select from a list of up to 15 previous search terms. You can also type the search term that you would like to use in this field.

If you want to find only those strings that exactly match the case of the search string that you enter, mark the Match Case check box. If this box is not marked (the default), the search is not case-sensitive.

If you want to search for a regular expression, rather than a text string, mark the Regular Expression check box. A regular expression is a formula for matching strings that have a certain pattern. Regular expressions are discussed in more detail in Find in Files.

If you are not using regular expressions, and you do not want the search function to consider hyphens and underscores, mark the Ignore - and _ check box.

If you want AcuBench to search the entire document, regardless of where the cursor is positioned when you start the search, mark the Wrap Around Search check box. This means that in a down search, when the search reaches the end of the active document, it continues searching from the top. Likewise, in an up search, when the search reaches the beginning of the active document, it continues searching from the end.

To determine the direction for the search, select either the Up radio button, to search from the cursor position to the top of the file, or the Down radio button, to search from the cursor position to the end of the file.

  • Locate a single instance of a search string
  • Mark all instances of a search string
  • List all occurrences of a search string
Parent topic: Looking for Something?: Search and Replace


Locate a single instance of a search string

To find a single instance of the search string, click Find Next to start the search function. The first instance of the string that AcuBench locates is highlighted. To continue to the next instance of the string, click Find Next again.

Parent topic: Find


Mark all instances of a search string

If you expect that multiple instances of a string will be found, and you want

an easy way to refer to each instance, click Mark All to perform the search. AcuBench places a bookmark at each line on which the string is found. Navigate between bookmarks with the Previous Bookmark and Next Bookmark Edit commands, toolbar buttons, or keyboard shortcuts.

Parent topic: Find


List all occurrences of a search string

Alternatively, to see a list of all instances of a search string in the Output window, click Find All to begin your search. A list is generated, showing the file path, line number, and text of each line in the active document that contains the string. Double-click an item in the list to jump to that point in the active document.

Parent topic: Find


Find in Files

To locate all instances of a search string within a specified directory or set of directories, do one of the following:

  • Open the Edit menu and select Find in Files.
  • Click the Find in Files button on the Editor toolbar.

When you choose this command, the Find in Files dialog box appears.

Like the basic Find dialog, the Find in Files dialog box starts with a Find what combo box that displays any currently selected text and provides a list of previous search commands.

In addition, because this search function searches specified directories for files containing a text string, rather than limit itself to the active document, you can limit the search to specific types of files. Use the File types field to enter one or more file extensions. Only files with the specified extension(s) will be examined during the search. The default is to search all file types (“*.*”).

As in the basic Find dialog, you can choose whether or not the search should be case-sensitive (the Match case) option, and whether or not regular expressions are used.

  • Special Operators and Regular Expressions
  • Performing the Search
Parent topic: Looking for Something?: Search and Replace


Special Operators and Regular Expressions

A regular expression is a formula for matching strings that have a certain pattern. It contains both normal alphabetic and numeric characters and metacharacters. Metacharacters are used to create the template pattern used in the search.

When you mark the Regular expressions check box, a button appears on the Find in Files interface, to the right of the Find what field. When you click this button, a pop-up list displays descriptions of various supported metacharacters.

Select a description from the list and the metacharacter is added to the Find what field. If you are familiar with Windows regular expression rules, you can also type in your own patterns.

The metacharacter options available from the pop-up list include:

Any Character . | When the search function looks for a match for the specified string, any character is acceptable in this character position.
Character in Range [] | Any of the characters between the brackets counts as a match for the search function.
Character Not in Range [^] | Any character other than those listed between the brackets is an acceptable match.
Beginning of Line ^ | Find the preceding search string only when it occurs at the beginning of a line.
End of Line $ | Find the preceding search string only when it occurs at the end of a line.
Beginning of Word \< | Find the following search string only when it occurs at the beginning of a word.
End of Word \> | Find the preceding search string only when it occurs at the end of a word.
Tagged Expression \(\) | Treat the expression between \(and \) as a group.
0 or More Matches * | Find zero or more occurrences of the preceding character.
1 or More Matches + | Find one or more occurrences of the preceding character.
Quoted String \ | This is an escape character, used before a symbol that may be used as a metacharacter to indicate that it is being used as a literal. For example, if you were searching for any library routine, you could use “\$” to indicate the dollar sign character, rather than the end of line metacharacter.

Some sample expressions using regular expressions include:

^…$ | Any line having three characters
[0-9] | Any digit
[1-2].$ | Strings where the second-to-last digit is “1” or “2”
[a-z] | Any lowercase alphabetic character
^[A-C] | Strings where the first character is an uppercase “A”, “B”, or “C”
[Ww]indow | The strings “Window” or “window”

One useful, supported metacharacter not included in the regular expressions pop-up list is the pipe symbol (“|”). This is used between two separate search strings or search patterns to indicate that either of the two expressions is acceptable. The expression if|else, for example, will find any line that contains either the word if or the word else.

Parent topic: Find in Files


Performing the Search

Two radio buttons let you choose whether to search through the files associated with the current workspace or files located in a specified directory path. When you select Search in directories, the Search directory options frame is enabled. You can enter a directory path, or click the Browse button to navigate to a directory. Mark the Include subdirectories box to include any subdirectories within the specified path, or uncheck the box to search only the specified directory.

When you have specified the location to be searched, click Find. AcuBench searches the specified files and folders, displaying all matches in the Output window. To see one of the specified instances of the string, double-click the corresponding line in the Output window. AcuBench opens the selected file in the Code Editor and places the cursor at the specified line.

Parent topic: Find in Files


Find in Objects

When you are working with programs that appear in the Structure view, you may find it useful to search for a given string within the various AcuBench designers used by the program. For example, you may want to search for a variable defined in the Screen Designer and referenced in the Event Editor. In this instance, Find in Files would locate the string in the read-only COPY file associated with the designer, rather than the actual designer. If you want to make changes to the string, this presents some difficulties.

To help you make efficient use of the AcuBench graphical designers, the Find in Objects function helps you to locate all instances of a given string stored in the Property window and the graphical design interfaces.

To search the graphical designers for all instances of a string, do one of the following:

  • Open the Edit menu and select Find in Objects.
  • Right-click in any of the graphical designers and select Find in Objects. When you issue this command, the Find in Objects dialog opens

As with the other Find dialogs, the Find What combo box is used to display the selected search string. The most recent search term, if any, is displayed in the entry portion of the combo box. You can expand the box to see a list of up to 15 previous search terms.

When you open the Find in Objects dialog at the project level, rather than from within an individual designer, you will see a Project combo box under the Find What field. If your workspace contains only one project, the name of that project will appear here. If your workspace contains multiple projects, by default, *.* appears here, indicating that all projects in the workspace should be searched. To search a single project in a workspace containing multiple projects, expand the combo box and select the project from the list.

When a single project name appears in the Project combo box, the Target Object list is enabled. This allows you to choose whether to search the objects associated with all PSF and DLT files in the project, or to search only the objects associated with certain PSF and DLT files.

Regardless of the context in which you launch the Find in Objects dialog, you can choose whether or not the search is case-sensitive with the Match Case option. You can also use the Match Whole Word Only option to determine whether the specified string should be considered only as an entire word, or as either an entire word or a portion of a word. If you want the search operation to include screen and report properties, rather than only property values, mark the Find Property Name check box.

Finally, if for any reason you want the results of your search output to the Find in Files tab of the Output window, rather than the default Find in Objects tab, mark the Output to pane (Find in Files) option.

When you have finished filling in the dialog options, click Find to begin your search. Any search items found are listed in the Output window. Double-click an item in the list to open the corresponding graphical designer with the found item selected.

Parent topic: Looking for Something?: Search and Replace


Replace

To replace instances of a string in a document currently open in the Code Editor or Event Editor, do one of the following:

  • Open the Edit menu and select Replace.
  • Click the Replace button on the Editor toolbar.
  • Use the default Ctrl + H keyboard shortcut.

When you issue the Replace command, the Replace dialog box is displayed.

As with the Find dialogs, the Replace dialog includes a Find What combo box, used to display the current search term. Expand the combo box to see a list of up to 15 previous search terms.

Enter the replacement string in the Replace With combo box. A list of up to 15 previous replacement strings can be seen by expanding the combo box.

See Find for more information about the check-box and radio button options at the bottom of the Replace interface.

When you have finished making your selections, click Find Next to locate the next instance of the search string. Select Replace to replace only that instance of the string or Replace All to replace all instances of the string. To skip an instance of the string and continue, select Find Next. To stop searching, click Cancel.

Parent topic: Looking for Something?: Search and Replace


Replace in Files

Just as Find in Files allows you to search for instances of a given string within a specified workspace or directory structure, Replace in Files provides a way to replace all instances of a string within a workspace or directory structure.

To replace a search string in all files in the specified location do one of the following:

  • Open the Edit menu and select Replace in Files.
  • Click the Replace in Files button on the Editor toolbar.

When you select this option, the Replace in Files dialog appears.

Most options on this screen correspond to options on the Find in Files interface, discussed at length in section Find in Files. There is, however, one important thing to note about this interface: there is no option to replace a single item. When you choose Replace All, AcuBench replaces all instances of the text string without prompting for user confirmation.

Parent topic: Looking for Something?: Search and Replace


Toolbar Reference

  • The Standard Toolbar
  • The Project Toolbar
  • The Editor Toolbar
  • The Debug Toolbar
  • The Align Toolbar
  • The Launch Toolbar
Parent topic: AcuBench Version 10.2.0 User's Guide


The Standard Toolbar

The default Standard toolbar is shown below:

The Standard toolbar commands (looking at the toolbar illustration from left to right) are described in the following table:

Command | Description | Menu Equivalent
New | Generates the New dialog box, from which you can open a new project, program, screen file, and source file. It also provides access to the File Designer interface | File > New
Open | Lets you open an existing file. When you choose this command, the Open dialog box appears | File > Open
Save | Saves the active file using its current file name. If the file has not yet been saved, the Save As dialog box appears | File > Save
Save All | Lets you save all open files. You can save the files in new folders or in the same folders using a new name | File > Save All
Open Project | Lets you open an existing project file (.pjf). When you choose this command, the Open Project dialog box appears | File > Open Project
Save Project | Lets you save a project file (.pjf). If the project has not yet been saved, the Save Project dialog box appears | File > Save Project
Print | Lets you send the active file to a printer. When you choose this command, the Print dialog box appears | File > Print
Print Preview | Lets you see how the active file looks before you print it. When you choose this command, the Print Preview screen appears | File > Print Preview
Cut | Removes the selected text or screen element and places it on the clipboard | Edit > Cut
Copy | Places a copy of the selected text or screen element on the clipboard | Edit > Copy
Paste | Places a selection that has been cut or copied to the clipboard into the active file. When you choose this command, selected text is pasted to the cursor location, and a selected control is pasted to the same location that it occupies in the old screen | Edit > Paste
Undo | Reverses recent editing actions. The workbench has multiple undo support, so previous commands can be undone | Edit > Undo
Redo | Reverses recent undo operations if you have performed no other actions since the undo. The workbench has multiple redo support, so previous commands can be redone | Edit > Redo
Workspace | Toggles the view of the workspace in the workbench window | View > Workspace
Output Window | Toggles the view of the Output window in the workbench window | View > Output Window
Property Window. | Toggles the view of the Property window in the workbench window | View > Property Window
Component Toolbox | Toggles the view of the Screen Component Toolbox in the workbench window | View > Screen Component Toolbox
Report Component Toolbox | Toggles the view of the Report Component Toolbox in the workbench window | View > Report Component Toolbox
Toggle Drag-and-Drop | Toggles the view of the Drag and Drop interface | View > Drag-and-Drop
Find in Objects | Lets you locate all instances of a given string stored in the Property window and the graphical design interfaces, such as the Working Storage Editor or the File Designer | Edit > Find in Objects
About | Displays application identification and copyright information | Help > About
Parent topic: Toolbar Reference


The Project Toolbar

The default Project toolbar is shown below:

The Project toolbar commands (looking at the toolbar illustration from left to right) are described in the following table:

Command | Description | Menu Equivalent
Set Active Mode | Allows you to select a mode (set of compiler, runtime, and environment settings) from the drop-down list | Project > Set Active Mode
Add/Remove Files | Allows you to add files to or remove files from a project | Project > Add > Remove Files
Settings | Opens the Project Settings dialog box. If a source file has focus, the dialog box is adjusted to support file-level settings (compile options only) | Project > Settings
Create Alias | Opens the Create Alias dialog box, in which you can define the alias that contains the information needed for a server-based runtime to run a remote program in ACUCOBOL-GT® Thin Client operations | Project > Create Alias
Generate | Generates code for the structural component of the program that has focus (such as screen, data layout, and Working Storage Editor). | Build > Generate
Regenerate Workspace | Regenerates all code-generating elements in a workspace | Build > Regenerate Workspace
Compile | Compiles the selected file | Build > Compile
Build | Initiates a conditional compilation of the workspace. Only those files that have changed since the last build, and their dependents, are recompiled | Build > Build Workspace
Rebuild | Initiates a full recompilation of the workspace. All files are compiled | Build > Rebuild Workspace
Stop Build | Terminates the active Build or Rebuild process | Build > Stop Build
Execute | Executes the selected program | Build > Execute
Debug (Runtime) | Starts the associated COBOL program in the ACUCOBOL-GT runtime debugger | Build > Debug (Runtime)
Allow Parameters | Prompts for parameters before executing the selected program | Build > Allow Parameters
Use Thin Client | Signals the workbench that you want to use ACUCOBOL-GT Thin Client related commands and project setting options | Build > Use Thin Client
Parent topic: Toolbar Reference


The Editor Toolbar

The Editor toolbar is used to invoke search and replace functions, as well as various Code Editor tools and commands. More information about using this toolbar can be found in Basic Editor Functions.

Parent topic: Toolbar Reference


The Debug Toolbar

The default Debug toolbar is shown below:

The Debug toolbar commands (looking at the toolbar illustration from left to right) are described in the following table:

Command | Description | Menu Equivalent
Toggle Breakpoint | At the cursor position, sets or removes a breakpoint | Debug > Breakpoints
Disable Breakpoint | Disables the selected breakpoint | Debug > Breakpoints
Clear All Breakpoints | Removes all breakpoints from the program | Debug > Breakpoints
Go | Starts the selected program in the AcuBench integrated debugger | Debug > Go
Restart | Ends the current debugging session and begins a new session | Debug > Restart
Exit Debugger | Terminates the current debugger session, but leaves the debugger open | Debug > Exit Debugger
Quit Debugging | Terminates the debugger session and exits the debugger | Debug > Quit Debugging
Interrupt | Stops execution of the program, returning control to the debugger | Debug > Interrupt
Step Into | Steps to the next statement | Debug > Step Into
Step Over | Steps over the next statement | Debug > Step Over
Step out Paragraph | Runs the program until the current paragraph returns to the point from which it was performed | Debug > Step Out Paragraph
Step out Program | Runs the program until it exits to its calling program | Debug > Step Out Program
Auto Step | Lets you execute step commands repeatedly until the program's end | Debug > Auto Step
Skip to Line | Moves the current program location to the line containing the cursor | Debug > Skip To Line
Run to Cursor | Sets a temporary breakpoint at the current line (or closest line with a verb) and continues execution of the program | Debug > Run To Cursor
Watch Window | Causes the Watch window to be displayed or hidden | View > Debug Window > Watch
Call Stack Window | Causes the Stack Info window to be displayed or hidden | View > Debug Window > Call Stack
Memory Window | Causes the Memory window to be displayed or hidden | View > Debug Window > Memory
Threads Window | Generates the Threads dialog box | View > Debug Window > Threads
Quick Watch | Opens the Quick Watch window, which displays the value of a selected variable | Debug > Quick Watch
Parent topic: Toolbar Reference


The Align Toolbar

The Align toolbar is discussed in detail in Working with Screens.

Parent topic: Toolbar Reference


The Launch Toolbar

The Launch toolbar is a configurable toolbar for holding program icons linked to frequently used applications (such as a browser, spreadsheet, or word processing application). When you first install AcuBench, the Launch toolbar is empty. For step-by-step instructions on how to add icons to the Launch toolbar, see The Customize Dialog.

Parent topic: Toolbar Reference


Keyboard Reference Shortcut

  • Introduction
  • Main: Default Keyboard Shortcuts
  • Code Editor: Default Keyboard Shortcuts
  • Screen Designer: Default Keyboard Shortcuts
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

AcuBench allows you to define keyboard key-combination shortcuts for most workbench commands. A list of all AcuBench keyboard shortcuts, organized by category, is contained in a drop-down list located in the Tools > Options > Environment > Keyboard dialog box. The Main, Code Editor, and Screen Designer categories indicate the state in which a particular command functions. The Main category, which lists the menu bar, toolbar, and window/right-click commands, is a superset of the Code Editor and Screen Designer categories. The Code Editor and Screen Designer categories each list shortcuts associated with their particular state. For example, you access the list of special keystrokes that perform commands particular to the Code Editor state by selecting the Code Editor category.

Using the three different categories, you can assign three different keyboard shortcuts to a common command (one for each category). When you assign different shortcuts to the same command name, AcuBench applies these shortcuts in context. Let's say you assign Ctrl+P to the Main category's FilePrint command and assign different shortcuts for FilePrint in the Code Editor and Screen Designer categories, Ctrl+F1 and Ctrl+F2, respectively. If you begin working in the Screen Designer, Ctrl+F2 is the shortcut key for FilePrint. If you change states and begin working in the Code Editor, the shortcut key associated with FilePrint changes to Ctrl+F1.

Following is a brief description of the Main, Code Editor, and Screen Designer shortcuts and their default values. You can assign key combinations for commands without shortcuts or replace default shortcut key designations with your own definitions, using the procedures described in the topic Keyboard Options.

Three common keyboard shortcuts are defined by the Windows operating system and cannot be changed. These are:

Close Document Window | Ctrl+F4
Next Document Window | Ctrl+F6
Previous Document Window | Ctrl+Shift+F6
Parent topic: Keyboard Reference Shortcut


Main: Default Keyboard Shortcuts

Command | Shortcut Key | Description
AboutAcuBench | undefined | Display version, copyright, license, and Micro Focus contact information
ActiveXControl | undefined | Display the ActiveX Control Components dialog box
ActiveXProperty | undefined | Display the ActiveX control's properties
AddFD | undefined | Add an existing data layout (.dlt) file to the current project
AddIOParagraph | undefined | In the IO Handling tab of the File Designer, add a new user-defined item to the paragraph list
AddItem | undefined | Add a data item to the record definition in the File Designer
AddItemBefore | undefined | Add a data item before the selected item in the File Designer record definition
AddKey | undefined | Add a key for an indexed file in the File Designer
AddProgram | undefined | Add an existing program structure (.psf) file to the current project
AddScreen | undefined | Add an existing screen (.smf, .stf) file to the current program
AddSubItem | undefined | Add a subitem to a group data item in the File Designer record description
AdjacentHorizontal | undefined | Align controls to be adjacent horizontally
AdjacentVertical | undefined | Align controls to be adjacent vertically
AlignToGrid | undefined | Align control(s) to the grid
ApplicationExit | Ctrl+E | Quit the application, and prompt to save the documents
AssociateFDSL | undefined | Associate the named FD/SL files within the project
BookmarkClearAll | undefined | Clear all bookmarks
BookmarkNext | undefined | Move the cursor to the line containing the next bookmark
BookmarkPrev | undefined | Move the cursor to the line containing the previous bookmark
BookmarkToggle | undefined | Toggle the display of a bookmark on the current line
Build | F7 | Build the project
BuildCompile | Ctrl+F7 | Compile the source file
BuildDebug | undefined | Execute the selected program using the run-time debugger
BuildExecute | Ctrl+F5 | Execute the selected program
BuildAllowParameters | undefined | Execute the selected program, allowing users to define parameters
BuildProject | undefined | Build the project
BuildStop | Ctrl+Break | Stop the build
CenterHorizontal | undefined | Center the controls horizontally within the screen form
CenterVertical | undefined | Center the controls vertically within the screen form
ChangePrefix | undefined | Change the prefix applied to the variables generated by the screen
CharBackTab | Shift+Tab | Move the cursor back one tab stop
CharLeft | Left | Move the cursor one character to the left
CharLeftExtend | Shift+Left | Select the text one character to the left
CharRight | Right | Move the cursor one character to the right
CharRightExtend | Shift+Right | Select the text one character to the right
CharacterScreenImportUtility | undefined | Prepare for character screen import
CharTab | Tab | Move the cursor forward one tab stop
ClearParagraph | undefined | In the IO Handling tab of the File Designer, delete the paragraph name for the currently selected user-defined paragraph
CodeTemplate | undefined | Open the Code Template list box
CommentBlock | undefined | Apply comment symbols to the selected block of text
ControlHeightDecrease | undefined | Decrease the height of the selected control by one pixel
ControlHeightDecreaseGrid | undefined | Decrease the height of the selected control by one grid cell
ControlHeightIncrease | undefined | Increase the height of the selected control by one pixel
ControlHeightIncreaseGrid | undefined | Increase the height of the selected control by one grid cell
ControlMoveDown | undefined | Move the selected control(s) down one pixel
ControlMoveDownGrid | undefined | Move the selected control(s) down one grid cell
ControlMoveLeft | undefined | Move the selected control(s) left one pixel
ControlMoveLeftGrid | undefined | Move the selected control(s) left one grid cell
ControlMoveRight | undefined | Move the selected control(s) right one pixel
ControlMoveRightGrid | undefined | Move the selected control(s) right one grid cell
ControlMoveUp | undefined | Move the selected control(s) up one pixel
ControlMoveUpGrid | undefined | Move the selected control(s) up one grid cell
ControlWidthDecrease | undefined | Decrease the width of the selected control(s) by one pixel
ControlWidthDecreaseGrid | undefined | Decrease the width of the selected control(s) by one grid cell
ControlWidthIncrease | undefined | Increase the width of the selected control(s) by one pixel
ControlWidthIncreaseGrid | undefined | Increase the width of the selected control(s) by one grid cell
Copy | Ctrl+C | Copy the selection to the clipboard
CustomColor | undefined | Customize the basic set of colors
Cut | Ctrl+X | Cut the selection and move it to the clipboard
DebugBreakExecution | undefined | Terminate the debugging session and the run-time
DebugBreakpointClearAll | undefined | Remove all breakpoints
DebugBreakpointDisable | undefined | Disable the breakpoint on the cursor line
DebugBreakpointManagement | undefined | Generate the Breakpoints dialog box
DebugBreakpointToggle | F9 | Toggle the breakpoint on the cursor line
DebugGo | F8 | Start the debugger or, if the debugger is already started, execute the program in Debug Mode
DebugHexadecimalDisplay | undefined | Toggle hexadecimal display of data item values in the debugger
DebugInterrupt | undefined | Interrupt the execution of the application, and return control to the debugger
DebugMonitorClear | undefined | Clear the selected variable from the debug Watch window
DebugMonitorClearAll | undefined | Clear all variables from the debug Watch window
DebugMonitorSet | undefined | Set a monitor on a variable in the debug Watch window
DebugQuickWatch | undefined | Open the Quick Watch window
DebugRecordScript | undefined | Record a script of keyboard input and menu selections in a debugging session
DebugRestart | undefined | Restart the debugging session at the beginning
DebugRunScript | undefined | Run a recorded script of keyboard input and menu selections in a debugging session
DebugRunToCursor | undefined | Debug the program from a temporary breakpoint at the cursor line
DebugSkipToLine | undefined | Debug the program from the current cursor location
DebugStepInto | F11 | Debug the next statement
DebugStepOutParagraph | undefined | Debug the program until the current paragraph returns to the point from which it was performed
DebugStepOutProgram | undefined | Debugging the program until it exits to its calling program
DebugStepOver | F10 | Debug the program after stepping over the next statement
DebugStopDebugging |  | Stop the debugger, and continue execution of the program
DebugStopRecordScript | undefined | Stop the recording of a script of keyboard input and menu selections in a debugging session
DebugThreads | undefined | Debug program threads
DebugTraceFiles | undefined | Enable the Trace File function
DebugTraceFlush | undefined | Enable the Trace Flush function
DebugTraceGeneral | undefined | Enable the Trace General function
DebugTraceLevels | undefined | Generate the Trace Level dialog box
DebugTraceParagraphs | undefined | Enable the Trace Paragraphs function
DebugTraceScreens | undefined | Enable the Trace Screens function
DebugTraceShowInfo | undefined | Display debugger trace information in the Output window
Delete | Delete | Delete the selection
DeleteAllKey | undefined | Delete all the keys in the File Designerkey list
DeleteBack | Backspace | Delete the selected text or, if no selection, the character to the left of the cursor
DeleteFromDisk | undefined | Remove the selected file from the project and place it in the Windows Recycle Bin
DeleteLine | undefined | Delete the line on which the cursor is positioned
DockingComponentBar | undefined | Dock the Screen Component Toolbox
DockingProjectManager | undefined | Dock the Workspace window
DocumentEnd | Ctrl+End | Move the cursor to the end of the document
DocumentEndExtend | Ctrl+Shift+End | Select the text from the current cursor position to the end of the document.
DocumentStart | Ctrl+Home | Move the cursor to the beginning of the file
DocumentStartExtend | Ctrl+Shift+Home | Select the text from the current cursor position to the start of the document
DragAndDrop | undefined | Toggle the Drag-and-Drop interface in the Screen and Report Designers
ExternalParagraph | undefined | If a program icon is selected in the Structure view, open the External Paragraph list
ExternalVariable | undefined | If a program icon is selected in the Structure view, open the External Variable list
FileClose | Ctrl+Q | Close the file, and remove it from the development area
FileCloseWorkspace | undefined | Close the workspace, and remove it from the Workspace window
FileOpen | Ctrl+O | Open an existing source file in the development area
FileOpenWorkspace | undefined | Open an existing workspace in the Workspace window
FilePageSetup | Ctrl+M | Generate the Page Setup dialog box
FilePrint | Ctrl+P | Print the active file
FilePrintPreview | undefined | Display full pages in print preview
FilePrintSetup | Ctrl+K | Generate the Print Setup dialog box
FileSave | Ctrl+S | Save the active file
FileSaveAll | undefined | Save all open files to disk
FileSaveAs | undefined | Generate the Save As dialog box
FileSaveWorkspace | undefined | Save the current workspace
Find | undefined | Find the specified text in the active file
FindInFiles | undefined | Find the specified text in the workspace or other designated directory
FindInObjects | undefined | Find the specified text in the Property window and graphical designers
FindInObjectsPopup | undefined | Open the Find in Objects interface
FindNext | undefined | Find the next occurrence of the specified text
FindPrev | undefined | Find the previous occurrence of the specified text
FindReplace | undefined | Find the specified text and replace it with another designated string
FindScope | undefined | Find the effective range of a selected variable
Generate | undefined | Generate code for the program element in the active window
GenerateSTFDocument | undefined | Generate an STF (Standard Text Format) description of the screen
GenerateWTFDocument | undefined | Generate a WTF (report template file) for the selected report form
GotoLine | undefined | Move the cursor to the specified line of code
Help | F1 | Provide context-sensitive help. If the context is not recognized, display the online help directory
HelpAcuBench | undefined | Display the AcuBench documentation
HelpGTManual | undefined | Display the four-book ACUCOBOL-GT documentation set
HelpRuntimeManual | undefined | Display the HTML version of the Runtime Manual.
HideComponentBar | undefined | Hide the Screen and/or Report Component Toolbox
HideProjectManager | undefined | Hide the Workspace window
Home | Home | Move the cursor to the start of the current line
HomeExtend | Shift+Home | Select the text from the current cursor position in a line to the start of that line
ImportCopyFile | undefined | Import a COPY file into the specified File Designer file descriptor
IndentToNext | undefined | Indent the selected line to match the indentation of the next line
IndentToPrevious | undefined | Indent the selected line to match the indentation of the previous line
InsertBefore | undefined | Insert an item before the selected item in the Menu or Tree View Designer
InsertFileContent | undefined | Insert an existing file at the cursor position
InsertMode | Insert | Toggle insert mode in the Code Editor
InsertSeparatorBefore | undefined | Insert a separator before the currently selected menu item in the Menu Designer
InsertSubitem | undefined | Insert a child item below the selected item in the Menu or Tree View Designer
InsertTabCtrlPage | undefined | Insert a new page in the tab control
LayoutAlignBottom | undefined | Align the bottom edges of the selected controls relative to the dominant control
LayoutAlignLeft | undefined | Align the left edges of the selected controls relative to the dominant control
LayoutAlignRight | undefined | Align the right edges of the selected controls relative to the dominant control
LayoutAlignTop | undefined | Align the top edges of the selected controls relative to the dominant control
LayoutOrderSendToFront | undefined | If multiple controls overlap, bring the selected control to the foreground
LayoutOrderSendToBack | undefined | If multiple controls overlap, send the selected control to the back.
LayoutSizeToContent | undefined | Resize the selected control(s) to fit the title text
LayoutSpaceEvenlyAcross | undefined | Evenly space the selected controls horizontally
LayoutSpaceEvenlyDown | undefined | Evenly space the selected controls vertically
LayoutTabOrder | undefined | Set the order in which your controls appear in the Screen Section
LineDown | Down | Move the cursor down one line
LineDownExtend | Shift+Down | Select the text from the current cursor position down one line
LineEnd | End | Move the cursor to the end of the current line
LineEndExtend | Shift+End | Select the text from the current cursor position to the end of the line
LineUp | Up | Move the cursor up one line
LineUpExtend | Shift+Up | Select the text from the current cursor position up one line
LinkCopyFile | undefined | Link to a specified file descriptor from the File Designer
ListConstants | undefined | Browse all level -78 constant names in the active file
ListParagraphs | undefined | Browse all paragraph names in the active file
ListVariables | undefined | Browse all variable names in the active file
ListCopyFiles | undefined | Browse all COPY file names in the active file
ListView | undefined | Display Screen Component Toolbox controls in a list
LockControls | undefined | Lock/unlock the position of a control on a screen
MakeSameHeight | undefined | Resize the selected controls to the same height
MakeSameSize | undefined | Resize the selected controls to the same size
MakeSameWidth | undefined | Resize the selected controls to the same width
MakeXFDFile | undefined | Create an XFD for the selected Data Layout
ModifyKey | undefined | Change a key in the specified file descriptor in the File Designer
NativeCode | undefined | Open the Translate Portable Object Code to Native Code dialog for the selected object file
New | Ctrl+N | Create a new project, program, screen, source file, or file descriptor
NewDataSet | undefined | Create a new data set
NewFD | undefined | Create a new data layout (.dlt) file
NewLine | undefined | Insert a new line above the current cursor line
NewProgram | undefined | Create a new AcuBench program
NewScreen | undefined | Create a new screen
NextControl | undefined | Select the next control in the tab order on the screen
NextTabCtrlPage | undefined | Select the next page in the tab control
NextTabPosition | undefined | Move the cursor to the next ANSI format area
OpenCopyFile | undefined | Open the designated COPY file
OpenFDEventEditor | undefined | Open the Event Editor for the data layout file selected in the Data view
OpenProject | undefined | Add an existing project (saved as a .pjf) to the current workspace.
OutputClear | undefined | Clear the contents of the Output window
OutputCompileOptions | undefined | If a source file is selected in the File view, show the compiler options for that file in the Output window
OutputFindInObjects | undefined |
OutputHistory | undefined | If the Output window is selected, toggle the History option (to append or overwrite existing output information)
OutputPreviousErrorLine | undefined | Position the cursor in source code at the location of the next previous compilation error listed in the Output window
OutputNextErrorLine | undefined | Position the cursor in source code at the location of the next compilation error listed in the Output window
PageDown | undefined | Move the cursor down one page
PageDownExtend | undefined | Select the text from the current cursor position down one page
PageUp | undefined | Move the cursor up one page
PageUpExtend | undefined | Select the text from the current cursor position up one page
Paste | Ctrl+V | Paste the selection from the clipboard to the active file
PreviousControl | undefined | Select the previous control on the screen form
PreviousTabCtrlPage | undefined | Select the previous page in the tab control
PreviousTabPosition | Ctrl+Shift+Tab | Move the cursor to the previous ANSI format area
ProgramCompileOptions | undefined | Open the Compile tab of the Project Settings window for the selected program or project
ProjectAddRemoveFiles | undefined | Add or remove files from a project
ProjectAssociateFDSL | undefined | Associate the added FD/SL files with the project
ProjectCreateAlias | undefined | When the Create Alias option is available, open the Alias dialog box
ProjectEmptyFolder | undefined | Empty the specified project folder
ProjectNewFolder | undefined | Create a new project folder
ProjectOpen | undefined | Open the selected project
ProjectProperty | undefined | Generate the Project Properties dialog box
ProjectSetActiveMode | undefined | Select the appropriate mode for your project
ProjectSetting | undefined | Generate the Project Settings dialog box
Property | undefined | Generate the Properties dialog box for the selected folder or file
PropertyFont | undefined | Choose the Property window text font
RebuildWorkspace | undefined | Recompile all files in the current workspace
RebuildProject | undefined | Rebuild the project
Redo | Ctrl+Y | Reverse the most recent Undo operation
ReferencedDataFiles | undefined | In the Data Set Designer, open the Data Set Member Files dialog box
RefreshDataFile | undefined | In the Data view, reload the selected data layout file
RefreshAllDataFiles | undefined | In the Data view, reload all data layout files in the selected project
RegenerateWorkspace | undefined | Regenerate all programs that have a program structure file, as well as all data layout files, within the workspace
ReloadCopyFile | undefined | In the Working Storage or Linkage Editor, reload the selected linked COPY file
RemoveCopyFile | undefined | In the Working Storage or Linkage Editor, remove the selected linked COPY file
Reparse | undefined | Reparse the current source file
ReparseAll | undefined | Reparse all the workspace's source files
ReplaceInFiles | undefined | Perform a search and replace operation in the specified directories
ResetXFDName | undefined |
RptSectionController | undefined | Open the Section Controller interface in the Report Writer
SaveProject | undefined | Save the selected project in a .pjf file
ScreenImportUtility | undefined | Import the Screen Section as a new program
ScrollDown | undefined | Scroll the Code Editor window down one line
ScrollUp | undefined | Scroll the Code Editor window up one line
SelectAll | Ctrl+A | Select all the elements in the active file
SelectionCapitalize | undefined | Capitalize the selected text
SelectionLowercase | undefined | Lowercase the selected text
SelectionUppercase | undefined | Uppercase the selected text
SequenceNumber | undefined | Generate the Sequence Number dialog box
SetDefaultXFD | undefined | On the XFD tab of the File Designer, return the XFD to its default settings
SyntaxCheck | undefined | Perform a syntax check in the Working-Storage, Linkage, or File Designer
ToggleAlignToolbar | undefined | Toggle the display of the Align toolbar
ToggleBookmarkPane | undefined | Toggle the display of the Bookmark pane
ToggleScreenComponentBar | undefined | Toggle the display of the Screen Component Toolbox
ToggleDebugToolbar | undefined | Toggle the display of the Debug toolbar
ToggleEditorToolbar | undefined | Toggle the display of the Editor toolbar
ToggleFullPathName | undefined | Toggle the display of the full pathname in the window title bar
ToggleGrid | undefined | Toggle the display of the grid in a Screen Designer window
ToggleGuide | undefined | Toggle the display of the Screen Designer's control positioning guides
ToggleLaunchToolbar | undefined | Toggle the display of the Launch toolbar
ToggleLineNumberPane | undefined | Toggle the display of the Line Number pane
ToggleMemoryWindow | undefined | Toggle the display of the Memory debugger window
ToggleOutputWindow | undefined | Toggle the display of the Output window
ToggleProjectManager | undefined | Toggle the display of the Workspace window
ToggleProjectToolbar | undefined | Toggle the display of the Project toolbar
TogglePropertyWindow | undefined | Toggle the display of the Property window
ToggleReportComponentBar | undefined | Toggle Report Component Toolbox display
ToggleRulerBar | undefined | Toggle the display of the ruler bar
ToggleStackInfoWindow | undefined | Toggle the display of the Call Stack debugger window
ToggleStandardToolbar | undefined | Toggle the display of the Standard toolbar
ToggleStatusBar | Ctrl+Shift+S | Toggle the display of the status bar
ToggleThreadWindow | undefined | Display the debugger Thread dialog box
ToggleWatchWindow | undefined | Toggle the display of the debugger Watch window
ToolsCustomize | undefined | Customize the toolbar settings
ToolsOptions | undefined | Generate the Tools > Options dialog box
TransposeSourceFormat | undefined | Transpose the document display format between ANSI and terminal formats
UncommentBlock | undefined | Remove comment symbols from the selected text
Undo | Ctrl+Z | Reverse previous operations
UtilityAcu4glFD | undefined | Launch the acu4glfd utility
UtilityAxdefgen | undefined | Launch the ACUCOBOL-GT utility axdefgen
UtilityNetdefgen | undefined | Launch the ACUCOBOL-GT utility netdefgen
UtilityCblUtil | undefined | Launch the ACUCOBOL-GT utility cblutil
UtilityLogUtil | undefined | Launch the ACUCOBOL-GT utility logutil
UtilityVio | undefined | Launch the ACUCOBOL-GT utility vio
UtilityVioProject | undefined | With a project icon selected, launch vio
UtilityVutil | undefined | Launch the ACUCOBOL-GT utility vutil
UtilityXml2FD | undefined | Launch the ACUCOBOL-GT utility xml2fd
VerbBlockMatch | Ctrl+Shift+M | Move to the opposite end of a verb block command statement
ViewPreprocessed | undefined | View the .asq file created when the selected file is compiled with a preprocessor (-P) flag
ViewFDFile | undefined | Display the selected .fd file
ViewLinkageFile | undefined | Display the selected Linkage Section (.lks) file
ViewMenuFile | undefined | Dpslay the selected menu (.mnu) COPY file
ViewParagraphFile | undefined | Display the selected event paragraph (.evt) file
ViewProcedureFile | undefined | Display the selected Procedure Division (.prd) file
ViewScreenFile | undefined | Display the selected screen (.scr) file
ViewSLFile | undefined | Display the selected .sl file
ViewSourceFile | undefined | Display the selected source (.cbl) file
ViewWorkingFile | undefined | Display the selected Working-Storage (.wrk) file
WindowArrangeIcons | undefined | Arrange the caption bars of minimized windows at the bottom of the screen
WindowCascade | undefined | Arrange open windows in a cascading format
WindowCloseAll | undefined | Close all open windows
WindowNextPane | F6 | Activate the next pane in a split window
WindowPreviousPane | Shift+F6 | Activate the previous pane in a split window
WindowSplit | undefined | Split the open window
WindowTileHorz | undefined | Tile the open windows horizontally
WindowTileVert | undefined | Tile the open windows vertically
WindowWindowsList | undefined | Generate the Windows list box showing all open windows
WordLeft | Ctrl+Left | Move the cursor back one word
WordLeftExtend | Ctrl+Shift+Left | Select the text from the current cursor position back one word
WordBackDelete | undefined | Delete the word to the left of the current cursor position
WordDelete | undefined | Delete the word to the right of the current cursor position
WordRight | Ctrl+Right | Move the cursor forward one word
WordRightExtend | Ctrl+Shift+Right | Select the text from the current cursor position forward one word
XML2FD | undefined | In the Data view, with a project icon selected, launches the xml2fd utility
Parent topic: Keyboard Reference Shortcut


Code Editor: Default Keyboard Shortcuts

Remember that some commands can be assigned keystrokes at both the Main level and the Code Editor level. This means that some common commands, Remember that some commands can be assigned keystrokes at both the Main such as Cut and Paste, are shown as undefined in the list that follows, even though a keyboard shortcut has been assigned to them at the Main level.

Command | Shortcut Key | Description
BookmarkClearAll | undefined | Clear all bookmarks.
BookmarkNext | Ctrl+Shift+N | Move the cursor to theline containing the next bookmark.
BookmarkPrev | Ctrl+Shift+P | Move the cursor to theline containing the previous bookmark.
BookmarkToggle | Ctrl+T | Toggle the display of a bookmark on the current line.
CharBackTab | Shift+Tab | Move the cursor back one tab stop.
CharLeft | Left Arrow | Move the cursor one character to the left.
CharLeftExtend | Shift+Left Arrow | Select the text one character to the left.
CharRight | Right Arrow | Move the cursor one character to the right.
CharRightExtend | Shift+Right Arrow | Select the text one character to the right.
CharTab | Tab | Move the cursor forward one tab stop.
CodeTemplate | Ctrl+J | Open the code template list box.
CommentBlock | Ctrl+Shift+C | Apply comment symbols to the selected block of text.
Copy | undefined | Copy the selected text to the clipboard.
Cut | undefined | Cut the selected text and move it to the clipboard.
Delete | undefined | Delete the selected text.
DeleteBack | Backspace | Delete the selected text, or if no selection, the character to the left of the cursor.
DeleteLine | Ctrl+Shift+Z | Delete the line on which the cursor is positioned.
DocumentEnd | Ctrl+End | Move the cursor to the end of the document.
DocumentEndExtend | Ctrl+Shift+End | Select the text from the current cursor position to the end of the document.
DocumentStart | Ctrl+Home | Move the cursor to the beginning of the file.
DocumentStartExtend | Ctrl+Shift+Home | Select the text from the current cursor position to the beginning of the document.
FilePrint | undefined | Print the document.
FilePrintPreview | undefined | Display full pages in print preview.
Find | Ctrl+F | Find the specified text in the active file.
FindNext | F3 | Find the next occurrence of the specified text in the active file.
FindPrev | Shift+F3 | Find the previous occurrence of the specified text in the active file.
FindReplace | Ctrl+H | Find the specified text and replace it with another designated string.
FindScope | Ctrl+Shift+V | Find the effective range of a selected variable.
GotoLine | undefined | Move the cursor to the specified line of code.
Home | Home | Move the cursor to the start of the current line.
HomeExtend | Shift+Home | Select the text from the current cursor position in a line to the start of that line.
IndentToNext | undefined | Indent the selected cursor line to match the indentation of the next line.
IndentToPrevious | undefined | Indent the selected cursor line to match the indentation of the previous line.
InsertFileContent | undefined | Insert an existing document at the cursor position.
InsertMode | Insert | Toggle insert mode in the Code Editor.
LineDown | Down Arrow | Move the cursor down one line.
LineDownExtend | Shift+Down Arrow | Select the text from the current cursor position down one line.
LineEnd | End | Move the cursor to the end of the current line.
LineEndExtend | Shift+End | Select the text from the current cursor position to the end of the line.
LineUp | Up Arrow | Move the cursor up one line.
LineUpExtend | Shift+Up Arrow | Select the text from the current cursor position up one line.
NextTabPosition | Ctrl+Tab | Move the cursor to the next ANSI format area.
NewLine | Ctrl+Shift+I | Insert a new line above the current cursor line.
OpenCopyFile | undefined | Open the designated COPY file.
PageDown | Page Down | Move the cursor down one page.
PageDownExtend | Shift+Page Down | Select the text from the current cursor position down one page.
PageUp | Page Up | Move the cursor up one page.
PageUpExtend | Shift+Page Up | Select the text from the current cursor position up one page.
Paste | undefined | Paste the selected text from the clipboard to the active file.
PreviousTabPosition | Ctrl+Shift+Tab | Move the cursor to the previous ANSI format area.
Redo | undefined | Reverse the most recent undo operation.
ScrollDown | Ctrl+Down | Scroll the Code Editor window down one line.
ScrollUp | Ctrl+Up | Scroll the Code Editor window up one line.
SelectAll | undefined | Select all the text in the active file.
SelectionCapitalize | Ctrl+G | Capitalize the selected text.
SelectionLowercase | Ctrl+U | Lowercase the selected text.
SelectionUppercase | Ctrl+Shift+U | Uppercase the selected text.
SequenceNumber | undefined | Generate the Sequence Number dialog box.
TransposeSourceFormat | undefined | Transpose the document display format between ANSI and terminal formats.
UncommentBlock | undefined | Remove comment symbols from the selected text.
Undo | undefined | Reverse previous operations.
VerbBlockMatch | Ctrl+Shift+M | Move to the opposite end of a verb block command statement.
WordBackDelete | Ctrl+B | Delete the word to the left of the current cursor position.
WordLeft | Ctrl+Left | Move the cursor back one word.
WordLeftExtend | Ctrl+Shift+Left | Select the text from the current cursor position back one word.
WordDelete | Ctrl+D | Delete the work to the right of the current cursor position.
WordRight | Ctrl+Right | Move the cursor forward one word.
WordRightExtend | Ctrl+Shift+Right | Select the text from the current cursor position forward one word.
Parent topic: Keyboard Reference Shortcut


Screen Designer: Default Keyboard Shortcuts

Remember that some commands can be assigned keystrokes at both the Main level and the Screen Designer level. This means that some common commands, such as Cut and Paste, are shown as undefined in the list that follows, even though a keyboard shortcut has been assigned to them at the Main level.
A C D F G I L M N P R S
Command | Shortcut Key | Description
ActiveXProperty | undefined | Display the ActiveX control's properties
AdjacentHorizontal | undefined | Align controls to be adjacent horizontally
AdjacentVertical | undefined | Align controls to be adjacent vertically
AlignToGrid | undefined | Align control(s) to grid
CenterHorizontal | undefined | Center the controls horizontally within the screen form
CenterVertical | undefined | Center the controls vertically within the screen form
ChangePrefix | undefined | Change the prefix applied to variables generated by the screen
Copy | undefined | Copy the selected screen element to the clipboard
ControlHeightDecrease | Shift+Up Arrow | Decrease the height of the selected control by one pixel
ControlHeightDecreaseGrid | Ctrl+Shift+Up Arrow | Decrease the height of the selected control by one grid cell
ControlHeightIncrease | Shift+Down Arrow | Increase the height of the selected control by one pixel
ControlHeightIncreaseGrid | Ctrl+Shift+Down Arrow | Increase the height of the selected control by one grid cell
ControlMoveDown | Down Arrow | Move the selected control(s) down one pixel
ControlMoveDownGrid | Ctrl+Down Arrow | Move the selected control(s) down one grid cell
ControlMoveLeft | Left Arrow | Move the selected control(s) left one pixel
ControlMoveLeftGrid | Ctrl+Left Arrow | Move the selected control(s) left one grid cell
ControlMoveRight | Right Arrow | Move the selected control(s) right one pixel
ControlMoveRightGrid | Ctrl+Right Arrow | Move the selected control(s) right one grid cell
ControlMoveUp | Up Arrow | Move the selected control(s) up one pixel
ControlMoveUpGrid | Ctrl+Up Arrow | Move the selected control(s) up one grid cell
ControlWidthDecrease | Shift+Left Arrow | Decrease the width of the selected control(s) by one pixel
ControlWidthDecreaseGrid | Ctrl+Shift+Left Arrow | Decrease the width of the selected control(s) by one grid cell
ControlWidthIncrease | Shift+Right Arrow | Increase the width of the selected control(s) by one pixel
ControlWidthIncreaseGrid | Ctrl+Shift+Right Arrow | Increase the width of the selected control(s) by one grid cell
CustomColor | undefined | Customize the basic set of colors
Cut | undefined | Cut the selected screen element and move it to the clipboard
Delete | undefined | Delete the selected screen element
FilePrint | undefined | Print the active screen
FilePrintPreview | undefined | Display full screens in print preview.
GenerateSTFDocument | undefined | Save the screen as an .stf file
InsertBefore | Insert | Insert an item before the selected item in the Menu or Tree View designer
InsertSeparaterBefore | undefined |
InsertSubitem | Ctrl+Insert | Insert a child item below the selected item in the Menu or Tree View Designer
InsertTabCtrlPage | undefined | Insert a new page in the tab control
LayoutAlignBottom | Alt+Down | Align the bottom edges of the selected controls relative to the dominant control
LayoutAlignLeft | Alt+Left | Align the left edges of the selected controls relative to the dominant control
LayoutAlignRight | Alt+Right | Align the right edges of the selected controls relative to the dominant control.
LayoutAlignTop | Alt+Up | Align the top edges of the selected controls relative to the dominant control
LayoutOrderSendToFront | undefined | If multiple controls overlap, bring the selected control to the foreground
LayoutOrderSentToBack | undefined | If multiple controls overlap, send the selected control to the back
LayoutSizeToContent | Shift+F7 | Resize the selected control(s) to fit the title text
LayoutSpaceEvenlyAcross | undefined | Evenly space the selected controls horizontally
LayoutSpaceEvenlyDown | undefined | Evenly the space selected controls vertically
LayoutTabOrder | Ctrl+D | Set the order in which your controls appear in the Screen Section
LockControls | Ctrl+L | Lock/unlock the position of a control on a screen
MakeSameHeight | undefined | Resize the selected controls to the same height
MakeSameSize | undefined | Resize the selected controls to the same size
MakeSameWidth | undefined | Resize the selected controls to the same width
NextControl | Tab | Select the next control in the tab order on the screen
NextTabCtrlPage | undefined | Select the next page in the tab control
Paste | undefined | Paste the selected screen element from the clipboard to the active screen
PreviousControl | Shift+Tab | Select the previous control on the screen form
PreviousTabCtrlPage | undefined | Select the previous page in the tab control
Redo | undefined | Reverse the most recent undo operation
SelectAll | undefined | Select all the elements in the active screen
ToggleGrid | Ctrl+G | Toggle the display of the grid in a Screen Designer window
ToggleGuide | undefined | Toggle the display of the Screen Designer's control positioning guides
Undo | undefined | Reverse previous operations
Parent topic: Keyboard Reference Shortcut


Appendix: Bringing Existing Code Into AcuBench

  • Introduction
  • Importing Data Definitions
  • Creating a PSF for an Existing Program
  • Adding Existing Code to an AcuBench Program
  • Updating a Character-based Screen
  • Importing a Graphical Screen
Parent topic: AcuBench Version 10.2.0 User's Guide


Introduction

If you want to use AcuBench's code generation tools with your existing COBOL source code, there are three basic options available. You can:

  • Create a new AcuBench program and use it to generate screen or report code, then copy the generated code into your existing source file
  • Create a program structure file for your existing source file
  • Create a new AcuBench program and use the graphical designers to copy and paste code from your existing source files into the new program

Each option has its own advantages and considerations.

  • If you choose to use an AcuBench template program to generate code that you then place into your existing source files, you retain your familiar code format and strict control over the contents of your source files. You lose, however, the flexibility of using the drag-and-drop design interfaces to make quick changes to your program
  • If you choose to create a program structure file for your existing source file, you gain access to some of the AcuBench code generation facilities while retaining most of the familiar code structure of your existing file. Because AcuBench has a limited ability to parse and understand your existing code, however, not all of the workbench's automation tools are available for your use
  • If you choose to bring your existing source code into a new AcuBench program, you gain access to all of the automated code generation tools that the workbench provides. This process may, however, be time consuming and requires adaptation to AcuBench's formats and processes

Whichever option you choose, keep in mind that to make best use of the tools that AcuBench provides, converting the source code is only one part of the process. By creating data layout files (.dlt) to define your data and data handling code for AcuBench, you greatly increase the utility and functionality of the AcuBench graphical designers.

Parent topic: Appendix: Bringing Existing Code Into AcuBench


Importing Data Definitions

As discussed in Working with Data at the Project Level, there are several advantages to bringing your data file definitions (file descriptors and SELECT statements) into AcuBench. It can help to centralize maintenance of data definition and file-handling code and enable various automation tools, like the Drag and Drop interface used in screen and report design and the Data Set Designer, used to define data for use with individual programs.

The easiest way to bring existing data definitions into AcuBench is to first create COPY files corresponding to each file descriptor and SELECT statement. For each FD/SELECT pair:

  • The two files should have the same base name.
  • The FD file should have a .fd extension.
  • The SELECT file should have a .sl extension.

When you have finished creating COPY files, open your AcuBench project and do the following:

  1. In the File view, right-click the FD folder and select Add/Remove Files.
  2. Use the navigation tree view in the top, right corner of the Add/Remove Files dialog to navigate to the directory containing your COPY files.
  3. Select the files from the file list, then click the Add button. To add all of the files in the directory, navigate to the directory and click Add All.
  4. When you have finished adding COPY files (which may reside in multiple directories), click OK.
  5. Switch to the Data view, right-click the project node, and select Associate FD/SL Files.
  6. In the window that opens, match the FD/SL pair and click Associate.
  7. Continue this process until all FD/SL pairs have been associated and added to the list in the middle of the dialog, then click OK.

    A new data layout file (DLT) appears in the Data view for each FD/SL pair.

Once you have created data layout files from your existing file descriptors and SELECT statements, you can use the AcuBench File Designer to maintain your data descriptions and file handling code. For more information about the File Designer and its capabilities, see Working with Data at the Project Level.

Parent topic: Appendix: Bringing Existing Code Into AcuBench


Creating a PSF for an Existing Program

When you create a program structure file for an existing source file, AcuBench also adds code generation tags to your .cbl source file. When you generate your program, these tags are used to tell AcuBench where to generate various types of code (such as Working-Storage or Screen Section). You can determine which tags are included in your code through the Tools > Options > Code Generator > Program Tag interface. The use of code generation tags is discussed in Program Tag Options.

  • Prepare to Create the PSF
  • Create the PSF
  • Key-Status
  • Import Program Elements into the PSF
Parent topic: Appendix: Bringing Existing Code Into AcuBench


Prepare to Create the PSF

Before you perform the steps described in this chapter, make sure that AcuBench's code generation is set to generate code only between AcuBench program tags.

CAUTION:
If you neglect this step, the first time you generate your program, all of the code outside the AcuBench tags (meaning all the code that you have written inside your source file) will be overwritten.

To ensure that only code between program tags is generated:

  1. Expand the Tools menu and select Options.
  2. In the Tools > Options interface, select the Code Generator tree item.
  3. Make sure that the second check box from the top of the screen is marked, as shown here:

    By default, this box is marked, but it is always a good idea to verify this setting before adding a new program to AcuBench.

Parent topic: Creating a PSF for an Existing Program


Create the PSF

To create a program structure file for an existing source file and add the updated program to a project, use the following steps:

  1. In the File view of the Workspace window, expand the project node to which you plan to add your program.
  2. Right-click the project’s Source folder and select Add/Remove Files.
  3. Locate and select your source file(s) in the Files to be added section of the dialog.
  4. Click the Add button and verify that the name of each selected source file appears in the Files in project list at the bottom of the dialog.
  5. Make sure that the check box in the Create .PSF column of the Files in Project list is marked for each source file for which you want to add a program structure file.
  6. Click OK. AcuBench creates a program structure file and inserts tags into the source file.

    When you switch to the Structure view, a new program node appears in your project. Note that the program icon is different than the icon used for new AcuBench programs that you create. This serves as a reminder that some of the workbench’s automation tools are not available with programs that have been imported into AcuBench in this manner.

Parent topic: Creating a PSF for an Existing Program


Key-Status

By default, AcuBench generates Key-Status code for any program that contains a program structure file. If you already have Key-Status code defined in your program, you will need to take steps to avoid duplicate definitions.

The simplest option is to disable the AcuBench option that generates Key-Status code. To do this:

  1. Right-click the program in the Structure view and select Properties.
  2. On the Key Status tab of the Program Properties window, mark the Do not generate CRT STATUS variable in .wrk check box.

    This check box appears near the bottom of the dialog.

  3. Click OK to save your changes.

Note that there are five key-status definitions that are required if you are using AcuBench-generated graphical screens. These are:

       88 Exit-Pushed            VALUE 27.
       88 Message-Received       VALUE 95.
       88 Event-Occurred         VALUE 96.
       88 Screen-No-Input-Field  VALUE 97.
       88 Screen-Time-Out        VALUE 99.

If your Key-Status definition does not contain these items and you use the AcuBench Screen Designer to add screens to your program, you will receive errors at compile time.

If you prefer to use the AcuBench-generated Key-Status code, you can copy and paste your own Key-Status variable into the generated definition. To do this:

  1. Right-click the program in the Structure view and select Properties.
  2. On the Key Status tab of the Program Properties window, make sure that the Do not generate CRT STATUS variable in .wrk check box is not selected.

    This check box appears near the bottom of the dialog.

  3. Use the Import or Insert button to add conditions and values to the Key-Status definition.

    The Import option allows you to read in items from a data file; the Insert option allows you to manually add items one at a time.

  4. When you are finished, click OK to save your changes.
Parent topic: Creating a PSF for an Existing Program


Import Program Elements into the PSF

Once you have created a program structure file for your source program, you can chose which elements of your program to leave as they are, and which to place into AcuBench's graphical interfaces. A first step might be to copy your Working-Storage code into the graphical Working Storage Designer. After performing this step, AcuBench stores your Working-Storage data in the program structure file, and you can view and modify Working-Storage items through the graphical design interface.

You may also want to add your existing screens to AcuBench so that you can maintain and update them using the graphical Screen Designer. The steps involved in this process can be found in Updating a Character-based Screen and Importing a Graphical Screen.

Parent topic: Creating a PSF for an Existing Program


Adding Existing Code to an AcuBench Program

To preserve the greatest amount of flexibility and ensure the greatest long-term ease of maintenance, the best option is adding your existing source code to a new AcuBench program. This option provides you with access to all of the AcuBench code generation and automation tools, and after the initial investment of time, requires the least amount of manual intervention to maintain and add to your code going forward. If you are using AcuBench as part of a legacy modernization process that involves increased use of graphical user interfaces and/or graphical reports, the ease with which you can add and update graphical features to an AcuBench program will likely render this initial investment well worthwhile.

In preparation for this process, the first thing to understand is how AcuBench generates code, and specifically how AcuBench uses program tags (discussed in section Program Tag Options) to determine where to generate code. These program tags act as cues, telling AcuBench where to place different sections of a COBOL program. They are also used to indicate insertion points, at which the code that you define in the AcuBench graphical designers is placed. To understand how to bring your existing code into a new AcuBench program, you must understand where to place your code, so that it can be integrated into the generated program.

Step 1: Define your data

As with every method of working with AcuBench, the process starts with data. When you bring your FD and SELECT statements into the File Designer, the IO Handling interface provides a central repository for storing the file handling code associated with a specific data file.

Specific methods for bringing your data definitions into AcuBench are discussed in Working with Data at the Project Level.

Step 2: Create the program

Before creating the AcuBench program, think about how code will be generated for the program. Do you want code to be generated into a single source file or split into multiple COPY files (the default)? Which program tags will you need? Study the Code Generator section of the Tools > Options interface, as described in Customize Your Working Environment, and set the code generation rules that best apply to your practices.

Chapter Working with Programs provides an overview of the program creation process, including information about the program properties that you can customize and control.

Step 3: Define your data sets

Data sets are used to specify how the data defined in project-level data layout files are used by an individual program. When you define a data set, you determine what file handling code is generated (OPEN, READ, DELETE, CLOSE), which key (if applicable) is used to start the file, and so on. In addition, data defined in data sets is exposed to the various AcuBench graphical designers, making it easier to create screens and reports, for example.

The process of defining data sets is described in Working with Data at the Program Level.

Step 4: Add your Working-Storage data

By default, once a program contains screens and reports, AcuBench performs an automatic check to verify that the variables used by those screens and reports have been defined within the program. If AcuBench cannot locate those data definitions, it adds them to the graphical Working-Storage Designer. To correct problems with duplicate names, it is a good idea to bring your existing Working-Storage data definitions into the graphical designer before adding screens or other code.

You can use either of the following methods to bring your Working-Storage code into AcuBench:

  • Copy and paste the code in from your existing source.
  • Place the Working-Storage code in a COPY file and use the Link COPY File or Import COPY File commands from within the designer.

The Working-Storage Designer interface is described in Working with Data at the Program Level and Using the Working-Storage and Linkage Editors.

Note that, by default, AcuBench generates Key-Status definitions for all generated programs. If your Working-Storage section contains Key-Status definitions, you can either disable the automatic generation of Key-Status code or add your definitions to the AcuBench interface used to generate this code. These Key-Status options are discussed in section Key-Status.

Step 5: Import or re-create your screens

The last two sections of this chapter discuss the process of importing existing character-based and graphical screens into AcuBench. These import utilities provide a starting point for working with existing screens in the graphical Screen Designer.

As you begin to work in the Screen Designer, keep in mind the following points:

  • Although the Property window contains long lists of screen and control properties, most of these settings shown here are defaults that you will have no need to change.
  • In most cases, when the Property sheet provides a way to associate a fixed value (Value property) with an item, it also provides a way to associate a variable (Value Variable property) with the item.
  • The Event tab of the Property sheet serves two purposes. It helps you associate codes with screen events and exceptions, and provides access to insertion points in the generated source (Before Routine, After Routine, Before Initdata, After Initdata) where you can add your own code.
  • The Event Editor provides additional insertion points for adding program code (Before Program, After Program) and file handling code (Declaratives, Before DeleteFile), accessed by selecting a program or data set from the Control drop-down list, then selecting an insertion point from the Message drop-down list.

The Screen Designer and Event Editor discussed in chapter Working with Screens.

Step 6: Add your code

As discussed in Step 5, the Event Editor is both used for event, exception, and termination procedures, and to access insertion points in the generated code. Each of these insertion points is associated with a program tag, making them relatively easy to identify when stepping through the code in the debugger.

It is difficult to offer general rules for how to determine which pieces of code go where. The better you understand AcuBench’s code generation rules, and the program tags that the code generator uses to identify and place code within the code skeleton, the more straightforward the process will be.

Parent topic: Appendix: Bringing Existing Code Into AcuBench


Updating a Character-based Screen

To help you transform your character-based application into a graphical one, ACUCOBOL-GT includes a screen conversion tool known as the Character-to-GUI Wizard. The tool works by watching a running character application and, at a specified point, constructing an equivalent graphical screen. This screen is automatically imported into the AcuBench Screen Designer, where you can make modifications to it as desired. You can then use AcuBench to produce a Screen section description of the graphical screen and integrate the new Screen section into your original program.

The Character-to-GUI Wizard is designed to work with any character screen that you have created using ACUCOBOL-GT syntax. This allows it to work with most existing character-based programs. Note that the wizard works with programs using either of ACUCOBOL-GT's two main screen handling techniques: the Screen section and in-line ACCEPT/DISPLAY statements.

When the wizard converts a character screen to a graphical one, each field in the original screen is created as either a label or an entry field. These controls are placed in the same positions as the corresponding fields and have the same size. Labels are given the same text as the fields from which they are created. The source data item, if any, is attached to the control in such a way that it becomes the corresponding value property when the control is viewed in the Screen Designer. Most other information, including color, is not copied. Color is not copied because most character color schemes do not look good under a graphical system.

The wizard uses special rules when deciding whether to make a field a label or an entry field. If you find that these conversion rules result in undesirable effects (for instance, screens with an overabundance of entry fields), you can try converting the screen using alternate rules.

  • Benefits and Restrictions
  • Using the Character-to-GUI Wizard
  • Running Under Windows
  • Setting Compiler Options
  • Setting the "--char2gui" Runtime Option
  • Screen Conversion
  • Editing Screen Properties
  • Manipulating the Screen in the Screen Designer
  • Generating New Screen Section Code
  • Integrating Code Back into Your Program
  • Tips and Techniques
Parent topic: Appendix: Bringing Existing Code Into AcuBench


Benefits and Restrictions

The main benefits of using the Character-to-GUI Wizard are the following:

  • The conversion process is faster than manual techniques.
  • The resulting screens are placed in AcuBench, ready to use the powerful facilities of the Screen Designer to modernize the screen further. This also provides a nice starting point for bringing the entire application into AcuBench.
  • Because the graphical interface is derived from the character one, it retains the efficiencies that have been built into the character interface, and the application’s user base will find the interface familiar and comfortable.
  • The resulting program is an ACUCOBOL-GT program. This program can be easier to understand and maintain than those produced via some other conversion techniques that may involve rewriting the screens in another programming language or using an external tool.
  • By focusing the tasks to accomplish, the wizard can make the programmer more productive. Replacing an application’s user interface with a graphical one is a daunting task with many decisions to be made. Using the wizard, the task is more concrete: integrating a screen into a program.
  • If you need to retain the character-based interface, the wizard’s output works well with ACUCOBOL-GT’s dual-interface features. This makes it easy for a single application to contain both a character and a graphical user interface.
  • The wizard creates screens that refer to the original data items used to build the character screen. This makes integration of the graphical screen into the program easier.

The Character-to-GUI Wizard has some important limitations that you should also consider:

  • The wizard is available under Windows only.
  • Because it mimics the character interface, the resulting graphical user interface makes use of only labels and entry fields. The programmer can add more graphical elements right away or over time as needed, but they are not included as part of the initial conversion.
  • The wizard only handles screen labels and entry fields. More advanced elements of a character application are not recognized by the wizard. These include menu bars, pop-up windows, and line drawing characters.
  • The wizard uses some source code analysis, some runtime analysis, and some heuristics to decide what on the character screen should be labels and what should be entry fields. While these are usually correct, in some cases the wizard could make the wrong choice. The wizard contains a method for correcting this when it occurs.
  • Spacing issues arise when you convert from a fixed-pitch font in the character application to a variable-pitch font in the graphical application. In addition, the boxes around the graphical entry fields occupy screen space that is not present in the character application. As a result, screen elements do not always fit correctly after the conversion. The wizard uses a general-purpose placement algorithm that works well for most screens, but does not ensure that screen fields always fit or look right. You may have to occasionally move or resize a screen field after the screen has been imported into the Screen Designer. You can choose to minimize this effect by using a fixed-pitch screen font and/or using unboxed entry fields. The wizard supports both of these options.
  • Screens constructed via techniques other than using ACUCOBOL-GT syntax cannot be converted or convert poorly. This also applies to screens constructed by embedding terminal control codes directly in the displayed data by the application. The wizard is not aware of the effects of the terminal control codes and treats them as data instead. The resulting screens are generally not useful.
  • The programmer is responsible for integrating the output of the wizard (a Screen section item) back into the program. The wizard tries to simplify this task by referring to the original data items and screen names as appropriate. However, in some cases, the data item may not be correct or even legal. For example, if you construct some portion of a screen out of data contained in a table, the resulting Screen section item could contain several identical table references for logically distinct items. (This would happen if the screen were constructed by processing the table in a loop.)
  • Screens that are not treated by the application as a series of fields do not convert well. For example, if you have a word processor application where the body of the screen is managed by single-character ACCEPT/DISPLAY statements, the wizard tries to treat each character as a distinct field. The results are not useful.
  • The wizard does not handle screens whose set of fields change based on other actions. Essentially, when you import you get an image of the screen as it is at that time. If the screen is dynamic, then that image expresses only one form of the screen.
Parent topic: Updating a Character-based Screen


Using the Character-to-GUI Wizard

The following steps summarize the use of the Character-to-GUI Wizard. The remainder of this section describes aspects of the process in more detail.

  1. Get the character application running with ACUCOBOL-GT under Windows.
  2. Compile the application with -Zw.
  3. From AcuBench, run the application with the --char2gui option.
  4. Convert the desired screens by right-clicking within them and selecting Build Graphical Screen.
  5. Edit properties as desired in the resulting Properties window.
  6. Make any desired changes to the new screens in the AcuBench Screen Designer.
  7. Generate a new Screen section definition from the Screen Designer.
  8. Include this Screen section definition in your program and connect it to your program logic.
Parent topic: Updating a Character-based Screen


Running Under Windows

To use the wizard, you must first get your program running using ACUCOBOL-GT on a Windows machine. The wizard uses both the compiler and runtime to do its job, so you must first get your program into a state where it can be run under Windows.

Parent topic: Updating a Character-based Screen


Setting Compiler Options

For best results, the program containing the screen to be imported should first be compiled with the ACUCOBOL-GT Compiler using the -Zw option. This option, which is set through the AcuBench Project Settings dialog box or on the ACUCOBOL-GT command line, causes the compiler to insert information that may be lost during compilation. Such information includes, for example, the names of the variables used to create the screen items. Importing screens without using the -Zw option yields screens that are not as complete as they are when you use the -Zw option.

When compiling, you can also select a mapping option to define how your data names appear in the screen description: in uppercase, lowercase, or mixed case. By default, uppercase data names are displayed. Note that the case transformation occurs only for characters in the ASCII character set (the English alphabet). For characters outside of the ASCII character set, no transformation is performed.

Use the following steps to set the -Zw compiler option:

  1. Use the Project > Settings command to display the Project Settings dialog box. Choose the Compiler tab.
  2. Select Miscellaneous Options in the catalog drop-down box. Check the -Zw option, Prepare for use with the Screen Import Utility.
  3. Select OK to save the setting.
  4. Select Save as Default to save the setting in the default.pof file. These settings are applied to new projects when they are created.

Set mapping options as follows:

  1. Use the Project > Settings command to display the Project Settings dialog box. Select the Compiler tab.
  2. Select Mapping Options in the catalog drop-down box.
  3. Select the option that best fits your needs:
    • -Mu: Names are uppercase
    • -Ml: Names are lowercase
    • -Mm: Names are mixed case: upper for the first letter of each word, lower for the rest
  4. Select OK to save the setting.
  5. Select Save as Default to save the setting in the default.pof file. These settings are applied to new projects when they are created.
Parent topic: Updating a Character-based Screen
Parent topic: Importing a Graphical Screen


Setting the "--char2gui" Runtime Option

After the relevant programs are compiled, you need to execute them. Perform this step as if you were running the programs normally, except add the --char2gui option to the runtime command line to launch the Character-to-GUI Wizard along with your program. In AcuBench, you add the --char2gui option to the runtime through the Project Settings dialog box as follows:

  1. Select the Project > Settings command to display the Project Settings dialog box. Choose the Runtime tab.
  2. Select Common Options in the catalog drop-down box. Check the --char2gui option, Import Character Screen File.
  3. Select OK to save the setting.
  4. Select Save as Default to save the setting in the default.pof file. These settings are applied to new projects when they are created.

Alternatively, to select the --char2gui option, you can right-click the program node in the File tab and select the Character Screen Import command from the pop-up menu. Note that only the Windows 32-bit runtime supports this option.

Parent topic: Updating a Character-based Screen


Screen Conversion

After you have compiled and executed the program, you are ready to convert your text-based screens into graphical ones. See Tips and Techniques for a list of things you may want to consider before beginning.

Note: Don't bother converting message screens, because these screens come from the Windows message handler rather than your application. The Windows runtime automatically displays messages in a Windows message box.

Perform the screen conversion operation as follows:

  1. With the relevant program running, right-click in the screen you want to convert.
  2. To capture the screen for conversion, select the Build Graphical Screen command from the resulting pop-up menu. At this point, a graphical version of the application screen is created based on the wizard’s internal conversion rules. The new graphical screen is displayed along with a Properties dialog box. You can use the Properties dialog to make global changes to the window created by the wizard. This is described in Editing Screen Properties. You can also change the size of the graphical window by dragging its borders.

    Note that the original application screen is still present, but it is disabled until you finish with the wizard.

  3. Navigate to the next screen that you want to convert and repeat the process until you have converted each screen in the program. The results are saved together in a single text file named import.out. If a file named import.out already exists in the current working directory, it is overwritten.
  4. Terminate the program normally. The converted screens are represented in your AcuBench project in the workspace Structure view in a new program. From there, they can be moved, opened, and modified as needed. Multiple screens are opened cascade style in the Screen Designer.
Parent topic: Updating a Character-based Screen


Editing Screen Properties

When the Character-to-GUI Wizard first displays a new graphical screen, it also displays the Properties dialog box so you can make changes if desired.

The Properties dialog box allows you to change the conversion rules that the wizard used when first creating your graphical screens. Changes to individual screen items are made using the Screen Designer in AcuBench after the wizard has finished.

The Properties dialog box contains the following options:

Option | Description
Unboxed fields | Creates entry fields without boxes. The default is to use boxes. Unboxed entry fields are useful if, for example, you need the resulting screen to fit on a 640 x 480 display. Most of the time, however, you would not want to use this option, because the resulting screen does not have a Windows look
Layout | Lets you choose how the rows of the graphical screen are placed. The two Separate Rows options result in a Windows like look, but use more vertical screen space
Adjacent Rows | Makes entry fields on adjacent rows overlap and share a common border (if boxed). This option uses the minimum screen height
Separate Rows | Places a small amount of space between the adjacent rows such that the entry field boxes are clearly separate from each other
Separate Rows / 3D | Gives the same result as the Separate Rows option, except that each entry field has a 3-D border drawn for it
Font | Lets you pick the font that is used for all the controls (individual controls can be changed in the Screen Designer). Note that many fonts designed for word processing are taller than the built-in fonts for a particular point size. These fonts have additional white space built into them on the top and bottom edges and therefore use more vertical screen space than the built-in fonts
Small | Displays your control with the runtime's built-in proportional small font
Medium | Displays your control with the runtime's built-in proportional medium-sized font
Large | Displays your control with the runtime's built-in proportional large font
Fixed | Displays your control with the runtime's built-in fixed-width font
Traditional | Displays your control with the runtime's built-in traditional font, which uses a different underlying character set than Windows normally does. The traditional font mimics IBM's original character set
Custom | Allows you to select any font on the system for your controls. This option is available once you click the Pick button
Pick | Displays the Font dialog box, in which you can select the font, its style (for example, italic), and size for your control
Use Alternate Rules | Causes the wizard to re-evaluate the original character screen using slightly different conversion heuristics. Generally, the alternate rules work well if you are getting too many entry fields using the default rules
Size | Displays the current screen dimensions in pixels. This is useful when you want to ensure that the resulting window fits on a specific resolution screen. For example, you may want to make sure that the resulting screen is not larger than 800 x 600 pixels
OK | Finishes the conversion process. The wizard imports the graphical screen to the AcuBench Screen Designer and returns control to the original character program
Cancel | Cancels the conversion process. The converted screen is destroyed along with the editing window, and control returns to the original character program
Set Default | Records the current Properties dialog box settings in the registry. These settings become the default values for future screen conversions

Any changes made in the Properties dialog box are immediately reflected in the graphical window. You can make three changes in the graphical window itself:

  • You can change the size of the window
  • The wizard uses a variety of heuristics to decide whether a field in the character application should be represented as a label or an entry field. Sometimes, these do not produce the desired result. You can change the type of the control
  • You can delete a control from the screen produced by the wizard. You would normally remove controls that don't make any sense. For example, you might want to delete a menu bar that has been turned into a set of controls. Later you can reconstruct the menu bar in the Screen Designer

When you are finished editing screen properties, click OK and terminate your program normally; control returns to AcuBench. Use the AcuBench Screen Designer to further manipulate your screens as required.

Parent topic: Updating a Character-based Screen


Manipulating the Screen in the Screen Designer

After converting your screens with the Character-to-GUI Wizard, you can use the AcuBench Screen Designer and all of its features to modify the screens to your liking. You can add graphical controls, define control properties, modify grid behavior, and perform any other function that you might if you were designing the screens from scratch in AcuBench. You can make changes all at once, or over time, as needed. For more information about modifying your screens, see Working with Screens.

You may want to move your newly imported screens into their host programs in the workspace Structure view.

Be sure to review the characteristics of each screen that you converted. As you review, you can make minor modifications to the look and feel of the screen and resize the screen as necessary. (Be aware that in Windows, the size of an initial screen is different than it might be in a character-based application.) Use the alignment functions to position and size controls, lock controls, and verify the tab order. In addition, you may want to change the names of your screens or rename individual controls in the Property window to give them meaningful names. If your original screens were constructed from a Screen section, we suggest that you name the screens with the same name that you used previously.

In many cases, you should replace consecutive singular entry fields with multi-line entry fields. You should also check the window type of your screens. Remember that there can be only one standard window. Subsequent windows are either floating windows or associated with pre-existing window handles. After you've performed these functions, you should verify that font, title, value, and other variables are set correctly.

Finally, if you want your menu to be associated with the screen (and have code generated to show it), be sure to update the Main Menu in your screen's Property window.

Any other changes that you want to make to your screens can be made now if you like. How far you take your screens is up to you. We have provided a list of guidelines you may follow for modifying your newly converted screen, if you like. How far you take your screens is up to you.

The following list offers some guidelines for modifying your newly converted screen:

  1. Examine the window properties of the imported screen. Set the following properties:

    Title: If the window in question is to be displayed on another Window’s handle, the title is just documentation. It is useful when working on a screen to have a quick visual cue of the name of the screen when it is not a primary screen.

    Screen Name: If the original screen came from a Screen section, preserve the screen’s name to facilitate integration of code.

    Window Type: This always defaults to Standard. However, there can be only one standard window in a program. If the window in question is to be displayed on another window’s handle, this is not an issue. If not, select another window type. Size / Lines: We suggest that you conform to some basic window size/lines measurements, and set all windows to those measurements.

  2. Examine the control properties of the imported screen.
    1. Set Control Name.
    2. Verify that Value-Variable and Title-Variable have been correctly preserved by the import process.
    3. Verify that embedded procedures have been correctly preserved by the import process.
    4. Align the controls. Conform alignments to preserve application look and feel. Conform the line number on which status messages appear (typically, line 24 in a character-based application).
  3. Examine the screen’s ACCEPT statement. ACCEPT Screen-Name does not require modification. ACCEPT Variable-Name does, because variable-name is now part of a screen. See Integrating Code Back into Your Programfor more information.
  4. Right-click the screen and select the Change Prefix command. This action is in preparation for moving the screen to the host program, where all screen prefixes must be unique. Select Change Prefix Only. Assign a unique prefix to the screen.
  5. Drag-and-drop the screen in the host program. Delete the program structure file when it contains no more screens.
  6. Examine the screen’s window-handle. If the screen is to be displayed on another screen, then change the window handle to the handle of that screen. If the screen is a floating window (derived from a pop-up window), make sure it shares the same handle as the original pop-up window.
  7. Save.
Parent topic: Updating a Character-based Screen


Generating New Screen Section Code

When you are done modifying your new screens, use the Build > Generate command to generate a COBOL code source file (.cbl) for the screen. As with all AcuBench screens, the code generation process also gives you a Screen section file (.scr), an event paragraph file (.evt), a menu paragraph file (.mnu), a Procedure Division file (.prd), and a Working-Storage file (.wrk).

Note: Before you generate code for your screens, you should be familiar with the code generation model used by AcuBench. For details, see Automatic Code Generation.
Parent topic: Updating a Character-based Screen


Integrating Code Back into Your Program

The final step in the conversion process is integrating your new graphical screens back into your program. This step typically takes the most time and may require some program changes. In some cases, the changes can be extensive. The amount of work you have to do depends on the original state of your program. The process is made somewhat easier because the new screen refers to your program's variables and embedded procedures where applicable.

There is no single correct way to do this step, and no procedure that works for every case. Instead, you have to evaluate your program to see how it can best interact with the updated screen. In the simplest case, the integration process consists of putting the new code in place and commenting out the old code.

When you're integrating the new code, you should analyze your application's:

  • data characteristics
  • keyboard characteristics
  • display characteristics
  • initialization sequence

Data Characteristics

Even though the concept of the Character-to-GUI Wizard is display oriented, you must understand the relationship between the screen and the data. For instance, you should verify that the fields on your new screen are matched with the fields in the FD or working-storage. You should also verify that embedded procedures are associated with your screens and its fields correctly.

In addition, if you've done things like create data sets, then you have to be aware of the fact that you generated code that opens files on initialization. If you don't need those files open, you should deselect OPEN in the definition of the data set.

Keyboard Characteristics

When integrating your new screen code, you must also be aware of your program's keyboard characteristics. If your application instructs users to press a function key and you want to implement this functionality with a push button, you have to know what exception value that key produces and you have to match the same exception values to your screen's new push buttons.

If you printed your cblconfig file or the section of code that contains environment settings before conversion, you should be able to easily locate the KEYSTROKE settings.

Display Characteristics

The most important element of the conversion is your application's display characteristics. In general, the conversion process results in a set of new DISPLAY statements that you must use in place of your old DISPLAY statements. There are several methods you can use to locate your old DISPLAY statements.

Once you know which DISPLAY statements correspond to which screen, you can begin replacing old code with new.

Where screens are displayed initially, you should comment out the old DISPLAY statement and replace it with a PERFORM statement that uses the following syntax:

     PERFORM Acu-[screen-name]-Scrn

For example:

    * display myscreen
     PERFORM Acu-myscreen-Scrn

This paragraph contains code to create a window, display the screen and its main menu on the window, and initialize any complex controls that have been included.

Where elements of screens are displayed (for example, with field-level DISPLAY statements), you should comment out the old DISPLAY statement and replace it with a MODIFY statement. For example:

    * display id-no-field
     MODIFY ID-NO-FIELD value Techhelp-ID

This is made easier because the wizard preserves the name of the Screen section element.

If your original program uses Screen section DISPLAYs and you have duplicated the name of the screen in the Screen Designer, then you may have very little work to do. However, you should replace the initial display window ERASE statement with the workbench-generated DISPLAY STANDARD WINDOW code in the .prd file.

Be sure to comment out non-Screen section DISPLAY statements if your program uses a combination of Screen section and field-level DISPLAY statements. DISPLAY LINE and DISPLAY BOX statements fall into this category. Comment them out.

ACCEPT Handling

Even though the generated code contains ACCEPT statements as well as DISPLAY statements, we recommend that you leave your application's ACCEPTs intact whenever possible. Where your application ACCEPTs screens, no conversion is necessary. (The screen name is already established by the wizard.)

However, where your application ACCEPTs variables, you should comment out the old syntax and replace it with an ACCEPT screen. You should then add an entry field to the screen whose value is the variable you were previously ACCEPTing. For example:

    * accept new-status
     ACCEPT NEW-STATUS-SCREEN

In this example, the screen, NEW-STATUS-SCREEN, contains an entry field whose value is new-status. The old ACCEPT is commented out and the new ACCEPT screen is added.

As a rule, you should examine your ACCEPT statements to determine whether they are ACCEPTing screens or variables, and therefore, whether or not you must perform any conversion.

Other Display Considerations

After you have made an initial pass through your application's ACCEPT and DISPLAY statements, you should consider how and whether your screens may be used differently in a graphical world than they were in a character-based world. For instance, it is a common practice in many character-based applications to use DISPLAY statements to redisplay a main screen whenever a field is updated. In the graphical world, it is impractical and unnecessary to recreate a window and redisplay an entire screen just to update a field. Therefore, you may want to use a MODIFY statement to update the field rather than the PERFORM screen.

In addition, in character-based applications, DISPLAYs are often made over existing DISPLAYs, in effect replacing the old DISPLAY with the new one. In graphical applications, controls must be explicitly destroyed or made invisible before other controls are put in the same space.

The way that a screen closes in a character application is also different from the way a screen or window is closed in a graphical application. For this reason, when you are replacing your DISPLAY statements, you should track where the screen closes or is blanked (a less obvious display event) and convert the close as needed. For example, you may replace a DISPLAY statement with a MODIFY statement in the following case:

    * display grow-scrn-1.
     MODIFY GROW-SCRN-1 TITLE GROW-DESC-LABEL.

However, if you are using a pop-up window, your close event may specify close window handle-1. In this case, when you import the screen, all you need to do is give it a handle of handle-1 and no other conversion is necessary.

Another important difference between character and graphical applications is that character-based applications often dynamically build a screen one line at a time, but it is impractical to display elements line-by-line in the graphical world. Therefore, if your application DISPLAYs a variable in column 10, line 10, and then again in column 10, line 11, and so on, in the graphical world, this may be better accomplished through the use of a list box.

Finally, with a graphical application, you have the opportunity to display message boxes, combo boxes, and other graphical elements that you didn't have access to before. You can use the Screen Designer to add these elements whenever you're ready.

Initialization Sequence

When you generate code for a screen, a statement called perform acu-initial-routine is generated. The acu-initial-routine paragraph performs several functions, some of which you may want and some of which you may not. It performs an ACCEPT System-Information FROM System-Info and an ACCEPT Terminal-Abilities FROM Terminal-Info. In addition, it initializes fonts, bitmaps, and ActiveX resource files; creates menus; and opens files described in data sets. Your character application may already be performing some of these functions, but it isn't likely to perform all of them, and some, like initializing fonts, are critical in the graphical world.

As you are adjusting your original application for the new screen code, you need to make some decisions about what you want your application to do upon initialization. If you want all of the stated initialization routines to take place, you can leave the new perform statement in place, but you may need to remove old redundant code. If you want to perform some of the initialization routines but not others, rather than performing acu-initial-routine, you may prefer to call individual routines, like initialize fonts. In this case, delete the new perform statement and add the desired calls to your own sequence.

Parent topic: Updating a Character-based Screen


Tips and Techniques

To simplify your conversion process, consider performing the following steps before converting your text-based screens:

  • Identify all character-based DISPLAY code in your application.
    Note: Character-based DISPLAY events include DISPLAYstatements and CLOSE WINDOW statements.
  • If your screens are defined in a Screen section, print descriptions of your screens. These can be used to ensure consistency, particularly regarding screen name, control names, and variable names associated with controls.
  • Create a screen flow diagram, that is, a list of the screens you are converting along with instructions on how to bring up those screens and conditions that need to be present in order to bring them up. This helps you determine whether you can capture all of the screen conditions contained in your application, or whether you must run the application again with another set of conditions to capture more screens. It also helps you associate the new screen forms with their host programs when you are ready to integrate the code back into your application.
  • Print descriptions of your menu bars. Menu bars are not captured by the wizard and must be rebuilt manually in the Screen Designer.
  • Print SELECT statements and file descriptors (FDs).
  • Print your cblconfig file or the section of code that contains environment settings. KEYSTROKE settings are important if you want to replace function key (F-key) labels with push buttons.
  • Back up your original application. The copy from which you are converting quickly becomes a work in progress, and you need to have the original system to verify that functionality has remained intact, as well as to serve as a reference point.
  • Create an AcuBench project and copy the necessary source files, data file selects and descriptions, and other COPY files into the created folders. Add source files to the project using the Add/Remove Files function and parsing for COPY files. This creates a program structure file in the workspace Structure view. Note that only programs with screens that will be converted need to have program structure files created for them.
  • If the application that you plan to convert has calls to ACUCOBOL-GT’s menubar.cbl program, replace these calls with calls to menubar2.cbl before capturing the screens. The menubar.cbl program creates a character-based menu bar and menubar2.cbl creates a graphical menu bar using the same input.
  • If you think you may have trouble creating real conditions for a screen to appear, run your program with the debug option -d. In debug mode, you can set breakpoints where the program evaluates the state of certain fields and you can set them using the A (accept) function. In this manner, you can force the display of the screen you want to capture.

In addition, be careful not to distribute the wizard to your end users when you ship the run-time. Specifically, do not give them the file achr2gui.dll. This file is normally located in the same directory as the run-time (which defaults to the bin subdirectory where you installed ACUCOBOL-GT). This file is not needed except when running the wizard.

Parent topic: Updating a Character-based Screen


Importing a Graphical Screen

This section describes the AcuBench graphical Screen Import Utility, which translates graphical ACUCOBOL-GT screens into those that can be read in the Screen Designer. The Screen Import Utility creates a text file that defines a graphical screen created by an ACUCOBOL-GT program. This utility is used to import graphical screens into AcuBench, and uses the ACUCOBOL-GT runtime to produce a description of the screen. For information about importing character screens, see Updating a Character-based Screen.

The following steps summarize the use of the Screen Import Utility. The remainder of this section describes aspects of the import function in more detail.

  1. In the Project Settings dialog box, set the compiler to use the -Zw option.
  2. Also in the Project Settings dialog box, set the runtime to use the -import option.
  3. Compile and execute the screen(s) to be imported using the above options.
  4. Right-click in the screen to be imported and click the Import Screen command.
  5. Close the program that contains the screen(s) you just imported. The imported screen(s) should be represented in your workspace in a new program. At this point, the imported screen can be edited, the screen can be saved as an .stf file, and code can be generated for the imported screen. You can also move the imported screen(s) to the program of your choice in the workspace.
  • Setting Compiler Options
  • Setting the "-import" Run-time Option
  • Graphical Screen Importing
  • Graphical Screen Importing Notes and Restrictions
Parent topic: Appendix: Bringing Existing Code Into AcuBench


Setting the "-import" Run-time Option

After the relevant programs are compiled, you need to execute them. Perform this step as if you were running the programs normally, except that you should add the -import option to the runtime command line. The ability to add the -import option is managed through the Project Settings dialog box.

After the relevant programs are compiled, you need to execute them. Perform this step as if you were running the programs normally, except that you should add the -import option to the runtime command line. The ability to add the -import option is managed through the Project Settings dialog box as follows:

  1. Select the Project > Settings command to display the Project Settings dialog box. Choose the Runtime tab.
  2. Select Common Options in the catalog drop-down box. Check the -import option, Import screen file.
  3. Select OK to save the setting.
  4. Select Save as Default to save the setting in the default.pof file. These settings are applied to new projects when they are created.

Alternatively, to select the -import option, you can right-click the program node in the File tab and select the Screen Import command. Note that only the Windows 32-bit runtime supports the -import option. Also, you must have the file WEXPRT32.DLL installed in the same directory as the runtime. This .DLL comes with the 32-bit Windows runtime, but is used only for the import function.

Parent topic: Importing a Graphical Screen


Graphical Screen Importing

After you have compiled and executed the program, you are ready to import. The compile and execute functions are available as separate commands in the menu bar or the Project toolbar. You can also right-click the source file in the workspace File view and click the Screen Import command.

Perform the screen import operation as follows:

  1. With the relevant program running, right-click in your screen to display the Import Screen pop-up menu. Make sure you click the mouse in the screen itself and not over a control on the screen.
  2. To capture the screen for import, select the Import Screen pop-up menu with the left mouse button.

    You may import multiple screens in a single execution. The results are all saved together in a single text file named import.out.

  3. Close the program that contains the screen(s) you just imported.

    The imported screen should now be represented in the workspace Structure view in a new program, from which it can be opened, modified as needed, saved, and have code generated for it. Multiple imported screens are opened cascade style in the Screen Designer.

  4. If you want to add the new import.out file to another program in the workspace Structure view, right-click the program node in the workspace, and select the Add Screen command from the pop-up menu. Select .out in the Files of type drop-down box. If necessary, use the Browse button to navigate to the desired import.out file. You can also move the imported screen to the program of your choice by clicking the imported screen in the workspace and dragging it to the desired program screen node.
Parent topic: Importing a Graphical Screen


Graphical Screen Importing Notes and Restrictions

  • The grid, tree view, Web browser, status bar, and ActiveX controls, as well as pop-up menus, are only partially imported. For these controls, common properties and styles are imported. However, control-specific properties and styles are ignored and must be added manually.
  • Only controls are imported. Screen elements described by textual fields (for example, DISPLAY "CUST NO") are not imported.
  • The imported screen does not retain any of the structural information in the original source's Screen section. For example, if a Screen section item contains subsidiary group items, that information is lost. The Screen Designer cannot represent these items, so they are not imported. The resulting screen has the same look as the original, but a different internal structure.
  • Importing a screen and then generating code may result in an illegal COBOL program. This can happen when the original source code contains structures that have no representation in the Screen Designer. For example, if the original program contains two fields that have the same name, but are distinct using qualification by intermediate group items, the resulting program may be illegal as the intermediate group items are lost. In another example, if the USING phrase for a control names a qualified data item (for example, MY-DATA OF MY-GROUP), then the resulting program contains an illegal data declaration (for example, 01 MY-DATA OF MY-GROUP PIC X(10)). You can adjust for these anomalies in the Screen Designer after importing the screen.
  • If both FROM and TO are specified, the TO item becomes the control's VALUE and the FROM item is ignored. Otherwise, any specified FROM/TO/USING item becomes the control's VALUE. The control's actual VALUE is suppressed, but the VALUE data item name and picture are imported.
  • CLINE, CCOL, CSIZE, and CLINES are not currently imported.
  • MULTIPLE VALUE items have the word Table in front of their data item name. However, the number of occurrences in the table is not imported.
  • For entry fields, list boxes, and combo boxes, if neither BOXED nor NO-BOX is specified, the import utility sets BOXED to true (although FIELDS-UNBOXED can affect this). While this is an accurate reflection of the control's appearance under Windows, this could change the look under character systems. You might want to leave both BOXED and UNBOXED false and have the Screen Designer assume the BOXED appearance. Also note that FIELDS-UNBOXED implies the NO-BOX style (for entry fields) at the time the control is created. This is reflected in the imported code even though NO-BOX is not specified in the original source.
  • Labels always have a LABEL-OFFSET of 0. The label offset value is reflected in the coordinates for the label.
  • Single-line entry fields report their MAX-LINES as 0, because MAX-LINES is meaningful only for multi-line entry fields.
  • CURSOR and ACTION properties are not imported for entry fields. These fields are not normally used in a Screen section.
  • For list boxes, the following properties are not imported: MASS-UPDATE, ITEM-TO-ADD, RESET-LIST, ITEM-TO-DELETE, INSERTION-INDEX, SEARCH-TEXT, SELECTION-INDEX, QUERY-INDEX, and ITEM-VALUE. All of these are dynamic properties that are not part of the static appearance of the list box. You may want to reconsider ITEM-TO-ADD and possibly others.
  • For combo boxes, the following properties are not imported: MASS-UPDATE, ITEM-TO-ADD, RESET-LIST, ITEM-TO-DELETE, and INSERTION-INDEX.
  • For frames, FILL-PERCENT is not imported.
  • For tab controls, RESET-TABS and TAB-TO-DELETE are not imported.
  • For bars, one dimension has a size of zero. Use the value of the WIDTH property to determine the actual width of the line.
  • For bitmaps, either SIZE or LINES may be zero. In this case, the full size of the actual bitmap should be used for the corresponding dimension.
Parent topic: Importing a Graphical Screen


AcuConnect Version 10.2.0 User's Guide

  • Copyright Statement
  • Introduction
  • The AcuConnect Server
  • Server Configuration
  • Preparing Your Application
  • Preparing the Client(s) in Distributed Processing
  • Preparing the Client(s) in Thin Client
  • Thin Client Special Topics
  • Managing the System
Parent topic: extend Product Guides


Introduction

  • Overview
  • Operating System Support
  • How AcuConnect Works
  • Licensing
  • Security
  • Contacting Technical Support
Parent topic: AcuConnect Version 10.2.0 User's Guide


Overview

Welcome to AcuConnect! Part of the extend® family of solutions, AcuConnect is a client/server technology that can help you distribute your computing processes in the way that best suits your business needs, while optimizing system performance and your existing resources. AcuConnect lets you implement a client/server system in which the client component can be as "thin" or as "thick" as you need.

AcuConnect can be deployed in two ways: in a distributed processing environment or in an environment that uses our thin client technology.

With AcuConnect's distributed processing deployment, users can distribute application logic among client and server machines in a way that best suits their needs. AcuConnect users who take advantage of the our thin client technology can run the user interface (UI) portion of an application on a Windows graphical display host while the rest of the application and data reside on a server.

  • Distributed Processing with AcuConnect
  • Thin Client Technology with AcuConnect
Parent topic: Introduction


Distributed Processing with AcuConnect

With AcuConnect in a distributed processing environment, users or programs on client machines can launch applications on server machines, whether those servers are part of a local area network, wide area network, or global Internet. While some portions of your application continue to run on the client (for example, the user interface and some interactive programs), the resource-intensive portion runs where it is most efficient . . . on the server.

Should users decide to run their programs on server1 one day and server2 the next, they can do so without any changes to the application code. They can even run the application locally if they choose, or "daisy chain" applications together on multiple servers.

With server programs written accordingly, AcuConnect can also provide users access to indexed file data. If the data are on the same remote server as AcuConnect, no special software is required to access the data from a local client. If the data are on a separate data server, AcuConnect works in tandem with our remote file server, AcuServer®, to provide seamless data access. AcuConnect can also work with Acu4GL®, our COBOL-to-RDBMS bridge, to provide seamless access to relational data wherever it resides.

By enabling you to distribute processing between the client and server, AcuConnect helps you leverage your computing resources to the fullest in a true distributed processing environment. For example, with AcuConnect, you can take advantage of the power of your server machines while using inexpensive client machines. AcuConnect

  • Improves application performance by offloading major processing tasks to the server.
  • Decreases network traffic, especially for I/O-intensive applications.
  • Lengthens the life of older computing equipment; users of slower, older technology can use newer server. components for the majority of their processing.
  • Lets you take advantage of existing resources, including the Internet.

You can also use AcuConnect to execute remote COBOL objects from client applications developed in C, C++, Java, .NET, Delphi, or Visual Basic. These applications run on the client and use the C, .NET, or Java API contained in our COBOL Virtual Machine (CVM) to interact with the COBOL object on the server. As instructed by a configuration file on the client, AcuConnect executes the COBOL object remotely and shares data with the client application through the CVM on the client. See Executing Non-COBOL Programs on the Client for information on how to execute remote COBOL objects.

Parent topic: Overview
Parent topic: Operating System Support


Thin Client Technology with AcuConnect

Our thin client technology is an innovation that enables you to display your ACUCOBOL-GT® graphical server-based application on graphical display hosts.

The thin client technology is designed for two main purposes:

  1. To allow ACUCOBOL-GT programs running on a UNIX, Linux, or VMS server to present a full Windows graphical user interface (GUI) on PCs networked with TCP/IP. The application screens may require conversion to graphical, but your application stays in one piece on the server.
  2. To allow you to host your application on a UNIX, Linux, VMS, or Windows server and enjoy the benefits of centralized application maintenance and to adopt the performance characteristics of a "thin" architecture. Many applications perform better when deployed in a thin fashion compared to other networking techniques, such as remote file access ("thick clients") or distributed processing. This is because thin client configurations execute COBOL programs on the server, where data access is local.

The benefits of our thin client technology are plentiful:

  • UNIX users can enjoy the best of two worlds: the stability and security of the UNIX world in multi-user environments and the graphical nature of Microsoft Windows. Previously, UNIX users could use terminal emulation, move their applications to Windows and add a GUI or split their applications into two or more pieces.
  • UNIX applications can use ActiveX controls, Automation Servers (OLE objects), and Windows Help systems on Windows clients. UNIX users can also interact with .NET assemblies in thin client. An ACUCOBOL-GT screen can include a mix of Win32, ActiveX, and .NET graphical controls, if desired.
  • Users can print locally on their Windows machine or on the remote server. They can also choose whether to perform local or remote debugging.
  • You don't have to separate your application into multiple tiers or deploy any of your application logic on client machines.
  • You can usually improve application performance by executing COBOL programs on the server, where data access is local. Server processing eliminates the need to perform file operations over the network, which can be quite slow when many records are involved. This reduces network traffic and often improves response time. (The thin client model does perform screen I/O over the network, but usually at a lesser cost than the file I/O that it replaces.)
  • Administration is simplified when an application resides solely on a server. Installation is easier, as are updates, distribution, and management.
  • Security is enhanced when an application resides centrally.
  • The total cost of ownership for enterprise information systems is reduced. With server-side processing, you remove many client requirements, providing end users easier, more cost-effective access to information.
  • Users and enterprises enjoy increased flexibility with a choice of clients.
  • The AcuConnect Thin Client solution can run on any TCP/IP network, including the Internet.

Our thin client solution can work in conjunction with other technologies from the extend family of solutions. If data will be stored on a separate data server in a three-tier architecture, your thin client solution can use AcuServer to provide transparent access to that data. If your application requires access to relational databases like Oracle, Informix, and Sybase, your thin client solution can use Acu4GL or AcuSQL® technologies on the server to provide automatic data translation. You can migrate your character-based application to ACUCOBOL-GT, display it on Windows hosts, and when you're ready, convert your screens to a full-featured graphical user interface. You can develop your GUI in Windows using our integrated development environment, AcuBench®.

Parent topic: Overview
Parent topic: Operating System Support


Operating System Support

Operating system support for AcuConnect's distributed processing deployment is different from that in the thin client deployment. The help topics in this section outline the specific operating systems supported in each environment.

Note: References to Windows in this manual denote any of the supported Windows platforms, which are listed in the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx. Where it is necessary to make a distinction, the specific version name/number is specified.
  • Distributed Processing with AcuConnect
  • Thin Client Technology with AcuConnect
Parent topic: Introduction


How AcuConnect Works

This help section describes in general terms how AcuConnect works in its various environments. In all cases, AcuConnect runs as an independent resident program (daemon) called acurcl.

  • Distributed Processing
  • Thin Client
Parent topic: Introduction


Distributed Processing

In a distributed processing environment, AcuConnect is a runtime server that handles user requests to start new runtimes on server machines. AcuConnect supports multiple runtime instances so that users may start multiple applications on the server at the same time. It also allows programs on one server to start programs on another server, ad infinitum, as long as each server has a copy of AcuConnect installed.

In distributed processing, both the client and the server have a copy of the ACUCOBOL-GT runtime. The runtime version on the client should match the version of the runtime on the server. If your application interfaces with C-ISAM or other special library routines, you must relink the runtime with the library routines you are using.

Because both the client and the server have an ACUCOBOL-GT runtime, you decide how much of an application runs on the client and how much on the server. The client can be as "thin" or as "thick" as you like. With AcuConnect in distributed processing, the client is actually a "smart" client.

To launch a server program, the client uses standard COBOL CALL syntax. You embed a CALL in the client application, and AcuConnect launches the server application for you automatically. All application (and data) access is completely transparent to the end user.

Differentiation is achieved through configuration files and, more precisely, through definition of either a CODE_PREFIX variable or a "code name alias," which defines the directory containing the object programs. Without modifying or recompiling the original code, the same object can operate on any server, client, or stand-alone machine.

The AcuConnect process can be described as follows:

  1. A network administrator starts AcuConnect on the server. On Windows servers, this can be accomplished through an application service. On UNIX, the administrator uses the acurcl command along with options. For instance, he or she may enter:
    acurcl -start -c acurcl.cfg -e server.err
  2. The user starts the ACUCOBOL-GT client application on the client. In Windows, he or she clicks an icon. In UNIX, her or she enters a runcbl command. For instance:
    runcbl -c client.cfg prog1.acu
  3. The client application, prog1.acu in this example, performs a remote CALL to the server application. For instance:
    CALL "prog2.acu" using customer-info.
  4. AcuConnect automatically starts the remote application, prog2.acu, on the server using the runtime flags and configuration file specified in client.cfg.
  5. The remote application performs the requested task and returns a response to the client. If programmed accordingly, the remote application may perform a CALL to another application on the same or different server before sending back a response.
  6. The client program processes the result, possibly displaying it to the user.

Synchronous or Asynchronous Operation

In the example shown above, the client application waits in a suspended state until the remote application performs its task and returns a result (that is, a "synchronous" CALL is performed). If desired, you can allow the client application to continue running by CALLing the C$ASYNCRUN library routine along with the remote application. In this case, you specify the "handle" of the remote application, as well as the application name itself. For instance:

CALL "C$ASYNCRUN" using handle-of-prog2 "prog2.acu" customer-info.

C$ASYNCRUN tells AcuConnect to allow asynchronous processing. If you use C$ASYNCRUN, you can check the status of the server application using the companion routine, C$ASYNCPOLL. See Synchronous or Asynchronous Execution for more information.

Parent topic: How AcuConnect Works


Thin Client

Our Thin Client computing is a network-based approach to information processing. With the thin client technologies, your software can display on Windows front-end clients, access COBOL programs in practically any server operating environment, permit local or remote printing, and allow remote debugging from Windows.

Different from AcuConnect's distributed processing environment, in which some application components are processed on the client and some on the server (and the application is engineered accordingly), thin client configurations perform all processing on the server and pass simple screen commands between the client and the server. Because server hardware is usually faster, and because data access on the server is local, application performance often improves when processing is performed on the server.

In a thin client configuration, your application comprises two logical layers: a UI layer on the display host (client) and a COBOL layer on the application host (server). The UI layer handles screen, mouse, and keyboard activity, and the COBOL layer performs application processing. Because no application components are required on the client (unless you want to use ActiveX controls), it is considered to be truly "thin."

Rather than forcing you to split your application into client and server components, the ACUCOBOL-GT runtime has been split so that your existing application can be displayed on the client. The runtime portion that is installed on the thin client is known as the ACUCOBOL-GT Thin Client. The thin client can be installed from your product media or downloaded from the Micro Focus Product Support Web site (www.microfocus.com). The full ACUCOBOL-GT runtime is installed on the server.

To function, the split runtime makes use of AcuConnect as a "remote COBOL listener" on the server. The role of the listener is to wait for requests from clients to launch the ACUCOBOL-GT runtime on the server. When a request is received, the AcuConnect listener starts a new runtime on the server, connects that runtime with the client process, and removes itself from the communication stream to wait for requests from other enabled applications. Once initiated, the runtime on the server executes the COBOL application and sends screen commands back to the client.

Together, the ACUCOBOL-GT Thin Client, the ACUCOBOL-GT runtime, and the AcuConnect listener are the enabling technologies that make up our thin client solution.

Parent topic: How AcuConnect Works


Licensing

The licensing scheme for AcuConnect allows AcuConnect to track both types of client connection: distributed processing and thin client. The Activator creates acurcl.alc when generating licenses for thin client connections and acurcl.clc when generating licenses for distributed processing connections.

AcuConnect is shipped with a product code and product key that defines the licensing capabilities specified in your purchase agreement. When you supply your key information during installation, the Activator creates a license file that contains information such as the product's version number, serial number, expiration date, and server count. After installation, AcuConnect must be able to locate the license file to function.

AcuConnect searches for acurcl.alc for thin client connections and acurcl.clc for distributed processing connections in the same directory as the acurcl executable file. If you move the AcuConnect executable file to a new directory, be sure to move a copy of the license file as well. If no license file is found, or if the information in the license file does not permit execution, AcuConnect exits with an error message.

When AcuConnect detects a client request to start a remote application runtime, it checks the connection count to see if another connection is permitted. If another connection is allowed, AcuConnect attempts to start a runtime on the server and connect it with the client process. The runtime, in turn, checks its usage count before it begins execution of the application. When an AcuConnect user disconnects from the remote server by exiting the COBOL program, the AcuConnect and runtime usage counts are decremented and those slots are made available to subsequent users. If the usage limit has been reached, the server runtime is not started and an appropriate message is returned to the end user.

The ACUCOBOL-GT Thin Client, which is installed on client machines, is available on your product media or as a download on Micro Focus's Product Support Web site. You are required to accept a clickwrap license agreement on installation.

The acushare utility is required for all UNIX installations that do not have an unlimited license. The acushare utility monitors and enforces the site runtime usage limits.

Please note that when accessing extend products on remote servers via the Internet or a virtual private network, products or technologies from third-party vendors like Microsoft may be invoked. Carefully review any license agreements with these third-party vendors before proceeding with the remote connection.

Nothing in this document is intended to amend the terms and conditions of the applicable license agreement between you and Micro Focus. Rather, this content is meant to summarize the various aspects of Micro Focus's licensing technology, which is required to operate the extend software. The terms and conditions of your licensing of extend software shall continue to be governed by the applicable license agreement between you and Micro Focus.

Parent topic: Introduction


Security

AcuConnect system security is designed to address two fundamental issues:

  1. Controlling access to data files
  2. Preventing unauthorized use of client components to perform privileged activities (such as modifying privileged files)

The first issue, controlling access to data files, is addressed in two ways: first, via a server access file known as AcuAccess (the same access file used by AcuServer), and second, through the standard UNIX or Windows server file access provisions. Whether an AcuConnect user can access a given file on the server depends on two things: (1) the user ID assigned the requester in the server access file, and (2) either the Windows security set up for your files, or the UNIX ownerships and permissions set on the particular file.

The second issue, preventing unauthorized privileged use, is addressed through strict enforcement of the security measures that you have established through the server's operating system.

Achieving sound system security depends on the configuration and management of the following security elements:

  • The AcuAccess server access file (the database of authorized AcuConnect users)
  • The Windows server security protections set up for the acurcl executable file, server configuration file, server access file, and remote data files and directories. Microsoft recommends that you use the NT file system (NTFS) for better security.
  • The UNIX ownerships assigned to the acurcl executable file, server configuration file, server access file, and remote data files and directories
  • The UNIX access permissions (read, write, and execute) set on the acurcl executable file, server configuration file, server access file, and remote data files and directories

When AcuConnect is running as a Windows service (NT/2000/2003/2008), it belongs to an implicit group called "SYSTEM." Make sure that the "SYSTEM" group is added to your file permissions with "Full Control." (This is not necessary if you are using Windows NT security via the SECURITY_METHOD configuration variable.)

UNIX ownerships and permissions can be set on key AcuConnect files. Note, however, that your site could jeopardize security if you include entries in the server access file that explicitly allow users running as root on the clients to run as root on the server. Do not include such entries.

UNIX ownerships and permissions on the acurcl executable file, server configuration file, and server access file are described in Establishing System Security. These specifications must be strictly maintained. If the ownerships and permissions are more permissive than those specified, AcuConnect will not start, halting system operations.

In addition to the AcuAccess file, AcuConnect offers internal socket layer encryption to further enhance security. Encryption protects information while it is in transit across the network. See Creating a Runtime Configuration File for the Remote Server Component for information about the configuration variables used to enable encryption.

Parent topic: Introduction


Contacting Technical Support

For the latest information on contacting customer care support services go to:

http://www.microfocus.com/about/contact

For worldwide technical support information, please visit:

http://supportline.microfocus.com/xmlloader.asp?type=home

Parent topic: Introduction
Parent topic: Introduction
Parent topic: Introduction


The AcuConnect Server

  • Getting Started with AcuConnect
  • Installing AcuConnect
  • Establishing System Security
  • Creating a Server Alias File in Thin Client
  • Installing Server Programs
  • Starting AcuConnect
  • AcuConnect Connection Logic
Parent topic: AcuConnect Version 10.2.0 User's Guide


Getting Started with AcuConnect

This help section describes some of the steps you need to take before you start using AcuConnect®. AcuConnect’s installation and start-up instructions are included, along with detailed information about establishing system security. The latter topic includes the creation of the server access file and server alias file for thin client. Ownerships and permissions are also discussed. Configuration file entries are covered in Server Configuration.

Parent topic: The AcuConnect Server


Installing AcuConnect

To prepare your server, you must first install AcuConnect. You also need to install an ACUCOBOL-GT® runtime. The procedure for installing AcuConnect varies, depending on whether you are installing on a UNIX server or a Windows server. The following help topics describe the process for these systems.

For thin client architectures, you can also install AcuConnect on a VMS server. See Installing AcuConnect in Thin Client on a VMS Server for information on VMS procedures.

For AIX version 5.1 and later, HP-UX version 11.11 and later, and Solaris version 7.0 and later, ACUCOBOL-GT products are distributed as shared object libraries. If you install AcuConnect as a shared object library, and you choose not to install to the default location (/opt/acucorp/xxx), you need to set an appropriate library search path variable specifying the location of the shared objects. The exact library path variable to set depends on the individual operating system. For example, on an AIX system, you would need to set the LIBPATH environment variable. Note that if you log on as root or superuser, this variable must also be set in root's environment for AcuConnect to start.

  • Installing AcuConnect on a UNIX Server
  • Installing AcuConnect on a Windows Server
  • Installing AcuConnect in Thin Client on a VMS Server
  • Installing the ACUCOBOL-GT Runtime
  • Relinking the Server Runtime in Distributed Processing
Parent topic: The AcuConnect Server


Installing AcuConnect on a UNIX Server

For UNIX platforms, AcuConnect software is shipped on the product CD-ROM. Use the following procedures to install AcuConnect on a UNIX server.

  1. Create a directory on the server to hold the AcuConnect software. You should install AcuConnect directly into the ACUCOBOL-GT home directory.
  2. Install the AcuConnect software, accepting the default options in the script described on the Quick Start card that came with your product. Following the instructions on the card, enter your product code and product key when prompted.
  3. If you want to use the server configuration file in its default location, move acurcl.cfg into the /etc directory. This may require root or superuser privileges. The acurcl.cfg file may remain in the current directory or be copied or moved to some other directory. If acurcl.cfg is not located in the default directory (/etc), the name and location of the configuration file must be specified with the "-c" option each time AcuConnect is started. See acurcl -start for more information.
  4. On UNIX servers, you must create a server access file (default name /etc/AcuAccess) before AcuConnect will start or establish connections with clients. AcuConnect includes a utility program for creating and maintaining the server access file. To create a minimal server access file that allows any user of any client to use AcuConnect, perform the following steps:
    1. Log on to the server as root or become a superuser.
    2. Use the acurcl -access command to launch the server access file manager utility.
    3. When prompted for the path and name of the server access file, accept the default /etc/AcuAccess.
    4. Respond yes to the "Do you want to create it now?" prompt.
    5. From the main menu, click option [1], Add a security record. The manager presents a series of five prompts. Accept the default for each prompt by pressing Return. After you accept the umask field, the program reports that it has added the record.
    6. Exit the utility by clicking option [5] on the main menu.
    Note: For the minimal server access file, the user should have an account on the server by the same name as the account on the client. See The Server Access File for more details about the AcuAccess file and important information about security.

    AcuConnect is now fully installed and ready for configuration on the UNIX server. See Creating a Server Configuration File for the settings that can be configured for the server.

    Note: acushare is installed automatically as part of AcuConnect installation.
Parent topic: Installing AcuConnect


Installing AcuConnect on a Windows Server

  1. Log on to your server using the administrator account or an account that belongs to the administrators group.
  2. Insert the product CD-ROM into your disk drive. If the installation program does not start automatically, perform the following steps:
    1. Click Start > Run.
    2. Enter the following:
      drive:\setup.exe

      where drive is the device designation of your CD-ROM drive.

  3. Follow the instructions on the screen. When prompted:
    1. Enter the product code and product key shown on the card that came with your product.
    2. Specify an installation directory or accept the default location.
    3. Select the component to install. Choose "AcuConnect" from the list of available products.
  4. If you already have the files C:\etc\AcuAccess and C:\etc\acurcl.cfg, the setup utility detects them and asks if you want to overwrite them. Do not overwrite them unless you have a backup copy. The AcuAccess file (as delivered from Micro Focus) contains one access record that gives all users access to AcuConnect. You can modify this file later. The file acurcl.cfg contains the server configuration variables; when the file is first installed, these variables are all commented out. You can also modify this file later.
  5. If you want AcuConnect to start automatically on boot, it must be installed and started as a Windows service. The setup program creates a sample Start Menu folder, and asks if you want to install and start AcuConnect. The default service is named "AcuConnect". Other instances of the service are named after the port on which they run.

    You can also use the command line or graphical user interface to install and start AcuConnect as a service. See Managing the System for information about other acurcl command-line options.

    In Windows, issuing the acurcl command without options causes a graphical control panel to appear. The Services tab in this interface lets you add, start, stop, and remove services.

    Note: Installing a service on a particular port resets all startup options for the service on that port. You can use all valid -start options when installing AcuConnect as a service. These options are stored so that the service will use them when starting.
  6. If you choose to start AcuConnect during the installation process, a Windows Command Prompt (DOS window) appears, showing the status of the Windows services being started or restarted automatically. You may see some error messages that can be ignored if the Windows services are not already installed and running. For example, you might see:
    acurcl –kill
Open/Control Service failed
acurcl –remove
Open/Control Service failed
acurcl –install
AcuConnect service installed.
acurcl –start
STATE: START PENDING

    When AcuConnect is started as a Windows service, all paths used in the configuration file or on the command line are relative to the Windows server system directory (for example, C:\winnt\system32); if you start AcuConnect with the command acurcl -start -le acurcl.log from another directory, the log file is not created in that location, but rather in the \winnt\system32 directory. If desired, you can use full path names, which has the effect of using an explicit file.

  7. After the services are installed and running, there should be no reason to stop them. However, if you choose to stop them, you may do so from the command line (acurcl -kill). You can also stop services by clicking Stop in the Services tab on the graphical control panel.

    After the services are installed, there should be no reason to delete them. However, if you decide to delete them, use the following command from the command line:

    acurcl -remove

    or click Remove on the graphical control panel's Services tab. See Managing the System for information about other acurcl command-line options.

    This command deletes only the services and does not delete the executables. To help in resolving service problems, you can check some messages from these services in the Microsoft Event Viewer. Choose Start > Programs > Administrative Tools > Event Viewer > Log > Application, or the similar command on your version of Microsoft Windows.

    Note: If you move or delete any installed .dll files, AcuConnect will not run.
Parent topic: Installing AcuConnect


Installing AcuConnect in Thin Client on a VMS Server

For VMS platforms (version 7.2 or later), AcuConnect software is shipped in BACKUP format. Select a directory on the server to hold the AcuConnect software, then extract the files from the tape following the installation instructions on the Quick Start card that came with your product. You should be logged in to the SYSTEM account or an account with SYSPRV system privileges.

Note: Runtimes on VMS servers use RMS indexed files rather than Vision.
  1. Define a symbol so users can access AcuConnect. Set up a symbol for each AcuConnect user:
    acurcl == "$disk:[directory]acurcl.exe"
  2. Use the acurcl -access command that launches the access file utility to create a server access file:
    acurcl -access
Enter the name of the Server Access File
Filename [acuaccess.dat]: acuaccess.dat
    See The Server Access File for information about creating and maintaining the server access file. Note that the server access file in VMS is an RMS indexed file.
  3. Set up user account quotas to define each user's capabilities. You can always modify account quotas as needed, but the following settings if you encounter quota errors are suggested:
    Maxjobs:      0    Fillm:      300   Bytlm:       100000
Maxacctjobs:  0    Shrfillm:     0   Pbytlm:           0
Maxdetach:    0    BIOlm:    10000   JTquota:       4096
Prclm:       40    DIOlm:    10000   WSdef:       100000
Prio:         4    ASTlm:      400   WSquo:       100000
Queprio:      0    TQElm:      400   WSextent:    100000
CPU:     (none)    Enqlm:     4000   Pgflquo:     100000

    AcuConnect is now installed and ready for configuration on the VMS server.

    See Creating a Server Configuration File for possible configuration variable settings. See Creating a Server Alias File in Thin Client and Starting AcuConnect in Thin Client on a VMS Server to learn how to create and maintain an alias file that holds all the information needed to start the desired application on the server, and for a description of how to start AcuConnect in this environment.

Parent topic: Installing AcuConnect


Installing the ACUCOBOL-GT Runtime

For the distributed processing deployment, there is nothing on the AcuConnect distribution media to install on the client machine. However, you should ensure that every client system that will use AcuConnect has a licensed copy of the ACUCOBOL-GT runtime that matches the version of AcuConnect installed on the server. For example, if you have installed AcuConnect Version 8.0 on the server, then the client should have the ACUCOBOL-GT runtime Version 8.0 installed.

To check the version number of the client runtime, use the -v option on the runtime command line. The runtime will display information similar to the following:

ACUCOBOL-GT runtime version 8.0
Serial number 1234
Licensed for 2 user(s), 2 processes per user
Copyright (c) 2008, MICRO FOCUS (IP) Ltd.

A -vv (double-v) option also displays the runtime's version number, along with extended information. The -vvv (triple-v) option, valid on UNIX systems, results in the display of additional configuration information about the UNIX port that is primarily useful to our development team. The information displayed varies with individual UNIX systems and is subject to change without notice.

If you have an earlier version of the runtime installed, or no version at all, contact your extend Sales Professional for information on purchasing the latest version of the runtime. For instructions on installing an ACUCOBOL-GT runtime, see your ACUCOBOL-GT User's Guide.

  • Relinking the Client Runtime
  • Removing AcuConnect Client Support from the Runtime
  • Passwords for Clients
  • Setting Up the Host Name
  • Confirming Network Services
Parent topic: Installing AcuConnect
Parent topic: Preparing the Client(s) in Distributed Processing


Relinking the Server Runtime in Distributed Processing

If your applications don't interface with any special library routines, you don't need to relink your runtime. If, on the other hand, your applications interface with C-ISAM or other special library routines, you must relink the included runtime with these special routines. To execute the link, you must have the appropriate C compiler for your host machine:

  • On Windows servers, use Microsoft Visual Studio .NET 2005. For more information, see A Guide to Interoperating with ACUCOBOL-GT.
  • On UNIX servers, use the C compiler supplied by the vendor of your UNIX system. On some machines, this is supplied with UNIX; on others, it is an add-on option.

For C-ISAM, follow the relinking procedure described in the add-on module's documentation.

See Working with C and C++ Programs in A Guide to Interoperating with ACUCOBOL-GT for other special library routines.

Note: Before relinking, modify direct.c (direct method) or sub.c and sub85.c (interface method) to include your C routines.
Parent topic: Installing AcuConnect


Establishing System Security

Proper ownerships and permissions on the acurcl executable file, server configuration files, server access files, and existing data files and directories are essential to establishing a secure and functional system. Whether an AcuConnect user can access a given application depends on whether the user ID assigned the requester in the server access file, and either the Windows or UNIX native server security set up for your files, or the UNIX ownerships and permissions set on the particular file. See The Server Access File for more information.

UNIX ownerships and permissions on the acurcl executable file, server configuration file, and server access file must be strictly maintained. If the ownerships and permissions are more permissive than those specified, AcuConnect does not start.

  • Windows Permissions
  • UNIX Ownerships and Permissions
  • The Server Access File
  • Access Record Composition
  • Using the Access File Manager
Parent topic: The AcuConnect Server


Windows Permissions

After you set up your applications, you may set access permissions by using the Windows server security features. Refer to your Windows documentation for more information about security procedures.

Note: In Windows, the AcuAccess and AcuAccess.vix files should be readable and writable by "Administrator" and "System," with no other access. Make sure that the AcuAccess file and the acurcl.cfg file can be written only by those accounts and groups that you want to have write privileges.

We recommend that you use native system security rather than AcuConnect system security. (On Windows 2008 you must use native system security.)

To use native security, set the SECURITY_METHOD variable in both the runtime configuration file on the client and server configuration file on the server. You still create a server access file containing access records that define your user base, but the server access file is used only to check if the user connecting to the server is allowed to connect, and to check to which local account the connection should be mapped.

We recommend that you install and run AcuConnect on an NTFS drive, because FAT partitions offer no security to files or programs and are not supported by Micro Focus. If you install AcuConnect on an NTFS partition, be aware that the user connecting to AcuConnect needs all of the following:

  • READ (RX) permissions on wrun32.exe and acurcl.clc
  • READ on wrun32.alc (or other license files)
  • The appropriate permissions to access any file

For example, if ACUCONNECT_RUNTIME_FLAGS contains -e logfile, AcuConnect attempts to write "logfile" in the same directory as acurcl.exe. In this case, the user would need CHANGE (RWXD) permissions to access that directory.

If the user connecting to AcuConnect is mapped to DEFAULT_USER, then DEFAULT_USER needs these permissions.

Parent topic: Establishing System Security


UNIX Ownerships and Permissions

Setting ownerships and permissions requires root privileges on UNIX systems or administrator privileges on Windows systems. On UNIX, use the commands chown, chgrp, and chmod to set ownerships and permissions.

UNIX permission modes are specified by a series of three octal numbers. These three numbers assign access privileges to user, group, and other, respectively.

In each user, group, and other field, the following values provide the following permissions:

Value | Permissions
7 | read, write, and execute
6 | read and write
5 | read and execute
4 | read only

The UNIX command ls -l will return the permissions, ownerships, file size, and modification date of a file or directory. For example:

ls -l  /usr2/bsmith/fio_seq

returns:

-rw-r--r--  1 bsmith  general  4870 Jan 18 2005
/usr2/bsmith/fio_seq

For details regarding UNIX file permission masks and the use of chown, chgrp, and chmod, see your UNIX operating system manuals.

Parent topic: Establishing System Security


The Server Access File

The foundation of AcuConnect system security is the server access file, an encrypted Vision file named AcuAccess by default. This file contains a database of access records that determine which machines and which users are allowed to use AcuConnect. AcuConnect searches for this file in the /etc directory on UNIX servers and the operating system drive:\etc directory on Windows servers. You may rename the file if you like.

The server access file is designed to support a wide range of access security, from very permissive to very restrictive. You choose the level of security appropriate for your application.

Access records may include wild cards that allow all clients or all users (except root under UNIX and administrator under Windows) access to AcuConnect. Or you can create individual access records for each user of each client. By having individual access records, you can restrict access to only those users specifically named in the access file.

The individual access records allow you to specify the user ID that AcuConnect will use when executing requests for users matching the given record. In this way, you can assign a user ID that has exactly the privileges needed and no more (typical of group access accounts).

In addition, every access record can include a password entry that the application or user must match before AcuConnect establishes a connection. (However, if the SECURITY_METHOD configuration variable is set to "LOGON", the local account password can be used instead.)

Note: Use native system security rather than AcuConnect system security. On Windows 2008 you must use native system security. To use native security, set the SECURITY_METHOD variable in both the runtime configuration file on the client and server configuration file on the server. You still create a server access file containing access records that define your user base, but the server access file is used only to check if the user connecting to the server is allowed to connect, and to check to which local account the connection should be mapped.

The security system is almost completely transparent to the end user. Only when remote file access requires interactive password authentication is the user made aware of the security system.

On UNIX servers, the access file must be owned by root. The access file cannot be writable by anyone other than root. If the access file does not exist, is not owned by root, or is writable by users other than root, AcuConnect does not start.

On Windows servers, you should protect the access file by allowing only the administrator or someone in the administrators group to have write access to it. If the access file does not exist, is not owned by administrator or the administrators group, or is writable by users other than administrator or the administrators group, AcuConnect does not start.

Parent topic: Establishing System Security


Access Record Composition

The server access file contains one or more access records. Each access record comprises the following fields:

Client Machine Name | The official host name by which the client machine is identified on the TCP/IP network. For distributed processing on Windows, this name is found in the Host field under Control Panel > TCP/IP Properties > DNS Configuration. Under UNIX, use the hostname or uname -n command to determine the name
Client Username | The user's login name on the client system
Local Username | The local user name that AcuConnect will use when fulfilling requests for the client user
Password | Optional password protection. When used, the requester must supply a password that matches this field
umask | A three-digit file creation mask

A typical server access record might look like the following:

Client Machine Name | Client Username | Local Username | Password | umask
starling | bernie | bsmith | . . . . . . . | 002

This record allows user "bernie" to connect from machine "starling". AcuConnect uses the local user name "bsmith" (Bernie's account on the file server) when executing requests for "bernie". In this case, ". . . . . ." represents Bernie's local Windows password, which is required if Windows security is used.

Four fields — Client Machine Name, Client Username, Local Username, and Password — each have a wild card value that is used to indicate a general behavior. These wild cards are:

Field name | Wild card | Meaning
Client Machine Name | * | Match all client machines
Client Username | (empty field) | Match all client users
Local Username | same as client | Use the Client Username
Password | * | Deny access to user

When the string "same as client" is specified in the Local Username field, certain conditions apply. If Client Username is not a valid name on the server, DEFAULT_USER is used. DEFAULT_USER is used also if the Local Username field is blank.

Again, if DEFAULT_USER is used to connect to AcuConnect on an NTFS partition under Windows NT, 2000, or 2003 through 2008, be sure that DEFAULT_USER has both READ (RX) permissions on the wrun32.exe file and the appropriate permissions to access any file.

Common Access Records Example

For illustrative purposes, here is a set of common access records:

Client Machine Name | Client Username | Local Username | Password | umask
support-pc |  | techie | <none> | 002
warehouse-pc |  |  | <none> | 002
president-pc | diamond | <same as client> | <none> | 002
robin |  | <same as client> | <none> | 002
starling | felice | <same as client> | <none> | 002
starling | baxter |  | ...... | 002
swallow | hartley | hartley | <none> | 002
swallow |  | acct | <none> | 002
raven |  |  | * | 002

These entries are interpreted as follows:

  • The entry for "support-pc" allows any user of "support-pc" to use AcuConnect. AcuConnect will use the local user name "techie" when executing requests for "support-pc".
  • The entry for "warehouse-pc" allows any user of "warehouse-pc" to use AcuConnect. Because the Local Username field is empty, AcuConnect will use the value of DEFAULT_USER as the local user name when executing requests for "warehouse-pc".
  • The entry for "president-pc" allows user "diamond" to access AcuConnect. Because the Local Username field holds "same as client," AcuConnect will attempt to use "diamond" as the Local Username. If "diamond" is not a valid local user name, the value of DEFAULT_USER will be used.
  • The entry for "robin" allows all users of "robin" to access AcuConnect. If the requester has an account on the server by the same name, AcuConnect will use that name; otherwise, AcuConnect will use the value of DEFAULT_USER.
  • The first entry for "starling" allows user "felice" to access AcuConnect. AcuConnect will follow the same rules as the previous entry to assign a local user name.
  • The second entry for "starling" allows user "baxter" to access AcuConnect. AcuConnect will use the value of DEFAULT_USER when executing requests for "baxter." "baxter" will need to provide a password before a connection will be established.
  • The first entry for "swallow" allows user "hartley" to access AcuConnect. AcuConnect will use the local user name "hartley" when executing requests for "hartley."
  • The second entry for "swallow" allows all users of "swallow" to access AcuConnect. AcuConnect will use the local user name "acct" for all users of "swallow," except "hartley" (or other records for "swallow" that explicitly name a client user).
  • The entry for "raven" denies any user of "raven" access to AcuConnect.

The most permissive access record that can be created is:

Client Machine Name | Client Username | Local Username | Password | umask
* |  | <same as client> | <none> | 002

This record allows any user of any client to use AcuConnect, as long as the user has an account on the server by the same name, or DEFAULT_USER is defined with a valid user name (DEFAULT_USER cannot be defined to be root). A client user running as root will be mapped to DEFAULT_USER.

Parent topic: Establishing System Security


Using the Access File Manager

Create and maintain the server access file with the access file manager utility. To start this utility, use the acurcl -access command or the Access tab in the AcuConnect graphical control panel in Windows. To use the access file manager, you must be logged on to a UNIX server as root or superuser or on to a Windows server from the administrator account or from an account that belongs to the administrators group.

Note: To use the access file utility on Windows 2008 where User Access Control (UAC) security is turned on (as it is by default), any user must choose Run as Administrator in order to use the various AcuServer utilities. UAC can be turned off, in which case the user must merely be a member of the administrators group in order to fully operate the utility.

The access file manager is an interactive, menu-driven utility that allows you to do the following:

  • Create an access file
  • Add an access record
  • Remove an access record
  • Modify an access record
  • Display an access record

When the access file manager displays a value inside a pair of square brackets ([ ]), that value is the default value for the field. To accept the default value, press Enter. In the following example, /etc/AcuAccess is the default value.

Enter the name of the Server Access File
Filename [/etc/AcuAccess]:
  • Starting the Access File Manager
  • Creating or Opening an Access File
  • Adding an Access Record
  • Removing an Access Record
  • Modifying an Access Record
  • Displaying an Access Record
Parent topic: Establishing System Security


Starting the Access File Manager

To start the Access File Manager, use the acurcl -access command, as shown:

acurcl -access
Parent topic: Using the Access File Manager


Creating or Opening an Access File

When the Access File Manager starts, you are prompted for the path and name of the server access file:

Enter the name of the Server Access File
Filename [/etc/AcuAccess]:
  • To open an existing access file, enter the path and file name of interest. If the specified server access file is not found, the manager asks if you want to create the file:
    'accessfile' does not exist.
Do you want to create it [N]?
  • To create a new access file, enter Y. After opening or creating the access file, the manager displays a menu of five options:
    Server Access File Option:

1. Add a security record
2. Remove a security record
3. Modify a security record
4. Display one/all security records
5. Exit

Enter choice [4]:
Parent topic: Using the Access File Manager


Adding an Access Record

Use the following procedure to add an access record.

  1. Start the Access File Manager.
  2. Click option [1] on the main menu. The manager presents a series of five prompts, one for each field in the record. The first field is the Client Machine Name field. The prompt looks something like this:
    A value of "*" for client machine name means that
this record will match all clients for which there
are no other records.  You cannot use alias names.
The name must be the official machine name.  Enter
the official machine name [*]:

    Enter a client machine name or accept the default value.

  3. The second prompt is for the Client Username:
    If no client user name is entered it implies any user.
Enter client user name []:

    If this field is blank, any user name will match. Enter a client machine name or accept the default value.

  4. The third prompt fills in the Local Username field:
    A value of 'same as client' for local user name
means to use the client user name.  If no local
user name is entered DEFAULT_USER is used.
Enter the local user name [same as client]:

    The Local Username is the name that AcuConnect will use when executing access requests for requesters that match the first two fields of this record. If the Local Username is not a valid name on the server, the server will attempt to use the value of the server configuration variable DEFAULT_USER (if defined). If DEFAULT_USER is not defined, the connection will be refused (AcuConnect returns an error 9D/103). Enter a local user name or accept the default value.

  5. The fourth prompt allows you to specify a password that must be supplied by requesters who match this record:
    If no password is entered it implies none.
Enter password []:
Retype password for verification:

    Enter a password up to 64 characters long. The set of allowable characters includes upper- and lower-case letters, numbers, the space character, and most special characters (all ASCII characters numbered 32 to 126). Delete, escape, and other non-printable characters are not allowed. The password characters are not echoed on the screen when entered. You are asked to enter the password a second time to verify that it was entered correctly.

    If the password verification fails, you see the following message:
    Mismatch - try again.
If no password is entered it implies none.
Enter password []:
  6. The final prompt allows you to specify a umask:
    The umask defines the file creation mask for all
files created by this user.  It must be an octal
value between 000 and 777.
Enter umask [002]:

    Enter the umask of the runtime process started for the user or accept the default value. See Establishing System Security for information on determining this value.

    If you enter an invalid umask value, you see this message:
    Invalid value for umask - try again.
  7. After you specify a valid umask, the access file manager adds the record to the server access file:
    Record added.
Press <Return> to continue...

    If you accept all of the defaults when creating the record, the entry looks like this:

    Client Machine Name Client Username Local Username Password umask
    * <same as client> <none> 002

    This record entry matches any client and allows any user to connect to the server, provided that the user has an account of the same name on the server, or the DEFAULT_USER variable is defined with the name of a valid user. Through inclusion or exclusion of wild cards, named entries, passwords, and umasks, it is possible to construct a server access file that allows open, unrestricted access; rigid, tightly controlled access; or almost any level in between.

Parent topic: Using the Access File Manager


Removing an Access Record

Use the following procedure to remove an access record.
  1. Start the Access File Manager.
  2. Click option [2] on the main menu. The manager presents two prompts:
    Enter official client machine name:
Enter client user name:

    At the first prompt, enter the official client machine name. At the second prompt, enter the client user name.

    If a matching record is found, it is removed and the following message appears:

    Record removed
Press <Return> to continue...
Parent topic: Using the Access File Manager


Modifying an Access Record

Use the following procedure to modify an access record.
  1. Start the Access File Manager.
  2. Click option [3] on the main menu. The manager presents two prompts:
    Enter official client machine name:
Enter client user name:

    At the first prompt, enter the official client machine name. At the second prompt, enter the client user name.

  3. If a matching record is found, the following message appears:
    Here is the record that was found:
Client machine name:
Client user name:
Local user name:
Password
Umask:

Do you want to modify the local user name [N]:

    Enter Y to modify the local user name. If you have a different local user name and want to change the record to "same as client," you can enter same as client at this prompt. Upper/lower case is ignored, but you must put a single space between the words. Don't enter brackets or quotes.

  4. If you enter "Y" or "same as client" at this prompt, you are asked:
    Do you want to modify the password [N]:

    If you want to modify the password, enter a new one now.

  5. After the password value is entered, you are prompted:
    Enter a new umask [002]:

    If you want to change the umask, enter the new value here.

    The record is updated:

    Record modified
Press <Return> to continue...
Parent topic: Using the Access File Manager


Displaying an Access Record

Use the following procedure to display an access record.
  1. Start the Access File Manager.
  2. Click option [4] on the main menu. The manager asks if you want to display the records to the screen:
    Display to the screen [Y]?
  3. You can display records to the screen, or you can output all of the records to a file:
    • To display the records to the screen, enter Y. The manager responds with the following prompt:
      Display all records [Y]?

      Enter Y to display all records to the screen. Enter N to select a specific record to display to the screen. If you enter N, the manager presents two prompts:

      Enter official client machine name:
Enter client user name:

      At the first prompt, enter the official client machine name. At the second prompt, enter the client user name. If a matching record is found, the record is displayed. Otherwise, the manager states that no match was found and returns to the main menu.

    • To copy the records to a file, enter N. The manager responds with the following prompt:
      Enter the name of the Server Report File
Filename [AcuAccess.rpt]:

      Enter a file name or accept the default. The manager copies the access records to the named file.

      Creating 'AcuAccess.rpt'
Parent topic: Using the Access File Manager


Creating a Server Alias File in Thin Client

Before using AcuConnect for thin client operations, you must create a single association file to hold all the information that will be needed to invoke the appropriate application on the server. This file is in XML format.

Note: Alias files created prior to Version 7.0 are in .ini format. These files are automatically converted to XML format on first use with Version 7.0 and beyond. If you would prefer your alias file to be in .ini format, set the ALIAS_FILE_IS_XML variable to “FALSE” in your environment when executing acurcl -alias (or acurcl with the graphical control panel on Windows). Alias files in XML format are incompatible with all AcuConnect versions prior to 7.0.
  1. Log on to the server as the superuser (UNIX) or administrator (Windows) and enter:
    acurcl -alias
    Note: In Windows, you can select the acurcl command in the graphical control panel's Alias tab.
  2. You are prompted to enter the name of the alias file:
    Enter the name of the Alias file: [/etc/acurcl.ini]

    In VMS, the following prompt appears:

    Enter the name of the alias file: [acurcl.ini]

    Enter the name of the file you want to use or press Enter to use the default file. If the file does not exist, AcuConnect asks if you want to create it. If you answer N, it asks for a new file name. If you answer Y, it displays the alias entry menu:

    RCL Alias file options
1) Add an alias entry
2) Remove an alias entry
3) Modify an alias entry
4) Display alias entries
5) Exit
Enter Choice [4]:
  • Adding Aliases
  • Removing Aliases
  • Modifying Aliases
  • Displaying Aliases
Parent topic: The AcuConnect Server


Adding Aliases

Use the following procedure to add an alias.

  1. Click item [1] on the alias menu. You will receive the following prompt:
    Add an alias
Enter the alias name:
  2. Enter the name of the alias you want to add. If the named alias already exists in the alias file, a message displays:
    Alias already exists

    and you are returned to the alias menu. Otherwise, you are asked for the working directory for the alias:

    Enter the working directory:
  3. Enter an existing directory name. (Note that Acuconnect does not verify that this directory actually exists.) You are then asked for a command line for the runtime:
    Enter the command line:
  4. Enter the command line that you would normally enter when executing the runtime, except do not include the runtime name.
    Enter the command line:

    The command line is parsed and the alias entry is added to the alias file. If there are incorrect parameters in the command line, the parsing fails and the alias is not added to the alias file. Note that if you inadvertently add a space, tab, or special character to the name of your program, it may not be found.

Example

To add an alias entry named "tour" that runs the tour program with the command runcbl -le err tour, you would have the following interaction:

C:\MicroFocus\AcuCBL8xx\AcuGT\bin> acurcl -alias
Enter the name of the Alias file: [/etc/acurcl.ini] myalias.ini

'myalias.ini' does not exist. Do you want to create it [N]? y

RCL Alias file options
1) Add an alias entry
2) Remove an alias entry
3) Modify an alias entry
4) Display alias entries
5) Exit

Enter Choice [4]: 1
Add an alias
Enter the alias name: tour
Enter the working directory:
C:\microfocus\acucbl8xx\acugt\sample
Enter the command line:
-le err tour
Press <Return> to continue...

RCL Alias file options
1) Add an alias entry
2) Remove an alias entry
3) Modify an alias entry
4) Display alias entries
5) Exit

Enter Choice [4]: 5

C:\MicroFocus\AcuCBL8xx\AcuGT\bin>
Parent topic: Creating a Server Alias File in Thin Client


Removing Aliases

Use the following procedure to remove an alias.

  1. Click item [2] on the alias menu. You receive the following prompt:
    Remove an alias
Enter the alias name:
  2. Enter the name of the alias that you want to remove. If the named alias does not exist in the alias file, a message displays:
    Alias does not exist

    and you are returned to the alias menu. Otherwise, you see the current working directory and command line for the alias, and are asked to confirm deleting the entry:

    Are you sure you want to remove this alias?
  3. Enter Y or N. In either case, you are returned to the alias menu. If you answered "Y", the alias is no longer an entry in the alias file.
Parent topic: Creating a Server Alias File in Thin Client


Modifying Aliases

Use the following procedure to modify an alias.

  1. Click item [3] on the alias menu. You receive the following prompt:
    Modify an alias
Enter the alias name:
  2. Enter the name of the alias that you want to modify. If the named alias does not exist in the alias file, a message displays:
    Alias does not exist

    and you are returned to the alias menu. Otherwise, you see the current working directory and are asked for a new one.

  3. Press Enter to leave the working directory unchanged, or enter the name of a different directory.
  4. After you enter a directory, you see the command line as it currently exists in the alias file, and are asked for a new command line. Press Enter to leave the entry unchanged, or enter a new command line. You are then returned to the alias menu.
Parent topic: Creating a Server Alias File in Thin Client


Displaying Aliases

To display an alias, click item [4] on the alias menu. You receive the following prompt:

Display aliases
Enter the alias name:

Enter a valid alias name, or enter nothing to see a list of valid aliases contained in the file. If you enter a valid alias name, you see the working directory and the command line for that alias. You are then returned to the alias menu.

Note: AcuConnect rewrites the command line before putting it into the alias file, so when it is displayed, it might not be exactly the same as what was originally entered.
Parent topic: Creating a Server Alias File in Thin Client


Installing Server Programs

The last step in preparing your server for use with AcuConnect is copying the server components of your COBOL application onto the server into the desired directory. If you created a runtime configuration file for the server application, you must copy this onto the server as well.

AcuConnect supports the following server operating systems:

  • UNIX
  • Windows NT Server
  • Windows 2000, 2003, 2008 Server
Parent topic: The AcuConnect Server


Starting AcuConnect

For a client process to access programs on the server, AcuConnect must be running. To start and stop AcuConnect (as well as to perform several system administration functions such as checking system status, maintaining the server access file, or installing AcuConnect as a Windows service), you issue the acurcl command on the server at the command line. In Windows, using the acurcl command with no options brings up a graphical control panel. You can start AcuConnect from the Services tab of this screen.

This help section provides specific instructions for issuing the acurcl -start command on the server. See 8. Managing the System for a description of AcuConnect's systems administrator functions and a complete reference to acurcl command formats and options.

  • Starting AcuConnect on a UNIX Server
  • Starting AcuConnect on a Windows Server
  • Starting AcuConnect in Thin Client on a VMS Server
  • Starting AcuConnect at System Startup
Parent topic: The AcuConnect Server


Starting AcuConnect on a UNIX Server

To start AcuConnect on a UNIX server, log in as root or superuser, then issue the acurcl -start command on the server command line. Valid options to -start are listed in the following table.

Option | Description
-c

Specifies the name and path of the server configuration file. The -c must be followed by a space and then the path and name of the server configuration file.

When -c is not used, acurcl looks for the configuration file in its default location: /etc/acurcl.cfg for UNIX or \etc\acurcl.cfg for Windows.

-d

Starts AcuConnect on the server machine in debug mode. AcuConnect runs in the foreground. Note that you are limited to one UNIX client connection when you use this option.

-e Causes error output from acurcl to be placed in the named file. Follow -e with a space and then the path and name of the error output file (use this same syntax for the -ee and +-e options listed below).
  • If -e is not specified, acurcl attempts to direct error output to /dev/console.
  • If /dev/console cannot be opened, acurcl attempts to append to a file named acurcl.err in the current directory.
  • If the acurcl.err file doesn't exist, or the file append fails, acurcl prints the message acurcl: can't open error output file to standard output, and acurcl terminates.

You can use -ee to redirect the contents of stderr into the new error file. You can use +-e to append error output from acurcl to the named file.

-f

By default, acurcl runs in the background. Use the -f option to run acurcl in the foreground. When run in the foreground, the acurcl process traps normal keyboard signals, such as Ctrl+C.

If combined with the --t option, the -f option causes acurcl to display tracing and transaction messages directly to the screen. However, if the -e switch is used, all messages are placed in the named log file.

-g | Causes the file specified by the -e option to be compressed using the gzip compression method. Because the error file name is not modified to reflect the compression, specify a different file extension for the error file (for example, .gz) when you use this option. To read the file, you must decompress it with gzip.
-i

Causes a listing of the server configuration file to be printed to standard error output. This can be helpful when you are debugging problems that may be related to configuration variables.

When this option is combined with the -e option, the listing is captured in the error output file.

-n

Assigns a port number to one instance of the acurcl daemon. The -n must be followed by a space and then an integer, for example, 5633. This overrides the ACURCL_PORT value set in the server configuration file.

Thin client applications can be assigned to a particular instance of the acurcl daemon via the <server:port> notation on the acuthin command line. Thin clients launched from a Web page can have the port number specified by the atc-port variable in the thin client command-line file. See Thin Client Command-line Files for more information.

The acurcl daemon can work with privileged port numbers (from 0 to 1023), and with non-privileged port numbers (1024 and higher). Privileged port numbers are useful for external, secure applications.

Note: If you start acurcl on two ports, you must also specify all startup arguments, including the configuration file, as in:
acurcl -start -n 5632 -c
c:\etc\config1 [other options]
acurcl -start -n 5633 -c c:\etc\config2 [other
options]
-t #

Turns on the tracing function. When combined with the -e option, trace information is placed in the named error file. The # symbol represents the type of tracing or logging to be performed, as described below:

  • 1 provides information about access file match attempts. The trace information buffer is flushed to the error file when the buffer is filled or acurcl terminates.
  • 2 provides information about runtime requests. The buffer is flushed to the error file when the buffer is filled or acurcl terminates.
  • 3 provides the information described for 1 and 2.
  • 5 is equivalent to 1, but the tracing buffer is flushed to the error file each time an access file match is requested. (File trace flushing can also be controlled with the FILE_TRACE_FLUSH server configuration variable. See Creating a Server Configuration File for more information.
  • 6 is equivalent to 2, but the tracing buffer is flushed to the error file each time a runtime is requested.
  • 7 provides the information described for 5 and 6.

You can stop AcuConnect at any time by issuing the acurcl -kill command. See acurcl -kill for a discussion of the -kill command options.

AcuConnect returns a status code of 0 after a successful start. When AcuConnect fails to start, it returns one of the following status codes to the operating system, indicating the reason for the failure.

Code | Reason for Failure
1 | Invalid argument
2 | Missing license
3 | Expired license
4 | Unable to open the error log file
5 | Unable to open the configuration file (writable by other than root)
6 | Unable to open the AcuAccess file (missing or writable by other than root)
7 | Unable to create a child process
8 | Too many servers running
9 | Unable to create a socket, because the socket is used by something other than AcuConnect
10 | AcuConnect is already running on this port

How you get this status depends on your shell. When you use the Bourne shell (or a compatible shell), enter echo $? to see the return status of any program executed from the shell.

Setting the User Environment in UNIX

With the use of the USE_UNIX_SHELL configuration variable, you can direct AcuConnect to attempt to read your UNIX shell login files based on the shell named in /etc/passwd when AcuConnect starts a runtime. Setting this variable to "true" means that AcuConnect can start a runtime through your login files, and the environment variables you set in these files are therefore available to the runtime.

AcuConnect tries to convince the shell to read the startup files by making the first character of argv[0] = `-', just as login(1) does. As a result, the following environment variables are set:
  • HOME (from /etc/passwd)
  • SHELL (from /etc/passwd)
  • PATH /usr/local/bin:/bin:/usr/bin:
  • TERM dumb
  • LOGNAME $USER

Your startup files may modify these variables or set other variables.

AcuConnect starts the shell as shown:

shell -c "'runcbl' . . ."

where shell is the user's shell and the ellipsis (". . .") designates the position of the arguments that AcuConnect would normally use to start the runtime. The full path to runcbl is also given. Make sure that the shell used supports the -c option and the ability to set argv[0] to "-". For example, the following shells can be used: sh, ksh, and bash. The csh and tcsh shells are not supported.

Parent topic: Starting AcuConnect


Starting AcuConnect on a Windows Server

Issue the acurcl -start command from the administrator account or from an account that belongs to the administrators group. On Windows servers, it's best to specify acurcl -start with no options. Alternatively, you can click the Start button on the Windows graphical control panel's Services tab.

Note: To use the AcuServer Control Panel on Windows 2008, where User Access Control (UAC) security is turned on (as it is by default), any user must choose Run as Administrator in order to use the various AcuServer utilities. UAC can be turned off, in which case the user must merely be a member of the administrators group in order to fully operate AcuServer.

You can stop AcuConnect at any time by issuing the acurcl -kill command or by clicking Stop on the control panel's Services tab. See acurcl -kill for a discussion of the -kill command options.

Parent topic: Starting AcuConnect


Starting AcuConnect in Thin Client on a VMS Server

To start AcuConnect on VMS (version 7.2 or later) as a detached process, use the following command line:

run/detached sys$system:loginout /input=acurcl.com -  /output=acurcl.out /process_name=acurcl
Parent topic: Starting AcuConnect


Starting AcuConnect at System Startup

On a UNIX server, to start AcuConnect whenever the server boots, add the acurcl -start command to the system boot file. Your entry might be similar to the following:

#
# If the acurcl executable is present,
# start acurcl
if  (test -f  /acucobol/acurcl)  then
   echo Starting acurcl > /dev/console
   /acucobol/acurcl -start -e /acucobol/acurcl.log
fi

On a Windows server, you should install AcuConnect as a Windows service. This causes the service to be started automatically each time the system is booted. If you don't install it as a service, it will stop whenever you log out.

We provide an installation script that gives you the option to install the acurcl daemon as a Windows service. If you choose not to install the service from the installation script, you can install it as a service as follows:

acurcl -install

You must be logged on to an account that belongs to the administrators group.

Alternatively, you can click New in the graphical control panel's Services tab. The service will now be started automatically each time the system is booted.

Immediately following the installation, you can start the service from the graphical control panel's Services tab by clicking Start. As an alternative, you can use the Start > Settings > Control Panel > Services menu option.

Note: Installing a service on a particular port resets all startup options for the service on that port. You can use all valid -start options when installing AcuConnect as a service. These options are stored so that the service will use them when starting.
Parent topic: Starting AcuConnect


AcuConnect Connection Logic

How the client connects to AcuConnect depends on the client application that is attempting to connect. However, some common steps are involved with any attempt, regardless of the client application. These are described here to clarify the use of the server access file and the DEFAULT_USER configuration variable.

To validate a requester's access privileges, AcuConnect does the following when a client process first makes a request to AcuConnect:

  1. Opens the server access file.
  2. Searches for a record that matches both the client machine name and the client user name.
  3. (If no match is found) searches for a record that matches the client machine name and a "match all" (blank) client user name.
  4. (If no match is found) searches for a record that has the "match all" ("*") client machine name and the client user name.
  5. (If no match is found) searches for a record that has the "match all" ("*") client machine name and the "match all" (blank) client user name.
  6. (If no match is found) refuses the connection.

When a match is found:

  1. If the Local Username is valid, it is used.
  2. If the Local Username is not valid, DEFAULT_USER is used.
  3. If the Local Username is not valid and DEFAULT_USER is not valid, the connection is refused.
  4. If the Local Username is valid and the password field is defined, a message is sent back to the requester asking for a password.

When a connection is established, AcuConnect invokes the runtime based on the information provided by the client making the request. AcuConnect connects that child runtime with the client and then removes itself from the communication loop between the two processes.

  • Passwords
  • Exiting the Access Manager
Parent topic: The AcuConnect Server


Passwords

When a password is assigned to an entry in the server access file, requesters who match that entry must return a matching password to AcuConnect. In a distributed processing environment, the client application has two options for acquiring and sending a password back to AcuConnect. In thin client, only option 2 applies.

Option 1: Program Variable

The requesting application may include code that checks for the program variable acu_client_password. If defined, its value is considered an unencrypted password, which is then encrypted and sent to AcuConnect for verification. If the value does not match the value in the access record, the connection is refused. Using acu_client_password, the COBOL programmer has a great deal of flexibility in setting and acquiring the password. The programmer can supply a password to AcuConnect without requiring any user interaction (the user may remain unaware that a password is required).

Option 2: User-entered Password

If acu_client_password is not defined, the client runtime opens a dialog window requesting that the user enter a password.

A password is required to connect to host hostname.
Please enter a password:

The user must enter a password. The characters do not echo on the screen.

The password is then encrypted and sent to the server for verification. If the password matches, a connection is established. If the password doesn't match, or if the user enters a blank password (by pressing Enter or clicking OK), the user is prompted again to enter a password:

Invalid password
Please enter a password:

The password verification cycle is repeated until a valid password is entered, or the value of the server configuration variable PASSWORD_ATTEMPTS is exceeded (the default value is "3"). The text displayed by the runtime to prompt for a password and report a failed verification can be modified with the TEXT runtime configuration variable. See Creating a Server Configuration File for more information about these configuration variables.

Parent topic: AcuConnect Connection Logic


Exiting the Access Manager

To exit the manager, select option [5] from the main menu.

Parent topic: AcuConnect Connection Logic


Server Configuration

  • Introduction
  • Configuring the Environment
  • Creating a Server Configuration File
  • Creating a Runtime Configuration File for the Remote Server Component
Parent topic: AcuConnect Version 10.2.0 User's Guide


Introduction

After you install AcuConnect, you need to configure the server. At a maximum, this can entail configuring the environment, creating a server configuration file for AcuConnect, and creating a runtime configuration file for the server component of your COBOL program. If you accept the default security file locations and other settings, however, no special configuration is required.

The client machine also requires configuration. See Preparing the Client(s) in Distributed Processing and Preparing the Client(s) in Thin Client for more information.

Parent topic: Server Configuration


Configuring the Environment

Environment variables are values maintained by the host operating system that can be changed by the user. These values can be used to store information such as the location of executable programs and header files. Use the ALIAS_FILE_IS_XML environment variable to specify the format of your alias file on your AcuConnect server. See Environment Variables in the ACUCOBOL-GT User's Guide for more information on environment variables.

  • ALIAS_FILE_IS_XML
Parent topic: Server Configuration


ALIAS_FILE_IS_XML

Alias files are stored on disk as XML files by default. If you want the alias files to be in INI format rather than in XML, set the ALIAS_FILE_IS_XML environment variable to FALSE.

Note: Once the alias file is in XML format, setting this variable to FALSE won't revert it.

If you want to use this variable, you must set it in the environment when you are executing acurcl -alias (or acurcl with the graphical control panel on Windows), because AcuConnect reads no configuration files in this mode.

See your operating system documentation for how to set environment variables.

Parent topic: Configuring the Environment


Creating a Server Configuration File

The server configuration file, called acurcl.cfg, tells AcuConnect the location of the AcuAccess file, defines the default user, and supplies other information. The server configuration file is completely optional if you have stored AcuAccess in the default /etc or drive:\etc directory (\etc for UNIX/Linux).

When shipped, AcuConnect comes with a sample acurcl.cfg file. If you choose to use a server configuration file, you can use the sample file as is (complete with its default values), or you can modify the file to your specification. By default, AcuConnect looks for acurcl.cfg in /etc or drive:\etc on the server. If the file is given another name or is located in another directory, you must specify the full location and name of the file with the -c option when you start AcuConnect. See the description of the -start command in acurcl -start for more information.

The server configuration file can contain any or all of the following variables:

Name | Default Value
ACCESS_FILE | /etc/AcuAccess
ACURCL_PORT | 5632
AGS_BAD_SOCKET | undefined
ALIAS_FILE_IS_XML | TRUE
CHILD_WAIT | 50
DEFAULT_USER | undefined
FILE_TRACE | 0
FILE_TRACE_FLUSH | FALSE
FILE_TRACE_TIMESTAMP | FALSE
FORCE_KILL_TIME | 150 seconds
PASSWORD_ATTEMPTS | 3
PROVIDE_PASSWORD_MESSAGES | FALSE
SECURITY_METHOD | NONE
SERVER_ALIAS_FILE | /etc/acurcl.ini (thin client only)
SERVER_IP | undefined
SERVER_NAME | undefined
SERVER_RUNTIME | wrun32.exe or runcbl in the acurcl directory
TEXT_015 | "A password is required to connect to host %s."
TEXT_016 | "Please enter a password: "
TEXT_017 | "Invalid password."
USE_SYSTEM_RESTRICTIONS | FALSE
USE_UNIX_SHELL | FALSE
WINNT_LOGON_DOMAIN | undefined
WINNT_EVENTLOG_DOMAIN | NULL

Note that values assigned to variables contained in the server configuration file are applied solely to operations performed by AcuConnect. See Starting AcuConnect for information on using these variables.

  • ACCESS_FILE
  • ACURCL_PORT
  • AGS_BAD_SOCKET
  • CHILD_WAIT
  • DEFAULT_USER
  • FILE_TRACE
  • FILE_TRACE_FLUSH
  • FILE_TRACE_TIMESTAMP
  • FORCE_KILL_TIME
  • PASSWORD_ATTEMPTS
  • PROVIDE_PASSWORD_MESSAGES
  • SECURITY_METHOD
  • SERVER_ALIAS_FILE
  • SERVER_IP
  • SERVER_NAME
  • SERVER_RUNTIME
  • TEXT_nnn
  • USE_SYSTEM_RESTRICTIONS
  • USE_UNIX_SHELL
  • WINNT_LOGON_DOMAIN
  • WINNT_EVENTLOG_DOMAIN
Parent topic: Server Configuration


ACCESS_FILE

The ACCESS_FILE variable (along with DEFAULT_USER and PASSWORD_ATTEMPTS) affects AcuConnect access security.

ACCESS_FILE must hold the full path and file name of the server access file, if it is other than the default location (/etc/AcuAccess on UNIX systems; \etc\AcuAccess on the root drive on Windows servers).

For example:

access_file c:\security\AcuAccess
Parent topic: Creating a Server Configuration File


ACURCL_PORT

The ACURCL_PORT variable specifies a particular port number to be used for accessing AcuConnect on the server host machine. This is especially helpful when the server host machine has a security firewall, because firewalls generally allow access only to specific ports. With this variable, the site can ensure that firewall restrictions are satisfied.

The acurcl daemon can work with privileged port numbers (from 0 to 1023) and with non-privileged port numbers (1024 and higher, up to 32767).

The value of this variable is overridden by any port number assigned on the command line (via the -n option) when the daemon is started.

Note: The ACURCL_PORT variable may be specified in the server configuration file. It may also be specified on the server command line with the -n option. If you specify a non-default value, you must use the same value on the client side (using the <server:port> notation).
Parent topic: Creating a Server Configuration File


AGS_BAD_SOCKET

AcuConnect depends on the ability to pass an open socket descriptor to the runtime for the client to communicate with the server. Some UNIX shells don't pass all file descriptors to a child process. You may be experiencing such a problem if users can sometimes connect to the server, but other times can no longer connect, even though there are sufficient licenses.

If you detect such problems, look for a line in the server runtime error file that shows what descriptor the socket is using, as in the example below:

Runtime version 9.0.0
Configuration file = 'config'
Thin client socket uses descriptor 6
Loading map file
Unable to open TC-MAP-FILE '', error 0
Try loading 'testit.acu'...
testit.acu loaded

Set the AGS_BAD_SOCKET variable to this socket descriptor to alleviate the problem. You can set this variable multiple times, once for each bad descriptor that you detect. Each time you set it, however, you should set it to a single value. For example, if you find that descriptors "18" and "62" are causing problems, you can add the following two lines to the runtime configuration file:

AGS_BAD_SOCKET 18
AGS_BAD_SOCKET 62
Note: If the socket descriptor is in use at the time you attempt to set it, you will not be able to use the -config option of acurcl.

Also, note that there is a chance that the setting will fail when using -config. You can determine whether this setting had any effect by looking at the error file. You will see a line something like:

7431977 - CONFIG request - SET AGS_BAD_SOCKET to n
Set parameter 'AGS_BAD_SOCKET' to n

Instead of n, you will see the value you are trying to set. The most important line is the second. If you don’t see that line, it means that acurcl has that descriptor value open for some other purpose (perhaps another client is trying and failing to connect). You should continue trying until you get the setting.

Parent topic: Creating a Server Configuration File


CHILD_WAIT

The CHILD_WAIT configuration variable lets you determine how long AcuConnect waits for a child runtime to start successfully. This variable is valid for Windows servers only. The default value (in milliseconds) is "50". When you set this variable to "0", AcuConnect does not wait at all. The maximum value is "32767", or approximately 32 seconds.

This variable helps you determine whether you have reached a Windows limit on the number of simultaneous child runtimes. See Connection Refused for more information about this Windows limitation and how to work around it.

Parent topic: Creating a Server Configuration File


DEFAULT_USER

DEFAULT_USER holds the default user name given to AcuConnect requesters who are not specifically mapped to a local user name in the server access file (as when the Local Username field of the access record is empty, or the value of the field is an invalid user name). Definition of DEFAULT_USER is optional. DEFAULT_USER cannot be defined as root on UNIX systems or administrator on Windows systems. See AcuConnect Connection Logic for a description of when AcuConnect assigns DEFAULT_USER to a requeste.

Parent topic: Creating a Server Configuration File


FILE_TRACE

This variable allows you to start the tracing function without specifying a -t # option on the command line when you start AcuConnect. Setting this variable to a value between 1 and 7 saves connection information. The default value is 0. See Starting AcuConnect for more information about trace values.

Parent topic: Creating a Server Configuration File


FILE_TRACE_FLUSH

Setting FILE_TRACE_FLUSH to "1" (on) causes AcuConnect to flush the error trace buffer to disk after every alias program execution. This function also ensures that in the event that the acurcl daemon terminates abnormally, all trace information, up to the last alias program execution, is captured in the error file.

If this configuration variable is not used (set to 0, false, or off), and AcuConnect terminates unexpectedly, an undefined amount of trace information is lost. FILE_TRACE_FLUSH is set to "false" by default.

Note that you can also enable trace flushing when you start the acurcl daemon by including the -t # command-line switch in the -start command. See Starting AcuConnect for more information.

Parent topic: Creating a Server Configuration File


FILE_TRACE_TIMESTAMP

Setting this variable to "true" allows you to turn on trace file timestamping. The timestamp is added to the trace file at the beginning of every line. The default value is "false". Note that setting this variable to "true" may have a negative impact on performance.

Parent topic: Creating a Server Configuration File


FORCE_KILL_TIME

In versions prior to 8.1.2 and when using Thin Client, if the runtime on the server side was stuck in a process intensive loop, then issuing the acurcl -kill -p command had no effect until the runtime became free to process the kill command. This lead to orphan runtimes as sometimes the runtime never came out of the loop or became free and also a hard kill command was never issued.

This behaviour was corrected in version 8.1.2 so that after a default set amount of time, a hard kill command is issued on the errant runtime.

The amount of time to wait before a hard kill is issued can be controlled by the FORCE_KILL_TIME. Set this variable to the amount in seconds to wait before issuing a hard kill. The default value for this variable is 150 seconds

Parent topic: Creating a Server Configuration File
Related information
acurcl -kill


PASSWORD_ATTEMPTS

The variable PASSWORD_ATTEMPTS (along with DEFAULT_USER and ACCESS_FILE) affects AcuConnect access security.

PASSWORD_ATTEMPTS holds a positive integer value specifying the total number of password validation attempts a requester is allowed before a connection attempt is terminated. The default value is "3". If a value of less than "1" is given, the value "1" is used. If a non-integer value is given, the default value is used.

Parent topic: Creating a Server Configuration File


PROVIDE_PASSWORD_MESSAGES

This variable controls whether the server sends password messages to the client when a remote connection is requested and passwords are required. When you set this variable to "true", the password messages defined in the TEXT configuration variable are sent to the client when it requests a connection to the server. If PROVIDE_PASSWORD_MESSAGES is set to the default value of "false", the client uses its own default values.

Parent topic: Creating a Server Configuration File


SECURITY_METHOD

This variable lets you determine the security method AcuConnect employs for user logon. AcuConnect can use the operating system's native logon facility or the security provided by the AcuAccess file. Users can use their regular passwords when they connect to servers, instead of having a different password in the AcuAccess file or remembering to keep the password in the AcuAccess file coordinated with the native password.

This feature works for Windows servers and for UNIX servers. For UNIX servers, passwords can be stored in /etc/passwd or in /etc/shadow (in other words, the machine uses shadow passwords). It does not use the newer pluggable authentication module (PAM) libraries.

The default value of SECURITY_METHOD is "NONE", which means that AcuConnect's AcuAccess file security is used. See Establishing System Security for information about using the AcuAccess file.

When this variable is set to "LOGON", the operating system's native logon capability is used.

Windows

In Windows, AcuConnect attempts to log the user onto the domain specified in the WINNT_LOGON_DOMAIN configuration variable. AcuConnect first uses the password in the AcuAccess file to log the user onto the server. If the AcuAccess password matches the user's Windows domain password, the login completes and the user is never prompted for a password. If the password doesn't match, or if the password field in the AcuAccess file is empty, the user is prompted to supply a password. The password provided must match the user's network domain password on the Windows server. The number of attempts the user has to supply the correct password is limited by the value of the configuration variable PASSWORD_ATTEMPTS. A successful logon grants users all the access rights they would have if they were directly logged on to the server. AcuConnect allows Windows servers to manage all issues pertaining to access permissions.

UNIX

In UNIX, the AcuAccess password is checked against the password in the system files. If the password matches, the login is completed. If it doesn't match, the user is asked for a password that is then checked against the system password. If you want your UNIX machine to be able to restrict access to the machine based on various parameters, set the USE_SYSTEM_RESTRICTIONS configuration variable.

In distributed processing, SECURITY_METHOD is set on both the client and the server, and the values must match. If the values don't match, the security method reverts to "NONE", which uses only the AcuAccess password.

In a thin client environment, the initial behavior is different from that of distributed processing. When the thin client establishes its configuration, it has a default setting of "LOGON". This value must match the SECURITY_METHOD setting on the server. If the values don't match, the security method reverts to "NONE", which uses only the AcuAccess password.

Parent topic: Creating a Server Configuration File


SERVER_ALIAS_FILE

This variable applies only in a thin client environment. SERVER_ALIAS_FILE holds the name of the alias file to be used with the thin client. When the thin client is invoked, it is not given the name of a COBOL program to run. Rather, it is given the name of an alias to use. This alias holds all the information for invoking the runtime, which will be used to run the COBOL program. See Creating a Server Alias File in Thin Client for information on creating the server alias file.

Parent topic: Creating a Server Configuration File


SERVER_IP

This variable is necessary only if your server interfaces with more than one network. In this instance, you can use SERVER_IP to specify the exact Internet Protocol (IP) address of the network interface card that you want AcuConnect to use. For example:

SERVER_IP 192.215.170.107

starts AcuConnect using IP address 192.215.170.107. If you have already assigned a host name to the desired IP address, you can use the SERVER_NAME variable instead of SERVER_IP to specify the precise network card to use.

Note: If using IPv6 addresses, you must enclose the IP address in brackets when appending the port number or any additional notation; see AGS_USE_IPV6 for more information.

If both the SERVER_IP and SERVER_NAME configuration variables are defined in the configuration file, AcuConnect uses the value of the first valid entry in the file.

Parent topic: Creating a Server Configuration File
Related reference
AGS_USE_IPV6


SERVER_NAME

You can use this variable in place of SERVER_IP to specify which network interface card to use when starting AcuConnect. It is necessary only if your server interfaces with more than one network, and it can be used only if you have already assigned a host name to the desired IP address. In this instance, you can use SERVER_NAME as follows:

SERVER_NAME <host-name>

where <host-name> is the host name assigned to the IP address of the desired network card. For example:

SERVER_NAME nts2

starts AcuConnect using host name nts2.

Note that if both the SERVER_IP and SERVER_NAME configuration variables are defined in the configuration file, AcuConnect uses the value of the first valid entry in the file.

Parent topic: Creating a Server Configuration File


SERVER_RUNTIME

This variable is used to specify the name of the runtime to use. The default is to use the runtime that is in the same directory as AcuRCL.

Parent topic: Creating a Server Configuration File


TEXT_nnn

You can use a set of TEXT configuration variables to control the text of selected AcuConnect messages. Configuration variables are included to support AcuConnect password handling. The default text for each message is:

TEXT_015  "A password is required to connect to host %s."
TEXT_016  "Please enter a password:  "
TEXT_017  "Invalid password."

In message 015, the name of the AcuConnect host is substituted for the %s characters.

To change the text associated with a given message, append an equals sign (=) followed by the new text. For example:

TEXT_016=Enter your password now:

Note that to enable the display of the password messages, you set the PROVIDE_PASSWORD_MESSAGES variable to "true" (1, on, yes).

The use of password protection is optional. If password protection is not used, these messages will not be displayed.

Parent topic: Creating a Server Configuration File


USE_SYSTEM_RESTRICTIONS

This configuration variable applies only to UNIX systems. Some UNIX machines can restrict access to the machine based on various parameters. If you want to include those restrictions in AcuConnect, set the USE_SYSTEM_RESTRICTIONS configuration variable to "true". The default value is "false".

This configuration variable is available only on UNIX servers and is used only if the SECURITY_METHOD configuration variable is set to "LOGON".

The server uses the loginrestrictions() function to implement this feature. Ask your system vendor for information about this function and how to establish restrictions.

Parent topic: Creating a Server Configuration File


USE_UNIX_SHELL

This configuration variable determines whether AcuConnect attempts to start a runtime through the user's UNIX login shell. When USE_UNIX_SHELL is set to "true" (1, on, yes), AcuConnect reads the user's login shell files based on the shell named in /etc/passwd when it starts a runtime for that user. As a result, the runtime has access to all the environment variables that the user has set in the startup file. The default value is "false".

Note: Running AcuConnect in debug mode when USE_UNIX_SHELL is "on" in a distributed processing deployment may render the UNIX debugger display unreadable. This behavior occurs because the TERM environment variable is automatically set to "dumb" when USE_UNIX_SHELL is on. To avoid this behavior, you can add a line to your shell's login script file (for example, .profile, .bash_profile, or .cshrc) that sets either the TERM or A_TERM environment variable to another value.
Parent topic: Creating a Server Configuration File


WINNT_LOGON_DOMAIN

This configuration variable applies only to Windows servers. When the SECURITY_METHOD configuration variable is set to "LOGON", you can specify a domain name for user logon via another configuration variable. Setting WINNT_LOGON_DOMAIN to the name of a Windows domain logs the user on to that domain. The user logs on to the NULL domain if this variable is not set. Note that the WINNT_LOGON_DOMAIN setting applies only when SECURITY_METHOD is "LOGON".

Parent topic: Creating a Server Configuration File


WINNT_EVENTLOG_DOMAIN

This configuration variable applies only to Windows servers. Set WINNT_EVENTLOG_DOMAIN to the Universal Naming Convention (UNC) name of the computer to which event log messages should be sent. This variable must be set in the configuration file and is not changeable.

If this variable is not set, system logging information is sent to the local machine on which the server is executing. See Event Logging for information about event logging.

Parent topic: Creating a Server Configuration File


Creating a Runtime Configuration File for the Remote Server Component

Because at least some application logic executes on the server, you may want to create a runtime configuration file for the remote server component of your application. If you create this file, you will install it on the server machine along with the remote application component. This file defines how the remote application should behave at run time.

To tell AcuConnect where to find this file in a distributed processing environment, you must specify its full path using the ACUCONNECT_RUNTIME_FLAGS variable in the client configuration file, client.cfg.

Because the remote application is run using an ACUCOBOL-GT runtime, you can use any runtime configuration file variable described in the ACUCOBOL-GT User's Guide. The following variables are significant for the distributed processing environment:

Name | Default value
AGS_MAX_SEND_SIZE | 16000
AGS_RECEIVE_BUFFER_SIZE | 16384
AGS_SEND_BUFFER_SIZE | 16384
AGS_SOCKET_COMPRESS | NONE
AGS_SOCKET_ENCRYPT | 0
AGS_TCP_NODELAY | TRUE

Runtime configuration files have a similar function in a thin client environment. The file is stored on the server along with the application, and its name is specified in a server alias file that you establish when first setting up the system. See Creating a Server Alias File in Thin Client for more information.

In addition to the variables in the previous table, the following variables are important for a thin client environment:

Name | Default value
FREEZE_AX_EVENTS | 1
UPDATE_FAILED_MESSAGE | ACUCOBOL-GT Thin Client: Automatic update was unsuccessful
TC_AUTO_UPDATE_FAILED_TITLE | ACUCOBOL-GT Thin Client
TC_AUTO_UPDATE_NOTIFY_FAIL | TRUE
TC_AUTO_UPDATE_QUERY | 1
TC_AUTO_UPDATE_QUERY_MESSAGE | See Informing the User When an Update Is Needed.
TC_AUTO_UPDATE_QUERY_TITLE | ACUCOBOL-GT Thin Client
TC_AX_EVENT_LIST | undefined
TC_CHECK_ALIVE_INTERVAL | 300
TC_CHECK_INSTALLER_TIMESTAMP | 0
TC_CONTINUITY_WINDOW | 0
TC_CONTROL_SYNC_LEVEL | 1
TC_DELAY_ACTIVATE | 1
TC_DELAY_PRE_EVENT_OPS | 0
TC_DISABLE_AUTO_UPDATE | 0
TC_DISABLE_SERVER_LOG | FALSE
TC_DOWNLOAD_CANCEL_MESSAGE | Please wait while the download is being cancelled . . .
TC_DOWNLOAD_DESCRIPTION | Downloading installation file . . .
TC_DOWNLOAD_DIALOG | 1
TC_DOWNLOAD_DIALOG_TITLE | ACUCOBOL-GT Thin Client Automatic Update
TC_EVENT_LIST | undefined
TC_EXCLUDE_EVENT_LIST | 0
TC_INSTALLER_ARGS | undefined
TC_INSTALLER_CLIENT_FILE | <APPDATA>\ACUCOBOL-GT\<installer_server_filename>
TC_INSTALLER_RUN_ASYNC | 0
TC_INSTALLER_SERVER_FILE | <runtime_path>\acuthin.msi
TC_INSTALLER_TARGET_DIR | undefined
TC_INSTALLER_UI_LEVEL | DEFAULT
TC_MAP_FILE | undefined
TC_NESTED_AX_EVENTS | 0
TC_QUIT_MODE | -1
TC_REQUIRES_BUILD_NUMBER | 0
TC_RESTRICT_AX_EVENTS | 0
TC_SERVER_LOG_FILE | autoupdate.%c.%p.log
TC_SERVER_TIMEOUT | 20
TC_TV_SELCHANGING | 1
THIN_CLIENT_ENCRYPT | 0
  • AGS_MAX_SEND_SIZE
  • AGS_RECEIVE_BUFFER_SIZE
  • AGS_SEND_BUFFER_SIZE
  • AGS_SOCKET_COMPRESS
  • AGS_SOCKET_ENCRYPT
  • AGS_TCP_NODELAY
  • ENCRYPTION_SEED
  • FREEZE_AX_EVENTS
  • TC_AUTO_UPDATE_FAILED_MESSAGE
  • TC_AUTO_UPDATE_FAILED_TITLE
  • TC_AUTO_UPDATE_NOTIFY_FAIL
  • TC_AUTO_UPDATE_QUERY
  • TC_AUTO_UPDATE_QUERY_MESSAGE
  • TC_AUTO_UPDATE_QUERY_TITLE
  • TC_AX_EVENT_LIST
  • TC_CHECK_ALIVE_INTERVAL
  • TC_CHECK_INSTALLER_TIMESTAMP
  • TC_CONTINUITY_WINDOW
  • TC_CONTROL_SYNC_LEVEL
  • TC_DELAY_ACTIVATE
  • TC_DELAY_PRE_EVENT_OPS
  • TC_DISABLE_AUTO_UPDATE
  • TC_DISABLE_SERVER_LOG
  • TC_DOWNLOAD_CANCEL_MESSAGE
  • TC_DOWNLOAD_DESCRIPTION
  • TC_DOWNLOAD_DIALOG
  • TC_DOWNLOAD_DIALOG_TITLE
  • TC_EVENT_LIST
  • TC_EXCLUDE_EVENT_LIST
  • TC_INSTALLER_ARGS
  • TC_INSTALLER_CLIENT_FILE
  • TC_INSTALLER_RUN_ASYNC
  • TC_INSTALLER_SERVER_FILE
  • TC_INSTALLER_TARGET_DIR
  • TC_INSTALLER_UI_LEVEL
  • TC_MAP_FILE
  • TC_NESTED_AX_EVENTS
  • TC_QUIT_MODE
  • TC_REQUIRES_BUILD_NUMBER
  • TC_RESTRICT_AX_EVENTS
  • TC_SERVER_LOG_FILE
  • TC_SERVER_TIMEOUT
  • TC_TV_SELCHANGING
  • THIN_CLIENT_ENCRYPT
Parent topic: Server Configuration


AGS_MAX_SEND_SIZE

This variable lets you tune socket performance by determining the maximum size of each data packet sent across the network. The default value is "16000".

See Buffer Size Considerations for tips on how to use this variable in a thin client environment.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


AGS_RECEIVE_BUFFER_SIZE

This variable helps you tune one element of low-level socket communication between a client and server. AGS_RECEIVE_BUFFER_SIZE controls the size of the low-level receive buffer. The variable must be set before the creation of any sockets. The default value is "16384".

Note that because ACUCOBOL-GT does not control this buffer, changes in its value are not displayed in response to a U debugger command to list runtime memory usage.

Changes to the default value may have little, if any, noticeable effect. The default value is probably adequate in most situations. See Buffer Size Considerations for tips on how to use this variable in a thin client environment.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


AGS_SEND_BUFFER_SIZE

This variable helps you tune one element of low-level socket communication between a client and server. AGS_SEND_BUFFER_SIZE controls the size of the low-level send buffer. The variable must be set before the creation of any sockets. The default value is "16384".

Note that because ACUCOBOL-GT does not control this buffer, changes in its value are not displayed in response to a U debugger command to list runtime memory usage.

Changes to the default value may have little, if any, noticeable effect. The default value is probably adequate in most situations. See Buffer Size Considerations for tips on how to use this variable in a thin client environment.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


AGS_SOCKET_COMPRESS

This variable controls data compression by the internal socket layer. Setting this variable to "ZLIB" means that data is compressed using the same algorithm as the gzip compression utility. A value of "RUNLENGTH" means that a simple compression based on counting repeated bytes of data is performed. RUNLENGTH compression tends to be faster than ZLIB compression, but tends not to compress as well, especially with large blocks of data. The default value for this variable is "NONE".

AGS_SOCKET_COMPRESS must be set before any socket communication is performed, and it cannot be changed via the SET ENVIRONMENT statement.

See File Compression for tips on how to use this variable in a thin client environment.

Note that Windows supports ZLIB compression, but not all UNIX machines do. If ZLIB compression is not supported on a particular machine, a variable value of "ZLIB" will be ignored. When the system must negotiate the compression algorithm to be used with a server, the method that both machines support is used.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


AGS_SOCKET_ENCRYPT

The AGS_SOCKET_ENCRYPT variable lets you encrypt any data passed over a socket. Set this variable to "1" (on, true, yes) if you want the internal socket layer to perform encryption. The default value is "0".

You must set this variable before any socket communication occurs, and you cannot change it via the SET ENVIRONMENT statement.

Note that if the THIN_CLIENT_ENCRYPT variable is set to "1", AGS_SOCKET_ENCRYPT is also set to "1". You can still use the ENCRYPTION_SEED configuration variable with AGS_SOCKET_ENCRYPT.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


AGS_TCP_NODELAY

This variable helps you tune one element of low-level socket communication between a client and server. The setting of AGS_TCP_NODELAY determines whether the Nagle algorithm is used to affect the frequency of socket communication. The Nagle algorithm is a method by which the transmission of small socket packets is briefly delayed so several can be sent at the same time. Setting this variable to "false" causes the algorithm to be used.

The default value is "true", which results in immediate individual packet transmissions. The default value is probably adequate in most situations.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


ENCRYPTION_SEED

The value of this variable initializes the encryption algorithm. You can change the default value of this variable to any text string of your choice. Note that AGS_SOCKET_ENCRYPT must be set to "true" for this variable to have an effect. It is not required for encryption to be enabled.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


FREEZE_AX_EVENTS

This variable applies only in a thin client environment. During the processing of an ActiveX event, the Windows and thin client runtimes attempt to suspend subsequent ActiveX events until the first event has completed. By default, the thin client runtime also attempts to suspend ActiveX events whenever the application is not processing an ACCEPT statement. To suspend and resume events, the runtime calls the ActiveX function IOleControl::FreezeEvents().

You might want to disable calls to FreezeEvents() for ActiveX controls that discard events while in a FreezeEvents() state. For example, if a user double-clicks in an ActiveX control, the control might generate three events: mouse-down, mouse-up, and double-click. If the COBOL program terminates an ACCEPT statement in response to the mouse-down event, the runtime calls FreezeEvents(), and the ActiveX control might discard the mouse-up and double-click events.

You can disable the FreezeEvents() logic by setting the FREEZE_AX_EVENTS runtime configuration variable to "0" (off, false, no) in the configuration file or programmatically with the SET verb. The default value of FREEZE_AX_EVENTS is "1" (on, true, yes).

When this variable is set to "0", the setting of TC_RESTRICT_AX_EVENTS is ignored.

Note: The FreezeEvents() logic protects against unexpected nesting of ActiveX events and against event procedures running unexpectedly during a CREATE, DISPLAY, MODIFY, INQUIRE, or other operation that waits for results from the thin client. Turning this feature off can cause unexpected behavior.
Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_AUTO_UPDATE_FAILED_MESSAGE

This configuration variable applies only to the thin client automatic update feature. If this process fails, the following message appears:

ACUCOBOL-GT Thin Client: Automatic update was unsuccessful

You can use the TC_AUTO_UPDATE_FAILED_MESSAGE configuration variable to change the text of this message.

See Automatic Update Failure for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_AUTO_UPDATE_FAILED_TITLE

This configuration variable applies only to the thin client automatic update feature. If this process fails, the message specified either by default or by the TC_AUTO_UPDATE_FAILED_MESSAGE configuration variable appears with the following in the title bar:

ACUCOBOL-GT Thin Client

You can use the TC_AUTO_UPDATE_FAILED_TITLE configuration variable to change this title bar text.

See Automatic Update Failure for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_AUTO_UPDATE_NOTIFY_FAIL

This configuration variable applies only to the thin client automatic update feature. If this process fails, a message appears informing the user of the failure. In some cases, you may not want the thin client to inform the user that the automatic update failed. If you don't want this message to appear, set the TC_AUTO_UPDATE_NOTIFY_FAIL configuration variable to "false" (0, off, no). The default value of this variable is "true" (1, on, yes).

Note that the message box does not appear if the user cancels the Windows installer download process.

See Automatic Update Failure for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_AUTO_UPDATE_QUERY

This configuration variable applies only to the thin client automatic update feature. When an event triggers the update process, the thin client displays a message box informing the user that an update is required. The default setting of "1" (on, true, yes) for the TC_AUTO_UPDATE_QUERY configuration variable enables the display of that message box. Setting this variable to "0" (off, false, no) prevents the message box from appearing.

See Informing the User When an Update Is Needed for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_AUTO_UPDATE_QUERY_MESSAGE

This configuration variable applies only to the thin client automatic update feature. When an event triggers the update process, the thin client displays a message box informing the user that an update is required. The value of the TC_AUTO_UPDATE_QUERY_MESSAGE configuration variable determines the message displayed in that message box. The default value of the variable depends on the circumstances that triggered the automatic update. For example, if the automatic update is initiated by a version or protocol number mismatch, the default message displayed is the following:

Incompatible server version
Server version: <srvvers>, client <clntvers>
Server protocol: <srvproto>, client <clntproto>
Press OK to automatically correct this problem

where <srvvers>, <clntvers>, <srvproto>, and <clntproto> are replaced by the server version, client version, server protocol number, and client protocol number, respectively.

See Informing the User When an Update Is Needed for more information about this variable, including other default values.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_AUTO_UPDATE_QUERY_TITLE

This configuration variable applies only to the thin client automatic update feature. When an event triggers the update process, the thin client displays a message box informing the user that an update is required. You use the TC_AUTO_UPDATE_QUERY_TITLE configuration variable to specify the title bar text in that message box. The default value of this variable is

ACUCOBOL-GT Thin Client

See Informing the User When an Update Is Needed for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_AX_EVENT_LIST

This configuration variable applies only in a thin client environment. TC_AX_EVENT_LIST lets you control which events your program receives, giving you more control over the rate of network traffic. It contains the numeric value of a single .NET or ActiveX event type or a list of .NET or ActiveX event types separated by non-numeric characters like spaces or commas. Whether your program receives these events depends on the value of TC_EXCLUDE_EVENT_LIST. If its value is "0", your program receives the events listed in TC_AX_EVENT_LIST. If the value of TC_EXCLUDE_EVENT_LIST is "1", the events listed in TC_AX_EVENT_LIST are not sent to your program. Note that this variable must be set in the configuration file and cannot be changed programmatically via the SET statement.

An AX-EVENT-LIST common control property performs the same function as this configuration variable. See Graphical Control Event Handling for more information.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_CHECK_ALIVE_INTERVAL

This variable applies only in a thin client environment. Use it to specify how long the runtime should wait (in seconds) for an inactive client (a "dead" acuthin) before exiting the server runtime process. If you enter a value of "60", the runtime checks for client activity for 60 seconds. Client activity includes regular client user interaction or "ping" messages sent automatically from the client to the server. If no client activity is detected during the specified interval, the server runtime process exits. Valid values range from 1 to 32767. Set this variable to "0" to disable client checking. The default value is "300" (5 minutes).

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_CHECK_INSTALLER_TIMESTAMP

This configuration variable applies only to the thin client automatic update feature. The value of TC_CHECK_INSTALLER_TIMESTAMP determines whether the thin client compares the modification times of the installer files on the client and on the server. If this variable is set to "1" (on, true, yes), and the modification time of the client file is older than the time of the server file, the automatic update process is initiated. If the installer file does not exist on the client, the comparison is made with the modification time of the thin client executable file (acuthin) currently running. The default value for this variable is "0" (off, false, no).

See Automatic Update Overview for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_CONTINUITY_WINDOW

This variable applies only in a thin client environment. TC_CONTINUITY_WINDOW can ensure that a given application does not lose focus in Windows 2000 and Windows XP clients because the application has destroyed all of its windows. Setting TC_CONTINUITY_WINDOW to "1" (on, true, yes) causes the thin client to create an invisible, independent window, which ensures that your application maintains focus. The default value is "0".

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_CONTROL_SYNC_LEVEL

This variable applies only in a thin client environment. TC_CONTROL_SYNC_LEVEL lets you control which VALUE data items are updated after an embedded procedure is executed. The setting of this variable can affect performance.

Setting | Effect
1 (the default) | Only the VALUE data item associated with the current field is updated when its AFTER or EXCEPTION procedure executes.
2 | Only the VALUE data item associated with the current field is updated when its BEFORE, AFTER, or EXCEPTION procedure executes.
3 | All VALUE data items are updated when any BEFORE, AFTER, or EXCEPTION procedure executes. Note that this setting affects only BEFORE, AFTER, and EXCEPTION procedures. Values of all variables are made current any time an ACCEPT terminates.

For best performance, set this variable to the default of "1". You can directly INQUIRE the value of a control in an embedded procedure if necessary.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_DELAY_ACTIVATE

This variable applies only in a thin client environment. TC_DELAY_ACTIVATE lets you control whether the thin client delays sending a CMD-ACTIVATE event to the server until after the Windows notification that caused the event is complete. Note that ActiveX events are never delayed, regardless of the setting of this variable. The default value of "1" (on, true, yes) enables this behavior. Setting TC_DELAY_ACTIVATE to "0" (off, false, no) turns off the delay mechanism.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_DELAY_PRE_EVENT_OPS

This variable applies only in a thin client environment. Using this configuration variable, you can direct the thin client to buffer some requests received from the server and process them later. When you set this variable to "1", the thin client buffers the requests received between the time that the client sends an event to the server and the time that the server informs the client that it has started the related event procedure. The events are processed only after the event procedure starts to prevent the thin client from processing requests that generate more events before the first event procedure has started. The default value of TC_DELAY_PRE_EVENT_OPS is "0".

Note: The buffering behavior described for this configuration variable was introduced as the default behavior in Version 6.1. Beginning with Version 7.2, the buffering behavior is turned off by default.
Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_DISABLE_AUTO_UPDATE

This configuration variable applies only to the thin client automatic update feature. You can disable the automatic update process by setting the TC_DISABLE_AUTO_UPDATE configuration variable to "1" (on, true, yes). The default value of this variable is "0" (off, false, no).

See Enabling or Disabling the Automatic Update Feature for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_DISABLE_SERVER_LOG

This configuration variable applies only to the thin client automatic update feature. If this process fails, a log file may be created on the server. This file contains a log of the update operations and details about the failure. To prevent the creation of this log file, set the TC_DISABLE_SERVER_LOG configuration variable to "true" (1, on, yes). The default value of this variable is "false" (0, off, no).

See Automatic Update Failure for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_DOWNLOAD_CANCEL_MESSAGE

This configuration variable applies only to the thin client automatic update feature. During the automatic update installer file download process, a progress dialog appears. You can cancel the download at any time from this dialog. The Cancel push button is disabled immediately after the user clicks it, the description line in the middle of the dialog box disappears, and the message specified in this configuration variable appears. The default value for this variable is

Please wait while the download is being cancelled . . .

See Download Progress Dialog Box for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_DOWNLOAD_DESCRIPTION

This configuration variable applies only to the thin client automatic update feature. During the automatic update installer file download process, a progress dialog appears. You use the TC_DOWNLOAD_DESCRIPTION configuration variable to specify the text that appears in the middle of the download progress dialog. Its default value is

Downloading installation file. . .

See Download Progress Dialog Box for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_DOWNLOAD_DIALOG

This configuration variable applies only to the thin client automatic update feature. During the automatic update installer file download process, a progress dialog box appears. The default value of "1" (on, true, yes) for the TC_DOWNLOAD_DIALOG configuration variable allows the appearance of this dialog box. If you set this variable to "0" (off, false, no), the progress dialog box does not appear.

See Download Progress Dialog Box for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_DOWNLOAD_DIALOG_TITLE

This configuration variable applies only to the thin client automatic update feature. During the automatic update installer file download process, a progress dialog appears. You use the TC_DOWNLOAD_DIALOG_TITLE configuration variable to specify the title bar text in this dialog. The default value of this variable is

ACUCOBOL-GT Thin Client Automatic Update
Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_EVENT_LIST

This variable applies only in a thin client environment. TC_EVENT_LIST lets you control which events your program receives, giving you more control over the rate of network traffic. It contains the numeric value of a single event type or a list of event types separated by non-numeric characters like spaces or commas. Whether your program receives these events depends on the value of TC_EXCLUDE_EVENT_LIST; if its value is "0", your program receives the events listed in TC_EVENT_LIST. If the value of TC_EXCLUDE_EVENT_LIST is "1", the events listed in TC_EVENT_LIST are not sent to your program. Note that this variable must be set in the configuration file and cannot be changed programmatically via the SET statement.

An EVENT-LIST common control property performs the same function as this configuration variable. See Graphical Control Event Handling for more information.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_EXCLUDE_EVENT_LIST

This variable applies only in a thin client environment. The value of TC_EXCLUDE_EVENT_LIST determines whether the events listed in TC_AX_EVENT_LIST or TC_EVENT_LIST are sent to your program. A value of "1" means the specified events are not sent to your program. The default value is "0". Note that this variable must be set in the configuration file and cannot be changed programmatically via the SET statement.

An EXCLUDE-EVENT-LIST common control property performs the same function as this configuration variable. See Graphical Control Event Handling for more information.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_INSTALLER_ARGS

This configuration variable applies only to the thin client automatic update feature. The thin client uses the value of the TC_INSTALLER_ARGS configuration variable as the command-line options passed to the installer executable. For example, if you want msiexec.exe to log all of its operations to a file named msi.log, you could set TC_INSTALLER_ARGS to "/log msi.log". TC_INSTALLER_ARGS has no default value.

See Accepting the Automatic Update for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_INSTALLER_CLIENT_FILE

This configuration variable applies only to the thin client automatic update feature. You use the TC_INSTALLER_CLIENT_FILE configuration variable to specify the path and file name of the installer file that you want to create on the client. The default value of this variable is

<APPDATA>\ACUCOBOL-GT\<installer_server_filename>

where <"APPDATA"> is a special directory name for C:\Documents and Settings\<user>\Application Data.

See Accepting the Automatic Update for more information about this variable and special directory names like <APPDATA>.

Note: If TC_INSTALLER_CLIENT_FILE is set to a non-existent directory or to one on which the autoupdate process doesn't have sufficient permissions, no log file is written if the autoupdate process fails.
Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_INSTALLER_RUN_ASYNC

This configuration variable applies only to the thin client automatic update feature. You use the TC_INSTALLER_RUN_ASYNC configuration variable when you want to prevent the thin client from restarting after an automatic update, or when your installer file handles the automatic update process to completion. When you set this variable to "1" (on, true, yes), the thin client starts the installer process asynchronously and then exits immediately. It does not wait for the automatic update process to complete and does not restart the application. The default value is "0" (off, false, no).

See Accepting the Automatic Update for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_INSTALLER_SERVER_FILE

This configuration variable applies only to the thin client automatic update feature. You set the TC_INSTALLER_SERVER_FILE configuration variable to the path and file name of the server installer file. Its default value is

<runtime_path>/acuthin.msi

where <runtime_path> is the directory that contains the wrun32 or runcbl runtime executable.

See Accepting the Automatic Update for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_INSTALLER_TARGET_DIR

This configuration variable applies only to the thin client automatic update feature. You use the TC_INSTALLER_TARGET_DIR configuration variable to specify the location where you want the updated thin client to be installed. This variable has no default value.

See Accepting the Automatic Update for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_INSTALLER_UI_LEVEL

This configuration variable applies only to the thin client automatic update feature. The keywords or numeric values in the TC_INSTALLER_UI_LEVEL configuration variable control the Windows installer interface.

TC_INSTALLER_UI_LEVEL setting | Result
NONE or "0" | Windows installer does not display a user interface.
UNATTENDED or "1" | Windows installer displays informational and progress messages, but executes unattended.
INTERACTIVE, DEFAULT, or "2" | Windows installer prompts for and accepts user input for the installation process.
REDUCED or "3" | Results in a reduced user interface.

See Accepting the Automatic Update for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_MAP_FILE

This variable applies only in a thin client environment. Use this variable to define the name and path of the map file to be used (if any) to map special characters in your client character set to their decimal or hexadecimal equivalent on the server. This file lets you reconcile the character encoding between two machines that use different codes for the same characters and is particularly useful for international character translation. Note that only single-byte alphanumeric characters are mapped. See International Character Handling for more information.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_NESTED_AX_EVENTS

This variable applies only in a thin client environment. TC_NESTED_AX_EVENTS allows you to control whether the runtime processes subsequent ActiveX events while it is already processing an ActiveX event from the same control. Setting this variable to "1" enables this behavior. The default value is "0".

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_QUIT_MODE

This variable applies only in a thin client environment. TC_QUIT_MODE lets you control how your COBOL application shuts down when no client activity occurs during the interval defined by TC_CHECK_ALIVE_INTERVAL. Setting TC_QUIT_MODE to "1" (the default value) shuts your program down according to the value chosen for the QUIT_MODE configuration variable. (For information about this variable, see the appendix Configuration Variables in your ACUCOBOL-GT Appendices.) If you set this variable to "0", the runtime stops the program immediately. When this variable is set to a value greater than "0" (up to "32767"), your application has a program-controlled exit.

When the runtime determines that the thin client is no longer responding (no user interaction and no pings during TC_CHECK_ALIVE_INTERVAL), the MSG-MENU-INPUT event is sent to the program's main window and EVENT-DATA-2 contains the value defined by TC_QUIT_MODE. Your program can detect this in the main window's event procedure and you can perform whatever code you desire. At this point, there is no connection to the thin client, so user interface operations may not be performed. You must end your shutdown code with "STOP RUN" to terminate the runtime.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_REQUIRES_BUILD_NUMBER

This configuration variable applies only to the thin client automatic update feature. When the thin client executes, it compares its build number with the value of the TC_REQUIRES_BUILD_NUMBER configuration variable. If the value of this variable does not match the client's build number, the automatic update process is initiated. Set this variable to the thin client build number required by the application. The default value of this variable is "0" (off, false, no).

See Automatic Update Overview for more information about this variable.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_RESTRICT_AX_EVENTS

This variable applies only in a thin client environment. The thin client runtime suspends all ActiveX events when the application is not processing an ACCEPT statement. However, some ActiveX controls do not support the ability to suspend and resume events. As a result, in a thin client environment, an event procedure may run unexpectedly during a CREATE, DISPLAY, MODIFY, INQUIRE, or any other operation that waits for results from the thin client.

With the TC_RESTRICT_AX_EVENTS configuration variable, you can control whether your application ignores all ActiveX events between the termination of one ACCEPT statement and the beginning of another. Set this variable to "1" (on, true, yes) to enable this behavior. The default value for this variable is "0" (off, false, no).

To determine if a particular ActiveX control supports suspending and resuming events, check the control's documentation or ask the control vendor. Note that to support suspending and resuming events, the control must implement the "IOleControl::FreezeEvents()" method.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_SERVER_LOG_FILE

This configuration variable applies only to the thin client automatic update feature. If the automatic update process fails for any reason, a log file may be created on the server. This file contains a log of the update operations and details about the failure. The TC_SERVER_LOG_FILE configuration variable can be used to configure the location and name of that log file. The name can optionally include the hostname of the client machine and the process ID of the server runtime that was managing the automatic update at the time of the failure.

By default, this file is named autoupdate.%c.%p.log, where %c is replaced by the client hostname and %p is replaced by the process ID of the server runtime. The default location is the working directory specified in the alias on the server. Note that the directory must exist at the time of the failure for the log file to be created.

The location of the log file is relative to the working directory specified in the alias. For example, the following setting:

TC_SERVER_LOG_FILE  updatefailed/%c.%p.log

configures the log files to be created in a directory named updatefailed relative to the working directory. The default location is the working directory specified in the alias on the server. The files are named with the hostname of the client followed by a dot and the process ID of the server runtime, ending with the .log file extension.

The client and server may be in different time zones. You can look at the file's creation date to see what time the update failed according to the clock on the server, and view the timestamps at the beginning of the lines in the log file to see what time it failed according to the clock on the client.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_SERVER_TIMEOUT

This variable applies only in a thin client environment. TC_SERVER_TIMEOUT lets you determine how many seconds (from 0 to 32767) the client waits for a response from the server. If the client receives no response from the server in the specified time period, the following message box appears:

The remote host is not responding.
Press OK to close this program.
Press Cancel to wait another %s seconds.

where %s is the value of TC_SERVER_TIMEOUT. The default value is "20".

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


TC_TV_SELCHANGING

This variable applies only in a thin client environment. The TC_TV_SELCHANGING variable lets you control how often Msg-Tv-Selchanging events are generated in the thin client environment.

Setting | Result
0 | The Msg-Tv-Selchanging event is never generated.
1 (the default) | A Msg-Tv-Selchanging event is generated only when a tree view selection is changed.
3 | Msg-Tv-Selchanging is always generated.

See Control Events in ACUCOBOL-GT User Inrterface Programming for more information on Msg-Tv-Selchanging.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


THIN_CLIENT_ENCRYPT

This variable applies only in a thin client environment. Use of this variable is superseded by the AGS_SOCKET_ENCRYPT configuration variable. Setting THIN_CLIENT_ENCRYPT to "1" means that AGS_SOCKET_ENCRYPT is automatically set to "1". See AGS_SOCKET_ENCRYPT if you want to encrypt your data.

Parent topic: Creating a Runtime Configuration File for the Remote Server Component


Preparing Your Application

  • Designing Your Application
  • Distribution Considerations
  • Distributed Processing Application Design
  • Thin Client Application Design
  • International Character Handling
Parent topic: AcuConnect Version 10.2.0 User's Guide


Designing Your Application

AcuConnect® is a client/server technology that lets you distribute your computing processes in the way that best suits your business needs. How you design your application for use with AcuConnect can affect system performance and efficiency.

Whether you choose the distributed processing model or use our thin client technology with AcuConnect, you will want to give some serious thought to your application design. Some issues for consideration are covered in Distribution Considerations.

  • In Distributed Processing
  • With AcuConnect's Thin Client Technology
Parent topic: Preparing Your Application


In Distributed Processing

To prepare your application for use in a distributed processing environment, you need to divide the application into two main components: a client component and a server component. If you are developing a new application, you can consider the division during the design stage of development. If you are modifying an existing application for use in a distributed processing environment, you need to find a logical division point.

With distributed processing, your client application should not only contain the user interface portion of the program, but also all of the interactive components. The server application, on the other hand, should be reserved for batch processing components (components that do not require user interaction).

How much processing is performed on the client and how much on the server is totally up to you. With AcuConnect's distributed processing capabilities, you can distribute the workload for maximum throughput. Be sure to consider such issues as network I/O, performance, and security when designing your application distribution.

If you change the location of your server application, all you need to do is change the CODE_PREFIX setting or the code alias definition in the client configuration file (for example, client.cfg). If you want to be able to access your application on multiple machines, you can install the server component in several locations, and then modify client.cfg on an as-needed basis. See Distributed Processing Application Design for more information on the design of a distributed processing application.

Parent topic: Designing Your Application


With AcuConnect's Thin Client Technology

Applications for use in a thin client environment require some preparation as well, even if you already have an ACUCOBOL-GT® program. Remember that with our thin client technology, only the user interface portion of your application resides on a Windows client or display host. Thin client supports all ACUCOBOL-GT control types and classical ACCEPT and DISPLAY. It also allows the use of ActiveX controls, provided the controls are installed on the client machine.

If your ACUCOBOL-GT program is already graphical, full benefits are immediately available in thin client. If your ACUCOBOL-GT program is character-based, you can run it as is and convert to graphical over time using AcuBench®, ACUCOBOL-GT, or the Character-to-GUI Wizard.

If you plan to redeploy Windows applications in a thin client environment, you should be aware that your application will be running on a back-end server rather than the desktop. The client machine provides screen and printing services. Other operating system services are provided by the server. If your program operates on the Windows registry, and the server is not a Windows machine, the registry does not exist. Calls to those library routines return a "not supported" status. See Thin Client Application Design for information about thin client application design issues.

Parent topic: Designing Your Application


Distribution Considerations

AcuConnect allows you to distribute your application components to best use your enterprise resources. You can perform most of your processing on the client (in a "thick" client arrangement), most on the server (in a "thin" client arrangement), or divide the processing equally. The ability to choose between these options or select anything in between makes the AcuConnect client a "smart" client.

Like any paradigm, there are advantages and disadvantages to the thin and thick client approaches. Deciding where to distribute your processing tasks requires extensive knowledge of the network. Your decision should be based on several issues, including:

  • Security — weighing ease of use against system integrity.
  • Performance — scaling client speed versus the speed of the server.
  • Physical location of program and data files, factoring in two-tier versus three-tier applications.
  • Number of users — planning for availability versus contention.
  • Network bandwidth — intranet versus Internet, dial-up versus direct access.
  • User requirements — occasional use versus constant connection, and batch processing versus real-time processing.
  • When to Use a "Thin" Client
  • When to Use a "Thick" Client
  • When to Use a "Smart" Client
Parent topic: Preparing Your Application


When to Use a "Thin" Client

For performance reasons, the "thin" client approach is ideal for data-intensive applications such as reporting. Data-intensive applications typically have a small number of screen I/Os and ACCEPTs, so they can easily be executed on the server to reduce network traffic. The client in this case is "thin," because the server performs the bulk of the application processing.

Our Thin Client technology can be an efficient architecture, with only the user interface portion of your application residing on the client. This model can also be a good choice if you want to develop a graphical user interface for your non-Windows application. In this case, the user interface displays on a Windows machine, while the rest of your application resides on a UNIX, Linux, Windows, or VMS machine.

Parent topic: Distribution Considerations


When to Use a "Thick" Client

The "thick" client approach is suitable for screen-intensive applications with interactive data entry. Such applications would suffer performance degradation if processing were performed on a server and passed across the network. By keeping interactive applications on the client, network traffic can be kept at a minimum.

You might also consider this arrangement if you want your client application to interact with other desktop software using the client's processor.

Parent topic: Distribution Considerations


When to Use a "Smart" Client

In reality, most applications have a combination of screen and data I/O. To maximize performance, you can divide your application into a client component and a server component, splitting the processing responsibilities between the client and the server where you see fit. The "smart" client approach is the foundation of the AcuConnect deployment. AcuConnect lets programmers or systems analysts design enterprise applications so that they use the least amount of network resources and at the same time reduce response time.

Parent topic: Distribution Considerations


Distributed Processing Application Design

Preparing your application for use in a distributed processing environment involves the consideration of several issues. Use of the CALL verb, synchronous or asynchronous program execution, and various memory and environment issues should be explored. The help topics in this section describe these areas of concern.

  • Embedding COBOL CALLs
  • Synchronous or Asynchronous Execution
  • Memory and Environment Issues
Parent topic: Preparing Your Application


Embedding COBOL CALLs

AcuConnect in distributed processing achieves remote application access with standard COBOL CALLs. Just as you would CALL a local application component, you can CALL a remote application component using AcuConnect

For example, if the name of the remote program that you want to invoke is prog2.acu, you embed the following statement into your client application:

CALL "prog2".

If you have not set the ACUCOBOL-GT configuration variable CODE_SUFFIX, the runtime system first attempts to locate an object file called prog2.acu and then an object file called prog2 with no suffix.

Or, if you have added "CODE_SUFFIX obj" to the client.cfg file, the runtime looks only for an object file called prog2.obj on the remote machine.

AcuConnect supports ACUCOBOL-GT's standard usage of the CALL verb, so you could embed:

CALL "prog2" USING {parameter} . . .
CALL "prog2" ON {EXCEPTION}  statement-1.
Note: You can use all forms of CALL documented in the ACUCOBOL-GT Reference Manual with AcuConnect, with the following exception: AcuConnect does not support the use of CALL THREAD, CALL PROGRAM, or CALL RUN to a remote server.

The configuration file on the client, client.cfg, specifies the complete remote path of the CALLed program, so you don't have to specify the path in the application code. This way, you can redistribute the application in your network as often as necessary without changing a single line in your code.

  • Terminating the Remote Application
  • Exception Handling
  • CALLing Multiple Programs
Parent topic: Distributed Processing Application Design


Terminating the Remote Application

By default, AcuConnect leaves the server runtime in memory with an open connection until the client application exits. This allows you to CALL the application as often as necessary without having to restart the server runtime.

If you want to close the connection after a CALL is completed, you must embed a CANCEL or CANCEL ALL in your client program and set the ACUCONNECT_CLOSE_AFTER_CANCEL configuration variable in the client.cfg file. Set to "0", this variable leaves the remote application open until the client application exits. Set to "1", this variable closes the remote application whenever a CANCEL occurs in the program. Note that you cannot set ACUCONNECT_CLOSE_AFTER_CANCEL from within a program. See ACUCONNECT_CLOSE_AFTER_CANCEL for more information on ACUCONNECT_CLOSE_AFTER_CANCEL.

Note: If you make asynchronous CALLs using the C$ASYNCRUN routine, you do not need to embed a CANCEL in your client program. The routine used to check application status, C$ASYNCPOLL, closes the remote application automatically when it receives a "completed" status indicator. See To CALL the C$ASYNCRUN library routine for more infiormation.
Parent topic: Embedding COBOL CALLs


Exception Handling

As is the case with any CALL, if your remotely CALLed program encounters an exception, the program terminates unless you use the "on exception" phrase. You could then use the C$CALLERR routine to find out what went wrong. If an ERRCODE of "25" is returned, it means that the AcuConnect server is not running.

For more information on the "on exception" phrase or the C$CALLERR library routine, see your ACUCOBOL-GT documentation set.

Parent topic: Embedding COBOL CALLs


CALLing Multiple Programs

With AcuConnect in distributed processing, you can start multiple applications on the server at the same time by invoking multiple instances of the runtime.

In addition, programs that have been CALLed using AcuConnect can CALL other programs on the same server as normal, or on a different server using AcuConnect. For example, program 1 on a client machine can CALL program 2 on Server A. In turn, program 2 can CALL program 3 on Server B, and program 3 could even CALL program 4 on Server C, and so on.

To start multiple programs in this fashion, you must design your application components to perform remote CALLs, then provide the necessary configuration files.

When CALLing multiple programs, be aware of the following:

  • If a "second generation" AcuConnect program (such as program 3 on Server B in the example above) requires a password from the first generation program, the password must be supplied using the acu_client_password variable coded into the CALLing program. Otherwise, the authentication will fail, because the first generation AcuConnect program has no way to handle an interactive password screen. See Passwords for more information on using passwords with AcuConnect.
  • Each successive generation of AcuConnect programs can have its configuration file and runtime flags specified by its CALLing program using the ACUCONNECT_RUNTIME_FLAGS variable. See ACUCONNECT_RUNTIME_FLAGS for more information on the ACUCONNECT_RUNTIME_FLAGS variable.
  • Runtime configuration variables are not passed from one program to the next when you use AcuConnect. So, instead of creating code name aliases for all the programs in the client configuration file, you should provide only the variables relevant to the first generation programs you are CALLing. The first generation programs need their own configuration variables to be used in CALLing second generation programs, and so forth.
Parent topic: Embedding COBOL CALLs


Synchronous or Asynchronous Execution

By default, AcuConnect performs synchronous CALLs to remote applications. That is, the client application CALLs the remote application, then waits for a response back from the server. Only when the client receives a response from the server does the client application continue processing.

To perform asynchronous CALLs, you can CALL the C$ASYNCRUN library routine along with the remote application name. This routine is installed during normal AcuConnect installation. More information on C$ASYNCRUN can be found in To CALL the C$ASYNCRUN library routine.

  • CALLing C$ASYNCRUN
  • CALLing C$ASYNCPOLL
Parent topic: Distributed Processing Application Design


CALLing C$ASYNCRUN

If desired, you call the C$ASYNCRUN library routine along with the remote application name to achieve asynchronous processing. The syntax for this CALL is:

CALL "C$ASYNCRUN" using handle-of-call program_name parameter-1
parameter-2

where:

handle-of-call | is a handle of the CALL defined in Working-Storage
program_name | is the name of the CALLed program
parameter | is a parameter of the CALL

For example, you might have the following line in the Working-Storage section of your client program:

01 h-call-prog2     handle.

and the following in the Procedure Division section:

CALL "C$ASYNCRUN" using h-call-prog2 "prog2.acu" customer-info.

C$ASYNCRUN tells AcuConnect to allow the client application to continue processing, even while the server application is active.

Parent topic: Synchronous or Asynchronous Execution


CALLing C$ASYNCPOLL

To check the status of the server program while the client is running, you can call the C$ASYNCPOLL routine. The syntax for this CALL is:

CALL "C$ASYNCPOLL" using handle-of-call state-of-call parameter-1
parameter-2.

where:

handle-of-call | is the handle of the CALL previously run with C$ASYNCRUN
state-of-call | is a PIC s(9) with value "0" if the run is not yet completed, or "1" if the run is completed
parameter | is the parameter of the CALL returned when state-of-call is "1"

For example:

CALL "C$ASYNCPOLL" using h-call-prog2 state-of-call customer-info.

Note that any parameters given in C$ASYNCPOLL must match the parameters given in C$ASYNCRUN. C$ASYNCPOLL tells AcuConnect to query the server about the status of the remote application. AcuConnect returns a status that you can DISPLAY on the client. If the status is "1" (CALL completed), C$ASYNCPOLL terminates the connection with the remote application.

Parent topic: Synchronous or Asynchronous Execution


Memory and Environment Issues

As you design your application for distributed processing, you should be aware of certain memory/environment issues with the ACUCOBOL-GT runtime.

Runtimes

Remotely CALLed programs cause the AcuConnect server to start a new runtime on the server machine. Spawned runtimes can start runtimes on other server machines, if desired, or they can call other programs on the same server.

AcuConnect can spawn Acu4GL® or AcuServer® linked runtimes, even if the client runtime is not so linked.

Memory

The remote program and remote runtime live in memory on the server machine.

Environment

The runtime started by AcuConnect on the server takes on whatever environment that the AcuConnect daemon itself was started in when it was started on the server. For example, if you log on as root and start AcuConnect, AcuConnect will inherit root's environment. If you log on as userX and then start AcuConnect by issuing the superuser account, AcuConnect will inherit userX's environment.

The important thing to note is that the CALLed program does not inherit the client environment of the CALLing program.

Open Connections

The runtime started by AcuConnect on the server in response to a CALL is kept running until a "stop run" is encountered on the client. This has the effect of maintaining any items in memory on the server machine until the client program is shut down.

One exception to this is in the case of asynchronous program execution, when the C$ASYNCPOLL library routine is called. In this case, the runtime on the server is immediately shut down when a status of "1" (CALL completed) is returned by C$ASYNCPOLL.

Another exception is in response to a CANCEL command. See Terminating the Remote Application for more information.

EXTERNAL Data Items

Data items declared as EXTERNAL are not shared between client and remote programs with AcuConnect.

CHAIN Command

The CHAIN command cannot be used to start a remote program through AcuConnect.

Parent topic: Distributed Processing Application Design


Thin Client Application Design

Designing an application for our Thin Client environment presents some unique issues. In addition to user interface design concerns and certain issues with Windows and printing, various technical limitations apply in this model.

Note that if your application is currently in a language other than ACUCOBOL-GT, you must migrate your code to ACUCOBOL-GT before you can implement our Thin Client solution. You can perform the migration yourself, hire Micro Focus's Professional Services Organization (PSO) to do it for you, or work together with Micro Focus's PSO.

No special preparation is needed for your data in a thin client environment. Because your data resides on a server (either the same server as the application or on a different data server) access to that data is the same as it would be in a standard client/server environment using AcuServer or Acu4GL. The server runtime passes the results back to the ACUCOBOL-GT Thin Client for display. If the data resides on the same server as the application runtime, no extra communication software is required.

  • Limitations in Thin Client Environments
  • User Interface Work in Thin Client
  • Other Application Work in Thin Client
Parent topic: Preparing Your Application


Limitations in Thin Client Environments

Note that there are some limitations to running a program with thin client. You may need to make some adjustments to your program if you rely on these features:

  • The SCREEN EDITED-UPDATES=Formatted runtime configuration variable is not supported. Generally speaking, you can continue to run programs that use this feature without changing them. The user will experience a formatting difference while entering data, but the final result should be the same.
  • Creating a graphical component does not move the cursor to the cell to the component's right. This restriction does not affect relative graphical component placement in the Screen Section (for example, "col + 2").
  • The grid control does not generate the MSG-CELL-GOTO-DRAG event. This is done for performance reasons. Because of this, you cannot use the REGION-COLOR property to highlight an area when the mouse is dragged over it. See Grid Control for a description of an alternate technique for doing this.
  • The runtime assumes that graphical components and windows are successfully created in the thin client. If the client runs out of memory, the creation succeeds, but subsequent operation is undefined.
  • The CREATE statement can create only COM and .NET objects on Windows-based servers. See CREATE Statement in the ACUCOBOL-GT Reference Manual for more information.
  • The JUSTIFY_NUM_FIELDS configuration variable is not communicated to the thin client.
  • The C$SETVARIANT library routine and OLE SAFEARRAY data type are supported in thin client environments, regardless of the kind of operating system on the server. The C$GETVARIANT library routine, however, is not supported and returns a negative RESULT-CODE value in thin client environments. To learn more about the C$SETVARIANT routine, refer to the appendix "Library Routines" in ACUCOBOL-GT Appendices.
    Note: You should be careful when using C$SETVARIANT in thin client environments, because it generates network traffic and can affect performance. When using this library routine in a thin client environment, you should pass only small amounts of data.
  • The WIN32_CTL_INPUT_STATUS configuration variable, which affects ACCEPT FROM INPUT STATUS behavior, is not supported in a thin client environment.
  • The thin client environment provides limited support for the SHARED_LIBRARY_LIST configuration variable and the "-y" runtime option. Note that they do not load client-side dynamic link libraries (DLLs) for thin client applications that make calls using the CALL verb "@[DISPLAY]:" syntax. These applications must explicitly load the DLL by calling it with the CALL verb before calling a function within the DLL. For more information about SHARED_LIBRARY_LIST, refer to the appendix "Configuration Variables" in ACUCOBOL-GT Appendices. See Compiler and Runtime in the ACUCOBOL-GT User’s Guide to learn more about the “-y” option.
Parent topic: Thin Client Application Design


User Interface Work in Thin Client

Front-end work is necessary in the following situations:

  • When you want a graphical display and haven't built one yet
  • When the limitations of the character display are unacceptable
  • When your program is highly interactive and you want to deploy it in a wide-area network like the Internet
  • Building a New Graphical Display
  • Working with Character Display Limitations
  • Deploying a Highly Interactive Program in a Wide-area Network
Parent topic: Thin Client Application Design


Building a New Graphical Display

If you want your application to display a full Windows graphical user interface (GUI) on the client, but it is currently character-based, you can develop a GUI using our graphical workbench, AcuBench. ACUCOBOL-GT includes a Character-to-GUI Wizard to assist in this process, and the workbench is designed to automatically use many of the graphical features of ACUCOBOL-GT.

Parent topic: User Interface Work in Thin Client


Working with Character Display Limitations

Because of certain limitations and restrictions, if you deploy a character-based application in our Thin Client configuration, certain display functions will not have the characteristics that you expect. Many will simply display in another fashion. But some unsupported display functions may be ignored. If this is unacceptable to you, you can alter your code to work around the limitations.

Parent topic: User Interface Work in Thin Client


Deploying a Highly Interactive Program in a Wide-area Network

Because highly interactive programs require frequent communication between the client and server, they are not practical for thin client configurations deployed over wide-area networks like the Internet. The more interactive the program, the slower the performance is over slow connections.

If your program was coded with event procedures (handlers), for instance, you should consider removing all but the events that your program really cares about, because event procedures result in frequent "calls" from the UI layer back to the COBOL layer. If your program tracks mouse movements or watches for interactions with controls, you may want to make further modifications. You can choose to redesign the screen or you can just simplify your program's interaction with the screen. The goal is to reduce the number of times that the client and server have to communicate.

Parent topic: User Interface Work in Thin Client


Other Application Work in Thin Client

Other situations require modifications to an application for use in a thin client environment. Issues involving certain Windows features and printing, among others, are described in the help topics in this section.

  • Adjusting for Certain Windows Features
  • Accessing the Windows Registry on the Client Machine
  • Printing in Thin Client
  • Selecting a File from the Client Machine's Drives
  • Using W$BITMAP Print Screen Features
Parent topic: Thin Client Application Design


Adjusting for Certain Windows Features

You may want to adjust your application for the individual Windows characteristics.

Making Direct Calls to the Windows API

Windows applications that contain direct calls to the Windows API must be modified to remove these calls, whether you deploy on a Windows or UNIX server.

Deploying a Windows Application on UNIX

ACUCOBOL-GT is so portable that you can deploy your Windows application on a UNIX server, if you wish. As mentioned earlier, if your application calls Windows API functions directly, you will need to remove these calls. If it relies on DOS file-naming conventions and directory structures, you will need to modify your program with UNIX file names and directories.

Testing the OS-IS-WINDOWS Flag

Some programs that are intended to run under multiple operating systems may test the OS-IS-WINDOWS flag to determine whether a graphical display is available. If your server is not a Windows machine, these programs assume that graphics are not available in thin client. Programs like this should test the HAS-GRAPHICAL-INTERFACE flag rather than OS-IS-WINDOWS. See ACCEPT Statement in the ACUCOBOL-GT Reference Manual for descriptions of ACCEPT FROM SYSTEM-INFO and ACCEPT FROM TERMINAL-INFO.

Accessing Windows Help from a UNIX Application

Your UNIX applications can access Windows help via the ACUCOBOL-GT $WINHELP library routine. Calling $WINHELP from your COBOL program sends the given arguments to the thin client to process. The thin client eventually calls the Windows help program with the arguments given to $WINHELP. Note that the help file is not copied to the client machine, but the client must be able to find this file. In a local office environment, help files can be installed on a local hard drive or a shared drive. Remote users should install the help files on the client machine. (More information about $WINHELP can be found in the appendix "Library Routines" in ACUCOBOL-GT Appendices.)

Using Certain $WINHELP Op-codes

Some $WINHELP op-codes are not supported in a thin client environment. If your application uses them, you may experience unexpected system terminations. These op-codes are

  • HELP_MULTIKEY
  • HELP_SETWINPOS
  • HELP_CONTEXTMENU
  • HELP_SETPOPUP_POS
  • HELP_WM_HELP
Parent topic: Other Application Work in Thin Client


Accessing the Windows Registry on the Client Machine

A set of library routines lets you access and modify the Windows registry on the client machine. The names of the routines all begin with "DISPLAY" to distinguish them from similar routines that operate on the server's registry if the server is Windows. For example, you use DISPLAY_REG_CREATE_KEY or DISPLAY_REG_CREATE_KEY_EX to create a new registry key on the display host. Note that user authorization is required to change the registry with any of the following routines:

  • DISPLAY_REG_CREATE_KEY
  • DISPLAY_REG_SET_VALUE
  • DISPLAY_REG_CREATE_KEY_EX
  • DISPLAY_REG_DELETE_VALUE
  • DISPLAY_REG_SET_VALUE_EX

You authorize or cancel an operation in an authorization dialog.

See Routines to Handle the Windows Registry in ACUCOBOL-GT Appendices for a description of all the DISPLAY Windows registry library routines.

Parent topic: Other Application Work in Thin Client


Printing in Thin Client

Printing in a thin client environment presents unique issues. You may need to modify your application accordingly.

Printing Locally on Windows Machines

If you'd like to allow end users to print locally on their Windows machines, you can add calls to ACUCOBOL-GT's WIN$PRINTER library routine to your program. The thin client environment supports WIN$PRINTER function calls, -P SPOOLER (DIRECT), and -Q printing. (Refer to the Getting Started manual for more information.)

Note that the following WIN$PRINTER functions are not supported by thin client because of variations in memory allocated by data types on the host and the client:

  • WINPRINT_GET_SETTINGS_SIZE
  • WINPRINT_GET_SETTINGS
  • WINPRINT_SET_SETTINGS

Instead of using these functions, you can make calls to WINPRINT_GET_PRINTER_INFO_EX and WINPRINT_SET_PRINTER, which are very similar. (Refer to the appendix "Library Routines" in ACUCOBOL-GT Appendices for more information about these WIN$PRINTER functions.)

Note that if the UNIX server is not an active thin client host when a WIN$PRINTER call is made, WIN$PRINTER returns a "0" (not supported).

Any COBOL logic that disables the WIN$PRINTER capability in non-32-bit Windows environments should be removed to allow Windows client printing to work.

Printing to -P SPOOLER automatically routes the print job to the client printer.

Although it is possible to print directly to the server printer, font selection and formatting capabilities are limited. These restrictions can have an impact on form printing. Send the print job to the client and let the client send the job to the desired printer. Note that the desired printer must be visible to the client.

Parent topic: Other Application Work in Thin Client


Selecting a File from the Client Machine's Drives

A call to the C$OPENSAVEBOX library routine allows you to browse the client machine's drives and select a directory or file. This routine is used in conjunction with other operations that have access to the client machine's drives, such as C$COPY, C$SYSTEM, DLL calls, and COM or ActiveX components. The server machine's file system does not appear in the box.

If your server machine is Windows, you can navigate to the server using Universal Naming Convention (UNC) notation. Set the C$OPENSAVBOX parameter OPNSAV-DEFAULT-DIR to the desired mapped drive or server directory using UNC notation.

Parent topic: Other Application Work in Thin Client


Using W$BITMAP Print Screen Features

Some elements of the W$BITMAP print screen feature deserve special mention in the context of a thin client deployment, particularly the following functions. Full details regarding all W$BITMAP features can be found in the appendix "Library Routines" in ACUCOBOL-GT Appendices.

  • WBITMAP-CAPTURE-IMAGE
  • WBITMAP-CAPTURE-DESKTOP
  • WBITMAP-CAPTURE-CLIPBOARD

WBITMAP-CAPTURE-IMAGE usage is as follows:

CALL "W$BITMAP"
     USING WBITMAP-CAPTURE-IMAGE
     filename
     [window-handle]
     [client]
     [colordepth]
     GIVING [result].

If filename is specified, the image is stored in the named file on the server, not the client machine. For example, with the following code:

CALL "W$BITMAP" USING WBITMAP-CAPTURE-IMAGE   "c:\myfile.bmp".

the bitmap image is stored as myfile.bmp in the c:\ directory on the server. In this example:

CALL "W$BITMAP" USING WBITMAP-CAPTURE-IMAGE "myfile.bmp".

myfile.bmp is stored in the working directory specified in the alias file. If you want the file stored on the client, use the C$COPY library routine to transfer it to the client. See Copying Files Between the Client and Server for more information.

If filename is not specified or is set to a space, the image is placed on the client machine's clipboard.

The setting of "colordepth" is important to consider in a thin client deployment. Because color density is a memory-intensive setting and the image may be transferred over network connections, a combination of high resolution and low bandwidth can have a negative effect on thin client application performance. Consider how the image is being used and set the color density only as high as needed.

The descriptions of filename and "colordepth" in the previous paragraphs also apply to their usage in the WBITMAP-CAPTURE-DESKTOP function of the W$BITMAP library routine.

The WBITMAP-CAPTURE-CLIPBOARD function copies the current bitmap content of the client machine's clipboard. The description of "filename" in the previous paragraphs also applies to its usage in WBITMAP-CAPTURE-CLIPBOARD, except that for this function, filename is mandatory.

Parent topic: Other Application Work in Thin Client


International Character Handling

Often in client/server environments, the client and server machines may use different character encoding, particularly if one machine is set up for foreign language characters that use values outside the ASCII character set (decimal values 128 and higher), or if the client is using a PC character set and the server is using a UNIX character set. This presents a problem when programs or data are passed between the environments, because the characters do not translate directly.

  • In Distributed Processing
  • In Thin Client
Parent topic: Preparing Your Application


In Distributed Processing

If you anticipate passing any items with special characters (such as vowels with a grave accent, acute accent, circumflex, or tilde) during a remote CALL, you should create a map file to reconcile the character encoding for you. You should also consider creating a map file if the client machine uses a different character set from the server machine. The map file should specify which client characters are to be converted to which values before passing the CALL's arguments to the server process or returning information from the server process. The translation on returning data will affect items that were passed to the server process as "BY REFERENCE" (the default).

The map file should re-map only those values that vary between the two character sets. It should contain two values per line: the first indicating the decimal or hexadecimal value of the special character on the client machine, and the second indicating the decimal or hexadecimal value of the corresponding character on the server machine. You can check the values of specific characters by using the Windows Character Map accessory in the PC environment, or by referring to your UNIX man pages in the UNIX environment.

In your character map, hexadecimal values should use the standard "0x" notation. For example:

0x90 0xC9

maps "E" (acute) in the IBM PC character set to "E" (acute) in the ISO8859-1 character set using0x90 0xC9 hexadecimal notation.

144 201

gives the same mapping using decimal notation.

You can use the pound sign (#) to indicate a comment, if desired.

Note that the map will be used to translate only alphanumeric fields, but it will translate all alphanumeric fields, including group items and items subject to a REDEFINES clause. If this is not a desired behavior, you may need to restructure your program to avoid these clauses by passing the elementary items instead of the group item, or passing an item from the REDEFINES clause instead of the first reference.

For example, if you pass the group-name in the following COBOL program:

01 group-name
   03 field-1   pic99 comp-5.
   03 field-2   pic99 comp-5.
call "sun3:/usr/obj/prog2" using group-name.

translation will occur on the elementary numeric items. If these numeric items contain binary data that matches the value of mapped characters, the data will be corrupted. To correct this situation, you could change the CALL statement to:

call "*sun3:/usr/obj/prog2" using field-1, field-2.

Or you could change the definition of the numeric items to a type that will not conflict with potentially mapped characters, as in:

01 group-name
   03 field-1   pic99.
   03 field-2   pic99.

Defined this way, the numbers are stored as the ASCII representation of each digit, which should not conflict with any character mapping.

Once the map file is created, you place it on the client, or if the client is AcuServer-enabled, you can place it on the client or server. Either way, you specify the location of the map file using the DEFAULT_MAP_FILE or server_MAP_FILE variable in the client configuration file (for example, client.cfg). See Other Variables for more information on using these variables.

Parent topic: International Character Handling


In Thin Client

International character handling in thin client is similar to that in distributed processing. You create a simple text file that contains the mapping of characters that may be different on the client than on the server. Include only the character codes that differ between the two machines.

After you create your map file, you need to point to it using a runtime configuration variable. For a thin client environment, this variable is called TC_MAP_FILE. Character mapping is triggered by the presence of the TC_MAP_FILE variable.

You need to be sure that the configuration file that contains this variable is referenced in the program's alias definition. See Creating a Server Alias File in Thin Client for information about the thin client alias file.

Parent topic: International Character Handling


Preparing the Client(s) in Distributed Processing

  • Installing the ACUCOBOL-GT Runtime
  • Creating a Client Configuration File
  • Installing Client Programs
  • Executing Programs on the Client
  • Sample Programs
  • Running the Sample Programs
Parent topic: AcuConnect Version 10.2.0 User's Guide


Relinking the Client Runtime

No relinking is necessary to use AcuConnect. The regular runtime distributed by Micro Focus can call an AcuConnect server program. See Working with C and C++ Programs in A Guide to Interoperating with Micro Focus if you need special extensions for which you would normally relink the runtime.

Parent topic: Installing the ACUCOBOL-GT Runtime


Removing AcuConnect Client Support from the Runtime

The procedure for removing AcuConnect client support from your runtime varies with your operating system:

  • For Unix, delete the file sub.o from the bin subdirectory, set NO_ACUCONNECT to 1 in config85.c, and run the make command.
  • For Windows, delete the file aclnt.dll from the bin subdirectory.
Parent topic: Installing the ACUCOBOL-GT Runtime


Passwords for Clients

If you are requiring a client password to access the server machine, you can prompt the user for this password and store it in the acu_client_password variable, or you can let the runtime prompt for it.

Parent topic: Installing the ACUCOBOL-GT Runtime


Setting Up the Host Name

The runtime system on each client machine needs to know the name of the server host machine. This is accomplished in the client configuration file, client.cfg. You can either use the CODE_PREFIX variable to define the remote pathname, or you can define code name aliases. Code name aliases are faster, because the runtime does not have to search remote machines. If you use CODE_PREFIX, place the remote paths at the end of the variable. See Defining Remote Application Path for more information.

Parent topic: Installing the ACUCOBOL-GT Runtime


Confirming Network Services

Whether your client is running UNIX or Windows, confirm that your TCP/IP software is loaded and running. On Windows clients, confirm that WSOCK32.DLL is loaded.

Parent topic: Installing the ACUCOBOL-GT Runtime


Creating a Client Configuration File

Once you have installed your client applications on the client(s), you must create a special configuration file that tells AcuConnect the location of the remote application component, the runtime flags to use when running the remote application (if any), and the runtime configuration file to use. This file can be named anything, but for clarity, it is called client.cfg in this manual. The client configuration file should be placed in the /etc or operating system drive:\etc directory on the client or specified using the -c command-line option at runtime.

When AcuConnect is shipped, it includes a sample client.cfg file. If you want to install this sample file on your client machine(s), you may do so. This may be a good starting point for creating and modifying your own file.

The client.cfg file can contain any standard configuration file variable defined in the ACUCOBOL-GT User's Guide (for instance, CODE_SUFFIX, ACUCOBOL, and TEXT). In addition, it can contain any of several AcuConnect-specific variables.

Note: Many of these variables are used to specify the location of remote programs and files. You can use either IP addresses or server names in the client.cfg file.
  • Defining Remote Application Path
  • Other Variables
  • Sample client.cfg File
Parent topic: Preparing the Client(s) in Distributed Processing


Defining Remote Application Path

You can define the pathname of the remote application in the client configuration file in two ways: by using the CODE_PREFIX variable or by defining code name aliases.

  • CODE_PREFIX
  • Code Name Aliases
Parent topic: Creating a Client Configuration File


CODE_PREFIX

If desired, you can use the CODE_PREFIX variable to define the location of the object programs being called. In a distributed processing environment, the CODE_PREFIX variable can be defined as follows:

CODE_PREFIX . /usr/prog1 *servername:/usr/prog2

where prog1 and prog2 are the directories containing the ACUCOBOL-GT object code (for example, prog1.acu and prog2.acu). In this example, whenever the client application tries to access a program's object code, it first looks for the code in the current directory ("."), then in the local /usr/prog1 directory, and finally on the remote application server *servername in the directory /usr/prog2.

Because AcuConnect supports Transmission Control Protocol/Internet Protocol (TCP/IP), it can also be used to launch application processes over the Internet. In an Internet environment, the *servername portion of CODE_PREFIX would be the name of the application server on the Internet.

Notice that the remote server name is preceded by the asterisk (*) character. The asterisk indicates that the program is located on the server and must be run on the server as well.

When the client COBOL program executes a CALL, it verifies which directory contains the program (by looking in CODE_PREFIX), and executes the program either on the client or the server.

Note: When you use CODE_PREFIX to specify the location of your called program, the runtime traverses the specified paths to locate the resource. If you use this method, try to place remote notations toward the end of the file. Generally, you achieve better performance by defining a code name alias, because remote machines do not need to be searched using this method.

This architecture allows most existing COBOL programs to operate in a true distributed processing environment without any code modification. You can simply install AcuConnect and modify the client.cfg file according to your needs. Even the parameter transfer is performed following standard COBOL procedures (the USING clause after the CALL command).

For example, in a standalone environment, CODE_PREFIX could be defined as follows in a Windows system:

CODE_PREFIX c:\prog1;c:\prog2

and as the following in a UNIX system:

CODE_PREFIX /usr/prog1:/usr/prog2
Parent topic: Defining Remote Application Path


Code Name Aliases

If you would rather specify the exact location of your called program (rather than having AcuConnect search through CODE PREFIX for the location), you can define code name aliases, also in the client configuration file. A code name alias is a substitute name for the program that you're calling.

For example, if you have this CALL statement in your application:

CALL "prog2" using customer-info.

You could create the alias "PROG2" in your client configuration file by adding two lines:

PROG2  *servername:/usr/prog2/prog2.acu
CODE_MAPPING 1

The first line creates the alias "PROG2" to represent prog2.acu on the application server in directory /usr/prog2. The second line turns the code alias, and any other code aliases, "on."

With these two lines in the client.cfg file, AcuConnect knows to look on *servername for the remote application when it encounters the CALL.

By using aliases in the client.cfg file, you enable your users to change their configuration file dynamically at run time, and you enable them to improve performance.

Note: To disable code aliases, set CODE_MAPPING to 0. In this case, remote program location is derived from the CODE_PREFIX variable. For more information on the CODE_MAPPING variable, refer to the appendix "Configuration Variables" in ACUCOBOL-GT Appendices.
Parent topic: Defining Remote Application Path


Other Variables

Although the client.cfg file can contain any standard configuration file variable defined in the ACUCOBOL-GT User's Guide, these variables have specific meaning to AcuConnect.

ACUCONNECT_DEBUG_METHOD | Used with ACUCONNECT_DEBUG_METHOD_STRING to control where remote debugging occurs.
ACUCONNECT_DEBUG_METHOD_STRING | Used with ACUCONNECT_DEBUG_METHOD to control where remote debugging occurs.
ACUCONNECT_CLOSE_AFTER_CANCEL | Lets you specify whether the connection to a remote application should remain open or be closed after a CALL is complete.
ACUCONNECT_RUNTIME_FLAGS | Parameters that you would normally put on the runtime command line when starting the remote application, used when the runtime for the remote application executes.
ACUCONNECT_PORT | Specifies a particular port number to be used for accessing AcuConnect on the server host machine.
DEFAULT_MAP_FILE | Defines the name and path of the map file to be used (if any) to map special characters in your client character set to their decimal or hexadecimal equivalent on the server.
server_MAP_FILE | Lets you specify a map file for use with international character translation for use with a specific server. The map file itself can be stored anywhere.
TEXT_nnn | Controls the text of selected AcuConnect messages.
  • ACUCONNECT_DEBUG_METHOD
  • ACUCONNECT_DEBUG_METHOD_STRING
  • ACUCONNECT_CLOSE_AFTER_CANCEL
  • ACUCONNECT_RUNTIME_FLAGS
  • ACURCL_PORT
  • DEFAULT_MAP_FILE
  • server_MAP_FILE
  • TEXT_nnn
Parent topic: Creating a Client Configuration File


ACUCONNECT_DEBUG_METHOD

This configuration variable gives you some control over where remote program debugging occurs. ACUCONNECT_DEBUG_METHOD is undefined by default and may take one of these values: XTERM, TERMINAL, THIN, or THINCLIENT. These settings also determine what values the ACUCONNECT_DEBUG_METHOD_STRING configuration variable takes.

Setting | Result
XTERM | The remote runtime creates an xterm and uses it for interaction with the runtime debugger. ACUCONNECT_DEBUG_METHOD_STRING should be set to the name of the X server to which the xterm is displayed.
TERMINAL | The terminal named in ACUCONNECT_DEBUG_METHOD_STRING is used by the runtime to interact with the user for debugging the remote COBOL program.
THIN or THINCLIENT | The client runtime attempts to start an instance of the thin client with the correct parameters using the client machine name and port number specified in ACUCONNECT_DEBUG_METHOD_STRING.
Parent topic: Other Variables


ACUCONNECT_DEBUG_METHOD_STRING

This configuration variable is used in conjunction with ACUCONNECT_DEBUG_METHOD to control remote program debugging. This variable is undefined by default.

Setting | Result
XTERM | The name of the X server to which the xterm is displayed. If the latter variable is not set, the xterm appears on the X server defined by the A_DISPLAY or DISPLAY environment variable.
TERMINAL | ACUCONNECT_DEBUG_METHOD_STRING must be set to the name of a TTY that is running a runtime started in a special mode (runcbl --wait). The runtime uses the specified terminal to interact with the user for debugging the remote COBOL program.
THIN or THINCLIENT | <client:port>, where client is the name of a Windows machine, and port is the port to which the runtime attempts to connect in order to control a thin client. In this mode, the client runtime attempts to start an instance of the thin client with the correct parameters. For example, if ACUCONNECT_DEBUG_METHOD_STRING is set to "rzack-xp:4444", the client runtime starts acuthin --wait --port 4444. Note that if the client machine is not "rzack-xp," you may have a thin client instance that is not being used.
Parent topic: Other Variables


ACUCONNECT_CLOSE_AFTER_CANCEL

This variable lets you specify whether the connection to a remote application should remain open or be closed after a CALL is complete. Set to the default value of "0" (off, false, no), this variable leaves the remote application open until the client application exits. Set to "1" (on, true, yes), this variable closes the remote application whenever a CANCEL occurs in the client program. For example:

ACUCONNECT_CLOSE_AFTER_CANCEL 1
Parent topic: Other Variables


ACUCONNECT_RUNTIME_FLAGS

ACUCONNECT_RUNTIME_FLAGS are parameters that you would normally put on the runtime command line when starting the remote application. These are used when the runtime for the remote application executes.

For example:

ACUCONNECT_RUNTIME_FLAGS *servername: -le errfile

Any runtime flag documented in the ACUCOBOL-GT User's Guide can be used, except -d. For information on how to run the remote application in debug mode, see the reference topics ACUCONNECT_DEBUG_METHOD and ACUCONNECT_DEBUG_METHOD_STRING.

Note: The server runtime runs in batch mode by default. It is not necessary to include -b in the runtime flags.

ACUCONNECT_RUNTIME_FLAGS also contains the name of the runtime configuration file for the remote application. By default, this file is named cblconfig and is located in the \etc directory in which you installed AcuConnect.

Parent topic: Other Variables


ACURCL_PORT

The ACURCL_PORT variable specifies a particular port number to be used for accessing AcuConnect on the server host machine. This is especially helpful when the server host machine has a security firewall, because firewalls generally allow access only to specific ports. With this variable, the site can ensure that firewall restrictions are satisfied.

The acurcl daemon can work with privileged port numbers (from 0 to 1023) and with non-privileged port numbers (1024 and higher, up to 32767).

The value of this variable is overridden by any port number assigned on the command line (via the -n option) when the daemon is started.

Parent topic: Other Variables


DEFAULT_MAP_FILE

Use this variable to define the name and path of the map file to be used (if any) to map special characters in your client character set to their decimal or hexadecimal equivalent on the server. This file lets you reconcile the character encoding between two machines that use different codes for the same characters. It is particularly useful for international character translation. For example:

DEFAULT_MAP_FILE=c:\etc\pc_iso

See International Character Handling for more information.

If desired, you can keep your map file on a remote machine and access it using AcuServer®. Simply use remote name notation for your DEFAULT_MAP_FILE entry to point to a server that is running the AcuServer daemon. For example:

DEFAULT_MAP_FILE=@sun3:/user/data/pc_iso_map

Note that you are not required to keep your map files on the same remote machine that you are calling with AcuConnect.

Parent topic: Other Variables


server_MAP_FILE

Similar to DEFAULT_MAP_FILE, this configuration variable lets you specify a map file for use with international character translation. However, this variable specifies a map file for use with a specific server. The map file itself can be stored anywhere.

For example, if you include the following statement in your client application:

CALL "prog2" using my-data.

and your client configuration file includes:

CODE_PREFIX *sun3:/usr/obj *sun4:/usr/obj

then:

sun3_MAP_FILE=c:\etc\pc_iso_map

causes the map file pc_iso_map to be applied if prog2 is found and run on sun3 but not on sun4. As with DEFAULT_MAP_FILE, you may use AcuServer® remote name notation to point to a map file residing on a remote server running AcuServer.

Note: You can have only one DEFAULT_MAP_FILE variable specified in the client configuration file, but you can have as many server_MAP_FILE variables as you want.
Parent topic: Other Variables


TEXT_nnn

A set of TEXT configuration variables is used to control the text of selected AcuConnect messages. Three runtime messages support AcuConnect password handling. The default text for each message is as follows:

TEXT_015  "A password is required to connect to host %s."
TEXT_016  "Please enter a password: "
TEXT_017  "Invalid password."

Note that in message 15, the name of the AcuConnect host will be substituted for the %s characters.

To change the text associated with a given message, append an equals sign (=) followed by the new text. For example:

TEXT_016=Enter your password now:

Note that to enable the display of the password messages, you set the PROVIDE_PASSWORD_MESSAGES server configuration variable to "true" (1, on, yes). This variable tells the remote listener to send these messages to the client.

Parent topic: Other Variables


Sample client.cfg File

The following file is included in the sample directory on your AcuConnect installation CD-ROM. You can use this file as a starting point and modify it to suit your needs.

"client.cfg"
# This is a sample configuration file used when starting your program
# on the client.
# You should edit it to match your needs. (See the AcuConnect User's
# Guide).
# Use the "*" notation to point to the cobol object on the server.
code_prefix . *server1:c:\acuconnect\sample.
# Allow code name aliases.  A name alias is a substitute string for the
# literal name that appears in the CALL statement.
#code_mapping 1
#prog2 *server1:c:\acuconnect\sample\prog2.acu
# runtime flags on the server
acuconnect_runtime_flags *server1: -c c:\acuconnect\etc\cblconfig -le
errfile
# action to be taken with the connection to the remote runtime after a
# CANCEL
acuconnect_close_after_cancel 0
# map special characters in client character set to their equivalent
# on server.
#default_map_file c:\etc\pc_iso
Parent topic: Creating a Client Configuration File


Installing Client Programs

The last step in preparing your client for use with AcuConnect in distributed processing is copying the client components of your COBOL application onto the client into the desired directory. If multiple clients will be used to access the server application, then you must install the client application components on each client machine.

Parent topic: Preparing the Client(s) in Distributed Processing


Executing Programs on the Client

After AcuConnect is running on the server, all you have to do to access the remote server application from the client is start the client program. If you have designed your application properly (embedding synchronous or asynchronous CALLs into the client application component, the client program will automatically and seamlessly launch the server application for you. The client configuration file, client.cfg or equivalent, defines the location of the server, along with the runtime flags and configuration file to be used at the server program run time. See Synchronous or Asynchronous Execution for more information.

When starting your client program, you can use any of the runtime options available to a standard ACUCOBOL-GT runtime. If you want to provide AcuConnect trace information for the client, specify -le plus the name of the error file in which to store the data.

  • Executing Non-COBOL Programs on the Client
  • Debugging in a Distributed Processing Environment
Parent topic: Preparing the Client(s) in Distributed Processing


Executing Non-COBOL Programs on the Client

You don't have to have a COBOL object running on the client. AcuConnect can also be used to execute remote COBOL objects from client applications developed in C, C++, Java, .NET, Delphi, or Visual Basic. This relies on the C, Java, and .NET APIs contained in the ACUCOBOL-GT runtime.

Parent topic: Executing Programs on the Client


Debugging in a Distributed Processing Environment

You can interact with the runtime debugger and debug remote programs in two ways.

The first way is to view a debugger window on the server itself: This is accomplished by starting acuconnect with the -d flag, or example:

acuconnect -start -d.

When started with this flag, AcuConnect will run in the foreground. This means that all logging messages will be sent to the console or command line window. On UNIX, only one connection is allowed at a time. On Windows, multiple users can connect simultaneously. When a server runtime is started by AcuConnect, a debugger window will be displayed to the console. On Windows, multiple debugger windows can be opened for multiple connections. The server debugger is a fully functional.

The second way to debug a remote program is to direct the debugger window to be opened on a remote machine with a TTY, an xterm, or the thin client.

If you want to use an xterm, the remote runtime will create an xterm and use it for interaction with the runtime debugger. Alternatively, you can specify the name of a TYY that will be used by the runtime to interact with the debugger. You can also specify a Windows client machine and port number. The client runtime will then start an acuthin instance for interacting with the debugger. See ACUCONNECT_DEBUG_METHOD and ACUCONNECT_DEBUG_METHOD_STRING for specific instructions in implementing these options.

Parent topic: Executing Programs on the Client


Sample Programs

This help section contains sample client and server programs: prog1.cbl, prog2.cbl, and asynch.cbl. By default, these files were placed in your acuconnect/sample directory during installation on the server. These programs are included in the sample directory on your AcuConnect installation media.

prog1.cbl is a client program that performs a synchronous CALL. Notice the CALL statement in the Procedure Division section of this program. This CALL invokes prog2 on the server and displays the result on the client workstation. Remember that the client configuration file (client.cfg, for example) defines the location of the server. In this case, it also defines the CODE_SUFFIX, .acu.

asynch.cbl is a client program that performs an asynchronous CALL. Notice that in the Procedure Division section of this program, a CALL is made to the C$ASYNCRUN library routine using prog2 and some parameters. This tells AcuConnect to allow processing on the client to continue. Notice also that this program later calls the C$ASYNCPOLL routine to check the status of prog2.

Both prog1.cbl and asynch.cbl start prog2 on the server using the same client.cfg file.

After you have prepared your server and client, you can try running prog1.acu and/or asynch.acu on the client to test your AcuConnect connection. See Running the Sample Programs for instructions.

Note: The sample file prog1.acu was compiled with ccbl32 -o @.acu prog1.cbl. prog2.acu was compiled with ccbl32 -o @.acu prog2.cbl.

Parent topic: Preparing the Client(s) in Distributed Processing


Running the Sample Programs

To test your AcuConnect connection between the client and server, you can copy the sample client programs onto the client and try to run them. If the connection succeeds, the server returns a response to the client, and that response displays on the client workstation. The following help topics describe how to run the sample programs in UNIX and Windows.

  • Running the Sample Programs in UNIX
  • Running the Sample Programs in Windows
  • Results
Parent topic: Preparing the Client(s) in Distributed Processing


Running the Sample Programs in UNIX

Follow the procedure below to run the sample programs in UNIX.

  1. Start AcuConnect on the server by going to the server and entering:
    acurcl -start -c acurcl.cfg -e server.err
  2. Copy the programs prog1.acu and asynch.acu from the sample directory on the server to any directory on the client. If you kept the installation defaults, these files can be found in the /AcuConnect/sample directory on the server. You may want to create a new directory on the client to hold the samples.
  3. Start the sample client program by changing to the directory where you installed the programs on the client and entering:
    runcbl -c client.cfg prog1.acu

    to test synchronous CALLs, or:

    runcbl -c client.cfg asynch.acu

    to test asynchronous CALLs.

Parent topic: Running the Sample Programs


Running the Sample Programs in Windows

Follow the procedure below to run the sample programs in Windows.

  1. Start AcuConnect on the server by using the acurcl -start command or by clicking Start on the graphical control panel's Services tab.
  2. Copy the programs prog1.cbl, asynch.cbl, and client.cfg from the sample directory on the server to any directory on the client. If you kept the installation defaults, these files can be found in the %PUBLIC%\Documents\Micro Focus\extend x.x.x\sample\acuconnect\client directory on the server. You may want to create a new directory on the client to hold the samples.
  3. From a command prompt, navigate to the directory that contains the source programs, then compile both sources using the following command:
    ccbl32 <prog-name>.cbl
  4. Again, from the command prompt, to test synchronous CALLs, enter:
    wrun32 -c client.cfg prog1.acu
  5. To test asynchronous CALLs, enter:
    wrun32 -c client.cfg asynch.acu
Parent topic: Running the Sample Programs


Results

Whether you are working in Windows or UNIX, you can expect the same results from the sample programs. If the connection is unsuccessful, you receive an error message. See AcuConnect Distributed Processing Troubleshooting for more information.

Synchronous Sample

When prog1 CALLs prog2, AcuConnect automatically starts prog2 on the server with the runtime flags and configuration file specified in the sample client.cfg file. This is equivalent to typing, wrun32 -b -le prog2.err -c cblconfig prog2.acu on a Windows server or runcbl -b -le prog2.err -c cblconfig prog2.acu on a UNIX server.

If the connection is successful, the following displays on the client:

Number of customers between 35 and 39: 003

Asynchronous Sample

When asynch.acu CALLs prog2, AcuConnect automatically starts prog2 on the server with the runtime flags and configuration file specified in the sample client.cfg file. Since C$ASYNCRUN was called as well, however, AcuConnect allows the client program, asynch.acu, to continue running this time.

If the connection is successful, the following displays on the client:

age-group-count immediately after async call:
Begin sleep for 5
End sleep, call asyncpoll
Number of customers between 35 and 39: 003
Parent topic: Running the Sample Programs


Preparing the Client(s) in Thin Client

  • Preparing the Client
  • Installing the ACUCOBOL-GT Thin Client
  • Installing ActiveX Files
  • Thin Client Splash Screen
  • Launching Remote Programs from the Client
  • Launching Programs on the Internet
  • Using the Client Cache Directory
Parent topic: AcuConnect Version 10.2.0 User's Guide


Preparing the Client

In the AcuConnect Thin Client environment, the client is also known as the display host. This is where screen, mouse, and keyboard handling is performed, but no actual application processing is performed on the client. Unlike servers (or application hosts), which are considered to be "thick," display host clients are "thin" because of their lack of application components and substantive processing work. Thin clients communicate with their application hosts through a split runtime, the thin portion of which is installed on the client.

The following two steps are all you need to do to prepare the client for AcuConnect Thin Client operation:

  1. Install client software.
  2. Run the ACUCOBOL-GT® Thin Client.
Parent topic: Preparing the Client(s) in Thin Client


Installing the ACUCOBOL-GT Thin Client

For in-house installations, the ACUCOBOL-GT Thin Client installation files are included on the product media. A self-extracting installation program ( extend(R) Thin Client Version 10.1.1.exe) can be found in the REDIST directory on either the Windows or the UNIX CD-ROM. In accordance with the applicable license agreement, this file can be distributed within your organization or placed on a shared network drive. Users double-click this file and follow the on-screen instructions to install the thin client. The thin client can also be selected as an installed product from the Windows CD-ROM.

Once it is installed, you can invoke the ACUCOBOL-GT Thin Client from a command line, or you can set up an icon for it. Create an icon for the thin client, specifying command parameters as desired. Command parameters for the thin client are described in The acuthin Command. For information on establishing program icons, refer to your Windows documentation.

You can also download and install the ACUCOBOL-GT Thin Client from the Micro Focus Web site. Click the link for the Micro Focus download page, then click the link for the ACUCOBOL-GT Thin Client. Follow the displayed instructions to download the file. When the download is complete, follow the instructions on the screen to install the thin client.

When you install the thin client from ' extend(R) Thin Client Version 10.1.1.exe' or from the Micro Focus Web site, the system displays the terms and conditions for using the ACUCOBOL-GT Thin Client. You must agree to the terms of this agreement to install or use the thin client.

Note: Microsoft Windows Vista’s UAC mechanism blocks the installation of ActiveX controls, such as ACUCOBOL-GT's Thin Client, onto systems that are not running Internet Explorer 7 in administrator mode. Vista includes an ActiveX installer service that allows IT administrators to use Group Policy to specify Web sites from which standard users will be allowed to install ActiveX controls.
Parent topic: Preparing the Client(s) in Thin Client


Installing ActiveX Files

If the server application uses ActiveX resource files or ActiveX controls, these resources and controls must be installed on the thin client machine before the application can be executed. This is because there is no way to send such resources along with screen commands to the UI layer in a single network message, and if they are sent separately, the UI layer doesn't "know" anything about how to group them into a Screen Section item.

End users can usually install and register ActiveX controls and resources by downloading the controls from the control vendor's Web site and running the accompanying setup program.

For simple controls, end users can usually accomplish installation and registration by downloading or copying the ActiveX control files (at least an .ocx or .dll file) to their hard disk and executing the following command:

regsvr32 <ocx or dll name>

regsvr32.exe is normally located in the \windows\system directory and may not be in the end user's search path. Even if the control is already installed on the machine (for instance, if it came with other software that's been installed), the user may still need to register the control with regsvr32.exe.

Note that the ability to load and destroy ImageList data types used by ActiveX controls is supported in thin client via the W$BITMAP library routine. Information about this function can be found in "library Routines" in ACUCOBOL-GT Appendices.

Parent topic: Preparing the Client(s) in Thin Client


Thin Client Splash Screen

The ACUCOBOL-GT Thin Client displays a splash screen on startup. This screen remains in place until the application's initial window appears. You can disable the splash screen by using the --nosplash option in the acuthin command line. For example:

acuthin --nosplash myserver:5764 myprog

Another method for suppressing the splash screen is to include the following in your .atc or .acutc command file:

 atc_splash_screen off

where "off" can also be "0", "no", or "false".

You can also use a splash screen of your own design. Simply name it acuthinsplash.bmp and place it in the same directory as acuthin.exe.

Parent topic: Preparing the Client(s) in Thin Client


Launching Remote Programs from the Client

Assuming that AcuConnect has been started on the server, you can launch remote server programs from a Windows client by issuing the acuthin command, either on the command line or from an icon. To point the client machine to the remote application host, specify a server name and port number along with an alias name and arguments.

  • The acuthin Command
Parent topic: Preparing the Client(s) in Thin Client


The acuthin Command

The acuthin command parameters can be specified as follows:

acuthin server[:port] [rarg1 [rarg2 . . .]] alias [carg1 [carg2 . . .]]

or

acuthin acurcep://server[:port]/alias[?carg1[&carg2 . . .]]

where:

[ ] | is optional parameters
server | is a server name
port | is a port number
rarg1 | is an argument passed on the runtime command line before the program name
carg1 | is an argument passed on the runtime command line after the program name
acurcep | is ACUCOBOL-GT Remote COBOL Execution Protocol
alias | is an alias that identifies a COBOL application on the server

For example:

acuthin myserver:5633 –d myprog1 10 20 30

or

acuthin acurcep://myserver:5633/myprog1?10&20&30

If you execute the acuthin command with an invalid argument, AcuConnect displays a standard "Usage:" error message. For example:

Usage: acuthin [--ping | -p] server:port
acuthin --accept
acuthin --register
acuthin --unregister
acuthin [-t [n]] server[:port] [runtime options] ALIAS
[COBOL arguments]

Other acuthin command-line options allow you to perform specific functions. See Debugging in a Transaction Processing Environment for a description of debugging a COBOL program from within a transaction processing environment. See Testing Your AcuConnect Connection for information about command-line options to test your connection (-p or --ping). See Setting Username and Password for a description of the options for designating username and password (--user and --password).

  • Debugging Option
  • Debugging in a Transaction Processing Environment
  • Testing Your AcuConnect Connection
  • Setting Username and Password
Parent topic: Launching Remote Programs from the Client


Debugging Option

If you want to test and debug your application in a thin client configuration, you can run the ACUCOBOL-GT Thin Client with the -d argument. This starts the server in debug mode. For example, the following command line:

acuthin server[:port] -c <path>\configfile –dlxe trace <progname>

would create a file named trace on the server in the directory specified by the alias. You can specify a full path, but it must be for the server, not for the client. For example:

acuthin server[:port] -c <path>\configfile –dlxe <path>\trace
<progname>

If the problem is slow screen display when the debugger window appears on the client screen, use the ts command to trace screen control creation.

You may also use the Ctrl-Break command to enter the debugger program (this works even if the program is not running an ACCEPT statement, as long as the program periodically makes requests to the user interface or is doing file I/O). If the thin client program is busy (such as looping around calls to external software or performing lengthy computations), insert some ACCEPT var FROM INPUT STATUS statements if you want to be able to use <Ctrl-Break> to enter the debugger in that part of your program. See Regarding Debugging in ACUCOBOL-GT User Interface Programming for more information on using Ctrl-Break to enter the debugger.

You should not attempt to execute a shell command (!) while your program is in debug mode. If you do, you will receive the error message Unable to start shell in thin-client mode.

Parent topic: The acuthin Command


Debugging in a Transaction Processing Environment

You can debug your program from within a transaction processing environment, as long as this capability is supported by the vendor of that environment. Refer to your vendor's documentation for details.

Use the following acuthin command-line syntax from your Windows machine:

acuthin --wait [--port nnnn]

where nnnn is the desired port number. When this option is used, the thin client waits for the transaction server to start the runtime, after which you can debug your application in the runtime debugger screen.

In this mode, the acuthin command has an additional option, --restart. With this option, the thin client restarts itself after each debug session, so if a transaction requires multiple COBOL programs to run, you can debug all of them. To terminate the thin client after your debugging session, use the Windows Task Manager.

On UNIX servers, an environment variable setting is required before the transaction server can start the runtime. A_DEBUG_USING_THIN must be set to a nonzero numeric value for debugging on thin client in transaction processing to occur. No additional environment settings are required for Windows servers.

Information about transaction processing environments can be found in "Working with Transaction Processing Systems" in A Guide to Interoperating with ACUCOBOL-GT.

Parent topic: The acuthin Command


Testing Your AcuConnect Connection

To test your initial AcuConnect setup, you can add a command-line option to the acuthin command. Add the -p or --ping option to test whether AcuConnect is running on the server. The command-line syntax is as follows:

acuthin -p [servername]

If a connection is established, the program shows results for message ID, time at client, time at server, and round trip time. If the client doesn't have the proper runtime installed, a message displays to this effect.

Parent topic: The acuthin Command


Setting Username and Password

Two acuthin command-line arguments let you send a username and a password for AcuConnect to use when it reads the AcuAccess file. The --user <username> option allows you to log in to the server as "username" rather than as the current logged-on user. The --password <password> option lets you send the given password to the server without being asked for it. If the password is not valid, the thin client does not allow the connection to occur. These options should appear before the server:port designation in the acuthin command line.

These options can also be set in a thin client command-line file. Use the atc-user and atc-password options described in Thin Client Command-line Files.

You are required to set a password on the server if you use the --user command-line option. In this situation, a prompt for the password appears after "username" is passed. If a password is not required, the --user option does not work.

Parent topic: The acuthin Command


Launching Programs on the Internet

The ACUCOBOL-GT Thin Client works in an Internet environment as well as a local-area or wide-area network environment. When end users invoke the thin client in an Internet environment, they simply enter the server name and, optionally, the port number of the server they are accessing over the Internet.

For example:

acuthin myserver.microfocus.com:5633 myprog1 10 20 30

Note that clients must have a live Internet connection when they execute this command, and the server name that they enter must be resolvable by the Internet name server used by their service provider. (The Internet name server then resolves the name with its IP address.)

If the server name is not exposed to Internet name servers, end users can enter the explicit IP address on the acuthin command line, as in the following example:

acuthin 128.110.121.42:5633 myprog1 10 20 30
Note: If using IPv6 addresses, you must enclose the IP address in brackets when appending the port number or any additional notation; see AGS_USE_IPV6 for more information.

If the server is in a Virtual Private Network (VPN), the user must connect to the network before entering the acuthin command.

If you include your application on a Web site, end users can launch your program from their browsers rather than typing command-line syntax. When they visit your Web site and click a link, the thin client is automatically invoked on their machine, initiating thin client communication with the server. See Launching Thin Client Applications from a Web Page for more information.

Parent topic: Preparing the Client(s) in Thin Client
Related reference
AGS_USE_IPV6


Using the Client Cache Directory

When the thin client needs to use a bitmap (.bmp), wave (.wav), or ActiveX resource file, it downloads the file from the server to a local cache directory. This directory is the one identified by the value in the TEMP environment variable. If no directory is designated in the TEMP variable, the file is downloaded to the client's current working directory.

The client downloads a particular bitmap, wave, or resource file on subsequent requests only if the file on the server is a different size or has a later timestamp than the corresponding file in the client cache directory, or if the file in the cache is deleted for any reason.

The thin client assigns a unique name to each file that it downloads to the cache. This name includes characters from the server name, port number, alias name, COBOL program archive or library name, server path, and server file name. For example, two bitmap files with the same name might be uniquely identified in the cache directory as shown:

myserver5764myalias,library1.acu,image.bmp
myserver5764myalias,library2.acu,image.bmp

If your application calls the WIN$PLAYSOUND library routine, and the named sound refers to a disk file on the server or a resource in the program or a library, the client downloads the file to its cache directory, even from a UNIX server. Another use for the cache directory includes storing keystroke files from the W$KEYBUF library routine. See Using Files Containing Keystrokes for information about using W$KEYBUF.

If your application calls the W$BITMAP routine, there may be a limit to the number of characters you may use in a file name. You are limited to 127 characters if the name passed to W$BITMAP is a file name and extension only and you want W$BITMAP to search for a matching file in the following directories and the order shown below:

  1. The directory in which an application is loaded.
  2. The current directory.
  3. The Windows system directory.
  4. The 16-bit Windows system directory.
  5. The Windows directory.
  6. The directories that are listed in the PATH environment variable.
Parent topic: Preparing the Client(s) in Thin Client


Thin Client Special Topics

  • Introduction
  • Using Library Routines and DLLs in Thin Client
  • Launching Thin Client Applications from a Web Page
  • Thin Client Automatic Update
Parent topic: AcuConnect Version 10.2.0 User's Guide


Introduction

This help section covers several topics of interest for thin client users:

  • Calls to some ACUCOBOL-GT library routines and dynamic link libraries (DLLs) in thin client involve special procedures
  • Instructions for starting a thin client application from a Web page
  • A highly configurable automatic update feature for the ACUCOBOL-GT Thin Client piece is described in detail
Parent topic: Thin Client Special Topics


Using Library Routines and DLLs in Thin Client

Calls to some library routines and dynamic link libraries (DLLs) may have some unique characteristics in thin client environments, as opposed to distributed processing deployments. Implementations of the C$COPY, C$SYSTEM, and W$KEYBUF library routines, among others, are included in this category. The method for calling DLLs on the display host as well as on a Windows application host (server) is also somewhat different for thin client deployments.

  • Copying Files between the Client and Server
  • Executing Desktop Programs
  • Using Files Containing Keystrokes
  • Selecting Files on the Client
  • Accessing Local Resource Files
  • Calling Dynamic Link Libraries (DLLs)
  • Calling the DLL Version of the ACUCOBOL-GT Thin Client
Parent topic: Thin Client Special Topics


Copying Files between the Client and Server

The C$COPY library routine allows the transfer of files between the application host and the display host in thin client and between directories on the display host. A special name notation of "@[DISPLAY]:" indicates that a particular file is located on the display host, or client. Use this designation for the source file or the destination file in the call to C$COPY. If the copy operation is performed entirely on the client side, the "@[DISPLAY]:" notation appears in both the source and destination file parameters. As an example, for a file transfer from the server to the client, "@[DISPLAY]:" precedes the destination file name, as shown:

C$COPY "/usr/data/file1.ext" "@[DISPLAY]:C:\My Documents\file1.ext"

For a file transfer from the client to the server, "@[DISPLAY]:" precedes the source file name. For example:

C$COPY "@[DISPLAY]:C:\My Documents\file1.ext" "/usr/data/file1.ext"

Path specifications on the client are relative to the directory identified in the TEMP user environment variable. On the server, they are relative to the working directory specified in the application's alias definition. For example, if TEMP is C:\Documents and Settings\joe\Local Settings\Temp and the application's working directory on the server is /usr/apps/app1, then the following statement:

C$COPY "@[DISPLAY]:file1.ext" "file2.ext"

uploads C:\Documents and Settings\joe\Local Settings\Temp\file1.ext from the client to /usr/apps/app1/file2.ext on the server.

Access to files on the display host is also accomplished via a set of directory specifiers. If the file name on the client starts with a special directory specifier, the thin client attempts to locate those files in special Windows directories. The special directory names are as follows:

Identifier | Directory
<APPDATA> | C:\Documents and Settings\<user>\Application Data
<COMMON_APPDATA> | C:\Documents and Settings\All Users\Application Data
<COMMON_DOCUMENTS> | C:\Documents and Settings\All Users\Documents
<DESKTOP> | C:\Documents and Settings\<user>\Desktop
<LOCAL_APPDATA> | C:\Documents and Settings\<user>\Local Settings\Application Data
<MYDOCUMENTS> | C:\Documents and Settings\<user>\My Documents

Note that these directories are not necessarily the same for all versions of Windows, and may in fact be on network drives.

If further directory information is specified, the thin client attempts to create the directories added. For example, when attempting to access <APPDATA>\ACUCOBOL-GT\settings.dat, the thin client ensures that the ACUCOBOL-GT directory actually exists as a subdirectory of the Application Data directory.

If the syntax for files on the display host is

C$COPY "@[DISPLAY]:<APPDATA>/filename"

the thin client would attempt to locate the specified file in

C:\Documents and Settings\<user>\Application Data

For security purposes, user authorization is required to allow a file transfer to the server using C$COPY. Copying a file to a location other than the directory named in the TEMP user environment variable also needs user authorization. The thin client displays a dialog box requesting the authorization.

Note that when the "@[DISPLAY]:" notation appears in the first or second parameter in the call to C$COPY, the optional parameter FILETYPE is not used. Only the single file named as the source file is copied. When an application is not running in the thin client, the "@[DISPLAY]:" notation is ignored.

Parent topic: Using Library Routines and DLLs in Thin Client


Executing Desktop Programs

Your server application can execute desktop programs via the ACUCOBOL-GT C$SYSTEM library routine. To achieve this functionality, add the CSYS-DESKTOP flag to the set of flags passed to C$SYSTEM. This flag indicates that the application wants to run the program on the client machine rather than the application server.

Note that the thin client appears "frozen" while the command executes, in order to return the termination status to the application correctly. To avoid this behavior, run the command asynchronously by specifying the CSYS-ASYNC flag.

For example, the following code fragment starts Notepad on the client machine:

77 flags      pic 9(4) comp

add csys-desktop, csys-async giving flags
call "c$system" using "notepad", flags

Because C$SYSTEM can perform harmful actions on the desktop (like removing files), the thin client asks the user for permission to run the command. The user can choose not to see the question again for a specific application host.

For detailed information about C$SYSTEM, refer to the appendix "Library Routines" in ACUCOBOL-GT Appendices.

Parent topic: Using Library Routines and DLLs in Thin Client


Using Files Containing Keystrokes

W$KEYBUF library routine behavior is slightly different in thin client environments than in the distributed processing environment. This routine lets you create files of keystrokes that can be played back to simulate user input. Specifically, W$KEYBUF op-codes 7, 8, and 9 have a different implementation in thin client. In a thin client environment, these files of keystrokes are created in a temporary cache file on the thin client machine, then uploaded to the server when recording stops (op-codes 7 and 8). When a file is to be played back, the thin client requests that the file be downloaded from the server to the client's temporary cache directory, as specified in the TEMP environment variable. If TEMP is not set, the files are stored in the thin client's current working directory. The file is not downloaded again unless it is changed on the server or deleted from the client.

More information about the W$KEYBUF library routine can be found in the appendix "Library Routines " in ACUCOBOL-GT Appendices.

Parent topic: Using Library Routines and DLLs in Thin Client


Selecting Files on the Client

A call to the C$OPENSAVEBOX library routine allows you to browse the client machine's drives and select a directory or file. This routine is used in conjunction with other operations that have access to the client machine's drives, such as C$COPY, C$SYSTEM, DLL calls, and COM or ActiveX components.

Note that the server machine's files do not appear in the dialog box. However, if your server machine is Windows, you can navigate to the server using Universal Naming Convention (UNC) notation. Set the C$OPENSAVBOX parameter OPNSAV-DEFAULT-DIR to the desired mapped drive or server directory using UNC notation.

Parent topic: Using Library Routines and DLLs in Thin Client


Accessing Local Resource Files

You can access a local resource file on the display host in thin client by adding the "@[DISPLAY]:" notation to the file name in calls to the W$BITMAP, WIN$PLAYSOUND, W$KEYBUF, or C$RESOURCE library routine. When a file name that you pass to one of these routines begins with "@[DISPLAY]:", the routine attempts to access the file in the display host's file system. It does not download the file from the server. This function is helpful when your application uses many or large resource files and you want to avoid the download delay that occurs when you first run your application.

You can distribute any number of resource files with the thin client executable. You can specify absolute paths or paths relative to the directory location of acuthin.exe. For example, if you distribute the wave file MyApp\sounds\sound1.wav, you can access it on the display host with the following statement:

CALL "WIN$PLAYSOUND" USING
     "@[DISPLAY]:../../MyApp/sounds/sound1.wav",
     SNDSYNC.

Note that if you change a distributed resource file, you need to distribute the updated file to all your users.

Parent topic: Using Library Routines and DLLs in Thin Client


Calling Dynamic Link Libraries (DLLs)

In a thin client environment, you can call subroutines in DLLs on the display host (client), as well as on the application host, when the application host is a Windows server. DLL calls to the display host involve some special considerations. Calling DLLs on the Windows application host uses the COBOL syntax and configuration variables described in A Guide to Interoperating with ACUCOBOL-GT. However, DLLs that are called on the server side and that interact with the user interface may be of limited use to thin client applications.

  • Calling Client-side DLLs
  • Related Configuration Variables
  • Passing Pointers in DLL Calls
Parent topic: Using Library Routines and DLLs in Thin Client


Calling Client-side DLLs

Calling a DLL on the display host requires special notation. The name of the DLL called on the display host must begin with "@[DISPLAY]:". For example, to call a DLL named MYLIB on the client, you would use the following code:

CALL "@[DISPLAY]:MYLIB.DLL"

The file path for a called DLL is relative to the directory that contains acuthin.exe. For example, if acuthin.exe is located in C:\Micro Focus\Acucbl8xx\AcuGT\bin, then the following call:

CALL "@[DISPLAY]:MYAPP\MYLIB.DLL"

refers to C:\Micro Focus\Acucbl8xx\AcuGT\bin\MYAPP\MYLIB.DLL. Note that the CALL statement ignores CODE_PREFIX when it searches for DLLs on the client. CODE_PREFIX is applied only to actions on the application host.

Parent topic: Calling Dynamic Link Libraries (DLLs)


Related Configuration Variables

You can use the CODE_MAPPING configuration variable (see the appendix "Configuration Variables" in ACUCOBOL-GT Appendices) to map CALLs to DLLs on the display host. For example, the following configuration file entry:

CODE_MAPPING  1
MYLIB.DLL @[DISPLAY]:MYLIB.DLL

causes a call to MYLIB.DLL to execute on the client. In addition to mapping the DLL name, you should map the name of each function contained in the DLL in the configuration file, as shown below for FuncA and FuncB in MYLIB:

FuncA @[DISPLAY]:FuncA
FuncB @[DISPLAY]:FuncB

It is important that you use the DLL_CONVENTION configuration variable to specify the appropriate calling convention. Refer to the appendix "Configuration Variables" in ACUCOBOL-GT Appendices for more details about DLL_CONVENTION.

Parent topic: Calling Dynamic Link Libraries (DLLs)


Passing Pointers in DLL Calls

Passing a pointer as a parameter of a DLL call that executes on the display host requires some special handling in code, because the pointer value refers to a memory address on the application host. In certain cases, you may safely pass a pointer BY VALUE. You may never pass a pointer BY REFERENCE.

Using M$ALLOC

The runtime knows the size of allocated memory and can pass the contents of that memory to the thin client if the pointer is returned by a call to the M$ALLOC library routine. Then, if the DLL call on the client modifies the memory, the display host returns the modified memory back to the application host. As an example, assume you have DLL routines named SetData and GetData that take size and pointer arguments. You may use the following code:

77  PTR     USAGE POINTER.
77  ITEM-1  PIC X(100).
...
  CALL "M$ALLOC" USING 100, PTR.
  CALL "M$PUT" USING PTR, "Hello World".
  CALL "@[DISPLAY]:SetData" USING 100, BY VALUE PTR.
  ...
  CALL "@[DISPLAY]:GetData" USING 100, BY VALUE PTR.
  CALL "M$GET" USING PTR, ITEM-1.
  CALL "M$FREE" USING PTR.

The application host sends the 100-byte contents of memory to the client on the CALL to SetData. After the client fills the 100 bytes of memory with GetData, it returns the contents to the server.

Using the -Zm Compiler Option

You can use a new compiler option with the Format 7 SET statement to pass pointers to client-side DLL calls. Use this option if you don't want to add the WITH MEMORY SIZE phrase for each pointer parameter in a CALL statement. If your Format 7 SET statement returns a pointer value and you compile with the -Zm option, the Compiler generates additional code that provides the runtime with the size of the item specified in the SET statement. Once the runtime has this information, it can pass the memory contents to the thin client and then retrieve the contents after the thin client modifies them. Note that the -Zm option adds runtime overhead for each Format 7 SET statement. See Procedure Division Statements in the ACUCOBOL-GT Reference Manual for information about the SET statement.

Using the CALL Statement

The USING phrase in the Format 1 CALL statement includes a size-phrase item with which you can pass the size of a memory item along with the pointer value. Use size-phrase when the runtime and the thin client cannot automatically determine the size of the memory being pointed to. This can occur if, for example, a pointer is passed through the Linkage section or is an external item. The syntax is

[ USING { [ BY {REFERENCE} ] {parameter} size-phrase ...} ...]
               {CONTENT }    {OMITTED }
               {VALUE   }    {NULL    }

where size-phrase is:

[WITH MEMORY SIZE { =  } memory-size]
                  { IS }

memory-size is a numeric literal or data item.

As an example, assume you have pointer PTR that points to 1024 bytes of memory. You can pass this pointer to a DLL called SetData on the display host with the following code:

CALL "@[DISPLAY]:SetData" USING BY VALUE PTR
       WITH MEMORY SIZE 1024.
Parent topic: Calling Dynamic Link Libraries (DLLs)


Calling the DLL Version of the ACUCOBOL-GT Thin Client

A DLL interface to the ACUCOBOL-GT Thin Client is designed to be called from languages that don't support ActiveX or when a DLL interface is preferable to ActiveX. If you decide that a DLL interface is the best method of accessing the Thin Client from your program, you call the thin client DLL, acuthin.dll.

To call the ACUCOBOL-GT Thin Client DLL from another programming language, you must add a single declaration to the source program. This example shows what you would use in C/C++:

int PASCAL AcuThinMain( const char *pCmdLine );

To start the thin client, you must pass AcuThinMain a single parameter that specifies a command-line string using the same syntax as required by the acuthin.exe command line. For example, in C/C++ you would use the following syntax to start an application on "myserver" using port 5764 with an acurcl alias named "myappalias":

int iRetVal = AcuThinMain( "myserver:5764 -d myappalias" );

AcuThinMain returns "1" on success, "0" on failure.

The thin client DLL depends on acme.dll, aclnt.dll, and atermmgr.dll. In addition, if your program uses .jpg files, you also need ajpg32.dll.

Parent topic: Using Library Routines and DLLs in Thin Client


Launching Thin Client Applications from a Web Page

Follow the procedure below if you want thin client users to launch your application from a Web page.
  1. Install your COBOL application on your application server host. This machine must also contain the ACUCOBOL-GT runtime, AcuConnect, and the other required software components. Note that your application does not need to reside on the same host as your Web server.
  2. Create a thin client command-line file that contains all the information needed by the ACUCOBOL-GT Thin Client to launch your application. This file should have an .atc or .acutc extension. The format of this file is described in Thin Client Command-line Files.
  3. Place the thin client command-line file on your Web server and create a link to it from an appropriate Web page. Your users click on this link to launch your thin client application.
  4. To ensure that your thin client is recognized across a wide variety of browsers, configure your Web server to generate an HTTP "Content-type" response header field, which is included with the thin client command-line file. This field should contain the MIME type "application/vnd.acucorp.thincommandline". Refer to your Web server documentation for instructions on adding a MIME type.

After you set up your hyperlink, end users who visit your Web page can run the program by clicking on the program's link. The display occurs in an application window outside of the user's browser. Users who start the thin client from an .atc or .acutc file that was downloaded from the Internet are presented with a security dialog asking them to authorize the action.

Note: A Windows XP Service Pack 2 user may receive a File Download dialog before the thin client application can execute. If the user clears the "Always ask before opening this type of file" check box the first time it appears, subsequent requests for this thin client application proceed immediately.

Another way to launch thin client applications from a Web page is the ACUCOBOL-GT Web Thin Client. The Web thin client is an ActiveX control that encapsulates the functionality of the ACUCOBOL-GT Thin Client. It is designed for browsers that support ActiveX controls, particularly Microsoft Internet Explorer. More information about the Web thin client can be found in A Programmer’s Guide to the Internet.

Users can also launch the ACUCOBOL-GT Thin Client by entering the host name of the application server or an Internet IP address on the acuthin.exe command line. See Launching Programs on the Internet for more information.

  • Thin Client Command-line Files
  • Using Anchor Tags
Parent topic: Thin Client Special Topics


Thin Client Command-line Files

When users install the ACUCOBOL-GT Thin Client on a Windows display host, the .atc and .acutc file extensions are automatically associated with the thin client executable (acuthin.exe). As a result, when your browser downloads one of these files, it uses these associations to invoke acuthin.exe. The thin client uses the contents of this file to establish its command-line parameters. The thin client command-line file has a format that resembles other configuration files, and it may contain the following variables:

Variable name | Description
atc-auto-update | Lets you disable the thin client automatic update feature with a setting of "off" (0, false, no)
atc-user | The logon user name (no default value)
atc-password | The password given to the server (a required variable when atc-user is used; no default value)
atc-splash-screen | The option that lets you disable the thin client splash screen with a setting of "off" (0, false, no)
atc-trace | The trace level (default value is "0")
atc-server | The name or IP address of the server to connect to (a required variable with no default value)
atc-port | The TCP port number to use (default value is 5632)
atc-runtime-options | runtime options passed to the runtime via AcuConnect (no default value)
atc-alias | The alias to execute (a required variable with no default value)
atc-cobol-args | COBOL arguments passed to your COBOL program via AcuConnect (no default value)

Comment lines (preceded by the "#" character) are allowed in this file, as they are in other configuration files.

The contents of the .atc or .acutc file are interpreted by the thin client as the following command line:

acuthin [atc-user atc-password atc-splash-screen atc-trace] <atc-server>[:<atc-port>] [atc-runtime-options] <atc-alias>
[<atc-cobol-args>]

As an example, assume the following command-line file components:

atc-server | myserver
atc-port | 5633
atc-runtime-options | -lxe runtime.err
atc-alias | myprog
atc-cobol-args | 10 20 30

These command-line file contents are interpreted as the following command line:

acuthin myserver:5633 -lxe runtime.err myprog 10 20 30

There is an additional command line argument for when a COBOL program does a lot of file IO without interacting with the user in a thin client environment, and if that user attempts to interact with the COBOL window (by trying to activate a control, for example), the thin client could just disappear after a few minutes.

the command line is:

acuthin --notimeout server alias

Note that setting this switch may cause the thin client to wait for a runtime that has died for some reason, without having notified the thin client. In other words, it is better to rework your application and to no use this switch if possible, so that your application will respond correctly to user interaction.

Parent topic: Launching Thin Client Applications from a Web Page


Using Anchor Tags

Use the HTML anchor tags <a> and </a> to create a link to your COBOL application. Anchor tags are closed elements that highlight text or images, making them clickable. When users click on a highlighted item on your Web page, they are transferred to the linked document. Because the link in this case is a thin client command-line file, when users click on the highlighted item, the thin client is automatically invoked.

To turn text into a hypertext anchor, enclose the clickable text in the anchor tags. For example:

<a href="myprog.atc">Click here to run the application</a>
Parent topic: Launching Thin Client Applications from a Web Page


Thin Client Automatic Update

The ACUCOBOL-GT Thin Client has an automatic update feature that determines whether the acuthin executable on the client is compatible with the server components (the AcuConnect executable acurcl and the ACUCOBOL-GT runtime executable wrun32 or runcbl) and triggers an automatic update of the client piece if it is not. This feature is especially helpful if you need to update a large number of clients after you update your server components. With the automatic update, users do not see an error message regarding a version mismatch, and they can use the application immediately after the update.

With this feature, the thin client can automatically download and install a new version of the client piece that matches the server version. It can then restart the user's application using the newly installed thin client.

Note that if your server is running AcuConnect Version 7.2 or later, it cannot automatically update a thin client that is earlier than Version 7.2. However, Version 7.2 can be updated from one product build to another via the TC_CHECK_INSTALLER_TIMESTAMP or the TC_REQUIRES_BUILD_NUMBER configuration variable. (This function may be useful when installing a patched product.) You can also test the automatic update process by using the --testautoupdate command-line option to acuthin.

  • Automatic Update Overview
  • Automatic Update Process
  • Enabling or Disabling the Automatic Update Feature
  • Informing the User When an Update Is Needed
  • Accepting the Automatic Update
  • Restarting the Application with the New Thin Client
  • Automatic Update Failure
Parent topic: Thin Client Special Topics


Automatic Update Overview

The thin client first connects to the AcuConnect executable, acurcl, which is running on the server. This executable looks up the specified alias and starts the ACUCOBOL-GT runtime on the server, which takes over the communication with the thin client. The runtime sends the thin client information about itself, including its version number and thin client protocol number. It also sends several configuration variables that control the thin client automatic update behavior.

You specify these configuration variables in the runtime configuration file for your application rather than in the acurcl configuration file. As a result, you can have a different automatic update configuration for each application alias managed by a single AcuConnect server.

Each of the following five events can cause an automatic update of the thin client:

  1. The client's major and minor version numbers do not match the server's.
  2. The client's protocol number does not match the server's.
  3. The TC_REQUIRES_BUILD_NUMBER configuration variable is a nonzero value, and the client's build number does not match this value.
  4. The TC_CHECK_INSTALLER_TIMESTAMP configuration variable is set to "on", and the modification time of the installer file on the server is later than the modification time of the installer file on the client. If the installer file does not exist on the client, the modification time of the running acuthin.exe is used.
  5. The acuthin command has been executed with the --testautoupdate command-line option.

The TC_REQUIRES_BUILD_NUMBER configuration variable facilitates the automatic update of the thin client via a comparison of the client's build number with the variable value. You set this variable to the thin client build number required by the application. The default value of this variable is "0" (off, false, no).

When thin client executes, it compares its build number with the value of TC_REQUIRES_BUILD_NUMBER. If the value of this variable does not match the client's build number, the automatic update process is initiated. For example, suppose you have a patched version of the thin client containing some enhancements needed by your application, and you want to use the automatic update feature to deliver the patched thin client to users. Run acuthin -v to get the build number of the patched thin client, then set TC_REQUIRES_BUILD_NUMBER to that build number in the runtime configuration file set up for your application. Even though the version and protocol numbers have not changed, the different build number triggers the automatic update. Note that if the value of TC_REQUIRES_BUILD_NUMBER does not match either the old or the new thin client build number, the automatic update process is initiated each time the user launches the acuthin executable.

The value of the TC_CHECK_INSTALLER_TIMESTAMP configuration variable determines whether the thin client compares the modification times of the installer files on the client and on the server. If this variable is set to "1" (on, true, yes) and the modification time of the client file is older than the time of the server file, the automatic update process is initiated. If the installer file does not exist on the client, the comparison is made with the modification time of the thin client executable (acuthin) currently running. The default value for this variable is "0" (off, false, no). To use this automatic update method, you should ensure that your client and server clocks are synchronized to avoid unnecessary automatic updates. Times are converted to UTC (Coordinated Universal Time) — formerly known as Greenwich Mean Time (GMT) — so the comparison works across world time zones.

The --testautoupdate command-line option to acuthin lets you test the automatic update feature with your configuration. You need to specify a server, port number, and alias when you use this option.

Parent topic: Thin Client Automatic Update


Automatic Update Process

When the server runtime determines that a thin client automatic update is needed, it triggers the following process (optional steps are enabled by default):

  1. The thin client checks to see if the automatic update feature is enabled.
  2. If the feature is enabled, the thin client informs the user that an update is required and asks the user to proceed with or cancel the update (optional). If the user accepts the update, the thin client downloads a single "installer" file while displaying a download progress dialog.
  3. If the installer file has an .msi extension, the thin client launches the Microsoft Windows Installer (msiexec.exe) to complete the thin client installation using the contents of the .msi file.
  4. Thin client waits for the installer process to exit and then starts the newly installed thin client with the same command-line parameters or .atc (or .acutc) file passed to the original thin client process (optional).
  5. If the automatic update fails for any reason, the thin client informs the user of that fact (optional).
Parent topic: Thin Client Automatic Update


Enabling or Disabling the Automatic Update Feature

The thin client automatic update feature is enabled by default. The feature can be disabled in one of three ways. You can:
  • Set the atc-auto-update thin client command-line variable in the .atc (or .acutc) file to "0" (off, false, no). The default value is "1" (on, true, yes).
  • Set the TC_DISABLE_AUTO_UPDATE runtime configuration variable to "1" (on, true, yes). Default value is "0" (off, false, no).
  • Use the --noautoupdate command-line option to acuthin.
Parent topic: Thin Client Automatic Update


Informing the User When an Update Is Needed

When a thin client event triggers the update process, the thin client displays a message box informing the user that an update is required. The appearance of the box may be triggered by a version or protocol number mismatch or a build number mismatch. At this point, the user may choose to proceed with or cancel the update. Three runtime configuration variables control the message box's appearance.

The default setting of "1" (on, true, yes) for the TC_AUTO_UPDATE_QUERY configuration variable enables the display of the query message box. Setting this variable to "0" (off, false, no) prevents the message box appearance.

You use the TC_AUTO_UPDATE_QUERY_TITLE configuration variable to specify the title bar text in the automatic update query message box. The default value of this variable is

ACUCOBOL-GT Thin Client

The value of the TC_AUTO_UPDATE_QUERY_MESSAGE configuration variable determines the message displayed in the query message box. The default value depends on the circumstances that triggered the automatic update. For example, if the automatic update is triggered by a version or protocol number mismatch, the message displayed is:

Incompatible server version
Server version: <srvvers>, client <clntvers>
Server protocol: <srvproto>, client <clntproto>
Press OK to automatically correct this problem

where <srvvers>, <clntvers>, <srvproto>, and <clntproto> are replaced by the server version, client version, server protocol number, and client protocol number, respectively.

If the automatic update is triggered by a build number mismatch, the message displayed is:

This application requires a newer version of ACUCOBOL-GT Thin Client
Build required: <reqbld>, current <curbld>
Press OK to automatically update this software

where <reqbld> is the value of the TC_REQUIRES_BUILD_NUMBER configuration variable, and <curbld> is the build number of the currently running thin client.

If the automatic update is triggered by any other condition, the following message appears:

This copy of ACUCOBOL-GT Thin Client is out of date
Press OK to automatically update this software
Parent topic: Thin Client Automatic Update


Accepting the Automatic Update

If the user proceeds with the thin client automatic update, the thin client downloads an installer file. ACUCOBOL-GT provides a default .msi installer file called acuthin.msi in the REDIST directory on our product CD. This file contains all of the information needed to update the thin client, including installation instructions and properties. To use this file as your installer file, you should copy it to the directory that contains the wrun32 or runcbl runtime executable. If you rename this file or install it in any other directory, you must set the TC_INSTALLER_SERVER_FILE configuration variable to the path and file name of the installer file.

You may use Microsoft® Visual Studio®, InstallShield®, Wise installer, or a similar tool to create your own .msi file if you want to customize the thin client automatic update installation.

You can also create an .exe, .html, .doc, .pdf, .bat, or .cmd file to run instead of an .msi installer. If the installer file ends with .msi or .exe, the thin client executes the file directly. If the installer file does not have either extension, the thin client uses the Windows ShellExecute() API to run it as if the user had double-clicked on the file or opened the file using Windows Explorer. Other issues apply if you use an installer file that does not have the .msi extension. See Restarting the Application with the New Thin Client for a description of the TC_INSTALLER_RUN_ASYNC configuration variable.

  • .msi Installer
  • Other Installers
  • Installer File Locations
  • Download Progress Dialog Box
  • Microsoft Windows Installer
Parent topic: Thin Client Automatic Update


.msi Installer

When the installer file has an .msi extension, the location specified in the TC_INSTALLER_TARGET_DIR configuration variable is used for setting the installation directory that appears in the installer dialog. The acuthin.msi file distributed with AcuConnect defines a default location of

C:\Program Files\ACUCOBOL-GT\Acucbl8xx\AcuGT\bin

If the installation directory for the new version of thin client is the same as the location of the currently running thin client, the installer cannot overwrite the executables and DLLs because they are in use. To avoid this problem, set TC_INSTALLER_TARGET_DIR to a unique name that includes the version number and build number, if necessary.

Note that if you set TC_INSTALLER_RUN_ASYNC, you may install the new thin client in the same directory as the currently running thin client. The system allows the executable and DLLs to be overwritten as soon as the current thin client exits, which with TC_INSTALLER_RUN_ASYNC, happens immediately after the thin client starts the installer. However, in this instance, the thin client does not automatically restart the application. See Restarting the Application with the New Thin Client for more information on TC_INSTALLER_RUN_ASYNC.

Parent topic: Accepting the Automatic Update


Other Installers

If your installer file does not have an .msi extension, it needs to choose or allow the user to choose the installation directory. After the new directory is chosen, your installer needs to update the .atc file type association in the registry so that the thin client can locate the newly installed executable after your installer finishes. If you want to install the thin client in a directory relative to the location of the existing thin client, you can determine the location by querying the registry entries for the .atc (or .acutc) file type association.

The thin client examines the .atc file type association in the registry by first reading the value of HKEY_CLASSES_ROOT\.atc to identify the version-specific name of the current thin client. It then reads the value of HKEY_CLASSES_ROOT\<current_version>\shell\open\command to get the absolute directory path to the acuthin.exe executable.

For example, after a Version 7.2 thin client installation, HKEY_CLASSES_ROOT\.atc has the value

MicroFocus.ThinClient.72

HKEY_CLASSES_ROOT\MicroFocus.ThinClient.72\shell\open\command may have the value

"C:\Program Files\AcuThin\acuthin.exe" "%1"

This value starts with the absolute directory path for the thin client. Your installer should change this value if you install the new thin client in a different directory.

If the value of TC_INSTALLER_CLIENT_FILE is an executable (.exe file), the thin client uses the value of the TC_INSTALLER_ARGS configuration variable as the command-line options passed to that executable. For example, if you want msiexec.exe to log all of its operations to a file named msi.log, you could set TC_INSTALLER_ARGS to "/log msi.log". (See the Microsoft Windows Installer documentation for more details.) TC_INSTALLER_ARGS has no default value.

Note that if the TC_INSTALLER_ARGS configuration variable is set, the TC_INSTALLER_UI_LEVEL configuration variable is ignored. See Microsoft Windows Installer for more information.

Parent topic: Accepting the Automatic Update


Installer File Locations

Two configuration variables specify the locations of the client and server installer files. You set the TC_INSTALLER_SERVER_FILE configuration variable to the path and file name of the server installer file. Its default value is

<runtime_path>/acuthin.msi

where <runtime_path> is the directory that contains the wrun32 or runcbl runtime executable. As mentioned earlier, you can substitute another type of file for the .msi file (for example, an .exe, .html, .doc, .pdf, or .cmd).

Note that on Windows servers, you should not use drive letters mapped to network shares in TC_INSTALLER_SERVER_FILE. Problems can occur if you try to use a drive letter that is mapped in a different security context. Instead, use Universal Naming Convention (UNC) names to access resources. The format looks like the following:

TC_INSTALLER_SERVER_FILE \\MyServer\filesharename\directoryname\filename
Note: To access network shares, you must either set the AcuConnect SECURITY_METHOD configuration variable to "LOGON" or use the control panel to set the AcuConnect Service "Log On As" property to an account that can access the network share.

Use the TC_INSTALLER_CLIENT_FILE configuration variable to specify the path and file name of the installer file that you want to create on the client. You may use the following special directory names for Windows to specify the value of TC_INSTALLER_CLIENT_FILE:

Identifier | Directory
<APPDATA> | C:\Documents and Settings\<user>\Application Data
<COMMON_APPDATA> | C:\Documents and Settings\All Users\Application Data
<COMMON_DOCUMENTS> | C:\Documents and Settings\All Users\Documents
<DESKTOP> | C:\Documents and Settings\<user>\Desktop
<LOCAL_APPDATA> | C:\Documents and Settings\<user>\Local Settings\Application Data
<MYDOCUMENTS> | C:\Documents and Settings\<user>\My Documents

See Copying Files between the Client and Server for more information about these special directory names.

The default value of TC_INSTALLER_CLIENT_FILE is

<APPDATA>\ACUCOBOL-GT\<installer_server_filename>

where <installer_server_filename> is the file name specified in the TC_INSTALLER_SERVER_FILE configuration variable. By default, the specified file name is acuthin.msi. As an example, if user Bob has TC_INSTALLER_SERVER_FILE set to the default, the default value of TC_INSTALLER_CLIENT_FILE is

C:\Documents and Settings\Bob\Application Data\ACUCOBOL-GT\acuthin.msi
Parent topic: Accepting the Automatic Update


Download Progress Dialog Box

During the installer file download process, a progress dialog box appears. You can cancel the download at any time from this dialog box. Four configuration variables control the behavior of the download progress dialog:

  • TC_DOWNLOAD_DIALOG

    The default value of “1” (on, true, yes) for this configuration variable enables the appearance of the progress dialog. If you set this variable to “0” (off, false, no), the progress dialog does not appear.

  • TC_DOWNLOAD_DIALOG_TITLE

    This configuration variable is used to specify the title bar text in the download progress dialog. The default value of this variable is

    ACUCOBOL-GT Thin Client Automatic Update
  • TC_DOWNLOAD_DESCRIPTION

    You use this configuration variable to specify the text that appears in the middle of the download progress dialog. Its default value is

    Downloading installation file. . .
  • TC_DOWNLOAD_CANCEL_MESSAGE

    Use this configuration variable to specify the message that appears if the download process is cancelled. The Cancel push button is disabled immediately after the user clicks it, the description line in the middle of the dialog disappears, and the message specified in this configuration variable appears. The default value for TC_DOWNLOAD_CANCEL_MESSAGE is

    Please wait while the download is being cancelled . . .
Parent topic: Accepting the Automatic Update


Microsoft Windows Installer

After the installer file downloads successfully, the thin client executes the Microsoft Windows Installer (msiexec.exe), which installs the new ACUCOBOL-GT Thin Client. Note that msiexec.exe is available on, and the .msi file extension is automatically recognized by, later generations of Microsoft operating systems. However, Windows NT may require the installation of a patch from Microsoft to execute the .msi file. These patch files are InstMsiW.exe for Windows NT Service Pack 6 and later.

Distributed with AcuConnect, these two files are located in the REDIST directory on the product CD. For the automatic download to work, you need to copy the appropriate patch file to the same directory as the installer file on the server, that is, the directory containing the runtime executable wrun32 or runcbl or the directory specified in TC_INSTALLER_SERVER_FILE.

The acuthin.msi file contains a default location for the install. If you want to install to a different location, use the TC_INSTALLER_TARGET_DIR configuration variable.

Note that on Windows servers, you should not use drive letters mapped to network shares in TC_INSTALLER_TARGET_DIR. Problems can occur if you try to use a drive letter that is mapped in a different security context. Instead, use UNC names to access resources. The format looks like the following:

TC_INSTALLER_TARGET_DIR \\MyServer\sharename\directoryname

The keywords or numeric values in the TC_INSTALLER_UI_LEVEL configuration variable control the Windows installer interface.

Set TC_INSTALLER_UI_LEVEL to... | if you...
NONE or "0" | do not want msiexec.exe to display a user interface. This setting adds the /qn command-line option to msiexec.
UNATTENDED or "1" | want msiexec.exe to display informational and progress messages, but to execute unattended. This setting adds the /passive command-line option to msiexec.
INTERACTIVE, DEFAULT, or "2" | want msiexec.exe to prompt for and accept user input for the installation process. For example, the user could choose the directory location for thin client installation. This setting adds the /qf command-line option to msiexec.
REDUCED or "3" | want msiexec.exe to use a reduced user interface. This setting adds the /qr command-line option to msiexec.
Parent topic: Accepting the Automatic Update


Restarting the Application with the New Thin Client

After the installer process is complete, the newly installed thin client is started with the same command-line parameters or .atc (or .acutc) file passed to the original process. The thin client examines the .atc file type association in the registry to find the new thin client version. If the registry entries are properly set, when you open the .atc file from Windows Explorer, a desktop shortcut, or the Start menu, the updated version of thin client is automatically found.

The thin client also adds the --noautoupdate command-line option to acuthin, which prevents an infinite loop in the event an error causes the new thin client to detect that it needs another update. This could happen if, for instance, the automatic update was configured with an incorrect version of the installer that installs an older thin client than required.

You use the TC_INSTALLER_RUN_ASYNC configuration variable when you want to prevent the thin client from restarting after an automatic update, or when your installer file handles the automatic update process to completion. When you set this variable to "1" (on, true, yes), the thin client starts the installer process asynchronously and then exits immediately. It does not wait for the automatic update process to complete and does not restart using the same command-line parameters or .atc file. The default value is "0" (off, false, no).

You may also use TC_INTALLER_RUN_ASYNC to install the new thin client in the same directory as the currently running thin client. When this variable is set to "1", the system allows the executable and DLLs to be overwritten as soon as the current thin client exits, which happens immediately after the thin client starts the installer.

This variable is useful if you want to run an .exe, .html, .doc, .pdf, .cmd, or other file instead of an .msi installer. For example, you could set TC_INSTALLER_SERVER_FILE to "AutoUpdate.html" and TC_INSTALLER_RUN_ASYNC to "1". The thin client downloads AutoUpdate.html and runs it. The original thin client process would exit and leave Internet Explorer (or the default Web browser or application associated with .html) displaying the contents of AutoUpdate.html. AutoUpdate.html could include scripting code, redirect the Web browser to a Web site, or simply display an informational message to the user.

Parent topic: Thin Client Automatic Update


Automatic Update Failure

If the thin client automatic update process fails for any reason, a message box appears and a log file is created on the server by default. This file contains a log of the update operations and details about the failure. The following configuration variables affect the failure notification process:

  • TC_AUTO_UPDATE_FAILED_TITLE

    This configuration variable lets you set the title bar text for the message box that appears on update failure. Its default value is

    ACUCOBOL-GT Thin Client
  • TC_AUTO_UPDATE_FAILED_MESSAGE

    This configuration variable lets you specify the text in this message box. Its default value is

    ACUCOBOL-GT Thin Client: Automatic update was unsuccessful
  • TC_AUTO_UPDATE_NOTIFY_FAIL

    In some cases, you may not want the thin client to inform the user that the automatic update failed. Set this configuration variable to “false” (0, off, no) to configure the thin client so it does not notify the user if the automatic update fails. The default value of TC_AUTO_UPDATE_NOTIFY_FAIL is “true” (1, on, yes). Note that the message box does not appear if the user cancels the Windows installer download process.

  • TC_SERVER_LOG_FILE

    You can use this configuration variable to configure the location and name of the log file created on the server. The name can optionally include the hostname of the client machine and the process ID of the server runtime that was managing the automatic update at the time of the failure.

    By default, this file is named autoupdate.%c.%p.log, where %c is replaced by the client hostname and %p is replaced by the process ID of the server runtime. The default location is the working directory specified in the alias on the server. The directory must exist at the time of the failure. Otherwise, this file is not created. The location of the log file is relative to the working directory specified in the alias. For example, the following setting:

    TC_SERVER_LOG_FILE  updatefailed/%c.%p.log

    configures the log files to be created in a directory named updatefailed relative to the working directory. The files are named with the hostname of the client followed by a dot and the process ID of the server runtime, ending with the .log file extension.

    The client and server may be in different time zones. You can look at the file’s creation date to see what time the update failed according to the clock on the server, and view the timestamps at the beginning of the lines in the log file to see what time it failed according to the clock on the client.

  • TC_DISABLE_SERVER_LOG

    Set this configuration variable to “true” (1, on, yes) to prevent the creation of a log file for a thin client automatic update failure. The default value of TC_DISABLE_SERVER_LOG is “false” (0, off, no).

Parent topic: Thin Client Automatic Update


Managing the System

  • Introduction
  • Managing the System: UNIX
  • Managing the System: Windows
  • Machine Failures
  • Event Logging
  • AcuConnect Error Messages
  • AcuConnect Distributed Processing: Troubleshooting
  • AcuConnect Thin Client: Troubleshooting
  • Connecting to AcuServer
  • Frequently Asked Questions
Parent topic: AcuConnect Version 10.2.0 User's Guide


Introduction

This help section discusses some system management issues to consider when you oversee AcuConnect® operations. Most UNIX system management functions are performed using the acurcl command described in Managing the System: UNIX. Windows users have two methods for performing management functions: the acurcl command or a graphical control panel, described in Managing the System: Windows.

This help section also discusses machine failures, event logging, and troubleshooting for both the distributed processing and thin client environments.

Parent topic: Managing the System


Managing the System: UNIX

The acurcl command is your control and maintenance interface to AcuConnect. The acurcl command is used on the server at the command line (or with the graphical control panel under Windows) and initiates the following actions:

  • Starts and stops the AcuConnect program and installs and removes AcuConnect as a Windows service
  • Controls the configuration of running instances of AcuConnect
  • Reports AcuConnect system status
  • Creates and maintains the server access and server alias files

When the acurcl command is entered with no options, a list of options (or a graphical control panel in Windows) appears.

The acurcl command formats on UNIX servers are:

acurcl
acurcl –access
acurcl -alias
acurcl -config [server] [-n  port]
acurcl -info [server] [-n port]
acurcl -kill [server] [-f] [-n port] [-p PID]
acurcl -start [-c config_file] [-d] [-e error_file] [-l] [-t #] [-n port]
acurcl -version

In addition to these command formats, the following formats are available on Windows servers:

acurcl -install [server] [-depends ServiceDependency].
                [any valid start options]
acurcl -query [server] [-n  port]
acurcl -remove [server] [-n port]
  • The acurcl Command
Parent topic: Managing the System


The acurcl Command

The following table briefly describes the acurcl command options. Follow the links for detailed descriptions.

acurcl -access | Starts the server access file manager utility.
acurcl -alias | Starts the server alias file manager utility.
acurcl -config | Configures server configuration variables on the fly.
acurcl -info | Returns a report of AcuConnect system status for the current host.
acurcl -install | For Windows servers only, this command installs AcuConnect as a Windows service.
acurcl -kill | Causes the AcuConnect process to halt.
acurcl -query | For Windows servers only, this command allows you to query whether or not the specified Windows service is installed.
acurcl -remove | For Windows servers only, this command shuts down AcuConnect (if it is not already shut down), removes the Windows service for AcuConnect, and removes the service's stored start-up parameters.
acurcl -start | Starts AcuConnect
acurcl -version | Causes the output of the version number of AcuConnect.
  • acurcl -access
  • acurcl -alias
  • acurcl -config
  • acurcl -info
  • acurcl -install
  • acurcl -kill
  • acurcl -query
  • acurcl -remove
  • acurcl -start
  • acurcl -version
Parent topic: Managing the System: UNIX


acurcl -access

The acurcl -access command starts the server access file manager utility. The access file manager is used to create and maintain the database of authorized AcuConnect clients and users. To use -access on a UNIX server, you must be logged in as root or superuser. On a Windows server, you must use -access from the administrator account or from an account that belongs to the administrators group. See The Server Access File for a description of how to use this utility.

Parent topic: The acurcl Command


acurcl -alias

The acurcl -alias command starts the server alias file manager utility. This utility is used to create and maintain the alias file required on the server for thin client operations only. This file holds all the information that is needed to invoke the appropriate runtime on the server. To use -alias on a UNIX server, you must be logged in as root or superuser. On a Windows server, you must use -alias from the administrator account or from an account that belongs to the administrators group. See Creating a Server Alias File in Thin Client for a description of how to use this utility.

Parent topic: The acurcl Command


acurcl -config

You can configure server configuration variables on the fly using the acurcl -config command. The acurcl -config command allows you to change the configuration of a running AcuConnect server, for instance, to turn tracing on or off or to change configuration variables, such as PASSWORD_ATTEMPTS. When you enter this option, you start communicating with the server running on the named server and named port. If no server name is given, the local server is assumed. If no port number is given, the default port is assumed.

Optional arguments to -config include:

Option | Description
server | Specifies the name of the server machine to be configured. If no server is specified, the server is assumed to be the local host.
-n | Identifies a particular instance of the AcuConnect program by port number. The -n must be followed by a space and then an integer, for example, "6524". If no port number is specified, the default port is configured.

After you have entered the -config option, the prompt rclcfg> appears. At this prompt, enter any of the following commands:

GET variable-name
 Gets the value of a single variable. For example:
rclcfg> get password_attempts
PASSWORD_ATTEMPTS: 3

SET variable-name new-value

Sets a variable in the server. For example:

rclcfg> set password_attempts 5

Note that if given an invalid variable name, the remote AcuConnect sets a variable of that name with the given value, even though that variable will not have any effect on the remote AcuConnect. See Creating a Server Configuration File for a list of valid server variables.

Setting certain variables has no effect on the remote AcuConnect, since the variable is used at initialization time and never checked again. For example, trying to set ACURCL_PORT, SERVER_IP, or SERVER_NAME results in an error message such as:

rclcfg> set SERVER_IP 192.215.170.34
Setting the SERVER_IP has no affect
rclcfg> get SERVER_IP
SERVER_IP: 192.215.170.34

Note that a GET command shows the new value, but it is not used.

LIST [{>|>>} file]

Lists the names and current values of all variables of which AcuConnect is aware, including some that do not directly affect AcuConnect. Use the optional {>|>>} file syntax to send the output to a named file instead of the screen. > creates a new file of the specified name, and >> appends the output to an existing file.

! cmd

Causes the command cmd to be executed.

HELP

Prints a quick synopsis of available commands. It looks very similar to the above list.

QUIT
EXIT

These commands exit the configure mode.

Parent topic: The acurcl Command


acurcl -info

The acurcl -info command returns a report of AcuConnect system status for the current host (unless another machine is specified). This report includes all child runtimes that have not yet terminated, including the working directory the runtime was started from, the list of runtime arguments used to start the runtime, and the time that each child runtime was started (in HH:MM:SS.FF format, where "FF" is hundredths of a second).

The status report contains the following fields:

  • The Client field identifies the client machine associated with the child runtime.
  • The User field identifies the client user name associated with the child runtime.
  • The PID is the process ID of the child runtime. Because these PIDs are local to the server machine, they are unique.
  • The Directory is the working directory changed to before executing the child runtime.
  • The Command is the full command line with which the child runtime was invoked. This will include all the options given to the runtime. This command line is not truncated and may wrap around on some screens, depending on how many options are used.

Optional arguments to -info include:

Option | Description
server | Specifies the name of the server machine whose status is to be reported.
-n | Identifies a particular instance of the AcuConnect program by port number. The -n must be followed by a space and then an integer, for example, "6524". If no port number is specified, then status for the default port is reported.
Parent topic: The acurcl Command


acurcl -install

The acurcl -install command is for Windows servers only. It installs AcuConnect as a Windows service. Optional arguments to -install include:

Option | Description
server | Specifies the name of the server machine. If no server is specified, the server is assumed to be the local host.
-depends You can add Windows service dependencies to the installation of AcuConnect as a service. You may include multiple dependencies; simply use the -depends option for each one. The name of the service should be used as the argument following -depends on the command line.

For information on service dependencies, consult your Microsoft Windows documentation.

any valid -start options Any valid -start option can be used for -install. Note that these options are stored for service startup on this particular port. See acurcl -start for a list of -start options. For example, to run the service with the arguments -c c:\etc\server1.cfg -le c:\tmp\server1.log on startup, you would use the following -install command:
acurcl -install -c c:\etc\server1.cfg -le
c:\tmp\server1.log

Installing a service on a particular port resets all startup options for the service on that port. If no options are stored for a service, starting the server on a particular port automatically installs a service on that port and stores the options used. In other words, you can install and run a service with one set of arguments, and then occasionally run the service with different arguments by using acurcl -start.

If you plan to have multiple instances of the AcuConnect service running at the same time, each instance will have a unique name. The name of an installed service will be "AcuConnect X", where X is the port number. If you do not use the -n option, the name of the service will be "AcuConnect".

In a thin client configuration, clients can be assigned to a particular instance of the AcuConnect service via the <server:port> notation of the acuthin command.

Parent topic: The acurcl Command


acurcl -kill

The acurcl -kill command causes the AcuConnect process to halt. If no server is specified, the AcuConnect process is halted on the current host; otherwise, the process is halted on the named host.

To use -kill on a UNIX server, you must be logged in as root or superuser. On a Windows server, you must use -kill from the administrator account or from an account that belongs to the administrators group.

Note that although files are not broken when you use this command, they may not be consistent. If a child runtime is terminated between two file updates that are both required for consistency, the runtime shuts down between them.

Unless the-f option is specified, AcuConnect prompts for confirmation before the halt action is executed, for example:

Shutting down acurcl on: condor
Do you really want to shut down acurcl [N]?

Respond by entering Y or N.

Optional arguments to -kill include:

Option | Description
server | Specifies the name of the server machine to kill. If no server is specified, the server is assumed to be the local host.
-f | Causes the AcuConnect process to terminate immediately, without prompting for confirmation. -f should be used when acurcl -kill is included in a program or script.
-n | Identifies a particular instance of the AcuConnect program by port number. The -n must be followed by a space and then an integer, for example, "6524". If no port number is specified, the default port is terminated.
-p | Causes AcuConnect to terminate an individual child process. The -p must be followed by a space and the process ID of the child process to be terminated.
Note: The AcuConnect process can also be terminated from the command line. For example, on UNIX you could use the command kill -9 (signal #9). However, a signal #9 prevents AcuConnect from performing an orderly shutdown and should never be used when clients are actively using AcuConnect.
Parent topic: The acurcl Command
Related concepts
FORCE_KILL_TIME


acurcl -query

The acurcl -query command is for Windows servers only. It allows you to query whether or not the specified Windows service is installed.

Optional arguments to -query include:

Option | Description
server | Specifies the name of the server machine. If no server is specified, the server is assumed to be the local host.
-n | Identifies a particular instance of the AcuConnect program by port number. The -n must be followed by a space and then an integer, for example, "6524". If no port number is specified, the default port (which has the service name "AcuConnect") is removed.

When you enter this option, you receive a message stating whether or not the service is installed, and if it is, whether or not the service is currently running. The -query command also displays the startup parameters that have been stored for the service, if any. For example:

C:> acurcl -query
Service AcuConnect (AcuConnect 8.0 on the default port (5632)) exists
Start Up: Automatic
Program: C:\microfocus\bin\acurcl.exe
Startup arguments: '-c c:\etc\server1.cfg -le
c:\tmp\server1.log'
Status: running
C:>

Note that the startup arguments listed are the arguments used to install the service and not the arguments given to the currently running server.

Parent topic: The acurcl Command


acurcl -remove

The acurcl -remove command is for Windows servers only. It shuts down AcuConnect (if it is not already shut down), removes the Windows service for AcuConnect, and removes the service's stored start-up parameters.

Optional arguments to -remove include:

Option | Description
server | Specifies the name of the server machine. If no server is specified, the server is assumed to be the local host.
-n | Identifies a particular instance of the AcuConnect program by port number. The -n must be followed by a space and then an integer, for example, "6524". If no port number is specified, the default port (which has the service name "AcuConnect") is removed. See acurcl -install for more information about port numbers.
Parent topic: The acurcl Command


acurcl -start

The acurcl -start command starts AcuConnect. On Windows servers, this option also installs AcuConnect as a Windows service, if it is not already installed. In addition, if no start-up options are stored, acurcl -start stores the start-up options to be used as the default options.

To use -start on a UNIX server, you must be logged in as root or superuser. On a Windows server, you must use -start from the administrator account or from an account that belongs to the administrators group.

Unless the-f option is specified, AcuConnect starts in background. If AcuConnect is already running, it outputs the following message:

acurcl is already running on hostname

and a new AcuConnect process is not started. If you want to start AcuConnect with new options, you must stop and then restart it.

Note: On Windows NT, 2000, or 2003 systems, it is best to specify acurcl -start with no options. This causes it to use the startup parameters that have been stored for the service. Typically, if you specify options with acurcl -start, these options are in effect only until the AcuConnect service is started again. The exception to this is if no startup parameters have been stored for the service. In this case, the parameters that you start AcuConnect with are stored for future startup use.

See Starting AcuConnect for a detailed description of valid arguments to the "-start" command.

Parent topic: The acurcl Command


acurcl -version

The acurcl -version command causes the version number of AcuConnect to be output. -version must be the only argument on the command line.

Parent topic: The acurcl Command


Managing the System: Windows

Windows administrators can manage AcuConnect through a graphical control panel. To access the control panel, enter the acurcl command on the server command line with no options. The control panel has five tabs, which correspond to the various actions available from the command line. You can access help from the graphical control panel by pressing the F1 key, as well as by clicking the Help button.

Note: To use the Control Panel on Windows 2008, where User Access Control security is turned on (as it is by default), any user must choose Run as Administrator in order to use the various Acuserver utilities. UAC can be turned off, in which case the user must merely be a member of the administrators group to fully operate the control panel.

Some of the tabs on the control panel are available only if you have administrator privileges.

  • AcuConnect Control Panel
Parent topic: Managing the System


AcuConnect Control Panel

The AcuConnect control panel contains the following tabs:

  • Access Tab
  • Config Tab
  • Alias Tab
  • Info Tab
  • Services Tab
Parent topic: Managing the System: Windows


Access Tab

The Access tab allows you to maintain the AcuAccess file through the access file manager. To use the access file manager from the control panel, you must be logged onto a Windows server from the administrator account or from an account that belongs to the administrators group. See The Server Access File for detailed information about the AcuAccess file.

The following table describes the contents of each of the fields on this tab.

Field | Description
Client Machine | The official host name by which the client machine is identified on the TCP/IP network. For distributed processing on Windows, this name is found in the Host field under Control Panel > TCP/IP Properties > DNS Configuration. An asterisk (*) in this field means "match all client machines".
Client User Name | The user's login name on the client system. An empty field means "match all client users".
Local User Name | The local user name that AcuConnect will use when fulfilling requests for the client user. If this field is blank, AcuConnect attempts to use the client user name; if that is not a valid name on the server, the value of the DEFAULT_USER configuration variable is used. If DEFAULT_USER is not defined, the connection will be refused (AcuConnect returns an error 9D/103). If DEFAULT_USER is used to connect to AcuConnect on an NTFS partition under Windows NT, 2000, 2003, or 2008, be sure that DEFAULT_USER has both READ (RX) permissions on wrun32.exe and the appropriate permissions to access any file.
Password | The password associated with the local user name.
Confirm Password | Confirmation of the password associated with the local user name.
Umask | The octal value (between 000 and 777) that determines file permissions.

For an example of common access records, see the topic Access Record Composition.

You can use the Access tab to:

  • Creating or Opening an Access File
  • Adding an Access Record
  • Modifying an Access Record
  • Removing an Access Record
Parent topic: AcuConnect Control Panel


Creating or Opening an Access File

The last access file used is already open when you select the Access tab. Use this procedure to create or open another access file.

  1. On the Access tab, click Open.

    The AcuAccess File dialog box appears.

  2. Do one of the following:
    • To open an existing file, navigate to it and click Open.
    • To create a new access file, in the File name field, type the path and file name of a new file, click Open, then click Yes when prompted to create the new file.

The access file appears, ready to be edited.

Parent topic: Access Tab
Related information
Adding an Access Record
Modifying an Access Record
Removing an Access Record


Adding an Access Record

Use this procedure to add a record to the access file.

  1. On the Access tab, with the required access file open, click New.

    The Access User dialog box appears.

  2. Complete the options as follows:
    Field | Description
    Client Machine The official host name by which the client machine is identified on the TCP/IP network. For distributed processing on Windows, this name is found in the Host field under Control Panel > TCP/IP Properties > DNS Configuration.

    An asterisk (*) in this field means "match all client machines".

    Client User Name

    The user's login name on the client system. An empty field means "match all client users".

    Local User Name The local user name that AcuConnect will use when fulfilling requests for the client user. If this field is blank, AcuConnect attempts to use the client user name; if that is not a valid name on the server, the value of the DEFAULT_USER configuration variable is used. If DEFAULT_USER is not defined, the connection will be refused (AcuConnect returns an error 9D/103).

    If DEFAULT_USER is used to connect to AcuConnect on an NTFS partition under Windows NT, 2000, 2003, or 2008, be sure that DEFAULT_USER has both READ (RX) permissions on wrun32.exe and the appropriate permissions to access any file.

    Password | The password associated with the local user name.
    Confirm Password | Confirmation of the password associated with the local user name.
    Umask | The octal value (between 000 and 777) that determines file permissions.
  3. Click OK.

    The record is added to the access file.

Parent topic: Access Tab
Related information
Creating or Opening an Access File
Modifying an Access Record
Removing an Access Record


Modifying an Access Record

Use this procedure to edit the details of an existing record in the access file. You can only modify the local user name, password, and umask details.

  1. On the Access tab, with the required access file open, select the required record.
  2. Click Modify.

    The Access User dialog box appears.

  3. Modify the Local User Name, Password fields and Umask, as required, then click OK.

    The record is modified.

Parent topic: Access Tab
Related information
Creating or Opening an Access File
Adding an Access Record
Removing an Access Record


Removing an Access Record

Use this procedure to remove an existing record from the access file.

  1. On the Access tab, with the required access file open, select the required record.
  2. Click Delete.

    The record is removed from the access file.

Parent topic: Access Tab
Related information
Creating or Opening an Access File
Adding an Access Record
Modifying an Access Record


Config Tab

The Config tab allows you to view and set the status of the current configuration settings of a running server. You can use the Config tab to:

  • Change the server and port
  • Add variables to the running server
  • Modify the values of variables

The list box on the Config tab displays the variables and their values associated with the server and port shown in the fields at the top of the tab. The following table describes the contents of each of the fields on this tab.

Field | Description
Variable Name | The name of a configuration variable that has been added to the server configuration file.
Value | The value that has been assigned the variable.
  • Changing the Server and Port You Are Viewing
  • Adding a Variable to the Running Server
  • Modifying the Value of a Variable
Parent topic: AcuConnect Control Panel


Changing the Server and Port You Are Viewing

Follow the procedure below to change the server and port you are viewing.

  1. On the Config tab, click Query. The Connect to server dialog box appears.
  2. Type or select from the Server list the name of the server you wish to view.
  3. Type or select from the Port list the name of the port you wish to view on the server.
  4. Click OK to apply your selections.
The information for the new server and port appears in the list box.
Parent topic: Config Tab
Parent topic: Config Tab
Related tasks
Adding a Variable to the Running Server
Modifying the Value of a Variable


Adding a Variable to the Running Server

Follow the procedure below to add a variable to the running server.

  1. On the Config tab, click New. The Configuration Variable dialog box appears with blank fields.
  2. In the Name field, type the name of the variable you wish to add.
  3. In the Value field, type the value for the variable you added.
  4. Click OK to add the variable to the server.
Parent topic: Config Tab
Parent topic: Config Tab
Related tasks
Changing the Server and Port You Are Viewing
Modifying the Value of a Variable


Modifying the Value of a Variable

Follow the procedure below to modify the value of a variable.

  1. In the list box on the Config tab, select the variable you want to modify, then click Modify. The Configuration Variable dialog box appears with the selected variable in the Name field and its value in the Value field.
  2. In the Value field, type the value you want for the variable.
  3. Click OK to apply the new value.
Parent topic: Config Tab
Parent topic: Config Tab
Related tasks
Changing the Server and Port You Are Viewing
Adding a Variable to the Running Server


Alias Tab

Before using AcuConnect for thin client operations, you must create a single association file, called an alias file, to hold all the information that is needed to invoke the appropriate application on the server. To create thin client aliases from the control panel, you must be logged on to a Windows server from the administrator account or from an account that belongs to the administrators group.

The following table describes the contents of each of the fields on this tab.

Field | Description
Alias Name | The name of an alias.
Working Directory | The default directory in which the runtime looks for all files specified on the alias command line.
Command Line | The full command line used to invoke the alias, including all the options given to the runtime.

You can use the Alias tab to:

  • Creating an Alias File and Record
  • Modifying an Alias Record
  • Deleting an Alias Record
Parent topic: AcuConnect Control Panel


Creating an Alias File and Record

Follow the procedure below to create an alias file.

  1. On the Alias tab, click Open and browse to the folder in which you want to save the file.
  2. Enter a file name. You are told the file does not exist and asked if you want to create it. Click Yes.
  3. Click New to add a new alias entry to the alias file. The Alias Properties dialog box appears with blank fields.
  4. In the Alias Name field, enter the name of the alias you want to add. For example, you might enter reserve for an airline reservation service.
  5. In the Working Directory field, enter the directory in which the COBOL object files for this alias can be found. (This must be an existing directory.)
  6. Click OK to add this entry to the alias file.
  7. Repeat the procedure for each record you want to add to the alias file.
  8. Click OK to apply your changes.
Parent topic: Alias Tab
Related tasks
Modifying an Alias Record
Related information
Deleting an Alias Record


Modifying an Alias Record

Follow the procedure below to modify an alias record.

  1. In the list box on the Alias tab, select the alias you want to modify. If you want to modify a record in a different alias file, open the alias file first. Click Modify. The Alias Properties dialog box appears, displaying the properties of the selected alias.
  2. To change the properties of the alias working directory, enter the information you want to appear in the Working Directory field.
  3. To change the properties of the command line for the alias, enter the information you want to appear in the Command Line field.
  4. Click OK to apply your changes.
Parent topic: Alias Tab
Related tasks
Creating an Alias File and Record
Related information
Deleting an Alias Record


Deleting an Alias Record

To delete an alias record, select the alias you want to delete in the list box on the Alias tab, then click Delete.

Parent topic: Alias Tab
Related tasks
Creating an Alias File and Record
Modifying an Alias Record


Info Tab

The Info tab allows you to list and terminate child processes. Use the Info tab to:

  • List child processes
  • Update the list box display
  • Automatically update the list box display
  • Terminate child processes

The following table describes the contents of each of the fields on this tab.

Field | Description
Client | The name of the client machine associated with the child runtime.
User | The client user name associated with the child runtime.
PID | The process ID (PID) of the child runtime.
Start time | The time the runtime started.
Working Directory | The default directory in which the runtime looks for all files specified on the alias command line.
Command Line | The full command line used to invoke the child runtime, including all the options given to the runtime.
  • Listing Child Processes
  • Updating the List Box Display
  • Updating the List Box Display Automatically
  • Terminating a Child Process
Parent topic: AcuConnect Control Panel


Listing Child Processes

Follow the procedure below to list child processes.

  1. On the Info tab, click Query. The Connect to server dialog box appears.
  2. From the Server list, select a server for the child process.
  3. From the Port list, select a port for the child process.
  4. Click OK to apply your changes.
The server you selected appears in the Server field, the port you selected appears in the Port field, and the child processes for the selected server/port combination are now listed in the Info tab list box.
Parent topic: Info Tab
Parent topic: Info Tab
Related tasks
Updating the List Box Display Automatically
Related information
Updating the List Box Display
Terminating a Child Process


Updating the List Box Display

To update the information displayed on the Info tab, click Refresh.

Parent topic: Info Tab
Parent topic: Info Tab
Related tasks
Listing Child Processes
Updating the List Box Display Automatically
Related information
Terminating a Child Process


Updating the List Box Display Automatically

Follow the procedure below to update the list box automatically.

  1. On the Info tab, click Query. The Connect to server dialog box appears.
  2. Check the Auto Refresh checkbox.
  3. In the list box, specify the number of seconds you want between updates.
  4. Click OK to apply your changes.
Parent topic: Info Tab
Parent topic: Info Tab
Related tasks
Listing Child Processes
Related information
Updating the List Box Display
Terminating a Child Process


Terminating a Child Process

To terminate a child process, select the child process in the list box and choose Kill.

Parent topic: Info Tab
Parent topic: Info Tab
Related tasks
Listing Child Processes
Updating the List Box Display Automatically
Related information
Updating the List Box Display


Services Tab

The Services tab allows you to add, start, stop, and remove services, as well as view or modify the properties of an existing service or the configuration and error files associated with that service. When you choose this tab, services that are currently running are marked with a green bullet and services that are currently stopped are marked with a red bullet.

The following table describes the contents of each of the fields on this tab.

Field | Description
Port | The port number on which AcuConnect is running.
Command line | The full command line used to invoke the runtime, including all the options.
  • Adding a Service
  • Starting, Stopping, or Removing a Service
  • Adding Dependencies to a Service
  • Editing the Configuration File
  • Viewing the Error File
Parent topic: AcuConnect Control Panel


Adding a Service

To add a service, click New on the Services tab. In the Service Properties dialog box, select the options you wish to add to your new service. The following table lists and briefly describes the options available to you.

Field | Description
Configuration file | Use Browse to specify the name and path of the configuration file for the server.
Error file | Use Browse to specify an error file for the server.
Trace level Selecting a trace level from this list turns on the tracing function. If you have specified an error file in the Error file field, trace information is placed in the named error file.

Trace level can be "1" through "7":

"1" provides information about access file match attempts. The trace information buffer is flushed to the error file when the buffer is filled or the service terminates.

"2" provides information about runtime requests. The buffer is flushed to the error file when the buffer is filled or the service terminates.

"3" provides the information described for "1" and "2".

"5" is equivalent to "1", but the tracing buffer is flushed to the error file each time an access file match is requested. (File trace flushing can also be controlled with the FILE_TRACE_FLUSH server configuration variable. See Creating a Server Configuration File for more information.

"6" is equivalent to "2", but the tracing buffer is flushed to the error file each time a runtime is requested.

"7" provides the information described for "5" and "6".

Compress trace output | Causes the file specified in Error file to be compressed using the gzip compression method.
List configuration variable settings | Checking this checkbox causes a listing of the server configuration file to be printed to standard error output. This can be helpful when you are debugging problems that may be related to configuration variables. If you have specified an error file, the listing is captured in this file.
Dependencies You can add the name of a Windows service or service group on which AcuConnect depends. (You may include multiple dependencies.) Click Add to display a list of possible services and service groups.

Note that if you enter dependencies in this field, AcuConnect will not start unless each service named is currently installed on the server as a service.

For information on service dependencies, consult your Microsoft Windows documentation.

Parent topic: Services Tab
Related information
Starting, Stopping, or Removing a Service
Adding Dependencies to a Service
Editing the Configuration File
Viewing the Error File


Starting, Stopping, or Removing a Service

To start, stop, or remove a service, select the service in the list box on the Services tab and click:

  • Start to start the service
  • Stop to stop the service
  • Remove to remove the service
    Note: Be certain that you in fact want to remove the record you select. You will not be asked if you are sure, and the action cannot be undone.
Parent topic: Services Tab
Related information
Adding a Service
Adding Dependencies to a Service
Editing the Configuration File
Viewing the Error File


Adding Dependencies to a Service

Follow the procedure below to add dependencies to a service.

  1. In the Service Properties dialog box, click Add to the right of the Dependencies list.

    The Service Dependencies list box appears.

  2. From the list, select a dependency you want to add to this service.
  3. Click OK to add this selection.
  4. Repeat this procedure until you have added all of the dependencies you want for this service.
  5. In the Service Properties dialog box, click OK to apply your changes.
Parent topic: Services Tab
Related information
Adding a Service
Starting, Stopping, or Removing a Service
Editing the Configuration File
Viewing the Error File


Editing the Configuration File

Use this procedure to edit the current configuration file (acurcl.cfg):

  1. On the Services tab, select the required service.
  2. Click Edit config ....

    The acurcl.cfg file associated with the service is displayed in Notepad.

    If there is no configuration file already in place, you are prompted to add one.

  3. Edit the file, as required, then save and close Notepad.
    Note: The control panel will remain in a 'wait' state until you close Notepad.
Parent topic: Services Tab
Related information
Adding a Service
Starting, Stopping, or Removing a Service
Adding Dependencies to a Service
Viewing the Error File


Viewing the Error File

Use this procedure to view or edit the error file:

  1. On the Services tab, select the required service.
  2. Click Edit error file ....

    The error file associated with the service is displayed in Notepad. If the service is currently running, then the file will be in use; therefore, a snapshot of the file is taken, and it this copy that is displayed. The file is opened in Notepad, where you can edit and save it, as required.

  3. View and/or edit the file, as required, then save and close Notepad.
    Note: The control panel will remain in a 'wait' state until you close Notepad.
Parent topic: Services Tab
Related information
Adding a Service
Starting, Stopping, or Removing a Service
Adding Dependencies to a Service
Editing the Configuration File


Machine Failures

Two major concerns regarding client and server machine failures are:

  • What happens to open files/programs when a server crashes?
  • How are other clients and servers affected by a crash?

When a client application or connection is terminated with Ctrl+C or a kill command (other than a kill -9), AcuConnect detects the termination and closes all files/programs held open for that client process. However, other terminal software and hardware failures are not detected. Note that although files are not broken when you use this command, they may not be consistent. If a child runtime is terminated between two file updates that are both required for consistency, the runtime shuts down between them.

Should the server go down, all clients actively using AcuConnect get access errors when attempting to communicate with the server. Client systems must terminate their current applications and wait for the return of the server. All files that were open on the server at the time of the termination are left in an unknown state and may be corrupt.

Note: If AcuConnect is automatically started when the server boots, AcuConnect should be immediately halted.

Before you start AcuConnect, you should check all files that might have been affected by the termination and, if necessary, rebuild them. After you have verified all files, you can start the acurcl daemon.

To view an AcuConnect system status report, issue the acurcl -info command. In Windows, you can use the graphical control panel's Info tab to check the status of active child runtimes. Click Query to select a server/port combination and list the child processes running on the selected server.

Parent topic: Managing the System


Event Logging

AcuConnect can write to the Windows event notification system or the UNIX system log when information or error messages need to be reported to the System Administrator. Such information might be generated when an unexpected termination occurs or a broken file is detected. If your operating system supports it, the UNIX version of AcuConnect writes to the syslog facility. If your operating system does not support syslog, it writes this information to the console.

The Windows version can write to the event log of other machines in the network. Set the WINNT_EVENTLOG_DOMAIN configuration variable to the UNC name of the computer to which all event log messages should be sent. This variable must be set in the configuration file and is not changeable. Note that if this variable is not set, system logging information is sent to the local machine on which the server is executing.

You should be aware that some Windows administration expertise may be required to implement this feature on a complex Windows network. For example, you can start AcuConnect on one server and send event log information to a different server. If you are Administrator on one machine but not on the other machine, however, the log file is not created and no error message informs you of that fact.

Parent topic: Managing the System


AcuConnect Error Messages

In the course of operations, AcuConnect may produce error messages that inform you of system problems. Error messages that appear when AcuConnect cannot be started are seen on the server by the system administrator who is trying to start AcuConnect, or on a client by a user who is trying to establish a connection to AcuConnect and start a client runtime.

Error messages that appear when a remote program cannot be started via AcuConnect may be different depending on whether AcuConnect is deployed in a distributed processing or thin client environment. See Distributed Processing Error Messages and Thin Client Error Messages for the various messages that are generated when a remote application cannot be started.

acurcl Start-up Errors

Messages generated as a result of the inability to start AcuConnect are different depending on the operating system. Two conditions can be responsible for the set of messages that appear when AcuConnect does not start: a missing or expired AcuConnect license file or a missing AcuAccess file.

Messages that appear when AcuConnect does not start:

Message | Description
License file './acurcl.alc' inaccessible. | In a UNIX/Linux environment, indicates that the license file is missing.
This license for the AcuConnect product has expired. Please contact your software vendor for assistance | Indicates that the user license is expired.
Access file '/etc/AcuAccess' not found. | In a UNIX/Linux environment, indicates a missing server access file.
The AcuConnect service failed to start. Invalid or missing license. | From the graphical control panel in Windows, indicates that the AcuConnect license file is missing or expired, or that the server access file is missing.
Parent topic: Managing the System


AcuConnect Distributed Processing: Troubleshooting

This help section describes error messages in AcuConnect's distributed processing configuration. Many of these procedures require access to root or administrator privileges and are intended for use by your site's system administrator.

  • Distributed Processing Error Messages
  • Unexpected User Name
  • Connection Refused
  • Invalid Password
  • AcuConnect Fails to Start
  • Problems Starting and Stopping Services
Parent topic: Managing the System


Distributed Processing Error Messages

In distributed processing, AcuConnect generates the following set of error messages after an unsuccessful attempt to start a program via the AcuConnect remote listener.

Program missing or inaccessible. Indicates that the program would not start, possibly because:
  • The called program cannot be found or permissions to execute the program do not exist.
  • The ACUCONNECT_RUNTIME_FLAGS variable contains incorrect parameters, such as an invalid error file path.
  • Permission to write to the server runtime error file does not exist.
  • AcuConnect cannot find the server runtime.
  • The server runtime license is expired or missing (Windows servers only).
  • The called program's return code indicates a failed call.
Connection refused - perhaps acuconnect is not running. Unable to start the server runtime.

Possible explanations for this message include:

  • AcuConnect is running on a port other than the one specified in the connection attempt.
  • The server runtime license is expired or missing (UNIX/Linux servers only).
  • The AcuAccess file does not allow access or it is missing.
Connection refused - User count exceeded on remote server. The number of users allowed by the runtime or distributed processing license has been exceeded.
Invalid license or license not found for this connection type.

The acurcl.clc license file is missing.

Various file status codes may also be returned to the client as error messages.

Refer to the topics in this help section for tips on resolving some of the system problems that can cause these error messages to appear.

Parent topic: AcuConnect Distributed Processing: Troubleshooting


Unexpected User Name

AcuConnect establishes a connection with the client, but uses an unexpected user name (Local Username). There are two common reasons for getting an unexpected Local Username on the server:

  1. The client machine/client user combination doesn't match the expected access record.
  2. The client machine/client user combination matches an access record that specifies an unexpected Local Username (perhaps the name of a group account, or an account with restricted privileges).

To investigate and correct this situation, you must be familiar with AcuConnect server access configuration and have access to root or administrator privileges. Work with your AcuConnect system administrator. See Diagnosing Unexpected User Errors on a UNIX Server and Diagnosing Unexpected User Errors on a Windows Server for more information.

  • Diagnosing Unexpected User Errors on a UNIX Server
  • Diagnosing Unexpected User Errors on a Windows Server
Parent topic: AcuConnect Distributed Processing: Troubleshooting


Diagnosing Unexpected User Errors on a UNIX Server

Follow the procedure below to diagnose unexpected user errors on a UNIX server.
  1. Confirm your client user name. Log on to the client system using the same user name and UNIX environment that resulted in the unexpected user name. At the UNIX prompt, enter:
    who am i

    Is the user name returned the name you expected?

  2. Confirm the name of the client system. Enter:
    hostname

    The system will return its official network host name.

  3. On the server, examine the server access file for the record that matches the client machine name/client user name combination. Run the server access file manager utility:
    acurcl -access
    Note: This task requires root privileges on a UNIX server. It should be done by the AcuConnect system administrator.
    1. Be sure to enter the name of the working server access file when prompted.
    2. Select menu item [4], Display one/all security records.
    3. Respond N to the Display all records? prompt.
    4. To the next two prompts, provide the client machine name and client user name, respectively. The matching record will be displayed.
    The AcuConnect system administrator should be able to determine whether this is the appropriate and expected access record for the client machine name/client user name combination and take any necessary steps to modify the record, or add a new one.
Parent topic: Unexpected User Name


Diagnosing Unexpected User Errors on a Windows Server

Follow the procedure below to diagnose unexpected user errors on a Windows server.
  1. Confirm the name of the client system:
    • In Windows XP, choose Start > Settings > Control Panel > Network > Configuration menu. Click TCP/IP, then choose Properties > DNS Configuration > Host. The name you specify for the "Host" entry is the one that the runtime uses.
    • In Windows NT/2000/2003, choose Start > Settings > Control Panel > Network > Protocols.Click TCP/IP, then choose Properties > DNS > Host Name. The name you specify for the "Host Name" entry is the one that the runtime uses.
  2. On the server, examine the server access file for the record that matches the client machine name/client user name combination. Run the server access file manager utility:
    acurcl -access
    Note: This task requires administrator group privileges on a Windows server. It should be done by the AcuConnect system administrator.
    1. Be sure to enter the name of the working server access file when prompted.
    2. Select menu item [4], Display one/all security records.
    3. Respond N to the Display all records? prompt.
    4. To the next two prompts, provide the client machine name and client user name, respectively. The matching record will be displayed.
    The AcuConnect system administrator should be able to determine whether this is the appropriate and expected access record for the client machine name/client user name combination and take any necessary steps to modify the record, or add a new one.
Parent topic: Unexpected User Name


Connection Refused

Attempts to connect to the server fail, possibly returning a 9D/ 103, connection refused error. Connection refused errors occur for a variety of reasons:

  • The matching access record specifies an invalid Local Username, or DEFAULT_USER holds an invalid user name. Note that the use of same as client in the Local Username field of the access record can lead to the attempted use of an invalid user name (same as client directs AcuConnect to use the Client Username as the Local Username).
  • There is no matching access record for the client machine name/client user name combination.
  • If connecting to a UNIX server, the AcuConnect license on the server may require that the acushare license manager be running, and AcuConnect was not able to start acushare automatically.
  • If connecting to a Windows server, various limitations in Windows can prevent a child runtime from starting.

To investigate and correct this situation, you must be familiar with AcuConnect server access configuration and have access to root or administrator privileges. Work with your AcuConnect system administrator. See Diagnosing Connection Refused Errors on a UNIX Server and Diagnosing Connection Refused Errors on a Windows Server for more information.

  • Diagnosing Connection Refused Errors on a UNIX Server
  • Diagnosing Connection Refused Errors on a Windows Server
Parent topic: AcuConnect Distributed Processing: Troubleshooting


Diagnosing Connection Refused Errors on a UNIX Server

Follow the procedure below to diagnose connection refused errors on a UNIX server.
  1. Confirm your client user name. Log on to the client system using the same user name and UNIX environment that resulted in the unexpected user name. At the UNIX prompt, enter:
    who am i

    Is the user name returned the name you expected?

  2. Confirm the name of the client system. Enter:
    hostname

    The system will return its official network host name.

  3. On the server, examine the server access file for the record that matches the client machine name/client user name combination. Run the server access file manager utility:
    acurcl -access
    Note: This task requires root privileges on a UNIX server. It should be done by the AcuConnect system administrator.
    1. Be sure to enter the name of the working server access file when prompted.
    2. Select menu item [4], Display one/all security records.
    3. Respond N to the Display all records? prompt.
    4. To the next two prompts, provide the client machine name and client user name, respectively. The matching record will be displayed.
  4. If there is no matching entry, you need to add one:
    • If the Local Username field contains the name of a user (a string), check the UNIX password file (/etc/passwd) for the presence of a valid entry for that name. If no entry exists, the name is not valid.
    • If the Local Username field is "same as client", Local Username is set to the value of Client Username. Check the UNIX password file (/etc/passwd) for the presence of a valid entry for that name.
    • If the Local Username field is blank, Local Username is set to the value of the server configuration variable DEFAULT_USER. The value of DEFAULT_USER is defined in the server configuration file. Check the UNIX password file (/etc/passwd) for the presence of a valid entry for that name.
  5. Confirm that acushare is running on the UNIX server by issuing the acushare command with no arguments. If you receive a usage message, acushare is not running and may be manually started using the acushare -start command.
Parent topic: Connection Refused


Diagnosing Connection Refused Errors on a Windows Server

Follow the procedure below to diagnose connection refused errors on a Windows server.
  1. Confirm the name of the client system:
    • In Windows XP, choose Start > Settings > Control Panel > Network > Configuration menu. Click TCP/IP, then choose Properties > DNS Configuration > Host. The name you specify for the "Host" entry is the one that the runtime uses.
    • In Windows NT/2000/2003, choose Start > Settings > Control Panel > Network > Protocols.Click TCP/IP, then choose Properties > DNS > Host Name. The name you specify for the "Host Name" entry is the one that the runtime uses.
  2. Confirm the name of the client system. Enter:
    hostname

    The system will return its official network host name.

  3. On the server, examine the server access file for the record that matches the client machine name/client user name combination. Run the server access file manager utility:
    acurcl -access
    Note: This task requires root privileges on a UNIX server. It should be done by the AcuConnect system administrator.
    1. Be sure to enter the name of the working server access file when prompted.
    2. Select menu item [4], Display one/all security records.
    3. Respond N to the Display all records? prompt.
    4. To the next two prompts, provide the client machine name and client user name, respectively. The matching record will be displayed.
  4. If there is no matching entry, you need to add one:
    • If the Local Username field contains the name of a user (a string), check the UNIX password file (/etc/passwd) for the presence of a valid entry for that name. If no entry exists, the name is not valid.
    • If the Local Username field is "same as client", Local Username is set to the value of Client Username. Check the UNIX password file (/etc/passwd) for the presence of a valid entry for that name.
    • If the Local Username field is blank, Local Username is set to the value of the server configuration variable DEFAULT_USER. The value of DEFAULT_USER is defined in the server configuration file. Check the UNIX password file (/etc/passwd) for the presence of a valid entry for that name.
  5. Determine whether you have reached the Windows limit on the number of simultaneous child runtimes. The CHILD_WAIT configuration variable contains a value for the number of milliseconds that AcuConnect waits for a child runtime to start successfully. If the child runtime subsequently stops, check the trace file for the entry "Child runtime stopped!! Exit code is nnn." If nnn is "128", the Windows limit has been reached and no additional child runtimes are allowed until another runtime process is terminated. Refer to Microsoft Knowledge Base article 184802, "User32.dll or Kernel32.dll Fails to Initialize," to learn how to work around this limitation.
Parent topic: Connection Refused


Invalid Password

Attempts to connect to the server fail with an invalid password error:

Invalid connection password specified by client.

Invalid password errors occur for two reasons:

  • The password supplied via interactive input does not match the password in the access record.
  • The password supplied by the application via the acu_client_password variable does not match the password in the access record.

Because password transactions involving acu_client_password are invisible to the user, the cause of these failures is not immediately obvious. If you are getting the error message given above, but you're not being prompted for a password, the application is using acu_client_password. The value of acu_client_password is set when the application is installed. (Note that the value of acu_client_password should terminate with LOW-VALUES.) See Passwords for Clients for more information about acu_client_password.

To resolve this problem:

  • If the error occurred after a password prompt, work with your AcuConnect system administrator to establish a new password or to have the password requirement removed.
  • If no password prompt occurred, ask the application's technical support group to change or remove the acu_client_password. Contact your application vendor.
Parent topic: AcuConnect Distributed Processing: Troubleshooting


AcuConnect Fails to Start

Perform the following procedure if AcuConnect fails to start.
  1. Verify that Windows and UNIX permissions are set correctly on the files. See Establishing System Security for more information.
  2. In Windows, verify the status of the service. To do this, enter:
    sc query acurcl

    The system should display the current state of AcuConnect and should say "RUNNING". If the service is not running, the system will return an error message similar to the following:

    [sc]EnumQueryServiceStatus:OpenService failed 1060
    Note: Another method for verifying the status of the service is to select: Start > Settings > Control Panel > Services and then check the AcuConnect service status. You should see "Started" under "Status". You may also check the Event Viewer for more information. Select these options: Start > Programs > Administrative Tools > Event Viewer > Log > Application.
  3. Examine AcuConnect service events to determine if there were any errors at startup.
Parent topic: AcuConnect Distributed Processing: Troubleshooting


Problems Starting and Stopping Services

You have problems starting or stopping the services or receive a message that the service has stopped when it has not. Be sure to stop services the same way you start them:

  • A service started using the Server Manager interface should be stopped using the same interface.
  • A service started on the command line should be stopped using the command line.
Parent topic: AcuConnect Distributed Processing: Troubleshooting


AcuConnect Thin Client: Troubleshooting

Many things can affect the way the server application and the ACUCOBOL-GT Thin Client interact. For example, computers can crash, networks can get interrupted, or other errors can occur. These help topics outline some areas you should be aware of as you use our Thin Client technology. Limitations and restrictions involved in running your application in the thin client are described in Limitations in Thin Client Environments.

  • Thin Client Error Messages
  • Tuning System Performance
Parent topic: Managing the System


Thin Client Error Messages

Error messages are produced in a thin client environment as a result of the following basic scenarios: AcuConnect cannot be started, a server connection cannot be made, or a remote application cannot be started via AcuConnect. See AcuConnect Error Messages for the messages generated when AcuConnect cannot be started. The following table provides links to the messages in the other two categories.

If you try to connect to a Windows server, limitations in Windows can prevent a child runtime from starting, resulting in a "Connection failed" error message. See Diagnosing Connection Refused Errors on a Windows Server to help determine whether you have reached this Windows limit and how to work around it.

Connection failed. General socket error. | A server connection cannot be established, possibly because of a busy socket.
Connection failed. Connection to server refused. | A server connection cannot be established. Specific reasons for this error message include a missing or invalid license file (acurcl.alc), an AcuAccess file that is missing or not allowing access for this particular user, or the use of a port number that is not available for some reason.
Connection failed. Alias does not exist. | A server connection cannot be established, because an alias file does not exist or the alias file does not contain the requested alias.
Connection failed. Unknown error. | Invalid working directory is specified in your alias file (when running on VMS).
Connection failed. Server failed to start remote process. Check messages on the server. | Invalid error file path and/or name in the alias file.
prog-name: Program missing or inaccessible. | The specified remote application could not be started.
You have exceeded the licensed number of users for ACUCOBOL-GT. If you would like to add users, please contact your customer service representative. | Indicates that the maximum number of runtime users in thin client has been exceeded.
Parent topic: AcuConnect Thin Client: Troubleshooting


Tuning System Performance

Thin Client technology may make some functions expensive in terms of system performance. Adjustments have been to minimize the amount of message traffic between the client and the server. For example, if a program resizes a window to be larger than the available screen space, the operation succeeds, because checking for failure is an expensive operation.

Frequent message traffic as a result of communications between screen controls on the display host and an application on the server can negatively affect thin client performance. To identify operations that may be causing performance issues for the thin client, you can establish a screen trace to monitor network message traffic on a slow screen. You can start with a trace of a frequently used screen if it is not clear which screen is causing your performance issue.

One way to improve system performance is to recompile your programs to the Version 5.2 or later object format. In older object files that use MODIFY to set control properties frequently, the thin client must return status to the runtime after each MODIFY statement that sets a property value. When you recompile, thin client sends status back to your program only if the program uses that status value.

  • Buffer Size Considerations
  • File Compression
  • TC_CONTROL_SYNC_LEVEL Runtime Configuration Variable
  • TC_TV_SELCHANGING Configuration Variable
  • Graphical Control Event Handling
  • Screen Section Table Handling
  • Grid Control
  • Bitmaps
  • Multiline Entry Fields
Parent topic: AcuConnect Thin Client: Troubleshooting


Buffer Size Considerations

Configuration variables that let you adjust internal network buffer sizes can help to improve thin client performance by increasing the amount of data that travels across the network at any one time.

The AGS_RECEIVE_BUFFER_SIZE and AGS_SEND_BUFFER_SIZE variables control the internal network buffers in the low-level socket routines. The ACUCOBOL-GT thin client and runtime call these routines to send data across the network. Every time data is sent across the network, it must be acknowledged from the other side. So increasing the size of these buffers may enhance performance, because sending more data at a time means fewer acknowledgement messages. Making these buffers larger has the most impact when a large amount of data is sent back and forth. Note that the buffer size won't change the performance characteristics in situations where data must be sent immediately.

The AGS_MAX_SEND_SIZE variable can work in tandem with the two BUFFER_SIZE variables mentioned above to help with performance. This variable works best if its value matches the BUFFER_SIZE values. For example, if AGS_MAX_SEND_SIZE is 8000 bytes and AGS_SEND_BUFFER_SIZE is 16000 bytes, the send buffer does not fill completely before the socket layer decides that data should be sent.

Parent topic: Tuning System Performance


File Compression

File compression is another factor to consider in system performance, and the AGS_SOCKET_COMPRESS variable can help address this issue. If the speed of your computer is much higher than the speed of the network, the "ZLIB" setting for this variable may work well for you. However, if the latency caused by compression time is higher than the latency in the network, you may not gain much. RUNLENGTH compression is faster, but much less is compressed.

As an example, suppose you need to send 10000 bytes over a network that can transfer 1000 bytes per second. With no compression, the data can be sent in 10 seconds. If ZLIB compression can compress that 10000 bytes to 1000 bytes in 20 seconds, the total time for this operation is 21 seconds (20 seconds to compress plus 1 to send). In this case, no compression is the better option. However, if ZLIB can compress that 10000 bytes to 2000 bytes in 2 seconds, the total time with ZLIB is 4 seconds (2 seconds to compress plus 2 to send). In this situation, the compression option is the better choice.

Note that Windows supports ZLIB compression, but not all UNIX machines do. If ZLIB compression is not supported on a particular machine, a variable value of "ZLIB" will be ignored.

Parent topic: Tuning System Performance


TC_CONTROL_SYNC_LEVEL Runtime Configuration Variable

Normal runtime behavior ensures that VALUE data items in a Screen Section are updated whenever a BEFORE, AFTER, or EXCEPTION procedure executes. This can result in decreased performance under the thin client. You can determine which VALUE data items are updated by the setting of the TC_CONTROL_SYNC_LEVEL configuration variable. Limiting updates can mean improved performance. See TC_CONTROL_SYNC_LEVEL. for more information about this configuration variable.

Parent topic: Tuning System Performance


TC_TV_SELCHANGING Configuration Variable

The tree view control normally generates a Msg-Tv-Selchanging event in some unexpected circumstances. For example, this event is generated when a tree view becomes active, even if the selection in the tree view is not changing. The frequency with which these events are passed between the client and the server can cause performance issues.

The TC_TV_SELCHANGING configuration variable lets you control how often Msg-Tv-Selchanging events are generated in a thin client environment. Different values for this variable enable you to suppress the generation of this message event to varying degrees. See TC_TV_SELCHANGING for more information about this configuration variable.

Parent topic: Tuning System Performance


Graphical Control Event Handling

Three runtime configuration variables give you some control over which events your application receives. Letting the thin client filter out some events can reduce network traffic and enhance performance. TC_EVENT_LIST and TC_AX_EVENT_LIST can contain the numeric value of an event type or a list of event types separated by non-numeric characters. TC_AX_EVENT_LIST is for .NET or ActiveX event types. If the value of TC_EXCLUDE_EVENT_LIST is "1", the specified events are not sent to your program. See Creating a Runtime Configuration File for the Remote Server Component for more information about these variables.

Three common control properties perform the same functions for individual graphical controls. EVENT-LIST and AX-EVENT-LIST properties allow you to specify a list of event types to either send or block from the program, depending on the value of the EXCLUDE-EVENT-LIST property. By default, listed events are sent to the program. See Common Screen Options in the ACUCOBOL-GT Reference Manual for detailed information about these properties.

One advantage to using the configuration variables for these functions is that you don't have to change your application code. For example, if program performance is affected by a single ActiveX control type or events that have unique type numbers, these are easily specified in a configuration file. Using the configuration variables is also an easy way to test whether this feature can improve system performance.

Parent topic: Tuning System Performance


Screen Section Table Handling

The Compiler produces some internal data items to hold intermediate values when a Screen Section USING, TO, or FROM data item is indexed or reference modified. In the thin client, this behavior is extended so that it uses the same intermediate item when both the FROM and TO items refer to the same data item, consuming slightly less memory. As a result, a program with a Screen Section that stores its values in tables may be able to use the performance benefit of a lower TC_CONTROL_SYNC_LEVEL configuration setting. See TC_CONTROL_SYNC_LEVEL for more information about this configuration variable.

Parent topic: Tuning System Performance


Grid Control

Because the performance of some controls may be affected in a thin client environment, some control properties may need to be changed. The grid control experiences performance delays when the user clicks and drags the mouse to highlight several cells in the grid. To avoid this, the thin client does not generate the MSG-GOTO-CELL-DRAG event. This prevents you from highlighting a region of the grid during drag operations via the REGION-COLOR property.

The grid control supports a DRAG-COLOR property, which allows you to perform highlighting during a drag operation. You can use this with both the thin client and with the stand-alone runtime.

For more information about the DRAG-COLOR property, refer to the grid control description in the ACUCOBOL-GT User Interface Programming Guide.

Parent topic: Tuning System Performance


Bitmaps

A program that uses bitmaps can be slower than one that does not. The first time a bitmap is displayed, it must be transferred from the server to the client. The bitmap is then placed in a memory cache on the client so that it doesn't have to be downloaded again. However, network messages travel between client and server regardless of whether the bitmap has already been downloaded to the client.

Bitmap download performance can be enhanced via the W$BITMAP library routine WBITMAP-LOAD process. Setting the WBITMAP-LOAD parameter FLAGS to WBITMAP-NO-DOWNLOAD optimizes bitmap handling. When WBITMAP-NO-DOWNLOAD is used, the server assumes that the bitmap is already in the client's cache directory and that the client can successfully load the bitmap. The server need not wait for a result code from the client that the bitmap is successfully loaded. For more information about W$BITMAP and the WBITMAP-LOAD function, refer to the appendix "Library Routines" in ACUCOBOL-GT Appendices.

Using .jpg files instead of .bmp files can also improve system performance, because .jpg files are compressed and therefore are smaller and transfer more quickly over the network.

Parent topic: Tuning System Performance


Multiline Entry Fields

A multiline entry field with a compressed size larger than the value of AGS_MAX_SEND_SIZE may experience degraded performance in thin client. Although the default value of AGS_MAX_SEND_SIZE should be adequate in most situations, large multiline entry field performance may improve if the value is increased from its default of 16000 characters. Note that if compression is enabled, it is performed before the calculation of maximum packet size. See AGS_BAD_SOCKET for more information.

Parent topic: Tuning System Performance


Connecting to AcuServer

It is possible that the ACUCOBOL-GT runtime may appear to hang if the application host needs to open files on a remote (third) machine using AcuServer® and a password is needed. The problem may appear in one of two ways:

  1. If the runtime is on a UNIX machine and the remote file is an error file or a configuration file, the runtime and the ACUCOBOL-GT Thin Client both hang. Note that in this instance, if the remote file is requested after the COBOL program has started, the password dialog appears as expected.
  2. If the runtime is running on a Windows machine, the runtime and the ACUCOBOL-GT Thin Client both hang.

You can avoid this behavior by not requiring passwords on machines running AcuServer if the files on the AcuServer machine are needed by the ACUCOBOL-GT runtime serving the thin client.

Parent topic: Managing the System


Frequently Asked Questions

Question:

Can AcuConnect load object files on mapped server drives?

Answer:

AcuConnect starts a new instance of the ACUCOBOL-GT runtime for each client request for an application to be executed. This runtime can locate object files on a Windows server mapped drive only if the drive mapping has occurred at an administrator level at system startup.

To load object files on a Windows server mapped drive in this way, you must ensure that the SECURITY_METHOD configuration variable defines the type of Windows security to be used for the connection. See SECURITY_METHOD. for more information.

Question:

Is the Windows print spooler supported in the thin client?

Answer:

Generally speaking, all functionality of the Windows print spooler is supported except the following WIN$PRINTER functions:

  • WINPRINT_GET_SETTINGS_SIZE
  • WINPRINT_GET_SETTINGS
  • WINPRINT_SET_SETTINGS

These functions are not supported because of variations in memory allocated by data types on the client and the server (for example, a 64-bit UNIX server versus a 32-bit Windows client). Instead, you can make calls to WINPRINT_GET_PRINTER_INFO_EX and WINPRINT_SET_PRINTER, which are similar.

See Printing in Thin Client for information about these functions.

Question:

I am using ACCEPT user-id FROM SYSTEM-INFO to return details about the user that is running a specific copy of the application, but the returned user ID is "root". How can I ensure that the correct user information is returned?

Answer:

To return the actual user ID of the user who is executing the application on a UNIX server, AcuConnect must be started automatically at server startup or by a user that logs onto the server as root and then logs out of the system. When a subsequent client user starts an application that executes ACCEPT user-id FROM SYSTEM-INFO, the correct user ID is returned.

To return the correct user ID when a program is running on a Windows server, AcuConnect must be started as a Windows service and SECURITY_METHOD must be set to LOGON.

See Starting AcuConnect at System Startup for information about starting AcuConnect automatically at system startup or as a Windows service.

Question:

I have an application that contains branching code, which is used when the application is executed on either UNIX or Windows servers. The code relies on information that is returned about the operating system by ACCEPT FROM SYSTEM-INFO.

However, with the thin client, the information returned is from the server side of the configuration. How can I obtain information about the client side, so that the application is executed using the correct client-side information?

Answer:

ACCEPT FROM SYSTEM-INFO returns server-side information for the thin client environment. To obtain client-side information, you should modify your existing code to perform an ACCEPT FROM TERMINAL-INFO.

Question:

If a thin client application is launched from a Web browser, does that application have Web browser access? Should a hyperlink be included on the screen?

Answer:

The thin client does not run in a Web browser. However, you could use the Web browser control inside your application to allow Web browser access, or include your links on the same Web page that launches the application.

Question:

Are there any restrictions regarding the use of ActiveX or COM objects?

Answer:

You can use ActiveX controls. However, they must be installed on the client machine. Note that some controls may generate too many messages to be usable over the Internet. See Installing ActiveX Files for information about installing ActiveX controls.

COM and Distributed COM objects maybe used with Thin Client.

Parent topic: Managing the System


AcuServer Version 10.2.0 User's Guide

  • Copyright Statement
  • Introduction
  • Preparing Your UNIX Network
  • Preparing Your Windows Network
  • Configuration
  • Administrator Utilities and Functions
  • System Security
  • Programming for AcuServer
  • System Management
  • Glossary of Terms
Parent topic: extend Product Guides


Introduction

  • Overview
  • Implementation Details
  • Technical Services
Parent topic: AcuServer Version 10.2.0 User's Guide


Overview

Welcome to the AcuServer file server, a client/server technology that provides remote file access services to ACUCOBOL-GT® applications running on UNIX and Windows TCP/IP-based networks.

With AcuServer, your applications gain:

  • The ability to create and store data files on any UNIX, Windows NT, Windows 2000 to 2008 server equipped with AcuServer.
  • Full function remote access from UNIX and Windows clients to all Vision, relative, sequential, and object files stored on an AcuServer server.
  • Full record locking support of all Vision and relative files.
  • Transparent access of remote and local files.

(Some applications that contain hard-coded paths to files must be modified to use the FILE_PREFIX or CODE_PREFIX environment variable, or to include the name of the file server in the path. See Accessing Remote Files for a discussion of name strategies.

AcuServer does not require that you recompile your existing programs. Programs compiled with any version of ACUCOBOL-GT can be executed by any later version of ACUCOBOL-GT. ACUCOBOL-GT runtimes are available for most UNIX and Windows platforms. Contact our customer service representative for a current list of supported platforms.

AcuServer can be combined with other extend technologies to provide access to data in networked, client/server, and distributed computing environments. It can be used with the ACUCOBOL-GT Web Runtime to provide access to data over the World Wide Web (with permission). It can be used with ACUCOBOL-GT's CGI technologies to provide Internet access to data through an HTML front end. And it can be combined with AcuConnect® to facilitate file distribution and optimize network performance in a distributed computing setting.

Pictured below is a simple AcuServer network. ACUCOBOL-GT applications running on UNIX and Windows client systems access and store data files on a common UNIX, Windows NT, Windows 2000 to 2008 file server running AcuServer. More complex networks might incorporate multiple AcuServer file servers supporting dozens of client machines running multiple applications.

Note: Your AcuServer version number and your ACUCOBOL-GT runtime version number should match. Programs compiled with earlier versions of ACUCOBOL-GT can be executed, provided that the version of ACUCOBOL-GT runtime and AcuServer are the same.

References to Windows in this manual denote any of the supported Windows platforms, which are listed in the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx. Where it is necessary to make a distinction, the specific version name/number is specified. .

Parent topic: Introduction


Implementation Details

AcuServer provides remote file access services through the use of a memory resident program (daemon or service) named acuserve, running on the file server. The client application executes using an ACUCOBOL-GT runtime. The runtime must be the same version as AcuServer.

The runtime recognizes access requests to remote files and uses socket calls to acuserve to fulfill the requests.

On the server, acuserve waits for file access requests, manages their execution, and returns the result to the client requester.

A typical AcuServer interaction might be:

  1. An application running on a network machine attempts to READ a file.
  2. The ACUCOBOL-GT runtime recognizes that the file to be read is located on a remote system and packages the request to acuserve on the file server.
  3. acuserve receives the request, executes the READ, and returns the result to the client, completing the interaction.
  • Remote File Access Performance
  • Record Locking
  • System Security
  • System Load Balancing
  • Server Licensing
  • Vision Files
  • International Character Handling
Parent topic: Introduction


Remote File Access Performance

AcuServer provides excellent network file access performance by using sockets as the principal communication protocol. Here’s why.

With the exception of a few unusual systems, remote file access always takes significantly more time than the same access made to a local file. It is not unusual for network overhead to add five fold or more to the time required to complete a common file action.

As the preceding drawing illustrates, a file access request (in this case a READ) can require multiple disk I/O actions. When these multiple disk actions are executed across the network, overhead is added to every I/O action. Some network protocols, notably NFS (Network File System), require that each disk action be handled as a separate network transaction.

Using sockets, AcuServer executes file I/O requests with a single network transaction. In this way, AcuServer minimizes network overhead, resulting in superior performance.

Ordinarily, AcuServer returns a single record in each packet sent over the network. If you are reading a large number of sequential records without user interaction (for instance, if you are generating a report), you can optimize performance even further by using AcuServer’s multiple-record mode. In this mode, AcuServer returns multiple records in each network packet. (By default, it returns ten records at a time, but this number is configurable.) Not all files are suited for multiple-record mode, however, and some limitations are imposed. See Multiple-Record Modefor more information on this mode.

Parent topic: Implementation Details


Record Locking

Record locking support is exactly the same as that provided in the local environment. Any indexed or relative file opened in I/O mode can have records locked. Three server configuration variables, LOCKS_PER_FILE, MAX_FILES, and MAX_LOCKS are used to tune AcuServer record locking support.

Parent topic: Implementation Details


System Security

AcuServer includes a transparent layer of remote file access security. This security system allows you to configure AcuServer access to be as open or restrictive as suits your needs. AcuServer uses a site-configured server access file (database) to validate the access privileges of service requesters. Optional password protection allows you to assign each user an individual password, which the user must then supply to AcuServer when making an initial service request.

On a Windows NT, Windows 2000 to 2008 server, AcuServer system security is designed to work with files that reside on an NTFS (NT file system). (AcuServer can work with a FAT file system, but the files are less secure.) For NTFSs, you may set read and write access permissions on your files by using the Windows security features. Refer to your Windows documentation for more information about NTFSs and security procedures.

In addition, whether you are on UNIX or Windows, you have the option of implementing native system security rather than AcuServer system security. This option is described in more detail in Security Overview.

Encryption

AcuServer offers support for data encryption. For any given service requestor (client process), you can instruct AcuServer to encrypt all data exchanged with that requestor. The encryption option and how to enable it is described in detail in Encryption.

Note: The use of encryption can impose a significant performance cost. The performance cost is determined by the quantity of data being exchanged, the speed and bandwidth of the network, and the computational power of both the client and AcuServer host machines. If you plan to use encryption, you should test and benchmark your application with encryption enabled prior to deployment to ensure that performance meets your requirements.
Parent topic: Implementation Details


System Load Balancing

For large networks, you can help to optimize performance by obtaining a multiple-server license for AcuServer. This license enables you to start two or more instances of the acuserve daemon or service on the same server machine simultaneously. This gives you two options to help you balance the network load:

  • You can assign each client runtime to a specific instance of the daemon.
  • You can designate one instance of the acuserve daemon as a master (primary) server, which distributes the load among multiple additional instances of the daemon (secondary servers). This process is described in ACUSERVER_MASTER_SERVER.
Parent topic: Implementation Details


Server Licensing

AcuServer is shipped with a product code and product key that defines the licensing capabilities specified in your purchase agreement. When you supply your key information during installation, the Activator creates a license file encoded with the maximum number of acuserve instances allowed for your site. See License Files for Windows in the Getting Started Guide for details on the Activator license utility.

To confirm the number of instances supported on your server, log onto the server and enter:

acuserve  -v

If you require support for additional acuserve instances, you can easily update your license by contacting your Micro Focus extend sales representative.

If you are deploying your application with the ACUCOBOL-GT Web Runtime (an ActiveX component) and will be accessing your data via AcuServer, special licensing considerations apply. Specifically, unless your users have a local or network runtime license file installed, you must have a multiple-user ACUCOBOL-GT runtime license file on the server. You need to have a license file that can accommodate the total number of concurrent remote users that you anticipate. (If you anticipate 100 concurrent users, you need a 100-user runtime license file on the server in addition to the AcuServer license file.)

The runtime license file must be located in the same directory or folder as the acuserve executable and must be named runcbl.alc (on Windows systems, this requires that you make a copy of the Windows runtime license file, wrun32.alc, and name it runcbl.alc.) When an application running in the Web Runtime makes a service request, AcuServer notices that the request is from a Web Runtime connection and attempts to secure an authorization for the connection from the runtime license file. When a Web Runtime user disconnects from AcuServer by exiting the COBOL program, the authorization is released and made available to subsequent users. If the number of Web Runtime users exceeds the number of users allowed by the license file, the COBOL program receives a file status code 9D,105 and the following message is output to AcuServer’s error log:

You have exceeded the licensed number of clients for AcuServer. If you would like to add clients, please contact your customer service representative.

See A Programmer’s Guide to the Internet for more information on using the ACUCOBOL-GT Web Runtime with AcuServer.

Note: Nothing in this document is intended to amend the terms and conditions of the applicable license agreement between you and Micro Focus. Rather, this document is meant to summarize the various aspects of our licensing technology, which is required to operate AcuServer. The terms and conditions of your licensing of AcuServer shall continue to be governed by the applicable license agreement between you and Micro Focus.
Parent topic: Implementation Details


Vision Files

The Vision file system is the default file system used with ACUCOBOL-GT for all environments other than VMS.

AcuServer creates Vision Version 6 files by default. AcuServer can also be used to build and access Vision Version 3, 4, and 5 files. Version 5 and later files are generated in a dual file format, with data records stored in one segment and overhead key information stored in another.

For information on building Vision files in a version other than the default, see V_VERSION in Server Configuration Variables.

Parent topic: Implementation Details


International Character Handling

International character translation is supported in AcuServer environments. The translation process is handled by the client runtime, which uses an XFD (eXtended File Descriptor) and a user-defined map file to accomplish the translation. See International Character Handling in the ACUCOBOL-GT User’s Guide for a detailed description of international character handling.

To take advantage of international character mapping support you must:

  • Create an XFD for each data file that contains fields that you want to have translated.

    Use the -Fx or -Fa compile option to create an XFD file. Note that only fields of type CHARACTER can be translated. See Compiler and Runtime in the ACUCOBOL-GT User’s Guide for more information.

  • Create a map file.

    The map file specifies the values that characters are translated into before being passed to the server or translated back from before being passed to the program. The map file can map any character value in the range 0 to 255. Map files are described in detail in International Character Handling in the ACUCOBOL-GT User’s Guide.

  • On the client, set the DEFAULT_MAP_FILE or server_MAP_FILE configuration variable to point to your map file (see Appendix H of Book 4 of the ACUCOBOL-GT documentation set).
Parent topic: Implementation Details


Technical Services

For the latest information on contacting customer care support services go to:

http://www.microfocus.com/about/contact

For worldwide technical support information, visit:

http://supportline.microfocus.com/xmlloader.asp?type=home

Parent topic: Introduction


Preparing Your UNIX Network

  • Getting Started on UNIX
  • UNIX System Requirements
  • Installing a UNIX Server
  • AcuServer System Security
  • Installing the Client
Parent topic: AcuServer Version 10.2.0 User's Guide


Getting Started on UNIX

There are three basic steps to using AcuServer® file server software in a UNIX environment.

  1. Install AcuServer.

    If you have not already installed AcuServer on your UNIX server, see UNIX System Requirements and Installing a UNIX Server for a list of installation requirements and procedures.

    If AcuServer is already installed, proceed to the next step. There is nothing on the AcuServer distribution media to install on the client machine. However, you should ensure that every client system that will use AcuServer has a licensed copy of an ACUCOBOL-GT® runtime, the same version as AcuServer. You may need to set up client passwords, user names, and host names. See Installing the Client for more information.

  2. Configure the AcuServer system.

    AcuServer system configuration consists of:

    • Assigning values to the runtime configuration variables.

      With the exception of the FILE_PREFIX and possibly CODE_PREFIX variables, none of the runtime configuration variables requires modification. See Runtime Configuration Variables for information about runtime configuration variables.

    • Assigning values to the AcuServer configuration variables.

      None of the server configuration variables requires modification; however, you may want to modify them to gain control over or initiate certain functions like file locking, multiple-record mode, or error trace flushing. If you want to implement UNIX security rather than AcuServer system security, you must set the SECURITY_METHOD variable to LOGON in both the runtime and server configuration files. See Server Configuration Variables for information about server configuration variables.

    • Creating the server access file.

      AcuServer file access security is managed by a site-configured access file called the server access file. You must create a server access file (default name /etc/AcuAccess) before AcuServer will start or establish connections with clients. See Creating or Opening an Access File for step-by-step instructions. See The Server Access File for general information about the file.

    • Assigning and verifying UNIX ownerships and permissions on AcuServer's executable, access, and configuration files, as well as existing data files and directories.

      AcuServer will not run on a UNIX server unless proper ownerships and permissions are set. Setting ownerships and permissions requires root privileges. Use the UNIX utilities chown and chmod to set ownerships and permissions, as described in Ownerships and Permissions.

    • Modifying your runtime configuration file or application code to use remote name notation.

      To use AcuServer, your applications must use remote name notation to reference files located on the server. The ACUCOBOL-GT runtime looks for remote name notation to identify requests to AcuServer. Remote name notation has the format @servername:pathname. You may add a remote path to the FILE_PREFIX or CODE_PREFIX configuration variables. Alternatively, you can define file name aliases in the runtime configuration file. A file name alias is a string that will replace the literal name in the ASSIGN TO clause of a SELECT statement. See Accessing Remote Files for more information on remote name notation.

  3. Issue AcuServer commands.

    AcuServer services are handled by the acuserve daemon running on the server. The acuserve command can be invoked from the command line to start and stop AcuServer (the acuserve daemon), retrieve AcuServer operation status, unlock stranded files, and create and maintain the server access file. See Administrator Utilities and Functions for complete details.

Be aware that the configuration of AcuServer system security is very important to safeguarding your data files and network computers. See the information in System Security before placing AcuServer into open service.

Parent topic: Preparing Your UNIX Network


UNIX System Requirements

For UNIX platforms, AcuServer software is shipped on CDROM, 4 mm Dat, 8 mm tape, or cartridge tape in TAR format.

To install and use AcuServer:

  • All servers must be networked to clients with TCP/IP. (TCP/IP is not sold or supplied by Micro Focus.)
  • Unless you have an unlimited license for AcuServer, all UNIX servers must run the current version of acushare, which is included on the AcuServer distribution media. See Reducing the Size of the run-time in the ACUCOBOL-GT User's Guide for more information.
  • All servers must have a copy of the license file activated by the product installation script. This file is named acuserve.alc.
  • Servers being accessed by the ACUCOBOL-GT Web Runtime must have a multiple-user ACUCOBOL-GT runtime license that accommodates each concurrent user that is anticipated. (If you anticipate 100 concurrent users of the Web Runtime, you need a 100-user runtime license on the server in addition to the AcuServer license file.) Alternatively, runtime users can install a local or network floating license for the runtime themselves.

What is the license file?

AcuServer is shipped with a product code and product key that define the licensing capabilities specified in your purchase agreement. When you supply your key information during installation, the Activator creates a license file that contains information such as the product’s version number, serial number, expiration date, and server count. After installation, AcuServer must be able to locate the license file to function.

AcuServer searches for the license file in the same directory as the executable, acuserve. The license file is named acuserve.alc.

If you move the AcuServer executable to a new directory, be sure to move a copy of the license file as well. If no license file is found, or if the information in the license file does not permit execution, AcuServer exits with an error message.

What is acushare?

The acushare utility is required for all installations that do not have an unlimited license. The acushare utility monitors and enforces the site license.

Parent topic: Preparing Your UNIX Network


Installing a UNIX Server

To install AcuServer on a UNIX server:

  1. Create a directory on the server to hold the AcuServer software.

    We recommend that you install AcuServer directly into the ACUCOBOL-GT home directory.

  2. Change directory (cd) into the target directory and extract the AcuServer software as described on the Getting Started card that came with your product.

    Follow the instructions on the card, entering your product code and product key when prompted.

    If you want to use the server configuration file in its default location, move etc/a_srvcfg into the /etc directory. This may require root or superuser privileges. The server configuration file does not need to reside in its default location, but if the file is located elsewhere, the name and location of the configuration file must be specified with the -c option each time acuserve is started. Regardless of where the server configuration file is located, the file must not be writeable by anyone other than root for AcuServer to function. See Starting and Stopping acuserve for more information about server configuration.

AcuServer is now fully installed and ready for configuration on the UNIX server. See Configuring AcuServer for the settings that can be configured for the server.

Note: If you do not have a network card in your machine, or if your network card is not working properly, AcuServer will fail to install and run.
Parent topic: Preparing Your UNIX Network


AcuServer System Security

To establish a secure and functional AcuServer system, it is important to restrict access to the acuserve executable, server configuration files, and server access files.

In addition, you will need to set appropriately restrictive ownerships and permissions for your existing data files and directories.

  • Ownerships and Permissions
  • File Access Security
  • Setting Ownerships and Permissions
  • File Access Security
  • Setting Permissions on New Files
Parent topic: Preparing Your UNIX Network
Parent topic: Preparing Your Windows Network


Ownerships and Permissions

Proper ownerships and permissions on the acuserve executable file, server configuration files, server access files, and existing data files and directories are essential to establishing a secure and functional AcuServer system.

UNIX settings

Setting ownerships and permissions requires root privileges on UNIX systems. Use the commands chown, chgrp, and chmod to set ownerships and permissions. For details regarding UNIX file permission masks and the use of chown, chgrp, and chmod, see your UNIX operating system manuals.

UNIX ownerships and permissions on AcuServer files

UNIX ownerships and permissions must be assigned to key AcuServer files as specified in the following table.

FILE NAME | OWNER | PERMISSIONS
acuserve (executable file) | root | 755
AcuAccess (and server access files having other names) | root | 600
a_srvcfg (and server configuration files having other names) | root | 644

The permissions specified in the above table are the least restrictive (most permissive) settings allowed for each file. The specified permissions are the optimal permissions for most installations. However, more restrictive permissions may be assigned (though more restrictive permissions could prevent some AcuServer users from using some AcuServer functions. For example, if the acuserve executable file were assigned permissions of 700, no user other than root could execute the acuserve -info command to generate a report of current AcuServer system status).

If the files named in the preceding table do not possess the specified ownerships and permissions (or more restrictive permissions), AcuServer will not start.

You must also set appropriate ownerships and permissions on existing data files and directories. Appropriate ownerships and permissions are those that allow file access to the individuals and groups that require access and that disallow access to all others. See your UNIX operating system documentation for a discussion of file permissions and file security.

Ownerships and permissions on new files

When a client application makes its initial request to AcuServer for services, the requester is validated for permission to use AcuServer. If the requester is permitted to use AcuServer, a user name is assigned to the requester based on the Local Username field of the matching server access record. Files created for that requester by AcuServer get the user and group ownerships of the assigned Local Username. See AcuServer Connection Logic for more information.

unmask

The read and write permissions set on new files are determined by the umask specified in the matching server access record (because all files created are data files, execute permission is not applicable).

On UNIX servers, the umask is a variable having a three-digit octal value, similar to that used by chmod, but which describes the permissions that are not to be set on new files. The value of each digit, subtracted from seven, gives the corresponding chmod value. For instance, a umask of 002 corresponds to a chmod value of 775 (however, because execute permission is not applicable to data files, AcuServer actually sets the chmod value to 664). A umask of 002 grants read and write permissions to user and group, and read only permissions to other. Another common umask is 007, which sets read and write permissions for user and group, and no permissions for other. For more about umask, see your UNIX operating system documentation.

Parent topic: AcuServer System Security


File Access Security

AcuServer allows users of UNIX networks to choose between the system security that AcuServer offers and the security features offered by their own operating system. By default, AcuServer system security is used to govern file access.

If you use AcuServer security, the AcuAccess and AcuAccess.vix files are used to establish user access privileges. Remember that these two files must be readable and writable only by Administrator and System, or AcuServer will not start.

Note: If you experience a problem with file access, it can be helpful to give the users Full Control of the files and directories they need to use. After everything is working smoothly, reduce access to Read-Only if desired. However, be sure to test each program to make sure that everything continues to function as you expect with the reduced privileges.

If you prefer to use UNIX security mechanisms, you may do so by setting the configuration variable SECURITY_METHOD to LOGON in both the runtime configuration file and server configuration file. See Server Configuration Variables for more information about the SECURITY_METHOD configuration variable.

Note that if you decide to use UNIX security instead of AcuServer system security, your users will have whatever permissions the system administrator has set up for them.

Parent topic: AcuServer System Security


Installing the Client

There is nothing on the AcuServer distribution media to install on the client machine. However, you should ensure that every client system that will use AcuServer has a licensed copy of an ACUCOBOL-GT runtime and that AcuServer and the runtime share the same version. To check a runtime's version, use the -v option on the client runtime command line. The runtime displays information similar to the following:

ACUCOBOL-GT runtime version 8.0
Serial number 1234
Licensed for 2 processes
AcuServer client
Vision version 5 file system
Copyright ©) 1988 - 2008, Micro Focus (IP) Ltd.

Look for the line AcuServer client and a runtime version number that matches the version of AcuServer that you are running. If these two criteria are not met, the client machine cannot access data using AcuServer.

  • Passwords for Clients
  • Setting Up the Host Name
  • Setting Up the User Name
  • Confirming Network Services
Parent topic: Preparing Your UNIX Network


Passwords for Clients

If you require a client password to access the server machine, you can prompt the user for this password and store it in the variable Acu_Client_Password, or you can let the runtime prompt for it. See Passwords for more information on user passwords.

Parent topic: Installing the Client
Parent topic: Installing the Client


Setting Up the Host Name

The runtime system on each client machine passes the client host name to the server machine.

Windows 2000/2003/XP/Vista

For Windows 2000 or 2003 and Windows XP clients, right-click the My Computer icon on the desktop and select Properties from the pop-up menu.

  • On a Windows 2000 or 2003 client, select the Network Identification tab of the System Properties window.
  • On a Windows XP or Vista client, select the Computer Name tab of the System Properties window.

In most instances, the computer name listed in the Full computer name field is the host name used by the runtime.

You can also verify the host name by typing the command hostname at the Windows command prompt.

Windows NT

  1. On Windows NT clients, open the Network folder in the Control Panel and select Protocols.
  2. Select TCP/IP and click Properties.
  3. Select the DNS tab and find the Host Name entry.

    The name you specify for Host Name is the one that the runtime uses.

UNIX

On UNIX clients, the runtime uses the host name that is in the file /etc/ hosts.

Parent topic: Installing the Client
Parent topic: Installing the Client


Setting Up the User Name

For Windows clients logged into a Windows NT network, the runtime uses the NT domain user name that the user logged in with. For Windows clients that are not logged into a Windows NT network, the runtime uses the user name value that is set by the environment variable USERNAME. If USERNAME is not set, the runtime uses the value that is set by the environment variable USER. (The values assigned to these variables are case-sensitive. Be sure that the case used in the AcuAccess file matches the case of the value set in the variable.) If neither of these environment variables is set, then the runtime uses the name USER.

The acuserve service is usually run as the SYSTEM account. If you need to change the account used by the acuserve service, be sure that the new account has all of the appropriate permissions for a file server.

For UNIX clients, the runtime uses the user name that the user logged in with.

Parent topic: Installing the Client
Parent topic: Installing the Client


Confirming Network Services

On UNIX and Windows clients, confirm that your TCP/IP software is loaded and running.

If desired, use ping to confirm that the server is up and responding to the network. From your client system, type:

ping hostname

Ping should return:

hostname is alive

Alternatively, you can use our AcuPing program, which is found in the Start > Programs > Acucorp 8.x.x > AcuServer menu. See Diagnosing Errors with C$PING for more information about AcuPing.

Parent topic: Installing the Client
Parent topic: Installing the Client


Preparing Your Windows Network

  • Getting Started in Windows
  • Windows Installation Requirements
  • Installing a Windows NT/2000/2003/2008 Server
  • Setting Up Accounts
  • AcuServer System Security
  • Installing the Client
  • Using AcuServer’s Graphical User Interface for Windows
Parent topic: AcuServer Version 10.2.0 User's Guide


Getting Started in Windows

There are six basic steps to using AcuServer® file server software in a Windows environment.

  1. Install AcuServer. If you have not already installed AcuServer on your Windows NT, or Windows 2000 - 2008 server, see Windows Installation Requirements and Installing a Windows NT/2000/2003/2008 Server for a list of installation requirements and procedures. If AcuServer is already installed, proceed to the next step.

    There is nothing on the AcuServer distribution media to install on the client machine. However, you should ensure that every client system that will use AcuServer has a licensed copy of an ACUCOBOL-GT® runtime, and you may need to set up client passwords, user names, and host names. See Installing the Client for more information.

  2. Set up user and/or group accounts. Decide how users will access resources on the server machine (individual accounts or group accounts). See Setting Up Accounts for more information. Create the user accounts and grant user rights, including access to the server from the network.
  3. Edit the AcuAccess file on the server. AcuServer will not start if the server access file cannot be found. By default, this file is named AcuAccess and is located in the c:\etc directory. If your server’s operating system is located on a drive other than c, AcuServer will look for the AcuAccess file in the \etc directory on the drive containing the operating system.

    See Creating or Opening an Access File for step-by-step instructions for configuring the access file. See The Server Access File for general information about the file.

    • If you choose to implement AcuServer system security, each record in the server access file should contain client machine name, client username, local username, and umask data. Passwords may also be defined if desired.
    • If you choose to implement Windows security (recommended) rather than AcuServer system security, the access records need only contain client machine, username, and if using the LOGON option, password data.
    Note: On Windows 2008 it is essentially required that you use the operating system’s security methods. This is mainly due to a new security layer called User Account Control (UAC). Consult Windows Help for information on how UAC impacts file and program access.

    If the access file is not owned by Administrator or the Administrators group, or is writable by users that do not have Administrator privileges, AcuServer will not start.

  4. Create or modify the directory structure that will be used by AcuServer clients. Ensure that user accounts have FULL CONTROL access to the directory containing the data and object files. If files already exist, modify the permissions for each file to give the users FULL CONTROL access.
  5. Configure the AcuServer system. AcuServer system configuration consists of:
    • Assigning values to the runtime configuration variables. With the exception of the FILE_PREFIX and possibly CODE_PREFIX variables, none of the runtime configuration variables requires modification. See Runtime Configuration Variables for information about runtime configuration variables.
    • Assigning values to the AcuServer configuration variables. Most of the server configuration variables require no modification; however, you may want to modify them to gain control over or initiate certain functions like file locking, multiple-record mode, or error trace flushing. If you want to implement Windows security rather than AcuServer system security, you must set the SECURITY_METHOD variable in both the runtime and server configuration files. If running on Windows 2008, using Windows security is essentially required. See Server Configuration Variables for information about server configuration variables.
    • Modifying your runtime configuration file or application code to use remote name notation. To use AcuServer, your applications must use remote name notation to refer to files located on the server. The ACUCOBOL-GT runtime looks for remote name notation to identify requests to AcuServer. On Windows NT/2000-2008 servers, the format for this notation is @servername:drive-letter:\pathname. You may add a remote path to the FILE_PREFIX or CODE_PREFIX configuration variables. Alternatively, you can define file name aliases in the runtime configuration file. A file name alias is a string that will replace the literal name in the ASSIGN TO clause of a SELECT statement. See Accessing Remote Files for more information on remote name notation.
  6. Issue AcuServer commands. AcuServer requests are handled by the acuserve service running on the server. You can use the Windows AcuServer Control Panel or the command line to start and stop AcuServer (the acuserve service), retrieve AcuServer operation status, unlock stranded files, and create and maintain the server access file. See Administrator Utilities and Functions for details about the AcuServer Control Panel and the acuserve command.
    Note: To use the AcuServer Control Panel on Windows 2008 where UAC is turned on (as it is by default), any user must choose Run as Administrator in order to use the various Acuserver utilities. UAC can be turned off, in which case the user must merely be a member of the administrators group in order to fully operate AcuServer.

Be aware that configuration of AcuServer system security is very important to safeguarding your data files and network computers. See the security information in System Security before placing AcuServer into open service.

Parent topic: Preparing Your Windows Network


Windows Installation Requirements

For Windows networks, AcuServer software is distributed via FTP or on CD-ROM.

To install and use AcuServer:

  • All servers must be networked to clients with TCP/IP. (TCP/IP is not sold or supplied by Micro Focus).
  • All servers must have a copy of the AcuServer license file activated by the product installation script. This file is named acuserve.alc.
  • Servers being accessed by the ACUCOBOL-GT Web Runtime must have a multiple-user ACUCOBOL-GT runtime license that accommodates each concurrent plug-in user that is anticipated. (If you anticipate 100 concurrent users of the plug-in, you need a 100-user runtime license on the server in addition to the AcuServer license file.)
  • Windows clients can run any TCP/IP software that uses a WINSOCK-compliant WSOCK32.DLL.
  • Client machines must have the current runtime. Use the -v option at the runtime command line to verify runtime version.

What is the license file?

AcuServer is shipped with a product code and product key that defines the licensing capabilities specified in your purchase agreement. When you supply your key information during installation, the Activator creates a license file that contains information such as the product’s version number, serial number, expiration date, and server count. The license file is named acuserve.alc. After installation, AcuServer must be able to locate the license file in order to function. AcuServer searches for the license file in the same directory as the executable, acuserve.

If you move the AcuServer executable to a new directory, be sure to move a copy of the license file as well. If no license file is found, or if the information in the license file does not permit execution, AcuServer exits with an error message.

Parent topic: Preparing Your Windows Network


Installing a Windows NT/2000/2003/2008 Server

To install AcuServer on a Windows NT, Windows 2000 - 2008 server:

  1. Install and configure TCP/IP before installing AcuServer. If you do not have a network card in your machine, or if your network card is not working properly, AcuServer will fail to install and run.
  2. Log onto your server using the Administrator account or an account that belongs to the Administrators group. For Windows 2008, if you do not log in using the Administrator account you will need to use Windows elevated privileges to install AcuServer.
    Note: If you are using an earlier release of AcuServer, you can either install the new release while AcuServer is running or stop AcuServer and then install the new software. If you install the new release while AcuServer is running, you must reboot the machine before the new software will take effect.
  3. Insert the product installation CD-ROM into your disk drive. If the installation program does not start automatically, click Start, select Run, and enter the path to the setup file. The path will be something like d:\setup.exe, where d is the drive letter for your CD-ROM drive.

    Follow the instructions on the screen. When prompted to select a component to install, select AcuServer.

  4. If you already have the files \etc\AcuAccess and \etc\a_srvcfg, the setup utility will detect them and will ask you if you want to overwrite them.
    CAUTION:
    Do not overwrite these files unless you have a backup copy.

    The AcuAccess file contains one access record that gives all users access to AcuServer. The file a_srvcfg contains the server configuration variables; when the file is first installed, these are all commented out. You can modify both of these files later, if desired.

  5. If you want the AcuServer file server to start automatically on boot, acuserve must be installed and started as a Windows NT/Windows 2000 - 2008 service. You can install and start the service after initial setup either through the AcuServer Control Panel or by using the acuserve command from the Windows command line.

    Note that installing a service on a particular port resets all start-up options for the service on that port. These options are stored so that the service will use them when starting.

    The default service is named AcuServer. All other service names include the port on which to run.

    The Start Menu folder contains shortcuts to the AcuServer Control Panel, the AcuPing utility, and online documentation. The Start Menu folder is not required to run AcuServer. You can safely remove it.

  6. If you choose to start AcuServer during the installation process, a command prompt window is displayed showing the status of the Windows NT/Windows 2000 - 2008 services being started or restarted automatically. You may see some error messages that can be ignored if the Windows services are not already installed and running. For example, you might see:
    acuserve -kill
      Open/Control Service failed
acuserve -remove
      Open/Control Service failed
acuserve -install
      AcuServer service installed
acuserve -start
      STATE: START PENDING

    The Windows NT/Windows 2000 - 2008 services that are needed for AcuServer can also be started and stopped manually. See Starting and Stopping acuserve for a detailed explanation of how to start and stop acuserve services.

    See Installing and Removing acuserve as a Windows Service for more information about removing a service after installation. Note that removing the service does not delete the executables.

    To help in resolving service problems, some messages from these services display in Microsoft Event Viewer’s Application Log. The Event Viewer is found in the Administrative Tools folder of the Windows Control Panel.

Parent topic: Preparing Your Windows Network


Setting Up Accounts

As you configure AcuServer, you need to establish user accounts on the Windows NT, Windows 2000 - 2008 host system. This section lists some key considerations for performing this activity. For specific instructions on setting up user accounts, refer to your operating system documentation.

When setting up user accounts, determine whether each user will have a unique account, or whether groups of users will share an account (such as Accounting) on the server. The table below shows some tradeoffs to help you make that decision:

Feature | Individual Accounts | Group Accounts
Security is configured user-by-user. | yes |
Log files can track usage by individual user. | yes |
Requires Administrator to create an account for every user. | yes |
Existing configuration and permissions are easily changed. |  | yes
Quickly configure a large group of users who need identical access to the same resources. |  | yes
Easily grant identical access to a bank of machines shared by a department. |  | yes
Note: Members of a group can be logged on simultaneously with the same account.

If you choose group accounts on the server, users may still have individual accounts on their client machines. The username returned by ACCEPT FROM SYSTEM-INFO will be the local (client) login-ID.

The acuserve service is usually run as the SYSTEM account. If you need to change the account used by the acuserve service, be sure that the new account has all of the appropriate permissions for a file server.

Parent topic: Preparing Your Windows Network


Setting Ownerships and Permissions

User Privileges

Windows NT and Windows 2000 - 2008 control access to resources with Access Control Lists (ACLs). An ACL specifically grants access to a user or to a group. Privileges are additive, meaning that users have the highest access given to their account and to any groups to which they belong. The exception is No Access, which overrides any other privileges.

The group Everyone contains every account on the system. Using this group is a handy way to set privileges, but can be a risky way to deny them. If a file or directory has No Access for Everyone, it will be unusable until someone (such as the Administrator) takes ownership and resets the privileges.

File Permissions

File permissions are set by the account that owns the file. To override permissions, a non-owner must have the Take Ownership privilege and use it to take ownership of the file before setting permissions.

Setting file permissions requires Administrator privileges. The topics in this help section list some key considerations for performing this activity. For specific instructions, consult your operating system documentation.

Parent topic: AcuServer System Security


File Access Security

AcuServer allows users of Windows NT and Windows 2000 - 2008 networks to choose between the system security that AcuServer offers and the security features offered by their own operating system.

Note: On Windows 2008 it is essentially required that you use the operating system’s security methods. This is mainly due to a new security layer called User Account Control (UAC). Consult Windows Help for information on how UAC impacts file and program access.

By default, AcuServer system security is used to govern file access.

If you use AcuServer security, the AcuAccess and AcuAccess.vix files are used to establish user access privileges. Remember that these two files must be readable and writable by only Administrator and System or AcuServer will not start.

Note: If you experience a problem with file access, it can be helpful to give the users Full Control of the files and directories they need to use. After everything is working smoothly, reduce access to Read-Only if desired. However, be sure to test each program to make sure that everything continues to function as you expect with the reduced privileges.

If you prefer to use Windows security mechanisms (recommended), you may do so by setting the configuration variable SECURITY_METHOD in both the runtime configuration file and server configuration file. See Server Configuration Variables for more information about the SECURITY_METHOD configuration variable.

Note that if you decide to use Windows security instead of AcuServer system security, your users will have whatever permissions the system administrator has set up for them.

Parent topic: AcuServer System Security


Setting Permissions on New Files

When a client application makes its initial request to AcuServer for services, the requester is validated for permission to use AcuServer. If the requester is permitted to use AcuServer, a user name is assigned to the requester based on the Local Username field of the matching server access record. Files created for that requester by AcuServer get the user and group ownerships of the assigned Local Username. See AcuServer Connection Logic for more information.

unmask

The read and write permissions set on new files are determined by the umask specified in the matching server access record (because all files created are data files, execute permission is not applicable).

On Windows NT and Windows 2000 - 2008 servers, when AcuServer security is being used, the umask is used to set read and write permissions for the owner (leftmost digit) and for other (rightmost digit). The group digit (middle) is ignored. umask is not used when Windows NT security is enabled. See System Security for more information about AcuServer security.

Parent topic: AcuServer System Security


Installing the Client

There is nothing on the AcuServer distribution media to install on the client machine. However, you should ensure that every client system that will use AcuServer has a licensed copy of the current ACUCOBOL-GT runtime. To check that your runtime is current, use the -v option on the runtime command line of the client machine. The runtime will display information (either at the command line or in a Windows message box) similar to the following:

ACUCOBOL-GT runtime version 8.1
Serial number 1234
Licensed for 2 user(s)
AcuServer client
Vision version 5 file system
Copyright (c) 1985 - 2008, Micro Focus (IP) Ltd.

Look for the line AcuServer client and a runtime version number that matches the AcuServer version. If either of these criteria is missing, the client machine will not be able to access data using AcuServer.

  • Passwords for Clients
  • Setting Up the Host Name
  • Setting Up the User Name
  • Confirming Network Services
Parent topic: Preparing Your Windows Network


Using AcuServer’s Graphical User Interface for Windows

Executing acuserve in Windows automatically launches the AcuServer Control Panel (ACP), a graphical-based administrative utility based on AcuServer’s command-line requirements.

Note: To use the AcuServer Control Panel on Windows 2008 where UAC is turned on (as it is by default), any user must choose Run as Administrator in order to use the various Acuserver utilities. UAC can be turned off, in which case the user must merely be a member of the administrators group in order to fully operate AcuServer.

You can use the ACP to perform the same tasks that you would otherwise perform by issuing the acuserve command at the command line. You can:

  • Edit an access file (add, change, or delete user security information)
  • Set and view current configuration settings for a running server
  • View, unlock, and close open files and connections
  • Install, start, stop, modify, or remove AcuServer services on any port
  • Monitor a port for status and open files

Chapter Administrator Utilities and Functions describes how to perform AcuServer functions from the command line and the ACP. You can access the AcuServer documentation from the ACP by clicking Help or by pressing F1.

Parent topic: Preparing Your Windows Network


Configuration

  • Configuring AcuServer
  • Configuration Variables
Parent topic: AcuServer Version 10.2.0 User's Guide


Configuring AcuServer

Before AcuServer file server software is ready for use, you must evaluate and configure several system attributes. AcuServer configuration consists of:

  • Assigning values to runtime configuration variables (section Runtime Configuration Variables)
  • Assigning values to server configuration variables (section Server Configuration Variables)
  • Creating the server access file/authorization database (chapter System Security)
  • Assigning ownerships and permissions to the acuserve executable file, the server configuration file, the server access file, and existing data files and directories

See Programming for AcuServer for information on enabling the application software to use AcuServer.

Parent topic: Configuration


Configuration Variables

Some attributes of AcuServer can be controlled using ACUCOBOL-GT® runtime configuration variables and AcuServer server configuration variables.

Runtime and server configuration variables are stored in separate plain-text files, located on their respective host machines. The content of these files is easily modified with the host system's standard text editor.

Each configuration variable entry consists of a single line in the file. Each entry starts with a keyword, followed by one or more spaces or tabs, and a value. Note that configuration file entries treat upper and lower case characters as equivalent, and hyphens and underscores as equivalent. A configuration variable definition might look like:

LOCKS_PER_FILE   10
  • Runtime Configuration Variables
  • Server Configuration Variables
Parent topic: Configuration


Runtime Configuration Variables

On UNIX systems, the runtime configuration file is typically named cblconfig and is located in /etc by default. On Windows systems, the configuration file is typically named cblconfi and located, by default, in the \etc directory on the same drive as the operating system.

If the configuration file has a different name or is located in another directory, the full path and name of the file must be specified with the -c option when you start the ACUCOBOL-GT application (for example, wrun32 -c device:\path\config_file program_name program_parameters). See Compiler and Runtime in the ACUCOBOL-GT User's Guide for a complete description of the runtime configuration file and all options to runcbl and wrun32.

Several configuration variables that appear only in the runtime configuration file can affect AcuServer's behavior. These variables, include AGS_PING_TIME, AGS_SOCKET_COMPRESS, AGS_SOCKET_ENCRYPT, CACHE_DIRECTORY, filename_MRC, and USE_LOCAL_SERVER.

Some specialized variables appear only in the server configuration file, while other configuration variables, including ACUSERVER_PORT, DEFAULT_TIMEOUT, ENCRYPTION_SEED, LOCKS_PER_FILE, MAX_FILES, and MAX_LOCKS, SECURITY_METHOD, TEXT, and V_BUFFERS, can or must be used in both the runtime and server configuration files. Most of these variables are discussed in Server Configuration Variables. The remainder (FILE_PREFIX, CODE_PREFIX, APPLY_CODE_PATH, and APPLY_FILE_PATH) are discussed in Using FILE_PREFIX and CODE_PREFIX.

  • AGS_BLOCK_SLEEP_TIME
  • AGS_PING_TIME
  • AGS_SOCKET_COMPRESS
  • AGS_SOCKET_ENCRYPT
  • CACHE_DIRECTORY
  • CACHE_DIRECTORY_SIZE
  • filename_MRC
  • USE_LOCAL_SERVER
Parent topic: Configuration Variables


AGS_BLOCK_SLEEP_TIME

This variable is used to specify the amount of wait time before attempting to retry writing data to a socket. It can improve file I/O peformance times for large files (32K or larger). The value of this variable by default is 10 milliseconds. The default value should provide performance at par with pre 7.3 versions.

This variable only has impact on UNIX/Linux.

Parent topic: Runtime Configuration Variables


AGS_PING_TIME

AGS_PING_TIME is used in combination with the server configuration variable DEAD_CLIENT_TIMEOUT to enable a mechanism in AcuServer that automatically detects when a client hangs or disappears (see the Machine Failures for a complete description).

Note: If you use AGS_PING_TIME, the variable must be set before the socket connection between the client and the server is created. This means that the runtime configuration file must reside on the client, rather than on the server, for AcuServer to detect lost connections.

If you set AGS_PING_TIME to -1, the default value, the client does not participate in the server's dead client detection service.

If you set AGS_PING_TIME to any other value, the client reporting mechanism is enabled and the connection is included in acuserve's monitoring table (if it is enabled). The value of AGS_PING_TIME specifies the interval, in seconds, in which the client will send an I'm alive message (a no-op instruction) to acuserve. The value is communicated to acuserve at the time that the connection is established so that acuserve can determine, when it checks its monitoring records, whether the connection has missed two or more consecutive communication periods. If the client misses two or more consecutive communications periods, AcuServer determines that the client is no longer responding and it closes all associated files, releases all associated locks, and closes the associated socket.

Note: When you are running a program in debug mode, the runtime is not able to send ping messages to the debugger prompt. Therefore, if you are debugging a COBOL program, you should set AGS_PING_TIME to -1.
Parent topic: Runtime Configuration Variables
Related information
DEAD_CLIENT_TIMEOUT


AGS_SOCKET_COMPRESS

The AGS_SOCKET_COMPRESS variable allows you to specify one of three data compression settings:

NONE (default) | No compression is performed.
ZLIB | Socket data is compressed using the same algorithm as the gzip compression utility. All versions of Windows support ZLIB compression, but some UNIX machines do not. When ZLIB compression is specified on a machine that does not support the format, RUNLENGTH compression is automatically used instead.
RUNLENGTH | Socket data is compressed using simple compression based on counting repeated bytes of data.

Note that RUNLENGTH compression is much faster than ZLIB compression. ZLIB compression, however, can compress data much more than RUNLENGTH compression.

The AGS_SOCKET_COMPRESS variable must be set before any socket communication is performed and cannot be changed via SET ENVIRONMENT.

Parent topic: Runtime Configuration Variables


AGS_SOCKET_ENCRYPT

Set AGS_SOCKET_ENCRYPT to 1 (on, true, yes) to turn on AcuServer encryption. The default value is 0 (off, false, no). Note that encryption can have a significant impact on performance. See Encryption for complete information about AcuServer encryption and use.

Note: The AGS_SOCKET_ENCRYPT configuration variable replaces AS_CLIENT_ENCRYPT. In a configuration file where the old AS_CLIENT_ENCRYPT variable is set to 1 (on, true, yes), AGS_SOCKET_ENCRYPT is also set to 1.
Parent topic: Runtime Configuration Variables


CACHE_DIRECTORY

By default, AcuServer creates a local, cached copy of any COBOL object files executed by the client in order to improve performance.

Use the CACHE-DIRECTORY configuration variable to specify the directory in which to store cached object files.

If you do not set CACHE-DIRECTORY, the runtime searches the other temporary directory variables (A_TMPDIR, TMPDIR, TEMP, and TMP), uses the first found, and appends /acu to the name of the directory. The runtime attempts to create the new directory. If the directory does not exist and cannot be created, caching is not performed.

AcuServer creates a unique filename for the cached file based on the date, time, size, and location of the file, so that as long as the object file doesn't change, the name of the cached file will remain the same.

To disable local caching, use the server configuration variable NO_LOCAL_CACHE, described in Server Configuration Variables.

Parent topic: Runtime Configuration Variables


CACHE_DIRECTORY_SIZE

By default, AcuServer copies any COBOL object files executed by the client to a local cache directory to improve performance. This variable allows you to limit the size of the directory in which these files are stored.

Set CACHE_DIRECTORY_SIZE to a whole integer value to specify the maximum number of megabytes available in the storage directory. For example, when this variable is set to the default value of 5, the sum of the sizes of all files in the cache must be less than 5MB. File size is checked before a new file is downloaded from the server. If the directory reaches maximum size, the oldest file is deleted first. In the rare event that there are two or more files that are equally old, the largest is deleted first. Files are deleted until there is room to save the new file.

When the runtime determines the size of the cache directory, it considers only object files it has cached into that directory. In particular, it counts only the sizes of object files that are from the server it is talking to (including the port on which AcuServer is running). Other object files are not considered, so they are never automatically removed by the runtime.

Parent topic: Runtime Configuration Variables


filename_MRC

The variable filename_MRC (MULTIPLE_RECORD_COUNT) applies only to those using AcuServer's multiple-record mode. Use this variable to specify that you want the named file to be opened in multiple-record mode whenever it is allowed (whenever the user has exclusive I/O access, or the file is open INPUT).

Note: Files opened in regular I/O mode will be transmitted a single record at a time, even if they are named in the runtime configuration file using this variable.

For filename, enter the final resolved name or physical filename on disk of the file to be used in this mode. Do not include any directory names and/or file extensions. For example, if the file that you wanted to open in multiple-record mode were named /user1/gl.dat, create a variable GL_MRC. Assign a value to this variable to reflect the number of records to be read in each network packet, for instance, GL_MRC 10. Valid values range from 0 to 32767. Setting this variable to "0" is equivalent to not setting it at all. Set this variable to 1 if you want the server to determine how many records to send to the client at once. AcuServer then examines the server configuration variable MULTIPLE_RECORD_COUNT and uses that value to determine how many records to send.

There are some exceptions to these general rules. For instance, when the client executes a random READ, the server sends only a single record. The next time the client executes a READ NEXT, the server sends a full set of records.

See Multiple-Record Mode for more information on multiple-record mode. Note that files opened in multiple-record mode have certain restrictions upon them. See File Limitations for more infoirmation.

Parent topic: Runtime Configuration Variables


USE_LOCAL_SERVER

Set USE_LOCAL_SERVER when you want to run AcuServer client applications on the same machine as the AcuServer file server. This variable allows you to specify whether to use or bypass AcuServer when accessing local files that have remote name notation.

Set USE_LOCAL_SERVER to 0 (the default setting) to prevent the use of AcuServer to access local files that have remote name notation (the remote name is stripped off and the file I/O operation is handled by the runtime). Set USE_LOCAL_SERVER to 1 to use AcuServer to access local files that have remote name notation.

Parent topic: Runtime Configuration Variables


Server Configuration Variables

The server configuration file is named a_srvcfg. On UNIX servers, it is located in /etc by default. On Windows NT, Windows 2000 to 2008 servers, it is located in the directory c:\etc (where c: is the letter of the drive on which the operating system is installed). If the file is given another name, or located in another directory, you must provide the full location and name of the file.

To specify the name and location of a server configuration file at the command line, use the -c option when you start AcuServer. On a Windows server, you can perform the same function from the Services tab of the AcuServer Control Panel. See the Starting and Stopping acuserve for more information about specifying acuserve startup options.

To change configuration values on the server or local machine without changing the configuration file on disk, use the Config tab. Using the Config tab is equivalent to issuing a SET ENVIRONMENT command from the runtime to modify a runtime configuration value.

Click Query to select the acuserve service whose configuration you want to view or modify, then use the New and Modify buttons to add or change configuration variables in the server's configuration file.

There are several server configuration variables. They are:

Name | Default Value
ACCESS_FILE | /etc/AcuAccess
ACUSERVER_MASTER_SERVER | undefined
AGS_SERVER_SOCKET_RESERVE | 0
COUNT_STATISTICS | 0 (off, false, no)
DEAD_CLIENT_TIMEOUT | -1 (off)
DEFAULT_TIMEOUT* | 25
DEFAULT_UMASK | 0
DEFAULT_USER | undefined
ENCRYPTION_SEED | undocumented for increased security
FILE_TRACE * | 0
FILE_TRACE_FLUSH | 0
FILE_TRACE_TIMESTAMP | 0 (off, false, no)
filename_DATA_FMT * | decimal extensions
filename_INDEX_FMT * | decimal extensions
filename_VERSION * | 0
LOCK_ALL_FILES | 0
LOCKS_PER_FILE* | 10
MAX_ERROR_LINES* | 0
MAX_FILES* | 32
MAX_LOCKS* | 32
MULTIPLE_RECORD_COUNT | 10
NO_LOCAL_CACHE | 0 (off, false, no)
PASSWORD_ATTEMPTS | 3
PROVIDE_PASSWORD_MESSAGES | 0 (off, false, no)
SECURITY_METHOD* | none
SERVER_IP | undefined
SERVER_NAME | undefined
SERVER_PORT* | 6523
TEXT | see entry for TEXT, below
USE_SYSTEM_RESTRICTIONS | 0 (off, false, no)
V_BASENAME_TRANSLATION* | 1 (on, true, yes)
V_BUFFERS* | 64
V_BUFFER_DATA* | 1 (on, true, yes)
V_INDEX_BLOCK_PERCENT* | 100
V_READ_AHEAD* | 1 (on, true, yes)
V_SEG_SIZE* | 2147482623
V_STRIP_DOT_EXTENSION* | 1 (on, true, yes)
V_VERSION* | 0
WINNT-EVENTLOG-DOMAIN | undefined
WINNT-LOGON-DOMAIN | undefined

Variables marked with an asterisk ("*") can appear in both the runtime (cblconfig) and server (a_srvcfg) configuration files. Those that must appear in both locations are indicated in the descriptions that follow. Note that values assigned to variables contained in the server configuration file are applied solely to operations performed by AcuServer.

Note that when file access is made through AcuServer, the values assigned to the following in the runtime configuration file are ignored:

  • filename_DATA_FMT
  • filename_INDEX_FMT
  • filename_VERSION
  • V_BASENAME_TRANSLATION
  • V_BUFFER_DATA
  • V_BUFFERS
  • V_INDEX_BLOCK_PERCENT
  • V_READ_AHEAD
  • V_SEG_SIZE
  • V_STRIP_DOT_EXTENSION
  • V_VERSION
  • ACCESS_FILE
  • ACUSERVER_MASTER_SERVER
  • AGS_SERVER_SOCKET_RESERVE
  • COUNT_STATISTICS
  • DEAD_CLIENT_TIMEOUT
  • DEFAULT_TIMEOUT
  • DEFAULT_UMASK
  • DEFAULT_USER
  • ENCRYPTION_SEED
  • FILE_TRACE
  • FILE_TRACE_FLUSH
  • FILE_TRACE_TIMESTAMP
  • filename_DATA_FMT
  • filename_INDEX_FMT
  • filename_VERSION
  • LOCK_ALL_FILES
  • LOCKS_PER_FILE, MAX_FILES, and MAX_LOCKS
  • MAX_ERROR_LINES
  • MULTIPLE_RECORD_COUNT
  • NO_LOCAL_CACHE
  • PASSWORD_ATTEMPTS
  • PROVIDE_PASSWORD_MESSAGES
  • SECURITY_METHOD
  • SERVER_IP and SERVER_NAME
  • SERVER_PORT
  • TEXT
  • USE_SYSTEM_RESTRICTIONS
  • V_BASENAME_TRANSLATION
  • V_BUFFERS
  • V_BUFFER_DATA
  • V_INDEX_BLOCK_PERCENT
  • V_READ_AHEAD
  • V_SEG_SIZE
  • V_STRIP_DOT_EXTENSION
  • V_VERSION
  • WINNT-EVENTLOG-DOMAIN
  • WINNT-LOGON-DOMAIN
Parent topic: Configuration Variables


ACCESS_FILE

The variable ACCESS_FILE, as well as the variables DEFAULT_USER and PASSWORD_ATTEMPTS, affects AcuServer access security.

ACCESS_FILE must hold the full path and file name of the server access file, if it is other than the default (/etc/AcuAccess on UNIX systems; \etc\AcuAccess on Windows NT, Windows 2000 to 2008).

Parent topic: Server Configuration Variables


ACUSERVER_MASTER_SERVER

This variable is used for load-balancing in environments with multiple instances of the acuserve daemon/service. One instance of acuserve is designated the master, or primary, server. This primary server is responsible for distributing client requests among the available acuserve daemons. Note that you must start the daemon designated as the primary server before you start any secondary servers.

After a primary server is specified, you can start other acuserve instances as secondary, or slave, servers. Instances of acuserve that are configured as secondary servers register with the primary server to indicate that they are ready to allow connections. When a secondary server shuts down, it notifies the primary server that it is no longer available for client requests.

If the master server dies unexpectedly, the -register command can be used to re-register the secondary or subordinate servers with a newly started master server. This avoids having to shut down and restart the entire system. See Registering Servers for more information.

In the following example, the primary server resides on a server called jupiter and listens at port 4331.

ACUSERVER_MASTER_SERVER jupiter.mycompany.com:4331

Note that you must specify a fully qualified domain name for your server.

If this value appears in the configuration files for all instances of acuserve in the environment, the primary server both manages communication with secondary servers and serves files itself.

To create a primary server that performs only load-balancing services, do not specify a value for ACUSERVER_MASTER_SERVER in the configuration file for the primary server. Configuration files for the secondary servers must still contain the machine name and port of the primary.

To configure the client machines to take advantage of the server load balancing, set the FILE_PREFIX and ACUSERVER_PORT runtime configuration variables to point to the instance of acuserve designated as the primary server. On the server side, set FILE_PREFIX to local file locations in the configuration file(s) used by the secondary servers.

When a client connects to the server, it first communicates with the primary server, which determines which secondary is least busy. Then the primary server passes the client connection to a secondary server, and all further communication occurs between the client and the secondary server, without further involvement of the primary server.

To determine which secondary server is least busy, the client considers the following criteria in the following order:

  1. Percentage of idle time in the last 15 minutes
  2. Number of active users
  3. Number of open files
  4. If all other factors are equal, registration order
Parent topic: Server Configuration Variables


AGS_SERVER_SOCKET_RESERVE

AcuServer depends on the select() system call to determine when a client is requesting services. On most UNIX machines, this call requires an array of socket identifiers on which to await results. If this array is sparse, select() can take more time than is necessary.

To address this issue, set AGS_SERVER_SOCKET_RESERVE to a positive integer to reserve that many socket handles for exclusive use with clients. This allows select() to be more efficient, and it allows UNIX machines that allow more open files than open sockets to reserve socket identifiers with low values.

Note that this variable is valid only on UNIX servers, and that the variable must be set no larger than the size of the array used in the call to SELECT. To determine the maximum value, use the command acuserve -vv.

Parent topic: Server Configuration Variables


COUNT_STATISTICS

When COUNT_STATISTICS is set to 1 (on, true, yes), AcuServer has the capability to collect and report various server statistics, described in Tracking Server Statistics. Because a small performance hit is incurred when AcuServer tracks its statistics, the default setting for this configuration variable is 0 (off, false, no).

Parent topic: Server Configuration Variables


DEAD_CLIENT_TIMEOUT

DEAD_CLIENT_TIMEOUT is used in conjunction with the runtime configuration variable AGS_PING_TIME to allow AcuServer to automatically detect when a client hangs or disappears. See Machine Failures for a complete description).

When DEAD_CLIENT_TIMEOUT is set to -1 (the default), the dead client detection mechanism is disabled.

When DEAD_CLIENT_TIMEOUT is set to any other value, the dead client detection mechanism is enabled and the variable's value is interpreted as the interval, in seconds, at which acuserve will analyze its records to detect dead connections.

For example, if DEAD_CLIENT_TIMEOUT is set to 300 (300 seconds = 5 minutes), the dead client detection mechanism is enabled on the server and acuserve analyzes its communication records every five minutes to look for dead connections.

Parent topic: Server Configuration Variables
Related information
AGS_PING_TIME


DEFAULT_TIMEOUT

The variable DEFAULT_TIMEOUT defines the length of time, in seconds, that the runtime or acuserve will wait for a response before timing out. The default value is 25 seconds. Note that some networks have long connect times and, depending on network loading, the default value may not be long enough to allow the application to connect.

Set this configuration variable on the client when you want the client to stop attempting to communicate with the server should the server fail to respond within the specified period. This is particularly helpful when you want to keep the client program from hanging when the server is down or inaccessible. If the timer expires without a response from the server, an error 98,104,10060 is returned to the application. For the mechanism to work, a value must be assigned to the variable before the first file is accessed. If you use AcuServer to get the configuration file from a remote host, you must set DEFAULT_TIMEOUT in the local environment.

On the server, DEFAULT_TIMEOUT allows you to tell acuserve how long to wait for a client to complete a communication that the client has already started. If the timer expires without any further communication from the client, the socket is closed. This allows the server to detect when a client has crashed or disappeared in the middle of a communication. This variable does not help in the situation in which the client crashes or disappears between requests. See Machine Failures for help in detecting dead connections.

Parent topic: Server Configuration Variables


DEFAULT_UMASK

The variable DEFAULT_UMASK defines the file creation mask (umask) to be used for users whose umask has not been adequately defined in the AcuAccess file (that is, their umask was set to spaces). The default value is 000, which causes all files created by these users to be readable and writable by everyone. You can change DEFAULT_UMASK to provide whatever read/write permissions you desire for these undefined users. Valid values include any octal value between 000 and 777.

Parent topic: Server Configuration Variables


DEFAULT_USER

The variable DEFAULT_USER, as well as the variables ACCESS_FILE and PASSWORD_ATTEMPTS, affects AcuServer access security.

DEFAULT_USER holds the default user name given to AcuServer requesters who are not specifically mapped to a local user name in the server access file (as when the Local Username field of the access record is empty, or the value of the field is an invalid user name). Definition of DEFAULT_USER is optional. DEFAULT_USER cannot be defined as root. See AcuServer Connection Logic for a description of when AcuServer assigns DEFAULT_USER to a requester.

Parent topic: Server Configuration Variables


ENCRYPTION_SEED

This variable holds a text string that is used to initialize the encryption module. The string can be any length. ENCRYPTION_SEED should be set in both the runtime configuration file (on the client) and in the server configuration file.

Note that the use of encryption can have a significant impact on performance. See Encryption for complete information on AcuServer encryption and use.

Parent topic: Server Configuration Variables


FILE_TRACE

This variable allows you to start file tracing without specifying a -t # option on the command line when starting AcuServer. Set this variable to a nonzero value to save information about all file OPENs, READs, and WRITEs in the error file. Set it to 5, 6, or 7 to flush the error trace buffer to disk after every WRITE operation. The default is 0. Like other server configuration variables, you can change the value of FILE_TRACE while AcuServer is running by using the acuserve -config option.

Parent topic: Server Configuration Variables


FILE_TRACE_FLUSH

Setting FILE_TRACE_FLUSH to 1 (on) causes AcuServer to flush the error trace buffer to disk after every WRITE operation. This ensures that in the event that the acuserve daemon terminates abnormally, all file trace information, up to the last WRITE operation, is captured in the log file. If this configuration variable is not used (set to 0 or off) and AcuServer aborts unexpectedly, an undefined amount of file trace information will be lost. FILE_TRACE_FLUSH is set to 0 by default. Note that you can also enable file trace flushing when you start the acuserve daemon by including the -t 5, -t 6, or -t 7 command-line switch in the -start command or by setting FILE_TRACE to 5, 6, or 7 in the server configuration file. See Starting and Stopping acuserve for more information.

Parent topic: Server Configuration Variables


FILE_TRACE_TIMESTAMP

When you set FILE_TRACE_TIMESTAMP to 1 (on, true, yes), AcuServer places a timestamp at the beginning of every line in the trace file. The format of the timestamp is HH:MM:SS:mmmmmm, where mmmmmm is the finest resolution that ACUCOBOL-GT can obtain from the system.

Timestamp information is included only when file trace information is directed to a file. Timestamp information is never included in file trace output that is sent to the screen.

Note: Turning on timestamps can add significant overhead to file operations and may have a noticeable impact on performance.
Parent topic: Server Configuration Variables


filename_DATA_FMT

This configuration variable specifies a format for naming the data segments of a Vision 5 file. The configuration variable starts with the physical file's base name followed by an underscore and the file's extension, all in uppercase.

Suppose that the regular name of your COBOL file is /usr1/gl.dat. The variable you would use to set the data segment naming format for this file is GL_DAT_DATA_FMT.

The variable must be set to a pattern that shows how to create the segment names. The pattern shows how to form the base name and extension for each segment. Part of this pattern is a special escape sequence (such as %d) that specifies how the segment number should be represented. Choices include %d (decimal segment numbers), %x (lowercase hexadecimal numbers), %X (uppercase hexadecimal numbers), and %o (octal numbers).

For example, setting the variable GL_DAT_DATA_FMT=gl%d.dat would result in data segments named /usr1/gl.dat (remember that the first data segment is not affected), /usr1/gl1.dat, /usr1/gl2.dat, and so forth.

Escape Sequence Definitions:

The %d in the value of the filename_DATA_FMT above is a printf-style escape sequence. Most reference books on the C language contain an in-depth explanation of these escape sequences, and UNIX systems typically have a man page (man printf) that explains them in detail. Here are the basics:

  • %d expands into the decimal representation of the segment number.
  • %x expands into the hexadecimal representation (with lowercase a-f) of the segment number.
  • %X expands into the hexadecimal representation (with uppercase A-F) of the segment number.
  • %o expands into the octal representation of the segment number.
  • You can add leading zeros to the number (to keep all the file names the same length) by placing a zero and a length digit between the percent sign and the following character. For example, %02d would result in 00, 01, 02, and so forth, when expanded.
  • To embed a literal % in the file name, use %%.

The escape sequence can be positioned anywhere in the file name, including the extension.

Note: While AcuServer checks for this segment naming variable in the runtime configuration file as well as in the environment, utilities such as vutil and vio check only the environment. Therefore, if you are using this variable with vio or vutil, you must set the variable in the environment and not in the configuration file.

See filename_INDEX_FMT for details about naming the index segments. Both variables should be set to corresponding patterns.

Parent topic: Server Configuration Variables


filename_INDEX_FMT

This configuration variable specifies a format for naming the index segments of a Vision Version 5 file. The configuration variable starts with the file's base name followed by an underscore and the file's extension, all letters in upper case.

Suppose that the regular name of your COBOL file is /usr1/gl.dat. The variable you would use to set the format for naming the file's index segments is GL_DAT_INDEX_FMT.

The variable must be set equal to a pattern that shows how to create the segment names. The pattern shows how to form the base name and how to form the extension for each segment. Part of this pattern is a special escape sequence (such as %d) that specifies how the segment number should be represented. Choices include %d (decimal segment numbers), %x (lowercase hexadecimal numbers), %X (uppercase hexadecimal numbers), and %o (octal numbers).

For example, setting the variable GL_DAT_INDEX_FMT=gl%d.idx would result in index segments named /usr1/gl0.idx, /usr1/gl1.idx, /usr1/gl2.idx, and so forth.

Escape Sequence Definitions:

The %d in the value of the filename_INDEX_FMT above is a printf-style escape sequence. Most reference books on the C language contain an in-depth explanation of these escape sequences, and UNIX systems typically have a man page (man printf) that explains them in detail. Here are the basics:

  • %d expands into the decimal representation of the segment number.
  • %x expands into the hexadecimal representation (with lower case a-f) of the segment number.
  • %X expands into the hexadecimal representation (with upper case A-F) of the segment number.
  • %o expands into the octal representation of the segment number.
  • You can add leading zeros to the number (to keep all the file names the same length) by placing a zero and a length digit between the percent sign and the following character. %02d would result in 00, 01, 02, and so forth when expanded.
  • To embed a literal % in the file name, use %%.

The escape sequence can be positioned anywhere in the file name, including the extension.

Note: While AcuServer checks for this segment naming variable in the runtime configuration file as well as in the environment, utilities such as vutil and vio check only the environment. Therefore, if you are using this variable with vio or vutil, you must set the variable in the environment and not in the configuration file.

See filename_DATA_FMT for details about naming the index segments. Both variables should be set to corresponding patterns.

Parent topic: Server Configuration Variables


filename_VERSION

This variable sets the file format on a file-by-file basis. Replace filename with the base name of the file (the filename minus directory and extension). The meaning of the variable is the same as for V_VERSION. This variable is useful if you want to have all your files in one format, with a few exceptions. For example, you might want to maintain most of your files in Version 6 format, but have a few files in an earlier version to conserve file handles. Note that this variable affects the file format only when it is created. You can always rebuild the file in another format later.

This variable (and the V_VERSION variable) is most helpful when you are using transaction management. The transaction system does not record the format of the created file if an OPEN OUTPUT is done during a transaction, because the transaction system is not tied to any particular file system. If you need to recover a transaction, the system will recreate the OPEN OUTPUT files using the settings of the VERSION variables.

Parent topic: Server Configuration Variables


LOCK_ALL_FILES

This configuration variable is designed for UNIX systems that are dedicated AcuServer servers. If the variable LOCK_ALL_FILES is set to 1, it causes AcuServer to lock all files that it opens. Access to locked files is faster than access to files that are not locked. As a result, LOCK_ALL_FILES can improve data access speed. If AcuServer is running on a UNIX system that other users are also using, this configuration variable should be set to 0 (the default), or the other users may not have access to the files. On Windows systems, AcuServer always locks the files it uses, so it is not necessary to configure this option.

Note that ACUCOBOL-GT runtimes that do not use acuserve may also be locked out if this variable is set to 1. Therefore, if your site uses this option, all runtimes must use acuserve to access the files (set USE_LOCAL_SERVER to 1).

When LOCK_ALL_FILES is set to 0, files are no longer automatically locked, and access times are increased.

Parent topic: Server Configuration Variables


LOCKS_PER_FILE, MAX_FILES, and MAX_LOCKS

The values of LOCKS_PER_FILE, MAX_FILES, and MAX_LOCKS are applied to the corresponding executable of each configuration file. That is, the values of the variables defined in the runtime configuration file are applied to the executing client program, and the values defined in the server configuration file are applied to the acuserve process. Remote file access is restricted by the smaller of the two values.

For example, for the following configuration values:

runtime (cblconfig) | MAX_FILES | 64
server (a_srvcfg) | MAX_FILES | 32

the runtime is able to open 64 files with a limit of 32 remote files.

Alternatively, if the configuration values are:

runtime (cblconfig) | MAX_FILES | 32
server (a_srvcfg) | MAX_FILES | 64

the runtime will be able to open, at most, 32 remote files.

Determine values for LOCKS_PER_FILE, MAX_FILES, and MAX_LOCKS by noting the values set in cblconfig and then multiplying the value of each variable by the number of runtimes likely to access the server simultaneously. The resultant values are sufficient to support the case where all runtimes have the maximum number of files open with the maximum number of locks applied. The values assigned these variables in a_srvcfg should not be smaller than the values assigned in cblconfig.

For example, if you anticipate having four runtimes accessing the server simultaneously, and the settings of your runtime configuration variables are:

LOCKS_PER_FILE  10
MAX_FILES  30
MAX_LOCKS  40

the corresponding variables in a_srvcfg might be:

LOCKS_PER_FILE  40
MAX_FILES  120
MAX_LOCKS  160

The value of LOCKS_PER_FILE and MAX_FILES in the server configuration file cannot exceed 32767 for Vision files. The value of MAX_LOCKS cannot exceed 8191 for Vision files. To conserve system resources and improve runtime and server performance, set these variables to the smallest value that still meets your requirements.

Parent topic: Server Configuration Variables


MAX_ERROR_LINES

This variable sets the maximum number of lines that can be included in the error file. When the size of the error file reaches the number of lines specified in this variable, the error file is rewound to its beginning, and subsequent lines of output overwrite existing lines in the file. For example, if you set the maximum to 300, then lines 301 and 302 would overwrite lines 1 and 2 in the file.

To help you locate the end of the file, the message "*** End of log ***" is output whenever AcuServer shuts down. Line numbers are included in each line of the file, in columns one through seven. The default value is 0, which means do not limit the size of the file.

Parent topic: Server Configuration Variables


MULTIPLE_RECORD_COUNT

The variable MULTIPLE_RECORD_COUNT applies only to those using AcuServer's multiple record mode. If you plan to open records in this mode, use this variable to specify how many records can be read in a single network packet. In other words, use this variable to specify how many records the server should send to the client each time the client requests more records. Note that this variable is checked only if the filename_MRC variable on the client is set to 1. Any other value on the client causes this variable to be disregarded.

Valid values of MULTIPLE_RECORD_COUNT range from 0 to 32767. The default value is 10. If this variable is set to 0, files opened in multiple record mode requesting a single record are treated as if they were being opened in standard mode.

See Multiple-Record Mode for more information on using AcuServer's multiple record mode.

Parent topic: Server Configuration Variables


NO_LOCAL_CACHE

By default, AcuServer copies any COBOL object files executed by the client to a local cache file to improve performance. To prevent local caching, set NO_LOCAL_CACHE to TRUE.

Parent topic: Server Configuration Variables


PASSWORD_ATTEMPTS

The variable PASSWORD_ATTEMPTS, like the variables DEFAULT_USER and ACCESS_FILE, affects AcuServer access security.

PASSWORD_ATTEMPTS holds a positive integer value specifying the total number of password validation attempts a requester is allowed before a connection attempt is terminated. The default value is 3. If a value of less than 1 is given, the value one (1) is used. If a non-integer value is given, the default value (3) is used.

Parent topic: Server Configuration Variables


PROVIDE_PASSWORD_MESSAGES

When set to true (on, 1), this variable causes the values of the password messages (TEXT_015, TEXT_016, and TEXT_017) to be sent to the client upon initial connection (prior to prompting the user for a password, if a password is required). This allows password messages to be defined on the server, in the server configuration file, and then downloaded to the client when a connection is established. See the entry for TEXT.

Parent topic: Server Configuration Variables


SECURITY_METHOD

This variable lets you specify the security method to use when accessing files via AcuServer. If desired, you can use your server's native security mechanism in place of AcuServer's so that users can use their usual passwords when accessing files rather than remembering or coordinating an AcuAccess password as well as a network password. On Windows 2008 it is essentially required that you use Windows security methods. This is mainly because of the Windows implementation of User Account Control (UAC) security feature.

Note: This feature works for Windows servers and UNIX servers that use shadow passwords. It does not use PAM (pluggable authentication module) libraries.

When native security is enabled, AcuServer impersonates the user who is logged onto the client machine. This allows AcuServer to spend less time managing security issues, and allows the full range of operating system security to be used on files and directories on the server. To use this feature, you must have the necessary user accounts set up and configured on the server. (Ask your system administrator whether security has been set up for each potential user.) Once a user is connected, it is as if that user is actually logged onto the server. Files that are available to the user when he or she is directly logged on to the server are available to the user who is connected via AcuServer.

SECURITY_METHOD can take any of the following values:

Value | Definition
NONE (false, no) | Do not use the native operating system security. Use AcuServer security instead. NONE is the default value.
LOGON Use the system's native security to manage user logons.

On Windows, attempt to log the user onto the Windows NT domain specified in the WINNT-LOGON-DOMAIN configuration variable. If the access file allows the connection, check the access record for the domain password. If it is present, establish a connection. If the password is not present in the access record or does not match the domain password, prompt the user for the domain password of the local username account. The number of attempts the user has to supply the correct password is limited by the value of the configuration variable PASSWORD_ATTEMPTS (3, by default). A successful logon grants users all of the same access rights they would have if they were directly logged onto the server. AcuServer allows the Windows NT/Windows 2000 server to manage all issues pertaining to access permissions.

On UNIX, if the access file allows the connection, check the access record for the native password. If it is present, establish a connection. If the password is not present in the access record or does not match the native password, prompt the user for the native password of the local username account.

Some UNIX machines have a the ability to restrict access to the machine based on various parameters. If you want to include those restrictions in AcuServer, set the configuration variable USE-SYSTEM-RESTRICTIONS to TRUE. See your UNIX administration manuals for information on this restriction feature.

NAMED-PIPE (on, true, yes) "NAMED PIPE" can be specified only when a Windows client is connecting to a Windows server. It is not valid for UNIX clients and is treated as NONE if specified for UNIX.

A value of NAMED PIPE tells AcuServer to use Windows security based on the connection made from the client to the server via a named pipe. When a named pipe is used, the password field in the AcuAccess file is ignored. The AcuAccess file is used only as a first check to see if the user connecting to the server is allowed to connect.

To use this option successfully, your client machine must have permission to connect to the named pipe that AcuServer creates. If your machine does not have permission, it may look to you as though your client runtime has hung and it may look to other users as though the server is down. Without the proper permission, the only way to resolve this situation is to kill the server using the Windows Task Manager. See your Windows system administrator for help in establishing named pipe permissions and resolving connection problems.

The SECURITY_METHOD configuration variable must be set in both the client runtime configuration file and the AcuServer configuration file. The values must match or the security method reverts to NONE, and only the AcuAccess password is used.

Parent topic: Server Configuration Variables


SERVER_IP and SERVER_NAME

The variables SERVER_IP and SERVER_NAME allow you to assign a specific IP address to an individual instance of the acuserve service/daemon. Use these variables when the server has two or more network addresses and you want to associate a particular network address with a given instance of acuserve.

To specify an IP address, include an entry for SERVER_IP in the configuration file and assign it the value of the desired IP address on the host. For example:

SERVER_IP = 192.215.170.107
Note: If using IPv6 addresses, you must enclose the IP address in brackets when appending the port number or any additional notation; see AGS_USE_IPV6 for more information.

To specify a hostname, make an entry for SERVER_NAME in the configuration file and assign it the value of a valid hostname on the server. For example:

SERVER_NAME = bigserve

where bigserve is the hostname for IP address 192.215.170.107.

If both variables are defined in the configuration file, acuserve uses the value of the first valid entry in the file.

By defining different values for these variables in separate server configuration files on the host and then specifying a particular configuration file when you start the acuserve daemon, you can associate a specific IP address/hostname with each instance of acuserve.

Parent topic: Server Configuration Variables
Related reference
AGS_USE_IPV6


SERVER_PORT

The variable SERVER_PORT specifies a particular port number to be used for accessing acuserve on the server host machine. This is especially helpful when the server host machine has a security firewall, because firewalls generally allow access only to specific ports. With this variable, the site can ensure that firewall restrictions are satisfied.

The acuserve daemon or service can work with privileged port numbers (from 0 to 1023) and non-privileged port numbers (1024 and higher, up to 32767).

The value of this variable is overridden by any port number assigned on the command line (via the -n option) when acuserve is started.

CAUTION:
The SERVER_PORT variable must be specified in both the server configuration file and the runtime configuration file on the client, and the values of both variables must match. If you change the default value in one location, you must also change it in the other.
Parent topic: Server Configuration Variables


TEXT

The TEXT configuration variable is used to control the text of selected runtime messages. Three runtime messages have been added to support AcuServer password handling. These messages are numbered 15, 16, and 17. The default text for each message is:

15 | A password is required to connect to host %s.
16 | Please enter a password:
17 | Invalid password.

Note that in message 15, the name of the AcuServer host will be substituted for the %s characters.

To change the text associated with a given message in the runtime configuration file, place the word TEXT at the beginning of a line, followed by a space, the message number, an "=" character, and the text to be used when that message number is displayed. For example:

TEXT 16=Enter your password now:

If you define these messages in the server configuration file (a_srvcfg), you can specify that they are downloaded and used by each client (the messages are downloaded upon initial connection with AcuServer). To turn this feature on, set the configuration variable PROVIDE_PASSWORD_MESSAGES to true.

Messages defined in the server configuration file have a slightly different format. To change a message, place the variable TEXT_015, TEXT_016, or TEXT_017 at the beginning of a line, followed by an "=" character, and the text to be used when that message number is displayed. For example:

TEXT_016=Enter your password now:
Note: Use of AcuServer password protection is optional. If password protection is not used, these messages are not displayed.
Parent topic: Server Configuration Variables


USE_SYSTEM_RESTRICTIONS

This configuration variable applies only to UNIX servers and is used only when the SECURITY_METHOD variable is set to LOGON.

Some UNIX machines have the ability to restrict access to the machine based on various parameters. If you want to include those restrictions in AcuServer, set this variable to TRUE. When set, this variable tells AcuServer to call the loginrestrictions() function to determine whether it is okay to log on or not. (AcuServer first verifies the password against the system password files). See the man page for loginrestrictions() to determine how to set up restrictions.

Parent topic: Server Configuration Variables


V_BASENAME_TRANSLATION

This variable determines whether or not Vision includes full path information in a filename. When V_BASENAME_TRANSLATION is set to the default value of 1 (on, true, yes), only the file's base name (the filename without any extension or path information) is stored. When the variable is set to 0 (off, false, no), complete path and filename information is stored.

Retaining path information can be helpful if you have Vision files with the same name stored in different locations and you want to map one of the segments from one directory to a new location.

Parent topic: Server Configuration Variables


V_BUFFERS

This variable determines the number of indexed block buffers to allocate on the client (if used in a runtime configuration file) or on the server (if used in the server configuration file). These buffers are used to improve the performance of indexed files. Each buffer is 512 bytes plus some overhead. Setting this number larger will generally improve file performance. Setting it smaller will save memory. The value can range from 0 (no buffering) to 2097152. The default value for use with AcuServer is 64.

Parent topic: Server Configuration Variables


V_BUFFER_DATA

This variable determines whether or not Vision indexed file data blocks (as opposed to key blocks) will be held in the memory-resident disk buffers. When it is set to 1 (on, true, yes), the default, both data blocks and key blocks will use the buffers. When set to 0 (off, false, no), only key blocks will use the buffers. Setting this value to 1 will usually improve performance unless very few buffers are being used.

Note: Holding data blocks in the buffers slightly increases the chances of losing data if a file opened for MASS_UPDATE is not closed properly (such as a power failure). The default setting of this variable is 1.
Parent topic: Server Configuration Variables


V_INDEX_BLOCK_PERCENT

Because the index data stored in index segments is often much smaller than the record data contained in data segments of Vision 5 and Vision 6 files, a large pre-allocate or extension factor typically allocates many more blocks than are needed. V_INDEX_BLOCK_PERCENT allows you to determine the ratio of index block to data blocks that are created for a Vision file, which can help trim file size when disk space is tight.

  • When V_INDEX_BLOCK_PERCENT is set to a value smaller than 100, fewer index blocks are created than data blocks.
  • When this variable is set to a value greater than 100, more index blocks are created than data blocks.

The value range for V_INDEX_BLOCK_PERCENT is 1 to 1000, and the default value is 100.

For example, if you have a file with an extension factor of 10 and set V_INDEX_BLOCK_PERCENT to 50, the next time the file is extended, 10 new data blocks and 5 new index blocks are created. If you set V_INDEX_BLOCK_PERCENT to 200 for the same file, the next time the file is extended, 10 new data blocks and 20 new index blocks are created.

Parent topic: Server Configuration Variables


V_READ_AHEAD

Setting this configuration variable to 0 (off, false, no) turns off Vision's read-ahead logic. This may improve performance in cases where highly random file processing is being used. The default value is 1 (on, true, yes).

Parent topic: Server Configuration Variables


V_SEG_SIZE

V_SEG_SIZE sets the maximum size of a Vision file segment. Vision Version 5 allows for very large logical files by creating additional physical files (called file segments) as needed.

The default value is 2 GB - 1 KB -1 (which is 2,147,482,623 or hexadecimal 7FFFFBFF). The default is also the maximum value allowed. For best performance, set this value as high as possible, to minimize the number of files created.

Parent topic: Server Configuration Variables


V_STRIP_DOT_EXTENSION

Ordinarily, Vision strips any trailing dot extension (such as .dat) from the logical name of a data file when generating file names for index and data segments (except for the first data segment). Setting V_STRIP_DOT_EXTENSION to 0 (off, false, no) allows you to prevent file extensions from being removed.

For example, the default first index segment name for the logical file file.001 is file.vix, which can cause problems if you also had a file called file.002. When V_STRIP_DOT_EXTENSION is set to 0, the index segment name becomes file.001.vix.

V_STRIP_DOT_EXTENSION is set to 1 (on, true, yes) by default.

Parent topic: Server Configuration Variables


V_VERSION

This variable specifies the version number of new Vision data files that are created by AcuServer. The default value is 6, which produces Vision files in the latest format (Version 6). Version 5 and later files are generated in a dual file format, with data records stored in one segment and overhead key information stored in another. The value 4 produces Version 4 files, which also use the dual file format, but do not support the larger maximum record size and larger block sizes available in Version 5 and later. The value 3 produces Version 3 files, in which data and keys are stored in a single file.

Parent topic: Server Configuration Variables


WINNT-EVENTLOG-DOMAIN

This variable applies only to Windows servers. Set it to the Universal Naming Convention (UNC) name of the computer to which you want to send event log messages. UNC names begin with two backslashes (\), indicating that the resource exists on a network computer. This variable is not changeable outside the configuration file.

Note: The event log machine that you specify must be able to receive messages from the AcuServer machine or message delivery will fail. On the event log machine, use the Windows control panel, User Accounts function to add the AcuServer machine name to the Users or Groups.
Parent topic: Server Configuration Variables


WINNT-LOGON-DOMAIN

This variable applies only to Windows servers. Set it to the name of the Windows domain to log users onto. For this variable to have an effect, you must set the SECURITY_METHOD variable to LOGON. Note that if the domain does not exist, users are denied access to the server.

Parent topic: Server Configuration Variables


Administrator Utilities and Functions

  • Overview
  • acuserve Command-line Options and Formats
  • AcuServer Control Panel Interface
  • Creating and Maintaining the Server Access File
  • Installing and Removing acuserve as a Windows Service
  • Starting and Stopping acuserve
  • Changing acuserve Properties
  • Checking System Status
  • Tracking Server Statistics
  • Closing Stranded Files
  • Checking Version Information
  • Registering Servers
Parent topic: AcuServer Version 10.2.0 User's Guide


Overview

Several activities are involved in the configuration and use of AcuServer® file server software:

  • Creating and maintaining the server access file
  • Installing and removing acuserve as a service on Windows NT and Windows 2000 to 2008 systems
  • Starting and stopping the acuserve daemon or service
  • Changing the attributes of a running process
  • Generating AcuServer system status reports
  • Closing files and connections in response to machine failures and special circumstances
  • Verifying AcuServer version information

With the exception of generating status reports and verifying version information, these activities can be performed only by someone who has privileged access to the system. On UNIX and Linux systems, you must have root or superuser privileges. On Windows systems, you must have administrator privileges. On Windows 2008, if you do not log in as the administrator you will need to use elevated privileges.

How these functions are executed varies depending on the host operating system and your personal preferences. On all systems, all functions can be performed using AcuServer's command-line interface utility. Alternatively, on Windows systems, most functions can also be performed using the AcuServer Control Panel (ACP) utility.

Parent topic: Administrator Utilities and Functions


acuserve Command-line Options and Formats

The acuserve command options and formats on UNIX servers are as follows:

acuserve
acuserve -access

acuserve -config [server] [-n portnum]

acuserve -info [server] [-n portnum] [-w] [-f c]

acuserve -kill [server] [-f] [-n portnum]

acuserve -register [server] [-n portnum]

acuserve -start [-c config] [-e error] [-l] [-t #] [f]
                 [-n portnum]
acuserve -statistics -t [parameter] [-n port]

acuserve -unlock [server] [-a] [-c client] [-u user] [-p PID]
                  [-f FID] [-n portnum]
acuserve -version

The acuserve command options and formats on Windows NT and Windows 2000 to 2008 servers are as follows:

acuserve -access
acuserve -config [server] [-n  portnum]

acuserve -info [server] [-n portnum] [-w]

acuserve -install [server] [-depends svcname] ...
                  [valid start options]

acuserve -kill [server] [-f] [-n portnum]

acuserve -query [server] [-n port]

acuserve -register [server] [-n portnum]

acuserve -remove [server] [-n port]

acuserve -start [-c config] [-e error] [-l] [-t#] [-f]
                [-n portnum]

acuserve -statistics -t [parameter] [-n port]

acuserve -unlock [server] [-a] [-c client] [-u user] [-p PID]
                 [-f FID] [-n port]

acuserve -version

In UNIX environments, entering the acuserve command with no options displays a usage list for the command.

In Windows environments, entering the acuserve command with no options launches the AcuServer Control Panel (ACP).

Parent topic: Administrator Utilities and Functions


AcuServer Control Panel Interface

On Windows systems, you can perform AcuServer operations using the AcuServer Control Panel (ACP). To launch the ACP, do any one of the following:

  • Double-click the acuserve icon.
  • Go to Start > All Programs > extendx.x.x> AcuServer and select AcuServer Control Panel 32-bit or AcuServer Control Panel 64-bit.
  • Enter the acuserve command at the Windows command line.
Note: To use the AcuServer Control Panel on Windows 2008, where User Access Control security is turned on (as it is by default), any user must choose Run as Administrator to use the various Acuserver utilities. UAC can be turned off, in which case the user must merely be a member of the administrators group to fully operate AcuServer.
Parent topic: Administrator Utilities and Functions


Creating and Maintaining the Server Access File

The server access file is an encrypted Vision file that contains records that define which users and client systems are permitted to use AcuServer. The access file manager is used to create and maintain that database. The acuserve -access command is used to start the access file manager from the command line. In the AcuServer Control Panel, the Access tab is used to perform access file manager activities (when you start the ACP, the Access tab is active by default).

See The Server Access File for an introduction to the server access file. See Using the Access File Manager for detailed instructions on using the access file manager.

Parent topic: Administrator Utilities and Functions


Installing and Removing acuserve as a Windows Service

acuserve is designed to run as a Windows service. When you install acuserve as a service, acuserve is started automatically each time the system is booted. If you do not install acuserve as a service, acuserve will stop whenever you log off of the server.

Note: With Windows you can configure any service to be either automatic or manual. As the name suggests, an automatic service starts up automatically when the system is booted; a manual service must be started by an administrator any time the system reboots. By default, acuserve is installed as an automatic service.

When you first install the AcuServer software, you are given the option to automatically install acuserve as a service. If you did not install the service during the initial AcuServer installation process, if you need to install the service again, or if you want to install multiple instances of acuserve, this help section describes the process of establishing acuserve as a service using either the AcuServer Control Panel or the Windows command line. See Installing a Windows NT/2000/2003/2008 Server for more information.

Note that if you have multiple instances of the acuserve service running at the same time, each instance must have a unique name. You can then assign client applications to a particular instance of the acuserve service via the ACUSERVER_PORT variable in the runtime configuration file. This can help to balance the client load and improve performance.

Removing the acuserve service shuts down AcuServer (if the server is currently running), removes acuserve as a Windows NT/2000 service, and deletes any stored start-up parameters for the service.

Remember that you must be logged in as administrator or as a member of the administrators group to install or remove the acuserve service.

Note that installing a service on a particular port resets all start-up options for the service on that port. Any start-up options that you specify when you install the acuserve service on a particular port are stored and used each time the service is started.

  • Installing from the Command Line
  • Installing From the Acuserver Control Panel
  • Removing the acuserve Service
  • Determining if acuserve is Installed as a Service
Parent topic: Administrator Utilities and Functions


Installing from the Command Line

The acuserve -install command installs acuserve as a Windows NT/2000 to 2008 service. Optional arguments to -install include:

Option | Description
server | Specifies the name of the server machine. If no server is specified, the server is assumed to be the local host.
depends Specifies the name of a service or service group on which acuserve depends. This option may be repeated multiple times. The effect of the depends option(s) is to establish a dependency in which acuserve will not start unless each service named after a depends is currently installed on the server as a service. depends must be followed by a space and the name of a Windows service or service group. If the name is a service group, it must be preceded by a "+" character (for example, depends +Alerter). The depends option and service name must come after the server option and before any start options.

If AcuServer is already installed as a service and you want to add or change dependencies, you must remove the acuserve service and reinstall it with the new depends options.

Refer to your Microsoft Windows documentation for information on service dependencies.

most start options Most -start options can be used with -install. The exception is -f, which prevents acuserve from being installed as a service. Note that these options are stored for service start-up on this particular port. See Starting and Stopping acuserve, for a list of options.
For example, to run the service with the arguments -c c:\etc\server1.cfg -le c:\tmp\server1.log on start-up, you would use the following -install command:
acuserve -install -c c:\etc\server1.cfg -le c:\tmp\ server1.log
If there are no options stored for a service, starting the server on a particular port automatically installs a service on that port and stores the options used. In other words, you can install and run a service with one set of arguments and then occasionally run the service with different arguments by using acuserve -start.

If running multiple instances of acuserve, use the -n option to specify a number for a particular acuserve service. The service will be named Acuserve X, where X is the number you specified with this option. If you do not use the -n option, the name of the service will be Acuserve.

Parent topic: Installing and Removing acuserve as a Windows Service


Installing From the Acuserver Control Panel

  1. From theStart > All Programs > extendx.x.x> AcuServer and select AcuServer Control Panel 32-bit or AcuServer Control Panel 64-bit, then select the Services tab.

  2. Click New.

    The Service Properties dialog appears.

  3. Enter the following details:
    Option | Description
    Port | Assigns a port number to this instance of acuserve. The port number must be an integer; for example, 6524.
    Configuration file | Specifies the name and path of the server configuration file. If this option is left blank, acuserve looks for the configuration file in its default location: \etc\a_srvcfg.
    Error file Specifies the name and location of the error file that acuserve uses for error output.
    • If no error file is specified, acuserve will attempt to direct output to a file named acuserve.err in the Windows system directory.
    • If this directory cannot be opened, acuserve will attempt to append to a file named acuserve.err in the current directory.
    • If that file doesn't exist, or if the file append fails, acuserve will print the message acuserve: can't open error output file\ to standard output, and acuserve will terminate.
    Trace level Tracing is used to help identify a problem. Specify a nonzero value only when you are actively isolating a problem.
    • 0 indicates no tracing
    • 7 is the highest level of tracing

    See Starting from the Command Line for a detailed explanation of tracing levels.

    Compress trace output | Select to compress the file specified in Error file using the gzip compression method.
    List configuration variable settings | Select to print a listing of the server configuration file to standard error output. This can be helpful when you are debugging problems that may be related to configuration variables. If you have specified an error file, the listing is captured in this file.
    Track Memory | Select to ensure acuserve tracks memory usage. This option is used in conjunction with the acuserve -statistics command. See Tracking Server Statistics for more information.
    Dependencies Specify the name of a Windows service or service group on which acuserve depends. You may include multiple dependencies. Click Add to bring up a list of possible services and service groups.

    If you enter dependencies in this field, acuserve will not start unless each service named is currently installed on the server as a service.

    For information on service dependencies, consult your Microsoft Windows documentation.

  4. Click OK to install the service.
Parent topic: Installing and Removing acuserve as a Windows Service


Removing the acuserve Service

From the command line, use the acuserve -remove command to remove an instance of an acuserve service.

Optional arguments to -remove include:

Option | Description
server | Specifies the name of the server machine. If no server is specified, the server is assumed to be the local host.
-n | Identifies a particular instance of the acuserve program by port number. The -n must be followed by a space and then an integer, for example, 6524. If no port number is specified, the default port (which has the service name Acuserve) is removed. See the Port option for more information about port numbers.

From the AcuServer Control Panel, select the Services tab. Highlight the service that you want to remove and click Remove.

Parent topic: Installing and Removing acuserve as a Windows Service


Determining if acuserve is Installed as a Service

AcuServer provides you with two easy ways to quickly determine whether acuserve is currently installed as a Windows service, as well as to view any start-up parameters that have been stored for the service.

From the command line, use the acuserve -query command.

Optional arguments to -query include:

Option | Description
server | Specifies the name of the server machine. If no server is specified, the server is assumed to be the local host.
-n | Identifies a particular instance of the acuserve program by port number. The -n must be followed by a space and then an integer, for example, 6524. If no port number is specified, the default port (which has the service name Acuserve) is queried.

When you enter this option, you receive a message stating whether or not the service is installed, and if it is, whether or not the service is currently running. The -query command also displays the start-up parameters that have been stored for the service, if any. For example:

C:> acuserve -query
Service 'AcuServer' (AcuServer 8.0 on the default port (6523)) exists
Start Up: Automatic
Program: 'C:\Program Files\Acucorp\Acucbl810\AcuGT\bin\acuserve.exe'
Startup arguments: '-c c:\etc\server1.cfg -le c:\tmp\server1.log'
Status: running

C:>

Note that the startup arguments listed are the arguments used to install the service, and may not be the arguments given to the currently running server.

From the AcuServer Control Panel, select the Services tab. This tab provides a list of all installed services. Services are listed by port number, with a summary of the arguments used by each process listed in the Command Line field. A green bullet next to the port number indicates that the service is currently running, while a red bullet indicates a service that is stopped.

To obtain further information about the installed services, select a service and click Properties. This opens the Service Properties window, which provides a more detailed breakdown of the service properties summarized in the Command Line field on the Services tab.

Parent topic: Installing and Removing acuserve as a Windows Service


Starting and Stopping acuserve

You must be logged onto a UNIX server as root or superuser or onto a Windows NT, Windows 2000 to 2008 server with administrator privileges to start or stop acuserve.

When you start acuserve, you can specify a number of startup options. If you start acuserve without specifying any options, the current defaults are used. AcuServer returns a status to the operating system indicating success or failure of the start. See Start Status Codes for a list of return codes.

When you stop the acuserve daemon/service, acuserve attempts to close all open files before shutting down.

CAUTION:
If you terminate the acuserve process using UNIX commands, such as kill, or using the Windows Task Manager, you prevent acuserve from performing an orderly shutdown. These methods should never be used when clients are actively using AcuServer. Instead, stop acuserve using one of the procedures described in the help.
  • Starting from the Command Line
  • Starting on UNIX
  • Stopping from the Command Line
  • Starting and Stopping From the AcuServer Control Panel
Parent topic: Administrator Utilities and Functions


Starting from the Command Line

Use the acuserve -start command to start acuserve. On Windows NT and Windows 2000 to 2008 servers, this option also installs AcuServer as a Windows NT/2000/2003/2008 service, if it is not already installed, unless the -f option is specified. (If -f is specified, AcuServer runs as a foreground process.)

Any -start options that you use when you first start acuserve as a service/daemon are stored and used as the default startup options. If you do not specify any -start options, acuserve uses the existing defaults.

The acuserve program is started in background unless the -f option is specified.

If acuserve is already running, AcuServer will output the message:

acuserve is already running on hostname

A new acuserve process will not be started. If you want to start AcuServer with new options, you must stop and restart acuserve.

Note: On Windows NT and Windows 2000 to 2008 systems, it is best to specify acuserve -start with no options, so that acuserve uses the start-up parameters that were stored when you installed acuserve as a Windows service.

Optional arguments to -start include:

Option | Description
-c | Specifies the name and path of the server configuration file. The -c must be followed by a space and then the path and name of the server configuration file. When -c is not used, acuserve looks for the configuration file in its default location: /etc/a_srvcfg for UNIX or \etc\a_srvcfg for Windows NT/2000.
-d | Indicates that acuserve should track memory usage. This option is used in conjunction with the acuserve -statistics command. See Tracking Server Statistics for more information.
-e Causes error output from acuserve to be output to the named file. The -e must be followed by a space and the path and name of the error output file.

If -e is not specified, acuserve will attempt to direct error output to /dev/console in UNIX or to a file named acuserve.err in Windows. This file resides in the Windows NT/2000 system directory (typically c:\winnt\system32).

If these directories cannot be opened, acuserve will attempt to append to a file named acuserve.err in the current directory. If that file doesn't exist, or if the file append fails, acuserve will print the message acuserve: can't open error output file to standard output, and acuserve will terminate.

-f By default, acuserve runs in background. Use the -f option to run acuserve in foreground. When run in foreground, the acuserve process traps normal keyboard signals, such as Control+C.

If combined with the -t option, the -f option causes acuserve to display tracing and transaction messages directly to the screen. However, if the -e switch is used, all messages are placed in the named log file.

Note: If you specify the -f option on a Windows NT/2000 machine, acuserve will not install itself or run as a Windows NT/2000 service.
-g | Causes the error file specified with the -e option to be compressed using gzip compression. Note that the name of the error file is not automatically modified to indicate that compression is being used; you may wish to assign the file a .gz extension.
-l | Causes a listing of the server configuration file to be printed to standard error output. This can be helpful when you are debugging problems that may be related to configuration variables. When this option is combined with the -e option, the listing is captured in the error output file.
-n Assigns a port number to this instance of the acuserve program. The -n must be followed by a space and then an integer, for example, 6524. This value overrides the ACUSERVER_PORT value set in the server configuration file.

The -n option associates a port number with one instance of the acuserve daemon. Client applications can, in turn, be assigned to a particular instance of the acuserve daemon via the ACUSERVER_PORT variable in the runtime configuration file.

The acuserve daemon can work with privileged port numbers (from 0 to 1023) and with non-privileged port numbers (1024 and higher). Privileged port numbers are useful for external, secure applications.

Note: If you start acuserve on two ports, you must also specify all start-up arguments, including the configuration file, as in:
acuserve -start -n 6523 -c c:\etc\config1 [other options]
acuserve -start -n 6524 -c c:\etc\config2 [other options]
-t # Turns on file tracing and transaction logging. When combined with the -e option, file trace and transaction messages are placed in the named error file. "#" represents the type of tracing or logging to be performed:
  • 1 turns on file tracing, and a message is printed to standard output every time a file operation is performed. The message includes the type of file operation performed, the name of the target file or file ID, and the values of any applicable keys.
  • 2 turns on connection information logging, and a message is output whenever a connection request is made, a disconnect is performed, or an acuserve -kill or acuserve -unlock command is processed.
  • 3 turns on file tracing and connection information logging.
  • 5 turns on file tracing and flushes the error file after each write operation. (File trace flushing can also be controlled with the FILE_TRACE_FLUSH server configuration variable. See Server Configuration Variables for more information.
  • 6 turns on connection information logging and flushes the error file after each write operation.
  • 7 turns on file tracing and connection information logging and flushes the error file after each write operation.
Note: You can also set these trace levels using the FILE_TRACE server configuration variable.

Note that when AcuServer is started as a Windows NT, Windows 2000 to 2008 service, all paths used in the configuration file or on the command line are relative to the Windows NT, Windows 2000 to 2008 system directory (for example, c:\winnt\system32). For instance, if your current directory is c:\Program Files\acucorp\acucbl8.x.x\AcuGT\bin, and you start AcuServer with the command acuserve -start -le acuserve.log, the log file will not be created in the current acuserve -start -le acuserve.logdirectory, but rather in the \winnt\system32 directory. If desired, you can use full pathnames, which has the effect of using an explicit file.

Parent topic: Starting and Stopping acuserve


Starting on UNIX

On a UNIX server, to start acuserve whenever the server boots, add the acuserve -start command to the system boot file. Your entry might be similar to the following in Bourne Shell:

# If the acuserve executable is present,
# start acuserve
if  (test -f  /acucobol/acuserve)  then
   echo Starting acuserve > /dev/console
   /acucobol/acuserve -start \
      -e /acucobol/acuserve.log
fi
Parent topic: Starting and Stopping acuserve


Stopping from the Command Line

The acuserve -kill command causes the acuserve process to be halted (killed). If no server is specified, the acuserve process is halted on the current host; otherwise, the process is halted on the named host.

Unless the -f option is specified, acuserve prompts for confirmation before the halt action is executed, as shown below.

Shutting down acuserve on: condor
There are 0 files in use by acuserve on: condor
Do you really want to shut down acuserve [N]?

Respond by entering Y or N.

Optional arguments to -kill include:

Option | Description
server | Specifies the name of the server machine on which to kill the acuserve process. If no server is specified, the server is assumed to be the local host.
-f | Causes the acuserve process to terminate immediately, without prompting for confirmation. -f should be used when acuserve -kill is included in a program or script.
-n | Identifies a particular instance of the acuserve program by port number. The -n must be followed by a space and then an integer, for example, 6524. If no port number is specified, the default port is terminated.
Note: If you issue the acuserve -kill command while an ACUCOBOL-GT Web Runtime is connected to the server, the connected client program (and browser window) will hang.
Parent topic: Starting and Stopping acuserve


Starting and Stopping From the AcuServer Control Panel

  1. To access the AcuServer control panel, do one of the following:
    • From the Extend Start Menu, click AcuServer Control Panel from the AcuServer folder.
    • From the command prompt, type acuserve and press Enter.
    Note: You need to run the AcuServer control panel as an administrator.
  2. Select the Services tab.

    You will see a list of port numbers and startup options for installed acuserve services. Services that are currently running are marked with a green bullet, and services that are stopped are marked with a red bullet.

  3. To start a service, highlight the service and click Start.

    To change the startup properties for a service, highlight the service and click Properties. Any modifications that you make to the startup properties for that service are stored and used as the default startup properties the next time the service is started.

    Note: You cannot start acuserve in the foreground using the ACP. If you want to start acuserve in the foreground, use the command acuserve -start -f at the Windows command line.
  4. To stop a service, highlight the service and click Stop.
Parent topic: Starting and Stopping acuserve


Changing acuserve Properties

Both the acuserve -config command and the Config tab of the AcuServer Control Panel allow you to change the configuration of a running acuserve process. You can use these functions, for instance, to turn tracing on or off or to change configuration variables such as PASSWORD_ATTEMPTS.

See Server Configuration Variables for a list of valid variables.

  • Changing Properties From the Command Line
  • Changing Properties From the AcuServer Control Panel
Parent topic: Administrator Utilities and Functions


Changing Properties From the Command Line

When you enter the acuserve -config command, you start communicating with the process running on the named server and named port. If no server name is given, the local server is assumed. If no port number is given, the default port is assumed.

Optional arguments to -config include:

Option | Description
server | Specifies the name of the server machine on which the acuserve process is to be configured. If no server is specified, the server is assumed to be the local host.
-n | Identifies a particular instance of the acuserve program by port number. The -n must be followed by a space and then an integer, for example, 6524. If no port number is specified, the default port is configured.

After you have entered the -config option, the prompt srvcfg> is displayed. At this prompt, enter any of the following commands:

Command | Description
GET variable-name Fetches and displays the value of a single variable. For example:
srvcfg> get max_files
MAX_FILES: 32
SET variable-name new-value Sets the value of a variable. For example:
srvcfg> set max_files 320

Note that if given an invalid variable name, the acuserve process sets a variable of that name with the given value, even though that variable will not have any effect on acuserve.

Be aware, also, that some variables are checked by acuserve only at initialization, so changing these variables on a running instance of the service will have no effect. For example, if you try to set ACUSERVER_PORT, SERVER_IP, or SERVER_NAME with the acuserve -config command, you receive an error message similar to the following:

srvcfg> set SERVER_IP 192.215.170.34
Setting the SERVER_IP has no effect
srvcfg> get SERVER_IP
SERVER_IP: 192.215.170.34

Note that the GET command will show the new value, but the value will not be used.

LIST [(>|>>) file] | Lists the names and current values of all variables of which AcuServer is aware, including some that do not directly affect AcuServer. Use the optional "{>|>>} file" syntax to send the output to a named file instead of the screen. ">" creates a new file of the specified name, and ">>" appends the output to an existing file.
! cmd | Causes the command cmd to be executed.
HELP | Prints a quick synopsis of available commands. It looks very similar to the above list.
QUIT | Exits the configure mode.
Parent topic: Changing acuserve Properties


Changing Properties From the AcuServer Control Panel

  1. To view configuration information, select the Config tab in the AcuServer Control Panel.

    Initially, the Config tab appears empty, because no server has been selected.

  2. Click Query, then select the name of the server machine and the port on which acuserve is running.

  3. Click OK.

    The configuration file entries for the service that you specified now appear on the Config tab.

  4. If you want to make changes to the way that acuserve is configured, use the New button to add configuration variables, or use the Modify button to remove or change configuration variables and their parameters.

    See the description of SET in Changing Properties From the Command Line for information about limitations and effects of changing variables for an active service.

Parent topic: Changing acuserve Properties


Checking System Status

System status reports, which are available both from the command line (-info) and within the ACP, include both a list of all open files and the total number of files open for a particular instance of acuserve. Connections that do not have any open files are also listed.

Status reports contain the following sections:

Field | Description
Client | Identifies the client machine associated with the open file.
User | Identifies the client user name associated with the open file.
PID | The process ID of the client application on the client system. Because service requests originating on different clients may have the same PID, the command acuserve -unlock requires that the PID be qualified with a client name.
TY | Indicates the type of open data file: (I)ndexed, (R)elative, (S)equential, (O)bject, or (F)ile.
FID | A unique file process ID associated with each open file on the server (FIDs are guaranteed to be unique).
Opened | Shows the date and time that a file was opened. To see this field from the command line, you must use the -w option.
File Name | Displays the name of the open file.

Note that the ACP includes statistics for servers that are controlled by the server that was queried in a master/slave relationship, but it does not indicate which file is open by which server. Rather, it lists all the files open by the master and its slaves.

  • Generating Status Reports From the Command Line
  • Checking Status from the AcuServer Control Panel
Parent topic: Administrator Utilities and Functions


Generating Status Reports From the Command Line

Use the command acuserve -info to generate an AcuServer system status report.

Optional arguments to -info include:

Option | Description
server | Specifies the name of the server machine whose status is to be reported.
-f | Returns the full client name and user name, up to 170 characters. Without this option, the client and user names can contain up to only 14 characters each.
-n | Identifies a particular instance of the acuserve program by port number. The "-n" must be followed by a space and then an integer, for example, "6524". If no port number is specified, status for the default port is reported.
-w | Generates a wide report that includes the date and time that each file was opened and shows file names as long as 190 characters.

The default status report has the following format:

Client       User         PID     TY   FID      File Name
----------   ----------   -----   --   ------   --------------------------
robin        chris        1813         <No open files for this connection>
starling     bernie       1281    I    5d7e8    /usr2/bsmi.../dat/IDX.DAT
starling     bernie       1281    S    5ce08    /usr2/bsmi.../dat/SUP.DAT

2 file(s) in use by acuserve on: condor
Port Number: 6523, AcuServer version 8.0

The File Name field displays up to 28 characters by default. To generate a report that displays file names of up to 190 characters and includes the date and time that the file was opened, use the -w option. Should the path and file name exceed 28 or 190 characters, the report will attempt to display all of the file name, preceded by the file's parent directory, preceded by the root directory. Path-name components that must be omitted are represented by an ellipsis (three dots). See the preceding example.

Parent topic: Checking System Status


Checking Status from the AcuServer Control Panel

  1. Open the AcuServer Control Panel and select the Info tab.

    By default, the Info tab originally appears blank.

  2. Click Query and specify the server and the port on which the acuserve service is running.

    The server name and port number appear at the top of the Info tab, and information about any clients currently using acuserve appears in the table in the center of the tab.

  3. To refresh the information on the Info tab, click Refresh. To activate an auto-refresh mode, click the Auto Refresh checkbox and enter the number of seconds to wait before a refresh.

    In the lower right of the Info tab, a text message displays the time until the next auto refresh.

Parent topic: Checking System Status


Tracking Server Statistics

AcuServer has an option to collect and report server statistics. When the COUNT_STATISTICS configuration variable is set to true, you can track memory usage, network reads and writes, socket select calls, and time spent in kernel, user, and idle modes. You can also track access to Vision, relative, and sequential data files, recording the number of file reads, writes, rewrites, deletes, and so on. See Server Configuration Variables for more information.

To get memory information, start AcuServer with the new -d option (acuserve -start -d). If you do not specify the -d parameter, memory is not tracked and is reported as 0 at all times.

To get a detailed server history, use the command:

acuserve -statistics -t [parameter] [-n port]

The available parameters are listed below.

Parameter | Short Description | Details
ALL (default) | All statistics | Returns all available statistics for an instance of acuserve
FILE | All data file statistics | Includes file statistics for all Vision, relative, and sequential files
MEMORY | Memory used | Total number of bytes of memory used by AcuServer
NETWORK | Users added | Total number of users who have connected
 | Users removed | Total number of users who have disconnected
 | Files opened | Total number of files that have been opened
 | Files closed | Total number of files that have been closed
 | Network bytes read | Total number of bytes read by AcuServer
 | Network bytes written | Total number of bytes written by AcuServer
 | Immediate select calls | Total number of times select() was called with no timeout
 | Immediate select sockets | Total number of sockets returned when select() was called with no timeout
 | Timed select calls | Total number of times select() was called with a timeout
 | Timed select sockets | Total number of sockets returned when select() was called with a timeout
TIME | % Kernel time, last minute | Percentage of time spent in kernel mode in the last minute
 | % Kernel time, last 5 minutes | Percentage of time spent in kernel mode in the last 5 minutes
 | % Kernel time, last 15 minutes | Percentage of time spent in kernel mode in the last 15 minutes
 | % User time, last minute | Percentage of time spent in user mode in the last minute
 | % User time, last 5 minutes | Percentage of time spent in user mode in the last 5 minutes
 | % User time, last 15 minutes | Percentage of time spent in user mode in the last 15 minutes
 | % Idle time, last minute | Percentage of idle time in the last minute
 | % Idle time, last 5 minutes | Percentage of idle time in the last 5 minutes
 | % Idle time, last 15 minutes | Percentage of idle time in the last 15 minutes
 | Uptime (days hours:minutes) | Amount of time the server has been running
VISION | Vision create | Total number of Vision files created
 | Vision open | Total number of Vision files opened
 | Vision close | Total number of Vision files closed
 | Vision read | Total number of Vision records read dynamically
 | Vision read next | Total number of Vision records read sequentially (next)
 | Vision read previous | Total number of Vision records read sequentially (previous)
 | Vision write | Total number of Vision records written
 | Vision rewrite | Total number of Vision records rewritten
 | Vision delete | Total number of Vision records deleted
 | Vision start | Total number of Vision files started
 | Vision info | Total number of Vision info calls
 | Vision remove | Total number of Vision files removed
 | Vision rename | Total number of Vision files renamed
 | Vision copy | Total number of Vision files copied
 | Vision unlock | Total number of Vision records unlocked
RELATIVE | Relative create | Total number of relative files created
 | Relative open | Total number of relative files opened
 | Relative unlock | Total number of relative records unlocked
 | Relative close | Total number of relative files closed
 | Relative read | Total number of relative records read dynamically
 | Relative read next | Total number of relative records read sequentially (next)
 | Relative read previous | Total number of relative records read sequentially (previous)
 | Relative start | Total number of relative files started
 | Relative write | Total number of relative records written
 | Relative delete | Total number of relative records deleted
 | Relative rewrite | Total number of relative records rewritten
 | Relative remove | Total number of relative files removed
 | Relative rename | Total number of relative files renamed
 | Relative copy | Total number of relative files copied
 | Relative info | Total number of relative info calls
SEQUENTIAL | Sequential create | Total number of sequential files created
 | Sequential open | Total number of sequential files opened
 | Sequential close | Total number of sequential files closed
 | Sequential read | Total number of sequential records read
 | Sequential write | Total number of sequential records written
 | Sequential rewrite | Total number of sequential records rewritten
 | Sequential remove | Total number of sequential files removed
 | Sequential rename | Total number of sequential files renamed
 | Sequential copy | Total number of sequential files copied
Note: Information about select() can be used to determine if clients are waiting a long time before being noticed by AcuServer. When a client has to wait, the number of sockets returned by select() without a timeout will be large, in general, and also large in comparison to the number of calls to select() with a timeout. If the number of sockets returned by calls to select() without a timeout is small, clients are being serviced immediately.
Parent topic: Administrator Utilities and Functions


Closing Stranded Files

Software and hardware errors can sometimes result in the stranding of records and files accessed via AcuServer. AcuServer is equipped to detect and close files opened by Windows clients using AcuServer's dead connection detection mechanism. AcuServer also detects and closes files belonging to client applications that terminate abnormally with a Control+C or kill signal. Other application or system failures may also result in stranded records and files. For example, if a UNIX client suddenly crashes, all files opened by that client remain open and all records locked by that client remain locked. If the client opened a file in a mode that prevents other applications from accessing the file (for example, EXCLUSIVE), that file remains unavailable to other applications. See Machine Failures for more information.

  • Closing Files from the Command Line
  • Closing Files From the AcuServer Control Panel
Parent topic: Administrator Utilities and Functions


Closing Files from the Command Line

The acuserve unlock command provides a mechanism for closing stranded files from the command line. Before you use -unlock, it is best to generate a current AcuServer status report using acuserve -info. The status report provides a complete list of open files on the server, including client name, user name, PID, FID, file type, and the file name of each open file. With information from this report, you can use -unlock to close specific files.

The -unlock command syntax is:

acuserve -unlock [server] [-a] [-c client] [-u user]
                     [-p PID] [-f FID] [-n portnum]

-unlock has two modes of operation:

  • An interactive mode, in which the user is prompted for information about the files to be closed.
  • A command-line mode, in which the user specifies all of the requisite information as additional arguments on the command line.

Optional arguments to -unlock include:

Option | Description
server | Specifies the name of the AcuServer server. If no server is specified, the server is assumed to be the local host.
-a | Causes all open files on the server to be immediately closed. -a does not ask the user for confirmation before closing all files.
-f FID | Causes the file associated with the specified FID to be unlocked and closed. -f must be followed by a space and the FID of an open file.
-c client | When -c is used with no other options, acuserve unlocks and closes all files and sockets held open for the named client on the current host. -c must be followed by a space and the name of an AcuServer client. Use -c in combination with the server option to specify a server other than the current host. -c can be qualified by the -u or -p options.
-u user | Used as a qualifier to the -c option. -u must be followed by a space and the name of an AcuServer user. The -c client -u user combination causes acuserve to close all files and sockets associated with the named user on the named client.
-p PID | Used as a qualifier to the -c option. -p must be followed by a space and the PID of a client process. The -c client -p PID combination causes acuserve to close all files and sockets associated with the specified PID on the named client.
-n port | Identifies a particular instance of the acuserve program by port number. The -n must be followed by a space and then an integer, for example, 6524. This option causes only those files associated with the specified instance of the acuserve program to be unlocked and closed. If no port number is specified, files for the default port are unlocked and closed.
Parent topic: Closing Stranded Files


Closing Files From the AcuServer Control Panel

If you are using the AcuServer Control Panel, you can unlock and close stranded files from the Info tab.

  1. Click Query and select the server name and port number on which acuserve is currently running.
  2. Select the name of the file or files you want to unlock and close, then click Unlock.

    If you want to close all files opened by a user process, select the name of any file opened by that process and click Disconnect.

Note: The Disconnect button in the Info tab of the AcuServer Control Panel performs the same function as entering the command acuserve -unlock -u user -c client -p PID from the command line.
Parent topic: Closing Stranded Files


Checking Version Information

From the command line, enter acuserve -version to see AcuServer version information. -version must be the only argument on the command line.

To check version information from within the AcuServer Control Panel, click on the AcuServer icon in the left corner of the title bar to open the system menu, then select About.

Parent topic: Administrator Utilities and Functions


Registering Servers

When using the AcuServer load-balancing feature (see ACUSERVER_MASTER_SERVER), if the master server dies unexpectedly, the -register command can be used to re-register the secondary or subordinate servers with a newly started master server. This avoids having to shut down and restart the entire system.

The syntax for the command is:

acuserve -register [server] [-n portnum]

This command tells the secondary acuserve running on server and listening on port portnum to re-register itself with the master server. Note that it registers with the master given in the configuration file when it was started. server defaults to the local host, and portnum defaults to the usual port.

Parent topic: Administrator Utilities and Functions


System Security

  • Security Overview
  • The Server Access File
  • Access Records
  • Using the Access File Manager
  • AcuServer Connection Logic
  • Encryption
Parent topic: AcuServer Version 10.2.0 User's Guide


Security Overview

System security for AcuServer file server software is designed to address two fundamental security issues:

  1. Controlling access to data files

    This is addressed in two ways: first, via the AcuServer server access file, and second, through the standard UNIX or Windows NT/2000 to 2008 file access provisions.

    Whether a user of AcuServer can access to a given file depends on two things: (1) the user ID assigned the requester in the server access file, and (2) either the Windows NT/2000 to 2008 security set up for your files, or the UNIX ownerships and permissions set on the particular file.

    On both Windows and UNIX networks you have the option to use your operating system security rather than AcuServer system security. Use the operating system security, which is essentially required when using Windows 2008. By setting the SECURITY_METHOD configuration variable on both the client and the server, you can override the server access file and use the full range of native security features on files and directories on the server instead. See SECURITY_METHOD in Server Configuration Variables for information and considerations.

  2. Preventing unauthorized use of AcuServer to perform privileged activities (such as modifying privileged files)

    This is addressed through strict enforcement of the security measures that you have established through the server's operating system.

    On a Windows NT, Windows 2000 to 2008 server, AcuServer system security is designed to work with files that reside on an NTFS (NT file system). (AcuServer can work with a FAT file system, but the files are less secure and no longer supported.)

    When using the NTFS, you may set read and write access permissions on your files by using the Windows security features. Refer to your Windows documentation for more information about NTFSs and security procedures. Make sure that the AcuAccess file and the a_srvcfg file can be written only by those accounts and groups that you want to have write privileges.

    NTFSs may also have shared directories. The permissions on the shared directory operate in addition to any NTFS permissions you have established. Shared directory permissions specify the maximum access allowed.

    When AcuServer is running as a Windows NT/2000 to 2008 service, it usually belongs to an implicit group called SYSTEM. Make sure that the SYSTEM group (or whichever group that you are using for your acuserve services) is added to your file permissions with Full Control.

    Files created by AcuServer are owned by the administrators group and allow Full Control for SYSTEM and Administrator. Everyone is given the permissions specified by the third digit in the umask in the AcuAccess file. UNIX ownerships and permissions can be set on key AcuServer files. Note, however, that your site could jeopardize security if you include entries in the server access file that explicitly allow users running as root on the clients to run as root on the server. It is strongly recommend against thto not include such entries.

Achieving sound AcuServer system security depends on the configuration and management of the following security elements:

  • The AcuServer server access file (the database of authorized and excluded AcuServer users)
  • The Windows NT, Windows 2000 to 2008 security protections set up for the acuserve executable file, server configuration file, server access file, and remote data files and directories. Recall that the NTFS is more secure.
  • The UNIX ownerships assigned to the acuserve executable file, server configuration file, server access file, and remote data files and directories
  • The UNIX access permissions (read, write, and execute) set on the acuserve executable file, server configuration file, server access file, and remote data files and directories.

UNIX ownerships and permissions on the acuserve executable, server configuration file, and server access file are specified in Ownerships and Permissions. These specifications must be strictly maintained. If the ownerships and permissions are more permissive than those specified, AcuServer will not start.

Parent topic: System Security


The Server Access File

The foundation of AcuServer system security is the server access file. The server access file is an encrypted Vision file, named "AcuAccess" by default. This file is located in the /etc directory on UNIX servers and the root drive, which is normally the c:\etc directory on Windows NT, Windows 2000 to 2008 servers. You may rename the access file, and you can have multiple access files (for multiple instances of acuserve, for example) if desired.

The server access file contains one or more access records. These records define which users of which clients are permitted access to AcuServer.

CAUTION:
If you have updated from a version of AcuServer prior to 6.0.0, the server will detect and convert existing AcuAccess files the first time that they are opened. Updated AcuAccess files are not compatible with earlier versions of AcuServer. If you are operating in an environment that includes AcuServer Version 8.x, 7.x, or 6.x mixed with earlier versions of AcuServer, you must use duplicate AcuAccess files. You should not maintain a mixed environment.

The server access file is designed to support a wide range of access security, from very open to very restrictive. You choose the level of security best suited to your needs.

Note: We recommend that you use native system security rather than AcuServer system security. On Windows 2008 it is essentially required that you use system security. To use native security, you set the SECURITY_METHOD variable in both the runtime configuration file on the client and server configuration file on the server. You still create a server access file containing access records that define your user base, but the server access file is used only to check if the user connecting to the server is allowed to connect, and to check to which local account the connection should be mapped. See SECURITY_METHOD in Server Configuration Variables for more information.

Access records may include wild cards that allow all clients or all users (except root under UNIX and administrator under Windows NT, Windows 2000 to 2008) access to AcuServer. You can also create individual access records for each user of each client, as well as individual records listing users who are explicitly excluded from accessing files.

The individual access records allow you to specify the user ID that AcuServer will use when executing requests for users matching the given record. In this way you can assign a user ID that has exactly the privileges needed, and no more (typical of group access accounts).

In addition, every access record can include a password entry, which the application or user must match before AcuServer will establish a connection. If this password is set to "*", the user is explicitly denied access to AcuServer.

The security system is almost completely transparent to the end user. The user is made aware of the security system only when remote file access requires interactive password authentication.

Creation and modification of the server access file requires root privileges on UNIX, and administrator privileges on Windows NT, Windows 2000 to 2008.

On UNIX servers, the access file must be owned by root and cannot be writable by anyone other than root. If the access file does not exist, is not owned by root, or is writable by users other than root, AcuServer will not start. On Windows NT and Windows 2000 to 2008 servers, the access file must be owned by administrator or the administrators group and cannot be writable by anyone without administrator privileges. If the access file does not exist, is not owned by administrator or the administrators group, or is writable by users without administrator privileges, AcuServer will not start.

Parent topic: System Security


Access Records

The server access file contains one or more access records. You must create access records for each user, whether you are using AcuServer's system security or native system security. Each access record comprises five fields:

Field | Description
Client Machine Name | The name of the client system
Client Username | The user's login name on the client system
Local Username | The local user name that AcuServer will use when fulfilling requests for the client user
Password | Optional password protection. When used, the requester must supply the password specified in this field. Ignored when you use the Windows NT security NAMED-PIPE option
Umask | A three-digit file creation mask. The umask is used when AcuServer creates a new file for the requester. The default value is 002.

From the command line, a typical server access record might look like:

Client Machine Name    Client Username    Local Username    Password    Umask
-------------------    ---------------    --------------    --------    -----
starling               bernie             bsmith             <none>      002

Using the AcuServer Control Panel in Windows, the record might look like the following:

This record will allow user bernie to connect from machine starling. AcuServer will use the local user name bsmith (Bernie's account on the file server) when executing requests for bernie. No password is required. Any files created for bernie will be created with a umask of 002 (read and write permissions for owner and group; read-only permissions for others).

Three fields, Client Machine Name, Client Username, and Local Username, can have a wild card value to indicate a general behavior. These wild cards are:

Field name | Wild card | Meaning
Client Machine Name | * | Match all client machines
Client Username | (empty field) | Match all client users
Local Username | same as client | Use the Client Username

When the string same as client is specified in the Local Username field, if the Client Username is not a valid name on the server, DEFAULT_USER is used. In addition, if the Local Username field is blank, DEFAULT_USER is used.

On Windows client systems, Client Username is set to the name given by the user at logon. If the operating system does not provide a logon, or if the user bypasses the logon, the value of the environment variable USER is applied. If USER is not defined, the value of the environment variable USERNAME is applied. Note that the values assigned to these variables are case-sensitive. Be sure that the case used in the AcuAccess file matches the case of the value set in the variable. If neither USER nor USERNAME is defined, the literal string USER is used.

For illustrative purposes, here is a set of common access records as seen from the command line:

Client Machine Name    Client Username    Local Username    Password    Umask
-------------------    ---------------    --------------    --------    -----
support-pc                                techie            <none>      002
warehouse-pc                                                <none>      002
president-pc           diamond            <same as client>  <none>      002
robin                                     <same as client>  <none>      002
falcon                 rjones             <same as client>  *           002
starling               felice             <same as client>  <none>      002
starling               baxter                               ......      002
swallow                hartley            hartley           <none>      002
swallow                                   acct              <none>      002

Here is the same set of access records seen in the AcuServer Control Panel's Access tab:

These entries are interpreted as follows:

Field | Description
support-pc | Allows any user of support-pc to use AcuServer. AcuServer will use the local user name techie when executing requests for support-pc.
warehouse-pc | Allows any user of warehouse-pc to use AcuServer. Because the Local Username field is empty, AcuServer will use the value of DEFAULT_USER as the local user name when executing requests for warehouse-pc.
president-pc | Allows user diamond to access AcuServer. For this record to match, the environment variable USERNAME or USER must be defined with the value diamond. AcuServer will also attempt to use diamond as the Local Username. If diamond is not a valid local user name, the value of DEFAULT_USER will be used.
robin | Allows all users of robin to access AcuServer. If the requester has an account on the server by the same name, AcuServer will use that name; otherwise, AcuServer will use the value of DEFAULT_USER.
falcon | Specifies that user rjones will not be allowed to access files through AcuServer. If rjones tries to access an AcuServer file, she will receive an error 9D,103, indicating that access is denied.
One entry for starling | Allows user felice to access AcuServer. AcuServer will follow the same rules as the previous entry to assign a local user name.
Other entry for starling | Allows user baxter to access AcuServer. AcuServer will use the value of DEFAULT_USER when executing requests for baxter. baxter will need to provide a password before a connection will be established.
One entry for swallow | Allows user hartley to access AcuServer. AcuServer will use the local user name hartley when executing requests for hartley.
Other entry for swallow | Allows all users of swallow to access AcuServer. AcuServer will use the local user name acct for all users of swallow, except hartley (or other records for swallow that explicitly name a client user).
Parent topic: System Security


Using the Access File Manager

You create and maintain the server access file using the Access File Manager utility from the command line, or if you're running under Windows, from the Access tab of the AcuServer Control Panel (ACP); see Using AcuServer’s Graphical User Interface for Windows for more information.

  • To start the Access File Manager utility from the command line, use the command acuserve -access.
  • To start the AcuServer Control Panel in Windows, go to Start > All Programs > Extend x.x.x. > AcuServer > AcuServer Control Panel, then click the Access tab.

Using either of these methods, you can:

  • Create an access file
  • Add an access record
  • Remove an access record
  • Modify an access record
  • Display an access record or records

If you are managing access records from the command line, note that when the Access File Manager displays a value inside a pair of square brackets ([ ]), that value is the default value for the field. To accept the default value, simply press Enter. In the following example, /etc/AcuAccess is the default value.

Enter the name of the Server Access File
Filename [/etc/AcuAccess]:
  • Creating or Opening an Access File
  • Adding an Access Record
  • Removing an Access Record
  • Modifying an Access Record
  • Displaying an Access Record
  • Exiting the Access File Manager
Parent topic: System Security


Creating or Opening an Access File

Whether you use the command line or the AcuServer Control Panel (ACP) to create or open an access file, the procedure is similar. You first specify a path and file name. If the file does not exist, you choose whether to create a new file or re-enter path and file-name information.

  • Creating and Opening an Access File From the Command Line
  • Creating and Opening an Access File From the AcuServer Control Panel
Parent topic: Using the Access File Manager


Creating and Opening an Access File From the Command Line

  1. Use the acuserve -access command to open the file access manager.
  2. Enter the path and name of the server access file:
    Enter the name of the Server Access File
Filename [/etc/AcuAccess]:
  3. If the specified server access file is not found, either type Y to create the file or N to re-enter the file name.
    'access-file' does not exist.
Do you want to create it [N]?
  4. The manager opens the access file and displays a menu of five options:
    Server Access File Options
1 - Add a security record
2 - Remove a security record
3 - Modify a security record
4 - Display one/all security records
5 - Exit
Enter choice [4]:
Parent topic: Creating or Opening an Access File


Creating and Opening an Access File From the AcuServer Control Panel

The last access file used is already open when you select the Access tab; however, to open an existing AcuAccess file, click Open, then browse to the correct directory and select the access file that you want to edit from the list of files provided.

To create a new access file:

  1. Select the Access tab of the AcuServer Control Panel and click Open.
  2. Browse to the directory where the new access file will reside (the default is c:\etc).
  3. Type the name of your new access file and click Open.

    A dialog box appears, confirming the name and location of the new access file.

  4. Click Yes.

You can now add records to your new access file.

Parent topic: Creating or Opening an Access File


Adding an Access Record

To add an access record, you must assign a value to each of the five access record fields:

  • Client Machine Name

    The "*" symbol indicates that the record will match all clients for which there are no other records. (This will be the default setting for all clients that do not have a specific record.) You can also enter the official machine name for a client machine. You cannot use alias names in this field.

  • Client Username

    If you do not specify a client username, leaving the field blank, any user name will match. For Windows clients that do not define a USERNAME or USER environment variable, this field should be left blank or set to USER. See Access Records for more information.

  • Local Username

    The Local Username is the name that AcuServer will use when executing access requests for requesters that match the first two fields of this record.

    Note that if the Local Username is not a valid name on the server, the server will attempt to use the value of the server configuration variable DEFAULT_USER (if defined). If DEFAULT_USER is not defined, the connection will be refused (AcuServer returns an error 9D/103).

    If the local username is the same as the client user name, leave the Local Username field blank.

  • Password

    Inclusion of a password is optional. AcuServer ignores any password included in the AcuAccess record when you use the Windows NT security named pipe option rather than AcuServer system security.

    Passwords can be up to 64 characters long. The set of allowable characters includes upper and lower case letters, numbers, the space character, and most special characters (all ASCII characters numbered 32 to 126). Delete, escape, and other non-printable characters are not allowed.

    To prevent a user from attempting to log in to AcuServer, assign that user the password "*". The excluded user will receive an error 9D/103, indicating that access is denied.

  • Umask

    The umask is a three-digit code that sets the read and write permissions on new files created for the requester by AcuServer. For more about umask, see the end of and your UNIX operating system documentation.

    If you accept all of the defaults when creating the record, and you are using the command line, the entry will look like:

    Client Machine Name    Client Username    Local Username    Password    Umask
-------------------    ---------------    --------------    --------    -----
*                                         <same as client>  <none>      002

    If you are using the ACP and accept all of the defaults, the entry will look like:

    This is the most permissive access record that can be created. This record will match any client and allow any user to connect to the server, provided that either:

    • The user has an account of the same name on the server
    • The DEFAULT_USER variable is defined with the name of a valid user

    Through inclusion or exclusion of wild cards, named entries, passwords, and umasks, it is possible to construct a server access file that allows open, unrestricted access; rigid, tightly controlled access; or most any level in between.

  • Adding a Record From the Command Line
  • Adding a Record From the AcuServer Control Panel
Parent topic: Using the Access File Manager


Adding a Record From the Command Line

  1. To add an access record, start the access file manager and select option [1] from the main menu.

    You are prompted to enter a client machine name. The prompt looks something like this:

    A value of "*" for client machine name means that this
record will match all clients for which there are no
other records.  You cannot use alias names. The name
must be the official machine name.
Enter the official machine name [*]:
  2. Enter a client machine name or accept the default value.

    You are prompted to enter the client username.

    If no client user name is entered it implies any user.
Enter client user name []:
  3. Enter a client user name or accept the default value.

    You are prompted to enter the local username.

    A value of 'same as client' for local user name means
to use the client user name.  If no local user name is
entered DEFAULT_USER is used.
Enter the local user name [same as client]:
  4. Enter a local user name or accept the default value.

    You are prompted to enter a password.

  5. If you want the specified user to have a password, enter the password. The password characters are not echoed on the screen.

    You are asked to enter the password a second time to verify that it was entered correctly.

    If no password is entered it implies none.
Enter password []:
Retype password for verification:

    Should the password verification fail, you will see the following message:

    Mismatch - try again.
If no password is entered it implies none.
Enter password []:

    You are prompted to enter a umask.

    The umask defines the file creation mask for all files
created by this user.  It must be an octal value between
000 and 777.
Enter umask [002]:
  6. Enter a umask value or accept the default value. If an invalid umask value is entered, you will see this message:
    Invalid value for umask - try again.

    After you specify a valid umask, the access file manager adds the record to the server access file.

    Record added.
Press <Return> to continue...
Parent topic: Adding an Access Record


Adding a Record From the AcuServer Control Panel

To add an access record using the graphical interface, open the AcuServer Control Panel and open the server access file to which you want to add a record.

Note: The last access file to be used is automatically opened.
  1. Click New.

    The Access User screen appears.

  2. Enter the Client Machine Name, Client User Name, Local User Name, Password (if any), and Umask value.
  3. Click OK to accept the record.
Parent topic: Adding an Access Record


Removing an Access Record

To remove a record from the command line, select option [2] from the access file utility main menu. The manager will present two prompts: one for the client machine name and one for the client user name. The prompts will look something like this:

Enter official client machine name:
Enter client user name:

If a matching record is found, it is removed.

Record removed
Press <Return> to continue...

To remove a record from the Access tab of the AcuServer Control Panel, highlight the applicable record and click Delete.

Parent topic: Using the Access File Manager


Modifying an Access Record

Using either the command-line access file utility or the AcuServer Control Panel, you can modify the local user name, password, and umask value for an existing access record.

If the client machine name or client user name changes, you must delete the existing access record and create a new one.

  • Modifying a Record from the Command Line
  • Modifying a Record From the AcuServer Control Panel
Parent topic: Using the Access File Manager


Modifying a Record from the Command Line

Select option [3] from the access file utility main menu. The access file manager will present a series of prompts. The first two prompts ask for the client machine name and client user name, followed by a display of the matching record, as shown in the following example:

Enter official client machine name:  president-pc
Enter client user name:  diamond

Here is the record that was found:

Client machine name:  president-pc
Client user name   :  diamond
Local user name    :
Password           :  <none>
Umask              :  002

The next three prompts allow you to change the local user name, the password, and the umask.

Do you want to modify the local user name [N]:
Do you want to modify the password [N]:
Enter a new umask [002]:

After the umask value is entered, the record is updated.

Record modified
Press <Return> to continue...
Parent topic: Modifying an Access Record


Modifying a Record From the AcuServer Control Panel

  1. On the Access tab of the AcuServer Control Panel, highlight the record that you wish to change and click Modify.

    The Access User box shows the Client Machine name and Client User Name and provides text boxes in which you can modify the Local User Name, Password, and Umask entries.

  2. Enter the changes you wish to make and click OK to save the modified access record.
Parent topic: Modifying an Access Record


Displaying an Access Record

To display one or all of the access records from the command line, select option [4] from the access file utility main menu.

You can display records to the screen, or you can output all of the records to a file. The manager first asks if you want to display the records to the screen.

Display to the screen [Y]? y

If yes, the manager will respond with the following prompt:

Display all records [Y]? y
Displaying all records...

If you want to see an individual record, respond no (n) to Display all records?, and the manager will display the following prompts:

Enter official client machine name:
Enter client user name:

If a match is found, the record will be displayed, otherwise the manager will state that no match was found and return to the main menu.

No matching record found.
Press <Return> to continue...

If you want to copy all of the records to a file, respond no to the Display to the screen? prompt. The manager will then prompt for a filename.

Enter the name of the Server Report File
Filename [AcuAccess.rpt]:

Enter a file name, or accept the default. The manager will copy the access records to the named file.

Creating 'AcuAccess.rpt'

In the AcuServer Control Panel, the access records contained in a specific AcuAccess file are automatically displayed when you open the server access file. Note that regardless of whether or not passwords have been specified in the AcuAccess file, the list of records shown in the ACP does not include a Password column.

Parent topic: Using the Access File Manager


Exiting the Access File Manager

To exit the command-line manager, select option [5] from the main menu.

To exit the graphical manager, click the close button at the top right corner of the AcuServer Control Panel dialog, or click Cancel. Note that clicking Cancel will not undo any changes that you have made to the AcuAccess files.

Parent topic: Using the Access File Manager


AcuServer Connection Logic

The AcuServer connection validation logic is described here to clarify the use of the server access file and the DEFAULT_USER configuration variable.

When a client process (running application) makes its first request to AcuServer, AcuServer performs the following access validation procedure whether AcuServer system security or native system security is being used.

To validate the requester's access privileges, AcuServer:

  1. Opens the server access file.
  2. Searches for a record that matches both the client machine name and the client user name.
  3. (If no match is found) searches for a record that matches the client machine name and a match all (blank) client user name.
  4. (If no match is found) searches for a record that has the "match all" ("*") client machine name and the client user name.
  5. (If no match is found) searches for a record that has the "match all" ("*") client machine name and the match all (blank) client user name.
  6. (If no match is found) refuses the connection.

When a match is found, and the named-pipe form of security is turned on (via the SECURITY_METHOD variable), and the client user has an account on the server, AcuServer automatically grants the user permission to connect. The AcuAccess file does not set the client user's local username, nor does it determine whether the client is required to enter a password.

When a match is found and the LOGON form of security is turned on, AcuServer attempts to use the value of the matching password field in the AcuAccess file to log the user on. If the password isn't valid or the password field is empty, the user is prompted to enter a password. If a valid password is given, the requester is logged on, otherwise the connection is refused.

When a match is found and AcuServer system security is being used:

  1. If the Local Username is valid, it is used.
  2. If the Local Username is not valid, DEFAULT_USER is used.
  3. If the Local Username is not valid and DEFAULT_USER is not valid, the connection is refused.

If the Local Username is valid and the password field is defined, a message is sent back to the requester asking for a password. See Passwords for more information about password handling.

When the client process terminates, the client-server connection is broken. New client applications requesting AcuServer services will go through the verification process to establish a connection.

  • Passwords
Parent topic: System Security


Passwords

Regardless of whether you're using AcuServer's built-in security or native system security, defining passwords in the access records of your AcuAccess file can be very useful.

If you are using LOGON security, defining the password field to hold the user's current Windows NT domain password can make the login process transparent. When a requester initiates a connection to AcuServer, AcuServer uses the value of the requester's password field, if defined, to log the requester onto the Windows NT domain. If the password is not valid, the user is prompted to enter a password. If the user enters a blank password, that entry counts as one password attempt, but AcuServer does not give an error message, and the user can try again. Note that the named-pipe form of security does not use the password field. See SECURITY_METHOD for more information.

If you are using UNIX system security, you can simplify the login process by defining the password field to hold the user's current system password.

If you are using AcuServer's system security, you can use passwords to achieve added security. When a password is assigned to an entry in the server access file, requesters who match that entry must return a matching password to AcuServer. The client application has two options for acquiring and sending a password back to AcuServer:

  • Using the Acu_Client_Password program variable
  • Having the client runtime prompt users to enter a password

Option one: program variable

The requesting application may include code that checks for the program variable Acu_Client_Password. If defined, its value is considered an unencrypted password, which is then encrypted and sent to AcuServer for verification. If the value does not match the value in the access record, the connection is refused. Using Acu_Client_Password, the COBOL programmer has a great deal of flexibility in setting and acquiring the password; the programmer can supply a password to AcuServer without requiring any user interaction (the user may remain unaware that a password is required).

To use Acu_Client_Password, declare an external pic X variable named Acu_Client_Password in Working-Storage.

ACU_CLIENT_PASSWORD PIC X(64) IS EXTERNAL

Assign (MOVE) a value to the variable before the program’s first access to a remote file (or better, before the program’s first access to any file).

Option two: user-entered password

If Acu_Client_Password is not defined, the client runtime will open a dialog window requesting that the user enter a password.

A password is required to connect to host hostname.
Please enter a password:

The user must enter a password. The characters do not echo on the screen.

The password is then encrypted and sent to the server for verification. If the password matches, a connection is established. If the password doesn’t match, the user is prompted again to enter a password.

Invalid password
Please enter a password:

The password verification cycle is repeated until a valid password is entered, or the value of the server configuration variable PASSWORD_ATTEMPTS is exceeded (the default value is 3). If you have a situation in which a client connects to acuserve many times in succession, you may want to set the server_PASSWORD and server_port_PASSWORD environment variables on the client. This allows AcuServer to verify the client password automatically, instead of repeatedly prompting the user to enter a password.

For more information about setting these environment variables, see Appendix H in Book 4 of the ACUCOBOL-GT documentation set.

The text displayed by the runtime to prompt for a password and report a failed verification can be modified with the TEXT runtime configuration variable. See Runtime Configuration Variables for more information.

Parent topic: AcuServer Connection Logic


Encryption

If necessary, you can direct AcuServer to encrypt all data exchanged between AcuServer and a given requester (a client connection).

Note: The use of encryption can have a significant performance cost. The performance cost is determined by the quantity of data being exchanged, the speed and bandwidth of the network, and the computational power of both the client and AcuServer host machines. If you plan to use encryption, prior to deployment you should test and benchmark your application with encryption enabled to ensure that your performance requirements are met.

Encryption is enabled with two configuration variables: ENCRYPTION_SEED and AGS_SOCKET_ENCRYPT. Once encryption is turned on, it remains on until the program terminates and the connection with AcuServer is closed.

The configuration variable ENCRYPTION_SEED must be set in both the AcuServer configuration file and the runtime (client-side) configuration file. The value of ENCRYPTION_SEED is used to initialize the encryption facility. See Server Configuration Variables for more information.

The configuration variable AGS_SOCKET_ENCRYPT must be set to on in the runtime configuration file. If it is set within the program, it must be set to on before the application opens its first remote file. The default value of AGS_SOCKET_ENCRYPT is off.

Parent topic: System Security


Programming for AcuServer

  • Programming Considerations
  • Accessing Remote Files
  • Server Name Management
  • Multiple-Record Mode
  • Restrictions to Library Functions
  • C$COPY
  • C$FILEINFO
  • RENAME
Parent topic: AcuServer Version 10.2.0 User's Guide


Programming Considerations

There are three programming issues to consider with AcuServer file server software:

  • How to modify your application to use remote name notation to access remote files.
  • How to minimize the work required to add or change the name of an AcuServer file server (pertinent to large or rapidly changing networks).
  • How and whether to use AcuServer's multiple-record mode (pertinent to those who read a large number of sequential records without user interruption, as when generating reports).

This help section discusses these programming issues. In addition, it discusses restrictions to three ACUCOBOL-GT® library routines of which programmers should be aware: C$COPY, C$FILEINFO, and RENAME. See Restrictions to Library Functions for more information.

Parent topic: Programming for AcuServer


Accessing Remote Files

Enabling your applications to use AcuServer requires that your applications reference remote files with remote name notation. To ensure that all references to remote files include remote name notation, you need to know how your application currently finds data files:

  • Are file paths defined in the application code?
  • Are file name aliases defined in the runtime configuration file?
  • Are the runtime configuration variables FILE_PREFIX or CODE_PREFIX used to define search paths?

If your file paths are hard-coded in your source code, you'll need to modify them to add remote name notation. A better approach, however, is to remove hard-coded paths and to replace them with the FILE_PREFIX configuration variable, or name aliases.

Note: If your application exclusively uses FILE_PREFIX and/or CODE_PREFIX to define data and code file search paths, all you need to do to enable your application to use AcuServer is to add remote paths to the definition of FILE_PREFIX and CODE_PREFIX.
  • Remote Name Notation
  • Using FILE_PREFIX and CODE_PREFIX
  • Command-Line and Configuration File Remote Name Notation
  • Using Name Aliases
Parent topic: Programming for AcuServer


Remote Name Notation

Accessing remote files requires that your application refer to remote files with remote name notation. The ACUCOBOL-GT runtime looks for remote name notation to identify requests to AcuServer. Remote name notation has the following format on UNIX:

@servername:/pathname

On Windows NT and Windows 2000 to 2008, the drive designation must be included along with the pathname:

@servername:c:\pathname

I/O requests to files prepended with @server-name:/path-name are routed to AcuServer on the host specified by server-name. AcuServer looks for the named file in the directory specified by pathname.

Parent topic: Accessing Remote Files


Using FILE_PREFIX and CODE_PREFIX

The easiest way to enable your applications to use AcuServer is to update the FILE_PREFIX and CODE_PREFIX configuration variables in the runtime and server configuration files. Because these variables can be used to define multiple search directories, they are powerful tools for accessing both local and remote files. Sites that use FILE_PREFIX to specify multiple directories or multiple servers (either multiple server host machines or multiple instances of the acuserve program on a single host) may note a significant performance enhancement using name aliasing instead of FILE_PREFIX. See Using Name Aliases for more information.

CAUTION:
When using FILE_PREFIX on Windows NT, Windows 2000 to 2008 machines, it is best to use the full path to the directory, rather than using share names (a share name is the name assigned when a directory is set up for sharing using the Properties/Share/Share As dialog). Share names can seriously degrade file access performance because Windows NT and Windows 2000/2003/2008 are very slow to resolve them.

To add a remote search path, you have two options:

  • Option 1: Include the name and path of the remote directory to the variable's definition in the runtime configuration file (which will also include any local object and data directories).

    You do not have to make any changes to the server configuration file. For example:

    FILE_PREFIX  .  /usr/data  @condor:/usr/data/ap  @condor:/usr/data/ar
CODE_PREFIX  .  /usr/objects  @condor:/usr/objects/ap  @condor:/usr/objects/ar

    In this example, whenever the application attempts to access a data file, it will first look for the file in the current directory ("."), then in the local /usr/data directory, and finally on file server condor in the directory /usr/data/ap or /usr/data/ar.

    To locate an object file, the application looks first in the current directory ("."), then in the local /usr/objects directory, and finally on the file server condor in the directory /usr/objects/ap or /usr/objects/ar.

  • Option 2: Specify only the server name for the PREFIX variables in the runtime configuration file (along with any local object and data directories), then specify the complete server path in the server configuration file.

    For example, the runtime configuration file might contain:

    FILE_PREFIX  .  /usr/data  @condor:
CODE_PREFIX  .  /usr/objects  @condor:

    The server configuration file would then include something like this:

    FILE_PREFIX  /usr/data/ap  /usr/data/ar
CODE_PREFIX  /usr/objects/ap  /usr/objects/ar

    In this situation, a single network request can search multiple server directories for a file. (Setting multiple server directories on the client requires multiple network requests to search the directories.)

    Note that you can change the PREFIX variables in the server configuration file after acuserve has started using the -config utility.

Note that if you want to specify the root directory on the server as a search path in the runtime configuration file, you must include a forward slash ("/") after the server name. To search the root directory on a server called condor, for example, you would specify @condor:/.

Although FILE_PREFIX and CODE_PREFIX are usually not applied to file names specified with absolute path names, you can force these variables to be used when the path name begins with a forward slash ("/"). To do this, set the APPLY_FILE_PATH or APPLY_CODE_PATH configuration variables (either locally or on the server) to on (1, true, yes). For example, if your application specifies the file:

/usr/bernie/data/ind.dat

and FILE_PREFIX is set to:

FILE_PREFIX @condor:

and APPLY_FILE_PATH is on, the runtime will attempt to access the file at:

@condor:/usr/bernie/data/ind.dat

APPLY_FILE_PATH and APPLY_CODE_PATH do not affect file names beginning with a device name (such as c:).

If the application attempts to access a file in a location (path) that does not exist, the program will terminate, displaying an error similar to the following:

File error 35 on SEQ1.DAT

(This error also appears if the runtime is not AcuServer-enabled.)

Note that the maximum length of FILE_PREFIX and CODE_PREFIX is restricted by a number of factors. The ACUCOBOL-GT runtimes restrict runtime configuration variables to a maximum of 4096 characters. The host operating system may, in addition, restrict environment variables to less than 4096 characters (refer to your operating system documentation).

Parent topic: Accessing Remote Files


Command-Line and Configuration File Remote Name Notation

Most files that can be named on the command line or defined in the runtime configuration file can be specified with remote name notation. There are two general exceptions to this:

  1. If you are redirecting standard input or standard output to a file, the file cannot have remote name notation.
  2. If you are using an indexed file system other than Vision, those indexed files cannot have remote name notation.

Files that can have remote name notation include the following:

configuration files | (-c runtime option)
error files | (-e runtime option)
object file libraries | (-y runtime option)
object files | (specified on runtime command line or DEFAULT_PROGRAM configuration variable or CODE_PREFIX configuration variable)
hot-key programs | (HOT_KEY configuration variable)
data files | (FILE_PREFIX configuration variable or name aliases in the configuration file or specified in the program)
log files | (LOG_FILE and filename_LOG configuration variables)
log directory | (LOG_DIR configuration variable)
xfd directory | (XFD_DIRECTORY configuration variable)

Note that AcuServer may not be used for sort files with the SORT_DIR configuration variable.

Files that cannot have remote name notation include:

keyboard input file | (-I runtime option)
keystroke playback file | (-k runtime option)
display output file | (-o runtime option)
debug input file | (-r runtime option)

Below is an example of a runtime command line that uses remote name notation to specify some of its runtime files:

runcbl -c @host1:/usr1/config/cblconfig
     -e @host2:/usr2/errors/err.out
     @host3:/usr3/objects/sample.obj

The following are example definitions for runtime configuration variables that can have remote name notation.

CODE_PREFIX @host3:/usr3/objects
DEFAULT_PROGRAM @host3:/usr3/objects/sample.obj
FILE_PREFIX @host3:/usr3/data
HOT_KEY "@host3:/usr3/objects/sample.obj"=100,200
LOG_DIR @host3:/usr3/log
LOG_FILE @host3:/usr3/log/log.out
XFD_DIRECTORY @host3:/usr3/dictionaries
Parent topic: Accessing Remote Files


Using Name Aliases

The runtime configuration file offers a second method for accessing remote files. You can use the runtime configuration file to define file name aliases. A name alias is a substitute string for the literal name that appears in the ASSIGN TO clause of a SELECT statement.

For example, if you have this SELECT statement in your application:

input-output section.
file-control.
    select idx-file
    assign to disk "IDXDAT"
    binary sequential
    status is idx-status.

you could alias IDXDAT in your runtime configuration file by adding:

IDXDAT  @condor:/usr/data/idx.dat

This line aliases IDXDAT to be file "idx.dat" on file server condor in directory /usr/data.

Parent topic: Accessing Remote Files


Server Name Management

At large installations, with many clients and servers, changes in file location and network configuration can mean frequent tedious maintenance of client runtime configuration files. Every time a new server comes on-line, or a network reorganization moves data files from one server to another, the FILE_PREFIX and CODE_PREFIX definitions and name aliases must be updated.

One way to simplify the network maintenance would be to create a file that contains the name of the file server. Each application would then be written so that it reads this file and uses the name it finds there when referencing the server. If you need to move your files to a new server, you have to change only this single file.

Here's an example of this approach:

First determine a permanent location for the server name file, and create it there. The following program creates a server name file on machine "faithful," on our hypothetical network:

identification division.
program-id. svnamcrt.
environment division.
input-output section.
file-control.
    select namefile
    assign to
    disk "@faithful:/usr/acucobol/srvrnam.dat".

data division.
file section.
fd  namefile.
01  namerec    pic x(60).

screen section.
01  enter-screen.
    03  "REMOTE DIRECTORY: " line 5.
    03  using namerec.

procedure division.
main-logic.

    open output namefile.
    display window erase.
    display enter-screen.
    accept enter-screen.
    write namerec.
    close namefile.

    stop run.

For the purposes of this example, enter @helios:/usr2/sales/records at the ACCEPT. This string designates the machine (helios) and the directory on that machine (/usr2/sales/records) where our data files can be found.

The next step is to create a front-end program that your application will use to read the server name file. It is possible for this program to be written in such a way that you can avoid any recompilation of existing programs within your application. The following is an example of such a front-end program:

identification division.
program-id. srvrnam.
environment division.
input-output section.
file-control.
    select namefile
    assign to
    disk "@faithful:/usr/acucobol/srvrnam.dat".

data division.
file section.
fd  namefile.
01  namerec    pic x(60).

working-storage section.

01  ws-prefix  pic x(80).

procedure division.
main-logic.
    open input namefile.
    read namefile.
    close namefile.

    string namerec
        delimited by spaces into ws-prefix.
    set environment "FILE_PREFIX" to ws-prefix.

    call "your_app".

    stop run.

In the above example, the program reads the server name file (found on faithful), creates the environment variable FILE_PREFIX set to the value found in the server name file (@helios:/usr2/sales/records), and then calls the existing application. Because the variable is defined in the same run unit in which the application runs, the variable is available to the application. File operations are now routed to the machine helios.

A file trace for this program might look like:

Configuration file = '/etc/cblconfig'
Try loading 'srvrnam'...
srvrnam loaded
@faithful:/usr/acucobol/srvrnam.dat: open input
@faithful:/usr/acucobol/srvrnam.dat: next
@faithful:/usr/acucobol/srvrnam.dat: close
Set parameter 'FILE_PREFIX' to '@helios:/usr2/sales/records'
Try loading your_app...
your_app loaded
Set keystroke to 'Edit=Next Terminate=13 ^M'
thelp.dat: open I-o
tword.dat: open I-o
users.dat: open I-o

Note that FILE_PREFIX is set to the directory on helios where the data files are found. The application behaves normally, and the FILE_PREFIX variable works just as if it had been changed in the runtime configuration file, but without the effort.

There are other approaches that the front-end program might take to define FILE_PREFIX. In the following program, FILE_PREFIX includes the value held in the server name file, as well as any values that exist in the configuration file:

identification division.
program-id. srvrnam.
environment division.
input-output section.
file-control.
    select namefile
    assign to
    disk "@faithful:/usr/acucobol/srvrnam.dat".

data division.
file section.
fd  namefile.
01  namerec     pic x(60).

working-storage section.

01  ws-prefix   pic x(80).
01  full-path   pic x(120).

procedure division.
main-logic.

    open input namefile.
    read namefile.
    close namefile.

    accept ws-prefix from environment "FILE_PREFIX".

    move spaces to full-path.
    string namerec, " ", ws-prefix
        delimited by "  " into full-path.
    set environment "FILE_PREFIX" to full-path.

    call "your_app".

    stop run.

This program accesses the server name file and calls the application, just as in the first example. However, the construction of the FILE_PREFIX variable includes both the value found in the server name file and the existing definition of FILE_PREFIX, as defined in the configuration file.

In the next example, the front-end program creates a full pathname for each file in the application, using a different variable to hold the location of each file:

identification division.
program-id. srvrnam.
environment division.
input-output section.
file-control.
     select namefile
     assign to disk "@faithful:/usr/acucobol/srvrnam.dat".

data division.
file section.
fd  namefile.
01  namerec      pic x(60).

working-storage section.
01  first-file   pic x(20) value "THELP_FILE".
01  second-file  pic x(20) value "KEYWORDS_FILE".
01  third-file   pic x(20) value "USER_FILE".
01  file-1       pic x(20) value "thelp".
01  file-2       pic x(20) value "tword".
01  file-3       pic x(20) value "users".
01  ws-suffix    pic x(10).
01  full-path    pic x(90).

procedure division.
main-logic.

    open input namefile.
    read namefile.
    close namefile.
    accept ws-suffix from environment "FILE_SUFFIX".

    move spaces to full-path.
    string namerec, "/", file-1, "."
        ws-suffix
        delimited by spaces into full-path.
    set environment first-file to full-path.

    move spaces to full-path.
    string namerec, "/", file-2, "."
        ws-suffix
        delimited by spaces into full-path.
    set environment second-file to full-path.

    move spaces to full-path.
    string namerec, "/", file-3, "."
        ws-suffix
        delimited by spaces into full-path.
    set environment third-file to full-path.

    call "your_app".

    stop run.

Notice that the program constructs the full path name of each file. If there is a file suffix, and it is known, it could be hard coded into this program. If there is a file suffix, but it is variable, this program could extract that information from the environment and append this variable suffix to the full path name. However, be aware that this approach may require recompilation of the existing programs within the application. In the case of the above example, the ASSIGN clause in each of the affected SELECT statements includes a hard coded file suffix. The period character (".") in that name cannot be used in the name of the environment variable, so the program must be recompiled after the code change:

input-output section.
file-control.

    select optional thelp-file
*       assign to "thelp.dat"
        assign to disk ...

    select optional keywords-file
*       assign to "tword.dat"
        assign to disk ...

    select optional user-file
*       assign to "users.dat"
        assign to disk ...

A file trace for this example might look like:

Configuration file = '/etc/cblconfig'
Try loading 'srvrnam'...
srvrnam loaded
@faithful:/usr/acucobol/srvrnam.dat: open input
@faithful:/usr/acucobol/srvrnam.dat: next
@faithful:/usr/acucobol/srvrnam.dat: close
Assign 'THELP_FILE' to '@helios:/usr2/sales/records/thelp.dat'
Assign 'KEYWORDS_FILE' to '@helios:/usr2/sales/records/tword.dat'
Assign 'USER_FILE' to '@helios:/usr2/sales/records/users.dat'
Try loading 'your_app'...
your_app loaded
THELP-FILE: open I-o
>>>translated name =   @helios:/usr2/sales/records/thelp.dat
KEYWORDS-FILE: open I-o
>>>translated name =   @helios:/usr2/sales/records/tword.dat
USER-FILE: open I-o
>>>translated name =   @helios:/usr2/sales/records/users.dat

Note that in the above example, only those files specifically named in an environment variable will be looked for or created on the file server.

Parent topic: Programming for AcuServer


Multiple-Record Mode

AcuServer includes a multiple-record mode designed for programs that read a large number of sequential records without user interruption, such as when you are generating a report. Rather than reading one record at a time, AcuServer returns multiple records in a single network request, dramatically improving performance. Files opened in this mode are optimized for sequential reading, but have restrictions placed on the types of operations they can do. See File Limitations for more information.

To use multiple-record mode, specify the name of the file to be opened in this mode using the runtime configuration variable, filename_MRC (multiple-record count). You can then specify the number of records to be sent in each packet in the filename_MRC variable on the client, or you can set this variable to 1 and specify the number of records to send using the server configuration variable MULTIPLE_RECORD_COUNT. See filename_MRC and MULTIPLE_RECORD_COUNT for more information.

Only files open in modes that do not require record locking can use multiple-record mode. Files that are opened in EXCLUSIVE I/O mode or open INPUT are good candidates. Note that this only affects files that read records, so files opened OUTPUT or EXTEND cannot use this mode.

In multiple-record mode, the client caches records that are read from the server. The first time a client does a READ NEXT, the server actually sends multiple records to the client. Until that collection of records has been processed, there is no more communication between the client and the server for future READ NEXT operations.

There are some exceptions to these general rules. When the client executes a random READ, the server sends only a single record. The next time the client executes a READ NEXT, the server sends a full set of records.

  • File Limitations
  • Other Considerations
Parent topic: Programming for AcuServer


File Limitations

All of the standard rules of COBOL apply in multiple-record mode, with the following limitations:

  • Only files that require no record locking can be opened in multiple-record mode. This limitation is enforced silently on both the client and the server. If a user tries to open a file that requires record locking in this mode, the file is still opened, but not in multiple-record mode. In other words, multiple-record mode does not affect the lock mode specified by the COBOL program, but the lock mode may affect whether records are sent in single or multiple-record packets.
  • Files open in this mode may not be read backward. (that is, READ-NEXT commands are supported; READ-PREVIOUS commands are not.) The purpose of this mode is to improve sequential performance. If you attempt to read a file backward that has been opened in multiple-record mode, an error 9B results (requested operation is not supported).
Parent topic: Multiple-Record Mode


Other Considerations

There are several things of which you should be aware when using multiple-record mode:

  1. In multiple-record mode, the client requires more memory than if it has no files open in this mode. In particular, the client requires memory for all the records in the cache from the server. For example, if three files are open in multiple-record mode with maximum record sizes of 100, 250, and 800, and MULTIPLE_RECORD_COUNT is set to "10", the client requires 100 * 10 + 250 * 10 + 800 * 10 bytes of storage for holding all the records from the server. This is compared to needing only 100 + 250 + 800 bytes of storage if these files were not open in multiple-record mode.
  2. The server also requires more memory when you use files in this mode. This should not be a significant addition to the usual amount of memory that the server needs, because the server reads all the records it sends and then does not save these records. The server needs only a single large internal buffer to hold the records temporarily. This buffer should have a size of the largest MAXIMUM_RECORD_SIZE multiplied by the largest MULTIPLE_RECORD_COUNT.
  3. This mode is inherently subject to race conditions, including those described below. (Note that these are not the only race conditions that you may encounter.) If your application is written in such a way that it will experience race conditions, you should not use multiple-record mode.
    • Condition 1: If two users are accessing a single file, and one of those users has the file open in multiple-record mode, the following situation could happen:
      • User A opens and reads the first record. At this time the server sends multiple records to user A.
      • User B opens the file and writes a record in a location within the record set that the server has already sent to user A.
      • User A never sees that record unless the file is closed and reopened.

      In other words, when the server sends a collection of records to a client, that client now has a snapshot of the records on the server. The client does not query the server about any new records, since this would remove the performance gain of using multiple-record mode.

    • Condition 2: Suppose a user opens the file I/O for exclusive access (or allowing only readers) in multiple-record mode. Suppose this user reads the first record, and then writes a record that is after the first record, but before the last record in the client cache.

      As the user executes READ NEXT, that record never appears. For example, suppose the file has a key that is a PIC 99 data item, and that ten records are sent in each batch. Also suppose that the file has records with keys 05, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95. The user opens the file and executes a READ NEXT. At this time, the first ten records are in the client cache (records 05, 10, 15, 20, 25, 30, 35, 40, 45, 50) and the COBOL program has record 05 in its record area. Suppose the user then executes a WRITE to write a record with the key of 08 and then executes another READ NEXT. The record that the COBOL program has in its record area is now record 10, not record 08. Again, the client and server will not communicate about this situation, since it would completely remove the performance gain of using multiple-record mode.

    • Condition 3: Now suppose you have the same file as in the previous case, and that the user has executed the first READ NEXT. Suppose the user then executes a REWRITE on record 10 to change data in that record and then executes a READ NEXT. The COBOL program will now have the original data from the file for record 10, not the data that the COBOL program just rewrote.

    Since multiple-record mode is inherently subject to race conditions, you should use this mode only in situations in which you are sure you understand all of the consequences.

Parent topic: Multiple-Record Mode


Restrictions to Library Functions

There are four restrictions on the usage of the library functions C$COPY and RENAME when they are used with remote name notation:

  • RENAME does not support file copies or renames from client systems to file servers, or vice versa. In other words, renames are not supported across machines.
  • For a rename, remote name notation is not allowed on the destination file parameter.
  • When copies or renames are executed on a file server, the location of the copied or renamed file is determined by the relative or absolute pathnames of the parameter values.
  • FILE_PREFIX and name aliases are not used to find files named in the function parameters.
Parent topic: Programming for AcuServer


C$COPY

C$COPY creates an exact duplicate of SOURCE-FILE in DEST-FILE. The usage of C$COPY is:

CALL "C$COPY"
    USING SOURCE-FILE, DEST-FILE, FILE-TYPE
    GIVING COPY-STATUS

Remote name notation is permitted on both the SOURCE-FILE and the DESTFILE parameter.

If either the SOURCE-FILE or DEST-FILE parameter specifies a remote file:

  • The copy takes place on the specified machine.
  • The location of the source and destination files on the server is dependent on the paths specified by SOURCEFILE and DEST-FILE. Parameters that do not specify an absolute pathname (an absolute path starts with a "/"), are considered to be located relative to the directory in which the server (acuserve) was started. For example:

    If acuserve was started on condor in the /acucobol directory, and SOURCE-FILE is:

    @condor:index.dat

    AcuServer expects to find index.dat in directory /acucobol (note the absence of a "/" after "condor").

    If SOURCE-FILE is:

    @condor:/usr2/sales_records/index.dat

    AcuServer expects to find index.dat in the absolute path /usr2/sales_records.

    These pathing rules hold for both SOURCE-FILE and DESTFILE.

FILE-PREFIX is not used to search for file names held in any of the function's parameters. Name aliases are not substituted for names held in the function's parameters. Full path names to the files, including remote name notation on the SOURCE-FILE and DEST-FILE, must be hard coded in the function call. A more portable solution is to use the ACCEPT FROM ENVIRONMENT statement to get pathnames during program execution. See ACCEPT Statement in the ACUCOBOL-GT Reference Manual for more information.

C$COPY returns a zero (0) if successful, a one (1) if the file does not exist or is not a regular disk file, or a two (2) if there is a network error (for example, AcuServer is not running). This value is returned to COPY-STATUS.

For a complete description of C$COPY, excluding the above restrictions, see Appendix I of the ACUCOBOL-GT documentation.

Parent topic: Programming for AcuServer


C$FILEINFO

C$FILEINFO retrieves operating system information for the named file. The syntax of C$FILEINFO is:

CALL "C$FILEINFO"
   USING FILE-NAME, FILE-INFO,
   GIVING STATUS-CODE

There are no restrictions on the use of C$FILEINFO. Note, however, that STATUS-CODE holds a zero (0) if successful, a one (1) if the file does not exist or is not a regular disk file, and a two (2) if there is a network error (for example, AcuServer is not running).

FILE_PREFIX is not used to search for FILE-NAME. A full path name to the file, including remote name notation, must be hard coded in the function call. A more portable solution is to use the ACCEPT FROM ENVIRONMENT statement to get pathnames during program execution. See ACCEPT Statement in the ACUCOBOL-GT Reference Manual for more information.

Parent topic: Programming for AcuServer


RENAME

RENAME renames the file specified by SOURCE-FILE to the name specified by DEST-FILE. The syntax of RENAME is:

CALL "RENAME" USING SOURCE-FILE, DEST-FILE,
        RENAME-STATUS, FILE-TYPE.

Remote file name notation is not permitted on the DEST-FILE parameter. If the SOURCE-FILE parameter specifies a remote file:

  • The rename takes place on the specified server.
  • The location of source and destination files on the server is dependent on the paths specified by SOURCE-FILE and DEST-FILE.

    Parameters that do not specify an absolute pathname (an absolute path starts with a "/"), are considered to be located relative to the directory in which the server (acuserve) was started. For example:

    If acuserve was started on condor in the /acucobol directory, and SOURCE-FILE is:

    @condor:sales_records/index.dat

    AcuServer expects to find index.dat in directory /acucobol/sales_records (note the absence of a "/" after condor:).

    If SOURCE-FILE is:

    @condor:/usr2/sales_records/index.dat

    AcuServer expects to find index.dat in directory /usr2/sales_records.

    These pathing rules hold for both SOURCE-FILE and DEST-FILE; however, DEST-FILE can never include the name of the remote host (@condor).

FILE_PREFIX is not used to search for file names held in any of the function's parameters. Name aliases are not substituted for names held in the function's parameters. Full path names to the files, including remote name notation on the SOURCE-FILE, must be hard coded in the function call. A more portable solution is to use the ACCEPT FROM ENVIRONMENT statement to get pathnames during program execution. See ACCEPT Statement in the ACUCOBOL-GT Reference Manual for more information.

RENAME-STATUS holds a zero (0) if the routine is successful; otherwise, it is set to the operating system's error number, or 19 if there is a network error (for example, AcuServer is not running).

For a complete description of RENAME, excluding the above restrictions, see Appendix I of the ACUCOBOL-GT documentation.

Parent topic: Programming for AcuServer


System Management

  • Machine Failures
  • Error and Status Codes
  • Diagnosing Errors with C$PING
  • Troubleshooting
  • Frequently Asked Questions
Parent topic: AcuServer Version 10.2.0 User's Guide


Machine Failures

There are two major concerns regarding client and server machine failures:

  • What happens to open files when a client or server crashes?
  • How are other clients and servers affected by a crash?

When a client application is terminated with a Control + C or kill command (other than a kill -9), the AcuServer software detects the termination and closes all files held open for that client process. However, other terminal software and hardware failures may not be detected.

AcuServer offers an optional mechanism for detecting connections that terminate unexpectedly. The mechanism works by establishing regular, periodic communication from the UNIX/Linux or Windows client to AcuServer. The acuserve process keeps a record of each participating connection's periodic communication and regularly analyzes these records for evidence of a dead connection. If a connection fails to send its periodic communication for two consecutive periods, acuserve concludes that the connection is dead, closes any open files associated with the connection, and disconnects the socket. The detection mechanism is enabled with two configuration variables, one on the server and one on the client.

On the server, the detection mechanism is enabled with the DEAD_CLIENT_TIMEOUT configuration variable. When DEAD_CLIENT_TIMEOUT is set to -1, its default value, the detection mechanism is disabled. When DEAD_CLIENT_TIMEOUT is set to any other value, the detection mechanism is enabled and the variable's value is interpreted as the interval, in seconds, at which acuserve will analyze its records to detect dead connections.

On the client, the AGS_PING-TIME configuration variable enables or disables the detection mechanism. When AGS_PING_TIME is set to -1, the periodic communications mechanism is disabled and the connection cannot be automatically disconnected. When AGS_PING_TIME is set to any other value, the reporting mechanism is enabled and the connection is included in acuserve's monitoring table. The value of AGS_PING_TIME specifies the interval, in seconds, at which the client will send an I'm alive message (a no-op instruction) to the server. The value is communicated to acuserve at the time that the connection is established so that acuserve can determine, when it checks its monitoring records, whether a connection has missed two or more consecutive communication periods.

The following example illustrates the system's behavior. If DEAD_CLIENT_TIMEOUT is set to 300 (300 seconds = 5 minutes), the dead connection detection mechanism is enabled on the server and acuserve analyzes its communication records every five minutes to look for dead connections. If, on the client, AGS_PING_TIME is set to 60, when a connection is established with the server, the server is told to expect an I'm alive message every 60 seconds and the connection proceeds to send those messages. If for some reason the connection fails to send the message for two or more consecutive periods, the next time that acuserve checks its records (which it's checking every five minutes), it will detect that the connection is dead and automatically close all files opened by that connection, release all locks held by that connection, and close the associated socket.

Note: The AGS_PING_TIME mechanism depends on regular system calls, which may slow some systems (notably some versions of Solaris) and affect the runtime's performance. Be sure to test for performance before using this configuration variable in a production environment.

Also note that AGS_PING_TIME starts an internal runtime thread to send its periodic communication to the server. This means that any activity that suspends thread switching will prevent this mechanism from working.

With clients that do not participate in the dead client detection mechanism, if a client system crashes while using AcuServer, the server will hold the client's open files open until the unlock function is used to close the files, or until the acuserve daemon is stopped and restarted (when AcuServer is stopped, all open files are closed). See Closing Stranded Files for a description of the use of the unlock function.

Should the server go down, all clients actively using AcuServer will get access errors when attempting to communicate with the server. Client applications must disconnect or shut down and wait for the return of the server. All files that were open on the server at the time of the crash are left in an unknown state and may be corrupt. See C$DISCONNECT in Appendix I_Library Routines in the ACUCOBOL-GT Appendices for more information.

Note: If acuserve is automatically started when the server boots, acuserve should be immediately halted. Before AcuServer is started, all files that might have been affected by the crash should be checked and, if necessary, rebuilt. After all files have been verified, the acuserve daemon can be started.
Parent topic: System Management


Error and Status Codes

AcuServer reports errors and status information in many ways.

See topics in this help section for descriptions.

  • Error Logging
  • Event Logging
  • Start Status Codes
  • File Access Failures, 9D Errors
Parent topic: System Management


Error Logging

If you want AcuServer to output error messages to an error log, specify the -e option when starting AcuServer with acuserve -start. On Windows, you can also specify the error log file using the AcuServer Control Panel (ACP).

If -e is not specified in UNIX, acuserve will attempt to direct error output to /dev/console.

In Windows, acuserve will attempt to direct error output to a file named acuserve.err in the Windows NT/2000 system directory (typically c:\winnt\system32). If these directories cannot be opened, acuserve will attempt to append to a file named acuserve.err in the current directory. If that file doesn't exist, or the file append fails, acuserve will print the message acuserve: can't open error output file to standard output, and acuserve will terminate.

See Starting and Stopping acuserve for more information on the -e option.

Parent topic: Error and Status Codes


Event Logging

acuserve writes information to the Windows event log or UNIX syslog when something of significance to a system administrator happens, such as acuserve starting and stopping, acuserve halting because of an unrecoverable error, or other emergency-type events. If a UNIX system does not support syslog, AcuServer writes these messages to /dev/console instead. This information is also output to the error log.

On Windows, the event messages to go to any computer in the network. Use the WINNT-EVENTLOG-DOMAIN variable to set the UNC name of the computer(s) to which you want to send event log messages. The machine that you specify must give acuserve access privileges or the event log output will fail.

Parent topic: Error and Status Codes


Start Status Codes

Whenever you try to start AcuServer, either by the acuserve -start command or the ACP, AcuServer returns a status to the operating system indicating success or failure. The way to get this status depends on your shell. When using the Bourne shell (or a compatible shell), echo $? to see the return status of any program executed from the shell.

The return codes are as follows:

Return Code | Description
0 | Success. AcuServer is running.
1 | Invalid argument.
2 | Missing license.
3 | Expired license.
4 | Unable to open the error log file.
5 | Unable to open the configuration file (writable by other than root).
6 | Unable to open the AcuAccess file (missing or writable by other than root).
7 | Unable to create a child process.
8 | Too many servers running.
9 | Unable to create a socket, but the socket is used by something other than AcuServer.
10 | AcuServer is already running on this port.
Parent topic: Error and Status Codes


File Access Failures, 9D Errors

AcuServer returns an error code whenever an AcuServer file access fails.

An error code of 9B indicates that the requested operation is not supported. Other AcuServer error codes have the following format:

9D,xxx

9D indicates a server error and is returned in your file-status variable.

You can retrieve the extended code with the -x runtime switch, or by calling C$RERR. Note that you can pass two parameters to C$RERR to fetch interface errors. The first parameter retrieves the two- or three-digit extended error code. This parameter must be at least PICTURE X(5). The second parameter retrieves a message associated with the error condition and should be at least PICTURE X(80).

AcuServer Errors

AcuServer errors have a three-digit extended code. These errors include the following:

Error Code | Description
9D/100 | Invalid syntax for FILE_PREFIX. The correct syntax for FILE_PREFIX is: FILE_PREFIX @server-name:pathname
9D/101 | The version of the server is not compatible.
9D/102 | Invalid connection password specified by client.
9D/103 | Connection to server refused, access denied.
9D/104 | PC/TCP resident kernel is not loaded, or the communication stream between the client and the server was interrupted, or a file open failure occurred.
9D/105 | User count exceeded.
9D/106 | Attached to a server that does not appear to be AcuServer.
9D/109 | Unknown command sent between AcuServer runtime and AcuConnect server or between AcuConnect runtime and AcuServer.

An error 9D/101 indicates that the version of the ACUCOBOL-GT runtime and the version of AcuServer are incompatible. AcuServer Version 8.0 and later will not work with earlier versions of the ACUCOBOL-GT runtime. Conversely, earlier versions of AcuServer will not work with a Version 8.0 or later runtime.

An error 9D/105 indicates that the number of users attempting to use AcuServer exceeds the number of users authorized by your license. For connections with the ACUCOBOL-GT Web Runtime, it means that the number of Web users trying to access AcuServer exceeds the number of ACUCOBOL-GT runtime licenses on the server machine. If your COBOL program receives a file status code 9D,105 in connection with plug-in users, it should display a message box stating that the Web file server is busy, and to retry later. To extend the number of authorized users, call your Micro Focus extend Sales Professional.

Client Runtime Errors

Whenever a client runtime passes a file handle to AcuServer with a request for file access, AcuServer validates the file handle before performing any I/O using that handle. If AcuServer determines that a file handle is not valid (for example, if the file pointer is invalid or the file is not open), it returns an error to the client runtime.

Client runtime error codes have the following format:

30/xx

30 indicates a system error. Client runtime errors include the following:

Error Code | Description
30/02 | No such file or directory
30/09 | Bad file number
Parent topic: Error and Status Codes


Diagnosing Errors with C$PING

ACUCOBOL-GT includes a library routine, C$PING, that provides diagnostic information for debugging network performance with AcuServer. If you write a small COBOL program that calls C$PING, you will obtain information such as whether or not the client is AcuServer-enabled, whether or not the parameter passed from the COBOL program is valid, whether the connection was refused or accepted by the server, and whether or not a socket error occurred.

A compiled COBOL program called acuping is included in the \AcuGT\bin directory in which you installed ACUCOBOL-GT. This program contains a call to the C$PING library routine, along with a graphical screen that runs well on Windows and UNIX platforms. If desired, you can run this program to diagnose AcuServer errors, or you can modify the source code for the program as required. You'll notice that AcuPing has four entry fields: log file name, server to ping, number of pings, and ping delay (1/10th second). The program shows results for Message ID, Time at Client, Time at Server, and Round Trip Time.

If you choose to write your own COBOL program, use the following calling sequence for C$PING:

call "C$PING" using server-to-ping, server-time [, client-data].

where:

server-to-ping is a PIC X(64) data item that should be filled in by the COBOL program before calling C$PING. This is the server that will be pinged.

server-time is a pic 9(8) data item that is filled in by C$PING and that designates the time the server got and returned the request. Note that if this is a group item, the time is left-justified instead of right-justified (as is done via a COBOL MOVE statement). For this reason, a PIC 9(8) elementary data item is highly recommended.

client-data is a PIC X(n) data item that is passed verbatim to the server. The server displays this data in the trace file (if tracing is enabled) and returns it verbatim to the client. The result is that the data in this data item is unchanged, even though it came from the server. This argument is optional.

When the library routine finishes, it sets the external variable return-code to the status of the ping, as follows (these values are defined in acucobol.def.):

78  CPING-OK                         VALUE 0.
78  CPING-NO-CLIENT                  VALUE 1.
78  CPING-PARAM-ERROR                VALUE 2.
78  CPING-CONN-REFUSED               VALUE 3.
78  CPING-VERSION-ERROR              VALUE 4.
78  CPING-SOCKET-ERROR               VALUE 5.
CPING-OK | Everything worked, and time-at-server has a valid time from the server
CPING-NO-CLIENT | This runtime is not AcuServer-enabled
CPING-PARAM-ERROR | The COBOL program passed an invalid parameter
CPING-CONN-REFUSED | The server refused the connection, possibly because it is not running or is running on a different port than the one for which the client is configured
CPING-VERSION-ERROR | The version of the server is not compatible with this version of the runtime
CPING-SOCKET-ERROR | Some unknown socket error occurred

If the server has tracing enabled, the ping request is logged in the trace file.

Parent topic: System Management


Troubleshooting

This help section includes a collection of step-by-step diagnostic procedures for finding and resolving common system problems. Many of these procedures require access to root or Administrator privileges and are intended for use by your site's AcuServer or system administrator.

  • Ambiguous File Error
  • Connection Times Out
  • File Access Denied
  • Unexpected User Name
  • Connection Refused
  • Invalid Password
  • Client and Server Both Hang When Connecting
Parent topic: System Management


Ambiguous File Error

Problem: Your application gets an error and aborts, returning an ambiguous AcuServer error message (9D). For example:

FILE ERROR #9D ON SEQ1.DAT
MYAPP ABORTED

Diagnostics

Run your application again with the -x option:

runcbl -x your-usual-options program-name

This time when your application gets the error, the runtime will report the extended error code and associated error text. For example:

File system error value = 102
Invalid connection password specified by client

If your runtime options include the -e switch to redirect error output to a log file, look for the extended error message in your log file.

Parent topic: Troubleshooting


Connection Times Out

Problem: An attempt to connect to AcuServer times out, or your application gets a time-out error during execution.

A typical time-out error message looks like:

File error 9D,14 on @condor:/usr2/bsmith/fio_seq.dat
condor: Timed out

Time-out errors occur when the server is down, the server crashes while your program is running, or network conditions produce very protracted response times (the result of an overburdened network, or faulty network hardware/software).

Diagnostics

  1. Confirm that the server is up and responding to the network:

    From your client system use "ping" to query the server:

    ping hostname

    Ping will return:

    hostname is alive

    or

    no answer from hostname

    If there is no answer from the server, determine the cause of the failure (machine down; network connection faulty) and restore the server. With ping, confirm that the network connection is working.

  2. Confirm that acuserve is running on the server:
    • If you are using the Windows graphical environment, check the Services tab in the AcuServer Control Panel. Services that are running are marked with a green bullet and services that are stopped are marked with a red bullet.

      If the service is not running, click Start.

    • If you are in a command-line environment, enter the command:
      acuserve -info

      If acuserve is running, the command will return a summary of AcuServer's current status. For example:

      0 file(s) in use by acuserve on: hostname

      If acuserve is not running the command will return:

      acuserve is not running on hostname

      If acuserve is not running, start acuserve and repeat the acuserve -info test.

    Once acuserve is running, rerun your application on the client. If the connection still times out, proceed to step three.

  3. Set the runtime configuration variable DEFAULT_TIME_OUT to 100 seconds (four times the default value) and run your application.

    If the connection succeeds, analyze your network for the cause of the prolonged connection time. You should investigate network capacity, collision and retransmission rates, and network hardware or software malfunction.

    If necessary, repair your network and confirm its proper operation. Reset DEFAULT_TIME_OUT to its default setting of 25 seconds and rerun your application.

  4. If the application times out, you will probably need to work with your network system administrator, network hardware and software vendors, and our Technical Services to resolve the problem.
Parent topic: Troubleshooting


File Access Denied

Problem: Attempts to access a file on the server fail with an access denied error. A typical access denied error looks like:

File error 37,07 on @condor:/usr2/bsmith/fio_seq

The 37, 07 error code (ANSI 85 standard error code) indicates that the user does not have sufficient permissions to access the file. If your application uses one of the alternate sets of file status codes, your error code will differ. See the ACUCOBOL-GT Runtime Manual for more information.

Access denied errors occur because a file's permissions, or the permissions of a directory in which the file resides, prohibit access. Finding and correcting access denied errors requires familiarity with AcuServer access security and Windows NT/2000 or UNIX file security. You may need access to administrator or root privileges. Work with your site's AcuServer system administrator to resolve the problem.

AcuServer adds complexity to finding access denied errors, because AcuServer handles requests with a user ID (user name) designated in the server access file (AcuAccess). The user name designated may not be the user name that you expect. Therefore, finding and resolving access denied errors can involve inspecting two components of the system: file protections and the AcuServer server access file. AcuServer also adds complexity when implementing native system security, because the server impersonates the connecting client. See Unexpected User Name for more information.

File permissions diagnostics are used to verify that the ownerships and permissions on the file and directories do, in fact, allow access to the user ID that AcuServer is using (or the user name that you assume that AcuServer is using).

The AcuServer user name diagnostics are used to determine the actual user name that AcuServer is using when the access denied error occurs. Step-by-step diagnostic procedures follow.

Whether you first verify the user ID or first check the file permissions, is up to you. If you're familiar with file security, you may find it faster to check the file permissions first, under the assumption that AcuServer is using the user ID that you expect. Then, if necessary, you can verify the user ID, followed by repeating the file permissions inspection if the actual user name differs from the assumed name.

The steps below break the diagnostic process into three activities:

  1. Getting the full path of the file generating the error
  2. Checking the file permissions (UNIX, Windows)
  3. Determining the user ID used by AcuServer

See The Server Access File to review the structure and function of the server access file. See AcuServer Connection Logic to review the procedure used by AcuServer to get the requester's user ID. See Ownerships and Permissions for a brief description of file permissions.

  1. Getting the file name

    Get the name and path of the file that produces the access denied error.

    Most applications will report the full path and name of the file in the standard error output. If your application doesn't, run your application again with the -x runtime option:

    runcbl -x your-usual-options program-name

    If the -x option doesn't produce the full name and path, run the application in the debugger with FILE TRACE enabled and examine the log file for the first occurrence of an access error. The file name that precedes the error is the file generating the error.

    To run the debugger enter:

    runcbl -dle error-file your-usual-options program-name

    where:

    -d turns on the debugger, -l causes the contents of the runtime configuration file to be included in the error output, and -e causes file trace and error output to be placed in error-file.

    After starting your program, you will be at the debugger screen. Turn on file tracing by entering

    tf

    FILE TRACE will be echoed to the screen. To start program execution, enter:

    g

    Allow the program to run until you encounter the error condition, and then exit. Your log file will contain the error information, all COBOL configuration file variables that have been set, and a record of every OPEN, READ, and WRITE.

    Examine the log file and find the error output for the access denied error. The file name that precedes the error is the file generating the error. Note the full path of the file and retain the log file for future reference.

  2. Checking permissions
    1. Checking UNIX permissions If you are using a UNIX server, verify that the file and directory permissions grant access to the user name:
      1. Log on to the server with the user name used (assumed to be used) by AcuServer. If that's not possible (you don't know the password or the login attempt fails), skip to step 3.
      2. After logging onto the server, perform an ls -l on the file using the full path (beginning with "/"). For example:
        ls -l /usr2/bsmith/fio_seq

        If the ls -l fails with a cannot access directory (or similar) error, the permissions on one or more of the directories are too restrictive. To access a directory, the directory must allow you EXECUTE permissions. Adjust the permissions or move the file to a directory that will allow access. If you are not the owner of the directories, you will need to ask the owner, or someone with root privileges, for assistance.

        After adjusting the permissions, verify directory access to the file by performing an ls -l on the full path to the file. If the ls -l succeeds, the permissions set on the file are displayed. For example:

        -rw-r--r--  1 prod  general  4870  Aug 18 1993
   /usr2/bsmith/fio_seq

        Evaluate the file's ownerships and permissions, including the group permissions, to determine if they allow the type of access required by the requesting application. Except as noted below, all files opened by AcuServer must allow READ and WRITE access. Under Sun OS with ACUCOBOL-GT Version 2.1.2 or later, files having READ only permissions may be opened INPUT.

        If the file's permissions need changing and the file is not owned by you, you will need to enlist the assistance of the owner of the file or someone with root privileges.

        Once the file and directories permit access, run the application again. If the program fails when attempting to access the same file and you have not yet confirmed the user name that AcuServer is using, perform the Confirming the user name diagnostics (below).

      3. If you can't log onto the server under the user name used by AcuServer, ask your UNIX system administrator to evaluate whether the file in question is accessible to the user name. If the file or directories do not allow access, ask the owner of the file, or the system administrator, to adjust the permissions to allow access.

        After the permissions have been adjusted, run the application again. If the program fails attempting to access the same file and you have not yet confirmed the user name that AcuServer is using, proceed to the next section. Otherwise, contact Customer Support.

    2. Checking Windows NT/Windows 2000/ 2003/2008 permissions

      If you are using a Windows NT, Windows 2000 to 2008 server, verify that the file and directory permissions grant access to the user name.

      1. Log on to the server with the user name used (assumed to be used) by AcuServer. If that's not possible (you don't know the password or the login attempt fails), skip to step 3.
      2. After logging onto the server, select the file or directory. Then select:

        File/Properties/Security/Permissions

        from the menus. If the permissions are too restrictive, adjust the permissions or move the file to a directory that will allow access.

        When AcuServer is running as a Windows service, it belongs to an implicit group called SYSTEM. Otherwise it should belong to the Administrators group. If you are using AcuServer system security, make sure that the SYSTEM and Administrators groups are added to your file permissions with Full Control. This step is not necessary if you are implementing Windows NT security.

        Under AcuServer system security, files created by AcuServer are owned by the administrators group and allow Full Control for SYSTEM and Administrator. Everyone is given the permissions specified by the third digit in the umask in the AcuAccess file.

        If you are not the owner of the directory or file, you will need to ask the owner, or someone with administrator privileges, for assistance.

        Once the file and directories permit access, run the application again. If the program fails when attempting to access the same file and you have not yet confirmed the user name that AcuServer is using, perform the Confirming the user name diagnostics (below).

      3. If you can't log onto the server under the user name used by AcuServer, ask your system administrator to evaluate whether the file in question is accessible to the user name. If the file or directories do not allow access, ask the owner of the file, or the system administrator, to adjust the permissions to allow access.

        After the permissions have been adjusted, run the application again. If the program fails attempting to access the same file and you have not yet confirmed the user name that AcuServer is using, proceed to the next section. Otherwise contact Customer Support.

  3. Confirming the user name

    Confirm the user name that AcuServer is using when the access denied error occurs (see also sectino Unexpected User Name).

    Note that some procedures require root or administrator privileges. If you don't have these privileges, enlist the assistance of your AcuServer or system administrator.

    1. If there is any doubt about your client user name, confirm your client user name.

      On UNIX systems:

      Enter who am I at the UNIX prompt.

      On Windows systems:

      If a user is logged into a Windows NT/2000 workgroup or domain, AcuServer will use the user's log-in name. Otherwise, it uses the user name value that is set by the environment variable USERNAME. If USERNAME is not set, the runtime uses the value that is set by the environment variable USER. (The values of these variables are case-sensitive.) If neither of these environment variables is set, the runtime uses the literal string USER.

      To confirm the presence (or absence) of the USERNAME environment variable, enter SET at the command prompt. SET will display the values of all environment variables.

      COMSPEC=C:\COMMAND.COM
PATH=C:\;C:\WINDOWS;C:\MOUSE;
PROMPT=$P$G
USERNAME=BERNIE

      If USERNAME is defined, the value of USERNAME is the name passed to AcuServer. Otherwise, the variable USER is checked. If USER is not set, then the literal string USER is passed.

    2. If acuserve is running with level 2, 3, 6, or 7 tracing enabled, all connections and disconnections are reported in the AcuServer log file. Inspect the log file and look for the last connection entry for your client machine name/client user name combination. The trace messages associated with that connection request will include the Local Username that AcuServer has assigned to that connection. Find the line that reports the mapping of the client user name to the local user name.
      acuserve: 06/13/94 12:43:44 -
   Server version: 010000
   Client version: 010000
acuserve: 06/13/94 12:43:44 -
   AUTHORIZATION request from user:bernie
>> client:starling,
   PASSWORD-ATTEMPTS allowed:3
>> Mapping user:bernie to local user:bsmith
>> Socket:5, uid:205, gid:101
>> Password is not required
acuserve: adding
   client:starling, user:bernie,
   pid:18397, fid:57a28

      If the local user name is not the one you expect, consult with your AcuServer system administrator to verify that it is the correct user name. Your system administrator can make any necessary changes to the server access file.

    3. If acuserve is not running with tracing enabled, you can turn it on using the acuserve -config option. At the command line, type
      • acuserve -config
      • then set FILE_TRACE 2 (or 3, 6, or 7) at the prompt
      • then exit
      After tracing is turned on, run your application again and follow the procedure outlined in step 2, above.

      When you no longer want tracing enabled, type acuserve -config again, then type set FILE_TRACE 0 at the prompt.

Diagnostics

Get the name and path of the file that produces the access denied error.

Most applications will report the full path and name of the file in the standard error output. If your application doesn’t, run your application again with the -x runtime option:
runcbl -x your-usual-options program-name

If the -x option doesn’t produce the full name and path, run the application in the debugger with FILE TRACE enabled and examine the log file for the first occurrence of an access error. The file name that precedes the error is the file generating the error.

To run the debugger enter:

runcbl -dle error-file your-usual-options program-name

-d turns on the debugger. -l causes the contents of the runtime configuration file to be included in the error output. -e causes file trace and error output to be placed in error-file.

After starting your program, you will be at the debugger screen. Turn on file tracing by entering

tf

FILE TRACE will be echoed to the screen. To start program execution, enter:

g

Allow the program to run until you encounter the error condition, and then exit. Your log file will contain the error information, all COBOL configuration file variables that have been set, and a record of every OPEN, READ, and WRITE.

Examine the log file and find the error output for the access denied error. The file name that precedes the error is the file generating the error. Note the full path of the file and retain the log file for future reference.

If you are using a UNIX server, verify that the file and directory permissions grant access to the user name:

  1. Log on to the server with the user name used (assumed to be used) by AcuServer. If that’s not possible (you don’t know the password or the login attempt fails), skip to step 3.
  2. After logging onto the server, perform an ls -l on the file using the full path (beginning with “/”). For example:
    ls -l /usr2/bsmith/fio_seq

    If the ls -l fails with a cannot access directory (or similar) error, the permissions on one or more of the directories are too restrictive. To access a directory, the directory must allow you EXECUTE permissions. Adjust the permissions or move the file to a directory that will allow access. If you are not the owner of the directories, you will need to ask the owner, or someone with root privileges, for assistance.

    After adjusting the permissions, verify directory access to the file by performing an ls -l on the full path to the file. If the ls -l” succeeds, the permissions set on the file are displayed. For example:

    -rw-r--r-- 1 prod general 4870 Aug 18 1993
   /usr2/bsmith/fio_seq

    Evaluate the file’s ownerships and permissions, including the group permissions, to determine if they allow the type of access required by the requesting application. Except as noted below, all files opened by AcuServer must allow READ and WRITE access. Under Sun OS with ACUCOBOL-GT version 2.1.2 or later, files having READ only permissions may be opened INPUT.

    If the file’s permissions need changing and the file is not owned by you, you will need to enlist the assistance of the owner of the file or someone with root privileges.

    Once the file and directories permit access, run the application again. If the program fails when attempting to access the same file and you have not yet confirmed the user name that AcuServer is using, perform the Confirming the user name diagnostics (below).

  3. If you can’t log onto the server under the user name used by AcuServer, ask your UNIX system administrator to evaluate whether the file in question is accessible to the user name. If the file or directories do not allow access, ask the owner of the file, or the system administrator, to adjust the permissions to allow access.

    After the permissions have been adjusted, run the application again. If the program fails attempting to access the same file and you have not yet confirmed the user name that AcuServer is using, proceed to the next section. Otherwise, contact Customer Support.

If you are using a Windows NT, Windows 2000 - 2008 server, verify that the file and directory permissions grant access to the user name.

  1. Log on to the server with the user name used (assumed to be used) by AcuServer. If that’s not possible (you don’t know the password or the login attempt fails), skip to step 3.
  2. After logging onto the server, select the file or directory. Then select: File > Properties > Security > Permissions from the menus. If the permissions are too restrictive, adjust the permissions or move the file to a directory that will allow access.

    When AcuServer is running as a Windows service, it belongs to an implicit group called SYSTEM. Otherwise it should belong to the Administrators group. If you are using AcuServer system security, make sure that the SYSTEM and Administrators groups are added to your file permissions with Full Control. This step is not necessary if you are implementing Windows NT security.

    Under AcuServer system security, files created by AcuServer are owned by the Administrators group and allow Full Control for SYSTEM and Administrator. Everyone is given the permissions specified by the third digit in the umask in the AcuAccess file.

    If you are not the owner of the directory or file, you will need to ask the owner, or someone with Administrator privileges, for assistance.

    Once the file and directories permit access, run the application again. If the program fails when attempting to access the same file and you have not yet confirmed the user name that AcuServer is using, perform the Confirming the user name diagnostics (below).

  3. If you can’t log onto the server under the user name used by AcuServer, ask your system administrator to evaluate whether the file in question is accessible to the user name. If the file or directories do not allow access, ask the owner of the file, or the system administrator, to adjust the permissions to allow access.

    After the permissions have been adjusted, run the application again. If the program fails attempting to access the same file and you have not yet confirmed the user name that AcuServer is using, proceed to the next section. Otherwise contact Customer Support.

Confirm the user name that AcuServer is using when the access denied error occurs. See Unexpected User Name for more information.

Note that some procedures require root or Administrator privileges. If you don’t have these privileges, enlist the assistance of your AcuServer or system administrator.

  1. If there is any doubt about your client user name, confirm your client user name.
    • On UNIX systems:

      Enter who am i at the UNIX prompt.

    • On Windows systems:

      If a user is logged into a Windows NT/2000 workgroup or domain, AcuServer will use the user’s log-in name. Otherwise, it uses the user name value that is set by the environment variable USERNAME. If USERNAME is not set, the runtime uses the value that is set by the environment variable USER. (The values of these variables are case-sensitive.) If neither of these environment variables is set, the runtime uses the literal string USER.

      To confirm the presence (or absence) of the USERNAME environment variable, enter SET at the command prompt. SET will display the values of all environment variables.

      COMSPEC=C:\COMMAND.COM
PATH=C:\;C:\WINDOWS;C:\MOUSE;
PROMPT=$P$G
USERNAME=BERNIE

      If USERNAME is defined, the value of USERNAME is the name passed to AcuServer. Otherwise, the variable USER is checked. If USER is not set, then the literal string USER is passed.

  2. If acuserve is running with level 2, 3, 6, or 7 tracing enabled, all connections and disconnections are reported in the AcuServer log file. Inspect the log file and look for the last connection entry for your client machine name/client user name combination. The trace messages associated with that connection request will include the Local Username that AcuServer has assigned to that connection. Find the line that reports the mapping of the client user name to the local user name.
    acuserve: 06/13/94 12:43:44 -
   Server version: 010000
   Client version: 010000
acuserve: 06/13/94 12:43:44 -
   AUTHORIZATION request from user:bernie
>> client:starling,
   PASSWORD-ATTEMPTS allowed:3
>> Mapping user:bernie to local user:bsmith
>> Socket:5, uid:205, gid:101
>> Password is not required
acuserve: adding
   client:starling, user:bernie,
   pid:18397, fid:57a28

    If the local user name is not the one you expect, consult with your AcuServer system administrator to verify that it is the correct user name. Your system administrator can make any necessary changes to the server access file.

  3. If acuserve is not running with tracing enabled, you can turn it on using the acuserve -config option. At the command line, type acuserve -config, then type set FILE_TRACE 2 (or 3, 6, or 7) at the prompt, then type exit. After tracing is turned on, run your application again and follow the procedure outlined in step 2, above.

    When you no longer want tracing enabled, type acuserve -config again, then type set FILE_TRACE 0 at the prompt.

Parent topic: Troubleshooting


Unexpected User Name

Problem: AcuServer establishes a connection with the client, but uses an unexpected user name (Local Username).

There are two common reasons for getting an unexpected Local Username on the server:

  1. The client machine/client user combination isn't matching the expected access record.
  2. The client machine/client user combination matches an access record that specifies an unexpected Local Username (perhaps the name of a group account, or an account with restricted privileges).

To investigate and correct this situation you must be familiar with AcuServer server access configuration, and have access to root or administrator privileges. Work with your AcuServer system administrator.

The diagnostic procedures include:

  1. Confirming your client user name
  2. Confirming your client machine name
  3. Looking up your client user name/client machine name combination in the server access file

Diagnostics

  1. Confirm your client user name.
    • On UNIX clients:
      • Log onto the client system using the same user name and UNIX environment that resulted in the unexpected user name.
      • If the system is a UNIX system, enter who am I at the UNIX prompt.

        Is the user name returned the name you expected?

    • On Windows clients:

      If a user is logged into a Windows NT/2000 workgroup or domain, AcuServer will use the user's log-in name. Otherwise, it uses the user name value that is set by the environment variable USERNAME. If USERNAME is not set, the runtime uses the value that is set by the environment variable USER. (The values of these variables are case-sensitive.) If neither of these environment variables is set, the runtime uses the literal string USER.

      To confirm the presence (or absence) of the USERNAME environment variable, enter SET at the command prompt. SET will display the value of all environment variables.

      COMSPEC=C:\COMMAND.COM
PATH=C:\;C:\WINDOWS;C:\MOUSE;
PROMPT=$P$G
USERNAME=BERNIE

      If USERNAME is defined, the value of USERNAME is the name passed to AcuServer. Otherwise, the variable USER is checked. (Both of these variables are case-sensitive.) If USER is not set, the literal string USER is passed.

  2. Confirm the name of the client system.
    • On UNIX clients, enter:
      hostname

      or

      uname -n

      The system will return its official network host name.

    • For Windows NT/2000 clients:
      1. Go to Start > Settings > Control Panel > Network > Protocols.
      2. Select TCP/IP.
      3. Choose Properties > DNS > Host Name.

      The name you specify for the Host Name entry is the one that the runtime uses.

  3. On the server, examine the server access file for the record that matches the client machine name/client user name combination. This process requires root privileges on a UNIX server, and administrator group privileges on a Windows NT, Windows 2000 to 2008 server. It should be done by the AcuServer system administrator.
    1. Run the server access file manager utility:
      acuserve -access
    2. Be sure to enter the name of the working server access file when prompted.
    3. Select menu item [4] - Display one/all security records.
    4. Respond N to the prompt: Display all records?
    5. To the next two prompts, provide the client machine name and client user name, respectively. The matching record will be displayed.

      The AcuServer system administrator should be able to determine whether this is the appropriate and expected access record for the client machine name/client user name combination and take any necessary steps to modify the record, or add a new one.

Parent topic: Troubleshooting


Connection Refused

Problem: Attempts to connect to the server fail with a 9D/ 103, connection refused error.

Connection refused errors occur for two reasons:

  • The matching access record specifies an invalid Local Username, or DEFAULT_USER holds an invalid user name. Note that use of the same as client string in the Local Username field of the access record can lead to the attempted use of an invalid user name (same as client directs AcuServer to use the Client Username as the Local Username).
  • There is no matching access record for the client machine name/client user name combination.

Diagnostics

Confirm your client user name and client machine name, and find the combination's matching entry in the server access file.

  1. Follow diagnostic steps in Unexpected User Name.
  2. Examine the server access file for the record that matches the client machine name/client user name combination (this should be performed by the AcuServer system administrator).
    1. On a UNIX server, become superuser or log on as root. On a Windows NT, Windows 2000 to 2008 server, log in as administrator or from an account that belongs to the administrators group.
    2. Run the server access file manager utility (acuserve -access).
    3. Be sure to enter the name of the working server access file in response to the utility's first prompt.
    4. Select menu item [4] - Display one/all security records.
    5. Respond no (N) to the prompt Display all records?.
    6. Respond to the next two prompts with the client machine name and client user name, respectively. The matching record will be displayed.

    If there is no matching entry, you need to add one:

    • If the Local Username field contains the name of a user (a string), check the UNIX password file (/etc/passwd) or the Windows NT/2000 User Manager for the presence of a valid entry for that name. If no entry exists, the name is not valid.
    • If the Local Username field is same as client, Local Username is set to the value of Client Username. Check the UNIX password file (/etc/passwd) or the Windows NT/2000 User Manager for the presence of a valid entry for that name.
    • If the Local Username field is blank, Local Username is set to the value of the server configuration variable DEFAULT_USER. The value of DEFAULT_USER is defined in the server configuration file. Check the UNIX password file (/etc/passwd) or the Windows NT/2000 User Manager for the presence of a valid entry for that name.
Parent topic: Troubleshooting


Invalid Password

Problem: Attempts to connect to the server fail with a 9D, 102, invalid password error.

File system error value = 102
Invalid connection password specified by client

The causes and remedies of password match failures are straightforward. Invalid password errors occur for two reasons:

  1. The password supplied via interactive input does not match the password in the access record.

    These failures are obvious and simply require that you work with your AcuServer system administrator to establish a new password or to have the password requirement removed.

  2. The password is supplied by the application via the Acu_Client_Password variable, and the value of Acu_Client_Password does not match the password in the access record.

    Because password transactions involving Acu_Client_Password are invisible to the user, the cause of these failures is not immediately obvious. If you are getting the error message given above, but you're not being prompted for a password, the application is using Acu_Client_Password. The value of Acu_Client_Password is set when the application is installed. To change or remove the password requires assistance from the application's technical support group. Contact your application vendor.

Parent topic: Troubleshooting


Client and Server Both Hang When Connecting

Problem: Attempts to connect to a Windows server cause both the client and the server to hang.

To use Windows NT security with AcuServer rather than AcuServer system security, your network must be set up with the appropriate permissions. If it is not, the client and server may both hang when the offending client attempts to connect.

When you are using Windows NT security, the server actually runs with the permissions of the client temporarily whenever the client requests access to a file. The method used to execute in this mode is called "impersonation" and requires a named pipe connection between the client and the server. A problem occurs when the client does not have the appropriate permissions to connect to the named pipe. Since the named pipe is not the primary means of communication, the client, failing to connect to the named pipe, tells the server it is shutting down. The server, however, is stuck waiting for the client to connect to the named pipe (which it will now never do). With the server stuck at the named pipe and the client stuck at the socket, both systems are hung. Each must be killed in whatever way your system allows (Task Manager, and so on).

Parent topic: Troubleshooting


Frequently Asked Questions

Question

Is AcuServer faster or more secure than using mapped drives in Windows or Novell environments?

Answer

Some operating environments implement aggressive file caching techniques, such as mapped drives, to improve file processing speed. However, errors in these buffering techniques can occasionally lead to corrupted files. AcuServer cannot always match the file processing speeds of the caching methods, but it is faster in certain situations and provides better file integrity. One situation in which the use of file caching techniques (instead of AcuServer) could lead to a caching error and corrupted files is described below.

When an ACUCOBOL-GT runtime asks that a record be rewritten to a file that is shared among multiple clients, the runtime might receive a response indicating that the operating system has correctly rewritten the record, when in fact the record may still be in a memory cache. If a second runtime (on a separate system) then asks for the same record, it will receive a copy of the unchanged record from the shared disk. When this second runtime rewrites the record, the data may actually be cached on this second system, just as it was cached on the first. In this situation, somebody's update to the record is going to be lost when the actual rewrites occur. If the rewrites contain index information as well as data, the problem might include structural file damage, leading to broken files.

Windows-based clients with mapped drives on a Windows NT server can easily fall into this category because of a caching bug. An ACUCOBOL-GT runtime executing on Windows client machines with data files on mapped drives on a Windows NT server can run faster than AcuServer, because the Windows client systems are caching data writes in their local memory. This approach can give increased file performance as long as the number of clients remains small. This file performance advantage begins to disappear as user counts increase. However, at any number of users, this scheme is at risk for data corruption, which is entirely dependent on timing vagaries. Even with a small user count, the scenario noted in the previous paragraph could occur. AcuServer provides better file integrity than the caching approach.

AcuServer can improve file performance in certain situations. AcuServer is faster than shared drives in situations where two or more users are accessing a single file in an interactive mode. This is because Windows caches mapped disk network files if only one user is in the file, but as soon as another user enters the file caching is terminated. Windows does not seem to know when caching can recommence.

In addition, consider the case of a keyed READ or START to a Vision file that has an average index tree height of four. The root node of the index tree is located by a field in the header, so a read of the header is necessary, followed by an average of four reads to move through the levels of index records, finally followed by a read of the data record. If a client runtime is using Novell or mapped drives, each of those reads must be transmitted across the network, with possibly hundreds of bytes of information returning to the client runtime for each read. If AcuServer is being used, the client runtime calls the appropriate file routine in AcuServer via one socket call. AcuServer knows how to issue all the reads to find the root node of the indexes, to track the needed record through the index tree and to read the data record, and all of this is done on the server with no network traffic. The requested data record is then transmitted back to the client runtime over the network. This approach represents significantly less network traffic than having the client runtime itself do each of the I/Os across the network.

Question

In my Windows NT or Novell environment, I would like AcuServer to serve some of the COBOL objects and data files for my application, but I would also like to access some of the objects and data files via mapped drives. May I do so?

Answer

Yes. You can use CODE_PREFIX, FILE_PREFIX, or file aliases in the client runtime configuration file. For example:

CODE_PREFIX @server1:C:\path\sub H:\path\sub
FILE_PREFIX @server1:C:\path\sub H:\path\sub
filea @server1:C:\path\sub
fileb H:\path\sub\fileb

The first two examples above rely on the fact that a runtime will use the CODE_PREFIX or FILE_PREFIX entries left to right, in a continuing search to find the COBOL object or data file. The first two examples will direct the client runtime to first ask AcuServer to serve the COBOL objects and data files. If AcuServer can't find them, the runtime is directed to look for them on the mapped drive. You could reverse the search by reversing the sequence of the entries in CODE_PREFIX or FILE_PREFIX. Specifying individual file aliases will be faster than FILE_PREFIX in opening data files.

Question

Which releases of AcuServer are currently supported?

Answer

Our Technical Services continues to offer telephone and fax support for every release of AcuServer and would be pleased to answer your questions about any version of the product. However, all releases of AcuServer prior to Version 5.2 have been retired from our sales portfolio. This means that the older versions are no longer sold, and that you obtain a correction to a problem uncovered in a retired version by updating your site to the latest version that contains the fix.

Question

Is AcuServer able to print files?

Answer

AcuServer is a file server. This means that it services file operations. To print, the runtime submits a process to the printer (in the case of Windows NT, it submits a spooler job). Because AcuServer is not intended to service (or start) processes, it is not able to print files to a printer. However, the programmer could use AcuConnect® in conjunction with AcuServer to achieve this functionality. Another option is to assign the print file to disk by establishing an alias for the file in the runtime configuration file with the -f flag, as shown in this example:

printer1 -f /usr2/users/jsmith/printer1

This causes a file named printer1 to be created in the /usr2/users/jsmith directory. This file is a line sequential file with additional formatting characters.

Question

Is AcuServer multi-threaded?

Answer

AcuServer is single-threaded. AcuServer processes each request to completion, on a first-come-first-served basis. This means that while AcuServer is engaged in handling a request from one client runtime, other runtime requests are queued in a manner appropriate to the server's operating system, awaiting AcuServer's completion of the current request.

Multiple instances of AcuServer can be executed on the same server or on multiple servers. Each separate instance of AcuServer is a single-threaded program.

Question

AcuServer's response to -info is larger than will fit on my screen, and I lose the information that scrolls past the top. How can I see it all?

Answer

Use the properties ability of a command prompt to increase the size of the window or:

  • On UNIX:
    • For the sh and ksh shells, use:
      acuserve –info 2> somefilename
    • for the csh shell, use:
      acuserve –info >& somefilename
  • On Windows NT:
    acuserve –info 2> somefilename

    Then use any editor to view somefilename.

Question

The entries I previously used for FILE_PREFIX and CODE_PREFIX in the configuration file when AcuServer was on UNIX don't work for Windows NT (or vice versa). Which is correct?

Answer

The entries need to comply with operating system naming conventions.

On UNIX, the use of the colon and the direction of the slash are relevant:

FILE_PREFIX @servername:/path
CODE_PREFIX @servername:/path

On Windows NT, the direction of the slash is not important, but the drive designation must be included along with the pathname:

FILE_PREFIX @servername:C:\path
CODE_PREFIX @servername:C:\path

(where C is a drive letter)

Question

I'm sure I have sufficient values specified in MAX_FILES, MAX_LOCKS, and LOCKS_PER_FILE in the client configuration file and in the AcuServer configuration file. But I still can't open all the files my application needs, or my application runs out of locks. How can I solve this?

Answer

In most UNIX operating environments, there is a limit to the maximum number of files that can be opened by any process and the maximum number of locks that can be held by any process. These limits are set in the UNIX kernel. If the settings of these kernel parameters are too low, AcuServer may reach these kernel limits before ever reaching the values you have specified in MAX_FILES, MAX_LOCKS, or LOCKS_PER_FILE.

If you have a C compiler on your UNIX system, you might want to make use of a C utility program (numfiles.c) that is available from our Technical Services. This utility can help you determine how many files your UNIX system will allow a process to open. The utility simply attempts to open 1,000 files and reports the number of the last file it was able to open successfully (if you would like to attempt a smaller or larger number of file opens, change the #define NUM_FILES).

The tuning of the kernel parameters on your UNIX systems is specific to your site and should be determined by your local specialist. Contact your UNIX system administrator to research or change the values of the kernel parameters that control maximum files per process or maximum locks per process at your site.

Question

I'm sure my client system has a valid connection to the server and that the files I'm trying to reach exist, but my attempts to access the files lead to an access denied error (File error 37,07 on @servername:/path/sub/file). How can I solve this?

Answer

This file error indicates that file permissions are probably not set up in a way that allows access. It may stem from variables set in your client system, so let's examine those variables first.

When a client runtime attempts to connect to AcuServer, it passes two variables to AcuServer: the client machine name and client user name. AcuServer checks the values of these two variables against the server access file (called AcuAccess by default). AcuAccess contains one or more access records. These access records define which users of which clients are permitted access to AcuServer. AcuAccess is designed to support a wide range of access security, from very open to very restrictive. You choose the level of security best suited to your needs.

The first variable passed from the client is matched against the AcuAccess field Client-Machine-Name, and the second is matched against Client-Username. See Diagnosing Errors with C$PING for a complete description of where those variables come from on various client systems. AcuServer Connection Logic describes how AcuServer uses these variables to determine which account will be used on the server for file access.) AcuAccess will look first for a specific match for the client variables, then for a wildcard that might allow access to the client. This example shows how you can uncover the source of a permissions problem at your site.

Execute AcuServer with a trace file, as shown here:

acuserve –start –e errorfile –t3

Attempt to connect to AcuServer, then after the failure, examine errorfile. You should see lines that resemble this:

acuserve: 08/13/99 17:48:39 – AUTHORIZATION request from user: klevine
>> Socket:0, client:klevine-ntw, pid:282, PASSWORD-ATTEMPTS allowed:3
>>>key 0 = 'klevine-ntw         klevine         '
>>>key 0 = 'klevine-ntw                         '
>>>key 0 = '*                   klevine         '
>>>key 0 = '*                                   '
>> Mapping user: klevine to local user:guest   acuserve: LookupAccountName for guest

In the above example, klevine-ntw is the variable from the client that is matched to Client-Machine-Name, and klevine is the variable that is matched to Client-Username in AcuAccess.

In the above example, the AcuAccess file on the server had a single access record:

Client Machine Name  Client Username  Local Username   Password   Umask
-------------------  ---------------  --------------   --------   -----
*                                     guest            <none>     002

Note that the Client-Machine-Name is a wildcard (matches any name). The Client Username is set to spaces. AcuServer attempts to find an AcuAccess record that has klevine-ntw as Client-Machine-Name AND klevine as Client-Username. There is no such record in the file. See AcuServer Connection Logic for more information.

Next, AcuServer attempts to find a record that has klevine-ntw as Client-Machine-Name AND spaces as Client-Username. There is no such record in the file.

Next, AcuServer attempts to find a record that has "*" as Client-Machine-Name AND klevine as Client-Username. There is no such record in the file.

Finally, AcuServer attempts to find a record that has "*" as Client-Machine-Name AND spaces as Client-Username. Such a record exists in the AcuAccess file, with the Local-Username set to guest.

AcuServer verifies that guest (in the sample above) is valid on this server. Because guest is valid on this server, future file requests from this client will be treated on the server as if guest had made the requests.

If the user specified in Local Username of the AcuAccess file is not valid on the server, the AcuServer configuration variable DEFAULT_USER will be used. If this is a valid user on the server, future file requests from this client will be treated on the server as if DEFAULT_USER had made the requests.

(If neither the Local Username of the appropriate record in the AcuAccess file nor DEFAULT_USER is valid on the server, the Authorization Request is denied.)

In our example, if receiving an access denied error (File error 37,07 on @servername:/path/sub/file), the Client-Machine-Name and Client-Username are still acceptable for the AcuAccess file shown above. Thus, in this case the error message must indicate that Local Username guest doesn't have permission to access the files the application needs.

Question

I'm sure my client system has a valid connection to the server and that the files I'm trying to reach exist, but my attempts to access the files lead to a File not found error (File error 35 on @servername:/path/sub/file). How do I solve this?

Answer

This might be caused by insufficient file permissions or by a client runtime that is not AcuServer-enabled.

  1. Verify that the client runtime being used is AcuServer-enabled. At a command line prompt, type:
    <name-of-your-runtime> –v

    Depending on your client platform and runtime version, the response may include a line like:

    AcuServer client

    or

    Network enabled

    Absence of a line similar to one of the two shown above indicates that your runtime does not have the ability to communicate with AcuServer. Contact your Micro Focus extend sales representative to obtain a runtime that does have that capacity.

  2. See the discussion in the preceding question about how AcuServer authorizes a client runtime. The most likely cause of this error is that the local user who was finally selected on the server machine does not have write permissions in the named directory, and the COBOL program is trying to open the file OUTPUT.

Question

Client runtimes experience slow response times during heavy loads (perhaps sometimes even exhausting the DEFAULT_TIMEOUT value and returning 9D/05). Is there anything I can do?

Answer

Here are several options to consider:

  1. AcuServer is single-threaded, handling a single request from a single client runtime to completion before attending to requests from other client runtimes, which are queued up in a manner dependent on the server's operating system. Slow response time may indicate that a single copy of AcuServer cannot keep ahead of the queued requests at times of peak load.

    If the load on AcuServer is variable, the DEFAULT_TIMEOUT tolerance allowed by client runtimes may be sufficient most of the time, but may be too brief to allow for the times when AcuServer is heavily burdened. In those cases, setting DEFAULT_TIMEOUT to a higher value can avoid the timeout errors. (On the other hand, if AcuServer is actually unable to access the data for some other reason – such as insufficient file permissions – then increasing DEFAULT_TIMEOUT only increases the amount of time that transpires before the client runtime returns the error message.)

    If there are sufficient system resources available on the server (memory, CPU cycles, I/O bandpass to multiple disks, and so forth), you may gain relief by acquiring an appropriate license and executing multiple instances of AcuServer on the same server. On the server, the operating system will use the time while one instance of AcuServer is waiting for the completion of an I/O process to allow another instance of AcuServer to have the CPU. This second instance of AcuServer will also then issue some I/O command of its own, and (assuming that there are multiple I/O subsystems capable of independent action), the I/O wait time of the multiple instances will interleave. A server with multiple CPUs may gain even more improvement with this approach.

    If you choose to run multiple instances of AcuServer, note that there is no automatic balancing of the load among them. You must direct each specific client runtime to use a particular AcuServer by (a) starting each instance of AcuServer with a particular ACUSERVER_PORT number and (b) setting the client runtime configuration variable of the same name to that value.

  2. You can choose to execute multiple instances of AcuServer on separate servers. In this case, you need not start each AcuServer with a separate ACUSERVER_PORT setting, as noted above. Rather, you would use FILE_PREFIX or file aliases in the client runtime configuration file to direct specific client runtimes to AcuServers running on specific servers. For example:

    In the runtime configuration file of client A:

    FILE_PREFIX @server1:/path/sub

    In the runtime configuration file of client B:

    FILE_PREFIX @server2:/path/sub
  3. You could combine approaches (1) and (2) and run multiple instances of AcuServer on multiple servers. In that case, each instance of AcuServer would need to be started with a ACUSERVER_PORT unique on that server. FILE_PREFIX or file aliases would be needed in each client runtime configuration file to point to the appropriate server. Also, ACUSERVER_PORT would need to be set to point to the appropriate instance of AcuServer on that server.
  4. If there are no runtimes executing on the server, or if the runtimes executing on the server don't use the same files that are being requested by the client runtimes, you can improve performance by directing AcuServer to open data files for exclusive use. To do this, set the AcuServer configuration variable LOCK_ALL_FILES to 1. With this variable on, AcuServer will open data files for exclusive use rather than using individual record locks; this will improve throughput. Note that this is not a workable option if multiple instances of AcuServer will be executed on the same server and will be accessing the same data files.

    (If the runtimes executing on the server do use the same files as client runtimes, you can direct the runtimes on the server to also use AcuServer, rather than opening the files themselves, by setting USE_LOCAL_SERVER to 1 in their configuration files. This will allow use of LOCK_ALL_FILES as noted above, so AcuServer can again open the data files for exclusive use, which is faster.)

  5. If client runtimes need to open files that may be located in various directories on one server or may be located on various servers, it is faster to use file aliases rather than a FILE_PREFIX that points to multiple paths or multiple servers. A great deal of network traffic can be avoided in those cases where the file that a client runtime is seeking happens to be in the last directory or on the last server specified in FILE_PREFIX. For example:
    FILE_PREFIX @server1:/path1a/sub1a @server1:/path1b/sub1b @server1:/path1c/sub1c

    The above method would be slower at opening files than:

    filea @server1:/path1a/sub1a/filea
fileb @server1:/path1b/sub1b/fileb
filec @server1:/path1c/sub1c/filec

    And notice:

    FILE_PREFIX @server1:/path/sub @server2:/path/sub @server3:/path/sub

    The above settings would be slower at opening files than:

    filea @server1:/path/sub/filea
fileb @server2:/path/sub/fileb
filec @server3:/path/sub/filec
  6. The AcuServer server configuration file can use the following variables:
    V_BUFFERS
V_BUFFER_DATA
V_READ_AHEAD

    Setting those variables in the AcuServer server configuration file overrides any setting of the identically named variables in the client runtime configuration file. These variables have the same function on AcuServer as they have on a client runtime, and they can affect file performance. Consult Appendix H in the ACUCOBOL-GT manual set for specifics.

  7. You have chosen AcuServer for its ability to serve COBOL object files and data files for your application. However, these data accesses may be overloading your network. If analysis of network performance indicates that network overloading is contributing to your application response time slowdown, consider that some data files in your application might be able to reside on the client system. The goal is to reduce the amount of traffic over the network. Some possibilities in this regard are:
    1. If the application creates temporary files, also consider placing them on a local drive. If the file is useful only on a particular client, and need never be seen by other client systems on the network, you can reduce the network burden by using a file alias in the client configuration file to place this file on a local drive.
    2. If the application has some data files that do need to be seen by every client runtime, but are only updated periodically, consider placing copies of these files on each client system and pointing at them with file aliases. Again the goal is to reduce network traffic. You would have to balance the administrative work of getting correct copies of these files placed on each client in a timely fashion against the gain in network performance by keeping access to these files off the network.
Parent topic: System Management


Glossary of Terms

  • ACL
  • ACP
  • acushare
  • daemon
  • multiple-record mode
  • name alias
  • NTFS
  • remote name notation
  • server access file
  • umask
  • XFD
Parent topic: AcuServer Version 10.2.0 User's Guide


ACL

Access Control List; used byWindows NT and Windows 2000 - 2008 to control access to resources. An ACL specifically grants access to a user or to a group. Privileges are additive, meaning that users have the highest access given to their account and to any groups to which they belong. The exception is No Access, which overrides any other privileges.
Parent topic: Glossary of Terms


ACP

AcuServer Control Panel; a Windows graphical user interface for performing AcuServer functions.
Parent topic: Glossary of Terms


acushare

License manager for UNIX servers.
Parent topic: Glossary of Terms


daemon

A memory resident program.
Parent topic: Glossary of Terms


multiple-record mode

A mode in which AcuServer returns multiple records in a single network packet rather than one record at a time. Designed for reading a large number of sequential records without user interruption, such as when you are generating a report. Files opened in this mode are optimized for sequential reading, but have restrictions placed on the types of operations they can do.
Parent topic: Glossary of Terms


name alias

A substitute string for the literal name that appears in the ASSIGN TO clause of a SELECT statement.
Parent topic: Glossary of Terms


NTFS

NT file system, the file system used by Windows NT.
Parent topic: Glossary of Terms


remote name notation

Notation used to refer to files located on the server.
Parent topic: Glossary of Terms


server access file

Access database that specifies which client systems and client users are permitted to use AcuServer and what their user privileges are.
Parent topic: Glossary of Terms


umask

File creation mask. The read and write permissions set on new files are determined by the umask specified in the matching server access record.

On UNIX servers, the umask is a variable having a three-digit octal value, similar to that used by chmod, but which describes the permissions that are not to be set on new files.

On Windows NT and Windows 2000 - 2008 servers, the umask is used to set read and write permissions for the owner (leftmost digit) and for other (rightmost digit). The group digit (middle) is ignored.

Parent topic: Glossary of Terms


XFD

eXtended File Descriptor. A data dictionary useful for translating COBOL records into other data formats.
Parent topic: Glossary of Terms


AcuSQL Version 10.2.0 User's Guide

  • Copyright Statement
  • Getting Started
  • Program Preparation
  • Pre-compiler Function and Use
  • Program Execution
  • Sample Programs
  • Glossary of Terms
Parent topic: extend Product Guides


Getting Started

  • Introduction to AcuSQL
  • AcuSQL Pre-compiler
  • AcuSQL Runtime Library
  • Requirements
  • Installation
  • Organization
  • Demonstration Programs
  • Technical Services
Parent topic: AcuSQL Version 10.2.0 User's Guide


Introduction to AcuSQL

Welcome to the AcuSQL® pre-compiler and runtime library. This add-on tool to the ACUCOBOL-GT® development system is a simple, cost-effective solution for those who want or need to use embedded SQL (ESQL) statements in COBOL programs to access SQL-conversant data sources.

AcuSQL is part of the extend® family of technologies and is designed to give COBOL applications access to IBM® DB2®, Microsoft® SQL Server, and ISO/ANSI SQL92 compliant data sources. AcuSQL also supports the open source database, MySQL®.

References to Windows in this manual denote any of the supported Windows platforms, which are listed in the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx. Where it is necessary to make a distinction, the specific version name/number is specified. . AcuSQL is available for most UNIX® operating system platforms, including 64-bit environments.

The AcuSQL pre-compiler is a powerful programming tool that allows you to embed SQL statements in your COBOL application. ESQL enables you to access the power and flexibility of Structured Query Language (SQL) from within your COBOL application. With AcuSQL, you can execute complex data selection and processing operations using the database engine to perform most of the work, greatly simplifying the COBOL code needed to perform the operation. AcuSQL supports both static and dynamic SQL.

AcuSQL support of native dialects of SQL (DB2, MySQL, SQL Server), ISO/ANSI SQL92, and a relaxed version of SQL enables you to write applications custom-tailored to a wide variety of individual databases or a more generic version able to run across multiple databases and data sources.

AcuSQL support for ESQL is provided by a special pre-compiler and runtime library.

Parent topic: Getting Started


AcuSQL Pre-compiler

The pre-compiler gives you the option of specifying various levels of SQL syntax checking, including modes that are specific to IBM DB2 SQL, MySQL, Microsoft SQL Server, and a mode that directs the pre-compiler to send SQL statements directly to the database engine for syntax verification. These syntax checking options give you a great deal of flexibility in developing your ESQL applications. In addition, you can stipulate relaxed or strict checking for certain individual commands in your program.

The AcuSQL pre-compiler works by scanning both the COBOL source file and all copy files for ESQL statements. It preserves the original statements in a comment block, performs syntax checking (either directly or indirectly), and then translates each statement into a standard COBOL CALL statement to the AcuSQL runtime library. All other code is untouched.

Although pre-compiling adds an additional step to the development process, a great deal of time and effort are saved by not requiring you to write database-specific API calls in your application. A single SQL statement in your COBOL program may translate to many API calls in the generated AcuSQL code. Embedded SQL is also easier to write and maintain than the corresponding API calls.

Pre-compilation is initiated from within the AcuBench® development environment or from the ACUCOBOL-GT command line. In AcuBench, when you set the pre-compile option on an ESQL file, the workbench automatically pre-compiles the file every time the project is built or the file is compiled. All pre-compilation errors are displayed in the AcuBench Outut Window. On the ACUCOBOL-GT command line a set of compiler flags initiates pre-compilation. Error messages are directed to standard output.

Parent topic: Getting Started


AcuSQL Runtime Library

Successful pre-compilation followed by successful compilation results in the creation of an object file. The object file is ready for execution by the runtime. When the object file is executed, the embedded SQL statements (now standard COBOL statements) are passed to the AcuSQL library, which in turn communicates with the database connectivity software (an ODBC level 2 API), establishing connections, retrieving and writing data, and exchanging messages.

Parent topic: Getting Started


Requirements

See the System Requirements section of the extend Release Notes for information about AcuSQL requirements.

Parent topic: Getting Started


Installation

Before installing AcuSQL, you should install, configure, and test your application-host to data-host connection software. For accessing DB2 databases, AcuSQL has been tested with IBM DB2 Connect software, and its use is recommended. However, any vendor’s properly installed and configured ODBC level 2 API connection is acceptable. This middleware connection software is essential to AcuSQL’s successful use.

Note: You must ensure that your connection middleware is functioning properly before attempting to run an AcuSQL-supported application.
  • Installation Under Windows
  • Installation Under UNIX
Parent topic: Getting Started


Installation Under Windows

AcuSQL is installed using Windows Installer. To install AcuSQL on your Windows host:

  1. Log onto your Windows system.

    Under Windows NT or Windows 2000, to ensure that all files are installed with the correct permissions, it is recommended that you log on using the Administrator account or an account that belongs to the Administrators group. You should also close all applications running on the system.

  2. Insert the installation CD-ROM into your disk drive. If the installation program does not start automatically, click Start, select Run, and then enter:
    D:\autorun.exe

    replacing D with the device designation of your CD-ROM drive. Follow the instructions on the screen, entering your product code and product key when prompted.

  3. When the Products Selection screen appears, select Custom from the list and click Next.
  4. Select AcuSQL from the product list, and if desired, Online Documentation. Before clicking Next, take special notice of the default installation directory appearing near the bottom of the window. Click Browse to designate a different directory. If you specify a different directory, a subdirectory named with the release version (e.g.Acucbl800) is not created. AcuSQL is installed in the directory you specify.
  5. Click Next to proceed with the installation and follow the instructions on the screen. The program will inform you when installation is complete.

There is nothing on the AcuSQL distribution media to install on your data source host machines.

On the Start menu under Programs > Acucorp 8.x.x > AcuSQL (or the name of the program group you specified), you will find entries for the AcuSQL Release Notes file. To view the online help for AcuSQL, select extend8 Documentation Set from the Start > Programs > Acucorp 8.x.x menu. This opens a document containing a listing of available documentation. Then select the AcuSQL User’s Guide from this listing.

Parent topic: Installation


Installation Under UNIX

Note: In the following directions, the term runtime system refers to the runtime shared object on systems where the ACUCOBOL-GT runtime is a shared object and to runcbl on other systems, where the runtime is static. The runtime is a shared object on the following systems: AIX 5.1 and later, HP/UX 11 and later, and Solaris 7 and later. To check, look at the contents of the lib subdirectory of your ACUCOBOL-GT installation. If the files libruncbl.so or libruncbl.sl reside in that directory, the runtime is a shared object on your system.

To install AcuSQL on your UNIX host:

  1. We recommend that you install AcuSQL into your ACUCOBOL-GT home directory. When you install in this way, the AcuSQL libraries and executables are added to the existing ACUCOBOL-GT bin and lib subdirectories. If you choose to install into a different directory, separate bin and lib subdirectories are created. You must include the location of the new bin directory in the definition of your path environment variable. No matter which directory you select for your installation, you must make sure that AcuSQL and the ACUCOBOL-GT compiler executable (ccbl) are in the same subdirectory.
  2. Insert the installation CD-ROM. The instructions for installing from CD-ROM are provided on a Getting Started card supplied with the CD-ROM.

    Follow the instructions on the screen, entering your product code and product key when prompted.

  3. Relink the runtime system to include your ODBC API library.
    Note: This step is not required if you are running a shared libraries build of the extend Interoperability Suite and are using one of the supported driver managers: unixODBC (www.unixodbc.org); DataDirect (www.progress.com); iODBC (www.iodbc.org), and the driver manager's lib directory is on the LD_LIBRARY_PATH.
    Warning: Relinking the runtime requires access to the C compiler supplied by the vendor of your UNIX software; in some cases the C compiler is offered as an add-on option. If the C compiler used to build the ODBC libraries creates files that are incompatible with those created by the C compiler used to build the runtime, the link may fail.
    1. In the lib subdirectory (of the directory into which you installed AcuSQL), edit config85.c and set the value of NO_ACUSQL to 0.
    2. Edit Makefile and locate the line that reads:
      ACUSQL_ODBC_LIB =

      Add the name of your ODBC API library to the end of the line. For example:

      ACUSQL_ODBC_LIB = ODBC_lib

      where ODBC_lib is the name of your ODBC API library. If you are working with DB2, the name of the library is libdb.so. If you are working with MySQL, the name of the library is libmyodbc3.

      If this library is not statically linked, your operating system must be able to locate this library. On some systems, this is accomplished by listing the directory in the environment variable LD_LIBRARY_PATH. (See your operating system documentation for more information on shared libraries.)

    3. Also in Makefile, locate the lines:
      ACUSQL_FLAGS = -DNO_ACUSQL=1

      ACUSQL_LIBS = # no acusql runtime libraries are necessary

    4. Make sure that the above lines are commented out (use the comment character “#”).
    5. Next, locate the lines:
      #ACUSQL_FLAGS =
#ACUSQL_LIBS = $(ACU_LIBDIR)/libesql.a $(ACUSQL_ODBC_LIB)

      Make sure that the above lines are un-commented (remove the comment character “#”).

    6. Save and close Makefile.
    7. Relink the runtime system by entering the following commands:
      make clean
make

      The default target of the Makefile is the runtime system, so this relinks runcbl on machines that do not have shared objects, and libruncbl.so on those that do.

      You can also relink the runtime system by executing the following command:

      make relinkrun

      This works on all systems.

      If you get unresolved reference errors that refer to your ODBC library, you will need to further modify the Makefile to include the needed libraries (see your ODBC API documentation). Such libraries can be added to the end of the LDFLAGS lines, or at the end of the list for runcbl and acusql.

    8. If the runtime system is a statically linked runcbl, move the new executable file into the bin directory. This step is not necessary when the runtime system is a shared library. In these cases, the shared object runtime, lib/libruncbl.so, is already in the correct location.
  4. If you plan to use the pre-compiler mode that connects directly to your database engine to verify the SQL syntax, you must relink acusql to include your ODBC API libraries.
    1. If you haven’t already done so, perform sub steps 1 and 2 of item 3 above.
    2. Relink the pre-compiler by entering the following command:
      make acusql
    3. Move the new acusql executable file into the bin directory.
Parent topic: Installation


Organization

The AcuSQL User's Guide includes the following:

  • Getting Started: Provides an overview of the AcuSQL product. It also provides installation information.
  • Program Preparation: Describes how to prepare your embedded SQL program, including an introduction to SQL syntax.
  • Pre-compiler Function and Use: Discusses the pre-compiler, including usage, environment variables, and errors.
  • Program Execution: Discusses running your application.
  • Sample Programs: Describes five of the sample programs included with AcuSQL. In addition, several SQL commands and concepts are introduced.
Parent topic: Getting Started


Demonstration Programs

Included with your AcuSQL software are several ESQL demonstration programs. These programs provide working examples of ESQL COBOL program code that connects to DB2, Access, MySQL, and Oracle databases. The source files are located in the sample/acusql subdirectory where ACUCOBOL-GT is installed. A different directory is provided for each database. Program source files have the three-character suffix .sqb. For those using AcuBench, an AcuSQL demonstration program is included in the sample project Samprj.

The section Sample Programs, provides a description of five of these programs and uses them to highlight examples of SQL syntax. Acquaint yourself with these programs and, if you have the underlying middleware support, pre-compile, compile, and run them. The DB2 program requires a Windows-to-DB2 ODBC data connection; the Access and Oracle programs require an ODBC data source. The program code includes examples of how to establish connections and how to access and manipulate data.

Parent topic: Getting Started


Technical Services

For the latest information on contacting customer care support services go to:

http://www.microfocus.com/about/contact

For worldwide technical support information, visit:

http://supportline.microfocus.com/xmlloader.asp?type=home

Parent topic: Getting Started


Program Preparation

  • Preparing Your Programs
  • Coding Considerations
  • Data Division
  • Data Types
  • Procedure Division
  • SQL Verbs
  • Checking Syntax
  • Error Handling
  • Error Messages
  • Limits and Restrictions
  • Detecting and Handling NULL Values
Parent topic: AcuSQL Version 10.2.0 User's Guide


Preparing Your Programs

Preparing your ESQL source code for use with the pre-compiler is straightforward. All ESQL statement blocks must start with the keywords EXEC SQL and end with the keyword END-EXEC. The structure and syntax of the SQL statements within each code block should conform to the variant of SQL required by the target database.

Note that the pre-compiler mode used to perform syntax checking can create variability with respect to errors encountered at runtime and, therefore, should be taken into consideration when you prepare your source code. For example, if you direct the pre-compiler to pass ESQL statements to the database engine for syntax checking (provided that your ODBC driver supports the return of syntax errors), you will know exactly what is acceptable and unacceptable to the database engine. This method ensures that your SQL statements are syntactically correct when the source code successfully pre-compiles. If, instead, you use the pre-compiler’s relaxed syntax checking mode (by specifying the -Pr option at compile time), some of your ESQL statements will pass through the pre-compiler without any test against the syntax accepted by the target database, increasing the likelihood of undetected SQL syntax errors causing problems at run time. See Using AcuSQL as a Standalone Program for a description of the -Pr option.

Note: The AcuSQL® precompiler does not currently support any large object data types (LOBs). If your existing applications include LOBs, contact our Technical Service personnel for assistance in evaluating the steps you may need to take to make the best use of AcuSQL.
Note: This manual provides only a brief treatment of the rules and application of SQL and ESQL. It is up to the programmers to know SQL and ESQL and to have a comprehensive SQL/ESQL reference manual at their disposal. Programmers will benefit from studying the special provisions of ESQL because they offer some supports for the programmatic application of SQL that are not included in interactive SQL.

By default, the pre-compiler performs syntax checking for compliance with the ISO/ANSI SQL 92 standard. For complete information about pre-compiler options, see section Using the Pre-compiler.

Working with DB2 databases

If your program will access a DB2 database, your ESQL statements should conform to the IBM SQL standard described in IBM publication S10J-8158-00, Embedded SQL Programming Guide, Version 5. A reference level definition of IBM SQL is included in IBM publication S10J-8165, SQL Reference. When you pre-compile your program, specify the -Pk DB2 option to direct the pre-compiler to perform DB2-specific syntax checking, or use the -Pc option to have the DB2 engine perform direct validation.

Working with Microsoft SQL Server databases

If your program will access a Microsoft SQL Server database, specify the -Pk mssql option to direct the pre-compiler to perform SQL Server-specific syntax checking.

In order to accommodate SQL Server function syntax (db_name(), for example), AcuSQL also supports SELECT statements that do not include FROM … tablelist. Note that if this is the only SQL Server-specific syntax your program contains, you do not need to use the -Pk mssql option on your command line.

AcuSQL supports the following SQL Server syntax for embedded transactions:

  • BEGIN TRANSACTION name
  • COMMIT TRANSACTION name
  • ROLLBACK TRANSACTION name

The name will be passed to SQL Server as is, and must match the rules for embedded transaction names. For information on configuration variables supported by AcuSQL in a SQL Server environment, see section Runtime Configuration Variables for SQL Server. For additional information on running applications with AcuSQL in a SQL Server environment, see section Running Your Application with Microsoft SQL Server.

In addition, it is possible to nest transactions, as supported by SQL Server. When you use nested transactions, note how many transactions you BEGIN, because you must COMMIT the same number of transactions for the transaction to be considered complete. For example, if you execute three BEGIN TRANSACTION statements, you must later execute three COMMIT TRANSACTION or COMMIT WORK statements to commit the work you have done.

Note, however, that a single ROLLBACK rolls back all nested transactions. This behavior is a feature of SQL Server, and is not controlled by the AcuSQL interface.

Parent topic: Program Preparation


Coding Considerations

This help section describes several points to keep in mind as your write your ESQL program.

  • User-Supplied Object Names
  • Coding Area
  • Commas
  • String Delimiters
Parent topic: Program Preparation


User-Supplied Object Names

AcuSQL is case sensitive when reading the names of objects in SQL supplied by the user, such as connection names or cursor names. For example, AcuSQL reads mycursor, MyCursor, and MYCURSOR as the names of three different cursors. Therefore, be consistent in your use of uppercase and lowercase letters when referring to these objects.

Parent topic: Coding Considerations


Coding Area

Code EXEC SQL statements in columns 12 – 72 unless you are using Terminal mode input. You can indicate the format of a source file with the -Sa and -St compile options. See Using AcuSQL as a Standalone Program for more information on these options.

Parent topic: Coding Considerations


Commas

Use commas to separate list items in embedded SQL statements. For example:

EXEC SQL
    SELECT FIRST_NAME, LAST_NAME FROM EMPLOYEE
END-EXEC.
Parent topic: Coding Considerations


String Delimiters

To ensure the greatest portability of your SQL code, use single quotation marks around string constants in SQL.

EXEC SQL
     SELECT LAST_NAME INTO :LAST-NAME FROM EMPLOYEE
     WHERE LAST_NAME = 'SMITH'
END-EXEC.
Parent topic: Coding Considerations


Data Division

The following SQL statements are supported in the Data Division:

SQL DECLARE CURSOR
SQL INCLUDE
SQL declarations

For example:

EXEC SQL
    DECLARE cursorname CURSOR FOR SELECT statement
END_EXEC.
EXEC SQL INCLUDE SQLCA END-EXEC.
EXEC SQL INCLUDE SQLDA END-EXEC.
EXEC SQL INCLUDE filename END-EXEC.
EXEC SQL BEGIN DECLARE SECTION END-EXEC.
... SQL declarations
EXEC SQL END DECLARE SECTION END-EXEC.
  • Cursors
  • SQL INCLUDE files
  • Host Variables
Parent topic: Program Preparation


Cursors

You can define cursors in both the Data Division and the Procedure Division. Note that when cursors are defined in the Data Division, the period (.) after the END-EXEC keyword is optional. However, if you do include the period, it must appear on the same line as the END-EXEC keyword. Therefore, both of the following are acceptable syntax when a cursor is defined in the Data Division section.

EXEC SQL
    DECLARE COBCUR1 CURSOR FOR
        SELECT
            C_FIRST_NAME,
            C_LAST_NAME,
        FROM CUSTOMER
            WHERE C_NUMBER >= 'SMITH'
END-EXEC.
EXEC SQL
    DECLARE COBCUR1 CURSOR FOR
        SELECT
            C_FIRST_NAME,
            C_LAST_NAME,
        FROM CUSTOMER
            WHERE C_NUMBER >= 'SMITH'
END-EXEC

See Cursors for a brief introduction to cursors. Refer to any of the commercially available books on SQL for more complete details.

Parent topic: Data Division


SQL INCLUDE files

You can include files of terminal or ANSI format in your ESQL source by using the SQL INCLUDE statement.

The standard SQLCA and SQLDA INCLUDE files are built into the pre-compiler and are included whenever they are named in the source, as in:

* Include the SQL Communications Area (SQLCA)
  EXEC SQL INCLUDE SQLCA END-EXEC.

These files include specific adaptations for AcuSQL.

Note: Do not attempt to substitute other versions of these files.

User-defined INCLUDE files must begin with an SQL BEGIN DECLARE statement and end with an SQL END DECLARE statement if the code is to be used as ESQL code. Variables not within the BEGIN/END DECLARE cannot be used as host variables. They can still be used as local variables. See Host Variables for additional information.

In statements of the form:

EXEC SQL INCLUDE filename END-EXEC.

the compiler adds to filename the standard file extension for COBOL source files (the default is .cbl). To specify another extension, or to exclude an extension, filename must be enclosed in either single or double quotation marks. For example:

EXEC SQL INCLUDE 'SQLCOPYBOOK' END-EXEC.

If the user-defined INCLUDE files do not reside in the current directory, you must indicate where they’re located using the -Pi compiler option or ACUSQL_INCLUDE environment variable.

SQL Communications Area (SQLCA)

The SQLCA is a COBOL group item that is used to provide information to your ESQL/COBOL program. The SQLCA contains data items for error checking, warnings, and status information that is updated whenever an ESQL statement is executed. Your COBOL program can check this structure after each ESQL operation or in a centralized error-checking routine if you are using the WHENEVER directive in your application. See Checking Syntax and WHENEVER Directive for information on the WHENEVER directive.

The field most commonly used in the SQLCA group item is SQLCODE, which contains the status of the last statement executed. SQLCODE can contain the following values:

0 | The executed statement succeeded without an error or warning.
>0 | The executed statement succeeded, but there was a warning. Check the other fields in the SQLCA structure to determine the nature of the warning.
<0 | The executed statement encountered an error. Check the other fields in the SQLCA structure to determine the nature of the error.

If SQLCODE contains a non-zero value, your application can check the value of SQLERRMC for the text associated with the error or warning, and, when appropriate, display that text as an error message or warning.

SQL Descriptor Area (SQLDA)

The SQLDA is a COBOL group item used in performing dynamic SQL operations. SQLDA is used to store information about the input and output variables of dynamically prepared SQL statements.

Parent topic: Data Division


Host Variables

Host variables are the key to communication in an ESQL application. These are data items in Working-Storage that are made available to ESQL for communicating information to and from the database. Put another way, host variables can provide input to your ESQL program and the program can return information to host variables.

Host variables are standard COBOL Working-Storage items that are enclosed by BEGIN/END DECLARE statements. For example:

EXEC SQL BEGIN DECLARE SECTION END-EXEC.
01 EMPLOYEE-NAME.
   03 FIRST-NAME                 PIC X(20).
   03 LAST-NAME                  PIC X(20).
EXEC SQL END DECLARE SECTION END-EXEC.

This makes the variables FIRST-NAME and LAST-NAME available to the AcuSQL pre-compiler. When these variables are used in the Procedure Division in an SQL statement, they must be preceded by a colon (:). This differentiates host variables from local data objects with the same name. If you are using the variables in COBOL operations (rather than SQL operations), the colon should not be used. The pre-compiler recognizes COBOL variables only if they have been declared in an SQL BEGIN DECLARE section. See Host Variables for a further discussion of host variables.

Parent topic: Data Division


Data Types

To ensure proper and accurate data matches between the data source and your COBOL program, you must match the SQL data type in your source code with the appropriate COBOL data type. Note that only fixed-length and variable-length character strings are supported (LOB-type data is not supported). This help section describes the data type compatibility between AcuSQL and DB2, Microsoft SQL Server, Microsoft Access, and MySQL.

  • DB2 Data Type Compatibility
  • Microsoft SQL Server Data Type Compatibility
  • Access Data Type Compatibility
  • MySQL Data Type Compatibility
Parent topic: Program Preparation


DB2 Data Type Compatibility

The following table describes data type compatibility for DB2.

SQL Type | COBOL Type | Description
CHAR | 01 name PIC X(n) | Fixed-length character string
DATE | 01 name PIC X(10) | 10-byte character string
DECIMAL | 01 name PIC S9(M) V9(N) COMP-3. | Packed decimal (where m = p - n)
DOUBLE | 01 name USAGE IS DOUBLE. | Double-precision floating point
INTEGER | 01 name PIC S9(9) COMP-5. | 32-bit signed integer
LONG VARCHAR(n) | 01 name. 49 name-length PIC S9(4) COMP-5. 49 name-name PIC X(n). | Variable-length character string
REAL | 01 name PIC S9(4) USAGE IS COMP-1. | Single-precision floating point
TIME | 01 name PIC X(8). | 8-byte character string
TIMESTAMP | 01 name PIC X(26). | 26-byte character string
VARCHAR(n)* | 01 name. 49 name-length PIC S9(4) COMP-5. 49 name-name PIC X(n). | Variable-length character string (n <= 4000)

* To be treated as a VARCHAR, the elementary items in a group item consisting of only a numeric item and a character item need to be level 49 as in the following:

01 my-record.
   49  my-number 	pic s9(3) comp-5.
   49  my-name 			pic x(20).
Parent topic: Data Types


Microsoft SQL Server Data Type Compatibility

The following table describes data type compatibility for SQL Server.

SQL Type | COBOL Type | Description
CHAR(n)* | 01 name PIC X(n) . | Fixed-length character string
DATETIME | 01 name PIC X(25) . | 25-byte character string
DECIMAL(p,n) | 01 name PIC S9(m)V9(n) COMP-3 . | Packed decimal (where m = p - n)
DOUBLE PRECISION | 01 name USAGE IS DOUBLE. | Double-precision floating point
INTEGER | 01 name PIC S9(9) COMP-5. | 32-bit signed integer
REAL | 01 name PIC S9(4) USAGE IS COMP-1. | Single-precision floating point
SMALLINT | 01 name PIC S9(4) COMP-5. | 16-bit signed integer
VARCHAR(n)** | 01 name. 49 name-length PIC S9(4) COMP-5. 49 name-name PIC X(n). | Variable-length character string (n <= 4000)
DATETIME | 01 name PIC X(24). | 8-character string

* To be treated as a VARCHAR, the elementary items in a group item consisting of only a numeric item and a character item need to be level 49 as in the following:

01 my-record.
   49  my-number 	pic s9(3) comp-5.
   49  my-name 			pic x(20).
Parent topic: Data Types


Access Data Type Compatibility

The following table describes data type compatibility for Microsoft Access and AcuSQL.

SQL Type | COBOL Type | Description
CHAR(n) | 01 name PIC X(n) . | Fixed-length character string
DOUBLE PRECISION | 01 name USAGE IS DOUBLE. | Double-precision floating point
INTEGER | 01 name PIC S9(8) COMP-5. | 32-bit signed integer
SMALLINT | 01 name PIC S9(3) COMP-5. | 16-bit signed integer
VARCHAR(n)* | 01 name. 49 name-length PIC s9(4) COMP-5. 49 name-name PIC X(n). | Variable-length character string (n <= 4000)

* To be treated as a VARCHAR, the elementary items in a group item consisting of only a numeric item and a character item need to be level 49 as in the following:

01 my-record.
   49 my-number 	pic s9(3) comp-5.
   49 my-name 			pic x(20).
Parent topic: Data Types


MySQL Data Type Compatibility

The following table describes data type compatibility for MySQL and AcuSQL.

SQL Type | COBOL Type | Description
CHAR (n) | 01 name PIC X(n) . | Fixed-length character string n <= 255
VARCHAR(n) | 01 name. 49 name-length PIC S9(4) COMP-5. 49 name-name PIC X(n). | Variable-length character string (n <= 255). Sub-items should be level 49.
TINYINT | PIC 9(04) / PIC 9(02). * | 1 byte -128 to +127
SMALLINT | PIC 9(09) / PIC 9(04). * | 2 bytes -32768 to +32767
MEDIUMINT | PIC 9(09) / PIC 9(06). * | 3 bytes -8388608 to +8388607
INTEGER (INT) | PIC 9(10) / PIC 9(09). * | 4 bytes -2147483648 to+2147483647
FLOAT | 01 name USAGE IS FLOAT. | 4-byte field
DOUBLE | 01 name USAGE IS DOUBLE. | 8-byte field
DECIMAL(p,n) | 01 name PIC S9(m)V9(n). | Numeric where m = p - n and p denotes the precision (in digits).
DATE | 01 name PIC X(10) | Format is YYYY-MM-DD
TIME | 01 name PIC X(8) or X(14) | Format HH:MM:SS or HHHH:MM:SS range -839:59:59 to 838:59:59
DATETIME | 01 name PIC X(19) | Format is YYYY-MM-DD HH:MM:SS (space between day and hour) Range 1000-01-01 00:00:00 to 9999-12-31 23:59:59
TIMESTAMP | 01 name PIC X(19) | 26-byte character string

* For numeric fields, unless the COBOL program is compiled with the -Dz option, the number will be truncated based on the number of 9’s in the picture clause. For maximum compatibility, use the larger picture size.

Note: Database and table names in MySQL are case-sensitive. Column names are not. There are multiple possible engines with MySQL.
Parent topic: Data Types


Procedure Division

AcuSQL supports many SQL programming concepts and techniques. Several of the these areas are described in this help section.

  • Cursors
  • Rowset Functions
  • Stored Procedures
Parent topic: Program Preparation


Cursors

Cursors are defined in the Procedure Division or in the Data Division. For example:

EXEC SQL DECLARE MYCURSOR CURSOR FOR
   SELECT FIRST_NAME, LAST_NAME
   FROM TEST_TABLE
END-EXEC.

AcuSQL also supports the declaration of scroll cursors, and the use of the following FETCH extensions:

Extension | Use
FETCH FIRST | Returns the first row of query results.
FETCH LAST | Returns the last row of query results.
FETCH PRIOR | Returns the row immediately preceding the current curser row.
FETCH NEXT | Returns the row immediately following the current curser row.
FETCH ABSOLUTE | Returns a specific row identified by a constant or host variable*.
FETCH RELATIVE | Moves the cursor forward or backward a specified number of times from its current position.

* If specifying a row position through a host variable, the host variable does not need to be declared in the DECLARE section of working-storage, and can be any numeric working-storage variable.

See Cursors for a brief introduction to cursors. Refer to any of the commercially available books on SQL for more complete details.

Parent topic: Procedure Division


Rowset Functions

The AcuSQL pre-processor allows for the use of Rowset functions. Microsoft SQL Server includes several built-in rowset functions, and also allows users to define their own rowset functions.

Refer to the Microsoft SQL Server documentation for information about using and creating rowset functions.

Parent topic: Procedure Division


Stored Procedures

If using Microsoft SQL Server, stored procedures can be called via embedded SQL. Some restrictions apply. See Restrictions for more information.

Generally, you can execute two types of stored procedures: those that return no result sets, and those that return a single result set. If you execute stored \procedures that return more than one result, the results are not available to the COBOL program. AcuSQL does support output parameters and return code values, however.

Consider the following stored procedure that has one output parameter and also returns a value:

create procedure sp_listcustomer
    @lastname varchar(100) = NULL,
    @numrows int output
    as
select @numrows = count(*) from customer where c_last_name = @lastname
select c_last_name, c_first_name, c_birthday from customer
    where c_last_name = @lastname
return 23

This stored procedure returns a single result set (c_last_name, c_first_name, and c_birthday). Depending on the rows in the customer table, this can consist of many rows.

There are two ways to execute this procedure from a COBOL program:

  1. Ignore the result sets, and just use the output parameters and return code.

    This can be done with the following code:

    display "Enter the name to search for: ", no.
accept c-last-name.
EXEC SQL exec :ret-code = exec sp_listcustomer
(:c-last-name, :num-rows out)
END-EXEC.

    Note that c-last-name, ret-code, and num-rows need to have been declared as valid variables in a DECLARE section. When executed this way, all the rows returned by the stored procedure are thrown away, and only the num-rows variable and the ret-code variable are changed. ret-code will be the value 23 (based on the return 23 in the stored procedure)and num-rows will be the number of rows that match the

    WHERE.

  2. Have the result set returned to the COBOL program. This requires a cursor to be declared, and is done with the following code:

    display "Enter the name to search for: ", no.
accept c-last-name.
EXEC SQL declare spcursor cursor for
        :ret-code = exec sp_listcustomer (:c-last-name,
         :num-rows out)
END-EXEC.

EXEC SQL
    open spcursor
END-EXEC.

move 0 to num-rows-read.
perform until SQLCODE not = 0
    EXEC SQL
        FETCH spcursor into
         :c-last-name, :c-first-name,
         :c-birthday
    END-EXEC
    if SQLCODE = 0
        add 1 to num-rows-read
        display c-last-name, ", ", c-first-name, ", ",
               c-birthday
    end-if
end-perform.
if num-rows not = num-rows-read
    display "stored procedure error, " num-rows,
            " not = ", num-rows-read
end-if.

    Note that c-last-name, ret-code, num-rows, c-first-name, and c-birthday need to have been declared as valid variables in a DECLARE section. When executed this way, the num-rows and ret-code variables are set to the values given by the stored procedure at the time the cursor is opened. You must then execute FETCH commands in order to get the result set columns. This particular example tests the number of rows actually fetched against the num-rows value returned by the stored procedure.

    There are two types of syntax allowed by the precompiler when MSSQL syntax is in effect (that is, when you specify the -Pk mssql option).

    EXEC SQL [:status-var = ] EXEC procedure-name
[[:param-var [out[put]]],...]

    and

    EXEC SQL DECLARE cursor-name CURSOR FOR
[:status-var = ] EXEC procedure-name [[:param-var
[out[put]]], ...]

    The second form requires all the usual steps necessary for cursors: you must open the cursor and then fetch from it until all the rows have been fetched.

    Any output parameters, including the return value, are not returned to the COBOL program until an UNPREPARE or CLOSE (for cursors) is executed.

  • Restrictions
Parent topic: Procedure Division


Restrictions

The stored procedures you execute must return no result sets or one result set. Stored procedures that return multiple result sets will execute, but all result sets except the first are thrown away.

The connection used when getting result sets from a stored procedure is not available for any other processing while the cursor is open. In other words, if you need to execute other SQL statements based on information from a stored procedure, you must open multiple connections to the database.

Parent topic: Stored Procedures


SQL Verbs

In embedded SQL applications, two of the most vital SQL verbs are CONNECT and DISCONNECT. These are the commands that open and close communication between your application and your data source. Your data source vendor most likely recommends the CONNECT and DISCONNECT syntax to access the data source. When accessing your data source through AcuSQL, however, you should use the CONNECT and DISCONNECT syntax described below instead of the syntax recommended for your data source.

With AcuSQL, SQL data can be read (using the SELECT or FETCH statement) or written to (using the INSERT statement). Most other SQL verbs are supported as well, including, but not limited to, DELETE and UPDATE. While it is not within the scope of this document to explain these standard SQL verbs, brief introductions are provided in Sample Programs. In order to understand which SQL features your database supports, be sure to work with a knowledgeable database administrator.

  • CONNECT Statement
  • DISCONNECT Statement
Parent topic: Program Preparation


CONNECT Statement

When connecting to an SQL data source through AcuSQL, use the following syntax for the CONNECT statement:

CONNECT TO server-name [AS connection-name] [USER userid USING passwd]

server-name, connection-name, and userid are alphanumeric literals or host variables defined in an ESQL DECLARE section of Working-Storage. Note that you must place a colon (“:”) before the host variable in the SQL statement.

passwd is a variable-length character string (VARCHAR, in DB2). Note that leading and trailing spaces are not stripped.

The CONNECTION statement attempts to establish a connection with server-name as user userid. The AS connection-name clause assigns the specified name to the connection. This is especially desirable when you want to establish multiple connections.

Example

CONNECT TO big-data AS con1 USER :uid USING :pwd

Note that big-data and con1 are alphanumeric literals. uid and pwd are host variables. A colon must precede host variables (“:”). See the sample programs for a working example

To use Windows authentication when connecting to SQL Server, omit the USER and USING phrases.

Parent topic: SQL Verbs


DISCONNECT Statement

When disconnecting from an SQL data source through AcuSQL, use the following syntax for the SQL DISCONNECT statement.

DISCONNECT { CURRENT | ALL | connection-name }
CONNECT RESET

connection-name is an alphanumeric literal or host variable defined in an ESQL DECLARE section of Working-Storage. Note that you must place a colon (“:”) before the host variable in the statement.

DISCONNECT closes the current connection, connection-name, or all connections. DISCONNECT CURRENT and CONNECT RESET cause the current connection to be closed. When the current connection is closed the value of current connection remains empty. You must use SET CONNECTION to set a new current connection.

Parent topic: SQL Verbs


Checking Syntax

The pre-compiler supports both relaxed and strict syntax checking. You indicate relaxed checking with the -Pr command line option, strict checking by not including this option. See Using AcuSQL as a Standalone Program for information on the -Pr option. These choices operate on the entire source code file.

However, you may prefer to exercise strict checking in some parts of your program and relaxed checking in others. You can indicate the mode of syntax checking by indicating Relaxed or Strict with your EXEC ESQL command.

For example,

EXEC SQL RELAXED
    DECLARE COBCUR1 FOR
    SELECT
        C_NUMBER, C_NAME, TO_CHAR(C_BIRTHDAY, 'DD-MM-YY'), C_INFO
        FROM CUSTOMER
        WHERE C_NUMBER >= :C_NUMBER
END-EXEC.

or

EXEC SQL STRICT
    DECLARE COBCUR1 FOR
        SELECT
            C_NUMBER, C_NAME, TO_CHAR(C_BIRTHDAY, 'DD-MM-YY'), C_INFO
        FROM CUSTOMER
        WHERE C_NUMBER >= :C_NUMBER
END-EXEC.

See Working With More Than One Row – select3.sqb for a description of this code.

Note that you cannot indicate Relaxed or Strict in the following instances:

  • EXEC SQL BEGIN DECLARE SECTION
  • EXEC SQL END DECLARE SECTION
  • EXEC SQL INCLUDE
Parent topic: Program Preparation


Error Handling

To strengthen error handling, you should consider embedding the SQL WHENEVER directive in your source code. The WHENEVER directive is used to direct program logic when the application encounters a warning or an error. You can choose to ignore errors or redirect them with WHENEVER.

The default behavior of AcuSQL is to attempt to ignore warnings and error conditions, and continue processing, if possible. Your application can either explicitly check error conditions or, for more automatic error processing, use the WHENEVER directive. Your application can contain more than one WHENEVER directive. A WHENEVER directive applies to all embedded ESQL statements that follow it, until it is superseded by another WHENEVER directive.

Use the WHENEVER directive to specify what actions the program takes when it encounters one of the following conditions:

  • SQLERROR
  • SQLWARNING
  • NOT FOUND. This condition applies only to SELECT and FETCH statements.

Specify one of the following actions when an error condition occurs:

  • CONTINUE – control passes to the next statement
  • PERFORM paragraph_name – the program performs paragraph_name and then returns to read the next statement.
  • GOTO paragraph_name – the program branches to paragraph_name, a specified procedure in the program. Flow of the program continues down this branch.
  • STOP

Syntax

EXEC SQL WHENEVER {SQLERROR}   | {CONTINUE}
                  {SQLWARNING} | {PERFORM paragraph}
                  {NOT FOUND}  | {GO TO paragraph}
                               | {STOP}

where paragraph is a specified procedure in the program.

See WHENEVER Directive for an example of the WHENEVER directive.

Parent topic: Program Preparation


Error Messages

The SQLCA can accommodate only 70 characters of error information in the error message field. Generally, this is not enough for a useful error message. See SQL INCLUDE files for additional information on this required file.

SQL Server Environments

In Microsoft SQL Server environments, the external variable F-ERRMSG is set to the full text of the error message returned to accommodate error messages longer than 70 characters.

F-ERRMSG is an external variable of USAGE POINTER that must be manipulated in order to see its contents. The following code demonstrates how to see the contents of the error message string:

01 f-errmsg         usage pointer external.
01 my-errmsg        pic x(512).

....
0000-START.
    EXEC SQL WHENEVER SQLERROR GO TO ERROR-EXIT END-EXEC.
....
ERROR-EXIT.
  EXEC SQL WHENEVER SQLERROR CONTINUE END-EXEC.
    DISPLAY "SQL ERROR: SQLCODE " SQLCODE
    DISPLAY " SQLSTATE " SQLSTATE
    DISPLAY SQLERRMC
    call "c$memcpy" using my-errmsg, by value f-errmsg, 512.
      display my-errmsg
    ACCEPT OMITTED
   STOP RUN.

where

f-errmsg is an external variable that contains the full text of the error message.

my-errmsg is the full text of the error message, which in this case can contain up to 512 bytes.

See the ACUCOBOL-GT Reference Manual for information on C$MEMCPY and USAGE POINTER.

Parent topic: Program Preparation


Limits and Restrictions

AcuSQL does not currently support any large object data types (LOBs). If your existing applications include LOBs, contact our Technical Services department for help evaluating the steps you need to take in order to use AcuSQL.

In addition, AcuSQL does not currently support compound SQL statements. For this reason, statements of the form:

EXEC SQL
     DROP TABLE table-name1
     DROP TABLE table-name2
END-EXEC

should be broken into single statements of the form:

EXEC SQL
     DROP TABLE table-name1
END-EXEC
EXEC SQL
     DROP TABLE table-name2
END-EXEC

Likewise, DCLGEN generated code must be split into data and procedure section files, and FILLER cannot be used as a group item.

Aside from these restrictions, you need to be aware that different databases react differently to SQL commands. For instance, during transaction management, Access performs an SQL COMMIT after a DROP TABLE, but DB2 does not. In order to discover the limits and restrictions of your database, talk with a knowledgeable database administrator.

Parent topic: Program Preparation


Detecting and Handling NULL Values

Many SQL-conversant data sources allow a NULL (empty) value in a data field. COBOL and ACUCOBOL-GT do not recognize or support the NULL value. When the value of a field returned from a query is NULL, the contents of the bound variable are undefined. As a result, the ESQL programmer must make provisions for detecting and handling NULL when it is retrieved from or must be stored in the database.

To identify a NULL value, ESQL offers the indicator variable. The indicator variable is a host variable that is used for the special purpose of indicating whether the value of a field is NULL or some other value. In the COBOL program, indicator variables are declared in an SQL DECLARE section of Working-Storage (the same as other host variables). Indicator variables take the form:

01 indicator_name pic s9(5) usage comp-5.

where indicator_name is a user-defined name such as “myind” (used in the example below).

In an ESQL statement, the indicator variable is paired with the bound variable and together they indicate a value. In the ESQL statement, the indicator variable immediately follows the bound variable and must be preceded with a colon (“:”). The ESQL reserved word indicator is optional. For example:

exec sql fetch next from mytable into :myfield indicator :myind ...

The value of the indicator valuable is checked to determine if the value of the field is NULL or some other value. Note that there are no commas between the variable and the indicator.

For input variables, such as those found in an INSERT or UPDATE statement:

If the value of the indicator variable is ... | Then ...
-1 | AcuSQL attempts to set the value of the column to NULL.
>=0 | AcuSQL attempts to set the value of the column to that of the host variable, or to the number that appears. This behavior is database dependent. It is recommend that you test your data source to understand the values that are returned.

For output variables, such as those found in SELECT statements:

If the value of the indicator variable is ... | Then ...
-1 | The selected column’s value is NULL.
0 | The column’s value is assigned to the host variable.
>0 | The column’s value is assigned to the host variable, but that value is truncated. The indicator variable is set to the number of characters read by the program.

Consult the ESQL documentation of your SQL reference manual for more information about the use of the indicator variable and the handling of NULL values.

Parent topic: Program Preparation


Pre-compiler Function and Use

  • The ESQL Translation Process
  • Using the Pre-compiler
  • Environment Variables
  • Pre-compilation Errors
Parent topic: AcuSQL Version 10.2.0 User's Guide


The ESQL Translation Process

The AcuSQL® pre-compiler identifies and translates ESQL statements into COBOL statements. It begins its work in the program's Data Division. The pre-compiler identifies ESQL statements by searching for the keywords EXEC SQL and END-EXEC in the source code. When it finds these markers, it encapsulates them with comments and line numbers and then parses and generates COBOL code, including CALLs to the AcuSQL library.

For example, if your code specifies an include file such as:

EXEC SQL INCLUDE SQLCA END-EXEC.

This line is translated into:

*(( PREPROC ACUSQL LINE BEGIN 12 ))
   01  SQLCA IS EXTERNAL.
       05  SQLCAID                PIC X(8).
       05  SQLCABC         COMP-5 PIC S9(9).
       05  SQLCODE         COMP-5 PIC S9(9).
       05  SQLERRM.
           10  SQLERRML    COMP-5 PIC S9(4).
           10  SQLERRMC           PIC X(70).
       05  SQLERRP                PIC X(8).
       05  SQLERRD OCCURS 6 TIMES COMP-5 PIC S9(9).
       05  SQLWARN.
           10  SQLWARN0           PIC X.
           10  SQLWARN1           PIC X.
           10  SQLWARN2           PIC X.
           10  SQLWARN3           PIC X.
           10  SQLWARN4           PIC X.
           10  SQLWARN5           PIC X.
           10  SQLWARN6           PIC X.
           10  SQLWARN7           PIC X.
           10  SQLWARN8           PIC X.
           10  SQLWARN9           PIC X.
           10  SQLWARNA           PIC X.
       05  SQLSTATE               PIC X(5).
       05  SQLERRM-PREFIX.
           10  SQLERRPL    COMP-5 PIC S9(4).
           10  SQLERRPC           PIC X(70)
*EXEC SQL INCLUDE SQLCA END-EXEC.
*(( PREPROC ACUSQL LINE END 12 ))
           .

The following ESQL statement:

EXEC SQL
    SELECT MIN(C_NUMBER)
        INTO :MIN-C-NUMBER
        FROM CUSTOMER
END-EXEC.

is translated into:

*(( PREPROC ACUSQL LINE BEGIN 41 ))
           PERFORM CALL "SQL$START" END-CALL CALL "SQL$PREPARE" USING 'S
      -    'QLISTM' "SELECT MIN(C_NUMBER) FROM CUSTOMER " END-CALL IF SQ
      -    LCODE OF SQLCA < 0 THEN GO TO Error-Exit END-IF CALL "SQL$BIN
      -    "DCOLUMN" USING 'SQLISTM' 1 MIN-C-NUMBER   END-CALL IF SQLCOD
      -    E OF SQLCA < 0 THEN GO TO Error-Exit END-IF CALL "SQL$CURSOR"
            USING 'SQLICUR' 'SQLISTM' IF SQLCODE OF SQLCA < 0 THEN GO TO
            Error-Exit END-IF CALL "SQL$OPEN" USING 'SQLICUR' IF SQLCODE
            OF SQLCA < 0 THEN GO TO Error-Exit END-IF CALL "SQL$FETCH" U
      -    SING 1 0 'SQLICUR' IF SQLCODE OF SQLCA < 0 THEN GO TO Error-E
      -    xit END-IF CALL "SQL$CLOSE" USING 'SQLICUR' IF SQLCODE OF SQL
      -    CA < 0 THEN GO TO Error-Exit END-IF CALL "SQL$UNPREPARE" USIN
      -    G 'SQLISTM'  END-CALL END-PERFORM
      *    EXEC SQL
      *        SELECT MIN(C_NUMBER)
      *            INTO :MIN-C-NUMBER
      *            FROM CUSTOMER
      *    END-EXEC.
      *(( PREPROC ACUSQL LINE END 45 ))
           .

The pre-compiler generates a standard 72-character line without regard for the end of statements or other formatting considerations.

The line numbers that appear in the comment lines specify the original line numbers in the input file.

Note: The precise results of these translations may vary depending on your version of the pre-compiler.
Parent topic: Pre-compiler Function and Use


Using the Pre-compiler

The ACUSQL pre-compiler offers three modes of SQL syntax checking.

  • The first mode, specified with the -Pk switch, uses internal reserved word lists and syntax rules to check IBM DB2 SQL, Transact-SQL, or ISO/ANSI SQL 92.
  • The second mode, called relaxed mode, is enabled with the -Pr switch and provides only minimal syntax checking. It is intended for use with unspecified SQL variants.
  • The third mode establishes a direct connection to the target database engine and uses the engine to directly check the syntax. This option is specified with the Pc switch. Note that for this mode to be effective, your ODBC API middleware must support the return of syntax error messages (not all ODBC drivers do). Also note that during syntax verification it is possible that some error messages will be converted to warning messages. This is done, when possible, to prevent the compiler from aborting so that syntax checking can continue. The text of the warning message preserves the text of the error message.

These modes operate on the file as a whole. See Checking Syntax for information on indicating relaxed or strict checking for individual EXEC SQL commands.

When the pre-compiler starts, it examines the source file to determine whether it is in ANSI or terminal format and then processes the file accordingly. If the file is in ANSI format, the pre-compiler removes characters from columns 1-6 and 72-80, replacing them with spaces. Information contained in these columns may not appear in the ACUCOBOL-GT compilation listing file.

You can start and use the AcuSQL pre-compiler in several ways:

  • From AcuBench
  • As a standalone program from the command line
  • From the compiler command line
  • Using AcuSQL From Within AcuBench
  • Using AcuSQL as a Standalone Program
  • Using AcuSQL from the Compiler
Parent topic: Pre-compiler Function and Use


Using AcuSQL From Within AcuBench

Using AcuSQL within AcuBench is easy. Simply set the -Ps pre-compiler option (and any other desired options) in the File Compiler Options dialog box whenever you add an ESQL source file to the project. Thereafter, AcuBench automatically pre-compiles the file every time the project is built or the file is compiled.

Pre-compiler options, such as -Pe, are set in the File Compiler Options dialog box. To open the File Compiler Options dialog box, right-click the ESQL file in the Source tab and select Program Compile Options from the menu. In the Catalog drop-down list of the File Compiler Options dialog box, select Pre-compiler from the list.

Pre-compiler options are identified on the command line by the -Px flag. Pre-compiler options are described in Using AcuSQL from the Compiler.

If your ESQL files have a unique file suffix, such as .sqb (a suffix used by many IBM ESQL developers), you will want to add that suffix to the Source tab properties so that your ESQL files will automatically be included in the Source tab. To modify the Source tab properties, right click the Source tab and select Properties from the pop-up menu. Add the suffix to the list in the Extension names entry field. Note that a semicolon separates each suffix except the last one.

ESQL files, like all COBOL source files, can be opened into the Code Editor by double-clicking the file name in the Source tab or by right-clicking the file icon and selecting View code from the pop-up menu.

Parent topic: Using the Pre-compiler


Using AcuSQL as a Standalone Program

You can run the AcuSQL pre-compiler from the command line as a standalone program or you can run it through the ACUCOBOL-GT compiler. Running the pre-compiler as a standalone gives you access to more pre-processor options, however, certain situations may require you to run AcuSQL from the main compiler. In particular, if you want to pre-process ESQL inside of copy files, you need to run AcuSQL from the compiler since the copy files must first be located by the compiler.

To start the pre-compiler from the command line, use the following syntax:

acusql [options] input_filename

This causes ACUCOBOL-GT to pre-compile and compile the specified source file. The following additional options affect pre-compiler behavior:

-Pc Directs the pre-compiler to connect to and use the database engine to perform SQL syntax checking. This switch should be used in conjunction with the Pd, Pu, and Pp switches; with the environment variables ACUSQL_DATASET, ACUSQL_USER, and ACUSQL_PASSWORD; or with some combination of switches and environment variables. Values given on the command line take precedence over values held by environment variables.

Note that during syntax verification, in some cases an error message may be converted to a warning message in order to prevent the compiler from aborting. The text of the warning message preserves the text of the error message.

-Pd dataset | Is used in conjunction with the -Pc option and must be followed by the name of the ODBC data source to use.
-Pe*

*(see special note at the end of this list)

Includes ESQL lines in a listing or in the debugger. If you want to see the preprocessed output, use -Pe and include a source listing by using -Lf.
-Pi dir | Specifies the path that the pre-compiler will search to locate files named in SQL INCLUDE statements. For example -Pi c:\SQL\include\ causes the pre-compiler to look in the C:\SQL\include directory for files named in SQL INCLUDE statements. You can also specify a search path via the ACUSQL_INCLUDE environment variable. Note that -Pi takes precedence over ACUSQL_INCLUDE when both are used. See Environment Variables for more information.
-Pk rlist Directs the pre-compiler to use the designated reserved word set for syntax checking. rlist can be "DB2", to use the DB2 word set, "MSSQL" to use the Microsoft SQL Server word set, or "EXT", to use the extended reserved word set. "EXT" is the default.
Note: The syntax of the ALTER, CREATE, and GRANT statements is not checked by either the Pr or Pk rlist modes. These statements are checked only when you use the -Pc mode to connect directly to the database engine.
-Po | use output-file for prepocessed output
-Pp password | Is used in conjunction with the -Pc option and must be followed by the password that matches the username specified by the -Pu switch or by the ACUSQL_USER environment variable.
-Pr Directs the pre-compiler to perform relaxed syntax checking. -Pr is intended for use in situations where the embedded SQL syntax does not conform to IBM SQL, Transact-SQL, or SQL92, but is correct for the database that you want to access.

Pr does not perform syntax checking on the following statements:

SELECT INTO FROM
VALUES
DELETE
INSERT
DECLARE CURSOR FOR SELECT
UPDATE
Note:  The syntax of the ALTER, CREATE, and GRANT statements is not checked by either the "Pr" or "Pk rlist" modes.  These statements are checked only when you use the "-Pc" mode to connect directly to the database engine.
-Pu username | Is used in conjunction with the -Pc option and must be followed by the username of an authorized database user.
-Pv | Causes the compiler to treat group items as they were treated in releases earlier than Version 6.2; that is, group items containing both a numeric item and a character item only do not need to be level 49 to be treated as a VARCHAR. See Data Types for more information.
-Pw | Causes the pre-compiler to dump the current reserved word list to standard output (use the -Pk option to set the reserved word list). No pre-compilation or compilation is performed. Note that Pw should not be used with any other pre-compiler switches. In AcuBench, Pw must be specified in the Additional options entry field at the top-right of the File Compiler Options dialog box.
-St | Source is in terminal format
-Sa | Source is in ANSI format
Note: Previous versions of the compiler accepted -Po filename, which enables you to view the pre-processed output. The compiler no longer accepts -Po, however, it is allowed if running AcuSQL as a standalone program. If you are running AcuSQL from the compiler and want to view the pre-processed output, use -Pe as described above.
Parent topic: Using the Pre-compiler


Using AcuSQL from the Compiler

Use the -Ps compiler switch, and specify the source file you wish to pre-process. For example:

ccbl -Ps [options] input_filename

The following options are available to modify how AcuSQL executes from the compiler.

-Pc Directs the pre-compiler to connect to and use the database engine to perform SQL syntax checking. This switch should be used in conjunction with the Pd, Pu, and Pp switches; with the environment variables ACUSQL_DATASET, ACUSQL_USER, and ACUSQL_PASSWORD; or with some combination of switches and environment variables. Values given on the command line take precedence over values held by environment variables.

Note that during syntax verification, in some cases an error message may be converted to a warning message in order to prevent the compiler from aborting. The text of the warning message preserves the text of the error message.

-Pd dataset | Is used in conjunction with the -Pc option and must be followed by the name of the ODBC data source to use.
-Pe*

*(see special note at the end of this list)

Includes ESQL lines in a listing or in the debugger. If you want to see the preprocessed output, use -Pe and include a source listing by using -Lf.
-Pi dir | Specifies the path that the pre-compiler will search to locate files named in SQL INCLUDE statements. For example -Pi c:\SQL\include\ causes the pre-compiler to look in the C:\SQL\include directory for files named in SQL INCLUDE statements. You can also specify a search path via the ACUSQL_INCLUDE environment variable. Note that -Pi takes precedence over ACUSQL_INCLUDE when both are used. See Environment Variables for more information.
-Pk rlist Directs the pre-compiler to use the designated reserved word set for syntax checking. rlist can be DB2, to use the DB2 word set, "MSSQL" to use the Microsoft SQL Server word set, or EXT, to use the extended reserved word set. EXT is the default.

Note: The syntax of the ALTER, CREATE, and GRANT statements is not checked by either the Pr or Pk rlist modes. These statements are checked only when you use the -Pc mode to connect directly to the database engine.

-Pp password | Is used in conjunction with the -Pc option and must be followed by the password that matches the username specified by the -Pu switch or by the ACUSQL_USER environment variable.
-Pr Directs the pre-compiler to perform relaxed syntax checking. -Pr is intended for use in situations where the embedded SQL syntax does not conform to IBM SQL, Transact-SQL, or SQL92, but is correct for the database that you want to access.

Pr does not perform syntax checking on the following statements:

SELECT INTO FROM
VALUES
DELETE
INSERT
DECLARE CURSOR FOR SELECT
UPDATE
Note: The syntax of the ALTER, CREATE, and GRANT statements is not checked by either the Pr or Pk rlist modes. These statements are checked only when you use the -Pc mode to connect directly to the database engine.
-Pu username | Is used in conjunction with the -Pc option and must be followed by the username of an authorized database user.
-Pv | Causes the compiler to treat group items as they were treated in releases earlier than Version 6.2; that is, group items containing both a numeric item and a character item only do not need to be level 49 to be treated as a VARCHAR. See Data Types for more information.
-Pw | Causes the pre-compiler to dump the current reserved word list to standard output (use the -Pk option to set the reserved word list). No pre-compilation or compilation is performed. Note that Pw should not be used with any other pre-compiler switches. In AcuBench, Pw must be specified in the Additional options entry field at the top-right of the File Compiler Options dialog box.
Note: Previous versions of the compiler accepted -Po filename, which enables you to view the pre-processed output. The compiler no longer accepts -Po, however, it is allowed if running AcuSQL as a standalone program. If you are running AcuSQL from the compiler and want to view the pre-processed output, use -Pe as described above.
Parent topic: Using the Pre-compiler


Environment Variables

The following variables can be used to control the way AcuSQL accesses your data source. They can be set at the system/environment level or they can be specified in a runtime configuration file.

  • ACUSQL_DATASET
  • ACUSQL_INCLUDE
  • ACUSQL_PASSWORD
  • ACUSQL_USER
Parent topic: Pre-compiler Function and Use


ACUSQL_DATASET

The ACUSQL_DATASET environment variable is used in conjunction with the -Pc pre-compiler switch (-Pc directs the pre-compiler to connect to the target database engine to perform syntax checking). ACUSQL_DATASET should be assigned the name of the ODBC data source to use. (Windows users refer to this value as the User DSN.)

Parent topic: Environment Variables


ACUSQL_INCLUDE

The ACUSQL_INCLUDE environment variable can be used in place of the -Pi option to specify multiple search directories for SQL INCLUDE files. ACUSQL_INCLUDE is defined in the environment. Directories are searched in the order specified, first to last. A semicolon (";") is used after each path except the last one. For example, to set ACUSQL_INCLUDE to search the current directory, the directory C:\SQL\LIBRARY, and the directory C:\COBOL\ESQL\LIBRARY, you would execute the following statement in the DOS shell or in "autoexec.bat":

SET ACUSQL_INCLUDE = ; C:\sql\library; C:\cobol\esql\library

The initial semicolon indicates an empty directory path (i.e., the current directory). Note that when both -Pi and ACUSQL_INCLUDE are used, the -Pi option takes precedence.

Parent topic: Environment Variables


ACUSQL_PASSWORD

The ACUSQL_PASSWORD environment variable is used in conjunction with the -Pc pre-compiler switch (-Pc directs the pre-compiler to connect to the target database engine to perform syntax checking). ACUSQL_PASSWORD should be assigned the value of the password that goes with the username specified with the -Pu switch or in the ACUSQL_USER environment variable.

Parent topic: Environment Variables


ACUSQL_USER

The ACUSQL_USER environment variable is used in conjunction with the -Pc pre-compiler switch (-Pc directs the pre-compiler to connect to the target database engine to perform syntax checking). ACUSQL_USER should be assigned the username of an authorized database user.

Parent topic: Environment Variables


Pre-compilation Errors

If the pre-compiler encounters illegal ESQL, it attempts to report the error and continue pre-compilation. If the pre-compiler cannot continue, pre-compilation is terminated.

Refer to your SQL reference manual for the meanings of pre-compiler error messages.

Parent topic: Pre-compiler Function and Use


Program Execution

  • Running Your Application
  • Running Your Application with Microsoft SQL Server
  • Debugging and File Tracing
  • Error Messages
Parent topic: AcuSQL Version 10.2.0 User's Guide


Running Your Application

Before using the AcuSQL® runtime for the first time, you should test your Windows-to-data or UNIX-to-data host connection software. If you're using IBM's DB2 Connect software, you can test your connection under Windows by launching the Client Configuration Assistant and clicking Test. For full testing instructions, consult your DB2 Connect documentation. To test other vendors' connectivity software, consult your product documentation. It is essential that you prove the proper functioning of your database connection software before attempting to run your program.

The program object file created by successful pre-compilation and compilation is ready for immediate execution. Generally, there are no special options or configuration settings needed to run an ESQL program. However, if you are using transactions in a SQL Server environment, you will need to set some runtime configuration variables. See Runtime Configuration Variables for SQL Server for information on these variables.

To start the program within AcuBench® integrated development environment, simply double-click on the executable file in the Object tab. To start the program from the DOS or UNIX command line, enter the name of your ACUCOBOL-GT® runtime executable (wrun32.exe on DOS, runcbl on UNIX) followed by the name of the executable file (the runtime executable must be in a directory that is included in the current PATH definition). See Using the Compiler in the ACUCOBOL-GT User's Guide for a detailed discussion of the runtime environment and runtime options.

Parent topic: Program Execution


Running Your Application with Microsoft SQL Server

AcuSQL offers a special runtime DLL for running the product with Microsoft SQL Server. Note that the pre-compiler is unchanged. To pre-compile COBOL programs with embedded SQL, use the procedures found in Pre-compiler Function and Use.

The new runtime DLL is named asqlsrvr.dll. You can use this DLL in two ways:

  • Rename the DLL to esqllib.dll for the runtime to use this DLL when attempting to execute any AcuSQL commands.
  • Give the DLL a name of your choice, and set the configuration variable ACUSQL_RUNTIME_DLL to the name you have chosen. Keep the name as asqlsrvr.dll and setting ACUSQL_RUNTIME_DLL to asqlsrvr.dll.

When getting runtime version information, in order to list the versions of the AcuSQL runtime DLLs, the runtime attempts to find and load all AcuSQL DLLs that it knows about. Currently these are esqllib.dll and asqlsrvr.dll. This is why changing the name of the DLL is not recommended.

ACUSQL_RUNTIME_DLL must be set in the configuration file; this variable cannot be set from the COBOL program. In addition, note that the value of ACUSQL_RUNTIME_DLL cannot be changed from the COBOL program once an AcuSQL command has been executed. In other words, it is not possible to use both esqllib.dll and asqlsrvr.dll in the same run unit.

When connecting to a server, the runtime DLL for the AcuSQL interface to SQL Server environments takes the name of the server, not the name of a datasource. Username and password information is used as described in Environment Variables.

The following statements are not supported by AcuSQL interface to Microsoft SQL Server:

  • DESCRIBE ident INTO parameter
  • FETCH ... USING DESCRIPTOR parameter
  • EXECUTE statement USING DESCRIPTOR parameter
  • OPEN cursor USING DESCRIPTOR parameter
  • CALL procname USING DESCRIPTOR parameter

All other statements are supported.

  • Runtime Configuration Variables for SQL Server
  • Runtime Configuration Variables for esqllib
Parent topic: Program Execution


Runtime Configuration Variables for SQL Server

In addition to the runtime configuration variable ACUSQL_RUNTIME_DLL described in Running Your Application with Microsoft SQL Server, AcuSQL support for SQL Server includes additional runtime configuration variables.

These variables are of particular use when working with transactions. The variables can be set in the environment or in a runtime configuration file.

  • ASQL_AUTO_DATE_FORMAT
  • ACUSQL_SQLSTATE_2000_ON_EOD
  • ASQL_AUTOCOMMIT
  • ASQL_BUFFER_SIZE
  • ASQL_COBOL_DATA_SIZE
  • ASQL_CONNECT_DATABASE
  • ASQL_FAST_ACCESS
  • ASQL_NULL_ALPHA_SPACES
  • ASQL_ODBC_DRIVER_NAME
Parent topic: Running Your Application with Microsoft SQL Server


ACUSQL_SQLSTATE_2000_ON_EOD

Some embedded SQL products set SQLSTATE to the value of "02000" when end of data is reached on FETCH (SQLCODE = 100). The ASQL_SQLSTATE_2000_ON_EOD enables you to duplicate this behavior. Set this variable to the non-default value of TRUE to cause SQLSTATE to have the value 02000 whenever end of data is reached. When set to its default value of FALSE, SQLSTATE will have the value 00000.

Parent topic: Runtime Configuration Variables for SQL Server


ASQL_AUTOCOMMIT

Beginning with version 9.0.1, transaction statements are no longer necessary in AcuSQL as they are now implied and happen automatically. Transaction statements will now be ignored if they are in the COBOL program.

This new behavior is configurable via the runtime configuration variable called ASQL_AUTOCOMMIT. If the value is TRUE, then the commits will automatically be executed immediately when the SQL command is executed. If the value is FALSE, then the SQL statements will be committed or rolled back when the COMMIT or ROLLBACK is executed.

Parent topic: Runtime Configuration Variables for SQL Server


ASQL_BUFFER_SIZE

ASQL_BUFFER_SIZE can be set to any positive number, and causes AcuSQL to cache that many rows from a cursor when the cursor is read. This can result in much less traffic across the network, and, therefore, better performance. Values as small as 5 (to cache 5 rows) can result in a significant performance boost. Test your application for the optimal value to which to set this variable.

ASQL_BUFFER_SIZE is tested when a cursor is opened. Setting the variable programmatically after a cursor is open has no effect.

Parent topic: Runtime Configuration Variables for SQL Server


ASQL_COBOL_DATA_SIZE

The ASQL_COBOL_DATA_SIZE configuration variable uses the size of the COBOL data item instead of the information returned from the SQLDescribeParam function to determine the size of the bind variable. When set to TRUE, the size of the COBOL data item determines the column size. For character fields, the size of the COBOL field is used. For numeric fields, it uses the value of an auto-parameterized query with the constant value is first numeric (10,0). The variable is read at run time before the values are bound, which allows it to be set it for an individual query.

ASQL_COBOL_DATA_SIZE should only be used to work around an issue where SQLDescribeCol returns the wrong column size in a complex union query with parameters since the field sizes it uses may not be the most accurate. The default value of this variable is FALSE. See http://support.microsoft.com/kb/308264/ for more in the issue that is resolved by setting this variable to TRUE.

Parent topic: Runtime Configuration Variables for SQL Server


ASQL_CONNECT_DATABASE

The configuration variable ASQL_CONNECT_DATABASE enables you to specify a database other than the default for accessing data. If ASQL_CONNECT_DATABASE is set to a non-blank value, the driver executes "use [database_name]" as soon as the connection is established. From that point, all data access via that connection will be relative to the specified database.

Note that the database can be specified only before the connection; it is not possible to change databases on the fly.

If the system cannot execute the USE statement, the connection attempt fails with SQLCODE 08004. This can occur, for example, if the specified database does not exist, or if the user does not have permissions to access that database.

Parent topic: Runtime Configuration Variables for SQL Server


ASQL_FAST_ACCESS

The configuration variable ASQL_FAST_ACCESS, when set to TRUE, allows SELECT queries to be solely available to a single request, and not treated as cursors. This can greatly improve performance, but whilst set, if you attempt to retrieve other information from the same connection, you may get a "Connection busy" error.

The default value is FALSE.

Parent topic: Runtime Configuration Variables for SQL Server


ASQL_NULL_ALPHA_SPACES

ASQL_NULL_ALPHA_SPACES allows you to determine how NULL data being returned to an ALPHA field is handled. In some cases, you may want the NULL data returned as ALL SPACES, or you may want the NULL data returned unchanged. Set this variable to the non-default value of TRUE if you want NULL data returned to an ALPHA field as ALL SPACES. The default value is FALSE, and will return NULL data to an ALPHA field unchanged.

Parent topic: Runtime Configuration Variables for SQL Server


ASQL_ODBC_DRIVER_NAME

This variable lets you specify the ODBC SQL Server driver name for the SQL Server interface. SQL Server is the value set by default. You can change this to any value. However, the results are undefined if changed to a value which is not a valid supported SQL Server ODBC driver on your system.

Supported values include:

  • SQL Server
  • SQL Server Native Client 10.0
  • ODBC Driver 11 for SQL Server
  • ODBC Driver 12 for SQL Server
  • ODBC Driver 13 for SQL Server
Parent topic: Runtime Configuration Variables for SQL Server


Runtime Configuration Variables for esqllib

When using the esqllib.dll, AcuSQL support for esqllib.dll includes additional runtime configuration variables.

  • ACUSQL_NO_AUTOCOMMIT
  • ACUSQL_ODBC_CURSORS
  • ACUSQL_USE_CONCURRENT
  • ODBC_CURSOR_TYPE
Parent topic: Running Your Application with Microsoft SQL Server


ACUSQL_NO_AUTOCOMMIT

ACUSQL_NO_AUTOCOMMIT explicitly turns off any auto-commit behavior that your ODBC driver may have. AUTOCOMMIT affects items such as record locking and the ability to roll back work. It is up to the driver vendor to determine whether a driver auto-commits work. If ACUSQL_NO_AUTOCOMMIT is set to 1, the runtime explicitly turns auto-commit off whether or not it is the default. If ACUSQL_NO_AUTOCOMMIT is set to 0, the runtime leaves the driver in its default state. Refer to the documentation provided by your driver vendor for default COMMIT behavior.

Parent topic: Runtime Configuration Variables for esqllib


ACUSQL_ODBC_CURSORS

This variable prevents the Microsoft cursor library from loading. When loaded, this library removes the FOR UPDATE clause from SELECT statements resulting in records not being locked. To prevent this, set ACUSQL_ODBC_CURSORS to 0, which will block the library from loading. The default value is 1, and will allow the Microsoft cursor library to load.

Note: The effect on your application is application and ODBC driver dependent. Refer to the Microsoft documentation and the documentation from your driver vendor.
Parent topic: Runtime Configuration Variables for esqllib


ACUSQL_USE_CONCURRENT

On some machines, calls to set concurrency mode can cause a memory access violation (MAV). The ACUSQL_USE_ CONCURRENT configuration variable can be used to prevent such a violation. Set ACUSQL_USE_ CONCURRENT to 0 (off, false, no) to prevent concurrency mode calls from being made. The default is 1 (on, true, yes).

Parent topic: Runtime Configuration Variables for esqllib


ODBC_CURSOR_TYPE

Set ODBC_CURSOR_TYPE to one of the following to specify a cursor type to use:

For cursor type ... | Set ODBC_CURSOR_TYPE to ...
SQL_CURSOR_FORWARD_ONLY | 0
SQL_CURSOR_KEYSET_DRIVEN | 1
SQL_CURSOR_DYNAMIC | 2
SQL_CURSOR_STATIC | 3

For example:

ODBC_CURSOR_TYPE 3

sets the cursor type to a static cursor.

On Windows, the default is 3 (static). On other systems, the default is the driver default.

Note that not all cursor types are supported by all drivers or in all circumstances. Therefore, you are encouraged to check your database and operating system documentation before using this variable.

Parent topic: Runtime Configuration Variables for esqllib


Debugging and File Tracing

Should you encounter an error in the execution of your program, you can use the debugging facilities in AcuBench or ACUCOBOL-GT to investigate the problem. Once the debugger is running, it may be helpful to use the tf option to turn on file tracing. Included in the file trace are all calls to esqllib.dll and asqlsrvr.dll. To generate the most detailed level of file tracing, follow tf with the number 9. See Handling Program Execution Problems and Debugger and Utilities in the ACUCOBOL-GT User's Guide for a detailed description of debugger options and use.

Parent topic: Program Execution


Error Messages

SQL error messages reported during program execution are directed to standard error output. Refer to your SQL reference manual for the meanings of SQL error messages. Programmers can check for error codes in their programs by examining the values of SQLSTATE and SQLCODE.

MySQL Users

Note that some MySQL drivers do not correctly clear their error buffers after reporting an error. This can cause the driver to produce an infinite loop reporting the same error message. If you keep receiving the same error message over and over, this could be the source of the problem. Check with your driver manufacturer for detail.

DB2 Users

For error messages generated by DB2 Connect or other connectivity software, refer to your product documentation.

Parent topic: Program Execution


Sample Programs

  • Sample Programs
  • Static SQL
  • Creating Tables With ESQL — create.sqb
  • Using Working-Storage Items – select1.sqb
  • Group Items in the INTO Clause – select2.sqb
  • Working With More Than One Row – select3.sqb
  • Updating Data – update.sqb.
  • Full SQL Program
Parent topic: AcuSQL Version 10.2.0 User's Guide


Sample Programs

Your AcuSQL® pre-compiler comes with several sample programs that demonstrate embedded SQL in a COBOL program. Use these sample programs to learn the basics of SQL concepts and syntax. In several places, a syntax statement appears. Given the variety of databases, this syntax statement is quite simplified. Full syntax statements can run pages in length. Refer to your database documentation or any of the commercially available SQL texts for more details of SQL concepts and syntax.

The sample programs on your distribution have been placed in different sub-directories for different data sources, for example Access, DB2, etc. Not all of the data sources will support all of the sample applications. The samples also differ in areas such as table creation syntax and date formats. Take the time to review the differences in these sample programs if you intend to write ESQL applications that run on multiple databases. If you data source is not explicitly listed in the examples, you may examine the various samples to find the one whose syntax most closely matches your target data source.

Note: All syntax examples in this help pertain to embedded SQL in ACUCOBOL-GT® programs with the specified sample database. If necessary, consult any of the commercially available books on SQL for a more generic treatment of embedded SQL.

The following sample files are provided with AcuSQL:

File Name | Description
create.sqb | Loads sample data into database
select1.sqb | Simple SELECT using Working-Storage items
select2.sqb | Simple SELECT using a group item
select3.sqb | Working with CURSORs
update.sqb | Modifying data through a CURSOR

The programs were compiled on a Windows using the following command in a Windows 2000 environment:

ccbl32 -ps filename.sqb

The program was then run by executing the following command:

wrun32 filename
Parent topic: Sample Programs


Static SQL

Embedded SQL programs are based on either static SQL or dynamic SQL. A program can be said to be static SQL when access to the database has been predetermined by the programmer. While the user may input values in response to a query, the query syntax itself is already in place. Put another way, all SQL statements are already part of the program when it is executed.

Parent topic: Sample Programs


Creating Tables With ESQL — create.sqb

The create program creates a table and loads data into it from the text or line sequential “customer” file. The table that is created provides the source data for the other sample programs, so be sure to compile create.sqb and run create.acu before working with the other programs.

This program demonstrates the following ESQL and SQL concepts:

  • The WHENEVER statement
  • Use of DDL (Data Definition Language) to create tables
  • The INSERT statement

When you run the create program, you see the following on your screen:

  • WHENEVER Directive
  • Using DDL
  • INSERT Statement
  • Date Format
  • Putting It All Together
Parent topic: Sample Programs


WHENEVER Directive

The WHENEVER directive controls the flow of the program in the event it encounters an error, warning, or NOT FOUND condition. Note that NOT FOUND conditions are the result of a SELECT or FETCH operation. See SELECT Statement and FETCH Statement for more information on SELECT and FETCH.

Syntax

EXEC SQL WHENEVER  {SQLERROR}   | {CONTINUE}
                   {SQLWARNING} | {PERFORM paragraph}
                   {NOT FOUND}  | {GO TO paragraph}
                                | {STOP}

where paragraph is a specified procedure in the program.

Example

The following statement appears in the create.sqb program:

EXEC SQL WHENEVER SQLERROR GO TO Error-Exit END-EXEC.

This indicates that when the program encounters an error condition, it proceeds to the Error-Exit routine. See SQL Verbs for additional information on the WHENEVER directive.

Parent topic: Creating Tables With ESQL — create.sqb


Using DDL

DDL is an acronym for Data Definition Language. You use DDL statements to create or modify the structure of the database. Creating or dropping tables, or changing the number of columns in a table are all done by means of the DDL.

The create.sqb program contains two examples of DDL statements: DROP TABLE and CREATE TABLE. The DROP TABLE statement causes the program to delete the specified table from the database. Conversely, the CREATE TABLE statement causes the program to create a table with the specified name in the database.

Syntax

DROP TABLE tablename
CREATE TABLE tablename (column1 [, column 2, ... ])

These statements are intended to demonstrate basic, generic syntax. However, syntax for creating tables is database dependent. When creating tables, refer to the documentation that accompanied your database.

Examples

The following statements appear in the create.sqb program.

EXEC SQL
     DROP TABLE customer
END-EXEC.
EXEC SQL
    CREATE TABLE customer
        C_NUMBER           INTERGER NOT NULL,
        C_FIRST_NAME       CHAR(20).
        .
        .
        .
        PRIMARY KEY        (C_NUMBER)
END-EXEC.

With these statements, the program deletes from the database any tables called customer that are owned by the user issuing the command. (The user's area of the database is called a schema). A new table by the same name is then created and defined. This precludes overwriting the original customer table.

Note: It is possible to delete tables from other areas of the database by using a qualified name. See any of the commercially available SQL texts for more information.
Parent topic: Creating Tables With ESQL — create.sqb


INSERT Statement

The INSERT statement is an example of DML (Data Manipulation Language). With INSERT, you are adding data to a table in the database, but you are not changing the structure of the data in any way. The database still contains the same number of tables, and the tables still contain the same number of columns. (Compare this with the CREATE statement, which creates the table, but does not insert data into the table.)

Syntax

The following is a general syntax statement for INSERT

INSERT INTO <tablename> [(field-list)]
VALUES (<values-list>)

where ...

tablename is the name of the table where you are inserting data

field-list is an optional list of fields to which you want to assign values. This list must be written according to the following syntax:

<field-name> [,<field-name] ...

Omitting this list specifies all the fields of the table, using the same order as they are defined.

values-list is a list of literals. The values of these literals are assigned to the fields specified in <field-list>, according to the order in which they are listed. For this reason, the number of elements of both lists must be equal. At the same time, the value of the literal must be compliant with the type of field (alphanumeric, numeric, etc.) used in the table definition.

value-list has the following format:

<literal> [,<literal>] ...

Example

EXEC SQL
    INSERT INTO CUSTOMER VALUES
        (:C-NUMBER, :C-FIRST-NAME, :C-LAST-NAME, :C=BIRTHDAY: C:-INFO)
END-EXEC.

With this statement, the program inserts values into the columns of the customer table. See Host Variables for a general introduction to host variables and Host Variables for an example using host variables.

Parent topic: Creating Tables With ESQL — create.sqb


Date Format

As a developer, you must keep in mind that date formats can vary by database and by country. Another thing to consider is whether you want to indicate the date alone or a timestamp. Be sure to check the documentation that comes with your database for information on date formats.

Help topics include sample code referring to the c_birthday variable. This is simply a placeholder; if you are working with the sample files, you will want to substitute database-specific code to specify the date.

Parent topic: Creating Tables With ESQL — create.sqb


Putting It All Together

You have now created a database table with the following format:

Name | Nullable | Type
C_NUMBER | Not null | NUMBER(38)
C_FIRST_NAME | Yes | CHAR(20)
C_LAST_NAME | Yes | CHAR(20)
C_BIRTHDAY | Yes | DATE
C_INFO | Yes | CHAR(10)

The contents of the customer table looks similar to the following:

C_NUMBER | C_FIRST_NAME | C_LAST_NAME | C_BIRTHDAY | C_INFO
1 | Sam | Snead | 13-APR-52 | New
2 | John | Future | 01-JAN-01 | New
3 | Betty | Falcon | 01-FEB-90 | New
4 | Sally | Snead | 31-DEC-54 | New
5 | John | Jones | 29-FEB-60 | New
Parent topic: Creating Tables With ESQL — create.sqb


Using Working-Storage Items – select1.sqb

Compile and run the select1 program to find the range of customer numbers in the customer table, prompt the user for a customer number, and then retrieve that record. Remember to compile and run the create program before running select1.

This program demonstrates the following SQL concepts:

  • SELECT statements for returning a single row of data.
  • host variables.
  • MIN and MAX functions. These are group functions that operate on a field, or column, of data.
  • SELECT Statement
  • Host Variables
  • INTO Clause
  • WHERE Clause
  • MIN and MAX Group Functions
  • Putting It All Together
Parent topic: Sample Programs


SELECT Statement

Use SQL's SELECT statement to view information in the database. You can see the values of all fields for an entry or you can see a specified subset.

Note: You can also use SELECT statements to view data from more than one table. See your SQL documentation for information about JOIN statements.

Syntax

At its most basic, the syntax for the SELECT statement is as follows:

SELECT <field-name-1>[, <field-name-2>] ...
FROM tablename

where

field-name represents a column or columns in tablename.

tablename is the name of the database table.

Example

For example, the statement

SELECT C_FIRST_NAME, C_LAST_NAME FROM CUSTOMER

returns the first and last names of customers listed in the customer table:

Parent topic: Using Working-Storage Items – select1.sqb


Host Variables

Host variables provide a way for embedded SQL to use variables that are declared in COBOL. They are declared in the SQL DECLARE section of Working-Storage. They are distinguished from database objects (such as columns or tables) by a leading colon (":"). Host variables can be used as input to a SELECT statement or they can be used as output to store the results of an SQL query. The pre-compiler recognizes COBOL variables only if they have been declared in an SQL BEGIN DECLARE section.

For example, in the select1.sqb program, the variables MIN-C-NUMBER and MAX-C-NUMBER are declared in Working-Storage. When embedded SQL statements refer to these variables, they appear as :MIN-C-NUMBER and :MAX-C-NUMBER. See Host Variables for more information on host variables.

Parent topic: Using Working-Storage Items – select1.sqb


INTO Clause

As indicated above, host variables are used to store the result of an SQL query. The resulting value is put INTO the variable.

Syntax

SELECT database-field(s)
INTO :host-variable

where

database-field(s) is one or more variables defined in Working-Storage.

host-variable is the name of a COBOL variable.

Example

The select1.sqb program contains the following code:

EXEC SQL
   SELECT
       C_FIRST_NAME, C_LAST_NAME,
       C_BIRTHDAY, C_INFO
   INTO
       :C-FIRST-NAME, :C-LAST-NAME, :C-BIRTHDAY, :C-INFO
   FROM CUSTOMER
       ...
END-EXEC.

This series of statements instructs the program to place the values for these fields INTO the corresponding COBOL variables, which are C-FIRST-NAME, C-LAST-NAME, etc., so that COBOL statements can refer to them. The semicolon in the code indicates that these are COBOL (host) variables.

Note: In this example, there is a one-to-one match between variables declared in Working-Storage and the columns in the table. The program select2.sqb provides an example where the values to INTO a group item rather than individual fields.
Parent topic: Using Working-Storage Items – select1.sqb


WHERE Clause

The WHERE clause imposes conditions on the SELECT statement. Put another way, it restricts the number of rows returned, based on the indicated criteria.

Syntax

SELECT <field-name-1>[, <field-name-2>] ...
FROM tablename
WHERE condition

Example

EXEC SQL
    SELECT
        C_FIRST_NAME, C_LAST_NAME,
        TO_CHAR, C_INFO
    INTO
        :C-FIRST-NAME, :C-LAST-NAME, :C-BIRTHDAY, :C-INFO
    FROM CUSTOMER
    WHERE C_NUMBER = :C-NUMBER
END-EXEC.

Using the example from the previous topic, the program to place values for these fields INTO the corresponding COBOL variables, which are C-FIRST-NAME, C-LAST-NAME, etc. The semicolon in the code indicates that these are COBOL (host) variables. See an SQL text for more information on conditions and operators supported by SQL.

Parent topic: Using Working-Storage Items – select1.sqb


MIN and MAX Group Functions

A SELECT statement can include any of a number of SQL aggregate functions. The MIN and MAX functions are two functions supported by AcuSQL. The MIN function returns the minimum value of the column from all the rows in a table; the MAX function returns the maximum value.

Syntax

The field name to which the function applies must follow the name of the function and must be enclosed in parentheses.

SELECT MIN(fieldname)
SELECT MAX(fieldname)

Example

The select1.sqb program specifies records containing a customer number. This field is called c-number.

Given that this field contains a range of numbers, if you want to find the smallest value in the range, use the following SELECT statement:

SELECT MIN(C_NUMBER)

Similarly, to find the highest value in the range, use the following SELECT statement:

SELECT MAX(C_NUMBER)
Parent topic: Using Working-Storage Items – select1.sqb


Putting It All Together

Putting this all together, the following statement that appears in the select1.sqb program

EXEC SQL
    SELECT MIN(C_NUMBER)
    INTO :MIN-C-NUMBER
    FROM CUSTOMER
END-EXEC.

instructs the program to do the following:

  1. Start executing an embedded SQL statement.
  2. Find the minimum value in the c_number field of the customer table.
  3. Assign that value to the COBOL host variable :min-c-number.
  4. Stop executing the embedded SQL statement.

If you haven't done so already, compile and run the select1 program. These steps provide one input for the statement Select a customer number between 1 and 5.

Parent topic: Using Working-Storage Items – select1.sqb


Group Items in the INTO Clause – select2.sqb

The program select2.sqb is very similar to select2.sqb. Users will see no difference when they run it. From a developer standpoint, however, the use of the INTO clause is different: the data is placed INTO a group item. This provides a shortcut for you, the programmer. See Host Variables and INTO Clause for information about host variables and the INTO clause.

The select2.sqb program contains the following code:

EXEC SQL
   SELECT
        C_NUMBER, C_FIRST_NAME, C_LAST_NAME,
        C_BIRTHDAY, C_INFO
   INTO :C-RECORD
   FROM CUSTOMER
        WHERE C_NUMBER = :C-NUMBER
END-EXEC.

This instructs the program to take the values of fields in the database table and put these respective values INTO a COBOL group item host variable called :C-RECORD. The host variable is a group item; generated code will have individual fields.

Note: There is a special case when working with group items where the generated code is not broken up into the individual fields. This is the case of a VARCHAR datatype. The structure of the COBOL group item must meet a strict format. Refer to the data type compatibility section of the documentation for your data source for more information.
Parent topic: Sample Programs


Working With More Than One Row – select3.sqb

The programs select1.sqb and select2.sqb each returned one row of data when you entered a customer number. Compile and run the program

select3 to receive data on more than one row. (Remember to compile and run the create program if you haven’t already. This generates the data for the sample programs.)

This program demonstrates

  • working with cursors
  • the FETCH statement

When you run select3.acu, you are asked for a starting customer number, and the program returns information on all customers with the number you provide, or higher, as shown below:

Note: The behavior and duration of a cursor can be affected by the state of transaction processing for your data source. For example, many databases do not have cursors that maintain their state across a commit or rollback. Refer to you database documentation for more details.
  • SET ROWCOUNT Statement
  • Cursors
  • Declaring a Cursor
  • Opening a Cursor
  • FETCH Statement
  • Closing a Cursor
  • Putting It All Together
Parent topic: Sample Programs


SET ROWCOUNT Statement

AcuSQL supports the SQL Server-specific SET ROWCOUNT statement. SET ROWCOUNT affects all SELECT statements made on the connection, and remains in effect until the connection ends or a new rowcount to 0 to turn off this option.

Parent topic: Working With More Than One Row – select3.sqb


Cursors

A cursor is an embedded SQL query that returns multiple rows. The cursor identifies the current row from a SELECT operation that returns multiple rows.

When you work with a cursor, you:

  1. DECLARE the cursor, which identifies it to the program.
  2. OPEN the cursor, which starts the SELECT process.
  3. FETCH until not found, which positions the cursor at each row that meets the conditions set in the SELECT statement and INSERTs the value as designated in the SELECT statement.
  4. CLOSE the cursor, which ends the SELECT operation and releases any resources that had been assigned to the cursor.
Parent topic: Working With More Than One Row – select3.sqb


Declaring a Cursor

Essentially, a cursor is an SQL statement, introduced with a DECLARE statement in the Procedure Division or the Data Division. The cursor does not start the query; the cursor simply identifies the query in the program.

Syntax

DECLARE cursorname CURSOR FOR SELECT_statement

where cursorname is the name you assign to the cursor and SELECT_statement is a SELECT statement that returns multiple rows.

Example

The program select3.sqb contains the following code:

EXEC SQL
   DECLARE COBCUR1 CURSOR FOR
       SELECT
            C_NUMBER, C_FIRST_NAME, C_LAST_NAME,
            TO_CHAR, C_INFO
       FROM CUSTOMER
       WHERE C_NUMBER >= :C_NUMBER
END-EXEC.

Here COBCUR1 is the name of the cursor. The operator in the WHERE clause indicates the possibility that more than one row will be returned.

Parent topic: Working With More Than One Row – select3.sqb


Opening a Cursor

To start the query, you OPEN the cursor.

Syntax

EXEC SQL
    OPEN cursorname
END-EXEC.

Example

EXEC SQL
    OPEN COBCUR1
END-EXEC.
Parent topic: Working With More Than One Row – select3.sqb


FETCH Statement

The FETCH statement positions the cursor at the start of the first row, takes the values returned by the query, and assigns these values to the appropriate host variables. Each time a FETCH is performed, the cursor moves to the next row of results and again assigns the values to host variables.

Syntax

EXEC SQL
    FETCH cursorname INTO :host-variable
END-EXEC.

Example

The program select3.sqb contains the following code:

EXEC SQL
    FETCH COBCUR1 INTO :C_RECORD
END-EXEC.

This positions the cursor, COBCUR1, at the beginning of the table of results returned by the query. The values returned by the query are FETCHed and placed INTO the group item host variable :C_RECORD. FETCH, then, is similar to a SELECT or INSERT operation, except that SELECT applies to results that return a single row and FETCH applies to results that return multiple rows.

Parent topic: Working With More Than One Row – select3.sqb


Closing a Cursor

When the cursor has completed its work, usually by encountering no more data, you must CLOSE it.

Syntax

EXEC SQL
    CLOSE cursorname
END-EXEC.

Example

EXEC SQL
    CLOSE COBCUR1
END-EXEC.
Parent topic: Working With More Than One Row – select3.sqb


Putting It All Together

In this program, which builds upon the previous programs, the following lines of code:

EXEC SQL
   DECLARE COBCUR1 CURSOR FOR
       SELECT
            C_NUMBER, C_FIRST_NAME, C_LAST_NAME,
            TO_CHAR, C_INFO
       FROM CUSTOMER
       WHERE C_NUMBER >= :C-NUMBER
END-EXEC.

EXEC SQL
   OPEN COBCUR1
END-EXEC.

perform until SQLCODE not equal 0

    EXEC SQL
         FETCH COBCUR1 INTO :C-RECORD
    END-EXEC
    IF sqlcode EQUAL 0
         display c-number, ": ",c-first-name,
                 c-last-name, c-info
    end-if
end-perform.

EXEC SQL
    CLOSE COBCUR1
END-EXEC.

cause the program to do the following:

  1. Identify the cursor: for all customers numbers greater than or equal to that supplied by the user, retrieve the values of C_NUMBER, C_FIRST_NAME, C_LAST_NAME, C_BIRTHDAY, and C_INFO and place them in a table of results.
  2. Open the cursor.
  3. Fetch the values of the indicated variables and assign them to the group item host variable :C_RECORD.
  4. If there are no errors or warnings, display the values of the variables.
  5. Do this until the program internally indicates that there are no more rows left in the table of results.
  6. Close the cursor.
Parent topic: Working With More Than One Row – select3.sqb


Updating Data – update.sqb.

The update.sqb program uses a cursor to select rows from a table and update information in the database. The program demonstrates

  • the FOR UPDATE clause when declaring a cursor
  • positioned updates
  • the SET clause
Note: This sample is not supported by MySQL, because it does not support updatable cursors or implement the UPDATE WHERE CURRENT OF and DELETE WHERE CURRENT OF phrases. Refer to the MySQL documentation for any changes in database support of these features.

Run the update program to change information for Sam and Sally Snead in the sample data source you created with the create program

  • FOR UPDATE Clause
  • The SET Clause
  • Positioning the Cursor for the UPDATE
  • Putting It All Together
Parent topic: Sample Programs


FOR UPDATE Clause

You must indicate in the program that the cursor you are declaring may be used to update data in the database table. Programs operate more efficiently if the purpose of the cursor is identified: to only read (SELECT) or to write (INSERT or UPDATE) as well. Remember that you can declare the cursor in either the Procedure or Data Divisions.

Syntax

EXEC SQL
    DECLARE cursorname FOR SELECT_statement
    FOR UPDATE
END-EXEC.

Example

EXEC SQL
    DECLARE COBCUR1 CURSOR FOR
    SELECT C_FIRST_NAME, C_LAST_NAME
        FROM CUSTOMER
        WHERE C_LAST_NAME = 'Snead'
    FOR UPDATE
END-EXEC.

This code opens a cursor that contains a query to SELECT the C_FIRST_NAME and C_LAST_NAME fields for customer Snead. It also indicates, by means of the FOR UPDATE clause, that this information will change and the cursor will write to the database. If you are working in a transaction environment, declaring a cursor FOR UPDATE may start transaction logging or may impose locks on the database table.

Parent topic: Updating Data – update.sqb.


The SET Clause

Use the SET clause to modify current values at the location pointed to by the cursor.

Syntax

EXEC SQL
    UPDATE tablename SET field = 'new_value'
...
END-EXEC

where

tablename is the name of the database table containing the data you want to update.

new_value is the new value you are assigning to that field.

Example

EXEC SQL
    UPDATE CUSTOMER SET C_INFO = 'Revised'
...
END-EXEC

This tells the update program to change the value of C_INFO in the customer table to Revised.

Parent topic: Updating Data – update.sqb.


Positioning the Cursor for the UPDATE

How does the program know which row in the table to update?

The FOR UPDATE Clause topic shows that when the cursor was declared, it contained a WHERE condition to indicate which rows were affected by the SQL query. The WHERE CURRENT OF clause uses this information to position the cursor. This is called a positioned update.

Syntax

EXEC SQL
    UPDATE tablename SET field = 'new_value'
    WHERE CURRENT OF cursorname
END-EXEC

where cursorname is the name of the cursor containing the SQL query.

Example

EXEC SQL
    UPDATE CUSTOMER SET C_INFO = 'Revised'
    WHERE CURRENT OF COBCUR1
END-EXEC

The FOR UPDATE Clause topic shows a cursor declared to select the C_FIRST_NAME and C_LAST_NAME fields from the "customer" table in those instances where C_LAST_NAME was equal to Snead.

When the cursor gets to a row that meets this condition, the value of the C_INFO field will be updated to Revised.

Note: You can also use cursors to perform positioned deletes in AcuSQL. See any commercially available SQL text for information on positioned deletes.
Parent topic: Updating Data – update.sqb.


Putting It All Together

This help section showed how to use a cursor to update a table in the database. The following code:

    EXEC SQL
        DECLARE COBCUR1 CURSOR FOR
        SELECT C_FIRST_NAME, C_LAST_NAME
            FROM CUSTOMER
            WHERE C_LAST_NAME = 'Snead'
        FOR UPDATE
    END-EXEC.

    EXEC SQL
        OPEN COBCUR1
    END-EXEC.

perform until SQLCODE not equal 0

    EXEC SQL
        FETCH COBCUR1
        INTO :C-FIRST-NAME, :C-LAST-NAME
    END-EXEC
    IF sqlcode EQUAL 0

        DISPLAY "Updating " C-FIRST-NAME , C-LAST-NAME
        EXEC SQL
            UPDATE CUSTOMER SET C_INFO = 'Revised'
            WHERE CURRENT OF COBCUR1
        END-EXEC
    end-if
end-perform.

EXEC SQL
    CLOSE COBCUR1
END-EXEC.

instructs the program to perform these steps:

  1. Declare a cursor to SELECT the values of C_FIRST_NAME and C_LAST_NAME from the customer table in those rows where C_LAST_NAME equals Snead. These rows will be updated.
  2. Open the cursor.
  3. Fetch the values and insert them into the host variables :C_FIRST_NAME and :C_LAST_NAME.
  4. If the program doesn't encounter an error condition, display a message indicating that the fields are being updated.
  5. Change the value of the C_INFO field to Revised for those rows that meet the condition set in the cursor (C_LAST_NAME equals Snead).
  6. Close the cursor.

The figure in Updating Data – update.sqb showed the output of the update program. If you want, run the select3 program to see the contents of the updated fields.

Parent topic: Updating Data – update.sqb.


Full SQL Program

The following program performs a simple ESQL CONNECT, DROP, CREATE, INSERT, SELECT, UPDATE, DELETE and DISCONNECT statement.

IDENTIFICATION DIVISION.
       PROGRAM-ID.                         t006146.

*****************************************************************
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT CUSTFILE
               ASSIGN TO "customer"
               ORGANIZATION IS LINE SEQUENTIAL
               FILE STATUS IS CUSTFILE-STATUS.

       DATA DIVISION.
       FILE SECTION.
       FD  CUSTFILE.
       01  CUST-RECORD.
           05  CUST-NUMBER                     PIC 9(3).
           05  CUST-FIRST-NAME                 PIC X(20).
           05  CUST-LAST-NAME                  PIC X(20).
           05  CUST-BIRTHDAY.
              07 SYEAR                         PIC X(4).
              07 SMONTH                        PIC X(2).
              07 SDAY                          PIC X(2).

       WORKING-STORAGE SECTION.
       01  CUSTFILE-STATUS                     PIC XX.

       EXEC SQL INCLUDE SQLCA END-EXEC.

       EXEC SQL BEGIN DECLARE SECTION END-EXEC.
       01  C-RECORD.
           05  C-NUMBER                        PIC S9(3) COMP-5.
           05  C-FIRST-NAME                    PIC X(20).
           05  C-LAST-NAME                     PIC X(20).
           05  C-BIRTHDAY                      PIC X(10).
           05  C-INFO                          PIC X(10).

       01  servername                          pic x(30).
       01  userid                              pic x(8).
       01  passwd.
           49 passwd-length                    PIC s9(4) comp-5 value 0.
           49 passwd-name                      PIC x(18).
       EXEC SQL END DECLARE SECTION END-EXEC.

       01  pyyyymmdd.
           03 syear                             pic 9(4).
           03 smonth                            pic 9(2).
           03 sday                              pic 9(2).

       01  e-yyyymmdd.
           03 syear                             pic 9(4).
           03 filler                            pic x value "-".
           03 smonth                            pic 9(2).
           03 filler                            pic x value "-".
           03 sday                              pic 9(2).

      ******************************************************************
       PROCEDURE DIVISION.
       Main Section.
           EXEC SQL WHENEVER SQLERROR GO TO Error-Exit END-EXEC.
           PERFORM initialization-routine.
           PERFORM make-connection.
           PERFORM drop-table.
           PERFORM create-table.
           PERFORM load-table
           DISPLAY "Table created with 15 rows."
           DISPLAY "Press Enter to retrieve and display these rows."
           ACCEPT OMITTED.
           PERFORM list-rows.
           DISPLAY "Press Enter to perform a UPDATE on table row."
           ACCEPT OMITTED.
           PERFORM update-row.
           DISPLAY "Press Enter to perform to DISPLAY updated list."
           ACCEPT OMITTED.
           PERFORM list-rows.
           DISPLAY "Press Enter to DELETE row 15."
           ACCEPT OMITTED.
           PERFORM delete-row.
           DISPLAY "Press Enter to display all remaining rows."
           ACCEPT OMITTED.
           PERFORM list-rows.
           DISPLAY "Press Enter to DISCONNECT and Exit program."
           PERFORM disconnect-connection.
           ACCEPT OMITTED.
           STOP RUN.

       drop-table.
           DISPLAY "Dropping existing table if it exists...".
           EXEC SQL WHENEVER SQLERROR CONTINUE END-EXEC.
           EXEC SQL
               DROP TABLE CUSTOMER
           END-EXEC.
      * Ignore SQLCODE as the table likely does not exist at this point
           EXEC SQL WHENEVER SQLERROR GO TO Error-Exit END-EXEC.

       create-table.
           DISPLAY "Creating CUSTOMER table...".
           EXEC SQL
              CREATE TABLE CUSTOMER (
                   C_NUMBER        INTEGER NOT NULL,
                   C_FIRST_NAME    CHAR(20),
                   C_LAST_NAME     CHAR(20),
                   C_BIRTHDAY      DATETIME,
                   C_INFO          CHAR(10),
                   PRIMARY KEY     (C_NUMBER))
           END-EXEC.
           IF SQLCODE < 0 PERFORM error-exit.

       load-table.
           DISPLAY "Loading CUSTOMER table with data...".
           OPEN INPUT CUSTFILE.
           PERFORM UNTIL CUSTFILE-STATUS = "10"
               READ CUSTFILE NEXT RECORD
                   AT END
                       CONTINUE
                   NOT AT END
                       PERFORM insert-record
               END-READ
           END-PERFORM.
           CLOSE CUSTFILE.

       insert-record.
           MOVE CUST-NUMBER TO  C-NUMBER.
           MOVE CUST-FIRST-NAME TO C-FIRST-NAME.
           MOVE CUST-LAST-NAME TO C-LAST-NAME.
           MOVE "New" TO C-INFO.

           MOVE CORRESPONDING CUST-BIRTHDAY TO E-YYYYMMDD.
           MOVE E-YYYYMMDD TO C-BIRTHDAY.

           EXEC SQL
               INSERT INTO CUSTOMER VALUES
                   (:C-NUMBER, :C-FIRST-NAME,
                    :C-LAST-NAME, :C-BIRTHDAY, :C-INFO)
           END-EXEC.
           MOVE LOW-VALUES TO CUST-RECORD.
           MOVE LOW-VALUES TO C-RECORD.

       initialization-routine.
           DISPLAY "Enter MS SQL Servername or ODBC DSN:", no.
           ACCEPT servername.
           DISPLAY "Enter your user id (default none): ", no.
           ACCEPT userid.
           DISPLAY "Enter your password : ", no.
           ACCEPT passwd-name.
           IF userid = spaces then
               DISPLAY "Using NT Authentication...".

           INSPECT passwd-name TALLYING passwd-length FOR CHARACTERS
              BEFORE INITIAL " ".

       make-connection.
           EXEC SQL CONNECT TO :servername as C1
                   USER :userid USING :passwd
           END-EXEC.
           IF SQLCODE < 0 PERFORM error-exit.
           IF SQLCODE = 0 DISPLAY "Connection successful".

       disconnect-connection.
           EXEC SQL COMMIT END-EXEC.
           EXEC SQL DISCONNECT ALL END-EXEC.
           IF SQLCODE < 0 PERFORM error-exit.

       Error-Exit.
           EXEC SQL WHENEVER SQLERROR CONTINUE END-EXEC.
           DISPLAY "SQL Error: SQLCODE  " SQLCODE of SQLCA.
           DISPLAY "           SQLSTATE " SQLSTATE of SQLCA.
           DISPLAY SQLERRMC OF SQLCA.
           ACCEPT OMITTED.
           EXEC SQL DISCONNECT ALL END-EXEC.
           STOP RUN.

       list-rows.
           EXEC SQL
              DECLARE COBCUR1 CURSOR FOR
                  SELECT
                       C_NUMBER,
                       C_FIRST_NAME,
                       C_LAST_NAME,
                       C_BIRTHDAY,
                       C_INFO
                  FROM CUSTOMER
                       WHERE C_NUMBER > 0
           END-EXEC.

           EXEC SQL
               OPEN COBCUR1
           END-EXEC.

           PERFORM UNTIL SQLCODE NOT EQUAL 0

              EXEC SQL
                   FETCH COBCUR1 INTO :C-RECORD
              END-EXEC
              IF SQLCODE EQUAL 0
                   DISPLAY c-number, ": ",c-first-name,
                           c-last-name, c-info
              END-IF
           END-PERFORM.

           EXEC SQL
               CLOSE COBCUR1
           END-EXEC.

       update-row.
           EXEC SQL
              DECLARE COBCUR2 CURSOR FOR
              SELECT C_FIRST_NAME,
                        C_LAST_NAME
                   FROM CUSTOMER
                       WHERE C_NUMBER = 002
                   FOR UPDATE
           END-EXEC.

           EXEC SQL
               OPEN COBCUR2
           END-EXEC.

           PERFORM UNTIL SQLCODE NOT EQUAL 0

              EXEC SQL
                   FETCH COBCUR2
                   INTO :C-FIRST-NAME,
                        :C-LAST-NAME
              END-EXEC
              IF SQLCODE EQUAL 0

                   DISPLAY "Updating " C-FIRST-NAME , C-LAST-NAME
                   EXEC SQL
                      UPDATE CUSTOMER SET C_INFO = 'Revised'
                         WHERE CURRENT OF COBCUR2
                   END-EXEC
              END-IF
           END-PERFORM.

           EXEC SQL
               CLOSE COBCUR2
           END-EXEC.

       delete-row.
           DISPLAY "Deleting row 15..."
           EXEC SQL
                DELETE FROM CUSTOMER
                       WHERE C_FIRST_NAME = 'OOOOO'
           END-EXEC
           .
Parent topic: Sample Programs


Glossary of Terms

  • cursor
  • Data Definition Language (DDL)
  • Data Manipulation Language (DML)
  • dynamic SQL
  • ESQL
  • host variable
  • intermediate file
  • ODBC
  • positioned update
  • pre-compiler
  • schema
  • static SQL
Parent topic: AcuSQL Version 10.2.0 User's Guide


cursor

An embedded SQL query that returns multiple rows. Cursors can be declared in either the Procedure Division or the Data Division.
Parent topic: Glossary of Terms


Data Definition Language (DDL)

The set of SQL statements related to the structure of the database, such as creating tables. Online help contains examples of the CREATE statement, an element of SQL’s Data Definition Language. Data Definition Language is also referred to as DDL. Compare this with Data Manipulation Language (DML).
Parent topic: Glossary of Terms


Data Manipulation Language (DML)

The set of SQL statements that pertain to manipulating the data. The structure of the database, such as the number of tables or the number of columns in a table, remains the same. Data Manipulation Language is also called DML. Compare this with Data Definition Language (DDL).
Parent topic: Glossary of Terms


dynamic SQL

A program in which user input determines how the program interacts with the database. Put another way, the SQL statements are not part of the program when it is launched; instead they are built as the program runs. Compare this with static SQL.
Parent topic: Glossary of Terms


ESQL

Embedded Structured Query Language. Commands that enable non-SQL programs such as COBOL programs to communicate with SQL databases. These commands reside in the program along with commands in the host,in this case COBOL, language.
Parent topic: Glossary of Terms


host variable

Any data item defined in an SQL DECLARE section of Working-Storage. Host variables are often used in SQL statements and must be preceded with a colon (“:”).
Parent topic: Glossary of Terms


intermediate file

An AcuSQL system file created between pre-compilation and compilation. Useful for debugging purposes. Intermediate files can be opened into the Code Editor; however, you should not modify the intermediate files in any way. Intermediate files created by AcuSQL have the extension .asq.
Parent topic: Glossary of Terms


ODBC

Open Database Connectivity. A standard protocol used to facilitate communications between Windows-based applications and data sources.
Parent topic: Glossary of Terms


positioned update

An update using a cursor. Use the WHERE CURRENT OF clause to position the cursor at the proper row(s).
Parent topic: Glossary of Terms


pre-compiler

A compiler that is run prior to a standard program compiler to perform preparatory translation tasks. AcuSQL is an ESQL pre-compiler. It is run before the standard ACUCOBOL-GT compiler to translate ESQL commands into ODBC API calls.
Parent topic: Glossary of Terms


schema

A user’s area of the database. Generally speaking, users can add tables to or delete tables from only their area of the database unless they use a qualified name for the table.
Parent topic: Glossary of Terms


static SQL

A program where access to the database has been predetermined by the programmer and any input from the user will not change this access pattern. Put another way, all SQL statements are already part of the program when it is executed. Compare this with dynamic SQL.
Parent topic: Glossary of Terms


AcuToWeb Version 10.2.0 User's Guide

  • Copyright Statement
  • AcuToWeb Introduction
    AcuToWeb is an innovative technology that displays the user interface portion of your server-based ACUCOBOL-GT application to a client-side browser.
  • AcuToWeb Installation and Licensing
    AcuToWeb can be installed as part of the main extend Interoperability Suite installer, and is licensed using the AcuConnect licensing scheme.
  • Preparing Your Application
    AcuToWeb relies on your program or application to be run with AcuConnect, and so when preparing your application, you must bear that in mind.
  • Getting Started (Windows)
    To successfully run an application through AcuToWeb, you need to configure both AcuConnect and AcuToWeb.
  • AcuToWeb Control Panel
    For Windows, there is an AcuToWeb Control Panel, which enables you to configure an AcuToWeb environment for your COBOL applications.
  • AcuToWeb Gateway
    AcuToWeb Gateway is the server module responsible for routing all the traffic between AcuConnect and the connected web browser.
  • AcuToWeb Desktop
    The AcuToWeb Desktop is a client-side component that is responsible for processing certain resources within the application that cannot be processed via the browser.
  • AcuToWeb Security and Authentication
    Client authentication when a client uses AcuToWeb to run an application is provided by AcuConnect, which can be implemented a number of ways.
  • Troubleshooting Your Application
    If you experience problems running your applications through AcuToWeb, run the application in debug mode, and with additional diagnostics enabled.
  • Limitations and Known Issues
    AcuToWeb has certain limitations as to what your applications can contain, or on which platforms they can be deployed.
Parent topic: extend Product Guides


AcuToWeb Introduction

AcuToWeb is an innovative technology that displays the user interface portion of your server-based ACUCOBOL-GT application to a client-side browser.

The client-side browser must have HTML 5 and WebSocket support; this can be found in such browsers as IE 10+, Edge, Firefox 38+, Chrome 43+, Safari 7+, IOS Safari 6+.

AcuToWeb consists of the AcuToWeb Gateway, AcuConnect, ACUCOBOL-GT runtime, your COBOL application and data, and also requires a web server (such as IIS, Apache, or AcuToWeb even includes its own web server). Client-side users only require a browser that supports HTML 5, unless your application needs access to the client, for example, client-side printing or other client-side resources (such as Thin client @[DISPLAY] syntax), in which case AcuToWeb Desktop is required. AcuToWeb Desktop facilitates the communication from the server-side COBOL program (such as calls to Win$Printer) and provides printing functionality on the client.

AcuToWeb can be deployed in the following ways:

  • In a single-tiered environment, where the web server, AcuToWeb, AcuConnect, ACUCOBOL-GT runtime and COBOL program and data all reside on single machine.
  • In a multi-tiered environment, where the web server is configured to tunnel the requests to a AcuToWeb gateway residing on a different machine, and then the AcuToWeb gateway is configured to communicate with AcuConnect, ACUCOBOL-GT runtime and COBOL programs and data residing on another machine.

As AcuToWeb is used by a variety of HTML 5-supporting browsers, the following are not supported by AcuToWeb: ActiveX controls and .NET controls.

Parent topic: AcuToWeb Version 10.2.0 User's Guide
Related reference
AcuToWeb Gateway
AcuToWeb Control Panel
AcuToWeb Desktop
Getting Started (Windows)


AcuToWeb Installation and Licensing

  • AcuToWeb Gateway to AcuConnect prerequisites
  • AcuToWeb install directories and files
  • Licensing
Parent topic: AcuToWeb Version 10.2.0 User's Guide


AcuToWeb Gateway to AcuConnect prerequisites

To route traffic between the browser and your application, the AcuToWeb Gateway provides a method where the client specifies an AcuConnect alias to be run. The AcuToWeb Gateway sends the alias information to AcuConnect; therefore, in order to use AcuToWeb, the following are prerequisites:

  • Install AcuConnect; see Installing AcuConnect.
  • Establish system security; see Establishing System Security.
    Note: When using the AcuToWeb Desktop, the client user name is retrieved and sent during the authentication process; otherwise the user name “acutoweb” will be used.
  • Create the required aliases; see Creating a Server Alias File in Thin Client.
Parent topic: AcuToWeb Installation and Licensing
Related tasks
Installing AcuConnect
Establishing System Security
Creating a Server Alias File in Thin Client


AcuToWeb install directories and files

AcuToWeb installs the following directories and files for each platform:

Windows

The Windows installation results in the following directories and files:

conf
This directory contains the default configuration file. You need a configuration file for each instance of the Gateway that you plan to run on the machine.
Gateway
This directory contains the python object files that provide the web server functionality.
Web
This directory contains the cascading style sheets and other resources required by the Gateway.
ATWDesktop
This directory contains the AcuToWeb Desktop executable.
Tools
This directory contains the python executables required to run the Gateway python object files.

UNIX

The UNIX installation results in the following directories and files:

Gateway
This directory contains the python object files that provide the web server functionality.
Python2.7
This directory contains the python object files.
Web
This directory contains the cascading style sheets and other resources required by the Gateway.
gateway.conf
This file is the default configuration file. You need a configuration file for each instance of the Gateway that you plan to run on the machine.
acutoweb-gateway
This executable enables you to start, stop, or obtain information about the Gateway.
Parent topic: AcuToWeb Installation and Licensing


Licensing

AcuToWeb is licensed using the AcuConnect licensing scheme, which on entry of the product code and product key shipped with AcuToWeb, creates the acurcl.wlc license file.

This file contains information such as the product's version number, serial number, expiration date, and server count. After installation, AcuConnect must be able to locate this license file in order to function.

When AcuConnect detects a client request to start a remote application runtime, it checks the connection count to ascertain if an additional connection is permitted; if it is, AcuConnect attempts to start a runtime on the server and connect it to the client process. The runtime, in turn, checks its usage count before it begins execution of the application.

When an AcuConnect user disconnects from the remote server by exiting the COBOL program, the AcuConnect and runtime usage counts are decremented and those slots are made available to subsequent users. If the usage limit has been reached, the server runtime is not started and an appropriate message is returned in the AcuConnect error file.

The acushare utility is required for all UNIX installations that do not have an unlimited license. The acushare utility monitors and enforces the site runtime usage limits.

Warning: When accessing extend products on remote servers via the Internet or a virtual private network, products or technologies from third-party vendors (such as Microsoft) may be invoked; carefully review any license agreements with these third-party vendors before proceeding with the remote connection.

Nothing in this document is intended to amend the terms and conditions of the applicable license agreement between you and Micro Focus. Rather, this content is meant to summarize the various aspects of Micro Focus's licensing technology, which is required to operate the extend software. The terms and conditions of your licensing of extend software shall continue to be governed by the applicable license agreement between you and Micro Focus.

Parent topic: AcuToWeb Installation and Licensing


Preparing Your Application

AcuToWeb relies on your program or application to be run with AcuConnect, and so when preparing your application, you must bear that in mind.

Details on how to prepare your application are covered in the AcuConnect documentation; use the links at the bottom of the topic for further details.

With AcuToWeb, your COBOL application interface displays in a browser. By default, the title of the tab in the browser is 'AcuToWeb' .You can change this by using the ACUTOWEB_TAB_TITLE configuration variable; it can be set in a runtime configuration file and then specified in the AcuConnect alias, or by using the SET phrase within your COBOL source.

Using CREATE to instantiate a client-side .NET assembly that contains no UI is not currently supported. The CREATE syntax provides server-side execution using the SERVER-NAME "Local:the_server_name" syntax.

If you are planning to deploy a character mode application that will include DBCS characters, then you should be aware of the effect that AcuToWeb sizing has on text and layout elements when a screen is displayed. AcuToWeb uses cascading style sheets to render the web pages when viewing the application within your browser.

When dealing with character screens and DBCS characters, AcuToWeb offers two ways to view the screen. The default way is that the DBCS character text is presented properly, but screen elements for entry may not lay out like they do when running through the runtime. Alternatively, if the layout of your screen elements is more important to your application than the text, then you can use a theme provided: in the URL used to launch your program, add &theme=./examples/DBCS_fixed_table.css, which ensures screen elements are laid out correctly.
Note: You can also select the DBCS_fixed_table.css style sheet from the Themes setting on the Properties dialog box, on the Gateway Services tab of the AcuToWeb Control Panel. Select it before the service is started; otherwise, you must restart the service before the style sheet has an effect.
Parent topic: AcuToWeb Version 10.2.0 User's Guide
Related reference
Designing Your Application
Distribution Considerations
Thin Client Application Design
International Character Handling
ACUTOWEB_TAB_TITLE


Getting Started (Windows)

To successfully run an application through AcuToWeb, you need to configure both AcuConnect and AcuToWeb.

As long as all required components are installed and licensed correctly, you should be able to carry out the majority of the configuration from the AcuToWeb control panel.

Access the control panel in one of the following ways:

  • From the Extend Start Menu, click AcuToWeb Control Panel.
  • From the command prompt, type AcuToWeb and press Enter.
Note: You need to run the AcuToWeb control panel as an administrator.

The following steps aim to get you up and running using as an example one of the extend sample programs running through AcuToWeb:

  1. Start the AcuToWeb Control Panel and click the Access tab.
  2. Select the AcuAccess file in the etc directory and then create a new entry.
  3. Specify acutoweb for the Client Username and enter a valid user as the local user name.
  4. Click the Alias tab and select the acurcl.ini file in the etc directory.
    Note: If one is not present, create a new acurcl.ini file.
  5. Click New and type Tour as the alias name.
  6. Enter C:\Users\Public\Documents\Micro Focus\extend x.x.x\sample\acubench\object as the Working directory.
  7. Enter Tour.acu as the Command Line.
  8. Click the Services tab, select the service (default 5632), then click Start.
  9. On the Gateway Services tab, click the existing entry (8009) and then click Properties.
  10. Browse to and select the gateway.conf file in AcuToWeb\conf sub-directory of your product installation directory.
  11. On the Gateway Services tab, click Start to start the gateway.
  12. Open a browser and load one of the following URLs: http://127.0.0.1:3000 or enter http://machine-name:3000.

    This starts the Gateway Connection Setup dialog box.

  13. Type Tour in the Alias field.
  14. Click Connect.

    The sample Tour program should appear in the browser.

Parent topic: AcuToWeb Version 10.2.0 User's Guide


AcuToWeb Control Panel

For Windows, there is an AcuToWeb Control Panel, which enables you to configure an AcuToWeb environment for your COBOL applications.

As AcuToWeb relies on AcuConnect, the first five tabs offer the same configuration as the AcuConnect control panel. It also includes a Gateway Services tab that provides a mechanism to create and manage gateway configuration files. If you plan to run more than one gateway on a machine, you need a gateway configuration file for each.

Access the control panel in one of the following ways:

  • From the Extend Start Menu, click AcuToWeb Control Panel.
  • From the command prompt, type AcuToWeb and press Enter.
Note: You need to run the AcuToWeb control panel as an administrator.

It includes the following tabs:

  • Access Tab
  • Config Tab
  • Alias Tab
  • Info Tab
  • Services Tab
  • Gateway Services Tab
Parent topic: AcuToWeb Version 10.2.0 User's Guide


Access Tab

The Access tab allows you to maintain the AcuAccess file through the access file manager. To use the access file manager from the control panel, you must be logged onto a Windows server from the administrator account or from an account that belongs to the administrators group. See The Server Access File for detailed information about the AcuAccess file.

The following table describes the contents of each of the fields on this tab.

Field | Description
Client Machine | The official host name by which the client machine is identified on the TCP/IP network. For distributed processing on Windows, this name is found in the Host field under Control Panel > TCP/IP Properties > DNS Configuration. An asterisk (*) in this field means "match all client machines".
Client User Name | The user's login name on the client system. An empty field means "match all client users".
Local User Name | The local user name that AcuConnect will use when fulfilling requests for the client user. If this field is blank, AcuConnect attempts to use the client user name; if that is not a valid name on the server, the value of the DEFAULT_USER configuration variable is used. If DEFAULT_USER is not defined, the connection will be refused (AcuConnect returns an error 9D/103). If DEFAULT_USER is used to connect to AcuConnect on an NTFS partition under Windows NT, 2000, 2003, or 2008, be sure that DEFAULT_USER has both READ (RX) permissions on wrun32.exe and the appropriate permissions to access any file.
Password | The password associated with the local user name.
Confirm Password | Confirmation of the password associated with the local user name.
Umask | The octal value (between 000 and 777) that determines file permissions.

For an example of common access records, see the topic Access Record Composition.

You can use the Access tab to:

  • Creating or Opening an Access File
  • Adding an Access Record
  • Modifying an Access Record
  • Removing an Access Record
Parent topic: AcuToWeb Control Panel
Related information
Config Tab
Alias Tab
Info Tab
Services Tab
Gateway Services Tab


Config Tab

The Config tab allows you to view and set the status of the current configuration settings of a running server. You can use the Config tab to:

  • Change the server and port
  • Add variables to the running server
  • Modify the values of variables

The list box on the Config tab displays the variables and their values associated with the server and port shown in the fields at the top of the tab. The following table describes the contents of each of the fields on this tab.

Field | Description
Variable Name | The name of a configuration variable that has been added to the server configuration file.
Value | The value that has been assigned the variable.
  • Changing the Server and Port You Are Viewing
  • Adding a Variable to the Running Server
  • Modifying the Value of a Variable
Parent topic: AcuToWeb Control Panel
Related information
Access Tab
Alias Tab
Info Tab
Services Tab
Gateway Services Tab


Alias Tab

Before using AcuConnect for thin client operations, you must create a single association file, called an alias file, to hold all the information that is needed to invoke the appropriate application on the server. To create thin client aliases from the control panel, you must be logged on to a Windows server from the administrator account or from an account that belongs to the administrators group.

The following table describes the contents of each of the fields on this tab.

Field | Description
Alias Name | The name of an alias.
Working Directory | The default directory in which the runtime looks for all files specified on the alias command line.
Command Line | The full command line used to invoke the alias, including all the options given to the runtime.

You can use the Alias tab to:

  • Creating an Alias File and Record
  • Modifying an Alias Record
  • Deleting an Alias Record
Parent topic: AcuToWeb Control Panel
Related information
Access Tab
Config Tab
Info Tab
Services Tab
Gateway Services Tab


Creating an Alias File and Record

Follow the procedure below to create an alias file.

  1. On the Alias tab, click Open and browse to the folder in which you want to save the file.
  2. Enter a file name. You are told the file does not exist and asked if you want to create it. Click Yes.
  3. Click New to add a new alias entry to the alias file. The Alias Properties dialog box appears with blank fields.
  4. In the Alias Name field, enter the name of the alias you want to add. For example, you might enter reserve for an airline reservation service.
  5. In the Working Directory field, enter the directory in which the COBOL object files for this alias can be found. (This must be an existing directory.)
  6. Click OK to add this entry to the alias file.
  7. Repeat the procedure for each record you want to add to the alias file.
  8. Click OK to apply your changes.
Parent topic: Alias Tab
Related information
Modifying an Alias Record
Deleting an Alias Record


Modifying an Alias Record

Follow the procedure below to modify an alias record.

  1. In the list box on the Alias tab, select the alias you want to modify. If you want to modify a record in a different alias file, open the alias file first. Click Modify. The Alias Properties dialog box appears, displaying the properties of the selected alias.
  2. To change the properties of the alias working directory, enter the information you want to appear in the Working Directory field.
  3. To change the properties of the command line for the alias, enter the information you want to appear in the Command Line field.
  4. Click OK to apply your changes.
Parent topic: Alias Tab
Related information
Creating an Alias File and Record
Deleting an Alias Record


Deleting an Alias Record

To delete an alias record, select the alias you want to delete in the list box on the Alias tab, then click Delete.

Parent topic: Alias Tab
Related information
Creating an Alias File and Record
Modifying an Alias Record


Info Tab

The Info tab allows you to list and terminate child processes. Use the Info tab to:

  • List child processes
  • Update the list box display
  • Automatically update the list box display
  • Terminate child processes

The following table describes the contents of each of the fields on this tab.

Field | Description
Client | The name of the client machine associated with the child runtime.
User | The client user name associated with the child runtime.
PID | The process ID (PID) of the child runtime.
Start time | The time the runtime started.
Working Directory | The default directory in which the runtime looks for all files specified on the alias command line.
Command Line | The full command line used to invoke the child runtime, including all the options given to the runtime.
  • Listing Child Processes
  • Updating the List Box Display
  • Updating the List Box Display Automatically
  • Terminating a Child Process
Parent topic: AcuToWeb Control Panel
Related information
Access Tab
Config Tab
Alias Tab
Services Tab
Gateway Services Tab


Services Tab

The Services tab allows you to add, start, stop, and remove services, as well as view or modify the properties of an existing service or the configuration and error files associated with that service. When you choose this tab, services that are currently running are marked with a green bullet and services that are currently stopped are marked with a red bullet.

The following table describes the contents of each of the fields on this tab.

Field | Description
Port | The port number on which AcuConnect is running.
Command line | The full command line used to invoke the runtime, including all the options.
  • Adding a Service
  • Starting, Stopping, and Removing a Service
  • Adding Dependencies to a Service
  • Editing the Configuration File
  • Viewing the Error File
Parent topic: AcuToWeb Control Panel
Related information
Access Tab
Config Tab
Alias Tab
Info Tab
Gateway Services Tab


Adding a Service

To add a service, click New on the Services tab. In the Service Properties dialog box, select the options you wish to add to your new service. The following table lists and briefly describes the options available to you.

Field | Description
Configuration file | Use Browse to specify the name and path of the configuration file for the server.
Error file | Use Browse to specify an error file for the server.
Trace level Selecting a trace level from this list turns on the tracing function. If you have specified an error file in the Error file field, trace information is placed in the named error file.

Trace level can be "1" through "7":

"1" provides information about access file match attempts. The trace information buffer is flushed to the error file when the buffer is filled or the service terminates.

"2" provides information about runtime requests. The buffer is flushed to the error file when the buffer is filled or the service terminates.

"3" provides the information described for "1" and "2".

"5" is equivalent to "1", but the tracing buffer is flushed to the error file each time an access file match is requested. (File trace flushing can also be controlled with the FILE_TRACE_FLUSH server configuration variable. See Creating a Server Configuration File for more information.

"6" is equivalent to "2", but the tracing buffer is flushed to the error file each time a runtime is requested.

"7" provides the information described for "5" and "6".

Compress trace output | Causes the file specified in Error file to be compressed using the gzip compression method.
List configuration variable settings | Checking this checkbox causes a listing of the server configuration file to be printed to standard error output. This can be helpful when you are debugging problems that may be related to configuration variables. If you have specified an error file, the listing is captured in this file.
Dependencies You can add the name of a Windows service or service group on which AcuConnect depends. (You may include multiple dependencies.) Click Add to display a list of possible services and service groups.

Note that if you enter dependencies in this field, AcuConnect will not start unless each service named is currently installed on the server as a service.

For information on service dependencies, consult your Microsoft Windows documentation.

Parent topic: Services Tab
Related information
Starting, Stopping, and Removing a Service
Adding Dependencies to a Service
Editing the Configuration File
Viewing the Error File


Starting, Stopping, and Removing a Service

To start, stop, or remove a service, select the service in the list box on the Services tab and click:

  • Start to start the service
  • Stop to stop the service
  • Remove to remove the service
    Note: Be certain that you in fact want to remove the record you select. You will not be asked if you are sure, and the action cannot be undone.
Parent topic: Services Tab
Related information
Adding a Service
Adding Dependencies to a Service
Editing the Configuration File
Viewing the Error File


Adding Dependencies to a Service

Follow the procedure below to add dependencies to a service.

  1. In the Service Properties dialog box, click Add to the right of the Dependencies list.

    The Service Dependencies list box appears.

  2. From the list, select a dependency you want to add to this service.
  3. Click OK to add this selection.
  4. Repeat this procedure until you have added all of the dependencies you want for this service.
  5. In the Service Properties dialog box, click OK to apply your changes.
Parent topic: Services Tab
Related information
Adding a Service
Starting, Stopping, and Removing a Service
Editing the Configuration File
Viewing the Error File


Editing the Configuration File

Use this procedure to edit the current configuration file (acurcl.cfg):

  1. On the Services tab, select the required service.
  2. Click Edit config ....

    The acurcl.cfg file associated with the service is displayed in Notepad.

    If there is no configuration file already in place, you are prompted to add one.

  3. Edit the file, as required, then save and close Notepad.
    Note: The control panel will remain in a 'wait' state until you close Notepad.
Parent topic: Services Tab
Related information
Adding a Service
Starting, Stopping, and Removing a Service
Adding Dependencies to a Service
Viewing the Error File


Viewing the Error File

Use this procedure to view or edit the error file:

  1. On the Services tab, select the required service.
  2. Click Edit error file ....

    The error file associated with the service is displayed in Notepad. If the service is currently running, then the file will be in use; therefore, a snapshot of the file is taken, and it this copy that is displayed. The file is opened in Notepad, where you can edit and save it, as required.

  3. View and/or edit the file, as required, then save and close Notepad.
    Note: The control panel will remain in a 'wait' state until you close Notepad.
Parent topic: Services Tab
Related information
Adding a Service
Starting, Stopping, and Removing a Service
Adding Dependencies to a Service
Editing the Configuration File


Gateway Services Tab

The Gateway Services tab allows you to configure the gateway services required for routing all the traffic between AcuConnect and an end-user's web browser. You can use the Gateway Services tab to:

  • Create, edit and delete gateway service configuration files.
  • Stop and start the gateway services.
  • Generate application URLs
Field | Description
Port | The port number on which AcuToWeb is running.
Config.conf file | The gateway.conf configuration file in use when connecting through the specified port.
  • Adding a Gateway Service
  • Editing a Gateway Service
  • Removing a Service
  • Starting and Stopping a Gateway Service
  • Generating a URL
Parent topic: AcuToWeb Control Panel
Related reference
AcuToWeb Gateway
Related information
Access Tab
Config Tab
Alias Tab
Info Tab
Services Tab


Adding a Gateway Service

  1. On the Gateway Services tab of the AcuToWeb control panel, click New. The Gateway Services Properties dialog box appears.
  2. Using the table below, complete the details of the service:
    Field | Description
    Gateway .conf file The name the file that controls the service. Specify a full path and filename for a new file, or browse to an existing file.
    Note: If you browse to an existing file, you should not alter the gateway port number if it is already in use and specified on the Gateway Services tab, otherwise you will not be able to edit or remove the existing entry; we recommend that you remove any redundant services/ports using the Remove option beforehand.
    AcuConnect host | The instance of AcuRCL that will start new runtimes.
    AcuConnect port | The port on which AcuConnect is listening. Defaults to 5632.
    Max Package Size | The maximum size of packages exchanged between the client and the server (in bytes). Messages bigger than the default will be split; messages smaller than the default will be sent immediately without waiting for the buffer to be filled (and therefore this setting would have no effect). The default is 64000 (bytes).
    TCP Port | The port that the Gateway is listening on, and uniquely identifies the service.
    Handshake Timeout | The interval (in seconds) after which the handshake between the Gateway and AcuConnect will time out. This setting has no effect on other communications. The default value is 3 (seconds). Increase the value if the Gateway and AcuConnect are on different machines and/or there are network issues.
    Web Server Port | The port that receives HTTP requests and routes them to the AcuToWeb Gateway
    Public Root Directory | The location of the cascade style sheets; you can browse to find a suitable directory.
    File Cache Directory | The location of cached files, which needs to be a writable directory; you can browse to find a suitable directory.
    Log Level The level of logging that is carried out. Permissible values are:
    0
    Logs startup/connection information, and the loaded gateway configuration.
    1
    Logs startup/connection information, tracing, and generic error reporting.
    2
    Logs protocol information, tracing, and protocol error reporting.
    4
    Logs detailed protocol information, tracing, and specific acuthin message handler information tracing (TC_W_BITMAP, TC_W_ICON…)
    8
    Logs a hexdump of the transmission data.

    To specify more than one level, add the values together; for example, to log protocol info(4) and transmission data(8), specify a value of 12.

    Log filename | The file in which the logging is recorded; you can browse to find a suitable file.
    Request Username/Password Always

    When checked, the web page prompts for a username and password before trying to connect. These details are verified in the AcuConnect access file.

    Use WebSock compression

    When checked, WebSocket compression is enabled.

    Use SSL Check to apply SSL authentication to your web pages. See Configuring SSL Authentication for more information.
    Note: You must have created the SSL Key and Certificate files already.
    SSL Key File | The name of the SSL Key file (.key) if Use SSL is checked; you can browse to find a suitable file.
    SSL Certification File | The name of the SSL Certificate file (.crt) if Use SSL is checked; you can browse to find a suitable file.
    Dependencies | The names of other services to start before the AcuToWeb Gateway starts. Click Add to add a new dependency, or Delete to remove a selected dependency.
    Themes | Enables you to access the Themes dialog box, where you can manage cascading style sheets. You can name themes and browse for a suitable CSS file that defines the theme.
  3. Click OK. The service is saved, and displayed on the main Gateway Services tab.
Parent topic: Gateway Services Tab
Related information
Editing a Gateway Service
Removing a Service
Starting and Stopping a Gateway Service
Generating a URL


Editing a Gateway Service

  1. On the Gateway Services tab of the AcuToWeb control panel, select the required service, then click Properties.

    The Gateway Services Properties dialog box appears.

  2. Edit the options as required, then click OK. The service details are saved. You will need to restart the gateway service for your edits to come into effect.
Parent topic: Gateway Services Tab
Related information
Adding a Gateway Service
Removing a Service
Starting and Stopping a Gateway Service
Generating a URL


Removing a Service

  1. On the Gateway Services tab of the AcuToWeb control panel, select the required service, then click Remove.

    A confirmation box appears.

  2. Click Yes to confirm. The service is removed from the list.
Parent topic: Gateway Services Tab
Related information
Adding a Gateway Service
Editing a Gateway Service
Starting and Stopping a Gateway Service
Generating a URL


Starting and Stopping a Gateway Service

Note: If you plan to run more than one Gateway on the machine, you need multiple gateway configuration files.

Windows:

  1. On the Gateway Services tab of the AcuToWeb control panel, select the required service, then do one of the following:
    • If the service is currently stopped, click Start.
    • If the service is currently started, click Stop.

    A confirmation box appears.

  2. Click Yes to confirm.

    The service is either started or stopped.

Note:

To start the Gateway from a command prompt, run the following command from the AcuToWeb sub-directory of your installation directory:

.\Tools\Python\python.exe -OO .\Gateway\main.py .\conf\gateway.conf

However, this requires that your command prompt window must remain open whilst you require the gateway. An alternative command that does not require you to keep the window open is:

.\Tools\Python\pythonw.exe -OO .\Gateway\main.py .\conf\gateway.conf

If you use this command, you must use the Services dialog box on the Windows Control Panel to stop the gateway.

UNIX:

On UNIX/Linux platforms, there is an executable called acutoweb-gateway. This supports the following commands:

  • acutoweb-gateway -start
  • acutoweb-gateway -kill
  • acutoweb-gateway -status

From a shell prompt, and in the directory that you installed AcuToWeb, use the following command:

./Python2.7/python -OO ./Gateway/main.py gateway.conf
Parent topic: Gateway Services Tab
Related information
Adding a Gateway Service
Editing a Gateway Service
Removing a Service
Generating a URL


Generating a URL

Use the Generating URL option to create a URL that can be distributed to your end-users; they can paste the URL into their browsers to run the application that the alias refers to

  1. On the Gateway Services tab of the AcuToWeb control panel, select the required (running) service, then click URL gen..

    The Connection Setup dialog box appears.

  2. In the Alias field, enter the name of an alias.
    Note: Use the Alias tab on the AcuToWeb control panel to configure aliases.
  3. Check Fullscreen if you want to run the application in full-screen mode.
    Note: Full-screen mode is only possible after user interaction; the browser will not run in Full-screen mode immediately.
  4. Check Debug-mode to run the ACUCOBOL-GT debugger when using the URL.
  5. In the Themes field, click [image] and select one of the themes available for the Gateway service.
    Note: This option is not available if you have not added any themes to the service from the Gateway Services tab, in the AcuToWeb Control Panel.
  6. Check Enable Logging Client to enable logging whilst the application is run. You should only enable logging when requested to by Micro Focus.
  7. Check Obfuscate Param to encode the URL parameters using the Base64 encoding scheme. When distributed, the specific details in the URL are not readable (without first being decoded).
  8. Click Make Url to generate a URL, which is displayed in the Generated Url field.
  9. You can copy the URL and paste it into a browser, or click Connect or [image] to run immediately.
Parent topic: Gateway Services Tab
Related information
Adding a Gateway Service
Editing a Gateway Service
Removing a Service
Starting and Stopping a Gateway Service


AcuToWeb Gateway

AcuToWeb Gateway is the server module responsible for routing all the traffic between AcuConnect and the connected web browser.

It includes a basic web server that is responsible for making all the resources required to render the ACUCOBOL-GT application, available to the client.

The AcuToWeb Gateway takes the output of the runtime and transforms it into HTML 5. The COBOL user interface, now as HTML 5, is then sent to the requesting browser. The AcuToWeb Gateway runs as a service on Windows servers, and as a daemon on UNIX systems. It listens on one port, and then connects to AcuConnect that is listening on a different port.

The AcuToWeb Gateway performs the following tasks:

  • Resource (.bmp) unpacking and caching. The AcuToWeb Gateway handles the resource extraction from an ACUCOBOL-GT object and the related cache. It also automatically converts the .bmp image format to a .png for bandwidth savings and transparency management.
  • Simple http GET request handling. The AcuToWeb Gateway handles basic http GET requests. This functionality allows the client to retrieve the web application files (.html, .js, .css, resources, etc…).

As AcuToWeb receives information from the runtime, the Gateway uses cascading style sheets to transform the runtime output into HTML 5.

For Windows, there is an AcuToWeb Control Panel, and for UNIX there is an executable (acutoweb-gateway). The AcutoWeb Control Panel and UNIX executable invoke a configuration file (named gateway.conf by default). This configuration file is a plain text file, and as such, can be manually edited; however, care must be taken when manually editing its details, especially around specifying the Gateway port number. If you change the port number, or delete or rename the configuration file, whilst the port is showing in the AcuToWeb Control Panel > Gateway Services, the port (and gateway service entry) is stuck, and can only be started or removed from the Control Panel once the correct port and/or configuration file has been restored.

The Gateway communicates with the client browser via web sockets. The tcp_port portion of gateway.conf corresponds to the port that the Gateway uses to communicate with the client browser.

  • Example Gateway Configuration File
  • Gateway Configuration Options
  • Working with IIS or Apache
  • Configuring SSL Authentication
  • Connecting to the Gateway
  • Cascading Style Sheets
  • Using AcuToWeb on a Mobile Device
Parent topic: AcuToWeb Version 10.2.0 User's Guide
Related reference
AcuToWeb Desktop
Gateway Services Tab


Example Gateway Configuration File

By default, the gateway configuration file is named gateway.conf and is located in C:\Program Files (x86)\Micro Focus\extend x.x.x\AcuToWeb\conf (Windows) or /etc (UNIX).

As the example configuration file below shows, it is in plain text format, and consists of one configuration option and value per line. Lines prefixed # are comment lines and the options are case-insensitive. Refer to Gateway Configuration Options for a description of each option and their permissible values.

The options that populate the configuration file can also be configured from the Gateway Service Properties dialog box (Windows platforms only).
Note: Websocket compression is not supported when you use IIS with AcuToWeb; in those cases, set WS_COMPRESSION 0 in your configuration file, or clear the Use WebSock compression option on the Gateway Service Properties dialog box.
LOGFILE             C:\Users\Public\Documents\Micro Focus\extend 10.2.0\gateway.log
USE_SSL             1
SSL_KEY_FILE        C:\gateway\my-key-file.key
SSL_CRT_FILE        C:\gateway\my-certificate-file.crt
ACURCL              127.0.0.1
ACURCL_PORT         5632
WEBSERVER_PORT      3000
TCP_PORT            8009
PUBLIC_ROOT_DIR     ./Web
FILE_CACHE          ./Web/cache
PATH_FILL_COMBO     C:\my-acutoweb\fillcombo.js
# CUSTOM CSS
CUSTOMIZE_CSS       Example1=../Web/_CSS/examples/defaultCustomCSS.css
CUSTOMIZE_CSS       FX=../Web/_CSS/examples/ThemeFX.css
# PROTOCOL
AUTHORIZED_ACCESS   0
HANDSHAKE_TIMEOUT   3
WS_COMPRESSION      1
MAX_PKG_SIZE        64000
LOG_LEVEL           1

If you edit any of the values in the configuration file, you must restart the AcuToWeb Gateway.

Previous versions of AcuToWeb used a configuration file in JavaScript format. These files continue to be compatible with AcuToWeb but are converted to plain text format when specified from the AcuToWeb Control Panel.

Parent topic: AcuToWeb Gateway
Related reference
Gateway Configuration Options


Gateway Configuration Options

The following table contains a list of the options that you can add to your gateway.conf file. If you are on a Windows platform, these options correspond to the gateway properties available from the Gateway Services tab of the AcuToWeb control panel.

Option Description
LOGFILE Name of the log file used to record the level of information specified by LOG_LEVEL.

Example: LOGFILE C:\etc\log\gateway.log

LOG_LEVEL The level of logging that is carried out. Permissible values are:
0
Logs startup/connection information, and the loaded gateway configuration.
1
Logs startup/connection information, tracing, and generic error reporting.
2
Logs protocol information, tracing, and protocol error reporting.
4
Logs detailed protocol information, tracing, and specific acuthin message handler information tracing (TC_W_BITMAP, TC_W_ICON…)
8
Logs a hexdump of the transmission data.

To specify more than one level, add the values together.

Example: to log protocol info(4) and transmission data(8), specify LOG_LEVEL 12

USE_SSL Enables to use of SSL when connecting through the gateway

Example: USE_SSL 1

SSL_KEY_FILE Specifies the key file to use when SSL is enabled

Example: SSL_KEY_FILE C:\certs\my-web-key.key

SSL_CRT_FILE Specifies the certificate file to use when SSL is enabled

Example: SSL_CRT_FILE C:\certs\my-web-cert.crt

ACURCL The IP address or host name of the AcuConnect server to be used

Example: ACURCL 127.0.0.1

ACURCL_PORT The port number of the AcuConnect server to be used

Example: ACURCL_PORT 5632

WEBSERVER_PORT The port number that receives HTTP requests and routes them to the AcuToWeb Gateway

Example: WEBSERVER_PORT 3000

TCP_PORT The port that the Gateway is listening on, and uniquely identifies the service

Example: TCP_PORT 8009

PUBLIC_ROOT_DIR The location of the AcuToWeb website files

Example: PUBLIC_ROOT_DIR .\web

FILE_CACHE The location of cached files, which needs to be a writable directory

Example: FILE_CACHE C:\tmp\Web\cache

PATH_FILL_COMBO The location of fillcombo.js: the JavaScript file that is used to populate a drop-down list in the Alias field of the Connection Setup screen.

Example: PATH_FILL_COMBO C:\my-acutoweb\fillcombo.js

The following excerpt of fillcombo.js adds aliases for the Calculator and Tour applications:

[
{"type": "category", "text": "Main Applications"},
{"type": "elem", "text": "Calculator", "value": "calc-alias"},
{"type": "elem", "text": "Tour", "value": "tour-alias"}
]
CUSTOMIZE_CSS The name and file location of a cascading style sheet to be used as a theme when running your application through AcuToWeb. You may specify more than one CUSTOMIZE_CSS option to have multiple style sheets in effect at one time. See Cascading Style Sheets for more information.

Example: CUSTOMIZE_CSS FX=../Web/_CSS/examples/ThemeFX.css

AUTHORIZED_ACCESS When set to 1, the web page prompts for a username and password before trying to connect. These details are verified in the AcuConnect access file.

Example: AUTHORIZED_ACCESS 1

HANDSHAKE_TIMEOUT The interval (in seconds) after which the handshake between the Gateway and AcuConnect will time out. This setting has no effect on other communications. The default value is 3 (seconds). Increase the value if the Gateway and AcuConnect are on different machines and/or there are network issues

Example: HANDSHAKE_TIMEOUT 3

WS_COMPRESSION Enables or disables WebSocket compression

Example: WS_COMPRESSION 1

MAX_PKG_SIZE The maximum size of packages exchanged between the client and the server (in bytes). Messages bigger than the default will be split; messages smaller than the default will be sent immediately without waiting for the buffer to be filled (and therefore this setting would have no effect). The default is 64000 (bytes)

Example: MAX_PKG_SIZE 64000

Parent topic: AcuToWeb Gateway
Related reference
Example Gateway Configuration File
Cascading Style Sheets


Working with IIS or Apache

The AcuToWeb Gateway acts as a web server or proxy server, as it listens for requests and then provides the resources needed for that request. AcuToWeb can also be used in conjunction with IIS and Apache.

  • Configuring Apache
  • Configuring IIS
Parent topic: AcuToWeb Gateway


Configuring Apache

To enable the traffic routing from Apache to AcuToWeb Gateway, use the following steps:

  1. (Optional) To enable WebSocket compression, edit your gateway configuration file to include the following line:
    "ws_compression"     : 1,
  2. Open the Apache httpd.conf file.
  3. Enable the proxy module by uncommenting the following lines:
    LoadModule proxy_module "{APACHEPATH}/modules/mod_proxy.so"
LoadModule proxy_wstunnel_module "{APACHEPATH}/modules/mod_proxy_wstunnel.so"
  4. Append the following to the end of the file:
    # HTTP
<VirtualHost *:80>
    ProxyPreserveHost On
    ProxyPass / http://{ip-gateway}:{webserver_port of gateway.conf}/
    ProxyPassReverse / http://{ip-gateway}:{webserver_port of gateway.conf}/
</VirtualHost>
# WebSocket
<VirtualHost *:{The port used by the client to communicate to the gateway}>
    RequestHeader set Host "{ip-gateway}:{tcp_port of gateway.conf}"
    ProxyPreserveHost On
    ProxyPass / ws://{ip-gateway}:{tcp_port of gateway.conf}/
    ProxyPassReverse / ws://{ip-gateway}:{tcp_port of gateway.conf}/
</VirtualHost>
  5. Consult the following scenarios, and use the appropriate one to help you replace the place-holder text in the sections that you have just added, with real information.
  • Scenario 1 Apache and Gateway on same server; Apache forwards all communications
    In the first scenario, the Apache web server and the AcuToWeb Gateway are on the same server, and you want all communications to be forwarded by Apache.
  • Scenario 2 Apache and Gateway on same server; Apache forwards only HTTP communications
    In the second scenario, the Apache web server and the AcuToWeb Gateway are on the same server, and you want only the HTTP communications to be forwarded by Apache.
  • Scenario 3 Apache and Gateway on different servers
    In scenario 3, Apache is installed on one server, and the AcuToWeb Gateway is installed on another server.
Parent topic: Working with IIS or Apache


Scenario 1 Apache and Gateway on same server; Apache forwards all communications

In the first scenario, the Apache web server and the AcuToWeb Gateway are on the same server, and you want all communications to be forwarded by Apache.

Using the following details:

tcp-port | 8008 (the default)
webserver_port | 3000 (the default)
Apache HTTP port | 80 (the default)
WebSocket port | 8010

Amend the httpd.conf file as follows:

# HTTP
<VirtualHost *:80>
    ProxyPreserveHost On
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/
</VirtualHost>
# WebSocket
<VirtualHost *:8010>
    RequestHeader set Host "localhost:8008"
    ProxyPreserveHost On
    ProxyPass / ws://localhost:8009/
    ProxyPassReverse / ws://localhost:8009/
</VirtualHost>

When opening the application in a browser, the URL must contain portgw=<port_num> (<port_num> in this instance is set as 8010 but can be any valid port number, except the same number as tcp_port)

Important: The firewall must allow connections on ports 80 and <port_num>.
Parent topic: Configuring Apache
Related information
Scenario 2 Apache and Gateway on same server; Apache forwards only HTTP communications
Scenario 3 Apache and Gateway on different servers


Scenario 2 Apache and Gateway on same server; Apache forwards only HTTP communications

In the second scenario, the Apache web server and the AcuToWeb Gateway are on the same server, and you want only the HTTP communications to be forwarded by Apache.

Using the following details:

tcp-port | 8008 (the default)
webserver_port | 3000 (the default)
Apache HTTP port | 80 (the default)

Amend the httpd.conf file as follows:

# HTTP
<VirtualHost *:80>
     ProxyPreserveHost On
     ProxyPass / http://localhost:3000/
     ProxyPassReverse / http://localhost:3000/
</VirtualHost>

The URL opened by the browser does not require a portgw parameter; its value defaults to tcp_port.

Important: The firewall must allow connections on ports 80 and 8008.
Parent topic: Configuring Apache
Related information
Scenario 1 Apache and Gateway on same server; Apache forwards all communications
Scenario 3 Apache and Gateway on different servers


Scenario 3 Apache and Gateway on different servers

In scenario 3, Apache is installed on one server, and the AcuToWeb Gateway is installed on another server.

Using the following details:

tcp-port | 8008 (the default)
webserver_port | 3000 (the default)
Apache HTTP port | 80 (the default)
WebSocket port | 8008

Amend the httpd.conf file as follows:

# HTTP
<VirtualHost *:80>
    ProxyPreserveHost On
    ProxyPass / http://{IP Address of the Gateway server}:3000/
    ProxyPassReverse / http://{IP Address of the Gateway server}:3000/
</VirtualHost>
# WebSocket
<VirtualHost *:8008>
    RequestHeader set Host "{IP Address of the Gateway server}:8008"
    ProxyPreserveHost On
    ProxyPass / ws://{IP Address of the Gateway server}:8008/
    ProxyPassReverse / ws://{IP Address of the Gateway server}:8008/
</VirtualHost>

The URL opened by the browser does not require a portgw parameter; its value defaults to tcp_port.

Important: The firewall on the Apache web server machine must allow connections on ports 80 and 8008, and the firewall on the AcuToWeb Gateway server must allow connections on ports 3000 and 8008. (The Gateway server only allows connections from the local area network.)
Parent topic: Configuring Apache
Related information
Scenario 1 Apache and Gateway on same server; Apache forwards all communications
Scenario 2 Apache and Gateway on same server; Apache forwards only HTTP communications


Configuring IIS

Note: You must use IIS version 8 or later, as this provides WebSocket support; IIS version 8 is supported on Windows Server 2012 and later. For more information, visit http://www.iis.net/learn/get-started/whats-new-in-iis-8/iis-80-websocket-protocol-support.

To enable the traffic routing from IIS to AcuToWeb Gateway, use the following steps:

  1. Enable WebSocket support:
    1. On the Add Roles and Features Wizard, select Server Roles.
    2. In the Roles pane, under Web Server > Application Development, select WebSocket Protocol.
  2. Download and install Application Request Routing (ARR 3.0): http://www.iis.net/downloads/microsoft/application-request-routing
  3. Download and install URL Rewrite: http://www.iis.net/downloads/microsoft/url-rewrite
  4. Configure ARR as a forward proxy:
    1. Double-click Application Request Routing Cache.

    2. Click Server Proxy Settings.
    3. Select Enable Proxy, then click Apply.
  5. Configure URL Rewrite:
    1. Double-click URL Rewrite.

    2. Click Add Rules, then click Blank rule.
    3. In the Edit Inbound Rule dialog box, type WebSocket Proxy in the Name field.
    4. Select Wildcards in the Using field.
    5. Select websocket* in the Pattern field.
    6. In the Conditions section, click Add.
    7. Type {HTTP_CONNECT} in the Condition Input field.
    8. Select Matches the Pattern in the Check if input string field.
    9. Type * in the Pattern field, then click OK.
    10. In the Action section, select Rewrite in the Action Type field.
    11. Type http://<gateway ip>:<gateway port>/{R:0} in the Rrewrite URL field (where <gateway ip>:<gateway port> are the IP and port number of your AcuToWeb Gateway).
    12. Check Stop Processing.
    13. Repeat from step b., and add two more rules, as shown here:

Important: Due a limitation of ARR 3.0, this component does not support compressed WebSocket frames; therefore, IIS is not capable of routing them. To make the WebSocket Proxy rule work, the WebSocket protocol must be enabled on the root node, but compression must not be enabled on the AcuToWeb node; add "ws_compression" : 0, to your gateway configuration file or clear the Use WebSock compression option on the Gateway Service Properties dialog box.

When all three rules are properly configured, the IIS-hosted site is able to route all the communications towards the AcuToWeb Gateway. Those rules are triggered using filters on the URL path, so now only port 80 (the http port) will be open to the public network.

Public URL | Routed to
http://<public ip>/* | http://127.0.0.1:3000/*
ws://<public ip>/websocket | http://127.0.0.1:8009/websocket
http://<public ip>/gateway | http://127.0.0.1:8009/gateway
Important:

With this configuration, the AcuToWeb Gateway is hidden behind IIS and it only reachable by using the HTTP port; therefore, it is mandatory to use the portgw parameter to override the gateway configuration; for example:

http://12.345.678.912?hostgw=12.345.678.912&portgw=80&alias=tour

Parent topic: Working with IIS or Apache


Configuring SSL Authentication

When running your applications through AcuToWeb, you can embed Secure Socket Layer (SSL) support into your applications by specifying a matching private key and digital certificate file on the Gateway Services tab of the AcuToWeb Control Panel: select the service properties, then configure the SSL section.

In order to create the digital certificate file, you require a private key and a certificate signing request; both of which can be generated using the following commands if you have the OpenSSL toolkit installed:

openssl genrsa -des3 -passout pass:x -out server.pass.key 2048
openssl rsa -passin pass:x -in server.pass.key -out server.key
openssl req -new -key server.key -out server.csr

Once you have these two files, you must submit them to a Certificate Authority (CA), who can issue you with a genuine digital certificate. Visit the following web site for information about creating and using SSL certificates: https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs

For testing purposes

For testing purposes, you can instead use a self-signed digital certificate that does not require submission to a CA.

For more information about creating and using self-signed certificates, visit: http://www.akadia.com/services/ssh_test_certificate

To create a self-signed certificate from the private key and certificate signing request files created above:

openssl x509 -req -sha256 -days 365 -in server.csr -signkey server.key -out server.crt

When you are prompted for a challenge password, you can leave it blank; this password is used by the CA to authenticate the certificate owner when they want to revoke their certificate. As you are creating a self-signed certificate, it will never be revoked via the Certificate Revocation List.

Self-signed SSL certificates are not officially supported due to browser security limitations when using a secure WebSocket protocol. As this certificate is only designed for non-production applications, you can avoid the security limitations by lowering the browser's security settings; for example, if you are using Chrome, you can run it using the following command, which ignores certificate checking errors:

chrome.exe --ignore-certificate-errors

Although the certificate implements full encryption, you will receive a warning indicating that the certificate should not be trusted, which is why you should only use it on non-production applications.

Parent topic: AcuToWeb Gateway


Connecting to the Gateway

When the Gateway service is up and running, navigate to the AcuToWeb start page using the syntax:

http://[server ip]:[configured port]

The default value is http://127.0.0.1:3000.

The Connection Setup dialog box appears, which confirms that the Gateway is running:

From this point, you can use the following options to create a URL that can be distributed to your end-users; they can paste the URL into their browsers to run the application that the alias refers to:

Option | Description
Gateway connection | Specifies the host name or IP address, and port number of the AcuToWeb Gateway. These values are taken from the gateway.conf configuration file.
Alias Specifies the alias of the AcuConnect to be executed. By default, this option is empty, but you can populate a list of values by adding them to the fillCombo.js file. By default, this file is located in the AcuToWeb\Web\js sub-directory of your installation path, but you can use the PATH_FILL_COMBO option in gateway.conf to use a fillCombo.js file at another location.

The following excerpt adds aliases for the Calculator and Tour applications:

[
{"type": "category", "text": "Main Applications"},
{"type": "elem", "text": "Calculator", "value": "calc-alias"},
{"type": "elem", "text": "Tour", "value": "tour-alias"}
]

You can also type an alias name into the field, then click Make URL, which will generate a URL that you can distribute to customers, which will allow them to paste into their browser and connect to the gateway directly.

Fullscreen When selected, it allows you to toggle Full-screen mode on the browser.
Note: If your program contains multiple windows, you can use Shift + Tab to switch between them.
Debug-mode | When selected, the ACUCOBOL-GT debugger immediately starts when connecting to the gateway.
Themes | Select a theme (.css file) for the application to use in the browser. This option is only available if you have added one or more themes to the service from the Gateway Services tab of the AcuToWeb Control Panel.
Generated Url | Displays the URL required to connect to the gateway.
Enable Logging Client | When selected, logging is enabled whilst the application runs. An additional [image] (Console) icon is added to the top-right corner of the interface to indicate that logging is enabled. Click the icon to display the Logging Console; see Using the Logging Console for more information.
Show Mobile Virtual Keyboard | Displays a mobile virtual keyboard when connecting through the gateway on a mobile device, to help navigate the application. This option is enabled by default, but will not have an effect if not connecting to a mobile device.
Obfuscate Param | Encodes the URL parameters using the Base64 encoding scheme, so that when a URL is distributed, the specific details are not readable (without first being decoded).
Connect | Connects to the gateway using the parameters provided.
  • Connection URL Syntax Explained
Parent topic: AcuToWeb Gateway
Related tasks
Starting and Stopping a Gateway Service


Connection URL Syntax Explained

The Connection Setup dialog box enables you to create URLs that can be distributed to your end-users; they can then paste the URL into their browsers to run your application.

The following example URL connects to your application. See the table beneath it for a breakdown of the syntax:

http://127.0.0.1:3000?hostgw=127.0.0.1&portgw=8009&alias=calc&aliasArgs=%20sum&showvirkey=n&theme=ThemeFX

These are the available URL parameters:

Syntax | Description
http://<IP>:<PORT> | Set <IP> and <PORT> to the IP or hostname and port of your web server.
?hostgw=<gateway-addr>&portgw=<gateway-port>

Set <gateway-addr> to the IP address or hostname of the gateway.

Set <gateway-port> to the port of the gateway. This defaults to 8009 if omitted.

&alias=<alias-name>

Set <alias-name> to the alias of your COBOL application, as configured in AcuConnect.

&aliasArgs=<args>

To pass arguments to the COBOL application, use &aliasArgs and set <args> to the arguments required to run the COBOL application specified; for example &aliasArgs=%20abc%20def.

In the example above %20 inserts the spaces required in between the alias name and the specified arguments.

&alias=<alias-name>%20value%20value | This is an alternative method to using &aliasArgs. You can append the arguments directly after the alias declaration.
&runtimeArgs=<args>

Set <args> to the runtime arguments required to run your COBOL application. This is optional.

&enable_log={y|n}

Set y or n to enable/disable logging. This is optional, and can be omitted completely to disable logging. You should only enable logging when requested to by Micro Focus.

&showvirkey={y|n}

Set y or n to enable/disable the mobile virtual keyboard when connecting to a mobile device. This is enabled by default, but has no effect if you are not connecting to a mobile device.

&theme=<theme-name>

Set <theme-name> to the name of a theme associated with the current Gateway service.

  • Including Special Characters
Parent topic: Connecting to the Gateway


Including Special Characters

If you are crafting a connection URL by hand, you need to be aware that some characters need special encoding (urlencoding). See the following table for the characters that need substituting for their %HexValue:

Special character | ASCII code | URL encoded
space | 32 | %20
! | 33 | %21
? | 63 | %3F
# | 35 | %23
[ | 91 | %5B
] | 93 | %5D
{ | 123 | %7B
} | 125 | %7D
* | 42 | %2B
- | 45 | %2D
+ | 43 | %2C
% | 37 | %25
$ | 36 | %24
/ | 47 | %2F
\ | 92 | %5C

Additional Resources

http://www.w3schools.com/tags/ref_urlencode.asp

http://www.w3schools.com/charsets/ref_html_ascii.asp

Parent topic: Connection URL Syntax Explained


Cascading Style Sheets

AcuToWeb uses cascading style sheets (CSS) to change the COBOL display to HTML. The CSS is implemented in your application as a theme, and themes are configured to be part of your Gateway engine. AcuToWeb connects (through AcuConnect) to a runtime executing the COBOL program and drives the information to the Gateway engine, at which point the display is transformed by CSS. As such, the CSS is not interactive, but is responding to information coming from the runtime.

AcuToWeb implements a default CSS (styles.css), which is located in the Web\_CSS sub-directory (of the install-dir\AcuToWeb directory), but this file should not be edited. There are other style sheets that are shipped with the product that you can use instead, which are located in the Web\_CSS\examples sub-directory:

Style sheet | Notes:
ThemeFX.css | Demonstrates how to change the window color of your applications.
defaultCustomCSS.css | Demonstrates how to change certain controls; for example, it includes a push button that uses rounded corners, and changes color when you place the cursor over it.
DBCS_fixed_table.css | Use this style sheet for character mode applications that display screens containing double-byte characters: it ensures that screen elements are placed as you expect (that is, not affected by the presence of double-byte characters).

Ultimately however, you will want to use your own customizations, and so you should create your own style sheets, and then add those as themes.

To customize a CSS so that it changes certain aspects of your interface, you can use the syntax described in Cascading Style Sheet Syntax to act on a certain type of control (for example, you can change the background-color on all push button controls), or you can explicitly target individual controls by using the AWT-CSS-CLASS or AWT-CSS-ID properties in your source code and adding a corresponding class or ID to the CSS (see details on the individual controls in Control Types for more information).

Tip: If you are unsure of which styles affect an element of your interface, when you have the program running through AcuToWeb, you can right-click in the browser and select Inspect or Inspect Element, which will show the underlying CSS being used in the program. You can also view the style sheets listed above, which should help you ascertain which styles to use.

You can also compliment your interface customizations with the ACUTOWEB_TAB_TITLE configuration variable, allowing you to add a title to your application.

To use a customized style sheet in your applications, implement it as a theme by associating it with the Gateway service: edit a gateway service, then use the Themes option to add (or remove) the style sheets you can use through the gateway service. When you add more than one theme, they are available on the Gateway Connection screen, allowing you to choose one each time you run an application. It is the &theme=<theme-name> syntax within your connection URL that determines the style sheet that is used.

The following example shows three additional themes (spring, image, and fall) that are associated with the gateway service, any of which can be used when running a program:

Note: For networks where there are latency issues, you may notice a delay the first time you use AcuToWeb, as the CSS files need to be loaded. The CSS files are cached on the client, so subsequent uses of AcuToWeb should be quicker, until the cache is emptied.
  • Cascading Style Sheet Syntax
Parent topic: AcuToWeb Gateway
Related reference
ACUTOWEB_TAB_TITLE
Control Types


Cascading Style Sheet Syntax

The following sections show sample CSS syntax. The purpose of this topic is not to teach CSS syntax, rules, properties or any other related concepts, but to show some simple element examples that can you can apply to your style sheets. For further information about any of the syntax, visit http://www.w3schools.com/cssref.

Use the following links to jump to the element details:

  • Bitmap
  • Check-Box
  • Combo-Box
  • Date-Entry
  • Entry-Field
  • Frame
  • Grid
  • Label
  • List-Box
  • Menu
  • Push-Button
  • Radio-Button
  • Scroll-Bar
  • Status-Bar
  • Tab-Control
  • Tree-View
  • Web-Browser
  • Window

Bitmap

Back to list

DOM structure

<div id="img_cnt_851" class="ui-control" style="...">
    <div id="img_851" class="ui-bitmap" style="">
        <img src="/media/image?img=...">
    </div>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-bitmap | The image element

CSS selector samples

.ui-bitmap img:hover {
    /* changing mouse cursor shape on mouse over */
    cursor: zoom-in;
}

Check-Box

Back to list

DOM structure

<div id="check_cnt_757" class="ui-control" style="..." tabindex="0">
    <div id="check_757" class="ui-control-checkbox" style="...">
        <div class="ui-control-check"><div></div></div>
        <legend style="...">...</legend>
    </div>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-checkbox | The radio-button element
ui-control-check | The radio-button bullseye
ui-control-left-text | Applied to the main element when left-text style is set
ui-control-checkbox-win32native | Applied to the check-box when WIN32_NATIVECTLS is set to true
ui-control-checkbox-flat | Applied to the radio-button element when flat style is set
checked | Applied to the div.ui-control-check when the check-box is checked

CSS selector samples

.ui-control-checkbox legend {
    /* adds a simple shadow to the check-box text */
    text-shadow: 2px 2px #ccc;
}

.ui-control-checkbox .checked {
    /* change the check mark border when is selected */
    border-color: #ff0000 !important;
    border-style: solid !important;
}

Combo-Box

Back to list

DOM structure

<div id="combo_cnt_754" class="ui-control" style="...">
    <div id="combo_754" class="dom-combobox" style="...">
        <div class="dom-combobox-container" style="...">
            <input type="text" class="dom-selector" readonly="readonly">
            <a class="dom-combobox-button">
                <span class="ui-icon"></span>
            </a>
        </div>
    </div>
</div>
...
<div class="dom-combobox dom-elems-container" style="...">...</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-combobox-win32native | Applied to the element when WIN32_NATIVECTLS is set to true
ui-combobox-flat | Applied to the main element when the flat style is set
dom-combobox | The combo-box element (main container)
dom-combobox-container | A div wrapping the input field and the combo-box button
dom-selector | The combo-box input field
dom-combobox-button | The combo-box button
dom-elems-container | The combo-box list (created on open)

CSS selector samples

.dom-combobox-container input {
    /* changing default foreground color */
    color: red;
}

.dom-combobox-button span {
    /* changing button icon */
    background-image: url(...);
}

.dom-elems-container {
    /* changing the border and the background color of the combobox items list */
    background-color: #fafafa;
    border: 1px solid #ccc;
}

Date-Entry

Back to list

DOM structure

<div id="dateentry_cnt_752" class="ui-control" style="...">
    <input id="dateentry_752_tvs" type="text" class="is-calendarsPicker">
    <input id="dateentry_752_noneCheck" type="checkbox" checked="">
    <select id="dateentry_752_cal" class="ui-control-staticselect"></select>
</div>

CSS class list

ui-control | Parent div wrapping the component
is-calendarsPicker | The date-entry input element
select | Used as date-entry button

CSS selector samples

.ui-control .is-calendarsPicker {
    color: #333;
    border: 0;
    border-bottom: 5px solid #444;
    padding-bottom: 3px;
    box-sizing: content-box !important;
}

Entry-Field

Back to list

DOM structure

<div id="txt_cnt_843" class="ui-control" style="...">
    <input id="txt_843" class="ui-control-textfield" type="..." >
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-textfield | The input element

CSS selector samples

.ui-control-textfield[type=password] {
    /* cool password field */
    background: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAcAAAAPCAQAAACCCB01AAAAV0lEQVQIW2NgYDg74ex/MJzAAOU0nHUA0xMYIOJA7gIQC8KFQwzuASTuAoazAmc/QDkXzgqAzBaAKoQBoDgKF2IJlCNwtgCVi1/xAyD3AUI2AGh3AYgFAImLeCPFitxPAAAAAElFTkSuQmCC) 12px 50% no-repeat, linear-gradient(to bottom, #f7f7f8 0%,#ffffff 100%);
    border-radius: 3px;
    border: none;
    box-shadow: 0 1px 2px rgba(0,0,0,0.2) inset, 0 -1px 0 rgba(0,0,0,0.05) inset;
    transition: all 0.2s linear;
    color: #222222;
}
.ui-control-textfield[type=password]:focus {
    /* on focus effect */
    box-shadow: 0 1px 0 #2392F3 inset, 0 -1px 0 #2392F3 inset, 1px 0 0 #2392F3 inset, -1px 0 0 #2392F3 inset, 0 0 4px rgba(35,146,243,0.5);
    outline: none;
    background: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAcAAAAPCAQAAACCCB01AAAAV0lEQVQIW2NgYDg74ex/MJzAAOU0nHUA0xMYIOJA7gIQC8KFQwzuASTuAoazAmc/QDkXzgqAzBaAKoQBoDgKF2IJlCNwtgCVi1/xAyD3AUI2AGh3AYgFAImLeCPFitxPAAAAAElFTkSuQmCC) 12px 50% no-repeat, #FFF;
}

Frame

Back to list

DOM structure

<div id="frame_cnt_761" class="ui-control" style="...">
    <div class="ui-control-frame" style="...">
        <div class="ui-control-frame-legend">...</div>
    </div>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-frame | The frame element (the box)
ui-control-frame-legend | The frame title element

CSS selector samples

.ui-control-frame {
    /* forcing a global frame border */
    border: 1px dashed red !important;
}

.ui-control-frame-legend {
    /* adds a simple shadow to the frame title */
    text-shadow: 2px 2px #ccc;
}

Grid

Back to list

DOM structure

<div id="grid_cnt_754" class="ui-control">
    <div id="grid_754_container" class="ui-grid-container">
        <table id="grid_754" class="ui-grid">
            <colgroup>...</colgroup>
            <tbody>
                <tr>
                    <td style="..." class="ui-grid-headers ui-grid-row-headers">
                        <div class="ui-grid-celltext">...</div>
                        <span class="ui-grid-bitmap"></span>
                    </td>
                    ...
                </tr>
                ...
            </tbody>
        </table>
        <div class="ui-grid-cursor" style="..."></div>
        ...
        scrollbars (vertical + horizontal)
        ...
        <div id="grid_754_pager" class="ui-grid-pager">
          <div><input class="ui-control-button ui-paged-prev" type="button"></div>
          <div><input class="ui-control-button ui-paged-pgprev" type="button"></div>
          <div><input class="ui-control-button ui-paged-pgnext" type="button"></div>
          <div><input class="ui-control-button ui-paged-next" type="button"></div>
        </div>
    </div>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-grid-container | Grid component container
ui-grid | Grid component
ui-grid-headers | Applied to the headers cells
ui-grid-row-headers | Applied to the row headings cells
ui-grid-col-headers | Applied to the column headings cells
ui-grid-celltext | Wraps the cell text
ui-grid-bitmap | Cell bitmap (if any)
ui-grid-cursor | Grid cursor frame
ui-grid-cursor-color | Applied to the selected cell
ui-grid-pager | Grid pager (paged style)
ui-paged-first ui-paged-last ui-paged-prev ui-paged-next | Grid pager buttons

CSS selector samples

.ui-grid-cursor {
    /* changes cursor frame color */
    background-color: green;
}

.ui-grid-headers {
    /* adds a simple shadow to the headers */
    text-shadow: 2px 2px #ccc;
}

.ui-grid-pager .ui-paged-next {
    /* changes the icon of the next button */
    background-image: url(...);
}

Label

Back to list

DOM structure

<div id="label_cnt_849" class="ui-control" style="...">
    <div id="label_849" class="ui-control-label" style="...">...</div>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-label | The label element

CSS selector samples

.ui-control-label {
    /* adds a simple shadow to the text */
    text-shadow: 2px 2px #ccc;
}

List-Box

DOM structure

<div id="list_cnt_749" class="ui-control">
    <div id="list_749" class="ui-control-listbox">
        <table>
            <colgroup>...</colgroup>
            <tbody>
                <tr>
                  <td>...</td>
                </tr>
                <tr class="listbox-selected">
                  <td>...</td>
                </tr>
                ...
            </tbody>
        </table>
    </div>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-listbox | List-box component
ui-control-listbox tr | List-box rows
ui-control-listbox tr.listbox-selected | Selected row
ui-control-listbox-win32native | Applied to the element when WIN32_NATIVECTLS is set to true
ui-paged-first ui-paged-last ui-paged-prev ui-paged-next | Paged list-box buttons

CSS selector samples

.ui-control-listbox tr.listbox-selected {
    /* changes selection color */
    background-color: red;
}

.ui-paged-next {
    /* changes the icon of the next button */
    background-image: url(...);
}

Menu

Back to list

DOM structure

<div id="window_837_menu" class="ui-winbase">
    <ul id="menu_838" class="ui-control-menubar">
        <li value="1000" sub="839" data-accelerator="70">
            <div class="ui-control-menuitem">...</div>
        </li>
        ...
    </ul>
</div>

CSS class list

ui-winbase | Generic container used for the windows
ui-control-menubar | Menu-bar component
ui-control-context-menu | Popup menu component
ui-control-menuitem | Generic menu-item
ui-control-menuarrow | Sub-menu arrow
ui-control-menucheck | Menu item check mark
separator | Menu separator item
ui-control-context-menu-li-hovered | Class applied on mouse over
ui-control-context-menu-li-pressed | Class applied on item click
ui-control-main-menu-li-hovered | Class applied on mouse over

CSS selector samples

.ui-control-menubar,
.ui-control-menuitem {
    /* forcing white background */
    background-color: white !important;
    border-color: white !important;
}

Push-Button

Back to list

DOM structure

<div id="button_cnt_822" class="ui-control" style="...">
    <button id="button_822" type="button" class="ui-control-button">...</button>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-button | The button element
ui-control-button-default | Applied to the button element when default-button style is set
ui-control-button-disabled | Applied to the button element when disabled
ui-button-win32native | Applied to the button when WIN32_NATIVECTLS is set to true
ui-button-link | Applied to the button element when islink style is set
ui-button-flat | Applied to the button element when flat style is set

CSS selector samples

.ui-control-button {
    /* buttons with rounded corners */
    border-radius: 5px;
}

button.ui-control-button-disabled {
    /* nearly transparent button when disabled */
    opacity: 0.3;
}

Radio-Button

Back to list

DOM structure

<div id="radio_cnt_937" class="ui-control" style="..." tabindex="0">
    <div id="radio_937" class="ui-control-radiobutton" data-group="..." style="...">
        <div class="ui-control-bull"><div></div></div>
        <legend style="...">...</legend>
    </div>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-radiobutton | The radio-button element
ui-control-bull | The radio-button bullseye
ui-control-left-text | Applied to the main element when left-text style is set
ui-control-radiobutton-win32native | Applied to the radio-button when WIN32_NATIVECTLS is set to true
ui-button-flat | Applied to the radio-button element when flat style is set
checked | Applied to the div.ui-control-bull when the radio-button is checked

CSS selector samples

.ui-control-radiobutton legend {
    /* adds a simple shadow to the radio-button text */
    text-shadow: 2px 2px #ccc;
}

.ui-control-radiobutton .checked {
    /* change the radio bullseye border when is selected */
    border-color: #ff0000 !important;
    border-style: solid !important;
}

Scroll-Bar

Back to list

DOM structure

<div class="dom-scrollbar ui-widget-content v-scrollbar s-hasButtons">
    <button class="dom-scrollbar-button dom-scrollbar-up_btn" href="#"></button>
    <div class="dom-scrollbar-cnt">
        <div class="dom-scrollbar-header">
            <div class="dom-scrollbar-pager" style="..."></div>
        </div>
    </div>
    <button class="dom-scrollbar-button dom-scrollbar-down_btn" href="#"></button>
</div>

CSS class list

dom-scrollbar | Parent div wrapping the component
dom-scrollbar-button | Scroll-bar buttons
dom-scrollbar-cnt | Scroll-bar pager container
dom-scrollbar-pager | Scroll-bar pager

CSS selector samples

/* modern scrollbar */

.dom-scrollbar-header {
    padding: 3px;
    background-color: transparent;
}

.dom-scrollbar-pager {
    border-radius: 5px;
}

.dom-scrollbar-cnt {
    background-color: #555;
}

Status-Bar

Back to list

DOM structure

<div id="sbar_cnt_878" class="ui-control">
    <ul id="sbar_878" class="ui-control-statusbar">
        <li style="..."></li>
        <li style="..."></li>
        ...
    </ul>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-statusbar | The statusbar component
ui-control-statusbar-win32native | Applied to the element when WIN32_NATIVECTLS is set to true
ui-control-statusbar > li | Statusbar panels

CSS selector samples

.ui-control-statusbar > li {
    /* removing border from panels */
    border: 0 !important;
    color: #333;
}

.ui-control-statusbar {
    /* adding a gradient and a border to the statusbar*/
    background: linear-gradient(#ddd, #fff);
    border-top: 1px solid #bbb;
}

Tab-Control

Back to list

DOM structure

<div id="tab_cnt_950" class="ui-control">
    <div id="tab_950" class="ui-control-tabs">
        <ul>
            <li class="tab-selected">...</li>
            <li>...</li>
            ...
        </ul>
    </div>
    <div class="ui-tab-scroller">
        <div class="ui-tab-scroller-prev"></div>
        <div class="ui-tab-scroller-next"></div>
    </div>
    <div id="tab_950_page" class="ui-control-tab-page"></div>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-tabs | Tabs container
ui-control-tabs-win32native | Applied to the element when WIN32_NATIVECTLS is set to true
ui-control-tabs li | Tabs
ui-control-tabs li.tab-selected | Current Tab
ui-tab-scroller | Tabs pager (scroll facility)
ui-control-tab-page | Tab page/body
ui-control-tabs-bottom | Applied to the main element when bottom style is set
ui-control-tabs-vertical | Applied to the main element when vertical style is set
tabs-rounded-label | Applied to the tabs when rounded style is set

CSS selector samples

.ui-control-tabs li.tab-selected {
    /* change foreground color of the selected tab */
    color: red;
}

Tree-View

Back to list

DOM structure

 <div id="tree_cnt_880" class="ui-control">
    <div id="tree_880" class="ui-treeview">
        <div class="ui-treeview-root ui-treeview-item-expanded">
            <div class="ui-treeview-children">
                <div class="ui-treeview-item ui-treeview-item-expanded">
                    <div class="ui-treeview-item-text">...</div>
                    <div class="ui-treeview-children">
                       ...
                    </div>
                </div>
                ...
            </div>
        </div>
    </div>
</div>

DIV.UI-TREEVIEW-ITEM-TEXT structure

<div class="ui-treeview-item-text">
    <span class="ui-treeview-button"></span>
    <span class="ui-treeview-text">
        <span class="ui-treeview-icon">...</span>
        <span class="ui-treeview-txt">...</span>
    </span>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-treeview | Tree-view component
ui-treeview-root | Hidden root node
ui-treeview-children | Children container
ui-treeview-item | Tree-view node container (node + children)
ui-treeview-item-text | Tree-view node
ui-treeview-item-expanded | Added when the tree-view node is expanded
ui-treeview-styles-buttons | Applied to the tree-view when buttons style is set
ui-treeview-styles-showlines | Applied to the tree-view when show-lines style is set
ui-treeview-styles-linesatroot | Applied to the tree-view when lines-at-root style is set
ui-treeview-button | Expand/collapse button
ui-treeview-text | Tree-view node label (icon + text)
ui-treeview-icon | Tree-view node icon
ui-treeview-txt | Tree-view node text

CSS selector samples

.ui-treeview-styles-buttons .ui-treeview-button {
    /* changes image strip used for the treeview items button */
    background-image: url(...);
}

.ui-treeview-item-text {
    /* removes items indentation */
    padding-left: 25px !important;
}

Web-Browser

Back to list

DOM structure

<div id="web_cnt_752" class="ui-control">
    <iframe id="web_752" class="ui-control-browser" style="..." src="..."></iframe>
</div>

CSS class list

ui-control | Parent div wrapping the component
ui-control-browser | The iframe element

CSS selector samples

.ui-control-browser {
    /* removing the border */
    border: 0;
}

Window

Back to list

DOM structure

<div id="window_818_cnt" class="ui-cblwindow">
    <div id="window_818_title" class="ui-wintitle">
        <span class="ui-wintitle-text">...</span>
        <span class="ui-winbtn ui-winbtn-close"></span>
    </div>
    <div id="window_818_menu" class="ui-winbase">
    ...
    </div>
    <div id="window_818_tool" class="ui-winbase">
    ...
    </div>
    <div id="window_818" class="ui-winbase">
       <table id="window_818_term_layer" class="ui-terminal-layer" style="...">
          <tbody>
              <tr>
                  <td style="...">&nbsp;</td>
              </tr>
          </tbody>
       </table>
       ...
    </div>
</div>

CSS class list

ui-winbase | Generic container used for the windows
ui-cblwindow | Window component
ui-wintitle | Window title bar
ui-wintitle-text | Wraps title bar text
ui-winbtn | Window title bar buttons
ui-cblwindow-active | Applied on the active window
ui-terminal-layer | Terminal layer

CSS selector samples

.ui-cblwindow .ui-wintitle {
    /* gradient on title bar */
    background: linear-gradient(to bottom,  #7abcff 0%,#60abf8 44%,#4096ee 100%);
    color: #04509C;
}

.ui-cblwindow {
    /* window with rounded corner */
    border-radius: 5px;
}
table.ui-terminal-layer td{
    /* background transparent on all terminal*/
    background-color: transparent !important;
}
Parent topic: Cascading Style Sheets


Using AcuToWeb on a Mobile Device

To enable existing desktop applications to run on mobile devices usually requires a certain amount of redesign and redevelopment, and often results in a mobile version of the application being produced. One of the main reason that a redesign is required is for navigational issues - if your application relies on extended keyboard functionality such as function keys, the ability to use these keys is often lost unless the program is rewritten to accommodate them on a mobile device.

With AcuToWeb, you can enable a mobile virtual keyboard, which provides extended keyboard functionality such as function keys and navigational keys, by displaying additional icons along the top of your application. This should compliment the alphanumeric virtual keyboard that your mobile device already provides.

You enable the mobile virtual keyboard using the Show Mobile Virtual Keyboard option on the Connection Setup screen.

Note: This option is enabled by default; however, if you are running on a non-mobile device, this option will have no effect.

When the application runs, an icon [image] is displayed in the top left-hand corner of the screen: tap the icon to open the keyboard, showing further navigational and function keys. To close the keyboard, tap the icon again.

Icon | Description
and | Toggle the display of the mobile virtual keyboard.
and | Navigate back and forward - synonymous with pressing Shift-Tab and Tab.
 | Toggles the display of function keys on and off.
 | Toggles the Navigation menu, which includes a set of cursor keys, Insert, Delete, Home, and EOF (End of File).
 | Move to a new line - synonymous with pressing Enter.
Parent topic: AcuToWeb Gateway


AcuToWeb Desktop

Note: AcuToWeb Desktop is currently only supported on Windows platforms.
The AcuToWeb Desktop is a client-side component that is responsible for processing certain resources within the application that cannot be processed via the browser.

The AcuToWeb Desktop must be running on a client machine containing applications that either want to capture client user-name/passwords for validation in the AcuConnect Access file, or applications that access certain client-side resources (see Supported AcuToWeb Desktop Functions); if you do not want to capture client user-name/passwords, or if the application does not use client-side resources, then your application can run without the AcuToWeb Desktop being present.

The AcuToWeb Desktop is installed by default when you select the AcuToWeb option during installation. After installation, you must launch it before you start a new AcuToWeb session when intending to run applications that requires it: to launch, select Start > Programs > extend x.x.x. > AcuToWeb > AcuToWeb Desktop; when running successfully, [image] is displayed in the system tray.
Tip: Add the AcuToWeb Desktop.exe file to your Windows Startup folder to ensure that you are ready to run all AcuToWeb applications when you log on to Windows. Alternatively, when the AcuToWeb Desktop is running, enable the Autorun option on the Tools menu to start the Desktop automatically next time Windows is started.

Once the AcuToWeb Desktop is running, another AcuToWeb Desktop will execute each time you start a new AcuToWeb session in the browser. At that point, a Web socket communications channel is created between the Gateway/browser and the Desktop, and then all the operations that cannot be handled by the browser are forwarded to the Desktop component for processing. For example, using the C$COPY routine to copy a file between the server and client requires the AcuToWeb Desktop, and without a link to the Desktop, the statement (and application) will fail.

Each AcuToWeb Desktop session captures information about that session. From each AcuToWeb Desktop, you can save the session information to a file.

  • Supported AcuToWeb Desktop functions
  • AcuToWeb Desktop menu
Parent topic: AcuToWeb Version 10.2.0 User's Guide
Related reference
AcuToWeb Gateway


Supported AcuToWeb Desktop functions

If your application contains any of the features or syntax listed below, then the AcuToWeb Desktop must be running when you launch your application. If the AcuToWeb Desktop is not running when the application attempts to process any of these features, the application will fail.

  • Local file system interaction
    • Copy
    • Make directory
    • Remove directory
    • Delete file
    • File info
    • List directory
  • Printing

  • ACCEPT Terminal-Abilities FROM Terminal-Info

  • ACCEPT SYSTEM-INFORMATION FROM SYSTEM-INFO

  • Windows Registry
  • Play sound
  • System commands
  • Client clipboard access
  • Windows help
  • Native calls using @[DISPLAY] notation
  • Use W$FONT to allow font selection
  • Open/save dialog box
  • Use WIN$VERSION to retrieve information
Parent topic: AcuToWeb Desktop


AcuToWeb Desktop menu

When installed and running, the AcuToWeb Desktop icon ( [image]) shows in the system tray.

You can right-click the icon to access a number of menu options:

Menu option | Description
Show/Hide AcuToWeb Desktop | Shows or hides the AcuToWeb Desktop control panel
Autorun | Enables or disables the AcuToWeb Desktop as an auto-run executable. When enabled, an instance of the AcuToWeb Desktop will run when you log on to Windows, ready for you to run your applications that require it.
Log Level | Changes the level of logging traced by the control panel
Save Log on file | Saves the log content that is currently displayed to a file
About | Shows AcuToWeb Desktop version information
Exit | Shuts down AcuToWeb Desktop
Parent topic: AcuToWeb Desktop


AcuToWeb Security and Authentication

Client authentication in AcuToWeb is provided by AcuConnect when AcuConnect starts a runtime and the runtime display content is sent to the client browser. AcuToWeb passes client identification to AcuConnect, which uses its server access file or the SECURITY_METHOD configuration setting to authenticate.

You can implement security and authentication checking in AcuToWeb using the following methods:

  • On Windows, from the AcuToWeb Control Panel, select the Properties option when the Gateway is selected on the Gateway Services tab, then on the Gateway Services Properties dialog box, check Request Username/Password Always. On UNIX, add the following line to your gateway.conf configuration file: AUTHORIZED_ACCESS 1. When this is setting is in effect, an additional HTML page appears on the client when an AcuToWeb session starts, allowing a user name and password to be entered. This user name and password is validated against the AcuConnect server access file or using the AcuConnect SECURITY_METHOD setting.
  • If this option is not checked, but the AcuToWeb Desktop is installed and running on the client, then the client user name and password (that is, the values used to sign in to the machine with) is sent to the server and validated by the AcuConnect server access file or using the AcuConnect SECURITY_METHOD setting.
  • If none of the previous options are used, then the AcuToWeb Gateway will send a client user name of 'acutoweb' to the server to be validated by the AcuConnect Access file or AcuConnect SECURITY_METHOD setting. In such cases, you need to add the client user name acutoweb to the AcuAccess file and map that to a local username to support allowing anyone launching a particular program.
Parent topic: AcuToWeb Version 10.2.0 User's Guide
Related reference
The Server Access File
SECURITY_METHOD


Troubleshooting Your Application

If you experience problems running your applications through AcuToWeb, run the application in debug mode, and with additional diagnostics enabled.

When running in debug mode, the application runs in the ACUCOBOL-GT debugger, where you can step through the code as normal.

The additional diagnostics will most likely be enabled at the request of the Micro Focus SupportLine, and can be configured to provide various levels of detail when you run the application. These details can be downloaded and sent to the SupportLine for further diagnosis.

When the diagnostics are enabled, an additional [image] (Console) icon is added to the top-right corner of the interface: click the icon to open the Logging Console, where you can configure the level of diagnostics to display.

  • Using the Logging Console
Parent topic: AcuToWeb Version 10.2.0 User's Guide


Using the Logging Console

When the diagnostics are enabled, an additional [image] (Console) icon is added to the top-right corner of the interface: click the icon to open the Logging Console, where you can configure the level of diagnostics to display.

Select one or more of the following options, the majority of which will affect the level of detail that you see in the console window:

Icon: | Description:
 | Download Log - enables you to download a copy of the current log in .csv format.
 | Clear Log - clears the information currently on display in the console.
Filter | Filter - use the text box to enter the text on which to display from the current log.
 | Show Warning - enables you to toggle on/off warning information in the log.
 | Show Error - enables you to toggle on/off warning information in the log.
 | Info - enables you to toggle on/off warning information in the log.
 | Method - enables you to toggle on/off information relating to methods in the log.
 | SubMethod - enables you to toggle on/off information relating to sub-methods in the log.
 | Socket - enables you to toggle on/off information relating to sockets in the log.
 | Keyboard - enables you to toggle on/off information relating to the keyboard in the log.
 | Event - enables you to toggle on/off information relating to events in the log.
 | GUI - enables you to toggle on/off information relating to the GUI interface in the log.
 | Desktop - enables you to toggle on/off information relating to the AcuToWeb Desktop in the log.
Parent topic: Troubleshooting Your Application


Limitations and Known Issues

AcuToWeb has certain limitations as to what your applications can contain, or on which platforms they can be deployed.

AcuToWeb has the following limitations or known issues:

  • Using CREATE to instantiate a client-side .NET assembly that contains no UI is not currently supported. The CREATE syntax provides server-side execution using the SERVER-NAME "Local:the_server_name" syntax.

  • AcuToWeb does not support AcuConnect encryption or compression. If one or both of those features are in use they must be deactivated. If you need this functionality, use the AcuToWeb Gateway, which provides gzip (native http/WebSocket compression, native http/websocket compression, turned on by default) and SSL (https/wss).

    See Editing a Gateway Service for details on how to configure SSL connections. SSL is usually needed for connections over a public network, and in such circumstances, it is recommended to have the AcuToWeb Gateway behind a full-flagged web server such as Apache or IIS; see Working with IIS or Apache.

  • The AcuToWeb control panel only shows 32-bit AcuConnect services; it will not show 64-bit services. However, as long as the 64-bit AcuConnect service is running, you can still use the AcuToWeb functionality as normal.
  • Character screen applications that use double-byte characters may experience some layout differences when running through AcuToWeb as opposed to the standard runtime. You can mitigate against these differences by using DBCS_fixed_table.css when running the application; see Preparing Your Application.
  • If you are running the AcuToWeb Gateway from the command line (see Starting and Stopping a Gateway Service), and receive a 'side-by-side' error, you need to install the MS Visual c++ 2008 Redistributable package. (note: it must be the base package, and not a subsequent service pack.)
  • When using the Browser control, you cannot load any web pages that have not been coded to run within a frame.
Parent topic: AcuToWeb Version 10.2.0 User's Guide
Related reference
Working with IIS or Apache
Editing a Gateway Service
Preparing Your Application
Starting and Stopping a Gateway Service


AcuXDBC Version 10.2.0 User's Guide

  • Copyright Statement
  • Introduction
  • AcuXDBC Architecture
  • Preparing Your COBOL
  • Configuration
  • Installation and Licensing
  • The System Catalog
  • Using the Command-line Query Tool
  • Supported SQL Commands
  • Working with Windows and Java Applications
  • Troubleshooting
  • Migrating from AcuODBC to AcuXDBC
Parent topic: extend Product Guides


Introduction

Welcome to the AcuXDBC™ data management system, designed to integrate COBOL data files into a relational database-like environment. AcuXDBC enables you to apply structured query language (SQL) and relational database concepts to your COBOL data files, resulting in data that is accessed and managed in much the same way as many of today's popular relational database management systems (RDBMSs).

  • Overview
  • Product Features
  • System Catalog and the Role of XFDs
  • Universal Configuration
  • System Security
  • Multi-company Support
Parent topic: AcuXDBC Version 10.2.0 User's Guide


Overview

AcuXDBC provides broad flexibility in the way your COBOL data is accessed and maintained. AcuXDBC lets you retrieve and update COBOL indexed files, relative files, and sequential files from Windows-based applications, including Microsoft Word, Excel, and Access. Business Intelligence tools such as Crystal Reports® Professional, and custom applications developed in ODBC-supported environments such as Visual Basic® are supported as well. Special functionality lets you retrieve data through Java applications that use JDBC standards. Direct SQL access to your COBOL data is available in Windows environments, in both single and two-tier configurations.

This manual describes how to configure and use AcuXDBC to access data from ODBC (Open Database Connectivity) and JDBC (Java Database Connectivity) enabled applications. It also describes what SQL commands and relational database concepts users can apply to a COBOL database.

Parent topic: Introduction


Product Features

AcuXDBC gives your COBOL data files extended data management capabilities typically associated with RDBMSs, as well as seamless access to this data from popular ODBC- and JDBC-enabled applications.

AcuXDBC provides you with the option of accessing your data through a local server or through a cient-server configuration. With AcuXDBC Local, you access your data directly from a single machine where your COBOL runtime is installed. With AcuXDBC Server and AcuXDBC Client, you access your data from client machines in your network provided that your COBOL runtime is installed on the remote server machine.

  • Relational Database Features
  • Data Access Features
Parent topic: Introduction


Relational Database Features

Tabular Structure of Indexed File Data

The fundamental concept behind relational databases is the organization of data within collections of tables consisting of columns and rows. AcuXDBC creates a database by restructuring COBOL data files into tables. It does this by importing extended File Descriptor (XFD) files, which the compiler can generate to describe schema information to be associated with the COBOL data files in your application. XFDs enable the AcuXDBC interface to populate tables in a system catalog that map COBOL records in the indexed, relative, or binary sequential file to rows and columns of data that can be accessed by common SQL commands. See Preparing your COBOL for more information about XFDs.

System Catalog

Special utilities included with AcuXDBC create and populate a system catalog with information obtained from your XFDs. No special restructuring of your data files is necessary to gain the relational database-like functionality.

SQL DDL (Data Definition Language) Support

AcuXDBC supports many of the DDL commands such as CREATE and DROP, enabling users to create and delete tables or views based on conditional operators and multiple fields/columns.

SQL DML (Data Manipulation Language) Enhancements

In addition to DDL support, AcuXDBC includes broader and more complete support for DML commands such as UNION, UNION ALL, and combined inner/outer joins, as well as an optimized ORDER BY clause.

Multi-level Security

Through the use of the DDL commands GRANT and REVOKE, you have data security options at both database-wide and object-specific levels. For example, one table from a database can be read-only for certain users, while another table within the same database can be read/write accessible by either the same or different users. By combining views and object-level security, even column-level security is available.

Enhanced Performance

AcuXDBC's optimized drivers and SQL processor result in fast execution of complex SQL commands on large data sets.

Parent topic: Product Features


Data Access Features

JDBC Driver for Java Applications

AcuXDBC includes a JDBC driver, which enables Java applications to connect to the database.

Command-line Query Tool

An SQL query tool enables you to execute SQL commands and scripts directly on your database tables without having to connect to the database from a third-party application or go through an ODBC connection. The command-line query tool is useful for such tasks as creating batch reports that require a series of complicated SQL commands to produce.

Parent topic: Product Features


System Catalog and the Role of XFDs

The system catalog forms the core of your database. It comprises a set of system tables that describe all of the tables and relations contained within the database. You can have multiple system catalogs (databases), but only a single catalog may be accessed at one time. The system catalog is fully portable between machines with the same byte ordering.

AcuXDBC populates a system catalog with information it reads from your XFDs. Once this information is loaded, AcuXDBC no longer requires your XFDs. Instead, it refers to the system catalog to obtain the information needed to construct and display your COBOL tables. This gives you the option of providing end users with either XFDs for building their own system catalog or a pre-built system catalog. The ability to supply a pre-built system catalog can lead to other benefits for your applications. For example, you can also pre-build user logins, database object permissions, and complex data handling views.

Parent topic: Introduction


Universal Configuration

Most variables are set from within a configuration file called acuxdbc.cfg by default. The advantage of using a configuration file is that Data Source Name (DSN) settings become universal, meaning you don't have to set them individually each time you create a DSN.

Parent topic: Introduction


System Security

The SQL GRANT/REVOKE command and its variants are used to manage database security. This provides flexibility and levels of security. See Granting Database Privileges for information on setting database security.

Parent topic: Introduction


Multi-company Support

AcuXDBC offers convenient ways to manage multiple company data sets. For example, you may have two sets of data, one for Company01 and one for Company02. The layouts of the data files are the same, but the file names have different prefixes or suffixes. Rather than setting up individual system catalogs for each company, you can use wild cards (defined in the AcuXDBC configuration file) to identify which company file to access. Alternatively, you can assign table ownership to the different companies, then issue a single query to access all the data files.

Parent topic: Introduction


AcuXDBC Architecture

This help section introduces the AcuXDBC interface and its components.

  • AcuXDBC Design
  • System Architecture
  • Security
Parent topic: AcuXDBC Version 10.2.0 User's Guide


AcuXDBC Design

The AcuXDBC interface is designed to let users of Windows, Java applications, or the AcuXDBC query tool read and write indexed files (as well as relative and sequential files) as if they were tables in a relational database.

Since none of these file formats is relational to begin with, AcuXDBC's job is to present COBOL files in a table format that can be accessed by applications like Microsoft Excel or ColdFusion.

  • Basic Components
Parent topic: AcuXDBC Architecture


Basic Components

AcuXDBC includes a database tool (xdbcutil) that creates and populates a system catalog from your XFDs. A system catalog is where database systems store metadata that describes the structure of the database system itself, as well as the structure of specific tables. You can generate XFDs at compile time along with your COBOL object files.

After you run xdbcutil, your COBOL data becomes like a relational database — a COBOL database — accessible to applications that issue SQL requests for data. After setup, your XFDs are expendable, unless you use them for another application.

When deployed, the basic components of a AcuXDBC system include:

An ODBC and/or JDBC driver | Receives SQL requests from ODBC- or JDBC-enabled applications and routes them to the SQL processor.
An SQL processor | Processes SQL requests, queries the driver, and returns results
A Micro Focus driver | Provides access to the COBOL database
Your COBOL database
  • COBOL data files (indexed, fixed sequential, or relative)
  • A system catalog — A series of files that maps your COBOL data fields to database columns. Based on your XFDs, these files are themselves indexed files. The system catalog is a deployment piece and has no bearing on the COBOL developer

With AcuXDBC, you can also use an SQL query tool, such as xdbcquery, to issue SQL requests for COBOL data directly. This bypasses the ODBC/JDBC layer altogether. xdbcquery comes with AcuXDBC.

The following illustration depicts the basic components of AcuXDBC:

A COBOL database is the system catalog and the COBOL files it describes (indexed, fixed sequential, and relative) that reside in one or more directories. For a given installation, you may have one or more COBOL databases. Only one database may be accessed by an application at one time; however, a single file may be a component of multiple databases.

Parent topic: AcuXDBC Design


System Architecture

AcuXDBC can operate in one of the following configurations:

  • Local processing (all processing accomplished on a local server using XDBC Local)
  • Remote processing (client-server architecture with AcuXDBC Server)
  • Remote Access/Local Processing (AcuXDBC with AcuServer)
  • Local Processing
  • Remote Processing (Network or Client-Server)
  • Remote Access - Local Processing - AcuServer
Parent topic: AcuXDBC Architecture


Local Processing

In a local processing configuration, both the AcuXDBC interface and the database that it creates reside on the same computer. This is considered a single-tier architecture.

A typical local-processing installation is illustrated in the following diagram.

Parent topic: System Architecture


Remote Processing (Network or Client-Server)

In a two-tier configuration, the client computer is running the ODBC/JDBC application or the command-line query tool. The data to be processed resides on a remote Windows server. With AcuXDBC Server (xdbcsrvr) running on the remote machine, your application is able to take advantage of server-side processing of the SQL statements.

Remote processing can mean more efficient use of your system resources. Queries often process large amounts of data to get results. Remote processing decreases the amount of data that must be transferred between the client and the server. If files reside on the same server on which processing occurs, network traffic is reduced. Only the final result of the processing is returned to the client machine. In addition, this structure encourages centralized management of your data, cutting down on duplication and ensuring that the information returned to the application is up-to-date.

For remote processing on a Windows server, xdbcsrvr resides as a service on the remote machine, waiting for calls for SQL processing. xdbcsrvr is a single-instance server: each time it gets a request, it spawns a new copy to deal with the request, and the original goes back to listening for additional requests. You may run xdbcsrvr continuously, or start and stop it.

The following illustration depicts the architecture for remote SQL processing.

Parent topic: System Architecture


Remote Access - Local Processing - AcuServer

For those whose configurations already using AcuServer, AcuServer can be used to gain access to files that reside on a remote computer; however, with AcuServer, these files are transferred to the client and processed locally. Because of the performance impact of network communication, AcuServer should be used with AcuXDBC only when a small amount of data is being accessed.

AcuServer is available for most UNIX/Linux and Windows NT (Intel) machines. It can serve COBOL applications running on UNIX/Linux and Windows TCP/IP-based networks. You must have a TCP/IP networking client installed on the client machine and a licensed copy of AcuServer installed on the server. For more information about AcuServer, see the AcuServer documentation.

Remote file access architecture is depicted as follows:

Notice that in this AcuServer configuration, the Vision database is split up. That is, the system catalog is local on the client, but the Vision data files themselves are on the remote server. The Vision data files can also be a mixture of local and remote.

Parent topic: System Architecture


Security

AcuXDBC provides a variety of security measures, some at the network level and some at the database level.

  • Network Security Layer
  • Database Security Layer
Parent topic: AcuXDBC Architecture


Network Security Layer

In client-server configurations, AcuXDBC offers one form of network security: user ID and password encryption.

Use the -k option to the xdbcsrvr command to encrypt the database user ID and password that goes across the network. Use it to specify the masking key value used to perform the encryption, then use the KEY_CONNECT variable in the file net.ini to specify the same value on each client machine. See Network Configuration for information about the net.ini file.

See Starting Micro Focus XDBC on the Server (Network Only) or Starting AcuXDBC on the Server - (Network Only) for more information on starting and stopping the server component of AcuXDBC.

Parent topic: Security
Related information
KEY_CONNECT configuration variable


Database Security Layer

AcuXDBC offers a variety of ways to secure your database. If you don't adopt any of these methods, your database is open to everyone.

  • You can hide individual data fields from within your COBOL application by using the HIDDEN directive. This directive instructs the compiler to flag a specified COBOL field as hidden when the XFD file is generated. When the XFD is subsequently loaded into the database, this field will not appear as a column in any description of the table. This is useful for hiding data like passwords, telephone numbers, and financial information — whatever information you do not want users to see.
  • You can tag fields or columns of data as read-only using the READ-ONLY directive. Users can then view the data but not update it.
  • You can use the READ_ONLY configuration variable to establish the read and write permissions for all the files belonging to the database.
  • You can grant database-level and table/file-level privileges to individual users or to PUBLIC using the SQL statement GRANT. This updates the system tables known as GENESIS_USERS and GENESIS_AUTH. When AcuXDBC receives the connection string, it compares the username and password supplied through the data source name (or user-entered) with the GENESIS_USERS table. If the GENESIS_USERS table doesn't exist, AcuXDBC allows the connection. If the table does exist, AcuXDBC checks to make sure the user and password match a record.

    For general information on granting permissions, see Granting Database Privileges and Setting Permissions on Your Database Tables.

  • You can create views of your data using the SQL statement CREATE VIEW to show certain fields and columns of data in your database, but not others. A potential situation in which this could be useful is the following:

    An application has a customer record containing all of the information on a customer. The application developer would like to enable clerical workers to update some of the customer information, while masking any private information. A good way to do this is making one user the owner of the full table. The application developer could then create a VIEW of the table that contained only the non-private information. If the view were created as owned by PUBLIC, all users would be able to access this information while maintaining the confidentiality of the remainder of the information.

Parent topic: Security


Preparing Your COBOL

This help section introduces the concept of mapping COBOL File Descriptors to XFDs.

  • Mapping COBOL Data Items and Database Fields
  • The Role of XFDs
  • Using XFD Directives
Parent topic: AcuXDBC Version 10.2.0 User's Guide


Mapping COBOL Data Items and Database Fields

AcuXDBC relies on Extended File Descriptors (XFDs) to map your COBOL data items to database columns. An XFD file may be created either as a simple text file or as an XML file. In either case, the XFD contains a description of a COBOL indexed, sequential, or relative file based on its fields. XFDs are automatically generated when you compile your program with the -Fx option. If the default mapping is sufficient, there is nothing more you need to do to prepare your COBOL for AcuXDBC except create the XFDs themselves. See The Role of XFDs for information on creating XFDs.

If you want to add more detail to your database tables, you can add other directives to your program before generating the XFDs. Directives are optional comments that you can place into a File Descriptor (FD) in your COBOL source code to control how XFDs are built. See Using XFD Directives for information on adding directives.

Parent topic: Preparing Your COBOL


The Role of XFDs

For AcuXDBC to map your COBOL data file to an SQL table format, descriptive information must be written to an XFD file for each data file. An XFD typically has the same name as the COBOL data file, but its extension is .xfd. When you distribute your application, you don't need to include the XFD with the executable files and data files. The XFDs are used only one time to populate your system catalog.

This help section describes the information included in an XFD and how it is mapped to a system catalog format that is easily recognized by your ODBC or JDBC application. See Using XFD Directives for a description of how you can take control of the XFDs using directives. Because this material is relevant during compilation, it applies only to COBOL developers.

  • Creating XFD Files
  • How XFDs are Formed
  • Defaults Used in XFD Files
  • Examples of Default Mapping
  • Summary of XFD Fields
  • Naming the XFD File
  • How AcuXDBC Locates XFD Files
Parent topic: Preparing Your COBOL


Creating XFD Files

To create an XFD file, specify the -Fx or -Fa option at compile time. For example:
ccbll32 -fa animals.cbl

Use the -Fa or -Fx option to generate XFDs for all indexed, relative, and sequential files in XML format. Specify -Fae or -Fxe to generate the XFDs in standard flat text file format. XFDs are stored in your source code directory unless you use -Fo to specify another location.

Once you compile with the -Fx option, each COBOL file has a corresponding .xfd file. The directive creates .xfd files without changing anything in the object code.

Creating XFD files at compile time offers two significant advantages:

  • Any changes made to the file definitions are automatically included in the XFDs when the program is recompiled
  • The effects of all compile-time options, COPY REPLACING, and source-code control lines are reflected correctly in the XFDs

The XFDs contain information about such things as the structure of the COBOL files, the names of the fields, and their format. However, this information is only a subset of the information available in most applications. To map your COBOL fields to tables that are more meaningful and useful to the application, you may need to add additional information to your XFDs. To add information to your XFDs, or to change the default names of the existing fields, you must use directives, or optional comments, in the FD section of your COBOL program. These directives are explained in Using XFD Directives.

Note: If you create your XFDs with a data storage option, you must specify the -s switch to xdbcutil when loading your system catalog with your XFDs. See xdbcutil Syntax for more information.
Parent topic: The Role of XFDs


How XFDs are Formed

XFDs enable the AcuXDBC interface to populate tables in a system catalog that map COBOL records in the indexed, relative, or binary sequential file to rows and columns of data that can be accessed by common SQL commands.

In the database table, each column contains the values for one data item. The column names are essentially the field names. The table that is built is based on the largest record in the COBOL file and contains the fields from that record, plus any key fields (key fields are those that are named in KEY IS phrases of SELECT statements in the FILE CONTROL section). This ensures that data from all COBOL records fits within the table and simplifies the storage and retrieval process. If you were to examine the database columns, only the fields from the largest record and the key fields would appear.

Note: If the field named in the KEY IS phrase is a group item, it does not become a column in the XFD table. Instead, the elementary items subordinate to the named group item each become a column. You can force a group item to be a column by using the USE GROUP directive.

With multiple record formats (level 01), not all COBOL fields are represented in the database by name, but all fields are storable and retrievable. The XFD maps fields from all records of a file to the corresponding locations in the "master" (largest) record of the file, and thus to the COBOL database table. Only the fields included in the XFD will be available to ODBC or JDBC applications. Because AcuXDBC has access to the table holding information from the XFD, it knows where the data from a given COBOL record fits in the database tables. This activity is invisible to the ODBC or JDBC application.

You can use the WHEN directive to include multiple record definitions in the XFD. Alternatively, you can create views of your data using the SQL command, CREATE VIEW.

CAUTION:
Each field or group of fields in your COBOL FD or XFD field must correspond to an SQL column name. To ensure that this is the case, you may need to use the NAME directive to add field names to the XFD.
Parent topic: The Role of XFDs
Related information
USE GROUP directive
WHEN directive
CREATE VIEW Command
NAME directive


Defaults Used in XFD Files

There are several elements of COBOL FDs that require special handling when XFDs are built. These include multiple record definitions, REDEFINES, FILLER, and OCCURS. This help section describes how the compiler handles each of these situations.

As described earlier, in many instances you can override the default behavior described below by placing directives in the FDs of your COBOL code. For example, the WHEN directive enables you to use multiple definitions for a single set of data by specifying when each definition should be used. Directives are described in Using XFD Directives.

Like most data sources, AcuXDBC does not support the notion of multiple definitions for the same column. Whenever a COBOL program gives more than one definition for the same data, the compiler makes a choice about which definition to use in the XFD. Then it disregards the rest.

  • KEY IS Phrase
  • REDEFINES Clause
  • Multiple Record Definitions
  • Group Items
  • FILLER Data Items
  • OCCURS Clause
  • Identical Field Names
Parent topic: The Role of XFDs


KEY IS Phrase

Fields named in KEY IS phrases of SELECT statements are included as column names in the XFD. Other fields that occupy the same areas as the key fields (by either explicit or implicit redefinition) are not included by name, but are mapped to the key field column names by the XFD.

Remember, if the field named in the KEY IS phrase is a group item, it will not be included in the XFD unless a USE GROUP directive is used.

Parent topic: Defaults Used in XFD Files
Related information
USE GROUP directive


REDEFINES Clause

Fields contained in a redefining item occupy the same positions as the fields being redefined. The compiler needs to select one of the field definitions to use. The default rule that it follows is to use the fields in the item being redefined as column names; fields that appear subordinate to a REDEFINES clause are mapped to column names in the COBOL database using the XFD.

Parent topic: Defaults Used in XFD Files


Multiple Record Definitions

This same rule extends to multiple record definitions. In COBOL, multiple record definitions are redefinitions of the entire record area. This leads to the same complication that is encountered with REDEFINES: multiple definitions for the same data. So the compiler needs to select one definition to use.

Because the multiple record types can be different sizes, the compiler must use the largest one, so that it can cover all of the fields adequately. Thus, the compiler's rule is to use the fields in the largest record defined for the file. If more than one record is of the largest size, the compiler uses the first one.

Parent topic: Defaults Used in XFD Files


Group Items

Group items are, by default, never included in an XFD for the same reason that REDEFINES are excluded: they result in multiple names for the same data items, and they are shown in the XFD file as a comment. You can, however, choose to combine grouped fields into one data item by specifying the USE GROUP directive.

Parent topic: Defaults Used in XFD Files
Related information
USE GROUP directive


FILLER Data Items

In a COBOL FD, FILLER data items are placeholders. FILLER items are not uniquely named and thus cannot be uniquely referenced. For this reason, they are not placed into the XFD. The XFD maintains the correct mapping of the other fields, and no COBOL record positional information is lost.

If your ODBC or JDBC application needs to refer to information contained in a FILLER data item, you may need to include it. In such a case, you could include it under a USE GROUP directive, or give it a name of its own with the NAME directive.

Parent topic: Defaults Used in XFD Files
Related information
NAME directive
USE GROUP directive


OCCURS Clause

An OCCURS clause requires special handling, because the compiler must assign a unique name to each database column. The compiler accomplishes this by appending sequential index numbers to the items named in the OCCURS.

For example, if the following were part of a file's description:

     03  employee-table occurs 20 times.
         05  employee-number     pic 9(3)

these column names would be created in the COBOL database table, that is, the table of COBOL data created when AcuXDBC performs its translation:

employee_number_1
employee_number_2
.
.
.
employee_number_10
employee_number_11
.
.
.
employee_number_20

You can use the SUBTABLE directive to modify this behavior, resulting in the compiler storing just the base name along with the name of the subtable specified by the directive.

Note that the hyphens in the COBOL code are translated to underscores in database field names, and the index number is preceded by an underscore.

Parent topic: Defaults Used in XFD Files
Related information
SUBTABLE directive


Identical Field Names

In COBOL you distinguish fields with identical names by qualification. For example, there are two fields named MONTH in the following code, but they can be qualified by their group items. Thus, you would reference MONTH OF LAST_VISIT and MONTH OF LAST_PAYMENT in your program:

10  last_visit.
    15  month               pic 99.
    15  day                 pic 99.
    15  year                pic 99.
10  last_payment.
    15  month               pic 99.
    15  day                 pic 99.
    15  year                pic 99.

However, database systems consider duplicate names an error. Thus, if more than one field in a particular file has the same name, you receive a compile warning, and an .xfd file is not generated.

The solution in this situation is to add a NAME directive that associates an alternate name with one or both of the conflicting fields.

Parent topic: Defaults Used in XFD Files
Related information
NAME directive


Examples of Default Mapping

If your program has one file with the three records shown below, the underlined fields are included in the XFD by default (this example assumes that ar-codes-key is named in a KEY IS phrase). Some fields do not appear in the XFD, but the XFD maps them to the master field names. The interface thus eliminates redundancies and gives you optimum performance.

Note: In the following example, the ship-weight and ship-instruct fields would be invisible to any ODBC, JDBC, or SQL application, unless you used a directive to make the fields visible.
01  ar-codes-record.
    03  ar-codes-key.
        05   ar-code-type     pic x.
        05   ar-code-num      pic 999.

These underlined fields are included because they are the key.

01  ship-code-record.
    03  filler               pic x(4).
    03  ship-weight          pic s999v9.
    03  ship-instruct        pic x(15).
01  terms-code-record.
    03  filler               pic x(4).
    03  terms-rate-1         pic s9v999.
    03  terms-days-1         pic 9(3).
    03  terms-rate-2         pic s9v999.
    03  terms-descript       pic x(15).

These underlined fields are included because they comprise the largest record.

The diagram below shows how AcuXDBC identifies database columns for some of the fields in the COBOL record, while other fields are mapped to those columns by the XFD; this means that all of the fields are accessible to the ODBC or JDBC program.

Note: If your application reads a record that should be a ship-code-record, the data that is displayed is unreadable. If you try to modify that record, you may receive an error message.
Parent topic: The Role of XFDs
Related information
KEY IS Phrase


Summary of XFD Fields

Fields defined with an OCCURS Clause are assigned unique sequential names. Fields without names are disregarded. When multiple fields occupy the same area, the compiler chooses only one of them unless you have a WHEN directive to distinguish them. To choose among multiple fields occupying the same area, the compiler:

  • Preserves fields mentioned in KEY IS Phrase
  • Discards group items unless USE GROUP is specified
  • Discards REDEFINES Clause
  • Uses the largest record if there are Multiple Record Definitions
Parent topic: The Role of XFDs
Related information
WHEN directive
USE GROUP directive


Naming the XFD File

The compiler must give a name to each XFD file that is built. The compiler attempts to build the name from your COBOL code, but in some instances the name in the code is nonspecific, and you must provide a name.

Each .xfd name is built from a starting name that is derived (if possible) from the SELECT statement in your COBOL code. The following table explains how that occurs.

ASSIGN name is a variable | If the SELECT for the XFD file has a variable ASSIGN name (ASSIGN TO filename), you must specify a starting name for the .xfd file via a FILE directive in your code
ASSIGN name is a constant | If the SELECT for the XFD file has a constant ASSIGN name (such as ASSIGN TO "COMPFILE"), that name is used as the starting name for the .xfd file
ASSIGN name is generic | If the ASSIGN phrase refers to a generic device (such as ASSIGN TO "DISK"), the compiler uses the SELECT name as the starting name for the XFD
  • Forming the Final XFD Name
  • Examples of XFD Names
Parent topic: The Role of XFDs


Forming the Final XFD Name

From the starting name, the final name is formed as follows:

  1. The compiler removes any extensions from the starting name
  2. It constructs a universal base name by stripping out directory information that fits any of the formats used by the operating systems that run the application.
  3. It converts the base name to lower case
  4. It appends the extension .xfd to the base name
Parent topic: Naming the XFD File


Examples of XFD Names

COBOL code File name
ASSIGN TO "usr/ar/customer.dat"
 customer.xfd
SELECT TESTFILE, ASSIGN TO DISK
 testfile.xfd
ASSIGN TO "-D SYS$LIB:HELP"
 help.xfd
Parent topic: Naming the XFD File


How AcuXDBC Locates XFD Files

You provide the path to your XFDs on the command line when first populating your system catalog using xdbcutil or addfile. Once your XFDs are used by xdbcutil, AcuXDBC no longer needs them. Your XFDs are completely expendable unless they are being used by another application. See Creating a System Catalog and Views for more information.

Parent topic: The Role of XFDs


Using XFD Directives

XFDs may be built directly from your source code with only the -Fx option if the compiler's default mapping rules are sufficient for your situation. If you would like to override the default mapping behavior or map a field to a different name, you can add additional directives to your COBOL code.

These directives are optional comments that you can place into an FD in your COBOL source code to control how XFDs are built. By controlling how XFDs are built, you can guide the way AcuXDBC will map the content of your COBOL files' fields to columns in the tables that comprise your database.

Among other things, directives enable you to

  • Specify a column name to be used in place of a COBOL field name
  • Map elementary items of a group item together into a single column
  • Cause the fields from a specific record in a file to appear in the database table (rather than just the fields from the largest record)
  • Give a name to the XFD file itself

Directives are always placed within a COBOL FD. They do not affect Procedure Division I/O statements, and they do not change your COBOL data in any way. The only exception to this is the CREATEXFD directive, which must be placed before the first COBOL SELECT statement.

Note: If you are going to access your COBOL data from an ODBC- or JDBC-enabled application, each field in the application must correspond to a data item in your COBOL FD or XFD. To ensure that this is the case, you may need to use the NAME directive to add fields to the XFD.
  • Sample Files and Examples
  • Directive Syntax
  • Supported Directives
Parent topic: Preparing Your COBOL
Related information
CREATEXFD directive
NAME directive


Sample Files and Examples

In addition to describing the directives you can include in your COBOL file's FD section, this section provides sample code and examples based on the sample files, animals.cbl and file_dir.cbl, that come with AcuXDBC. (These files are located with the other files that make up the AcuXDBC installation.)

The files were compiled with the following command:

ccbl32 -fa animals.cbl

After successful compilation, the Vision file was created with the following command:

wrun32 animals

The tables resulting from these files are displayed in Microsoft Access 2000. See Working with Windows and Java Applications for information on bringing external data into the database.

The following code is the FD for the source animals.cbl file. Note that this is a highly simplified example intended only to demonstrate the use of directives. You would not insert data into a table with this design.

       FILE SECTION.
       FD  jr-file.
       01  jr-record.
           03  animal-info.
               05  patient-id                  pic x(5).
               05  atype                       pic x.
               05  ctype redefines atype       pic x.
               05  dtype redefines atype       pic x.
               05  otype redefines atype       pic x.
           03  owner-info.
               05  phone                       pic x(8).
               05  owner                       pic x(30).
           03  financial.
               05  acct_no.
                   10  year                    pic x(2).
                   10  seq_no                  pic x(4).
               05  last_visit.
                   10  yyyy                    pic 9(4).
                   10  mm                      pic 9(2).
                   10  dd                      pic 9(2).
               05  fee                         pic s9(5)v99.
               05  date_paid                   pic 9(8).

With each directive, a new line is added to the code. Examples in each directive description (follow the links in the table below) show the code and also the resulting database table, where appropriate. If you are working on a different system, you may use different commands to compile animals.cbl and to create the COBOL file. If you are using an application other than Microsoft Access 2000, the resulting tables may appear different.

The following figure illustrates a table that was imported into Microsoft Access 2000 based on the FD above. You may want to note the changes to this table as directives are added to the FD in the directive descriptions.

The file file_dir.cbl is used only when describing the FILE directive. The sample source code is shown in the topic FILE directive.

Parent topic: Using XFD Directives


Directive Syntax

Place each directive on a line by itself, immediately before the COBOL line to which it pertains.

Introduce each directive with a $ in the Indicator Area (column 7 in standard ANSI source format), followed immediately by the letters XFD, and then the directive itself. There must be no space between the $ and the XFD. Spaces are permitted elsewhere on the line as separators, however. For example, the NAME directive looks like this:

$XFD  NAME = COLOR

An alternate ANSI-compliant way to introduce a directive is with an asterisk (*) in the Indicator Area. In this case, you begin the directive with the letters "XFD" and enclose the entire directive in double parentheses. For example:

*(( XFD  NAME = COLOR ))

There must be no space between the asterisk and the double left parentheses. Spaces are permitted elsewhere on the line as separators.

You may use either form of the directive syntax (or both) in your applications.

Two or more directives that pertain to the same line of COBOL code may be combined on one comment line. The directives should be separated by a space or a comma. For example, to specify both USE GROUP and NUMERIC at the same time, you would add this line:

$XFD USE GROUP, NUMERIC

or

*(( XFD USE GROUP, NUMERIC ))
  • Line Continuation for Complex XFDs
    Syntax for XFD directives that exceed one line.
Parent topic: Using XFD Directives


Supported Directives

AcuXDBC supports the following directives. The table supplies a brief description of each directive; for complete descriptions and examples, follow the links.

For more information, see Directive Syntax.

Note: The examples included with the complete descriptions of the directives may be cumulative. In other words, beginning with ALPHA and continuing alphabetically through the list of directives, some examples show the cumulative effects of the preceding directives. Therefore, your table may not appear the same as the table in an example if you haven't applied the preceding directives. The example for the WHEN directive includes most of the preceding directives.
Directive | Description
ALPHA | Allows you to treat a data item as alphanumeric text in the database, when it is declared as numeric in the COBOL program
BINARY | Specifies that the data in the field could be alphanumeric data of any classification
COMMENT | Allows you to include comments in an XFD file
DATE | Creates a map between the ODBC or JDBC application date fields and COBOL numeric fields
FILE | Supplies a starting name from which the XFD file name is formed
HIDDEN | Allows you to hide specific data items from end users, while providing normal access to other data items
NAME | Assigns a database field name to the data item defined on the next line
NUMERIC | Allows you to treat a data item as an unsigned integer when it is declared as alphanumeric
READ-ONLY | Allows you to make some fields/columns of data read-only, while preserving normal access to other fields/columns
SUBTABLE | Modifies the way fields that appear in an OCCURS clause are processed, resulting in the creation of subtables
USE GROUP | Indicates that the following group item is to correspond to a column as if it were an elementary item of the same width
VAR_LENGTH | Requests that the data item that immediately follows the directive be assigned a type that implies variable length
WHEN | Includes multiple record definitions or REDEFINES in the XFD for use with your application
XSL | Allows you to include a stylesheet reference in the XML header
  • ALPHA directive
  • BINARY directive
  • COMMENT directive
  • DATE directive
  • FILE directive
  • HIDDEN directive
  • NAME directive
  • NUMERIC directive
  • READ-ONLY directive
  • SUBTABLE directive
  • USE GROUP directive
  • VAR_LENGTH directive
  • WHEN directive
  • XSL directive
Parent topic: Using XFD Directives


ALPHA directive

The ALPHA directive allows you to treat a data item as alphanumeric text in the database, when it is declared as numeric in the COBOL program.

Syntax

$XFD ALPHA

or

*(( XFD ALPHA ))

This is especially useful when you have numeric keys in which you occasionally store non-numeric data, such as LOW-VALUES or special codes. In this situation, treating the field as alphanumeric allows you to move any kind of data to it.

Example

01  code-record.
    03  code-key.
        05  code-num      pic 9(5).

In the database, group items are disregarded, so CODE-NUM is the actual key field. Suppose you needed to move a non-numeric value to the key:

MOVE "C0531" TO CODE-KEY.
WRITE CODE-RECORD.

In this case, the results are not well-defined because a non-numeric value has been moved into a numeric field. The database might very well reject the record.

One way to solve this problem is to use the ALPHA directive. This causes the corresponding database field to accept alphanumeric data:

 01  code-record.
$XFD ALPHA
     03  code-key.
         05  code-num      pic 9(5).

As an alternative, you could specify the USE GROUP directive on the line before code-key. The USE GROUP directive implies that the field is alphanumeric.

Parent topic: Supported Directives
Related information
USE GROUP directive


BINARY directive

The BINARY directive is used to specify that the data in the field could be alphanumeric data of any classification. Absolutely any data is allowed.

The BINARY directive cannot be used in combination with the VAR_LENGTH directive.

The method of storing fields declared as binary is database-specific. For example, Oracle uses the data type raw for the field.

Syntax

$XFD BINARY

or

*(( XFD BINARY ))

Example

You might use this directive when you need to store a key that contains LOW-VALUES; COBOL allows a numeric field to contain LOW or HIGH values, but these are invalid for a numeric field in the RDBMS:

 01  code-record.
     03  code-key.
         05  code-indic          pic x.
$XFD BINARY
         05  code-num            pic 9(5).
         05  code-suffix         pic x(3).
             .
             .
             .
 move low-values to code-num.
Parent topic: Supported Directives
Related information
VAR_LENGTH directive


COMMENT directive

The COMMENT directive allows you to include comments in an XFD file. Because the information is embedded in a comment, it doesn't interfere with processing by AcuXDBC. Each comment entered with this directive appears in the XFD file with the symbol "#" in column 1. This information will appear in only the XFD file. It will not be imported into the system catalog by xdbcutil.

Syntax

$XFD COMMENT text

or

*(( XFD COMMENT text ))

Example

The following FD includes a comment:

       FILE SECTION.
       FD  qa-file.
      $XFD COMMENT  This sample file demonstrates directives.
       01  qa-record.
           03  animal-info.
               05  patient-id                  pic x(5).
               05  atype                       pic x.
               05  ctype redefines atype       pic x.
               05  dtype redefines atype       pic x.
               05  otype redefines atype       pic x.
           03  owner-info.
               05  phone                       pic x(8).
               05  owner                       pic x(30).
           03  financial.
               05  acct_no.
                   10  year                    pic x(2).
                   10  seq_no                  pic x(4).
               05  last_visit.
                   10  yyyy                    pic 9(4).
                   10  mm                      pic 9(2).
                   10  dd                      pic 9(2).
               05  fee                         pic s9(5)v99.
               05  date_paid                   pic 9(8).

The following line appears in the animals.xfd file:

<!--  This sample file demonstrates directives. -->
Parent topic: Supported Directives


DATE directive

The DATE directive creates a map between the ODBC/JDBC application date fields and COBOL numeric fields. Because there's no COBOL syntax that identifies a field as a date, you should add this directive to differentiate dates from other numbers. This way, when a user of a Windows or Java application requests date information, AcuXDBC can respond properly.

Syntax

$XFD DATE[=date-format-string optional]

or

*(( XFD DATE[=date-format-string optional]))

The DATE directive implies the NUMERIC directive.

The date-format-string is a description of the desired date format, composed of characters from the following list:

Y | year (2- or 4-digit)
M | month (01 to 12)
D | day of month (01 to 31)
J | Julian day (00000000 to 99999999)
E | day of year (001 to 366)
H | hour (00 to 23)
N | minute
S | second
T | hundredth of a second
  • If date-format-string contains only date characters (Y, M, D, E, or J), the string is treated as a DATE variable
  • If date-format-string contains only time characters (H, N, S), it is treated as a TIME variable
  • If date-format-string contains any combination of date and time characters, or if it contains fractional seconds (T), it is treated as a TIMESTAMP variable
Note: Some applications have difficulty processing a date-format-string that contains fractional seconds (for example: HHNNSSTT). If you are using such an application, modify strings containing fractions to be purely numeric.

Each character in a date-format-string can be considered a placeholder that represents the type of information stored at that location. The characters also determine how many digits will be used for each type of data. Any other characters cause the date-format-string to be invalid. Invalid formats are automatically treated as numeric data.

For example, although you would typically represent the month with two digits, if you specify MMM as part of your date format, the resulting date uses three digits for the month, left-zero-filling the value. If the month is given as M, the resulting date uses a single digit and truncates on the left.

If you don't specify a date-format-string, the default is YYMMDD if the field has six digits, or YYYYMMDD if the field has eight digits.

Sometimes it's desirable to have incomplete date types, for example, to have YYYYMM to simply store the year and month. AcuXDBC defaults the month and day to 1, so that incomplete types will be valid. Note thatAcuXDBC can handle incomplete date types, but if you have a complete type and invalid date data, AcuXDBC cannot handle the date.

  • Julian Dates
  • Group Items
  • Example 1 - Elementary Data Item, DATE Directive
  • Example 2 - Group Data Item, DATE and USE GROUP Directives
  • FY and RY Date Formats
Parent topic: Supported Directives
Related information
GRANT (Object Privileges) command
INVALID_NUMERIC_DATA configuration variable
NUMERIC directive
USE GROUP directive


Julian Dates

Because the definition of Julian day varies, the DATE directive offers a great deal of flexibility for representing Julian dates. Many source books define the Julian day as the day of the year, with January 1st being 001, January 2nd being 002, and so forth. If you want to use this definition for Julian day, simply use EEE (day of year) in your date formats.

Other reference books define the Julian day as the number of days since some specific "base date" in the past. This definition is represented in the DATE directive with the letter "J" (for example, a six-digit date field would be preceded with the directive $XFD DATE=JJJJJJ). The default base date for this form of Julian date is January 1, 1900.

You can define your own base date for Julian date calculations by setting the JULIAN_BASE_DATE configuration variable in your acuxdbc.cfg configuration file.

Parent topic: DATE directive


Group Items

You may place the DATE directive in front of a group item, as long as you also use the USE GROUP directive.

Example

The source code for the animals table contains a group item for the date of the animal's last visit, and an elementary item for the date of the last payment:

          05  last_visit.
              10  yyyy                    pic 9(4).
              10  mm                      pic 9(2).
              10  dd                      pic 9(2).
          05  fee                         pic s9(5)v99.
          05  date_paid                   pic 9(8).

The date portions of a database table based on source code with this FD look similar to this illustration. All of these date-related fields are of type NUMBER in the (Access) database.

The examples that follow build on this source code.

Parent topic: DATE directive


Example 1 - Elementary Data Item, DATE Directive

The date_paid field is defined in the sample file as an elementary item of type NUMBER. Inserting the DATE directive before this line maps the type to DATE/TIME (in Access) and changes the format of the date in the table, as shown below.

       FILE SECTION.
       FD  qa-file.
      $XFD COMMENT  This sample file demonstrates directives.
       01  qa-record.
           03  animal-info.
               05  patient-id                  pic x(5).
               05  atype                       pic x.
               05  ctype redefines atype       pic x.
               05  dtype redefines atype       pic x.
               05  otype redefines atype       pic x.
           03  owner-info.
               05  phone                       pic x(8).
               05  owner                       pic x(30).
           03  financial.
               05  acct_no.
                   10  year                    pic x(2).
                   10  seq_no                  pic x(4).
               05  last_visit.
                   10  yyyy                    pic 9(4).
                   10  mm                      pic 9(2).
                   10  dd                      pic 9(2).
               05  fee                         pic s9(5)v99.
      $XFD DATE=YYYYMMDD
               05  date_paid                   pic 9(8).

The resulting entries in a database table look similar to the following illustration:

Parent topic: DATE directive


Example 2 - Group Data Item, DATE and USE GROUP Directives

If your date information is defined as a group item, you must use both the DATE and USE GROUP directives to map your COBOL numeric data items to SQL date fields. Insert the directives on the line preceding the group item.

       FILE SECTION.
       FD  qa-file.
      $XFD COMMENT  This sample file demonstrates directives.
       01  qa-record.
           03  animal-info.
               05  patient-id                  pic x(5).
               05  atype                       pic x.
               05  ctype redefines atype       pic x.
               05  dtype redefines atype       pic x.
               05  otype redefines atype       pic x.
           03  owner-info.
               05  phone                       pic x(8).
               05  owner                       pic x(30).
           03  financial.
               05  acct_no.
                   10  year                    pic x(2).
                   10  seq_no                  pic x(4).
      $XFD DATE=YYYYMMDD, USE GROUP
               05  last_visit.
                   10  yyyy                    pic 9(4).
                   10  mm                      pic 9(2).
                   10  dd                      pic 9(2).
               05  fee                         pic s9(5)v99.
      $XFD DATE=YYYYMMDD
               05  date_paid                   pic 9(8).

The resulting table now has a column with the name of the group item ("last_visit"), which is defined as type DATE/TIME (in Access).

Parent topic: DATE directive


FY and RY Date Formats

The FY and RY date format characters have very precise requirements and are used to handle a specific case in which eight-digit dates are expressed in six characters.

Instead of YYYY or YY, you can specify FY to mean that the first character of the year specifies the decade instead of the “tens” year. The decade can be a character between space (“ “) and 1 (inclusive). For the characters 0 through 9 to be treated as decades in the 20th century, the decade characters have the following meaning:

 | 00 | 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90
1700 |  |  |  |  | spc | ! | " | # | $ | %
1800 | & | ' | ( | ) | * | + | , | - | . | /
1900 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
2000 | : | ; | < | = | > | ? | @ | A | B | C
2010 | D | E | F | G | H | I |  |  |  |

This means that a date of ?70210 is converted to 20570210, or February 10, 2057. The range of valid dates is 00101 (Jan 1, 1740) through I91231 (Dec 31, 2159).

Instead of YYYY or YY, you can also specify RY to mean that the first character of the year specifies the decade and that the entire date is to be 9s complement (to be able to sort dates in reverse order). Note that the entire date and time is treated as a 9s complement number in this case. The decade characters have the following meaning:

 | 00 | 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90
1700 |  |  |  |  | I | H | G | F | E | D
1800 | C | B | A | @ | ? | > | = | < | ; | :
1900 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
2000 | / | . | - | , | + | * | ) | ( | ' | &
2010 | % | $ | # | " | ! | spc |  |  |  |

The date 20570210 is now specified with *29789. The range of valid dates is I99898 (Jan 1, 1740) through 08768 (Dec 31, 2159), the same valid range as when using F instead of R.

While using F and R before month, day, hour, or any other format specifier does not generate a compile error for the XFD, the results are undefined at runtime.

Note that if you use these format specifiers with Acu4GL or Database Connectors, the actual date is written to the database, not the encoded date. That means that the R specifier is not very useful in this scenario (you won’t be able to read forward through a file in reverse date order). This format specifier is more useful with AcuXDBC, where the data is in indexed file format.

Parent topic: DATE directive


FILE directive

The FILE directive supplies a starting name from which the XFD file name is formed. This directive is required only when the file name in the COBOL code is nonspecific. For example, you would use this directive when the SELECT for the file has a variable ASSIGN name (ASSIGN TO variable_name). In this situation, the interface cannot form a file name automatically, and you must provide a name.

You can encounter this situation when you are using AcuXDBC's file alias feature. For example, the description section of your COBOL file may reference multiple data files with the same format. Each of these data files represents a distinct table in the database, but one XFD file describes them all.

A starting name is a short file name that serves as the basis for the XFD name.

Syntax

$XFD FILE=name

or

*(( XFD FILE=name ))

This directive must appear on the line immediately preceding the file's FD.

Example

The sample file file_dir.cbl contains code that demonstrates the FILE directive. Suppose your SELECT statement has a variable ASSIGN name such as the one shown here:

SELECT work-file
     ASSIGN to pet-file.

You must add the FILE directive as shown here:

       FILE-CONTROL.
           SELECT work-file
              ASSIGN TO pet-file
              ORGANIZATION IS INDEXED
              ACCESS IS DYNAMIC
              RECORD KEY IS type-id
              FILE STATUS IS qa-file-status.
       DATA DIVISION.
       FILE SECTION.
      $XFD FILE=patients
       FD  work-file.
       01  pet-record.
           05  type-id.
               10  atype            pic x.
               10  ano              pic 99.
           05  owner                pic x(30).
           05  breed                pic x(25).
           05  gender               pic x.
       WORKING-STORAGE SECTION.
       01  pet-file                 pic x(8).
       01  qa-file-status           pic xx.

Note that after compilation, the data directory now contains the files file_dir.acu and patients.xfd. Because the FILE directive assigns the name of the XFD file, this is different from previous examples in which both the .scu file and the .xfd file took the same base name as the .cbl file.

See Setting Up File Aliases for information on file alias and how to load XFDs to different tables and databases using the system catalog utility program (xdbcutil).

Parent topic: Supported Directives
Related information
NAME directive


HIDDEN directive

The HIDDEN directive allows you to hide specific data items from end users, while providing normal access to other data items. When you place this directive immediately before a data item in an FD, that item is hidden from end users. Field names affected by the HIDDEN directive are literally not placed into the system catalog. The user can neither read, modify, nor even know that this field exists.

Note: An alternative is to create a VIEW of the table that does not include the field. To do so, use the CREATE VIEW command.

The HIDDEN directive applies to only the elementary data item it precedes. Subsequent data items revert to normal read access. Note that you cannot apply the HIDDEN directive to group items and you cannot hide the key.

If you use the INSERT command on a table that has hidden fields, spaces (hex value 20) are put into the hidden fields, whether they are numeric or alphanumeric.

Syntax

$XFD HIDDEN

or

*(( XFD HIDDEN ))

In the following FD, "fee" is hidden from users in the resulting table.

       FILE SECTION.
       FD  jr-file.
      $XFD COMMENT  This sample file demonstrates directives.
       01  jr-record.
           03  animal-info.
               05  patient-id                  pic x(5).
               05  atype                       pic x.
               05  ctype redefines atype       pic x.
               05  dtype redefines atype       pic x.
               05  otype redefines atype       pic x.
           03  owner-info.
               05  phone                       pic x(8).
               05  owner                       pic x(30).
           03  financial.
               05  acct_no.
                   10  year                    pic x(2).
                   10  seq_no                  pic x(4).
      $XFD DATE=YYYYMMDD, USE GROUP
               05  last_visit.
                   10  yyyy                    pic 9(4).
                   10  mm                      pic 9(2).
                   10  dd                      pic 9(2).
      $XFD HIDDEN
               05  fee                         pic s9(5)v99.
      $XFD DATE=YYYYMMDD
               05  date_paid                   pic 9(8).

Note that in the resulting table, the "fee" column no longer appears:

This directive is useful for hiding data like passwords, telephone numbers, and financial information — whatever information you don't want users to see.

You cannot include a HIDDEN field in a WHEN directive with a TABLENAME clause, because of the complexities of editing or adding records. In this situation, you must add the data, but since the field is hidden, you cannot see it and could add a value that would cause unexpected results.

Parent topic: Supported Directives
Related information
CREATE VIEW command
INSERT command
WHEN directive


NAME directive

The NAME directive assigns a database field name to the data item defined on the next line. You can use the NAME directive to prevent duplicate field names.

Syntax

$XFD NAME=fieldname

or

*(( XFD NAME=fieldname ))

Examples

This directive has several uses, as shown in the following examples.

Example 1 — Duplicate Names for Data Items in a Single Record

Within a table, all field names must be unique. (Multiple database tables may include the same field name, but duplicates may not exist within a single table.) Unique field names are not required in COBOL, because names can be qualified by group items. For example, this is acceptable in COBOL:

               10  last_visit.
                    15  mm                  pic 99.
                    15  dd                  pic 99.
                    15  yy                  pic 99.
               10  last_payment.
                    15  mm                  pic 99.
                    15  dd                  pic 99.
                    15  yy                  pic 99.

It is not, however, acceptable for a database table to have two columns with the same name. In fact, you will not be able to compile and generate an XFD with the above source code in your program.

You need not change the field names in your COBOL program to make them accessible as a database column. A preferable option might be to use the NAME directive to provide unique names for the fields. The NAME directive has the advantage of being placed in your COBOL program as a comment, which allows you to change the database name of the column without impacting the existing code or functionality of your COBOL application.

Although this is not included in the sample code, here is an example of using the NAME directive when you have duplicate field names:

               10  last_visit.
                    15  mm                  pic 99.
                    15  dd                  pic 99.
                    15  yy                  pic 99.
               10  last_payment.
               $XFD NAME=MONTH_PD
                    15  mm                  pic 99.
               $XFD NAME=DAY_PD
                    15  dd                  pic 99.
               $XFD NAME=YEAR_PD
                    15  yy                  pic 99.

The "dates" portion of the indexed file database table will look like this:

mm | dd | yy | MONTH_PD | DAY_PD | YEAR_PD
06 | 18 | 02 | 07 | 04 | 02

Example 2 — Assigning Shorter Names

You may want to use the NAME directive to assign shorter names than those used in your COBOL programs. This makes the formation of interactive SQL queries easier and quicker. For example:

       FILE SECTION.
       FD  jr-file.
      $XFD COMMENT  This sample file demonstrates directives.
       01  jr-record.
           03  animal-info.
      $XFD NAME=PATIENT
               05  patient-id                  pic x(5).
               05  atype                       pic x.
               05  ctype redefines atype       pic x.
               05  dtype redefines atype       pic x.
               05  otype redefines atype       pic x.
           03  owner-info.
               05  phone                       pic x(8).
               05  owner                       pic x(30).
           03  financial.
               05  acct_no.
                   10  year                    pic x(2).
                   10  seq_no                  pic x(4).
      $XFD DATE=mmddyyyy, USE GROUP
               05  last_visit.
                   10  mm                      pic 9(2).
                   10  dd                      pic 9(2).
                   10  yyyy                    pic 9(4).
      $XFD HIDDEN
               05  fee                         pic s9(5)v99.

This directive causes the XFD to map PATIENT-ID to PATIENT in the database.

Additional Examples

Here are some other cases in which you may consider using the NAME directive. In all of these instances, note that your COBOL data does not change. The new name appears only in the indexed file database and in any tables that result from your COBOL code.

  • If your COBOL data contains field names that are identical within the first 18 characters

    Each time you compile your program and specify the CREATEXFD directive, any field names longer than 18 characters are checked for uniqueness within the first 18. If you have names that are identical within the first 18 characters, or that would not be meaningful if shortened to the first 18 characters, use the NAME directive to assign them different database field names.

  • If you map COBOL data items to Windows or Java applications

    If a column name in your Windows or Java application does not match the name used in your COBOL FD, you can use a NAME directive to associate the two names.

  • If a field name in your COBOL data begins with a numeric character

    Because Windows and Java applications communicate using SQL, the program typically generates a syntax error when it encounters a column name that begins with a numeric character. If your COBOL program uses field names that begin with a numeric character, use the NAME directive to assign a different name for use with your Windows and Java applications.

  • If you want to include a "FILLER" item
  • If your COBOL name is an SQL reserved word
Parent topic: Supported Directives


NUMERIC directive

The NUMERIC directive allows you to treat a data item as an unsigned integer when it is declared as alphanumeric. You might use this when the data stored in the item is always numeric.

Syntax

$XFD NUMERIC

or

*(( XFD NUMERIC ))

Example

The PATIENT-ID field (now appearing in the database table as the PATIENT column) is defined in the source code as being a text field. Since this field will always contain a number, you may want to define it in the database table as numeric. (Note the use of two directives for the same data item here.)

       FILE SECTION.
       FD  jr-file.
      $XFD COMMENT  This sample file demonstrates directives.
       01  jr-record.
           03  animal-info.
      $XFD NAME=PATIENT, NUMERIC
               05  patient-id                  pic x(5).
               05  atype                       pic x.
               05  ctype redefines atype       pic x.
               05  dtype redefines atype       pic x.
               05  otype redefines atype       pic x.
           03  owner-info.
               05  phone                       pic x(8).
               05  owner                       pic x(30).
           03  financial.
               05  acct_no.
                   10  year                    pic x(2).
                   10  seq_no                  pic x(4).
      $XFD DATE=YYYYMMDD, USE GROUP
               05  last_visit.
                   10  yyyy                    pic 9(4).
                   10  mm                      pic 9(2).
                   10  dd                      pic 9(2).
      $XFD HIDDEN
               05  fee                         pic s9(5)v99.

The following table is the result, and, in the database, PATIENT is now of type NUMBER.

Parent topic: Supported Directives
Related information
INVALID_NUMERIC_DATA configuration variable
NULL_NUMERIC_READ configuration variable
NULL_NUMERIC_WRITE configuration variable


READ-ONLY directive

The READ-ONLY directive allows you to make some fields (columns) of data read-only, while preserving normal access to other fields/columns. When placed immediately before a data item in an FD, this directive assigns the read-only attribute to the item. The read-only attribute applies only to elementary items and not to group items. Subsequent data items return to normal read-write access.

Note: Use the READ-ONLY directive if you want to tag fields (columns) of data as read-only. Use the READ_ONLY configuration variable if you want to designate all of the files belonging to a data source name (DSN) as read-only.

Syntax

$XFD READ-ONLY

or

*(( XFD READ-ONLY ))

In the code creating the animals table, the owner data item has been designated as read-only. The code is:

       FILE SECTION.
       FD  jr-file.
      $XFD COMMENT  This sample file demonstrates directives.
       01  jr-record.
           03  animal-info.
      $XFD NAME=PATIENT, NUMERIC
               05  patient-id                  pic x(5).
               05  atype                       pic x.
               05  ctype redefines atype       pic x.
               05  dtype redefines atype       pic x.
               05  otype redefines atype       pic x.
           03  owner-info.
               05  phone                       pic x(8).
      $XFD READ-ONLY
               05  owner                       pic x(30).
           03  financial.
               05  acct_no.
                   10  year                    pic x(2).
                   10  seq_no                  pic x(4).
      $XFD DATE=YYYYMMDD, USE GROUP
               05  last_visit.
                   10  yyyy                    pic 9(4).
                   10  mm                      pic 9(2).
                   10  dd                      pic 9(2).
      $XFD HIDDEN
               05  fee                         pic s9(5)v99.
      $XFD DATE=MMDDYYYY
               05  date_paid                   pic 9(8).

In the database table, the owner column looks the same as the other columns. However, if users attempt to modify data in the owner column, they receive a message telling them that the update on a linked table failed.

Parent topic: Supported Directives
Related information
READ_ONLY configuration variable
GRANT (Object Privileges) command
INSERT command


SUBTABLE directive

This directive modifies the way fields that appear in an OCCURS clause are processed, resulting in the creation of subtables.This directive instructs the XFD parsing routines not to append the occurrence number to the field name, as would normally take place with OCCURS clauses, but instead to store just the base name along with the name of the subtable as written in the XFD file. (Note that this directive is not supported by Acu4GL .)

The resulting tables will appear as multiple tables in a primary/foreign key relation based on the base table's primary key.

Syntax

$XFD SUBTABLE=name

or

*(( XFD SUBTABLE=name ))

Example

$XFD SUBTABLE=subtab1
    03 employee-table occurs 10 times.
        05 employee-number           pic 9(3).
Parent topic: Supported Directives
Related information
OCCURS Clause


USE GROUP directive

Generally, only elementary data items correspond to columns. The USE GROUP directive indicates that the following group item is to correspond to a column as if it were an elementary item of the same width. This is necessary if the item is stored in your database as a group, rather than as individual fields.

By default, the USE GROUP directive implies that the consolidated field is alphanumeric. If you want a numeric field, add the word NUMERIC at the end of the directive.

Grouping data items in this way is efficient if the groups are usually processed as units.

Syntax

$XFD USE GROUP

or

Example

You might use this directive with fields like multi-part account numbers or department numbers, or keys that are referenced as a unit but not by their individual pieces. In the sample file, you can group the year and seq_no fields to make a single account number column (acct_no), as shown below:

       FILE SECTION.
       FD  jr-file.
      $XFD COMMENT  This sample file demonstrates directives.
       01  jr-record.
           03  animal-info.
      $XFD NAME=PATIENT, NUMERIC
               05  patient-id                  pic x(5).
               05  atype                       pic x.
               05  ctype redefines atype       pic x.
               05  dtype redefines atype       pic x.
               05  otype redefines atype       pic x.
           03  owner-info.
               05  phone                       pic x(8).
      $XFD READ-ONLY
               05  owner                       pic x(30).
           03  financial.
      $XFD USE GROUP
               05  acct_no.
                   10  year                    pic x(2).
                   10  seq_no                  pic x(4).
      $XFD, USE GROUP, DATE=YYYYMMDD
               05  last_visit.
                   10  yyyy                    pic 9(4).
                   10  mm                      pic 9(2).
                   10  dd                      pic 9(2).
      $XFD HIDDEN
               05  fee                         pic s9(5)v99.

The resulting table looks similar to this:

If you are using an existing database in which certain fields are grouped, they must also be grouped in your COBOL FD.

Why group fields?

If the database does not yet exist, keep in mind that combining fields into groups typically improves execution speed. Whether to group fields or not also depends on how you want to process them. Do you always store and use the fields together? Someone who really knows how the data is being used might help to identify groups of fields that can be combined to speed processing.

Once you have grouped fields, you can apply other directives to them, such as DATE, NUMERIC, and ALPHA.

Parent topic: Supported Directives
Related information
ALPHA directive
DATE directive
NUMERIC directive


VAR_LENGTH directive

By default, the compiler generates fixed-length fields in the XFD. The VAR_LENGTH directive requests that the data item that immediately follows the directive be assigned a type that implies variable length, if possible. This can save considerable space in your database.

The VAR_LENGTH directive cannot be used in combination with the BINARY directive.

The precise variable type that is assigned to the data item depends on which RDBMS is in use. Possible variable types that might be assigned are VARCHAR and VARBINARY.

Syntax

$XFD VAR_LENGTH

Example

For example, the directive in the following code indicates that the employee-name field should be entered into the database as a VARCHAR data item.

 $XFD  VAR_LENGTH
      03  employee-notes      pic x(300).
Parent topic: Supported Directives
Related information
BINARY directive


WHEN directive

Use the WHEN directive when you want to include multiple record definitions or REDEFINES in the XFD. The WHEN directive typically is used to force certain columns of data to be available that wouldn't be available otherwise. See REDEFINES Clause for information about REDEFINES.

Note: You cannot use the WHEN directive in an OCCURS clause. See OCCURS Clause for information about the OCCURS clause.

Recall that the key fields and the fields from the largest record are automatically included as explicit columns in the indexed file database table. So you should use the WHEN directive if you want the user to be able to access all the data in the COBOL file in a way that is understandable. See How XFDs are Formed for details about how fields are included in the database table.

WHEN declares that the field (or subordinate fields, if it is a group item) that immediately follows the directive must appear as a column (or columns) in the indexed file database table. It also states one condition under which the columns are to be used. The WHEN directive thus guarantees that the fields will be explicitly included in the table (as long as they aren't FILLER and don't occupy the same area as key fields).

Syntax

$XFD WHEN field operator value

or

*(( XFD WHEN field operator value ))
where
field Specifies the name of a data item that corresponds to a field; if there is a NAME directive for this data item, the name used in the WHEN directive is the name given to the item by the NAME directive, not its COBOL name
operator Specifies the relation between the field value and the alphanumeric literal that satisfies the condition; operator can be one of the following:
  • = - The field value is equal to the literal value
  • != - The field value is not equal to the literal value
  • > - The field value is greater than the literal value
  • < - The field value is less than the literal value
  • >= - The field value is greater than or equal to the literal value
  • < = - The field value is less than or equal to the literal value
value Is one of the following:
  • An alphanumeric literal (if the field is alphanumeric)
  • A numeric literal (if the field is numeric)
  • The special word other; other is used only with the = operator:
    $XFD WHEN field = other
    other is true only when all other conditions for the same field are false; for example, if your FD contains the following lines of code:
          $XFD WHEN ATYPE = "C"
      $XFD WHEN ATYPE = "D"
      $XFD WHEN ATYPE = other
    the other condition holds true only if both atype = 'c' and atype = 'd' are false

Example

The following code is an example of using the WHEN directive.
       01  key-record.
      * employee-number is a key data item
           03  employee-number     pic 99999.
           03  emp-type            pic x.
      $xfd when emp-type="1"
      * record has this form when emp-type="1"
       01  data-record-1.
           03  filler              pic 99999.
           03  filler              pic x.
           03  name-1              pic x(35).
           03  pay-rate-1          pic 99.99.
      $xfd when emp-type="2"
      * record has this form when emp-type="2"
       01  data-record-2
           03  filler              pic 99999.
           03  filler              pic x.
           03  name-2              pic x(35).
           03  pay-rate-2          pic 999.99.
           03  subordinates        pic 999.
           03  position            pic x(50).
The effect of these directives is to force emp-type, name-1, and pay-rate-1 to correspond to columns, even though they are not in the largest record description. Therefore, the corresponding table has the following columns:
  • EMPLOYEE_NUMBER
  • EMP_TYPE
  • NAME_1
  • PAY_RATE_1
  • NAME_2
  • PAY_RATE_2
  • SUBORDINATES
  • POSITION

If each data item is subordinate to at most one WHEN directive, as in this example, the following occurs:

  • When the condition is true, the data item appears in the database table in the usual way
  • When the condition is false, the special value NULL appears in the corresponding column in the database table, and any value written into the column in the database table is not written to the COBOL data file. The exact meaning of a NULL value depends on the database. In some databases, NULL is a blank or zero value. In others, NULL is a special value on which no arithmetic or string operations can be performed, although a value can be tested to determine whether it is NULL

If a data item is subordinate to two or more WHEN directives, the following applies:

  • When all conditions are true, the data item appears in the database table in the usual way
  • When at least one condition is false, the special value NULL appears in the corresponding column in the database table, and any value written into the column in the database table is not written to the COBOL data file
  • WHEN Complex Expressions
    Syntax and rules for using complex expressions with WHEN directives.
  • WHEN Directive with TABLENAME Clause
Parent topic: Supported Directives
Related information
NAME directive


WHEN Directive with TABLENAME Clause

If you assign a table name, a VIEW will be created that contains the columns subordinate to the WHEN directive and any columns the WHEN directive depends on.

When an XFD names a condition, such as WHEN, AcuXDBC produces multiple tables from a single XFD file. One table is given the current name of the file, while the VIEWS resulting from any named conditions are given the name specified with the tablename parameter (see syntax below).

You cannot include a HIDDEN field in a WHEN directive with a TABLENAME clause, because of the complexities of editing or adding records. In such a situation, you must add the data, but since the field is hidden, you cannot see it and may add a value that would cause unexpected results.

If an XFD file in an alias contains WHEN directives with TABLENAME phrases, the corresponding tables are defined in the usual way, using the data file specified by its physical file name. You can define two or more file aliases with the same XFD file, but with different physical file names if the XFD file does not contain any WHEN directives with the TABLENAME clause.

Syntax

$XFD WHEN field operator value TABLENAME=new_table_name

or

*(( XFD WHEN field operator value TABLENAME=new_table_name ))

The syntax is essentially the same as for the WHEN directive alone, with the addition of the TABLENAME clause. The word "OTHER" can be used only with "=". It means "use the following field(s) only if none of the other WHEN condition(s) listed for the same field is met." In other words, this condition is true only if all other conditions for the same field are false.

Note: If a WHEN condition sets a TABLENAME, any WHEN OTHER condition specified for the same WHEN directive must also set a TABLENAME.

For example:

.
.
assign to "ar_table"
.
.
01 ar-code-type.
$xfd  when ar-code-type = "s" tablename=ship
     03  ship-code-record     pic x(4).
$xfd  when ar-code-type = "b" tablename=backorder
     03  backorder-code-record redefines
         ship-code-record.
$xfd  when ar-code-type = other
     03  obsolete-code-record redefines
         ship-code-record.

If you tried to connect to the system catalog through a program like Access, you would see a table named ar_table, and two views named ship, and backorder. If you placed $XFD READ-ONLY TABLE immediately before the

xfd  when ar-code-type = "s" tablename=ship
line, the ship view and ar_table would be read-only, but the backorder view would not. If you create the INFORMATION_SCHEMA during AcuXDBC setup, you can see these entries by executing the following SQL query:
SELECT * FROM INFORMATION_SCHEMA.VIEWS;
OTHER may be used before one record definition and may be used once at each level within each record definition.

See Creating a System Catalog and Views for more information.

Note: A WHEN directive with condition OTHER must be used if there is a possibility that the data in the field will not meet any of the explicit conditions specified in the other WHEN directives. If this is not done, results are undefined. Also, WHEN directives may ensure that there will be multiple columns that share the same record area. If you try to modify both columns, an error results.

Example 1

If the following code were compiled without directives, the underlined fields would appear explicitly in the database table. Note that the key fields are included automatically, as are the fields from the largest record. FILLER would be ignored:
01 ar-codes-record.
  03 ar-codes-key.
    05 ar-code-type    pic x.
    05 ar-code-num     pic 999.
01 ship-code-record.
  03 filler            pic x(4).
  03 ship-instruct     pic x(15).
01 terms-code-record.
  03 filler            pic x(4).
  03 terms-rate-1      pic s9v999.
  03 terms-days-1      pic 9(3).
  03 terms-rate-2      pic s9v999.
  03 terms-descript    pic x(15).
If you added the WHEN directive as shown below, it would cause the fields from the SHIP-CODE-RECORD to be included in the database table and would determine when specific database columns would be used. The underlined fields would appear as columns in the database table:
 01 ar-codes-record.
   03 ar-codes-key.
     05 ar-code-type      pic x.
     05 ar-code-num       pic 999.
$xfd when ar-code-type = "s"
 01 ship-code-record.
   03 filler              pic x(4).
   03 ship-instruct       pic x(15).
$xfd when ar-code-type = "t"
 01 terms-code-record.
   03 filler              pic x(4).
   03 terms-rate-1        pic s9v999.
   03 terms-days-1        pic 9(3)
   03 terms-rate-2        pic s9v999.
   03 terms-descript      pic x(15).
FILLER data items don't have unique names and thus are not used to form columns in the database table. You could use the NAME directive to give them a name if you really need to see them in the database table. However, in this example the FILLER data items implicitly redefine key fields. Thus, they would be disregarded even if you provided a name for them.

Example 2

In the following code, in which no WHEN directives are used, the underlined fields will be explicitly named in the database table. (Key fields have the suffix key in their names in this example.)

Note that REDEFINES records simply re-map the same data area and are not explicitly included in the database table by default:

01 archive-record.
  03 filler               pic x(33).
  03 archive-code         pic 9(6).
  03 archive-location     pic 9(2).
  03 filler               pic x(10).
01 master-record.
  03 animal-id-key.
    05 patient-id         pic 9(6).
    05 species-code-type  pic 9(5).
    05 species-name       pic x(6).
  03 service-code-key.
    05 service-code-type  pic 9(6).
    05 service-name       pic x(10).
  03 billing-code.
    05 billing-code-type  pic 9(4).
    05 plan-name          pic x(8).
  03 office-info.
    05 date-in-office     pic 9(8).
    05 served-by-name     pic x(10).
  03 remote-info redefines office-info.
    05 van-id             pic 9(4).
    05 proc-code          pic 9(8).
    05 vet-name           pic x(6).
If you added the WHEN directives shown below, you would add several columns to the database table. The fields that would appear in the table are underlined:
$xfd when animal-id-key = "00000000000000000"
 01 archive-record.
   03 filler              pic x(33).
   03 archive-code        pic 9(6).
   03 archive-location    pic 9(2).
   03 filler              pic x(10).
$xfd when animal-id-key = other
 01 master-record.
$xfd use group
   03 animal-id-key.
     05 patient-id        pic 9(6).
     05 species-code-type pic 9(5).
     05 species-name      pic x(6).
   03 service-code-key.
     05 service-code-type pic 9(6).
     05 service-name      pic x(10).
   03 billing-code.
     05 billing-code-type pic 9(4).
     05 plan-name         pic x(8).
$xfd when billing-code-type = "1440"
   03 office-info.
     05 date-in-office    pic 9(8).
     05 served-by-name    pic x(10).
$xfd when billing-code-type = other
   03 remote-info redefines office-info.
     05 van-id            pic 9(4).
     05 proc-code         pic 9(8).
     05 vet-name          pic x(6).

Example 3

If your application has a REDEFINES whose field names are more meaningful than the fields they redefine, you might consider switching the order of your code, rather than using a WHEN directive. Use the less significant field names in the REDEFINES.

For example, you might change this:

   03 code-info.
     05 filler        pic 9(8).
     05 code-1        pic x(10).
   03 patient-info redefines code-info.
     05 patient-id    pic 9(4).
     05 service-code  pic 9(8).
     05 server-name   pic x(6).
to this:
   03 patient-info.
     05 patient-id    pic 9(4).
     05 service-code  pic 9(8).
     05 server-name   pic x(6).
   03 code-info redefines patient-info.
     05 filler        pic 9(8).
     05 code-1        pic x(10).
The fields that would appear in the database table by default are underlined above. This shows how the column names might become more meaningful when the order is reversed. Your application operates the same either way.
Note: If a WHEN condition is false for a particular record, columns corresponding to data items subject to the WHEN directive and in the row corresponding to the record are set to the special database value NULL This means that there is no value provided for those columns. NULL is not equivalent to zero, and it has special properties in the database. For example, you can select all rows for which a given column is NULL.

Example 4

The COBOL code:
 01  col-type                        pic x.
     03  col-def.
$xfd  when col-type = "a"
          05  def1                   pic x(2).
$xfd  when col-type = "b"
          05  def2 redefines def1    pic 9(2).
results in this database table:
col-type | def1 | def2
a | xx | null
b | null | 10
a | yy | null
Note that if you try to set the first row so that col-type=a,def1=xx, and def2=20, the value of def2 is not stored.
Parent topic: WHEN directive


XSL directive

The XSL directive allows you to include a stylesheet reference in the XML header of your XFDs when they are created.

Syntax

$XFD XSL=stylesheet

or

*(( XFD XSL="stylesheet" ))

where stylesheet is an alphanumeric literal indicating the appropriate stylesheet. The compiler includes the following line in all generated XFD files:

<?xml-stylesheet type="text/xsl" href="stylesheet"?>

For example:

$XFD XSL="myxsl.xsl"

generates this line:

<?xml-stylesheet type="text/xsl" href="myxsl.xsl"?>
Parent topic: Supported Directives


Configuration

This help section describes the various ways you can configure AcuXDBC to suit your needs.

  • Introduction
  • Local Configuration
  • Network Configuration
  • Network Configuration with AcuServer
  • Sample AcuXDBC File
  • Sample net.ini File
  • Configuration Variables
Parent topic: AcuXDBC Version 10.2.0 User's Guide


Introduction

Two configuration files are central to AcuXDBC. By default, they are named acuxdbc.cfg and net.ini. In local configurations, only acuxdbc.cfg is used. Network installations require both configuration files. In this case, acuxdbc.cfg resides on the server and net.ini resides on the client.

Note: acuxdbc.cfg can be named anything. You specify the name of the file when you set up the data source name (DSN) on the client or when using various command-line tools. net.ini, on the other hand, must retain its default name and location.

Configuration files provide you with two main benefits:

  • Universal configuration

    When creating DSNs on network clients, you don't have to configure each DSN individually. Instead, just point to a configuration file on the server.

  • Dynamic configuration

    When you need to change your AcuXDBC configuration, you can modify the configuration file as needed without changing individual DSNs.

Parent topic: Configuration


Local Configuration

You configure the AcuXDBC local server with a configuration file named acuxdbc.cfg. This configuration file is where you define the location of your COBOL data files and system catalog, file case instructions, and other important program functions.

You can create several different configuration files for different purposes. You can set ACUCOBOL specific configuration variables for the AcuXDBC environment in a configuration file called xdbc_env.cfg, which should also reside in the GENESIS_HOME directory. This file is not required.

Configuration files must reside in your AcuXDBC installation directory, specified by the GENESIS_HOME environment variable. You specify the exact name and path when setting up your DSNs on the client.

In an XDBC Local installation, acuxdbc.cfg is the only configuration file that is required.

For acuxdbc.cfg, you can use configuration variables from several key areas, as shown below. The DICTSOURCE and FILE_PREFIX variables are required. If you installed AcuXDBC in a non-default directory, you must modify the DICTSOURCE and FILE_PREFIX variables in the client configuration file or generate a new configuration file with the genxconf batch or shell script file, which is included in your distribution to make the generation of configuration files easier. This utility takes the format:

      genxconf [-d directory] [-c catalog] [-p prefix] [-n config_name]

where:

-d | Specifies the directory name to use for the GENESIS_HOME environment variable
-c | Specifies an optional directory name to use for the system catalog
-p | Specifies a location (path) to your data files
-n | Specifies a name for the configuration file that is created

This utility automatically generates an AcuXDBC configuration file that includes the required configuration variables. The variables are set to the values that you define. You can override these with command-line parameters.

You can also specify an alternate directory name for GENESIS_HOME and an alternate configuration file name. Most of the settings are read from a template, located in $(GENESIS_HOME)/sample/acuxdbc/acuxdbc.in. Use this to customize the generation settings.

This table lists the configuration variables available, along with their defaults and brief descriptions. For complete descriptions, including examples, follow the links.

General Setup Options

Variable | Default | Description
DICTSOURCE | Install directory | Location (path) of your system catalog
FILE_PREFIX | Install directory | Location (path) of your data files Note: Enclose any values contains space(s) in quotation marks. If the value can contain multiple directories that contain spaces, enclose the entire entry in quotation marks.
FILE_SUFFIX | None | Extension of your data files

Advanced Options

Variable | Default | Description
FILE_CASE | Default (Mixed) | Indicates the file case of your data files
FILENAME_WILDCARD | None | Defines multi-company wildcards and their respective substitution characters
IGNORE_OWNER | 0 | Specifies whether you want the table owner to be included in a listing of tables
INVALID_NUMERIC_DATA | Error | Indicates how to treat non-numeric data in a numeric field
JULIAN_BASE_DATE | 19000101 | The base date for Julian date calculation
NULL_ALPHA_READ | Null | Defines how to read null alphanumeric data
NULL_ALPHA_WRITE | Spaces | Defines how to write null alphanumeric data
NULL_NUMERIC_READ | 0 | Defines how to read null numeric data
NULL_NUMERIC_WRITE | 0 | Defines how to write null numeric data
DATE_ZERO_VALUE | YYYYMMDDHHmmsshh (Year/Month/Day/Hour/Minute/Second/Hundredths) | When DATETIME = DATE_ZERO_VALUE, LOW-VALUES or all 0 are returned
DATE_NINE_VALUE | YYYYMMDDHHmmsshh (Year/Month/Day/Hour/Minute/Second/Hundredths) | When DATETIME = DATE_NINE_VALUE, HIGH-VALUES or all 9 are returned
DATE_NULL_VALUE | YYYYMMDDHHmmsshh (Year/Month/Day/Hour/Minute/Second/Hundredths) | DATETIME is SQL NULL, the value of the DATE_NULL_VALUE will be written to the COBOL data.
DATE_INVALID_VALUE | YYYYMMDDHHmmsshh (Year/Month/Day/Hour/Minute/Second/Hundredths) | When DATETIME = DATE_INVALID_VALUE, spaces will be written to the COBOL
DATE_MAX_HIGH_VALUES | HIGH-VALUES or 9 | Setting to configure DATE_NINE_VALUE
DATE_MIN_LOW_VALUES | LOW-VALUES or 0 | Setting to configure DATE_ZERO_VALUE
QUERY_TIMEOUT | No | Defines the timeout for a query. When set to zero, the query never times out.
READ_ONLY | No | Read/write status of data files

Vision Options

Variable | Default | Description
LOCKS_PER_FILE | 10 | The maximum number of record locks that can be held on a file when an SQL transaction has been issued
MAX_FILES | 32 | Maximum number of files that can be opened
MAX_LOCKS | 32 | The maximum number of record locks that can be held for all of the files together
V_BUFFERS | 32 | The number of indexed block buffers to allocate

Transaction Processing Options

Variable | Default | Description
LOG_BUFFER_SIZE | 512 | The maximum buffer size, in bytes, for the transaction log file
LOG_ENCRYPTION | off | Encrypts transaction log file
LOG_FILE | none | Name of transaction log file
LOG_DEVICE | off | Assumes that the log file is actually a device, rather than a file
LOGGING | off | Enables transaction logging
TEMP_DIR | current directory | Directory to be used for holding the temporary files generated by the transaction management system
TRANSACTIONS | on | Enables transaction processing in the AcuXDBC interface
TRANSACTION PROCESSING | off | Enables Vision's transaction processing support.

Logging Setup Options

Variable | Default | Description
DEBUG_LOGFILE | None | Name and location of the log file used for debugging
DEBUG_LOGLEVEL | 0 | The log level you desire for debugging
VISION_LOGGING_FILE | vision_trace.log | Sets name of the Vision log file
VISION_LOGGING_LEVEL | 0 | Initiates Vision logging/tracing
Parent topic: Configuration


Network Configuration

When deployed in a network or client-server configuration, AcuXDBC requires two configuration files:

  • acuxdbc.cfg on the server

    This file is described in Client Configuration.

  • net.ini on the client

    By default, AcuXDBC expects this file to be located in the lib subdirectory of the install. net.ini is where you define client-side settings for your network configuration.

You may use any of the following configuration variables in net.ini. The table below lists the variables, along with their defaults and brief descriptions. For complete descriptions, including examples, follow the links.

Variable | Default | Description
KEY_CONNECT | 1234 | Used to encrypt the user ID and password sent over the network
PACKETSIZE | 8192 | Specifies the size of buffer used to aggregate send operations
READ_TIMEOUT | 0 | Specifies the time to wait for read completion
RETURN_ERRNO | No | Returns the operating system error code for communication errors
WRITE_TIMEOUT | 0 | Specifies the time to wait for write completion

For your convenience, a sample net.ini is is installed with the AcuXDBC package in the lib subdirectory. Most of the configuration options are commented out in this sample. To use an option, remove the comment hash sign (#) to apply a setting, and then resave the file.

Parent topic: Configuration


Network Configuration with AcuServer

Network installations that use AcuServer rather than AcuXDBC Server require one configuration file: acuxdbc.cfg on the client.

Any AcuXDBC configuration variable can be used in this file. The following variables are specific to AcuServer users. They apply only to network environments that use AcuServer for remote data access:

Variable | Default Setting | Description
ACUSERVER_PASSWORD | None | Defines the password for connecting to AcuServer
ACUSERVER_PORT | 6523 | Specifies the port number on which AcuServer is listening
DEFAULT_MAP_FILE | None | Sets the name and path of the map file to be used to map special characters to their decimal or hexadecimal equivalent
SECURITY_METHOD | None | Sets the security method to use when accessing the AcuServer host
Parent topic: Configuration


Sample AcuXDBC File

# This is a sample acuxdbc.cfg configuration file.
# You should edit it to match your needs.

# The following lines are commented out to show you the default values.
# If you want to use a different value, then uncomment the line and change
# the value.

#-----------------------------------------------------------
#---------------GENERAL SETUP OPTIONS-----------------------
#-----------------------------------------------------------

#  The path to your system catalog directory. This is a required variable

dictsource C:\Program Files\Micro Focus\Acucbl900\acugt\syscat

#  The path to your data files.  You must prepend the line with a semi-colon,
#  use either double backslashes ("\\") or forward slashes ("/"),
#  and separate your paths by semi-colons. This is a required variable

file_prefix ;C:/Program Files/Micro Focus/Acucbl900/acugt/sample/AcuXDBC/data

#  Specify your data file extensions; leave blank if no
#  extensions exist.

# file_suffix

#-----------------------------------------------------------
#-------------------ADVANCED OPTION SETUP-------------------
#-----------------------------------------------------------

#  Values for File_Case are Default (case ignored),
#  Lower (filename converted to lower case), and
#  Upper (filename converted to upper case).

# file_case      default

#  To specify how MFDBC will treat non-numeric values in numeric fields,
#  set this variable to Error (assignment error returned),
#  Truncate (value truncated from first non-numeric value to the end),
#  or Zero (value returned will be zero).

invalid_numeric_data    error
# invalid_numeric_data  truncate
# invalid_numeric_data  zero

#  Set this value to true if the user should have read-only
#  permissions to this database. The default is read and write permissions.

# read_only       no

#  These two variables provide a representational mapping between COBOL's
#  SPACES and LOW-VALUES and the corresponding SQL column values.
#  Valid values are null and empty.

# null_alpha_read null

#  Valid values are spaces and low-values.

# null_alpha_write      spaces

#  Valid values are null and 0 (zero).
# null_numeric_read     0

#  Valid values are spaces, low-values, and 0 (zero).
# null_numeric_write     0

#  Enter a start date for Julian dates using the YYYYMMDD
#  format. The default date is January 1, 1900.
# julian_base_date 19000101

# This variable when turned off will cause AcuXDBC to ignore the transaction
# options on operations such as an update. The default is on.
#
# transactions          on

# Tables in AcuXDBC have an owner specified. The owner is either public
# or an authorization id. The ignore_owner variable can be used to have
# files show as no owner. This must be used in conjunction with loading
# through xdbcutil with the -o " " option to have a blank owner in the
# database. The default is FALSE.
#
# ignore_owner          off

# Configuration variables now exist in
# AcuXDBC to handle conditions where date values
# do not contain valid dates. These variable cover the situations # where a date
# field contains HIGH-VALUES, LOW-VALUES, all nines, all zeros, or an invalid
# date.

#date_zero_value 1901010100000000
#date_nine_value 2099123100000000
#date_null_value 1966021100000000
#date_invalid_value 2012011600000000
#date_max_high_values nine
#date_min_low_values zero

#-----------------------------------------------------------
#-------------------FILE OPTION SETUP-----------------------
#-----------------------------------------------------------
# Set Max_Files from 1 to 256.
# max_files 		      32

# Set Max_Locks from 1 to 8191.
# max_locks 		       32

# Set Locks_per_file from 1 to 8191.
# locks_per_file		     10

# Set V_Buffers from 0 to 256.
# v_buffers		      32

#-----------------------------------------------------------
#----------TRANSACTION PROCESSING SETUP OPTIONS-------------
#-----------------------------------------------------------
# transaction_processing 	Off
# logging		 off
# log_encrypt		 off
# log_device 		off
# log_file
# temp_dir 		.
# log_buffer_size	 512

#-----------------------------------------------------------
#---------------------Multi-Company OPTIONS-----------------
#-----------------------------------------------------------

#  For multi-company handling, you can specify the value of any
#  wildcards that you used when creating the table in your
#  system catalog by noting the values here.

# filename_wildcards

#-----------------------------------------------------------
#---------------LOGGING SETUP OPTIONS-----------------------
#-----------------------------------------------------------

# debug_logfile
# debug_loglevel
# vision_logging_file
# vision_logging_level
#-----------------------------------------------------------
#-------------------END CONFIGURATION-----------------------
#-----------------------------------------------------------
Parent topic: Configuration


Sample net.ini File

This sample file is located in %GENESIS_HOME%\lib on Windows and in $GENESIS_HOME/lib on UNIX/Linux.

#  net.ini file, used by AcuXDBC Server for client-side
#  configuration settings. Note that the information
#  in the DSN takes precedence over the settings here.

#  This number must match the one given with
#  the -k option when AcuXDBC Server is started.
#  It is used to encrypt the user ID and password
#  information over the network.
#key_connect      1234

#  Comma-delimited list of environment variable(s) to set on the host.
#hostenv0

#  Size (in bytes) of the buffer used to aggregate send operations.
#packetsize 8192

#  Time to wait for read completion. The default of 0 (zero) means no timeout.
#read_timeout     0

#  Time to wait for a write completion. The default of 0 (zero) means no timeout.
#write_timeout    0

#  Return the OS error code for a communication error.
#return_errno     no
Parent topic: Configuration


Configuration Variables

  • ACUSERVER_PASSWORD
  • ACUSERVER_PORT
  • DEFAULT_MAP_FILE
  • SECURITY_METHOD
  • DATE_INVALID_VALUE
  • DATE_MAX_HIGH_VALUES
  • DATE_MIN_LOW_VALUES
  • DATE_NINE_VALUE
  • DATE_NULL_VALUE
  • DATE_ZERO_VALUE
  • DEBUG_LOGFILE configuration variable
  • DEBUG_LOGLEVEL configuration variable
  • DICTSOURCE configuration variable
  • FILE_CASE configuration variable
  • FILE_PREFIX configuration variable
  • FILE_SUFFIX configuration variable
  • FILENAME_WILDCARD configuration variable
  • IGNORE_OWNER configuration variable
  • INVALID_NUMERIC_DATA configuration variable
  • JULIAN_BASE_DATE configuration variable
  • KEY_CONNECT configuration variable
  • LOCKS_PER_FILE
  • LOG_BUFFER_SIZE
  • LOG_DEVICE
  • LOG_ENCRYPTION
  • LOG_FILE
  • LOGGING
  • MAX_FILES
  • MAX_LOCKS
  • NULL_ALPHA_READ configuration variable
  • NULL_ALPHA_WRITE configuration variable
  • NULL_NUMERIC_READ configuration variable
  • NULL_NUMERIC_WRITE configuration variable
  • PACKETSIZE configuration variable
  • QUERY_TIMEOUT
  • READ_ONLY configuration variable
  • READ_TIMEOUT configuration variable
  • RETURN_ERRNO configuration variable
  • TEMP_DIR
  • TRANSACTIONS
  • TRANSACTION_PROCESSING
  • WRITE_TIMEOUT configuration variable
  • V_BUFFERS
  • VISION_LOGGING_FILE
  • VISION_LOGGING_LEVEL
Parent topic: Configuration


ACUSERVER_PASSWORD

Use this variable to specify the password assigned in AcuServer's server access file (AcuAccess file). AcuXDBC will use this password to access the AcuServer host.
Parent topic: Configuration Variables


ACUSERVER_PORT

Use this variable to specify the port number assigned to the AcuServer host if it is different from the default port number, 6523. This variable is useful for redirecting additional instances of AcuServer or for working around a firewall.
Parent topic: Configuration Variables


DEFAULT_MAP_FILE

Use this variable to set the name and path of the map file to be used (if any) to map special characters in your character set to their decimal or hexadecimal equivalent in another character set before they are passed to or from the Vision file system. This file lets you reconcile the character encoding between two machines that use different codes for the same characters.

You can specify a local or remote directory for the map file. To specify a remote directory, use the following syntax:

@server-name:directory-path

where server-name is the name of the UNIX/Linux or Windows server on which the map file resides.

When creating a map file, you need to re-map only those values that vary between the two character sets (e.g., vowels with a grave accent, acute accent, circumflex, tilde, etc.) You can check the values of specific characters using the Windows Character Map accessory in the PC environment, or by referring to your UNIX manual pages (man pages) in the UNIX environment.

The map file should contain two values per line: the first indicating the decimal or hexadecimal value of the special character on the client machine and the second indicating the decimal or hexadecimal value of the corresponding character on the server machine. (Hexadecimal values use the standard 0x notation.) For instance:

0x90 0xC9

maps "É" (E acute) in the IBM PC character set to "É" (E acute) in the ISO8859-1 character set using hexadecimal notation.

144 201

gives the same mapping using decimal notation.

You can use the pound sign ("#") to indicate a comment.

Note: The map will be used to translate only alphanumeric fields; but it will translate all alphanumeric fields, including group items and items subject to a REDEFINES clause. If this is not a desired behavior, you may need to restructure your program to avoid these clauses by passing the elementary items instead of the group item, or passing an item from the REDEFINES clause instead of the first reference.
Parent topic: Configuration Variables


SECURITY_METHOD

Use this variable to specify the security method to use when accessing the AcuServer host. AcuXDBC's network security methods are not used with AcuServer.

SECURITY_METHOD can take any of three values. The value specified here must match the value specified in the server configuration file on the AcuServer host. Valid values include:

Value | Description
NONE (false, no) | Do not use the native operating system security. Use AcuServer security instead.
LOGON | Use the system's native security to manage user logons.
NAMED-PIPE (on, true, yes) | Use Windows security based on the connection made from the client to the server via a named pipe.
Parent topic: Configuration Variables


DATE_INVALID_VALUE

In an XDBC configuration file, set the DATE_INVALID_VALUE configuration variable to a valid date, as per the format specified by the XFD DATE directive, to be used when translating dates between a DATETIME type and a COBOL data type.

This date is used in the following situations:
  • When translating COBOL data to a DATETIME, if the COBOL data item consists of an invalid date or is set to SPACES, the value for DATA_INVALID_VALUE is used.
  • When translating a DATETIME type to a COBOL data item, if the DATETIME is the same value as DATE_INVALID_VALUE, the COBOL item is set to SPACES.
Note: During translation, any information missing from the date string will default to the lowest possible value.

Example:

With the following variable set:

DATE_INVALID_VALUE       2012011600000000

the following translations occur:

Original item | Translated to
COBOL item not set to a valid date according to the DATE XFD directive | 2012011600000000
DATETYPE is 2012011600000000 | SPACES
Parent topic: Configuration Variables
Related concepts
DATE_NINE_VALUE
DATE_NULL_VALUE
DATE_ZERO_VALUE


DATE_MAX_HIGH_VALUES

Use the DATE_MAX_HIGH_VALUES configuration variable when translating invalid DATETIME types to COBOL data items.

During translation, if the DATETIME type is equal to the date specified by DATE_NINE_VALUE, the COBOL item is translated either to all 9's or to HIGH-VALUES, depending on the value of DATE_MAX_HIGH_VALUES.

Permissible values: nine or high.

Note: By default, this variable is not set.
Parent topic: Configuration Variables
Related concepts
DATE_NINE_VALUE


DATE_MIN_LOW_VALUES

Use the DATE_MIN_LOW_VALUES configuration variable when translating invalid DATETIME types to COBOL data items.

During translation, if the DATETIME type is equal to the date specified by DATE_LOW_VALUE, the COBOL item is translated either to all zeros or to LOW-VALUES, depending on the value of DATE_MIN_LOW_VALUES.

Permissible values: zero or low.

Note: By default, this variable is not set.
Parent topic: Configuration Variables
Related concepts
DATE_ZERO_VALUE


DATE_NINE_VALUE

In an XDBC configuration file, set the DATE_NINE_VALUE configuration variable to a valid date, as per the format specified by the XFD DATE directive, to be used when translating dates between a DATETIME type and a COBOL data type.

This date is used in the following situations:
  • When translating COBOL data to a DATETIME, if the COBOL data item consists of all 9's or HIGH-VALUES, the value for DATA_NINE_VALUE is used.
  • When translating a DATETIME type to a COBOL item, if the DATETIME is the same value as DATE_NINE_VALUE, the COBOL item is set to either all 9's or HIGH-VALUES, depending on the value of the DATE_MAX_HIGH_VALUES configuration variable.
Note: During translation, any information missing from the date string will default to the lowest possible value.

Example:

With the following variables set:

DATE_NINE_VALUE       2099123100000000
DATE_MAX_HIGH_VALUES  nine

the following translations occur:

Original item | Translated to
COBOL item is all 9's | 2099123100000000
COBOL item is HIGH-VALUES | 2099123100000000
DATETYPE is 2099123100000000 | all 9's
Parent topic: Configuration Variables
Related concepts
DATE_INVALID_VALUE
DATE_NULL_VALUE
DATE_ZERO_VALUE
Related reference
DATE_MAX_HIGH_VALUES


DATE_NULL_VALUE

In an XDBC configuration file, set the DATE_NULL_VALUE configuration variable to a valid date, as per the format specified by the XFD DATE directive, to be used when translating dates between a DATETIME type and a COBOL data type.

This date is used in the following situations:
  • When translating COBOL data to a DATETIME, if the COBOL data item is the same value as the DATA_NULL_VALUE value, NULL is used.
  • When translating a DATETIME type to a COBOL data item, if the DATETIME is an SQL NULL value, the COBOL item is set to the value of DATE_NULL_VALUE.
Note: During translation, any information missing from the date string will default to the lowest possible value.

Example:

With the following variable set:

DATE_NULL_VALUE       1969021100000000

the following translations occur:

Original item | Translated to
COBOL item is the same value as DATE_NULL_VALUE | SQL NULL
DATETYPE is NULL | 1969021100000000
Parent topic: Configuration Variables
Related concepts
DATE_INVALID_VALUE
DATE_NINE_VALUE
DATE_ZERO_VALUE


DATE_ZERO_VALUE

In an XDBC configuration file, set the DATE_ZERO_VALUE configuration variable to a valid date, as per the format specified by the XFD DATE directive, to be used when translating dates between a DATETIME type and a COBOL data type.

This date is used in the following situations:
  • When translating COBOL data to a DATETIME, if the COBOL data item consists of all zeros or LOW-VALUES, the value for DATA_ZERO_VALUE is used.
  • When translating a DATETIME type to a COBOL data item, if the DATETIME is the same value as DATE_ZERO_VALUE, the COBOL item is set to either all zeros or LOW-VALUES, depending on the value of the DATE_MIN_LOW_VALUES configuration variable.
Note: During translation, any information missing from the date string will default to the lowest possible value.

Example:

With the following variables set:

DATE_ZERO_VALUE       1901010100000000
DATE_MIN_LOW_VALUES  zero

the following translations occur:

Original item | Translated to
COBOL item is all zeros | 1901010100000000
COBOL item is LOW-VALUES | 1901010100000000
DATETYPE is 1901010100000000 | LOW-VALUES
Parent topic: Configuration Variables
Related concepts
DATE_INVALID_VALUE
DATE_NINE_VALUE
DATE_NULL_VALUE
Related reference
DATE_MIN_LOW_VALUES


DEBUG_LOGFILE configuration variable

Use DEBUG_LOGFILE to specify the fully qualified name of the log file to be generated by the DEBUG_LOGLEVEL variable.

Example

DEBUG_LOGFILE c:\logdir\xdbc.log
Parent topic: Configuration Variables
Related information
DEBUG_LOGLEVEL configuration variable


DEBUG_LOGLEVEL configuration variable

Set DEBUG_LOGLEVEL to the level of logging that you need for debugging purposes. This variable has three valid values:

Value | Description
0 | None — No log file is created; logging is off
1 | Log control blocks/data — The log file contains information about the connection, the values in your configuration file, and the data from the table/file
2 | Log conversion output

Use DEBUG_LOGFILE to specify the name of the log file to be generated.

Parent topic: Configuration Variables
Related information
DEBUG_LOGFILE configuration variable


DICTSOURCE configuration variable

Use this variable to specify the location of your system catalog. The system catalog is a required component of AcuXDBC and is created using the xdbcutil program or the ainit script. See Creating a System Catalog and Views for more information.

Example

DICTSOURCE c:\data\Dict

By default, DICTSOURCE is set to C:\Program Files\Micro Focus\Acucbl900\acugt\syscat.

Use the FILE_PREFIX variable to specify the location of your indexed data files. Both DICTSOURCE and FILE_PREFIX are required.

Parent topic: Configuration Variables
Related information
FILE_PREFIX configuration variable
Sample Configuration File


FILE_CASE configuration variable

Using this variable, set the case of the indexed file filenames in your destination directory. On Windows by default, the filenames are recognized in either upper, lower, or mixed case. On UNIX/Linux using the default setting enables you to access files regardless of whether they are named in upper case or lower case letters. You may need to use this variable to indicate the correct case.

If you set FILE_CASE to Upper, you can access only files that are named in upper case letters. In the reverse, if you set FILE_CASE to Lower, you can access only files that are named in lower case letters.

Example

The following table shows the files you would find depending on the FILE_CASE:

 | FILEA | FileA | filea
Upper | x |  |
Lower |  |  | x
Default | x | x | x

The name of the file is stored in the system catalog at the time it is loaded using either xdbcutil or addfile. On UNIX/Linux this will be equivalent to the file name being loaded in lower case. Should you wish to access a file in mixed case, you must load the original filename in the appropriate case. You can do this with the xdbcutil program.

For a UNIX/Linux example if you wish to load an .xfd file titled myxfd that will result in an SQL table named “newtable” and reference a COBOL data file named MyDaTaFile, you would use this command:

xdbcutil -a myxfd#newtable#MyDaTaFile

In your AcuXDBC configuration file, you would need to ensure that you have the entry:

FILE_CASE Default

On UNIX/Linux AcuXDBC would then leave the case of the filename unchanged when it attempts to open the file.

Parent topic: Configuration Variables


FILE_PREFIX configuration variable

Use this variable to specify the directories in which AcuXDBC should search for data files. You can specify multiple locations for your data files. Until you specify a data directory, AcuXDBC will not let you log on.

You must prepend the line with a semi-colon, use double backslashes ("\\") or single forward slashes ("/") between directory names, and separate your paths by semi-colons. If any of your directories contain spaces, place the entire entry (including the prepended semi-colon) in quotation marks:

FILE_PREFIX ";c:\my dir1;c:\my dir2"

For best performance, list the directories in the order in which you want AcuXDBC to search.

Example

FILE_PREFIX   ";C:\\data\\data;\\XYZDomain\\data"

or

FILE_PREFIX   ";C:/data/data;/XYZDomain/data"

Use the DICTSOURCE variable to specify the location of your system catalog. Both DICTSOURCE and FILE_PREFIX are required.

Parent topic: Configuration Variables
Related information
DICTSOURCE configuration variable


FILE_SUFFIX configuration variable

Use this variable to specify the file extension used for your data files.

Example

FILE_SUFFIX dat

When AcuXDBC looks for a file, it looks only at files with the extension specified here. If you do not include this variable in your configuration file, AcuXDBC looks for data files with no extension in the data directory indicated with FILE_PREFIX. You can always specify the exact filename with suffix when using the xdbcutil program or the addfile script.

Parent topic: Configuration Variables
Related information
FILE_PREFIX configuration variable


FILENAME_WILDCARD configuration variable

Use this variable to define wildcards for multi-company data source names (DSNs). For example, a configuration file entry like this:

FILENAME_WILDCARD $$=01;**=02

tells AcuXDBC to substitute 01 for $$ and 02 for ** whenever the wildcard characters $$ and ** are encountered in a configuration file, a list.txt file, or on the xdbcutil command line.

Wildcards can be any character except an equal sign (=), colon (:), semi-colon (;), alphabetic characters A to Z, and numerals 0 to 9. These are reserved characters.

Separate a wildcard from its substitution character by an equal sign. Separate multiple wildcards from one another by a semi-colon.

See Multi-company Support for instructions on setting up multi-company DSNs.

Parent topic: Configuration Variables


IGNORE_OWNER configuration variable

All tables in a AcuXDBC database have an owner. By default, the owner of the table is PUBLIC, or you can specify a different authorization ID when you add the file to the database with xdbcutil. See xdbcutil Syntax for information on the xdbcutil utility.

If an application such as Microsoft Access tries to link to the table, the table appears with the link table name of the form OWNER_NAME by default. If you don't want the owner of the table to be displayed, you can prevent this from happening through configuration variables and command-line options.

Parent topic: Configuration Variables


INVALID_NUMERIC_DATA configuration variable

Use this variable to indicate how AcuXDBC should treat non-numeric data in a numeric field.

Error (default) | Causes AcuXDBC to treat non-numeric data in a numeric field as an assignment error
Truncate | Causes AcuXDBC to treat the first non-numeric character in a numeric field as the end of the numeric data (thus truncating the numeric data). This includes anything that is not a number, decimal, plus, or minus
Zero | Causes the field to be returned to the application as 0 if the field contains any non-numeric data
CAUTION:
Be aware that users may inadvertently change data in a record. For example, if a particular record contains non-numeric data in a numeric field, and the user changes the data while working in an ODBC-enabled application, the record in the source file changes to reflect what is now in the application. Therefore, exercise caution when setting either the INVALID_NUMERIC_DATA or READ_ONLY variables to a non-default value.

Some applications must read data based on the key. If a numeric column of a key field contains non-numeric data, the application will be unable to find the correct row of the file and may show an error. Note that, in particular, Microsoft Access selects the columns of the primary key and then selects the rest of the data based on those key columns. If Access cannot read the data (because a user operation has changed the data, and therefore the wrong data is in the key), the affected records show as DELETED. In this case, you must fix the data in the primary key.

Parent topic: Configuration Variables


JULIAN_BASE_DATE configuration variable

A Julian date is the number of days since a certain base date. For example, if the Julian base date is June 18, 2006 and today's date is July 4, 2006, the Julian date is 16. The default Julian base date in AcuXDBC is January 1, 1900.

To specify the date from which to start counting Julian dates, use the JULIAN_BASE_DATE variable. Specify a base date in the format yyyy/mm/dd.

Example

JULIAN_BASE_DATE 2006/10/30

Note that you can enter any Julian Base Date, regardless of whether or not the date is valid. Also note that when AcuXDBC calculates Julian dates, the Julian base date becomes date 0. For example, if your Julian base date is October 30, 2006, the Julian dates are counted as follows:

October 30 | Julian date 0
October 31 | Julian date 1
November 1 | Julian date 2
November 2 | Julian date 3
November 3 | Julian date 4
Parent topic: Configuration Variables


KEY_CONNECT configuration variable

Use the net.ini configuration variable, KEY_CONNECT, to specify the connect string masking key used to encrypt the operating system and DBMS user ID and password information. This number must match the one given with the -k option when AcuXDBC is started on the server.

Example

KEY_CONNECT 12345
Parent topic: Configuration Variables
Related information
Sample net.ini File


LOCKS_PER_FILE

This value determines the maximum number of record locks that can be held on a file by a single process. This value affects only the files that are maintaining multiple record locks. The default setting is "10". The maximum value is 32767 for Vision files. Setting this variable to its maximum value can waste resources and is not recommended.

Note:

If you increase the value of LOCKS_PER_FILE, you may wish to increase the value of MAX_LOCKS as well.

Parent topic: Configuration Variables


NULL_ALPHA_READ configuration variable

COBOL does not have a concept that corresponds directly to SQL's NULL. The closest candidates in COBOL are data items that contain either SPACES or LOW-VALUES. In SQL, NULL is often used to indicate that the data is missing or not applicable.

To maintain the integrity of the source data and to ensure that any data written from your application back to the COBOL source is accurate, you must provide a representational mapping between COBOL's SPACES and LOW-VALUES and the corresponding SQL column values.

Use the NULL_ALPHA_READ variable to indicate which COBOL alphanumeric data should be represented as NULL. For data coming into your application (READs), if a field contains either SPACES or LOW-VALUES in alphanumeric data in the COBOL files, instruct the application to represent it as either NULL or an empty string. Valid values are:

NULL_ALPHA_READ null
NULL_ALPHA_READ empty

By default, alphanumeric data is interpreted as null on input to your ODBC-enabled application.

AcuXDBC follows these rules for alphanumeric data coming into an ODBC-enabled application.

If an alphanumeric field contains... | That field comes into the application
All SPACES or all LOW-VALUES | As either NULL or as an empty string, depending on the setting for variables for the data source
Any other values | Unchanged
Parent topic: Configuration Variables


NULL_ALPHA_WRITE configuration variable

COBOL does not have a concept that corresponds directly to SQL's NULL. The closest candidates in COBOL are data items that contain either SPACES or LOW-VALUES. In SQL, NULL is often used to indicate that the data is missing or not applicable.

To maintain the integrity of the source data and to ensure that any data written from your application back to the COBOL source is accurate, you must provide a representational mapping between COBOL's SPACES and LOW-VALUES and the corresponding SQL column values.

Use the NULL_ALPHA_WRITE variable to indicate how SQL NULLs in alphanumeric data should be translated into COBOL data. For data returned to the COBOL files (WRITEs), indicate whether the NULLs should be interpreted as SPACES or LOW-VALUES. Valid values are:

NULL_ALPHA_WRITE spaces
NULL_ALPHA_WRITE low-values

By default, alphanumeric data is interpreted as SPACES on output to the COBOL source.

Note: This variable is ignored if your data source is read-only.
Parent topic: Configuration Variables
Related information
NULL_ALPHA_READ configuration variable


NULL_NUMERIC_READ configuration variable

COBOL does not have a concept that corresponds directly to SQL's NULL. The closest candidates in COBOL are data items that contain either SPACES or LOW-VALUES. In SQL, NULL is often used to indicate that the data is missing or not applicable.

To maintain the integrity of the source data and to ensure that any data written from your application back to the COBOL source is accurate, you must provide a representational mapping between COBOL's SPACES and LOW-VALUES and the corresponding SQL column values.

Use the NULL_NUMERIC_READ variable to indicate which COBOL numeric data should be represented as NULL. For data coming into your application (READs), if a field contains either SPACES or LOW-VALUES in numeric data in the COBOL files, instruct the application to represent it as either NULL or a zero. Valid values are:

NULL_NUMERIC_READ null
NULL_NUMERIC_READ 0

With numeric fields, LOW-VALUES and SPACES are valid values for many numeric types, as shown in the following examples:

If the numeric type is ... | LOW-VALUES is equal to ... | SPACES is equal to ...
PIC 9(4) COMP-3 | 0 | 202
PIC 9(2) COMP-5 | 0 | 8224
PIC 9(4) COMP-2 | 0 | INVALID

Therefore, AcuXDBC follows these rules for numeric data coming in to the ODBC-enabled application:

Field | Rule
All LOW-VALUES | If LOW-VALUES is an invalid value for the numeric type, the field comes into the application based on the setting for numeric variables for the data source
Any other values | If the value is invalid for the numeric type, undefined data may come in to the application
Note: SPACES or LOW-VALUES will not be converted to NULL or zero in a numeric data item where SPACES or LOW-VALUES, respectively, are valid numeric values.

By default, numeric data is interpreted as zero on input to your ODBC-enabled application.

See NULL_NUMERIC_WRITE configuration variable for additional restrictions on writing data to your COBOL data file from your ODBC-enabled application.

Parent topic: Configuration Variables
Related information
NULL_ALPHA_READ configuration variable


NULL_NUMERIC_WRITE configuration variable

COBOL does not have a concept that corresponds directly to SQL's NULL. The closest candidates in COBOL are data items that contain either SPACES or LOW-VALUES. In SQL, NULL is often used to indicate that the data is missing or not applicable.

To maintain the integrity of the source data and to ensure that any data written from your application back to the COBOL source is accurate, you must provide a representational mapping between COBOL's SPACES and LOW-VALUES and the corresponding SQL column values.

Use the NULL_NUMERIC_WRITE variable to indicate how SQL NULLs in numeric data should be translated into COBOL data. For data returned to the COBOL files (WRITEs), indicate whether the NULLs in numeric data should be interpreted as SPACES, LOW-VALUES, or zero.

Valid values are:

NULL_NUMERIC_WRITE spaces
NULL_NUMERIC_WRITE low-values
NULL_NUMERIC_WRITE 0

By default, numeric data is interpreted as zero on output to the COBOL source.

Numeric fields that take the form of one of the computational types further complicate the situation. For most comp fields, LOW-VALUES and SPACES are valid values. See the configuration variable NULL_NUMERIC_READ for examples. To prevent erroneous information being written to the COBOL data files by the insert of a NULL value, tables created with comp fields that could be misinterpreted are created with the NOT NULL constraint on these columns. The following describes these columns:

Field Type | NULLABLE
Numeric | NULL
COMP | NOT NULL
COMP-1 | NOT NULL
COMP-2 | NULL
COMP-3 | NOT NULL
COMP-4 | NOT NULL
COMP-5 | NOT NULL
COMP-6 | NOT NULL
Other comp | See above types

In this case, if you attempt to insert a row into the COBOL file and specify NULL for one of these columns, or do not specify a value, you will receive the error message:

“***** ERROR: NULL not allowed for column”

From within the command-line query tool, you can check which columns have this constraint. For example, to find out which columns in the table COMPTEST will not allow a null value, use the command:

select
        column_name, ordinal_position
from
        information_schema.columns
where
        table_name = 'COMPTEST'
and
        is_nullable = 'N';

For columns having the NOT NULL constraint, you must specify a value.

Note: This variable is ignored if your data source is read-only.
Parent topic: Configuration Variables
Related information
NULL_NUMERIC_READ configuration variable
NULL_ALPHA_READ configuration variable


PACKETSIZE configuration variable

Use this variable to specify the size (in bytes) of the buffer used to aggregate send operations. The default is 8192.

Example

PACKETSIZE 1024
Parent topic: Configuration Variables
Related information
Sample net.ini File


READ_ONLY configuration variable

This variable establishes the default read/write permission for all the files belonging to the associated DSN. By default, this variable is set to 0 (off, false, no), indicating that users can write to the files. Specify 1 (on, true, yes) if you want to make the files read-only.

What you indicate for read/write permission here applies to all files in the data source. If you want to assign different permissions to any individual files, you can do so using file aliases. See Setting Up File Aliases for more information on file aliases.

File (table) level read/write protection can also be defined by granting object privileges to specific users or to the PUBLIC user. You do this with the SQL GRANT (Object Properties) statement. For example, to make a table read-only to all users, you could issue the following command using xdbcquery. See Using the Command-line Query Tool for information about this tool.

GRANT SELECT ON TABLE1 TO PUBLIC

Field (column) level read/write protection can be further defined using the READ-ONLY directive.

Note: When executing a SELECT statement, AcuXDBC opens indexed files as INPUT regardless of how this variable is set. When the user attempts to update a row (from Microsoft Access, for example), if the READ_ONLY configuration variable is off, AcuXDBC attempts to open the indexed file for update. If the COBOL program has the record locked during a AcuXDBC SELECT, and that record has met the SELECT conditions, a locked record condition occurs. When the COBOL program updates a record previously retrieved during a AcuXDBC, the update takes effect. When AcuXDBC attempts to update the record, an error occurs indicating that the record has been changed by another process after the original AcuXDBC SELECT.
Parent topic: Configuration Variables
Related information
READ-ONLY directive


READ_TIMEOUT configuration variable

Use this variable to specify the time to wait (in seconds) for read completion. The default of 0 indicates that there is no timeout.

READ_TIMEOUT 60
Parent topic: Configuration Variables
Related information
Sample net.ini File


RETURN_ERRNO configuration variable

When this variable is set to "1" (on, true, yes), AcuXDBC returns the operating system error code for communication errors. By default this variable is set to "0" (off, false, no).

RETURN_ERRNO yes
Parent topic: Configuration Variables
Related information
Sample net.ini File


TRANSACTIONS

This variable turns transaction processing support on (1, true, yes) or off ( 0, no, false) for the AcuXDBC interface. The default setting is On and results in AcuXDBC accepting or recognizing Vision transaction commands. When set to Off AcuXDBC ignores the transaction commands.
Parent topic: Configuration Variables


TRANSACTION_PROCESSING

Use this variable to enable Vision's transaction processing support in AcuXDBC. If you are in a transaction processing environment, set this variable to 1, (on, true, yes) to begin transaction management, locking, and other key functions. By default, transaction processing is off. Use the LOGGING configuration variable to turn on transaction logging.
Parent topic: Configuration Variables


WRITE_TIMEOUT configuration variable

Use this variable to specify the time to wait (in seconds) for write completion. The default of 0 indicates that there is no timeout.

WRITE_TIMEOUT 60
Parent topic: Configuration Variables
Related information
Sample net.ini File


VISION_LOGGING_FILE

Use this variable to specify the name of the log file to be used for Vision logging. (Activate Vision logging using the VISION_LOGGING_LEVEL variable.) If the file does not exist, one is created.

You may store your Vision log file on a remote machine if your system utilizes AcuServer. To specify a remote filename for Log File, use remote name notation in this field. Note that AcuServer must be running on the remote machine.

Remote name notation has the following format:

@server-name:path-name/file-name

Log files prepended with @server-name:path-name are routed to AcuServer on the host specified by server-name, and stored in the directory specified by path-name

Parent topic: Configuration Variables


VISION_LOGGING_LEVEL

Set this variable to a value between 1 and 9 to initiate Vision logging/tracing; the higher the number, the more detailed the trace file. The trace file contains all Vision file operations performed at runtime, such as file opens, reads, and writes. It is useful for troubleshooting file errors. By default, the file is named vision_trace.log.

A value of 0 or -1 turns file tracing off.

Parent topic: Configuration Variables


Installation and Licensing

  • General Setup Procedures
  • Using AcuXDBC
  • Installing AcuXDBC/AcuXDBC Server
  • Creating a System Catalog and Views
  • Granting Database Privileges
  • Loading the System Catalog with Your XFDs
  • Setting Permissions on Your Database Tables
  • Starting AcuXDBC Server (Network Only)
  • Setting Up DSNs on the Client
Parent topic: AcuXDBC Version 10.2.0 User's Guide


General Setup Procedures

Procedures for setting up AcuXDBC in network and local environments are described in this help section. They assume that you have already created your configuration file(s).

  • Quick-start Demo Program
  • Stand-Alone Installations
    Describes steps for to install a standalone installation of AcuXDBC.
  • AcuXDBC Server Installations
    Overview of AcuXDBC Server Installation procedures.
  • AcuServer Installations
    Overview for installing AcuServer
Parent topic: Installation and Licensing


Quick-start Demo Program

To become familiar with the AcuXDBC software quickly, follow the quick-start demo procedure. Using this procedure, you will be up and running with a demonstration application in no time.

Parent topic: General Setup Procedures


Stand-Alone Installations

If you will be accessing your Vision data locally, you don't require AcuXDBC Server or AcuServer. The following steps are all performed on the same machine:
  1. Install AcuXDBC software using the installation script found on your product distribution media.
  2. Edit a configuration file, either by hand or with genxconf.

    For information about genxconf see AcuXCBC Configuration.

  3. Create a database:
    • For the demo, use the demo file located in the GENESIS_HOME directory.
    • For an empty database:
      1. Use the script file ainit.
      2. Run the executable xdbcutil

        xdbcutil -c -d mydb -pa

  4. If desired, create users.
  5. Load the system catalog with information from your XFDs. (for details on this see Loading the System Catalog with Your XFDs.
  6. Set permissions. See Setting Permissions on Your Tables.
  7. Set up a Data Source Name (DSN) for your Vision data. This step is not required if you plan to use a query tool to issue SQL queries and do not require ODBC integration.
Parent topic: General Setup Procedures


AcuXDBC Server Installations

If you will be using AcuXDBC Server to process Vision data on the server, you will need to install the server software and configure it for your specific client configuration. If you will be using AcuXDBC in a client/server configuration, you will first need to set up and configure AcuXDBC on the server machine for local access. Once you have completed this configuration, you can start the server and test client/server connections locally.

  • Server Procedure
    Procedure for installing the AcuXDBC server.
Parent topic: General Setup Procedures


Server Procedure

If you will be using AcuXDBC Server to process Vision data on the server, you will need to install the server software and configure it for your specific client configuration.
  1. Install AcuXDBC Server software on the server and set necessary environment variables.
  2. Create an empty system catalog, database system tables, and base views of the catalog.
  3. If desired, define users and grant database privileges to them. If you do not perform this step, your database will be open to all users.
  4. Load the system catalog with information from your XFDs.
  5. If desired, set permissions on your newly created Vision tables.
  6. Start AcuXDBC Server.
Parent topic: AcuXDBC Server Installations
Related tasks
UNIX_LinuxClientProcedure_Install
WindowsClientProcedure_Install
Related information
AcuXDBCServer_Installations


AcuServer Installations

If you will be using AcuServer to process remote Vision data locally, do the following:

Install AcuServer on the server.

Install AcuXDBC software.

  • Server Procedure
    Installing AcuServer for servers and clients.
  • Client Procedure
    Install AcuXDBC on the client if you will be using AcuServer to process remote Vision data locally.
Parent topic: General Setup Procedures


Server Procedure

Enter the prerequisites here (optional).
If you will be using AcuServer to process remove Vision data locally, you will need to install AcuServer software on the server and and AcuXDBC software on the client.
  1. Install AcuServer software on the server.
  2. Create a server access file.
  3. Start AcuServer. See the AcuServer User's Guide for specifics.
Parent topic: AcuServer Installations
Related tasks
AcuServer Installations_ClientProc


Client Procedure

Install AcuServer software on the server before performing these steps. See AcuServer Installations for more information.
If you will be using AcuServer to process remote Vision data locally, you will need to install AcuServer software on the server and perform the following steps on the client.
  1. Install AcuXDBC software.
  2. Create an empty system catalog, database system tables, and base views of the catalog.
  3. If desired, create users and grant database privileges to them. If you do not perform this step, your database will be open to all users.
  4. Load the system catalog with information from your XFDs.
  5. If desired, set permissions on your newly created Vision tables
  6. Setup a Data Source Name (DSN) for your Vision data. This step is not required if you plan ot use a query tool to issue SQL queries and do not require ODBC integration.
Parent topic: AcuServer Installations
Related tasks
AcuServer Installations_ServerProc


Using AcuXDBC

Once you have installed and configured AcuXDBC, you are ready to issue SQL queries to your COBOL data. There are two ways to do this:

  1. You can issue queries from ODBC-enabled applications like Microsoft Word, Excel, and Access, or JDBC-enabled applications like Cold Fusion. See Working with Windows and Java Applications for more information.
  2. You can issue queries from the command-line query tool or script. See Using the Command-line Query Tool for more information.
Parent topic: Installation and Licensing


Installing AcuXDBC/AcuXDBC Server

This help section provides instructions for installing AcuXDBC and AcuXDBC Server in Windows and UNIX/Linux environments.

  • Installing AcuXDBC/AcuXDBC Server in Windows
    Instructions for installing AcuXDBC and AcuXDBC Server in Windows environments (except for Windows Vista).
  • Installing AcuXDBC/AcuXDBC Server in Windows Vista and or Windows 64 bit environments
    Instructions for installing AcuXDBC and AcuXDBC Server in Windows Vista and or Windows 64 bit environments.
  • Installing AcuXDBC/AcuXDBC Server for UNIX/Linux Client
    Instructions for Installing AcuXDBC/AcuXDBC Server for UNIX/Linux Clients.
  • Installing AcuXDBC/AcuXDBC Server for UNIX/Linux Servers
    Instructions for Installing AcuXDBC/AcuXDBC Server for UNIX/Linux Servers.
  • Providing JDBC Access
  • Installed Executables and Scripts
    List of the executable components and batch files/shell scripts that are installed along with AcuXDBC.
Parent topic: Installation and Licensing
Installing AcuXDBC/AcuXDBC Server in a Windows Environment
Installing AcuXDBC/AcuXDBC Server in Windows Vista
Installing AcuXDBC/AcuXDBC Server on a UNIX/Linux Client
Installing AcuXDBC/AcuXDBC Server on a UNIX/Linux Server


Installing AcuXDBC/AcuXDBC Server in Windows

For installation instructions on Windows Vista, see Installing AcuXDBC/AcuXDBC Server_WinVista.

  1. On Windows, run setup.exe on your product CD-ROM to install AcuXDBC on your machine.
  2. Select AcuXDBC from the product selection list as appropriate. You will be prompted for product codes and license keys during the installation, so have this information ready. The installation process sets an environment variable known as GENESIS_HOME with the location for configuration files and the installation directory. The default installation directory is C:\Program Files\Micro Focus\extend x.x.x\AcuGT\ on Windows (where x.x.x is the extend version number). Though you can have several different configuration files and refer to different ones in your DSNs, they must always reside in the directory pointed to by GENESIS_HOME.
    Note: If you install AcuXDBC in a non-default directory, be sure to modify the DICTSOURCE and FILE_PREFIX variables in the client configuration file. See the topic Configuration > AcuXDBC Configuration for more information on these variables.
The setup.exe file contains defaults used for many of the tools. You may want to duplicate in this file any changes that you made to defaults, to reflect the new defaults used by system utilities
Parent topic: Installing AcuXDBC/AcuXDBC Server


Installing AcuXDBC/AcuXDBC Server in Windows Vista and or Windows 64 bit environments

If you are using the install script from the CD to install AcuXDBC on Windows Vista and or Windows 64 bit environments, you will need to follow a different process from the Installing AcuXDBC_AcuXCBC Server_Windows process. Windows Vista and or Windows 64 bit environments requires that programs be "Run as Administrator" to install correctly. Follow the steps below to ensure that AcuXDBC runs correctly on Windows Vista and or Windows 64 bit environments.
  1. Exit the install script.
  2. Launch Windows Explorer and navigate to the CD drive.
  3. Right-click Setup.exe and select Run as Administrator to launch the installer.
  4. Proceed as normal from there. The installation process sets an environment variable known as GENESIS_HOME with the location for configuration files and the installation directory. The default installation directory is C:\Program Files\Micro Focus\extend x.x.x\AcuGT\ on Windows (where x.x.x is the extend version number). Though you can have several different configuration files and refer to different ones in your DSNs, they must always reside in the directory pointed to by GENESIS_HOME.
    Note: If you install AcuXDBC in a non-default directory, be sure to modify the DICTSOURCE and FILE_PREFIX variables in the client configuration file. See Local Configuration for more information on these variables.

AcuXDBC is available for the 64-bit Windows operating system.

INSTRUCTIONS for use:

Run the 64-bit AcuXDBC installer to setup AcuXDBC for 64-bit Windows onto your system.

Note: The 64-bit Windows system contains two versions of the Microsoft Open Database Connectivity (ODBC) Data Source Administrator tool. The 64-bit version of the ODBC Administrator is located in the standard location in the Control panel under Administrative tools. This Data Source Administrator is actually a 64-bit driver manager. For your convenience, the installer will create a shortcut to the 64-bit ODBC Data Source Administrator tool in the AcuXDBC program group on the start menu. The 64-bit Windows operating system also includes a 32-bit driver manager available for administrating 32-bit data sources. To start up this driver, you must run it individually from a command prompt or create a custom shortcut.

The two drivers can be run individually:

  • The 32-bit version of the ODBC Administrator is located at %WINDIR%\SysWOW64\odbcad32.exe
  • The 64-bit version of the ODBC Administrator is located at %WINDIR%\System32\odbcad32.exe

The 32-bit version of the ODBC Administrator tool displays 32-bit SYSTEM DSNs, 32-bit USER DSNs, and 64-bit USER DSNs.

The 64-bit version of the ODBC Administrator displays 64-bit SYSTEM DSNs, 32-bit USER DSNs, and 64-bit USER DSNs.

Note: The USER DSNs for both 32-bit and 64-bit will be display for both Driver Managers even though the bit size of the driver must match the bit size of the executable calling it. This occurs because Windows uses registry redirection for the "HKEY_CURRENT_USER\Software\ODBC\ODBC.INI" registry key. Registry redirection does not occur for SYSTEM DSNs. The SYSTEM DSNs for 32-bit drivers and for 64-bit drivers are separated. If a 64-bit application tries to use a USER data source created in the 32-bit ODBC Administrator, it will not be able to load the ODBC driver. Similarly, if a 32-bit application tries to use a USER data source created in the 64-bit ODBC Administrator, it also will be unable to load the ODBC driver.

The setup.exe file contains defaults used for many of the tools. You may want to duplicate in this file any changes that you made to defaults, to reflect the new defaults used by system utilities
Parent topic: Installing AcuXDBC/AcuXDBC Server


Installing AcuXDBC/AcuXDBC Server for UNIX/Linux Client

  1. Mount the installation CD-ROM for AcuXDBC.
  2. Change to the mount directory.
  3. Type ./install and follow the instructions given from the command line.
  4. Download an ODBC driver for UNIX. AcuXDBC has been tested with "unixODBC" from www.unixodbc.org/unixODBC-2.2.11.tar.gz. 64-bit platforms require unixODBC version 2.2.12 or later.
  5. Copy the unixODBC*.tar.gz file to a location where you have permission to create files and directories.
  6. Type unzip unixODBC*.tar.gz.
  7. Type tar xvf unixODBC*.tar
  8. Read the readme file located in the directory where the package was extracted and any other readme files with a suffix that describes your operating system (for example, readme.aix for IBM.AIX). These directions are provided for a basic 32-bit Linux (Intel x86) installation.
  9. Read the install file for prerequisites and installation instructions.
  10. Type configure and wait while features on your system are being checked.
  11. Type make and wait for the package to be compiled.
  12. Type make install to install programs, data, and documentation.
  13. Type odbcinst -j to find out where your SYSTEM and USER data sources are located. Here is the location information from a Linux system.

    DRIVERS............: /usr/local/etc/odbcinst.ini

    SYSTEM DATA SOURCES:/usr/local/etc/odbc.ini

    USER DATA SOURCES..:/home/techsup/.odbc.ini

  14. Add the following to the file where your SYSTEM data sources are located (for example, /usr/local/etc/odbc.ini):

    [ODBC Data Sources]

    vision_sys = VORTEXodbc to VISION

    [vision_sys]

    Driver = /usr2/lib/acuxdbc.so

    Description = VORTEXodbc to VISION

    LoginID = system

  15. In /opt/acucorp/xxx/lib, create another odbc.ini file with the following information:

    rem -------------- VORTEXodbc

    fetch_buffer_size 8192 --fetch buffer size (in bytes)

    columns 256 -- max # of database columns

    logical_cursors 1024 -- max # of logical cursors

    db_cursors 64 -- max # of DB cursors

    • If the information above is for use on a local machine, enter: dsn_vision_sys "acuxdbc04:%s/%s/xvision:acuxdbc.cfg"
    • If the information above is for use on a server, enter: dsn_vision_sys "acuxdbc03:%s/%s/xvision:acuxdbc.cfg@20222:servername!acuxdbc04"
  16. Set two operating environment variables called VORTEX_HOME and GENESIS_HOME to the root installation directory of AcuXDBC, /opt/acucorp/xxx/ by default. The following is an example of how to set these variables:

    export VORTEX_HOME=/opt/acucorp/xxx

    export GENESIS_HOME=/opt/acucorp/xxx

    Note: The value of the environment variable should not have a “/” as the last character, because this can interfere with installation and configuration scripts.
  17. Set or modify environment variables that point to the location of the AcuXDBC executables and to tell the operating system where to find the AcuXDBC shared libraries. On Linux, use the PATH and LD_LIBRARY_PATH variables, for example:

    export PATH=/opt/acucorp/xxx/bin

    export LD_LIBRARY_PATH=/opt/acucorp/xxx/bin

  18. Modify the AcuXDBC configuration file. A sample configuration file called acuxdbc.cfg is provided for your convenience. The configuration file must be located at $GENESIS_HOME. There are two variables that are required: DICTSOURCE and FILE_PREFIX. Other variables may be needed depending on your situation. Below is a partial sample of acuxdbc.cfg. showing the syntax for the two required variables. Note that this file also contains sample syntax and instructions for all available variables. If you want to use this file, you can remove the comment indicators from any of the other variables listed in acuxdbc.cfg.

    # The path to your system catalog directory

    DICTSOURCE /usr2/acuxdbc/syscat

    # The path to your data files. You must prepend the line with a semi-colon,

    # use either double backslashes ("\\") or forward slashes ("/"),

    # and separate your paths by semi-colons.

    FILE_PREFIX ;/usr2/acuxdbc/data;/usr2/acuxdbc/sample/acuxdbc/data

    Note: For FILE_PREFIX, the delimiting character is a semi-colon or colon. Spaces are not supported in this AcuXDBC variable.
  19. Verify that the AcuXDBC license file, xvision.alc, is located in the bin directory.
  20. Run the setup script demo.sh located in the $GENESIS_HOME/bin directory.
  21. Try to access a sample Vision file using a utility that came with unixODBC. To run the test, type isql vision_sys system manager.

    A successful connection looks like this:

    Connected! sql-statementhelp [tablename]quit

  22. To use the unixODBC driver, set up a Data Source Name (DSN) for the veterinary data:
    1. From the Start menu, select Programs/extend xxx/AcuXDBC/ODBC Data Source Administrator. The ODBC Data Source Administrator appears.
    2. From the User DSN tab, click Add.
    3. From the Create New Data Source dialog box, select extend AcuXDBC Driver, and then click Finish.
    4. On the AcuXDBC Setup: General Tab, complete the fields as follows:
      Field | Description
      Data Source Name | Enter Vet Data
      Description (Optional) | Enter Sample veterinary application data
      Network Driver | Leave unchecked
      Hostname | N/A
      Port | N/A
      Configuration File | Accept the default value
      Username | System
      Password | Manager
      Confirm Password | Leave blank
    5. Access the veterinary database from an ODBC-compliant application as described in Working with Windows and Java Applications.
Parent topic: Installing AcuXDBC/AcuXDBC Server


Installing AcuXDBC/AcuXDBC Server for UNIX/Linux Servers

  1. Mount the installation CD-ROM for AcuXDBC Server.
  2. Change to the mount directory.
  3. Type ./install and follow the instructions given from the command line.
  4. Set the operating system environment variable GENESIS_HOME to the root installation of AcuXDBC, /opt/acucorp/xxx by default. The following is an example of how to set this variable: export GENESIS_HOME=/opt/acucorp/xxx
    Note: The value of the environment variable should not have a “/” as the last character, because this can interfere with installation and configuration scripts.
  5. Set or modify environment variables that point to the location of the AcuXDBC executables and to tell the operating system where to find the AcuXDBC shared libraries. On Linux, use the PATH and LD_LIBRARY_PATH variables, for example.

export PATH= /opt/acucorp/xxx/bin:$PATH

export LD_LIBRARY_PATH=/opt/acucorp/xxx/bin:/opt/acucorp/xxx/lib:$LD_LIBRARY_PATH

Parent topic: Installing AcuXDBC/AcuXDBC Server
Related tasks
Installing AcuXDBC_AcuXDBC Server_UNIXLinux Client


Providing JDBC Access

With AcuXDBC Enterprise Edition, you have access to Vision data from JDBC as well as ODBC. Below are the instructions for setting up a JDBC installation on UNIX/Linux:
  1. Create a directory on your machine for the AcuXDBC JDBC files.
  2. Put the downloaded .tar file in that directory and untar it. The directory now contains two subdirectories and a vortex.jar file:
    • sample - Sample Java and JDBC programs.
    • html - HTML Java and JDBC method descriptions.
  3. Move the vortex.jar file into a directory pointed to by the Java JVM CLASSPATH environment variable that is used for running the JDBC-enabled application.

    Alternatively, you can add this directory to the CLASSPATH environment variable:

    CShell

    setenv CLASSPATH "$CLASSPATH":"/usr2/acuxdbc"

    Bourne Shell

    CLASSPATH=$CLASSPATH:/usr2/acuxdbc export CLASSPATH

Parent topic: Installing AcuXDBC/AcuXDBC Server


Installed Executables and Scripts

Here is a list of the executable components and batch files/shell scripts that are installed along with AcuXDBC. You can make changes to all scripts in a centralized default settings file, axset.bat.

File | Description
xdbcutil.exe / xdbcutil | System catalog tool
xdbcquery.exe / xdbcquery | Command-line SQL query tool
xdbcsrvr.exe / xdbcsrvr | AcuXDBC Server network daemon
vortex.jar | JDBC and Java class file
ainit.bat / ainit.sh | Creates system catalog and information-schema views
asql.bat / asql.sh | Starts xdbcquery tool
addfile.bat / addfile.sh | Adds named XFD file or file list to system catalog
acuxdbcs.exe / acuxdbcs.sh

Performs functions on xdbcsrvr server daemon with the following options:

“-help”

“-info [-n port][server]” (pings daemon)

Examples: E:\>acuxdbcs -info

AcuXDBCS is running on port 20222 of server jmccoy-xp

E:\>acuxdbcs -info -n 20111 sparky

AcuXDBCS is not running on port 20111 of server sparky

E:\>acuxdbcs -info -n 20999 sparky

AcuXDBCS is running on port 20999 of server sparky

“-install [any valid -start options]” (installs the AcuXDBC server as a Windows service on a specified port)

“-kill [-n port][server]” (kills daemon)

Examples: E:\>acuxdbcs -kill

Kill of AcuXDBCS on port 20999 of server jmccoy-xp successful

E:\>acuxdbcs -kill n 20999 sparky

Kill of AcuXDBCS on port 20999 of server sparky successful

E:\>acuxdbcs -kill -n 20999 sparky

Kill of AcuXDBCS on port 20999 of server sparky failed

connect: errno: 10061

“-remove” (removes the server as a service on a specified port)

“-start [-n port][-l]” (starts daemon)

“-version” (gets the version of the tool)

-debug <params> (runs as a console app for debugging)

demo.bat / demo.sh | Creates system catalog and load it with sample veterinary data
genxconf.bat / genxconf.sh | Generates an AcuXDBC configuration file that includes the required configuration variables set to the values that you define. It also enables you to specify an alternate directory name for GENESIS_HOME and an alternate configuration file name.
Parent topic: Installing AcuXDBC/AcuXDBC Server


Creating a System Catalog and Views

A system catalog, also known as a repository, is where database systems store schema metadata, such as information about tables and columns in your data directories, and internal bookkeeping information.

If you ran demo.bat or demo.sh, you don't need to create a system catalog. One has been created for you. Look for an AcuGT/syscat/ directory to confirm whether a system catalog exists.

For your convenience, we have included a script that creates a system catalog and simultaneously generates information-schema views of the catalog. The views are reflections of the system tables and contain columns that describe your COBOL data, so that you can use SQL syntax that you're used to using (standard SQL).

In addition, AcuXDBC includes a command-line utility, xdbcutil, that lets you create a system catalog for your COBOL data files. xdbcutil reads your XFD files and creates a table, transforming your COBOL file system into a database. The system catalog itself is stored in the COBOL database.

If you plan to port your system catalog to multiple hardware operating systems, be aware of the byte order format for both the machine you created your system catalog on and the machine you are going to deploy on. The machine's byte order format is commonly referred to as big-endian or little-endian. A system catalog created on a machine that uses little-endian (Intel, for example) will not be portable to a machine that uses big-endian (Motorola, for example), and vice versa. In this case, you need to create a system catalog once on each type of machine (big-endian and little-endian) and then port the appropriate catalog to the appropriate target machine.

An alternate method is to dynamically create and load the database on the target machine. In this case, you would send the XFD files to the end-user site, and then create an empty database and load the XFD files into it, either one at a time or in batch mode.

Note: This section describes how to create an empty system catalog. Once you have a catalog, you must populate it with information from your XFDs. This process is described in Loading the System Catalog with Your XFDs.
  • To Create a System Catalog using a Script
  • To Create a System Catalog using xdbcutil
  • xdbcutil Syntax
Parent topic: Installation and Licensing


To Create a System Catalog using a Script

  1. Change to the AcuGT\bin directory where AcuXDBC or AcuXDBC Server was installed.
  2. Enter the following command:
    ainit

    The script creates a series of system tables and views of those tables and places them in the \AcuGT\syscat\ directory by default.

    Note: If you did not accept the default catalog path, be sure to amend your COBOL configuration file to point to your system catalog. Do this using the DICTSOURCE variable.
Parent topic: Creating a System Catalog and Views


To Create a System Catalog using xdbcutil

  1. Change to the directory where you want your system catalog installed.
  2. Enter one of the following commands:
    xdbcutil -c

    f you plan to grant database and table privileges to individual users, use the -pa option as well to create a user/group catalog and an object permissions catalog:

    xdbcutil -c -pa

    Because the above command will create all of the system catalog files in the current directory, you may want to use this command instead:

    On Windows:

    xdbcutil -c -pa -d  %GENESIS_HOME%/syscat

    On UNIX:

    xdbcutil -c -pa -d  $GENESIS_HOME/syscat
    Note: If you use the -d option to specify a catalog path, be sure to amend your COBOL configuration file to point to your system catalog. Do this using the DICTSOURCE variable
Parent topic: Creating a System Catalog and Views


xdbcutil Syntax

The xdbcutil command has this syntax:

xddbcutil [-l LOGFILE] [-d SYSCAT_PATH] [-x XFD_PATH] [-v] [-p] [-pa] [-n] [-s] <-c | -a xfd1 [xfd2...] | -f FILE> | -u xfd1 [xfd2...]>
Note: Use quotes or the short name if specifying a path that contains spaces. XFD filenames, when given, must be of the format:
xfilename[#[tablename] [#filename]]

where xfilename is the XFD filename, tablename is the SQL tablename to use, and filename is the COBOL data filename.

As shown in the tables below, some of the command options are used when creating the system catalog; others are used when loading the system catalog with XFDs.

See Creating a System Catalog and Views for information on using command options when creating the system catalog.

Option | Description
-c | Required — Creates a new system catalog
-d | Specifies a directory for your system catalog. If none is specified, the system catalog is stored in the current directory
-n | Specifies "do not overwrite" the user/group catalog if it exists
-p | Creates a user/group catalog for granting database privileges
-pa | Creates a user/group catalog and an object permissions catalog. A user/group catalog is for granting database privileges. An object permissions catalog is for setting permissions on your tables. Use the GRANT statement to set permissions in these tables

For use when loading the system catalog with XFDs. See Loading the System Catalog with Your XFDs for information on loading the system catalog.

Option | Description
-a | Adds an individual table definition from the specified XFD file. You can use either -a or -f to populate the system catalog with XFDs, but do not use both in the same operation
-d | Specifies the location of your system catalog. Required if you are not in the system catalog directory when you issue the xdbcutil command
-f | Adds table definitions from the specified file, which contains a list of XFD filenames. You can use either -a or -f to populate the system catalog with XFDs, but do not use both in the same operation
-l | Defines the log output file name
-o | Specifies table ownership. This must be a valid authorization ID that was created with the GRANT SQL statement for database privileges. See GRANT (Database Privileges) command for information on the GRANT SQL command.
-s | Says to include data storage method switch. Required if you are using XFDs created with a pre-8.0 version compiler, and used one of the data storage compiler options (-Dci, -Dcm, -Dcn...) when creating your XFDs. If you compiled with any of the folllowing -D commands, then use the corresponding -s command: -Dca / -s a -Dci / -s i -Dcm / -s m -Dcn / -s n -Dcv / -s v -Dcb / -s b -Dcr / -s r
-u | Updates table definitions from the specified XFD files. Use this option if you have already loaded an XFD file into the system catalog but have modified it for some reason. Reloading a file with -a results in an error
-v | Initiates a verbose reporting mode
-x | Specifies an XFD file directory — required if your XFD files are not in the current directory

Minimum options

XFD filenames are of the format:

xfilename[#[tablename][#filename]]
where
  • xfilename - is the XFD filename
  • tablename - is the SQL tablename to use
  • filename - is the Vision data filename
Note: All tables in a AcuXDBC database have an owner. By default, the owner of the table is PUBLIC, or you can specify a different authorization ID using the -o option to xdbcutil. If you don't want a table owner to be listed publicly in applications like Microsoft Access, specify “-o “ ” ” and set the IGNORE_OWNER variable to 1 (on, true, yes) in your configuration file.
Parent topic: Creating a System Catalog and Views
Related information
IGNORE_OWNER configuration variable


Granting Database Privileges

Access to objects can be secured on both the database and the object level with AcuXDBC. If you created your database using xdbcutil or ainit with the -p or the -pa options, you will have a database that supports user authorization IDs. (By default, ainit will create the database with the -pa option, providing both database-level privileges and object-level privileges.)

By default, the system will create a single user system with the password manager. There is also a second special authorization ID called public, which is used only in the context of object-level privileges. Any object owned by public is accessible by all authorization IDs. By default, when you load an XFD into AcuXDBC, the owner of the object will be public. You may override this by specifying the -o option to xdbcutil or the -u option to addfile.

Once you have created your database with database-level privileges, you will need to create additional user authorization IDs. This is done using the SQL GRANT command from within the command-line query tool or script (xdbcquery or asql) or some other ODBC-enabled query tool that will allow the input of SQL commands. (The GRANT statement is described in detail in the topic GRANT (Database Privileges) command. The command-line query tool is described in To start xdbcquery from the command line.

If you wish, you can load the system catalog with your XFDs and send the loaded tables to your customer or end user. A site administrator can grant database and table permissions.

A second — and perhaps more efficient — approach to setting up a new database is to use an SQL script file to create all of the user authorization IDs and object-level privileges. This script can then be run at the end-user site using the command-line query tool. For example:

asql -u system -p manager -r my_script.sql

where my_script.sql is a text file containing the SQL commands to perform. For an example of this, see the ainit script, which executes the cview.sql script to create the information schema in new databases.

Once you have granted users database privileges, you can modify their object-level privileges as well.

  • To grant database privileges
  • To modify privileges for existing users
Parent topic: Installation and Licensing


To grant database privileges

  1. Using a command line navigate to AcuXDBC bin directory. Run asql from the command line using the following syntax:
    asql -u system -p manager -c myconfigfile.cfg

    (This command creates the default schema of authorization ID system with the password manager.)

    The following prompt appears:

    SQL (/? for help) ==>
    Note: If you REVOKE privileges from system before creating another authorization ID with database administrator (DBA) privileges, no one will be able to connect and your system will be unusable. Should this happen, you will need to recreate the system catalog as described in Creating a System Catalog and Views.
  2. Grant DBA privileges to yourself by issuing a GRANT statement such as:
    GRANT DBA TO tsmith IDENTIFIED BY password123;
  3. Grant the privileges CONNECT and/or RESOURCE to each of your users:
    CONNECT | Lets grantees connect to the database when the password is correct
    RESOURCE | Lets grantees create objects/tables in the database
    DBA | Implies both CONNECT and RESOURCE and lets grantees read or modify any table in the database (we suggest that you use caution when granting this privilege — anyone with DBA privileges has complete control over a database)

    For example, you might issue the following commands:

    GRANT CONNECT,RESOURCE TO jsmith IDENTIFIED BY password1;
GRANT CONNECT TO sjones IDENTIFIED BY password2;
  4. When you have finished granting privileges, quit the query tool by entering:

    /q

Parent topic: Granting Database Privileges
Related information
GRANT (Database Privileges) command


To modify privileges for existing users

Issue a GRANT statement without the IDENTIFIED BY clause, for example:

GRANT CONNECT TO jsmith;
Parent topic: Granting Database Privileges
Related information
REVOKE (Database Privileges) command


Loading the System Catalog with Your XFDs

The xdbcutil utility can be used both to create a system catalog and to populate it with data. The xdbcutil command is very flexible, so you have many options for loading your XFDs into the system catalog.

For your convenience, we have provided a script, addfile, for loading XFD files into your system catalog. This script will allow you to default many of the common options.

  • To Load XFDs using a Script
  • To load XFDs using the xdbcutil utility
  • Setting Up File Aliases
  • Multi-company Support
Parent topic: Installation and Licensing


To Load XFDs using a Script

  1. Change to the \AcuGT\bin directory where AcuXDBC or AcuXDBC Server was installed.
  2. Enter one of the following commands:
    addfile filename

    where filename is the name of the XFD file to add to the system catalog. By default, the script assumes that your XFDs are stored in the current directory and that your system catalog is stored in AcuGT/syscat/. Also by default, the user PUBLIC is assumed.

    If you stored your XFDs and/or system catalog elsewhere or if you want to specify an alternate user, you can edit the script or add command-line options as follows:

    addfile [-d syscat_path] [-x xfd_path] [-u user] filename

    Or:

    addfile [-d syscat_path] [-x xfd_path] [-u user] -f filelist

    The second form assumes that you have created a text file that list all of the XFD files that you want to load into the system catalog. When you create a list file, use just the base name of the XFD files; do not use the `.xfd' suffix. List the XFD files one per line. For example, you might create a file called "list.txt" containing:

    animals
    accounts
    pets

    In this case your addfile command would be:

    addfile -f list.txt
Parent topic: Loading the System Catalog with Your XFDs


To load XFDs using the xdbcutil utility

To load the system catalog with your XFDs, minimally, use the -d and -a options to xdbcutil, as shown below:

xdbcutil [-d SYSCAT_PATH] <-a xfd1 [xfd2...]>

For example:

xdbcutil -d c:\data\dict -a c:\data\XFD\animals

results in the system catalog in c:\data\dict being loaded with information from the XFD named animals found in c:\data\XFD.

Rather than prepending the XFD filenames with their path, however, you can specify the XFD directory with the -x option, as in:

xdbcutil -d c:\data\dict -x c:\data\XFD -a animals

This would have the same effect as the preceding example.

If desired, you can create a file with a list of XFD names and then specify it with an -f option, along with the -x option to specify the directory. For example, this command:

xdbcutil -d c:\data\dict -x c:\data\XFD -f list.txt

and a list.txt that contains this:

animals
accounts
pets

results in a system catalog with table definitions from animals, accounts, and pets.

If you have several different XFD directories, you can create the list file with the XFD paths prepended. For example, this command:

xdbcutil -d c:\data\dict -f list.txt

and a list.txt that contains this:

c:\data\data\animals
c:\data\data2\accounts
c:\data\other\pets

results in a catalog with three table definitions, coming from XFDs in three separate XFD directories.

Note: xdbcutil command syntax is described in xdbcutil Syntax.

See Setting Up File Aliases for more information on xdbcutil.

Parent topic: Loading the System Catalog with Your XFDs


Setting Up File Aliases

With AcuXDBC, you can define file aliases when adding XFDs to your system catalog with xdbcutil.

A file alias is a way to map data files, .xfd files, and SQL tables. It is used at runtime to dynamically reassign a file name that is referenced in an ASSIGN clause or, if the ASSIGN clause is a variable, from the FILE directive.

File aliases are useful when:

  • A single COBOL file description can reference multiple physical data files, such as when the ASSIGN TO clause of a COBOL select statement is a variable
  • A single table name in SQL can refer to multiple physical COBOL data files

These situations can easily occur in a large company, in which one COBOL file needs to point to more than one company. For example, Corporation A supports several other companies (say, company01 and company 02) and wants to use the same code to point to each company. Corporation A has named its COBOL file company, so the XFD file would be called company.xfd. Because Corporation A wants to use this same code for company01 and company02, it has set up the code to point to data files company01.dat and company02.dat.

Let's also say that Corporation A wants to use a different name when referring to the data files from SQL (maybe the name is too long or cumbersome). No problem! Corporation A can specify all three components: the XFD name, the database table name, and the data file name. All of this information, along with the schema to load the tables into, is specified using the Windows batch file addfile.bat or the UNIX/Linux shell script addfile.sh. You can also you xdbcutil.exe on Windows or the xdbcutil/ on UNIX/Linux.

Note that another issue that you may need to consider is the configuration file variable FILE_PREFIX, which points to the directory in which your files are stored.

If your .xfd and data files for a table have different names, define a file name alias on the xdbcutil command line or in the list file using the standard syntax. Simply enter the alias as the third parameter.

xfilename[#[tablename][#filename]]

For example:

Acme#Table1#Company1

indicates that an alias should be assigned to the file named Company1. In this example, Acme is the name of the XFD file being read, Table1 is the name to be used in SQL statements, and Company1 plus FILE_SUFFIX, if any, is the filename that will be used.

See Loading the System Catalog with Your XFDs for information about loading XFD files.

Parent topic: Loading the System Catalog with Your XFDs


Multi-company Support

AcuXDBC offers convenient ways to manage multiple company data sets. For example, you may have two sets of data for Company01 and Company02. The layouts of the data files are the same, but the file names have different prefixes or suffixes. For example, ACCT01 and ACCT02 may be the accounting files for Company01 and Company02, respectively. They are stored in different directories.

Rather than having to set up system catalogs for each of your companies individually, you can do one of two things:

  • You can have a different configuration file for each company. In this configuration file, you can use wildcards and substitution characters to identify which data files to access, allowing you to have a single system catalog that gets populated only once and yet supports more than one company
  • You can set up a separate schema for each company, and then you can specify which table to access. For example, you could set up a schema for "acme" and a separate schema for "generic," and then qualify your SQL statements.
  • To set up a multi-company DSN with wildcard substitution
  • To set up multi-company with separate schemas (table ownership)
Parent topic: Loading the System Catalog with Your XFDs
Related information
To set up a multi-company DSN with wildcard substitution
To set up multi-company with separate schemas (table ownership)


To set up a multi-company DSN with wildcard substitution

  1. Create a text file listing the XFD filenames for your companies. Name the file list.txt or something similar.

    For example, if your data is:

    main.xfd
ACCT01.dat
ACCT02.dat
ACCT03.dat

    you might have an entry like this in list.txt:

    main#AcctTbl#Acct$$

    where main is the XFD name, AcctTbl is the table/repository name, and Acct$$ represents the indexed file name.

  2. In the configuration file, acuxdbc.cfg by default, use the FILENAME_WILDCARD variable to define the wildcards and their respective substitution characters.

    For example, the configuration file might contain:

    FILENAME_WILDCARD $$=01
  3. Create your system catalog using the -f option as shown:
    xdbcutil -d c:\data\dict -f list.txt

    When building the system catalog, xdbcutil uses the XFD "main" to create a repository table called AcctTbl.

  4. At the company site, create a single data source name (DSN) for Accounting, and point to the configuration file that contains the substitution characters for that company. See Setting Up DSNs on the Client for instructions on creating DSNs.

When a user accesses the table AcctTbl from SQL,AcuXDBC looks in the configuration file for the FILENAME-WILDCARD variable, and, substituting 01 for $$, accesses the data file, Acct01. In programming terms, when "SELECT * from AcctTbl;" is issued, it functions as if SELECT * from acct01; was entered.

There is no limit on the number of wildcards/replacements that you can use with AcuXDBC. You can change several characters in a filename, for example:

ACCT>=$$**

where the actual filename would be ACCTZ01AA and the configuration file entry would be:

FILENAME_WILDCARD >==Z ;$$=01;**=AA

You don't have to create a list file to specify your company wildcards. If you prefer, you can specify them directly on the xdbcutil command line, like this:

xdbcutil -d c:\data\dict -x c:\data\data  -a mainxfd#AcctTbl#Acct$$
Parent topic: Multi-company Support
Related information
FILENAME_WILDCARD configuration variable


To set up multi-company with separate schemas (table ownership)

Specify database table ownership using the -o option to xdbcutil when creating your system catalog.

For example, there could be two tables named AcctTbl — one owned by company01 and one by company02.

Filename | Database Name | Owner | Table name
ACCT01 | dd | company01 | AcctTbl
ACCT02 | dd | company02 | AcctTbl

On the command line, you specify:

xdbcutil -d <catalog_dir> -x <xfd_dir> -o <owner's name> xfdname#tablename#filename

Or in this case:

xdbcutil -d c:\data\dict -x c:\data\XFD -o company01 mainxfd#accttbl#acct01
xdbcutil -d c:\data\dict -x c:\data\XFD -o company02 mainxfd#accttbl#acct02

Then you can access all the data files with one SQL query to one data source name (DSN), like this:

SELECT * FROM company01.accttbl AND company02.accttbl WHERE .....

You can also use a SYNONYM for company01.acctbl, such as acctab:

CREATE SYNONYM acctab FOR company01.acctbl;
Note: If you don't want a table owner to be listed publicly in applications like Microsoft Access, specify “-o “ ” ” when loading the table with xdbcutil and set the IGNORE_OWNER variable to 1 (on, true, yes) in your configuration file.
Parent topic: Multi-company Support
Related information
IGNORE_OWNER configuration variable


Setting Permissions on Your Database Tables

You set object privileges — permissions on individual tables, views, and so forth — by modifying the GENESIS_AUTHS system table. GENESIS_AUTHS is created when you use the -pa option to xdbcutil or ainit when creating the system catalog. (While ainit defaults to -pa, you must specify -pa with xdbcutil.)

Like the database-level privileges described in Granting Database Privileges, this is done by issuing GRANT commands from an SQL query tool like xdbcquery. Use the SQL GRANT command to specify permissions for specific users. If a table is loaded into the PUBLIC schema (the default), all users have all access levels to the table. If a table is loaded into an alternate schema, the SQL GRANT statement must be executed on the table to give access permissions to individual users, or to all users if permission is granted to PUBLIC.

Note that different access permissions can be granted to different users. For example, one user may have just SELECT (or what we might call read-only) permissions, while a different user might have SELECT and UPDATE permissions (this user can modify data).

Setting permissions is often performed at the user site by a site administrator. If you would like to pre-set a group of permissions, the series of GRANT statements can be placed in a text file and then executed as a script using asql or xdbcquery. For details, see the topic GRANT (Database Privileges) command.

  • To set permissions on your database tables
Parent topic: Installation and Licensing


To set permissions on your database tables

  1. From a command prompt locate asql in your bin directory and log in as database administrator.

    For example, enter the following at the prompt:

    asql -u system -p manager

    After a brief message, the following prompt appears:

    SQL (/? for help) ==>
  2. Grant table-level privileges to individual users or groups of users.

    For example:

    GRANT SELECT ON table_a TO sjones;
GRANT ALL PRIVILEGES ON table_b TO public;

    Other privileges include DELETE, INSERT, and UPDATE.

    The following table describes some privilege levels:

    SELECT | Gives grantees read-only access. This allows them to issue the SELECT statement on the object, but nothing else
    SELECT, UPDATE, DELETE, and INSERT | Allows grantees to read, write, delete, or insert data
    ALL PRIVILEGES | Passes on all applicable privileges that you are entitled to grant
    USAGE | Allows grantees use the object to define another object
Parent topic: Setting Permissions on Your Database Tables
Related information
GRANT (Object Privileges) command


Starting AcuXDBC Server (Network Only)

If you or your users are operating in a network environment, the final step is to start theAcuXDBC server daemon on the server. If you are operating on a stand-alone machine, this step is not necessary; you can begin using ODBC applications to access your data right away.

AcuXDBC Server can be started under any user ID on the system. In this mode, all file access will be performed using the user and group ID under which the daemon was started. You also have the option of startingAcuXDBC under the root or superuser account and turning on operating system (OS) authorization checking with the -a option. This option lets one user start a process and pass ownership to another. In this mode, you must pass a valid operating system user ID and password as part of the connect string. AcuXDBC Server will use this information to perform an OS authentication of the user and then spawn a process to handle the requests using this user information.

Note that to perform the functions described in this section on a UNIX server, you should be logged in as root or superuser. To perform these functions on a Windows NT or Windows 2000 server, you should be logged in from the administrator account or from an account that belongs to the administrators group.

To Start AcuXDBC Server

Enter the following at the command prompt:

acuxdbcs -start

This runs a script that invokes the xdbcsrvr daemon on the default port, 20222, with the "-k" option to request data encryption over the network. If the xdbcsrvr daemon is already running, AcuXDBC Server displays the message:

The AcuXDBC Server 9.x.x on the default port <20222> service is already installed

A new xdbcsrvr process will not be started. You can, however, start multiple AcuXDBC Servers on different ports. If you want to start the AcuXDBC Server with new options, you must stop and restart xdbcsrvr.

If you would like to invoke the server daemon with different security, logging, or port options, you can issue the xdbcsrvr command directly. Following is the command syntax for xdbcsrvr.

Command Syntax

xdbcsrvr [-a[l]] [-p] [-kn] [log]

or

acuxdbcs.exe -start [-n port] [-1]

Optional arguments to xdbcsrvr include:

-a[l] Activates the operating system (OS) authorization checking. This option lets one user start a process and pass ownership to another.

You must pass a valid OS user ID and password as part of the connect string, so the spawned service knows who owns it. xdbcsrvr performs a default OS authentication.

If the [l] modifier is specified, xdbcsrvr logs the outcome of the authentication request to the system log. On UNIX, this is syslogOn Windows, this is the event log

-kn | Specifies a masking key value used to decrypt incoming OS and DBMS user ID and password information. Clients must have the same value in their net.ini file in the KEY_CONNECT variable
-pport_number | Assigns the listener port number for clients to request service. The default is 20222
log | Starts logging. It puts a log file named tcmprocessid.log in the directory in which xdbcsrvr is started
  • Pinging AcuXDBC Server
  • Stopping AcuXDBC Server
Parent topic: Installation and Licensing


Pinging AcuXDBC Server

Use "acuxdbcs -info" to ping the xdbcsrvr process. If no server is specified, the xdbcsrvr process is pinged on the current host; otherwise the process is pinged on the named host. You may get a message similar to the following:

You may get a message similar to the following:

On Windows

  • For a successful call:
    acuxdbcs.exe -info myserver

    you receive the response:

    xdbcsrvr is running on port 20222 of server myserver
  • For an unsuccessful call:
    acuxdbcs.exe -info -n 2345 myserver

    you receive the response:

    xdbcsrvr is not running on port 2345 of server myserver
connect: errno: 10061

On UNIX/Linux

  • For a successful command:
    acuxdbcs.sh -info myserver

    you receive the response:

    Pinging 'myserver'.
vtxnetd is alive and kicking (1st attempt).
Host process ID       :23526
Requires byte flipping: No
Character set - Client: ASCII
           Host : ASCII
  • For an unsuccessful command:
    acuxdbcs.sh -info -n 2345 myserver

    you receive the response:

    Pinging 'myserver'
SORRY: connect: Connection refused
Parent topic: Starting AcuXDBC Server (Network Only)


Stopping AcuXDBC Server

Use

 acuxdbcs -kill [-nport] [server]

to halt (kill) the xdbcsrvr process on port 20222 or the port specified by the-noption. On UNIX/Linux, you may also use "xdbckill [-p<port#>]". If no port is specified, the xdbcsrvr process is halted on the current host; otherwise the process is halted on the named host.

On Windows, all client connections are terminated. On UNIX/Linux, client connections remain activ.e

CAUTION:
The xdbcsrvr process can also be terminated from UNIX/Linux using the command "kill -9" (signal #9). However, a signal #9 prevents xdbcsrvr from performing an orderly shutdown and should never be used when clients are actively using AcuXDBC.
Parent topic: Starting AcuXDBC Server (Network Only)


Setting Up DSNs on the Client

Traditionally, the data source is one of the main components of an ODBC installation. Physically, data sources consist of sets of data and their associated environments. This means that the term data source actually indicates the data files, the operating system, the file system or RDBMS used to manage the physical data, and the optional network software used to access this data. The term data source name (DSN), therefore, refers to something rather complicated.

Because part of the ODBC mission is to hide the complexity of underlying software, ODBC architects have chosen to use an abstract name to identify all the components of a data source. This data source name maps all the underlying software components necessary to access the data.

The name you assign to a data source is arbitrary. However, when users try to access the data files, they will be asked to specify the DSN. Therefore, you should assign a meaningful name that represents the type of data that the files contain or the type of query that will be made against the files.

This help section describes how to create local data source names (or DSNs) for your COBOL data files.

You begin by adding the AcuXDBC driver on the ODBC Data Source Administrator of the Windows control panel. (The ODBC Data Source Administrator, included as part of your operating system, is your interface for adding, removing, or configuring ODBC data sources on your system.) Once you add a driver, you define the data source name and configuration file through the AcuXDBC Setup screen.

  • Adding a Data Source Name
    Instructions for adding a DSN to the ODBC Data Source Administrator.
  • Copying DSNs to Other Network Machines
Parent topic: Installation and Licensing


Adding a Data Source Name

To add a DSN to the ODBC Data Source Administrator, follow these steps.
  1. From the Start menu, select All Programs/extend x.x.x/AcuXDBC/ODBC Data Source Administrator. The ODBC Data Source Administrator appears with the User DSN tab selected. User DSNs are one of three types of DSNs managed by the ODBC Data Source Administrator:
    DSN | Description
    User | Stores information about how to connect to a specific data source; may be used only by the current user on the current machine.
    System | The most common type of DSN that you and your users will create for AcuXDBC. Same as the UserDSN, but available to all users on a particular machine, including NT services. Local to the computer, rather than dedicated to a user. The system or any user having privileges, can use a data source set up with a system DSN.
    File | A file-based data source that may be shared among all users who have the same drivers installed. AcuXDBC does not support File DSNs.
  2. Select the User DSN or System DSN tab, depending on your preference, and click Add.
  3. From the Create New Data Source dialog box, select AcuXDBC Driver, and then click Finish. If AcuXDBC Driver is not an option in the list box, reinstall AcuXDBC on your system. The AcuXDBC Setup screen appears. It contains three tabs: General, Advanced, and Logging. Complete these tabs. For more information, see the following related topics.
  • AcuXDBC Setup: General Tab
    How to set up the AcuXDBC Setup General Tab.
  • AcuXDBC Setup: Advanced Tab
    How to set up the AcuSDBC Setup Advanced Tab
  • AcuXDBC Setup: Logging Tab
    How to set up the Logging tab in AcuXDBC Setup.
Parent topic: Setting Up DSNs on the Client


AcuXDBC Setup: General Tab

In the General tab, enter the information that is requested, then click OK. Descriptions of each field are shown in the table below.

Field Description

Data Source Name (Required)

Enter a string that identifies the name of the data source that you are creating. Specify a name that represents the type of data in this group of data files or the type of query that will be made against these files. Since this name is used every time a user opens this data source, select a name that is meaningful to users. (For example, “ACME Payroll” might be used for payroll files for the ACME Corporation.)

The name of the data source must be no longer than 63 characters. Follow the Windows file-naming conventions when using special characters in data source names. Also, note that the name you choose must be unique.

This is a required field. Default value is blank. Description

Description (Optional)

Enter a description of the data source for additional user clarification. Default value is blank.

Network Driver

Check this box if this is a network data source.

Hostname

If this is a network data source, enter the hostname ofthe server on which the data resides.

Port

If this is a network data source, enter the port number on whcih the server is listening. Default is 20222.

Configuration File (Required)

Browse to the configuration file that you created for the data source (a remote file if this is a network data source).

The configuration file defines the location of your Vision files, file case instructions, and much more. This is a required field. By default, it is located in the installation directory and named “acuxdbc.cfg”.

Username (Optional)

A username for the person who will be logging into the database on this machine. Default value is blank. If you have set up usernames, but the Username field is blank, you will be prompted for one at the time of connect.

Password (Optional)

A password to be associated with the username. Default value is blank.

Confirm Password

Confirm the password by entering it a second time.

Parent topic: Adding a Data Source Name


AcuXDBC Setup: Advanced Tab

Into the Advanced tab, enter the following infromation or accept the defaults, then click OK.

Field Description

Fetch Buffer Size

Enter the size of the fetch buffer in bytes. The fetch buffer indicates how much data will be fetched or retrieved from a query at time. Allowable values are 1024 through 32766. Default value is 4096.

Merge Buffer Size

Enter the size of the merge buffer in rows. This is the number of unique rows that your query can return. Default value is 10,000.

Memory Sort Pages

Enter the number of memory sort pages. This indicates how many of the "Total Sort Pages" will reside in memory. Allowed values are 100 to 999,999. Default value is 1000.

Total Sort Pages

Enter the total number of sort pages. Total sort pages is the number of virtual memory pages used to sort results sets. Allowed values are 1000 to 99,999,999. Default value is 10,000.

Maximum Statements

Enter the maximum number of statements allowed. Values are 10 to 4096. Default value is 256. See Maximum Cursors.

Maximum Cursors

Enter the maximum number of cursors allowed. Allowable values are 10 to 1024. Default value is 64.

AcuXDBC has a concept of logical cursors (nlc) that are mapped over a smaller number of actual DB Cursors (ndc). If you create SQL statements equal to or fewer than the number of DB Cursors set, it is a straight one-to-one relationship. However, when you attempt to open more, AcuXDBC searches for the oldest "soft-closed" logical cursor that it can "unhook" from a data base cursor and assign to the new statement. If the application tries to use the original statement, AcuXDBC will look for another unused logical cursor to donate its DB Cursor.

If no cursors can be unhooked (because results are pending), then an error message "Too many concurrently open cursors" is returned.

Maximum Columns

Enter the maximum number of columns allowed in a single table. Allowable is 1 to 1024. Default value is 256. (Please not that some Microsoft applications will not allow more thank 256 columns in a table.)
Note: The Vision file or table supports 65535 field names (columns); however, you may be limited in your queries to the table based on the query tool used. For instance, the command-line query tool will support only result sets with a maximum number of 512 columns. Queries through ODBC Driver default to 1024 columns.
Parent topic: Adding a Data Source Name


AcuXDBC Setup: Logging Tab

You can gather information from AcuXDBC to help you troubleshoot server processes and debug your client applications. Into the Logging tab, enter the information that is requested or accept the defaults, then click OK.

Field | Description
Client Logging: |
Full Logging | Check this box if you want detailed logging on the client. By default, AcuXDBC performs abridged logging. Abridged logging, more space efficient, records only selected items rather than the complete control structure.
SQL Logging | Check this box if you want to create an SQL log file locally.
Include Time | Check this box if you want to include the time to complete each call in the local log file.
Unique Filenames | Check this box if you want unique identifiers to be appended to the name of the local log file.
Server Logging: | These options appear when you check Network Driver on the General tab.
Log Filename | Browse to the name of the remote log file used for AcuXDBC logging. By default, this is ACUXDBC_HOST_LOGFILE_pid.log, where pid is the host process ID. Log files are created in the local directory that is current when AcuXDBC starts. If you want your log field to write to another location, you must specify a fully-qualified file name.
Full Logging | Check this box if you want detailed logging on the host. By default, AcuXDBC performs abridged logging. Abridged logging, more space efficient, records only selected items rather than the complete control structure.
SQL Logging | Check this box if you want to create an SQL log file on the host.
Include Time | Check this box if you want to include the time to complete each call in the log file on the host.
Unique Filenames | Check this box if you want unique identifiers to be appended to the name of the remote log file.
Hide Errors | For Windows servers only, check this box if you want AcuXDBC to quit when a GPF error occurs.
Hide GPF Errors | For Windows servers only, check this box if you do not want to display GPF dialog boxes to the end user.
Parent topic: Adding a Data Source Name


Copying DSNs to Other Network Machines

If desired, you can create a single DSN, then download it to other machines in your network using the .reg file.

Parent topic: Setting Up DSNs on the Client


The System Catalog

This help section describes the structure and purpose of the system catalog.

  • Introduction
  • System Catalog Structure
Parent topic: AcuXDBC Version 10.2.0 User's Guide


Introduction

The system catalog forms the core of your database. It comprises a set of system tables that describe all of the tables and relations described by the database. You can have multiple system catalogs (databases), but only a single catalog may be accessed at one time. The system catalog is portable between machines with the same byte ordering (little endian to little endian and big endian to big endian).

AcuXDBC creates a system catalog corresponding to information it reads from your XFDs. Once this information is loaded,AcuXDBC no longer requires your XFDs. Instead, it refers to the system catalog to obtain the information needed to construct and display your COBOL tables. This gives you the option of providing end users with XFD files for building their own system catalog, or you can provide them with a pre-built system catalog. The ability to supply a pre-built system catalog can lead to other benefits for your applications. For example, you can also pre-build user logins, database object permissions, and complex data handling views.

The primary advantage to a system catalog is that it allows for much greater relational-database-like behavior.

This help section describes the structure of the system catalog, and in doing so, orients you to the environment from which you can access and manage your database. It shows how a newly created COBOL database may appear to users after the initial install of AcuXDBC and a system catalog populated with sample customer data. Database administrators and other programmers should find this information useful for more effectively managing and querying the database.

Note: This section is not intended to teach SQL programming or how to manage a database. Consult a resource dedicated to SQL programming and database management for a fundamental understanding of these concepts.
Parent topic: The System Catalog


System Catalog Structure

The examples in this help section are based on the sample catalog created from the quickstart demo included with AcuXDBC. The examples depict what a user encounters after the system catalog is created and loaded using this installation script and a data source name (DSN) is created. See Setting Up DSNs on Client for a description of the DSNs.

The system catalog displays the database tables that are created from your XFD files. It also contains system tables that you can query to obtain information about the definitions that make up your tables. The initial structuring of the catalog places or assigns your tables to the PUBLIC schema, which allows any database user to access the tables. AcuXDBC also creates two other schemas that appear as users or owners, depending on the client application being used to view the catalog. These schemas are called INFORMATION_SCHEMA and SYSTEM.

For example, the following Microsoft Query Add Tables screen shows a partial list of the catalog tables that appear under PUBLIC for the sample veterinarian database:

Under the Options button of this screen, you can choose which types of objects to show. For example, if you uncheck all except tables, you will see only Accounts, Animals, Clients, Codes, and Pets under the PUBLIC schema.

From Microsoft Access, the same veterinarian database tables appear as shown below:

  • PUBLIC
  • GENESIS Tables
  • INFORMATION_SCHEMA
  • DUAL
Parent topic: The System Catalog


PUBLIC

Tables created from your XFDs have a schema or owner. By default, this owner is the authorization ID PUBLIC. Tables or other database objects owned by PUBLIC are accessible to any authorized database user. This includes users initially created, as well as any additional users added in the future.

If you don't want a table owner to be listed publicly in applications like Microsoft Access, specify the following option when loading the table with xdbcutil:

-o " "

and set the IGNORE_OWNER variable to 1 (on, true, yes) in your configuration file. (Note that there is a blank space between the parentheses.) However, you will usually want to display owner and tablename.

Parent topic: System Catalog Structure
Related information
IGNORE_OWNER configuration variable


GENESIS Tables

Although appearing under the PUBLIC schema, GENESIS_TABLES is actually in a special class of objects in the database called system tables, not to be confused with the SYSTEM schema. These system tables are internal tables required by the AcuXDBC processor. When you execute SQL statements, the AcuXDBC processor constantly refers to these tables to complete the SQL command. These system tables are marked as System tables in the catalog, and they begin with GENESIS_. If you don't want to see these tables in tools such as Microsoft Query, uncheck the System Tables checkbox under the Options button of the Add Tables dialog box.

You cannot change or modify these system tables directly. The content of these tables is maintained by the AcuXDBC processor and is modified only as an effect of executing various SQL statements or the use of the AcuXDBC command-line tools and scripts, such as addfile. For example, issuing the following command not only results in AcuXDBC creating a new table, it also results in a new row being entered into the table GENESIS_TABLES.

CREATE TABLE MYTABLE(coll CHAR(10));

This effect can be seen in asql with the following command:

SQL (/? for help) ==> SELECT
SQL continued ======>      t_owner, t_name
SQL continued ======> FROM
SQL continued ======>      genesis_tables
SQL continued ======> WHERE
SQL continued ======>      t_name = 'MYTABLE';

 T_OWNER                        T_NAME
 ------------------------------ ------------------
 SYSTEM                         MYTABLE

SQL (/? for help) ==>

Note that the table name in the query is in upper case.

The system tables include the following:

Table Name | Description
GENESIS_AUTHS | Enables the setting of object-level authorizations on objects (for example, tables and views) by the GRANT SQL statement. These privileges are SELECT, INSERT, UPDATE, and DELETE
GENESIS_COLUMNS | Provides the mapping between SQL tables/views and the columns that comprise them. These fields are equivalent to the COBOL fields that comprise a File Descriptor (FD)
GENESIS_CONDITIONS | Tracks the conditions used to modify the result set based on the values in certain columns
GENESIS_DEPENDS | Keeps track of view dependencies
GENESIS_FORKEYS | Defines foreign key relationships, but is not currently used.
GENESIS_INDEXES | Provides the mapping between SQL indexes and the COBOL keys
GENESIS_TABLES | Provides information about the tables and views that comprise a database. This contains all of the COBOL XFD files that you have loaded into the database, as well as system tables
GENESIS_USERS | Enables a security method based on user ID and password
GENESIS_VIEWS | Describes the SQL view definition
GENESIS_XCOLUMNS | Provides the mapping between SQL indexes and the COBOL key segments
Parent topic: System Catalog Structure


INFORMATION_SCHEMA

There is a special schema created for you if you create your database using ainit or demo.bat called information_schema. This schema is used to store a set of views that pulls information out of the system tables that begin with GENESIS_. These views are modeled after the SQL92 and SQL99 INFORMATION_SCHEMA.

INFORMATION_SCHEMA views provides a common interface to query object definitions. For SQL programmers used to working with other SQL-compliant databases, these views provide an intuitive method of retrieving information about your database. Only the COLUMNS, TABLES, and VIEWS objects are created. The SQL script that creates the INFORMATION_SCHEMA views is located in %GENESIS_HOME%\bin\cview.sql on Windows. These views are provided as a convenience only. You are free to modify or expand the script to meet your site’s particular needs.

Using Microsoft Query as an example, when you choose the owner INFORMATION_SCHEMA from the Add Tables dialog box, the box displays the following:

When you double-click * or execute the following SQL command:

SELECT * FROM INFORMATION_SCHEMA.TABLES;

the following information is displayed for each of the Veterinarian database tables:

Note: You can query and read the column headings, but not modify them.
  • INFORMATION_SCHEMA.COLUMNS
  • INFORMATION_SCHEMA.TABLES
  • INFORMATION_SCHEMA.VIEWS
Parent topic: System Catalog Structure


INFORMATION_SCHEMA.COLUMNS

This view contains the following information on each user-defined or publicly created column:

Column Heading | Definition
table_catalog | Database containing the column; this column is always blank, because it is limited to the current database
table_schema | Schema (owner) of the column; the owner can be either the current schema (user) viewing the INFORMATION_SCHEMA or the PUBLIC schema
table_name | Name of the table containing the column
column_name | Name of the column
ordinal_position | The column's physical location in the table
is_nullable | Indicates if NULL is allowed (Y/N)
data_type | Column data type
character_octet_length | Applies to char and varchar, the number of bytes in the column
numeric_precision | The maximum precision column for decimal and numeric data types
numeric_scale | The maximum scale column for decimal and numeric data types
Parent topic: INFORMATION_SCHEMA


INFORMATION_SCHEMA.TABLES

This view contains the following information on each user-defined or publicly created table:

Column Heading | Definition
table_catalog | Database containing the table
table_schema | Schema (owner) of the table; the owner can be either the current schema (user) viewing the INFORMATION_SCHEMA or the PUBLIC schema
table_name | Name of the table
table_type Type of table — the possible values are:
  • T — User
  • V — View
Parent topic: INFORMATION_SCHEMA


INFORMATION_SCHEMA.VIEWS

This view contains the following information on each user-defined or publicly created view:

Column Heading | Definition
table_catalog | Database containing the view
table_schema | View owner; the owner can be either the current schema (user) viewing the INFORMATION_SCHEMA or the PUBLIC schema
table_name | Name of the view
view_definition | SQL that defines the view
Parent topic: INFORMATION_SCHEMA


DUAL

DUAL is a system table and has one column called DUMMY and one row containing the value X. The DUAL table is a convenience tool that enables users, or their programs, to select a single known constant or function.

For example, since DUAL contains only a single column, it makes the following types of commands more sensible:

SELECT USER()FROM DUAL;
SELECT NOW()FROM DUAL;
SELECT DATABASE()FROM DUAL;

...and for other functions where you want only a single value returned.

If you would like to provide a slightly different format of the data in the information_schema, you can modify the queries to return the name of the configuration file. In the file %GENESIS_HOME%\bin\cview.sql, modify the following lines:

change... | to...
t_database as table_catalog, | database() as table_catalog,
v_database as table_catalog, | database() as table_catalog,
c_database as table_catalog, | database() as table_catalog,

These changes will cause the configuration file of the current database to be printed on each line.

Parent topic: System Catalog Structure


Using the Command-line Query Tool

This help section describes how to use the SQL command-line query tool, xdbcquery, provided with AcuXDBC.

  • Introduction
  • Starting xdbcquery from the Command Line
  • Starting xdbcquery from asql
  • xdbcquery Commands
  • Running SQL Scripts
Parent topic: AcuXDBC Version 10.2.0 User's Guide


Introduction

AcuXDBC includes a command-line SQL query tool called xdbcquery. You use xdbcquery from an operating system command prompt to connect to your system catalog and execute SQL commands on your database directly, as opposed to connecting to the catalog from a third-party query tool such as Microsoft Query. The xdbcquery tool is also useful for conducting the following database tasks:

  • Creating users and granting permissions on objects
  • Creating VIEWs
  • Executing AcuXDBC queries and programs in non-interactive mode through an SQL script
  • Testing SQL scripts

To use the query tool, you first start the tool and then specify a command that connects you to your system catalog. You can perform these steps manually from the command prompt, or you can run a batch or shell script file that includes the xdbcquery start and connect command syntax and parameters.

Parent topic: Using the Command-line Query Tool


Starting xdbcquery from the Command Line

Execute the following xdbcquery connect command. (No spaces are allowed between parameters.)

xdbcquery /cacuxdbc04:[user name]/[password]/ xvision: [configuration file name]

where:

/c | Is the xdbcquery connect command
acuxdbc04 | Is the SQL driver with which to connect
user name ¹ | Is the user name
password ¹ | Is the user password
xvision | Is the driver providing access to the COBOL data files with which to connect
configuration file name | Is the file that specifies the data source and catalog location, which must be in %GENESIS_HOME% on Windows.
1

Example

xdbcquery /cacuxdbc04:system/manager/xvision:acuxdbc.cfg
Note: If you have not set up database security, you can omit the user name and password, but you need to keep the two forward slashes before xvision as place holders.

You are now connected to the system catalog and can execute xdbcquery-specific commands or execute SQL statements on your catalog tables. See Summary of Supported SQL Commands for the complete list of SQL commands and functions supported by AcuXDBC.

Parent topic: Using the Command-line Query Tool
1 ¹: Not required if no database security is in effect.


Starting xdbcquery from asql

For your convenience, a script file named asql.bat (asql.sh on UNIX/Linux) is included with AcuXDBC. You can use this file to start xdbcquery and connect to a database and system catalog, either locally or on a remote machine. The xdbcquery script has the following usage:

 asql [-c config] [-u user] [-p password] [-r script]
             [-s server] [-n port]

Option | Parameter | Default | Description
-c | configuration filename | acuxdbc.cfg | Specifies the configuration file that identifies the database and catalog location, which is %GENESIS_HOME% on Windows
-u | user name | system | Specifies the user name to connect to the database as
-p | password | manager | Specifies the password for the user
-r | script name | none | Runs the specified script
-s | server | none | Specifies a name or IP address
-n | port | 20222 | Specifies the port to connect to

Example

asql -u mary -p 123

Because no configuration file was specified in this example, this command connects the user Mary to the database and catalog specified in the acuxdbc.cfg configuration file.

Note: You can modify the default parameters directly within asql.bat or asq.sh to match your settings and then simply run the asql file from the same directory where xdbcquery is installed.
Parent topic: Using the Command-line Query Tool


xdbcquery Commands

Once xdbcquery is started, you can view a list of command options and other helpful information by executing the /? command. Doing so displays the following information:

Option | Parameter | Description
/c | connect_string | Connect to a database
/x | c r [u] | Commit or Rollback transaction and, if u is specified, start a read/write transaction
/d | s tstring | Describe an SQL statement or table
/r | file name | Run statements/commands from a file; files can be chained, but not nested
/o | cmd parameters | Execute driver command
/m | mask | Set datetime format mask
/n | null | Indicates what to display for a NULL value; default is blank
/l | N | N lines displayed for SELECT; "0" for continuous
/p [N T [data]]

Just /p to reset

Parameters:

  • "N" is parameter number (zero-based)
  • "T" is one of the following data types:
    • B - binary
    • C - character
    • D - date time
    • I - integer
    • N - number
/v | y n | Verbose messages - n for errors only
/b - Display database request block
/s | N | Sleep for N seconds
/? or /h - Help screen
/q - Quit session and exit
Parent topic: Using the Command-line Query Tool


Running SQL Scripts

Using a text editor, you can create SQL scripts and run them with asql by using the /r command followed by the filename. A sample script file appears below. Note that asql recognizes the hash sign (#) as the comment identifier.

#############################################################
#  x.sql
#############################################################
create table foo(col1 char(10), col2 char (10) );

#now create an index for the file
create unique index ifoo_0 on foo(col1);

#insert values
insert into foo values ('1','1');

#insert a null value for col2
insert into foo values ('2', '');

# set the null character
/n !null!

#select some records
select * from foo;

#now exit
/q

Run this script by issuing the following command:

asql -r x.sql

This will log into the default database with the default user and password information. It will then execute the script called x.sql.

If you wish, you can redirect the output to a file. For example

asql –r x.sql > output.txt

The file output.txt would then contain:

COL1       COL2
 ---------- ----------
 1          1
 2          !null!
Parent topic: Using the Command-line Query Tool


Supported SQL Commands

This help section describes the SQL commands that are supported by AcuXDBC.

  • Introduction
  • Conventions
  • Limitations and Restrictions
  • Summary of Supported SQL Commands
  • SQL Commands
  • AcuXDBC Functions
Parent topic: AcuXDBC Version 10.2.0 User's Guide


Introduction

This help section describes the SQL commands and functions that you can use to query and manage your database tables. See Supported SQL Commands for a concise list of the supported SQL commands. See SQL Commands for a detailed explanation of each supported command.

Note: This help section does teach SQL programming and is not meant serve as a comprehensive SQL guide. Consult your preferred SQL-specific programming guide for detailed information on SQL programming techniques.
Parent topic: Supported SQL Commands


Conventions

The following conventions describe the SQL syntax supported by AcuXDBC. There are no rules pertaining to the number of words you put on a line or where the line breaks. The number of words and line breaks used in this section are strictly for readability.

Convention | Description
CAPS | Capital letters indicate the word is a keyword (command)
MIXed | Capitals mixed with lower-case letters indicate that the word is a keyword, but you can type either the full word or just the letters in capitals
lower | Lowercase words are variables; you supply your own
{ } | Curly braces indicate you must choose at least one of the enclosed options
[ ] | Brackets indicate you can choose one or more of the enclosed options, or none of them
( ) | Parentheses are part of the command. Type them just as they appear
| | A vertical bar separates mutually exclusive options. You can choose only one
, | A comma separates multiple options. You can choose as many options as you like, but include commas in the command between choices
... | The ellipses (three dots) mean you can repeat the marked section or commands as many times as you like
Parent topic: Supported SQL Commands


Limitations and Restrictions

This help section describes SQL programming protocols related to object names, predicates, and constraints.

  • Object names
  • Predicates
  • Constraints
Parent topic: Supported SQL Commands


Object names

Names or identifiers of objects such as columns, tables, and indexes are limited to 30 characters. Identifiers must start with an alphabetic character and can include numbers as well as the "_" character. Avoid using any special characters such as "-" and "+". If you use special characters, you will have to put double quotation marks ("" "") around identifiers in your SQL statements.

Parent topic: Limitations and Restrictions


Predicates

Predicates are expressions that apply comparison operators (comp_op elements in the following syntax) and/or SQL predicate operators (such as IN and EXISTS) to values to produce a truth value of TRUE, FALSE, or UNKNOWN.

Predicates can be either a single expression or a combination of any number of expressions using Boolean operators (AND, OR, and NOT) as well as the special SQL operator IS, and parentheses to define the order of evaluation.

Predicates are most often used in the WHERE and HAVING clauses of SELECT statements and subqueries to determine the rows or aggregate groups to select, and in UPDATE and DELETE statements to identify the rows on which changes should be made.

Predicates evaluate to TRUE, FALSE, or UNKNOWN. UNKNOWNs arise when NULLs are compared to any value, including other NULLs, because it is impossible to know the value of a data field with NULL value. You can use Boolean operators and SQL IS on UNKNOWN truth values.

Parent topic: Limitations and Restrictions


Constraints

The ANSI standard defines a list of constraints that can be placed on a table or index. Constraints following the definition of a column apply to that column; those standing alone as table constraints can reference any one or more columns in the table.

At this time, AcuXDBC supports only the NOT NULL constraint. The complete list of possible constraints are:

Constraint | Description
NOT NULL | Forbids NULLs from being entered in a column. According to ANSI standard, this specification can be only a column constraint
UNIQUE | Mandates that every column value, or combination of column values if a table constraint, be unique
PRIMARY KEY | Same effect as UNIQUE, except that none of the columns in a PRIMARY KEY constraint can contain NULLs. You can issue this constraint only once in a given table
CHECK | Followed by a predicate (in parentheses) that uses column values in some expression whose value can be TRUE, FALSE, or in the presence of NULLs, UNKNOWN. The constraint is violated only when the predicate is FALSE

You can define constraints so that they are not checked until the end of the current transaction. This approach is useful when you want to update a table that references itself as a parent key. This operation usually creates intermediate states where referential integrity must be violated. By default, constraints are not deferrable.

Parent topic: Limitations and Restrictions


Summary of Supported SQL Commands

This help section provides a concise list of each supported command's syntax. For detailed descriptions of each command, including syntax, descriptions, use, and examples, follow the links for specific commands in SQL Commands.

If you are writing commands from an ODBC or JDBC application, that application must also support the same commands as AcuXDBC for the command to function properly.

CREATE (UNIQUE) INDEX index_name
   ON table_name
     (column_name (ASC | DESC) (,column_name (ASC | DESC)) ... )

CREATE SYNONYM synonym_name
  FOR object_name

CREATE TABLE table_name
   (column_name datatype (NOT NULL)
      (, column_name datatype (NOT NULL)) ...)

CREATE VIEW view_name
      ((column_name(, column_name) ...))
   AS subselect
   (WITH CHECK OPTION)

DELETE FROM {table_name | view_name} (correlation_name)
   (WHERE search_condition)

DROP INDEX index_name

DROP SYNONYM synonym_name

DROP TABLE table_name

DROP VIEW view_name

GRANT database_priv., ..  TO { grantee } IDENTIFIED by { password }
GRANT object_priv., ON object_name  TO { grantee., …} |  PUBLIC [WITH GRANT OPTION]

INSERT INTO table_name
   [ (column_list)]
   { VALUES (constant_list)

REVOKE { privilege., ..} FROM  { grantee }

    privilege ::=
       { CONNECT
       | DBA
       | RESOURCE }

SELECT [ALL | DISTINCT ] select_list
   FROM {table_name | view_name} (corr_name)
      (, {table_name | view_name} (corr_name)) ...
   (WHERE search_condition)
   (GROUP BY column_name (, column_name) ...)
   (HAVING search_condition)
   (ORDER BY {column_name | select_list_number } (ASC | DESC)) ... )

SET PASSWORD {old_password} {new_password}

UPDATE {table_name | view_name} (correlation_name)
   SET
   column_name = {expression | NULL}
      (column _name = {expression | NULL} ) ...
   (WHERE search_condition)
Parent topic: Supported SQL Commands


SQL Commands

The SQL commands below are ordered alphabetically.

CREATE INDEX | Creates an index on a base table
CREATE SYNONYM | Creates a PUBLIC synonym name for a database object
CREATE TABLE | Creates a new base table
CREATE VIEW | Defines a view
DELETE | Deletes rows from a table
DROP INDEX | Removes an index from a base table
DROP SYNONYM | Removes a PUBLIC synonym from the database
DROP TABLE | Removes a base table
GRANT (Database Privileges) | Gives users database access rights
GRANT (Object Privileges) | Gives users database object privileges
INSERT | Inserts rows into a table
REVOKE (Database Privileges) | Removes the privilege to perform an action on a database
REVOKE (Object Privileges) | Removes the privilege to perform an action on a database object
SELECT | Used to formulate queries
SET OPTION | Enables and disables numerous administrative options
SET PASSWORD | Allows users to set passwords
UPDATE | Changes the data in a table
  • CREATE INDEX command
  • CREATE SYNONYM command
  • CREATE TABLE command
  • CREATE VIEW command
  • DELETE command
  • DROP INDEX command
  • DROP SYNONYM command
  • DROP TABLE command
  • GRANT (Database Privileges) command
  • GRANT (Object Privileges) command
  • INSERT command
  • REVOKE (Database Privileges) command
  • REVOKE (Object Privileges) command
  • SELECT command
  • SET OPTION command
  • SET PASSWORD statement
  • UPDATE command
Parent topic: Supported SQL Commands


CREATE INDEX command

This command creates an index on a base table.

Syntax

CREATE [UNIQUE] INDEX index_name
  ON table_name
   (column_name [ASC | DESC] [,column_name [ASC | DESC]]...)

Keyword | Description
UNIQUE | Creates a unique index
index_name | Name of the index to create
table_name | Name of the table for the index
column_name | Column name to use in the index key. The index key is built using the columns in the order you specify in this list

Use

You can create indexes on initial tables that have yet to be used or referenced within a SELECT or INSERT statement. Once you use a table, you cannot go back to the table and create an index.

Example

CREATE UNIQUE INDEX STAFF_IX1 ON STAFF(ID)
CREATE INDEX STAFF_IX2 ON STAFF(DEPT,NAME)
Parent topic: SQL Commands
Related reference
INSERT command
SELECT command


CREATE SYNONYM command

This command creates a PUBLIC synonym name for a database object.

Syntax

CREATE SYNONYM synonym_name
  FOR object_name
Keyword | Description
SYNONYM | Creates a synonym name for a table name
synonym_name | Name of the synonym to create
object_name | Name of the table or view to which the synonym name applies

Use

You can create synonyms for an object in the database. Synonyms can currently be created for base tables or views. The synonym name can then be used in place of the object name in queries. Note that users of the synonym name must have appropriate privileges to the base object to which the synonym applies. Synonyms are useful in that a user can access data from tables existing in other user schemas (authorization IDs) without having to specify that user's schema.

The DROP synonym command is used to remove a synonym name.

Example

CREATE SYNONYM REPS FOR Mary.ALL_REPS_LOCATIONS
Parent topic: SQL Commands
Related reference
DROP SYNONYM command


CREATE TABLE command

This command creates a permanent table.

Syntax

CREATE TABLE table_name
   (column_name datatype (NOT NULL)
      (, column_name datatype (NOT NULL)) ...)
Keyword | Description
table_name | Name of the table to create
column_name | Column name to create in the table; columns are created in the order you specify in this list
datatype | Data type for the specified column; you must specify a valid data type for each named column to successfully create the table
Enter the actual information in this section (optional).

Use

AcuXDBC supports the creation of permanent base tables only. Tables contain one or more columns, which must be defined when you create the table. Thus, a table definition is a series of one or more comma-separated column definitions.

To define a column, you specify a column_name, a data type for the data in that column, and whether the data can be NULL or not.

The order of the columns in this statement determines their order in the table. A column definition must include the following:

  • The name of the column (the column must be named)
  • A data type that applies to all column values
  • NULL or NOT NULL Designation
  • Default Values and Collations
  • Ownership and Access Control
  • Example
Parent topic: SQL Commands
Related information
FILE_PREFIX configuration variable


NULL or NOT NULL Designation

Some data types accept size arguments indicating, for example, the length of a fixed-length character string or the scale and precision of a decimal number. The meaning and format of these vary with the data type, but defaults exist.

Parent topic: CREATE TABLE command


Default Values and Collations

If you specify a NOT NULL constraint for a column, one of the following must happen:

  • You must define a default value.
  • Every INSERT or UPDATE command on the column must leave it with a specified value.

The default can be specified as a literal, a user value function, a datetime value function, or NULL (if you don't specify a default, the column is assumed to be nullable).

Parent topic: CREATE TABLE command


Ownership and Access Control

Tables and other database objects are created and owned by authorization IDs, which means users in most contexts. An object's owner controls the privileges others have on it. In a sense, all privilege flows from the right to create objects. Tables are grouped into schemas and can be created by only the owner of the schema in which they reside or by a user with database administrator (DBA) privileges.

Parent topic: CREATE TABLE command


Example

CREATE TABLE STAFF(ID INTEGER NOT NULL,
             NAME VARCHAR(10) NOT NULL, DEPT INTEGER NOT NULL,
             JOB VARCHAR(6) NOT NULL, YEARS INTEGER,
             SALARY FLOAT(8,2) NOT NULL,COMM FLOAT(8,2))

AcuXDBC supports the creation of permanent base tables only. Tables contain one or more columns separated by commas, which must also be defined when you create the table. The query processor will store Data Definition Language (DDL) statements after a CREATE TABLE statement until the first non-DDL statement is encountered. It will then create the COBOL table.

Example:

SQL (/? for help) ==> CREATE TABLE staff (
SQL continued ======>     id INTEGER NOT NULL,
SQL continued ======>     name VARCHAR(10) NOT NULL,
SQL continued ======>     dept INTEGER NOT NULL,
SQL continued ======>     job VARCHAR(6) NOT NULL,
SQL continued ======>     years INTEGER
SQL continued ======> );
SQL (/? for help) ==> CREATE UNIQUE INDEX
SQL continued ======>     i_staff0
SQL continued ======> ON
SQL continued ======>     staff( id )
SQL continued ======> ;
SQL (/? for help) ==> INSERT INTO
SQL continued ======>     staff
SQL continued ======> VALUES (
SQL continued ======>   1, 'John Smith', 31, 'PGM', 1
SQL continued ======> );

After the insert, the table will be created in the first directory listed in your FILE_PREFIX configuration file variable. Here is the file description:

C:\>vutil32 -info -x SYSTEM%STAFF (vision version 5)

        # of records                     :   1
        # of deleted records             :   0(0+0)
        file size                        :   1024 (SYSTEM%STAFF)
        file size                        :   1024 (SYSTEM%STAFF.vix)
        total file size                  :   2048
        segment size                     :   2147482112
        record size                      :   34
        # of keys                        :   1
        key size                         :   6
        key offset			                       :   0
        duplicates okay                  :   N

        block size                       :   512
        blocks per granule               :   1
        tree height                      :   1/1/1.0
        # of nodes	                       :   1
        # of deleted nodes               :   0
        total node space                 :   509
        node space used                  :   24 (4.72%)
        user count                       :   0
Parent topic: CREATE TABLE command


CREATE VIEW command

The CREATE VIEW command defines a view.

Syntax

CREATE VIEW view_name (column_list)
     AS ( SELECT statement );
Keyword | Description
view_name | Name of view
column_list | List of columns to display in view
statement | Criteria by which you identify rows that you want to retrieve

Use

This statement creates a view. A view is an object that is treated as a table, but whose definition contains a query - a valid SELECT statement. Because the query may access more than one base table, a view may combine data from several tables. Views do not contain their own data. Because the rows of a view are, by definition, unordered, you cannot use ORDER BY when creating a view.

You reference a view in SQL statements just like base tables. When you reference the view in a statement, the output of the query becomes the content of the view for the duration of that statement. In cases in which views can be updated, the changes are transferred to the underlying data in the base tables.

The tables or views directly referenced in a query are called the simply underlying tables of the query or view. These, combined with all the tables they reference and all the subsequently referenced tables all the way down to and including the base tables that contain the data, are called the generally underlying tables. The base tables - the ones that don't reference any other tables, but actually contain the data - are called the leaf underlying tables. View definitions cannot be circular. That is, no view can be among its own generally underlying tables.

Views also cannot contain target specifications or a dynamic parameter specification. The list of columns is used to provide the columns with names that are used only in a given view. You can use it if you don't want to retain the names that the columns have in the underlying base tables. However, you must use it whenever:

  • Any of the two columns would otherwise have identical names
  • Any of the columns contain computed values or any values other than column values directly extracted from the underlying tables, unless an AS clause is used in the query to name them
  • There are any joined columns with distinct names in their respective tables, unless an AS clause is used in the query to name them

If you do name the columns, you cannot use the same column name twice in the same view. If you name the columns, you must name all of them, so the number of columns in the name list is the same as the SELECT clause of the contained query. You can use SELECT * in the query to select all columns; this command is converted internally to a list of all columns, so that if a column is added to an underlying table (using ALTER TABLE), your view remains valid.

Views can base their queries on other views, as long as the definition is not circular. Views cannot reference declared temporary tables, although global and created local ones are acceptable.

  • Inserting, Updating, and Deleting Values in Views
  • Example
Parent topic: SQL Commands
Related reference
SELECT command


Inserting, Updating, and Deleting Values in Views

When you perform any of the above operations on a view, the changes are transferred to the base table that contains the data. Such operations are permitted only if the changes that must be made to the underlying table are unambiguous. The principle is that an insertion or change to one row in the view must translate to an insertion or change to one row in the leaf underlying table. If this is the case, the view is said to be updatable. The specific conditions outlined in the standard for a view to be updatable are:

  • It must be drawn on only one simply underlying table; joins are not allowed
  • It must contain only one query
  • If the simply underlying table is itself a view, that view must also be updatable
  • The SELECT clause of the contained query may specify only column references, not value expressions or aggregate functions, and no column can be referenced more than once
  • The contained query cannot specify GROUP BY or HAVING
  • The contained query cannot specify DISTINCT
  • Subqueries are permissible, but only if they do not refer to any of the generally underlying tables on which the view is based
Parent topic: CREATE VIEW command


Example

CREATE VIEW STAFF_VIEW (Employee_id, Employee_name, Employee_dept)
            AS SELECT ID,NAME,DEPT FROM STAFF
Parent topic: CREATE VIEW command


DELETE command

This command deletes rows from a table

Syntax

DELETE FROM table_name (correlation_name)
       [ (WHERE search_condition) |
       { (WHERE CURRENT OF cursor_name) } ]
Keyword | Description
table_name | Name of table or view from which to delete data rows
correlation_name | Also called range variable or alias, provides an alternative name for the table whose name it follows; the definition lasts only for the duration of the statement. Correlation names are optional for base tables and views, but required for tables produced by subqueries
search_condition | Criteria by which you identify rows on which you want to act

Use

This statement can be coded directly or in dynamic SQL, coded as a prepared statement, which is a statement whose text is generated at runtime. The DELETE statement removes rows from permanent base tables, views, or cursors. In the last two cases, the deletions are transferred to the base table from which the view or cursor extracts its data.

The WHERE CURRENT OF form is used for deletions from cursors. The row currently in the cursor is removed. This is called a positioned deletion. The WHERE predicate form is used for deletions from base tables or views. All rows that satisfy the predicate are removed at once. This is called a searched deletion. If the WHERE clause is absent, it is also a searched deletion, but all rows of the table or view are removed. The following restrictions apply to both types:

  • You must have DELETE privileges on the table to delete it
  • If the deletion is performed on a view or cursor, that view or cursor must be updatable
  • The current transaction mode cannot be read-only
  • Searched Deletions
  • Positioned Deletions
  • Prepared DELETE Statements
  • Example
Parent topic: SQL Commands


Searched Deletions

The predicates used in DELETE statements, like those in SELECT and UPDATE, use one or more expressions (for example, location ='Bahrain'). This will test whether TRUE, FALSE, or if NULLs exist, UNKNOWN for each row based on the values within that row. Each row for which the predicate is TRUE is deleted.

Parent topic: DELETE command


Positioned Deletions

Positioned deletions use cursors and therefore apply to only static or dynamic SQL, but not to interactive SQL. You can use a positioned deletion if:

  • A cursor is within the current module or one of its compilation unit emulations that references the table
  • This cursor has been opened within the current transaction
  • This cursor has had at least one row fetched
  • The cursor has not yet been closed

The last row fetched is deleted.

Parent topic: DELETE command


Prepared DELETE Statements

The PREPARE statement lets you generate the text of dynamic SQL statements at runtime. When you use PREPARE to generate a positioned deletion, you can omit the FROM table_name clause of the DELETE statement. The table underlying the cursor is assumed.

Parent topic: DELETE command


Example

Downsize department 15:
  DELETE FROM STAFF WHERE DEPT = 15
Parent topic: DELETE command
Parent topic: GRANT (Object Privileges) command


DROP INDEX command

This command removes an index from a base table.

Syntax

DROP INDEX index_name;
Keyword | Description
index_name | Name of the index to remove

Use

This statement is used to remove an index and can be used currently only before the table is accessed the first time by a non-DDL statement (which causes the physical file to be created).

Example

DROP INDEX STAFF_IX1
Parent topic: SQL Commands


DROP SYNONYM command

This command removes a PUBLIC synonym from the database.

Syntax

DROP SYNONYM synonym_name
Keyword | Description
synonym_name | Name of the synonym to drop

Use

This statement is used to remove a synonym referencing a table or view from the database. The removal of a synonym has no effect on the base object to which it refers.

The CREATE SYNONYM statement is used to create a synonym name.

Example

DROP SYNONYM REPS
Parent topic: SQL Commands
Related reference
CREATE SYNONYM command


DROP TABLE command

This command removes a base table.

Syntax

DROP TABLE table_name;
Keyword | Description
table_name | Name of the table to remove

Use

This statement is used to remove the same kinds of tables that are created with a CREATE TABLE statement. To drop views, use the DROP VIEW statement. To drop a table, you must own the schema in which the table resides or have (database administrator) DBA privileges.

The definition of the table is eliminated and all users lose their privileges on that table.

Example

DROP TABLE STAFF
Parent topic: SQL Commands
Related reference
CREATE TABLE Command


GRANT (Database Privileges) command

This command gives users database access rights.

Syntax

GRANT privilege., ..TO { grantee } IDENTIFIED by { password }
privilege ::=
     { CONNECT
     | DBA
     | RESOURCE }
Keyword | Description
privilege Type of privilege to grant:
  • CONNECT - lets grantees connect to and read from the database
  • RESOURCE - lets grantees create objects in the database
  • DBA - implies both CONNECT and RESOURCE, and gives grantees total control over all tables in the database
grantee | User name to allow privilege
password | Password for user name

Use

Only database administrators (DBAs) can use the GRANT command. If you are a DBA, this command lets you give grantees the right to perform specified actions on the database. ( Grantee is the authorization ID that represents a user or group of users.)

You may use SET PASSWORD to change a password.

Example

GRANT CONNECT,RESOURCE TO CLERK IDENTIFIED BY MY42
Parent topic: SQL Commands
Related reference
REVOKE (Database Privileges) command
SET PASSWORD statement


GRANT (Object Privileges) command

This command gives users database object privileges.

Syntax

GRANT privilege., ..ON object_name
    TO { grantee., ...} | PUBLIC
    [ WITH GRANT OPTION ];
privilege ::=
     { ALL PRIVILEGES }
     | { SELECT
         | DELETE
         | { INSERT [ ( column name.,..) ] }
         | { UPDATE [ ( column name.,..) ] }

object name ::=
         [ TABLE ] table name
Keyword | Description
privilege Type of access, action, or privilege to grant:
  • ALL PRIVILEGES - Passes on all applicable privileges that you are entitled to grant. PUBLIC denotes all authorization IDs, present and future
  • SELECT, INSERT, UPDATE, and DELETE - Let grantees execute the statements of the same names on the object
object_name | Name of the object on which to grant privileges
grantee | User name(s) to allow privilege

Use

This statement gives grantees the right to perform specified actions on named objects. (Grantee is the authorization ID that represents a user or group of users.)
  • USAGE
  • Privileges Cascade
  • Example
Parent topic: SQL Commands
Related reference
FROM Clause (SELECT Statement)
CREATE VIEW command
DELETE command
INSERT command
SELECT command
UPDATE command
REVOKE (Object Privileges) command


USAGE

To grant an object privilege, you must have been given (granted) the privilege yourself. You can then grant that particular privilege to other users. Be aware that the users to whom you grant this privilege are in turn able to grant this same privilege to other users.

Parent topic: GRANT (Object Privileges) command


Privileges Cascade

Privileges can cascade up; that is, privileges granted on some object can imply grants of privileges on other objects. These situations are covered by the following principles:

  • If the grantee owns an updatable view and is being GRANTed privileges on its leaf underlying table (the base table wherein the data finally resides, regardless of any intervening tables or views), these privileges are GRANTed for the view as well. If specified, the grant option also cascades up. There is only one leaf underlying table for an updatable view
  • If the grantee owns an updatable view that immediately references the table on which privileges are being GRANTed (in other words, if the reference appears in the FROM clause without an intervening view), these privileges can also cascade up, including the grant option, if applicable
  • If the grantee owns a view, updatable or not, that grantee already has the SELECT privilege on all tables referenced in its definition, as well as on the view itself. If the grantee gains the grant option on SELECT on all the referenced tables, he or she also acquires the grant option on the SELECT privilege on the view

In all of these situations, the grantor of the privilege is ''_SYSTEM,'' which denotes an automatic grant.

For each privilege that is granted, a privilege descriptor is effectively created. (This is a theoretical construct used by the ISO standard to specify privilege behavior; it may not actually exist.) The privilege descriptor indicates:

  • The grantee that has received the privilege
  • The privilege itself (the action that can be performed)
  • The object on which the privilege is granted, which may be one of those listed above or a column
  • The grantor that conferred the privilege. For automatic grants, this is the built-in value ''_SYSTEM''
  • Whether the privilege is grantable (GRANTed with the grant option)

Multiple identical privilege descriptors are combined, so that a privilege granted twice by the same grantor need be revoked only once. Likewise, if two privilege descriptors differ only in that one confers grant option and the other does not, they are merged into a single privilege with grant option. If the grantor lacks the ability to grant the privileges attempted, a completion condition is raised - a warning that privileges were not granted.

Parent topic: GRANT (Object Privileges) command


INSERT command

This command inserts rows into a table.

Syntax

INSERT INTO table_name
   [ (column_list)]
   { VALUES (constant_list)
Keyword | Description
table_name | Name of the table into which values are inserted
column_list | Identifies the columns of the table into which the values are inserted. All columns not in the list receive their default values automatically. If any such column cannot receive defaults (for example, if they have the NOT NULL constraint, but have no other default value specified) the INSERT fails. If you omit the list, all columns of the table are the target of the insert. The number and order in which you list the columns must match the number and order of the output columns of the corresponding query
constant_list | A simple list of values to insert

Use

This statement enters one or more rows into table_name. The rows are the output rows of the subquery. These rows must have the same data types as the columns being inserted into.

You must have INSERT privileges on all named columns to issue an INSERT statement. If the table is a view, this view must be updatable, in which case the new rows are inserted into the base table that contains the data from which the view is derived (the leaf underlying table).

The values to be inserted may be directly specified with a table value constructor (whose elements may include variables or parameters passed from applications) or derived from a query from information already present in the database.

Example

INSERT INTO STAFF VALUES
(10,'Sanders',15,'Clerk',7,12345.67,543.54)
Parent topic: SQL Commands


REVOKE (Database Privileges) command

This command removes the privilege to perform an action on a database.

Syntax

REVOKE { privilege., ..} FROM  { grantee }
privilege ::=
     { CONNECT
     | DBA
     | RESOURCE }
Keyword | Description
privilege | Type of access, action, or privilege to remove
grantee | User name(s) to allow privilege

Use

This statement removes privileges from authorization IDs that have previously received them with the GRANT statement. Only a database administrator (DBA) can execute this statement.
  • Removing CONNECT privileges means that the grantee can no longer access the database. It has no effect on the objects owned by that grantee.
  • Removing RESOURCE privileges means that the grantee can no longer create new objects.
Note: Be very careful when removing DBA privileges: If there are no other DBAs, the GRANT and REVOKE statements can no longer be used.

Example

REVOKE CONNECT FROM CLERK
Parent topic: SQL Commands
Related reference
GRANT (Database Privileges) command


REVOKE (Object Privileges) command

Enter the syntax information of your reference here (optional).

Syntax

REVOKE [ GRANT OPTION FOR ]
    { ALL PRIVILEGES } | { privilege., ..}
    ON object_name
    FROM PUBLIC | { grantee .,.. };
Keyword | Description
privilege | Type of access, action, or privilege to revoke
object_name | Name of the object on which to revoke privileges
grantee | User name(s) to revoke

Use

This statement removes privileges from authorization IDs (users) that have previously received them with the GRANT statement. The privileges follow the definitions and rules outlined under GRANT. The GRANT option is the ability to grant the privileges received in turn to others.

In any case, the revoker of the privilege is the same authorization ID that granted it, and all dependent privileges may be revoked. A privilege (privilege A) depends directly on another (privilege B) if either of the following sets of conditions is met:

All of the following must be true to satisfy this condition set:

  • Privilege A is grantable (has GRANT option)
  • The grantee of A is PUBLIC or the same as the grantee of B
  • A and B are both privileges for the same action on the same object

OR

All of the first three below must be true to satisfy this condition set:

  • B is an automatically generated privilege, indicated by a grantor value of _SYSTEM
  • The actions of the two privileges are the same
  • The grantee of A owns the object (which must be a table, translation, or collation) on which the privileges exist

plus any one of the following:

  • Privilege B is on a view referencing a table on which privilege A is the SELECT privilege (if it is a read-only view) or the privilege at hand (if it is an updatable one)
  • B is the USAGE privilege on a collation defined on a character set on which A is the USAGE privilege
  • B is the USAGE privilege on a translation that uses the character set on which A is the USAGE privilege as either source or target

Example

REVOKE SELECT ON STAFF FROM CLERK
Parent topic: SQL Commands
Related reference
GRANT (Object Privileges) command


SELECT command

Syntax

SELECT [ALL | DISTINCT ] select_list
   FROM [table_name | subquery] (corr_name)
      (, [table_name | subquery] (corr_name)) ...
   (WHERE search_condition)
   (GROUP BY column_name (, column_name) ...)
   (HAVING search_condition)
   (ORDER BY {column_name | select_list_number } (ASC | DESC)) ...
Keyword | Description
select_list | List of columns to retrieve
table_name | Name of table or tables in which the columns reside
correlation_name | Also called range variable or alias, provides an alternative name for the table whose name it follows; the definition lasts only for the duration of the statement. Correlation names are optional for base tables and views, but required for tables produced by subqueries
search_condition | Criteria by which you identify rows on which you want to act
column_name | Name of the column to evaluate with the search_condition
select_list_number | Position in the select list of the column to evaluate with the search_condition

Use

This is the statement used to formulate queries, which are requests for information from the database. To issue this statement, you must have the SELECT privilege on all tables accessed. Queries may be stand-alone or used in the definitions of views and cursors. In addition, you can use them as subqueries to produce values that are used within other statements, including the SELECT statement itself. Sometimes a subquery is evaluated separately for each row processed by the outer query. Values from that outer row are used in the subquery. Queries of this type are called "correlated subqueries."

The output of a query is itself a table, and the SELECT clause defines the columns of that table (the output columns).

Clauses of the SELECT statement are evaluated in the following order:

  1. FROM
  2. WHERE
  3. GROUP BY
  4. HAVING
  5. SELECT
  6. ORDER BY*
Note: The order of records returned by AcuXDBC is always undefined unless you specify an ORDER BY clause. If a specific returning order is required, you must use the ORDER BY clause.
  • FROM Clause (SELECT Statement)
  • WHERE Clause (SELECT statement)
  • GROUP BY Clause (SELECT Statement)
  • HAVING Clause (SELECT Statement)
  • SELECT List (SELECT Statement)
  • ORDER BY Clause (SELECT Statement)
  • Possibly Nondeterministic Queries
Parent topic: SQL Commands


FROM Clause (SELECT Statement)

The FROM clause names the source tables for the query. These tables may be:

  • Tables or views named and accessed directly
  • Derived with a subquery that is part of the main query
  • Explicit joins

The FROM clause determines the tables from which the data is taken or derived. These sources can include temporary or permanent base tables, views, results of subqueries, and other operations that return tables.

You can use correlation names to qualify ambiguous column references in the rest of the statement. You can choose to join a table to itself, which is treated as a join of two identical tables. In this case, you must use correlation names to distinguish between the two tables. The correlation names prefix the "column_name" and are separated by a period. The column name list is for renaming columns, just as they are in the SELECT clause.

The names used here, however, are not for the output; they are for references to the columns made in the remainder of the statement, particularly in the WHERE clause. They are optional, but may be required to clarify column references in some cases.

  • Joins
  • Outer Joins
Parent topic: SELECT command
Related information
WHERE Clause SELECT statement


Joins

If more than one table is named in the FROM clause, they are all implicitly joined. This means that every possible combination of rows (one from each table) is derived. In addition, this concatenation is the table on which the rest of the query operates. The concatenated table is called a Cartesian product or cross join. Typically, you want to eliminate most of the rows and focus on the data you want. To do this, use the WHERE clause.

The standard join is also referred to as an inner join and is simply the regular SQL WHERE clause, for example:
WHERE [table1.]column1 = [constant | [table2.]column2]
Parent topic: FROM Clause (SELECT Statement)


Outer Joins

AcuXDBC supports OUTER joins, including LEFT, RIGHT, and FULL. The outer joins follow the FROM clause and are of the form:

<LEFT | RIGHT | FULL> OUTER JOIN <tablename> ON <column1> = <column2>

where <column1> is a column in <tablename> and <column2> is a column in another FROM clause table.

Parent topic: FROM Clause (SELECT Statement)


WHERE Clause (SELECT statement)

The WHERE clause defines the criteria that rows must meet to be selected for output.

The WHERE clause contains a predicate, which is a set of one or more expressions that can be TRUE, FALSE, or UNKNOWN. Values are compared according to:

Predicate Type | Description
NULLS | Compared to any value, including other NULLs, produce UNKNOWNs
Character string types | Collating sequence
Numeric types | Numerical order
Date-time types | Chronological order
Interval types | Magnitude

These comparisons are expressed using the following operators: =, <, <=, >, =>, and < > (does not equal).

Operators such as "*" (multiplication) or "||" (concatenation) may be applied depending on the data type. In most situations, row value constructors may be used instead of simple value expressions.

In addition to the standard comparison operators, SQL provides the following special predicate operators. Assume that B and C are all value expressions, which can be column names or direct expressions (possibly using column names or aggregate functions) in the appropriate data type:

Predicate Operator | Description
B BETWEEN A AND C | Equal to (A <= B) AND (B <= C) A and C must be specified in ascending order B BETWEEN C AND A is interpreted as C <= B) AND (B <= A), which is FALSE if the first expression is TRUE, unless all three values are the same If any of the values is NULL, the predicate is UNKNOWN
A IN C, D, ., ...) | This is true if A equals any value in the list
A LIKE 'string' | This assumes that A is a character string and searches for the specified substring. Fixed and varying-length wild cards can be used
A IS NULL | Specifically tests for NULLs. It can be TRUE or FALSE only, not UNKNOWN
A comp op SOME | ANY subquery | SOME and ANY have equivalent meanings. The subquery produces a set of values. If, for any value V so produced, A comp op V is TRUE, the ANY predicate is TRUE
A comp op ALL subquery | Similar to ANY except that all the values produced by the subquery have to make A comp op V true
EXISTS subquery | Evaluates to TRUE if the subquery produces any rows; otherwise, evaluates to FALSE. It is never UNKNOWN. To be meaningful, this phrase must use a correlated subquery
UNIQUE subquery | If the subquery produces no identical rows, UNIQUE is TRUE; otherwise, it is false. For the purposes of this predicate, identical rows are devoid of NULLs; otherwise, they are not identical
row value constructor MATCH arguments subquery | Tests for the presence of the constructed row among those of the table produced by the subquery. The arguments allow you to specify FULL or PARTIAL matches and whether the matched row must be unique
row value constructor OVERLAPS row value constructor | Allows you to determine when two date or time periods overlap. You must use it with DATETIME data types, possibly in conjunction with INTERVAL data types

These predicates are combined using the conventional Boolean operators AND, OR, and NOT. For TRUE and FALSE values, these have the conventional results. The rows selected by the WHERE clause go on to be processed by subsequent clauses.

Parent topic: SELECT command


GROUP BY Clause (SELECT Statement)

The GROUP BY clause groups identical output values in the named columns. Every value expression in the output column that includes a table column must be named in it unless it is an argument to aggregate functions. GROUP BY is used to apply aggregate functions to groups of rows defined by having identical values in specified columns.

If you don't use GROUP BY, either all or none of the output columns in the SELECT clause must use aggregate functions. If all of them use aggregate functions, all rows satisfying the WHERE clause or all rows produced by the FROM clause (if there is no WHERE clause) are treated as a single group for deriving the aggregates.

The GROUP BY clause defines groups of output rows to which aggregate functions (COUNT, MIN, AVG, and so on) can be applied. If you do not use this clause and elect to use aggregate functions, the column names in the SELECT clause must all be contained in aggregate functions, and the functions are applied to all rows to satisfy the query.

Otherwise, each column referenced in the SELECT list outside an aggregate function must be a grouping column and be referenced in this clause. All rows output from the query that have all grouping column values equal, constitute a group. (For the purposes of GROUP BY, all NULLs are considered equal). The aggregate function is applied to each such group.

Parent topic: SELECT command
Related information
WHERE Clause (SELECT statement)


HAVING Clause (SELECT Statement)

The HAVING clause defines criteria that the groups of rows defined in the GROUP BY clause must satisfy to be output by the query.

Just as the WHERE clause defines a predicate to filter rows, HAVING is applied after grouping to define a similar predicate to filter the groups based on the aggregate values. It is needed to test for aggregate function values, as these are not derived from single rows of the Cartesian product defined by the FROM clause, but from groups of such rows, and therefore cannot be tested in a WHERE clause.

Parent topic: SELECT command


SELECT List (SELECT Statement)

The SELECT list appears as the first clause in a SELECT statement, but it is not the first logical step. The other clauses produce a set of rows, the "source rows," from which the output is derived.

The SELECT list determines which columns from these rows are output. It may directly output these columns, or it may use them in aggregate functions or value expressions. Value expressions can be NUMERIC, STRING, DATETIME, or INTERVAL. They may include aggregate functions and subqueries.

If DISTINCT is specified, the rows are compared and if any duplicate rows are found, only one copy appears in the output. The SELECT clause may contain any of the following:

Aggregate functions | Functions that extract single values from groups of column values, for example, SUM or COUNT
An asterisk (*) | Causes all the columns of all tables listed in the FROM clause to be output in the order in which they appear in the FROM clause
A qualifier | Where the "qualifier" is the table or correlation name referenced in the FROM clause. All columns of that (possibly derived) table are output, excluding common columns of joined tables
A value expression Normally is (or includes) a column name from one of the tables identified in the FROM clause. Either the column's value is directly output or it becomes part of some expression, such as
AMOUNT * 3
A specified column name | If the output columns are directly taken from only one column referenced in the FROM clause, it inherits the name of that column by default. You can override this name by using the AS clause. The names of columns not directly taken from input columns are implementation-dependent. You are not required to name any output columns by the SELECT clause, but may be required to by the context of the way the output columns are to be used (for example, in a view). The keyword AS is not required because it is implied

If aggregate functions and value expressions are mixed, all the value expressions must be specified in a GROUP BY clause.

Parent topic: SELECT command


ORDER BY Clause (SELECT Statement)

ORDER BY forces the output of queries to emerge in a particular sequence.

The ORDER BY clause sorts the output. The rows are sorted according to the values in the columns listed:

  • The first column listed gets the highest priority
  • The second column determines the order within duplicate values of the first
  • The third column determines the order within duplicate values of the second, and so on

You can specify ASC (for ascending, the default) or DESC (descending) independently for each column.

Character sets are sorted according to their collations. You can also use integers rather than names to indicate columns. The integers refer to the placement of the column among those in the output, so that the first column is indicated with a "1", the fifth with a "5", and so on. If any output columns are unnamed, you must use a number.

Note: The order of records returned by AcuXDBC is always undefined unless you specify an ORDER BY clause. If a specific returning order is required, you must use the ORDER BY clause.
Parent topic: SELECT command


Possibly Nondeterministic Queries

In some cases the same query can produce different output tables on different implementations because of subtle implementation-dependent behaviors. Such queries are called possibly nondeterministic queries. A query is possibly nondeterministic if any of the following is true:

  • It specifies DISTINCT and the data type of at least one column of the source row is a character string
  • One column of the source rows is a character string data type and is used in either the MIN or the MAX aggregate function
  • A character set column is used as a grouping column or in a UNION
  • A HAVING clause uses a character string column within a MIN or MAX function
  • It uses UNION without specifying ALL

Possibly nondeterministic queries cannot be used in constraints.

Parent topic: SELECT command
Related information
HAVING Clause (SELECT Statement)


SET OPTION command

This command enables and disables several administrative options.

Syntax

SET OPTION OptionType  param1 [param2]
OptionType | param1 | param2 | Description
COMPSORT | ON | OFF | - | Sets sort page compression (default is ON)
DATETIME | [n] 'string' | - | Allows the user to modify the DATETIME formatting string. The default is DD-MON-RR and the maximum size for the string is 64 bytes. The user can define up to three DATETIME formatting strings. These are identified by the optional n parameter
ERROR | ON | OFF | - | Sets internal error dumping
EXPR | ON | OFF | - | Sets internal expression dumping
HASH | ON | OFF | - | Sets internal hash dumping
HEAPBLOCKSIZE | bytes | - | Allows the user to set the heap block size used in allocating memory. Larger sizes require less CPU overhead but may result in excessive memory use The range is 0 to 1000000. Setting 0 means that the exact required size will be used
LOGFILE | 'filename' | - | Sets the name of the debugging logfile
MERGESIZE | records | - | Sets the number of records used to check for duplicates while processing an IN or UNION clause. The default is 1000. Increase this value if you get a "Multi RID overflow" error
OJNESTON | ON | OFF | - | Allows nested ON clauses (default is "OFF")
OPTIMIZE | ON | OFF | - | Allows the user to control whether or not optimization is used to evaluate statements. (Default is "ON")
PLAN | ON | OFF | - | Sets query plan dumping
SORTPAGES | totalpages | mempages | Allows the user to modify the amount of disk and memory storage used for sort operations. The totalpages parameter is the total number of 4096 byte pages to use, and mempages is the number of these pages kept in memory. totalpages must be greater than or equal to mempages. The default values are 10000 and 1000. The default values are fine for most users. If you get a message indicating that Virtual Memory has been exceeded, increase the totalpages value
TRACE | ON | OFF | - | Sets internal trace dumping
TREE | ON | OFF | - | Sets internal tree dumping

Use

This statement is used to set a number of database administrative options, as described in the table above.

In addition to adding SET OPTION commands to applications, you can use the GENESIS_INITSQL environment variable to point to a file containing these commands. Each command in the file can be up to 511 characters. All SQL commands except SELECT are valid.

Example

SET OPTION SORT 8000 2000
SET OPTION DATETIME DD-MM-YYYY
SET OPTION LOGFILE mylogfile
SET OPTION ERROR ON
Parent topic: SQL Commands
Related reference
SET PASSWORD statement


SET PASSWORD statement

This statement is used to change the user's password.

Syntax

SET PASSWORD old_password new_password
Keyword | Description
old_password | Old password
new_password | New password

Use

This statement is used to change the user's password.

Example

SET PASSWORD mypass newpass
SET PASSWORD mypass ''42pass''
Parent topic: SQL Commands
Related reference
SET OPTION command


UPDATE command

This command changes the data in a table.

Syntax

{UPDATE table_name (correlation_name)
   SET column_name = {expression | NULL}
      (column_name = {expression | NULL} ) ...
   (WHERE search_condition)
Keyword | Description
table_name | The name of an existing table that you can access. May include the owner's name if it is not you, for example, "owner.table"
correlation_name | Also called an alias. Used to relabel the name of the reference in other clauses in the statement
column_name | A column within the table. Parentheses are required only if the column list contains more than one column
expression | The operation or function to execute on the specified column_name
search_condition | A valid condition that evaluates to TRUE, FALSE, or UNKNOWN

Use

This statement changes one or more column values in an existing row of a table. The table may be a base table or view. You can set any number of columns to values and follow the whole column_name = value_expression clause with a comma if there is another such to follow. As an alternative to an explicit value, you can set the column to NULL or to the DEFAULT defined for the column.

You can use value_expression to refer to the current values in the table being updated. Any such references refer to the values of all of the columns before any of them were updated. This allows you to do such things as double all column values (if numeric) by specifying:

column_name = column_name * 2

You can also swap values between columns. Value expressions can also use subqueries.

The UPDATE is applied to all rows that fulfill the WHERE clause, which is one of two types. The WHERE predicate form is like the WHERE predicate clause in the SELECT statement: it uses an expression that can be TRUE, FALSE or UNKNOWN for each row of the table to be updated, and the UPDATE is performed wherever it is TRUE.

Be careful of omitting the WHERE clause; if you do, the UPDATE is performed on every row in the table. You can use the WHERE CURRENT OF form in static or dynamic SQL if the cursor direction is updatable (in other words, not through views) and provided the target table is open and positioned on a row. The UPDATE is then applied to the row on which it is positioned. When using WHERE CURRENT OF in dynamic SQL, you can omit the table name from the UPDATE clause, because the table in the cursor is implied.

In either case, for the UPDATE to be successful, the following conditions must be met:

  • The statement issuer must have the UPDATE privilege on each column of the table being set
  • If the target table is a view, it must be updatable
  • If the current transaction is read-only, the target table must be temporary
  • If the UPDATE is performed through a cursor that specifies ORDER BY, it may not set the values of any columns specified in the ORDER BY clause
  • If the target table is a view, the "value_expression" in the SET clause must not directly, or through views, reference its leaf-underlying table (the base table where the data ultimately resides)
  • The "value_expression" may not use aggregate functions except in subqueries
  • Each column of the target table can be altered only once by the same UPDATE statement
  • If the UPDATE is on a cursor that specified FOR UPDATE, each column being set must have been specified or implied by that FOR UPDATE
  • If the UPDATE is made through a view, it may be constrained by a WITH CHECK OPTION clause

Example

The following statement updates every salary in department 15:
UPDATE STAFF SET SALARY = SALARY * 1.10 WHERE DEPT = 15
Parent topic: SQL Commands
Related reference
WHERE Clause SELECT statement


AcuXDBC Functions

AcuXDBC has a number of built-in functions that help you create your SQL statements. You can use them in the SELECT-list to modify the result set or in the WHERE clause to limit the number of qualifying rows. They are also valid in INSERT, UPDATE, and DELETE statements.

  • ABS
    Returns the absolute value of expr.
  • ASCII
    Returns the integer value of char.
  • BITAND
    Returns the bitand of expr1 and expr2.
  • BITOR
    Returns the bitor of expr1 and expr2.
  • BITXOR
    Returns the bitxor of expr1 and expr2.
  • CASE
  • CAST
    Returns the value of expr or NULL as a data type.
  • CHAR_LENGTH
  • CHR
  • CONCAT
  • CONVERT
  • CURDATE
  • CURTIME
  • DATABASE
  • DAYNAME
    Returns the name of the day of the week for the date specified by expr.
  • DECODE
  • GREATEST
    Returns the highest value of the expressions.
  • HOUR
  • IFNULL
  • INSTR
  • LCASE
  • LEAST
    Returns the lowest value of the expressions.
  • LEFT
  • LENGTH
  • LOCATE
  • LTRIM
  • NOW
  • NVL
  • POSITION
  • REPLACE
    Returns a string where the instances of from in char are replaced with to.
  • REVERSE
    Returns a string where the characters in char are in reverse order.
  • RIGHT
  • ROUND
  • RTRIM
  • SQRT
  • SUBSTR
  • SUBSTRING
  • SYSDATE
  • TO_CHAR
  • TO_DATE
  • TO_NUMBER
  • TRANSLATE
  • TRUNC
  • UCASE
  • USER
Parent topic: Supported SQL Commands
Related information
INSERT command
UPDATE command
DELETE Command


ABS

ABS(expr)
Returns the absolute value of expr.
Parent topic: AcuXDBC Functions


ASCII

ASCII(char)
Returns the integer value of char.
Parent topic: AcuXDBC Functions


BITAND

BITAND(expr1,expr2))
Returns the bitand of expr1 and expr2.
Parent topic: AcuXDBC Functions


BITOR

BITOR (expr1,expr2))
Returns the bitor of expr1 and expr2.
Parent topic: AcuXDBC Functions


BITXOR

BITXOR (expr1,expr2))
Returns the bitxor of expr1 and expr2.
Parent topic: AcuXDBC Functions


CASE

CASE
  WHEN search-condition1 THEN result1
  ...
  WHEN search-conditionn THEN resultn
  ELSE resultx
END

All the result1 values must have comparable data types. The ELSE resultx is optional and is set to ELSE NULL if not specified. The search-conditions are in the form of operand operator operand. For example:

CASE
  WHEN dept = 'HQ' THEN 'Headquarters'
  WHEN dept = 'FC' THEN 'Factory'
  ELSE 'Somewhere else'
END

A shorthand syntax is also permitted:

CASE valuet
  WHEN value1 THEN result1
  ...
  WHEN valuen THEN resultn
  ELSE resultx
END
Parent topic: AcuXDBC Functions


CAST

CAST({ expr | NULL } AS { datatype })
CAST returns the value of expr or NULL as a data type. Valid data types are the same as for the CONVERT() function as well as any valid data types used in a CREATE TABLE statement. Note that no trunctation occurs if you use the CREATE TABLE data types; any precision such as varchar(n) is ignored.
Parent topic: AcuXDBC Functions


CHAR_LENGTH

CHAR_LENGTH(expr)
Returns the length of the character expression.
Parent topic: AcuXDBC Functions


CHR

CHR(a)
Returns the character value of a.
Parent topic: AcuXDBC Functions


CONCAT

CONCAT(char1,char2)
Returns the concatenation of char1 and char2.
Parent topic: AcuXDBC Functions


CONVERT

CONVERT(expr1,DataType)
Returns the value of expr1 converted into DataType , which is one of the following:
  • SQL_BIGINT
  • SQL_BINARY
  • SQL_BIT
  • SQL_CHAR
  • SQL_DATE
  • SQL_DECIMAL
  • SQL_DOUBLE
  • SQL_FLOAT
  • SQL_INTEGER
  • SQL_LONGVARBINARY
  • SQL_LONGVARCHAR
  • SQL_REAL
  • SQL_SMALLINT
  • SQL_TIME
  • SQL_TIMESTAMP
  • SQL_TINYINT
  • SQL_VARBINARY
  • SQL_VARCHAR
Parent topic: AcuXDBC Functions


CURDATE

CURDATE()
Returns the current date.
Parent topic: AcuXDBC Functions


CURTIME

CURTIME()
Returns the current time.
Parent topic: AcuXDBC Functions


DATABASE

DAYNAME(expr)
Returns the name of the day of the week for the date specified by expr.
Parent topic: AcuXDBC Functions


DAYNAME

DAYNAME(expr)

Returns the name of the day of the week for the date specified by expr.

Parent topic: AcuXDBC Functions


DECODE

DECODE(expr,value,result [,value,result]..., default )
Compares expr with each value and returns either the first matching value's result or the default value if no values match.
Parent topic: AcuXDBC Functions


GREATEST

GREATEST(expr1,expr2[,...])
GREATEST returns the greatest value of the expressions. The returned data type is based on the data type of the first expression.
Parent topic: AcuXDBC Functions


HOUR

HOUR(expr)
Returns the hour for the date and time specified by expr.
Parent topic: AcuXDBC Functions


IFNULL

IFNULL(expr1,expr2)
Returns a result or default based on a test for NULL. (See also the NVL function.)
Parent topic: AcuXDBC Functions


INSTR

INSTR(string,substring[,position[,occurrence]])

Returns the position of substring within string.

  • If position is specified and positive, the search begins position characters into string
  • If position is negative, the search begins position characters from the end of string
  • If occurrence is specified, the occurrenceth occurrence of substring in string is located

If substring does not exist within string, 0 is returned.

See also the LOCATE function.

Parent topic: AcuXDBC Functions


LCASE

LCASE(expr)
Returns the lowercase representation of expr.
Parent topic: AcuXDBC Functions


LEAST

LEAST(expr1,expr2[,...])
LEAST returns the lowest value of the expressions. The returned data type is based on the data type of the first expression.
Parent topic: AcuXDBC Functions


LEFT

{fn LEFT(expr,n)}

Returns the first n characters of expr.

The LEFT and RIGHT built-in functions are also SQL keywords. You must enclose them in {fn <LEFT | RIGHT>(parameters)}.

Parent topic: AcuXDBC Functions


LENGTH

LENGTH(expr)

Returns the length of the character representation of expr.

Parent topic: AcuXDBC Functions


LOCATE

LOCATE(string,substring[,position[,occurrence]])

Returns the position of substring within string.

  • If position is specified and positive, the search begins position characters into string.
  • If position position is negative, the search begins position characters from the end of string.
  • If occurrence is specified, the occurrenceth occurrence of substring in string is located.

If substring does not exist within string, 0 is returned.

See also the INSTR function.

Parent topic: AcuXDBC Functions


LTRIM

LTRIM(expr)
Returns the character representation of expr trimmed of leading blanks.
Parent topic: AcuXDBC Functions


NOW

NOW()
Returns the current date and time.
Parent topic: AcuXDBC Functions


NVL

NVL(expr1,expr2)
Returns expr2 if expr1 is NULL; otherwise, it returns expr1.

See also the IFNULL function.

Parent topic: AcuXDBC Functions


POSITION

POSITION(char1 IN char2)
Returns the position of char1 within char2 . If char1 does not exist within char2 , 0 is returned.
Parent topic: AcuXDBC Functions


REPLACE

REPLACE(char,from,to)
Returns a string where the instances of from in char are replaced with to.
Parent topic: AcuXDBC Functions


REVERSE

REVERSE (char))
Returns a string where the characters in char are in reverse order.
Parent topic: AcuXDBC Functions


RIGHT

{fn RIGHT(expr,n)}
Returns the last n characters of expr. The LEFT and RIGHT built-in functions are also SQL keywords. You must enclose them in {fn <LEFT | RIGHT>(parameters)}.
Parent topic: AcuXDBC Functions


ROUND

ROUND(n[,m])
Returns the rounded value of n based on the value of m. If n is a numeric value, it can be either positive or negative.
  • A positive value m specifies the digits to the right of the decimal point.
  • A negative value m specifies the digits to the left of the decimal point.
  • If m is 0 or not specified, the value is rounded at the decimal point.
  • If n is a date value, m can be one of the following:
    SCC,CC | Century
    SYYY, YYYY, YEAR, SYEAR, YYY, YY, Y | Year
    Q | Quarter
    MONTH, MON, MM | Month
    WW,W | Start of Week
    DDD,DD,J (default) | Day
    DAY, DY, D | Nearest Sunday
    HH, HH12, HH24 | Hour
    MI | Minute
Parent topic: AcuXDBC Functions


RTRIM

RTRIM(expr)
Returns the character representation of expr trimmed of trailing blanks.
Parent topic: AcuXDBC Functions


SQRT

SQRT(n)
Returns the square root of n.
Parent topic: AcuXDBC Functions


SUBSTR

SUBSTR(string,m[,n])

Returns a substring of a string, beginning at position m for n characters.

  • If you specify m=0, the whole string is returned.
  • If you specify a negative number, the function returns the number of characters specified from the end of the string.
  • If you don't specify n, the default is to return all characters starting from m.
Parent topic: AcuXDBC Functions


SUBSTRING

SUBSTRING(string,m[,n])
See SUBSTR() above.
Parent topic: AcuXDBC Functions


SYSDATE

SYSDATE
Returns the current system date and time.
Parent topic: AcuXDBC Functions


TO_CHAR

TO_CHAR(expr[,fmt])

Returns the character representation of expr based on the fmt string or the default for expr's data type. If expr is already a character string, expr is not converted.

If expr is a numeric value, fmt can be:

% | Percent sign at right of number
$ | Dollar sign at left of number
B | Display zero as blank
0 | Display leading zeros
9 | A digit position
other | Delimiting character (not leading)

The default mask is as many nines (9s) as required for the number's precision and scale.

If expr is a date value, fmt can be:

YYYY | Four-digit year
YY | Two-digit year
RR | Two-digit year in another century
MM | Two-digit month of year (01 to 12)
MON | Three-character month (all uppercase)
mon | Three-character month (all lowercase)
Mon | Three-character month (initial cap)
MONTH | Fully named month (all uppercase)
month | Fully named month (all lowercase)
Month | Fully named month (initial cap)
DDD | Three-digit day of year (001 to 356)
DD | Two-digit day of month (01 to 31)
D | Single-digit day of week (1 to 7)
DY | Three-character day (all upper case)
dy | Three-character day (all lowercase)
Dy | Three-character day (initial cap)
DAY | Fully named day (all uppercase)
day | Fully named day (all lowercase)
Day | Fully named day (initial cap)
HH12 | Two-digit hour (00 to 11)
HH,HH24 | Two-digit hour (00 to 23)
MI | Two-digit minutes (00 to 59)
SS | Two-digit seconds (00 to 59)
SSSSS | Seconds past midnight (0000 to 86399)
J | Julian day
Q | Single-digit quarter of year (0 to 4)
W | Single-digit week of month (1 to 4); the week begins on Sunday
WW | Two-digit week of year (01 to 52)
other | Delimiting character

To add character extensions to the values that represent counting, such as "ST", "ND", "RD", or "TH", simply add "th" to any uppercase digit mask. The function correctly interprets the extension based on the last digit and the case based on the mask's case.

Put embedding characters that are valid masks inside double quotes (" ").

The default mask is DD-MON-YY.

Parent topic: AcuXDBC Functions


TO_DATE

TO_DATE(expr[,fmt])
Returns the datetime representation of expr based on the fmt string or the default for expr's data type. If expr is already a datetime, the value is not converted.

The expr can be an integer or numeric value.

  • If expr is an integer value, it represents the number of days since year zero.
  • If expr is a numeric, the integer portion represents the number of days since year zero, and the fractional portion represents the part of the last day.
  • If expr is a char value, fmt can be:
    YYYY | Four-digit year
    YY | Two-digit year
    RR | Two-digit year in another century
    MM | Two-digit month of year (01 to 12)
    MON | Three-character month (all uppercase)
    mon | Three-character month (all lowercase)
    Mon | Three-character month (initial cap)
    DDD | Three-digit day of year (001 to 356)
    DD | Two-digit day of month (01 to 31)
    HH12 | Two-digit hour (00 to 11)
    HH,HH24 | Two-digit hour (00 to 23)
    MI | Two-digit minutes (00 to 59)
    SS | Two-digit seconds (00 to 59)
    SSSSS | Seconds past midnight (0000 to 86399)
    J | Days since 1/1/1
    other | Delimiting character
Parent topic: AcuXDBC Functions


TO_NUMBER

TO_NUMBER(expr[,fmt])

Returns the numeric representation of expr based on the fmt string or the default for expr's data type.

If expr is already a numeric, the value is not converted. If expr is a char value, fmt can be:

% | Percent sign at right of number
$ | Dollar sign at left of number
B | Display zero as blank
0 | Display leading zeros
9 | A digit position
other | Delimiting character (not leading)

The default mask is as many nines (9s) as required for the number's precision and scale.

If expr is a date value, the returned numeric represents the number of days since year 0 and the portion of the last day.

Parent topic: AcuXDBC Functions


TRANSLATE

TRANSLATE(char,from,to)

Returns char with all characters in from replaced with the corresponding ones in to.

  • If the number of characters in to is a multiple of the number of characters in from, that multiple of characters in to replaces each single character in from.
  • If to is empty, all characters found in from are deleted.
Parent topic: AcuXDBC Functions


TRUNC

TRUNC(value)
Returns the truncated value. If value is of type datetime, the hours, minutes, and seconds are set to zero. Otherwise, it is treated as a number and the fractional part is removed.
Parent topic: AcuXDBC Functions


UCASE

UCASE(expr)
Returns the uppercase character representation of expr.
Parent topic: AcuXDBC Functions


USER

USER()
Returns the username of the current connection.
Parent topic: AcuXDBC Functions


Working with Windows and Java Applications

This help section provides information on using AcuXDBC with Windows and Java applications.

  • Working With Windows Applications
  • Working with Java Applications
Parent topic: AcuXDBC Version 10.2.0 User's Guide


Working With Windows Applications

The most common way to interact with your COBOL tables (now an ODBC data source) is by using Microsoft Query, a database query tool that comes with Microsoft Office. You can invoke Query directly from Windows applications like Microsoft Word and Excel. Once in Query, you can use the point-and-click interface to build up queries graphically, or you can bring up a text box to manually enter SQL for execution by AcuXDBC. ODBC calls to the COBOL tables are totally transparent when you use Query. Other Windows programs, like Microsoft Access, Crystal Reports Professional, and the Microsoft Visual Basic development system, have their own interfaces to ODBC data sources.

This help section describes how you can access indexed file data from three of the most popular Windows applications: Microsoft Word, Excel, and Access. For instructions on accessing an ODBC data source from other Windows applications, see the application-specific user documentation. Examples assume you have performed all the setup tasks applicable to your environment, such as creating the sample database and a data source name (DSN).

Note: It is important to be aware of how many fields your application supports for a primary key. For example,AcuXDBC can support 16 columns in a primary key. Microsoft Access, on the other hand, supports only ten columns in a primary key. If your application does not support as many fields as your data, you can receive unexpected results.
  • Accessing Data From Word
  • Accessing Data From Word 2003
  • Accessing Data From Excel
  • Accessing Data From Access
Parent topic: Working with Windows and Java Applications


Accessing Data From Word

You can access your COBOL data from Microsoft Word 2000, 2003, or 2007. If you have a different version of Word, your instructions may be slightly different.

The procedures for using Microsoft Word 2003 or later use the Mail Merge task pane and wizard to create form letters. You can also create the letters using the Mail Merge toolbar. If you are an experienced Word user, you may favor this method over the Mail Merge task pane approach, but be aware that your steps will differ from what is depicted here.

  • Choose Your Data Source
  • Add Your Tables
  • Finish Preparing Your Document
Parent topic: Working With Windows Applications


Choose Your Data Source

  1. Start Microsoft Word and open a new document, or if you have a form letter already prepared, open that document.
  2. Perform the following action based on your Word version:
    Word Version | Action
    2000 | Click Tools > Mail Merge. If your Microsoft Office menus are set to Show recently used commands first, you may need to click the expansion arrows at the bottom of the Tools menu to see the Mail Merge option. The Mail Merge Helper dialog box appears.
    2003 | Click Tools > Letters and Mailings > Mail Merge. If your Microsoft Office menus are set to Show recently used commands first, you may need to click the expansion arrows at the bottom of the Tools menu to see the Letters and Mailings option. The Mail Merge task pane appears.
    2007 | Click Mailings > Start Mail Merge > Step by Step Mail Merge Wizard. The Mail Merge task pane appears.
  3. Perform the following action based on your Word version:
    Word Version | Action
    2000 | Under Main Document, click Create > Form Letters.
    2003 or 2007 | In the Mail Merge pane, select the Letters radio button, and then click Next at the bottom of the pane.
  4. Because you are already working in the document into which you want to insert data, perform the following action based on your Word version:
    Word Version | Action
    2000 | In the query message window, click Active Window. You are then returned to the Mail Merge Helper dialog box.
    2003 or 2007 | Click Use the current document, and then click Next.
  5. Perform the following action based on your Word version:
    Word Version | Action
    2000 | Under Data Source, click Get Data > Open Data Source.
    2003 or 2007 | In the Select recipients section, click Use an existing list, and then click Browse.
    The Select Data Source dialog box appears.
  6. From this dialog box, click the MS Query button. For this exercise, uncheck the Query Wizard check box if it is selected. If you do not have an MS Query button, you need to install Microsoft Query on your machine. This starts Microsoft Query and opens the Choose Data Source dialog box.
  7. In the Choose Data Source dialog box, click the data source name (DSN) corresponding to the data source you want to access and click OK.
    Note: See Setting Up DSNs on the Client for instructions on creating DSNs.
    If you don't see your DSN listed, do one of the following:
    • Click Browse and navigate to C:\Program Files\Common Files\ odbc\DataSources, then double-click the name of your DSN. This adds the DSN to the list in the Choose Data Source dialog box.
    • Click Options and type the path to the directory containing your DSN, then click Add. Now the contents of that directory will be listed. For more information, see the Microsoft Query documentation.
  8. If you or an administrator established database security methods during AcuXDBC setup, the AcuXDBC login dialog box appears; type a valid User ID and Password, and click OK.
    Tip: You can display just the tables of a given user by selecting from the owner drop-down list. For example, you could display only the tables that belong to PUBLIC by choosing PUBLIC from the drop-down list.
    The Add Tables dialog box appears.
    Note: If no security methods have been established, a User ID and Password are not required and the Login dialog box will not appear.
Parent topic: Accessing Data From Word


Add Your Tables

  1. In the Add Tables dialog box, click the name of the table you want to add (for example, CLIENTS), and then click Add. Do this for each table you want to add. Close the dialog box when you're finished. For each table you selected, a list box is displayed on the Microsoft Query screen. This box lists all of the columns in the associated table.
  2. In a list box, double-click each column that you want to read into your Word document. If you want to add all columns from a list box into your Word document, double-click the "*" at the top of the list box. If you prefer, you can select columns or further refine your query by clicking the SQL button in the toolbar and typing your own SQL statements.
    Note: See Summary of Supported SQL Commands for a description of the SQL commands supported by AcuXDBC.
  3. Click OK when you're finished.
  4. In the Microsoft Query dialog box, click File > Return Data to Microsoft Word.
  5. If you or an administrator established database security methods during AcuXDBC setup, the AcuXDBC Login dialog box appears; type a valid User ID and Password, and click OK.
    Note: If database security methods have been established and you previously supplied a correct user ID and password, this step is not necessary. If, however, you established security methods but didn't enter a user ID and/or password, the login dialog box will appear for you to do so now. If no security methods have been established, the Login dialog box will not appear.
    The Mail Merge Recipient dialog box appears.
  6. Make sure all the records are selected and click OK. Note that no records actually appear after you click OK. This is expected behavior, as this step is simply making the data records available to Microsoft Word. Additional steps are necessary to actually insert the data records into your document.

    The Mail Merge Recipients dialog box provides options for refining your mail merge list. For example, you can add or delete records, and specify certain record criteria. For help on using the commands appearing in this dialog box, see Microsoft Word documentation.

Parent topic: Accessing Data From Word


Finish Preparing Your Document

  1. Click Edit Main Document to continue preparing your document. Notice that new mail merge buttons have been added to the toolbar.
  2. Place the cursor in your document where you want to insert the data and click Insert Merge Field to see a drop-down list of table columns. These are the columns that you selected in Microsoft Query.
  3. Click the merge field you wish to insert. The control characters for this field are placed in your document.

  4. To display the data that corresponds to each field code, click the <<ABC>> button on the Mail Merge toolbar. Use the control buttons on the Mail Merge toolbar to move to the next, previous, first, or last record in the table.

  5. Finish your document as you normally would. Whenever you want to insert a data field, click Insert Merge Field once again and click the appropriate field.
For more instructions on using Word's mail merge feature, see your Microsoft documentation.
Parent topic: Accessing Data From Word


Accessing Data From Word 2003

You can access your COBOL data from Microsoft Word 2003 or later. This procedure uses Word's Mail Merge task pane and wizard to create form letters. You can also create the letters using Word's Mail Merge toolbar. If you are an experienced Word user, you may favor this method over the Mail Merge task pane approach, but be aware that your steps will differ from what is depicted here.

  • Choose Your Data Source
  • Add Your Tables
  • Finish Preparing Your Document
Parent topic: Working With Windows Applications


Choose Your Data Source

  1. Start Microsoft Word and open a new document, or if you have a form letter already prepared, open that document.
  2. Click Tools > Letters and Mailings > Mail Merge. If your Microsoft Office menus are set to Show recently used commands first, you may need to click the expansion arrows at the bottom of the Tools menu to see the Letters and Mailings option. The Mail Merge task pane appears.
  3. Select the Letters radio button, then click Next at the bottom of the pane.
  4. Click Use the current document, then click Next.
  5. Click Use an existing list, then click Browse. The Select Data Source dialog box appears.
  6. From this dialog box, click Tools > MS Query. For this exercise, uncheck the Use the Query Wizard check box if it is checked. If you don't have an MS Query option, you need to install MS Query on your machine. This starts Microsoft Query and opens the Choose Data Source dialog box.
  7. In the Choose Data Source dialog box, click the data source name (DSN) that corresponds to the data source you want to access and click OK.
    If you don't see your DSN listed, do one of the following:
    • Click Browse and navigate to C:\Program Files\Common Files\odbc\DataSources, then double-click the name of your DSN. This adds the DSN to the list.
    • Click Options and type the path to the directory containing your DSN, then click Add. Now the contents of that directory will be listed. For more information, see the Microsoft Query documentation.
    Note: See Setting Up DSNs on the Client for instructions on creating DSNs.
  8. If you or an administrator established database security methods during AcuXDBC setup, the AcuXDBC login dialog box appears; type a valid User ID and Password, and click OK.
    Tip: You can display just the tables of a given user by selecting from the owner drop-down list. For example, you could display only the tables that belong to PUBLIC by choosing PUBLIC from the drop-down list.
    The Add Tables dialog box appears.

    If no security methods have been established, a User ID and Password are not required and the Login dialog box will not appear.

Parent topic: Accessing Data From Word 2003


Add Your Tables

  1. Click the table or tables that you want to add (for example, clients) and then click Add. Close the box when you're done. For each table you selected, a list box is displayed on the Microsoft Query screen. This box lists all of the columns in the associated table.
  2. In the list box, double-click each column that you want to read intoto read into your Word doccolumns, double-click the "*" at the top of the list box. your Word document; that column then appears on the screen. If you want to add all In the list box, double-click each column that you want to read into your Word doccolumns, double-click the "*" at the top of the list box. If you prefer, you can select columns or further refine your query by clicking the SQL button in the toolbar and typing your own SQL statements, such as the one shown below.

    Click OK when you're done.

    See Summary of Supported SQL Commands for a description of the SQL commands supported by AcuXDBC.

  3. Click File > Return Data to Microsoft Word on the Microsoft Query dialog box.
  4. If you or an administrator established database security methods during AcuXDBC setup, the AcuXDBCC Login dialog box appears; type a valid User ID and Password, and click OK. If no security methods have been established, a User ID and Password are not required and the Login dialog box will not appear. The Mail Merge Recipient dialog box appears.
  5. Make sure all the records are checked and click OK.

    Note that no records actually appear after you click OK. This is expected behavior, as this step is simply making the data records available to Microsoft Word. Additional steps are necessary to actually insert the data records into your document.

    The Mail Merge Recipients dialog box provides options for refining your mail merge list. For example, you can add or delete records, and specify certain record criteria. For help on using the commands appearing in this dialog box, see Microsoft Word documentation.

Parent topic: Accessing Data From Word 2003


Finish Preparing Your Document

  1. Click Next on the Mail Merge task pane and continue preparing the body of your letter as needed.
  2. Place the cursor in your document where you want your customer data to appear and click More items on the Mail Merge task pane. The Insert Merged Field dialog box appears.
  3. Make sure the Database Fields radio button is selected. Click the field name you want to appear first in your document and click Insert. Click the next field you want and click Insert again. Repeat this process for each field that you want to add to your document. Once you have added all desired fields, close the Insert Merge Field dialog box.
    Note: This dialog box does not allow you to select multiple fields and insert them all at once. You must select and insert them individually.
  4. Format your fields as desired, then click Next on the Mail Merge task pane. The data corresponding to each field is displayed. Notice the options on the Mail Merge task pane to preview or edit your letters.
  5. When you are satisfied with your letters, click Next on the Mail Merge task pane.
  6. Click Edit Individual Letters on the Mail Merge task pane. The Merge to New Document dialog box appears. Consider your options for selecting which records to merge.
  7. Click All and then click OK. A new document containing individual letters for each record is created.
  8. Edit and save your letter document as you normally would. You can also save your original document containing the mail merge query and reuse it to create additional mail merge letters.
For more instructions on using Word's mail merge feature, see your Microsoft documentation.
Parent topic: Accessing Data From Word 2003


Accessing Data From Excel

You can access your COBOL data from Microsoft Excel 2000, 2003, and 2007. If you have a different version of Excel, your instructions may be slightly different.

  • Choose Your Data Source
  • Add Your Tables
Parent topic: Working With Windows Applications


Choose Your Data Source

  1. Start Excel. Excel automatically opens a new spreadsheet.
  2. Perform the following steps if your are using Excel 2000:
    1. Click Tools > Add-Ins. If your Microsoft Office menus are set to Show recently used commands first, you may need to click the expansion arrows at the bottom of the Tools menu to see the Add-Ins option.
    2. In the Add-Ins dialog box, select the MS Query Add-In checkbox and click OK. If this add-in does not appear on your list, reinstall Excel, being sure to select MS Query from the list of functions to install.
    3. In the Add-Ins dialog box, select the MS Query Add-In checkbox and click OK. If this add-in does not appear on your list, reinstall Excel, being sure to select MS Query from the list of functions to install.
  3. Perform the following action based on your Excel version:
    Excel Version | Action
    2000 or 2003 | Click Data > Import External Data or Data > Get External Data and then click New Database Query from the submenu.
    2007 | Click Data > From Other Sources > From Microsoft Query.

    This starts Microsoft Query and opens the Choose Data Source dialog box.

    If you want to use Microsoft Query Query Wizard to create your SQL query, leave the Use Query Wizard check box checked. For instructions on using the Query Wizard, see Microsoft Query's online documentation.

    For this exercise, uncheck the Query Wizard check box.

  4. In the Choose Data Source dialog box, click the data source name (DSN) that corresponds to the data source you want to access and click OK.

    See Setting Up DSNs on the Client for instructions on creating DSNs.

  5. If you or an administrator established database security methods during AcuXDBC setup, the AcuXDBC login dialog box appears; type a valid User ID and Password, and click OK.
    Tip: You can display just the tables of a given user by selecting from the owner drop-down list. For example, you could display only the tables that belong to PUBLIC by choosing PUBLIC from the drop-down list.
    The Add Tables dialog box appears.
    Note: If no security methods have been established, a User ID and Password are not required and the Login dialog box will not appear.
Parent topic: Accessing Data From Excel


Add Your Tables

  1. From the Add Tables dialog box, click the name of the table you want to add (for example, PETS) and then click Add. Do this for each table you want to add. Close the dialog box when you're finished. For each table you selected, a list box is displayed on the Microsoft Query screen. This list box shows all of the columns in the associated table.
  2. In a list box, double-click each column that you want to read into your Excel spreadsheet. If you want to add all columns, double-click the "*" at the top of the list box. If you prefer, you can select columns or further refine your query by clicking the SQL button on the toolbar and typing your own SQL statements. See SQL Commands for a description of the SQL commands supported by AcuXDBC.
  3. Click OK when you're finished.
  4. In the Microsoft Query dialog box, click File > Return Data to Microsoft Excel. The Import Data dialog box appears.
  5. Select where to put the data and then click OK. If you want to select further options, click Properties. If no database security methods have been established, the AcuXDBC Login dialog box will not appear. If database security methods have been established and you previously supplied a correct user ID and password, this step will not be necessary. However, if database security measures were established and you have not entered a valid user ID or password, you will be prompted to do so at this time.

    You are returned to Excel. The data you selected is displayed in the current Excel spreadsheet.

Parent topic: Accessing Data From Excel


Accessing Data From Access

You can access your COBOL data from Microsoft Access 2000, 2003, and 2007. If you have a different version of Access, your instructions may be slightly different.

Note: When you are accessing relative files, you don't need to specify a unique key for Access. When Access displays the dialog box requesting that you enter a unique key, just click OK without selecting any field.

If you are using the multi-company feature and are linking tables, you must relink every time you start Access and use this data source. See Multi-company Support for more information.

  • Choose Your Data Source
  • Add Your Tables
Parent topic: Working With Windows Applications


Choose Your Data Source

  1. Start Microsoft Access.
  2. Open an existing database or create a new one.
  3. Import or link tables based on your Access version:
    Access Version Action
    2000 or 2003
    1. Click File > Get External Data > Import or File > Get External Data > Link Tables.
    2. In the Import or Link dialog box, choose the ODBC Databases in the Files of type list box.
    2007 To import tables:
    1. Click the External Data tab.
    2. In the Import section, click the Access icon.

      The Get External Data - Access Database dialog box appears.

    3. Select a source file.
    4. Select Link to the data source by creating a linked table.

    To link tables:

    1. Click the External Data tab.
    2. In the Import section, click the More list, and then click ODBC Database.

      The Get External Data - ODBC Database dialog box appears.

    3. Select Import the source data into new table in the current database.
    Here's a brief comparison of working with imported or linked data. For more information, see your Microsoft Access documentation:
    Imported Tables | Linked Tables
    Data is local — the entire contents of an imported table are read into a copy on local storage. Data is remote — only rows requested from the linked table are read into local storage.
    Note: You can link to a local table, rather than creating a second copy by importing it.
    Importing can take several seconds, or even minutes, depending on the size of the database. | Creating a link is almost instantaneous, depending on the network connection.
    Space is required for local copies of imported tables. | The link requires very little local storage.
    Data is static — if there are changes to the database, they are not reflected in local data. If the database is subject to frequent changes, linking can be preferable. | Data is dynamic — you have access to any changes.
    If the network connection is broken, users still have access to data. | If the network connection is broken, users have no access to data until connection is restored.
    Users cannot write to the indexed file source. | Users can write to the indexed file source if the data source name (DSN) is read/write and the user has INSERT and/or UPDATE permissions on the object

    As a guideline, re-linking or re-importing is required when the table structure — such as the number of columns, or their names, sizes, and types — changes.

  4. In the Select Data Source dialog box, click the DSN that you established and click OK.
    AcuXDBC sources will appear on the Machine Data Source tab.
    Note: Click New to create a new DSN. See Setting Up DSNs on the Client for instructions on creating new DSNs.

    The AcuXDBC Login dialog box appears if you or an administrator established database security methods during AcuXDBC setup. If no security methods were established, a User ID and Password are not required, and the Login dialog box will not appear.

  5. If the Login dialog box appears, type a valid User ID and Password and click OK. Microsoft Access connects to the ODBC data source and displays the list of tables that you can import or link.
Parent topic: Accessing Data From Access


Add Your Tables

  1. Click the table or tables that you want to read into Access and click OK. Click Select All to add all of the listed tables to your Access database. In Access 2007, The Get External Data - ODBC Database dialog box appears. Select the Save import steps checkbox if you wish, and click Close.
  2. Double-click the table icon to open the table in Access. If you have imported the data, the table name or names you selected appear on the Access screen next to an icon of a table. You will see a different icon next to the table names if you have linked the data.
  3. You may now perform Access operations on this data.
Parent topic: Accessing Data From Access


Working with Java Applications

The enterprise edition of AcuXDBC includes the "vortex.jar" file, which enables a Java client application to connect to your Vision database. The general Java-specific steps and requirements involved in connecting to a Vision database include the following:

  • A Java source file that uses the DriverManager.getConnection method to initiate a COBOL database connection
  • String URL within the Java source file that includes the appropriate connection syntax
  • Java source file compiled using Java 1.5 or later
  • The path of vortex.jar specified in the CLASSPATH of the Java application you wish to run
  • Source File and String URL Syntax Sample
Parent topic: Working with Windows and Java Applications


Source File and String URL Syntax Sample

Included with AcuXDBC is the sample.java file, which is located in the samples directory of your product installation. This file demonstrates the use of the "DriverManager.GetConnection" method, along with the String URL syntax to connect to a remote system catalog.

Run the demo program, demo.bat on Windows and demo.sh on UNIX/Linux, to create a sample veterinarian database. The sample.java program will issue SQL commands to access the sample veterinarian database tables.

Note: No spaces are allowed between the String URL connection parameters. If access to the system catalog is local, @port no, machine name, and ip-address are not required.
  • sample.java
Parent topic: Working with Java Applications


sample.java

import java.sql.*;

class sample {
    public static void main (String argv[]) {
        try {

    /*  Note:  The format is

jdbc:vortex:userid//password/driver:configfile@port:hostname!databaseid

        For example
        (using defaults for driver, configfile, port, and databaseid):

jdbc:vortex:system//manager/gds10:acuxdbc.cfg@20222:myserver!acuxdbc04

    */

            String connectionURL =
                "jdbc:vortex://system/manager/gds10:" +
                "acuxdbc.cfg" +
                "@20222:myserver.microfocus.com" +
                "!acuxdbc04";

            String sqlStatement =
                "  SELECT                           \n" +
                "      patient_id,                  \n" +
                "      patient_name,                \n" +
                "      animal_type                  \n" +
                "    FROM                           \n" +
                        pets                        \n" +
                "    WHERE                          \n" +
                "       LCASE(animal_type) = 'dog'  \n" +
                "    ORDER BY                       \n" +
                        patient_name";

            System.out.println("\nConnection URL: \n" + connectionURL);
            System.out.println("\nSQL Statement:  \n" + sqlStatement);

            Class.forName("vortex.sql.vortexDriver");
            Connection conn =
                DriverManager.getConnection(connectionURL);

            Statement stmt =
                conn.createStatement(   ResultSet.TYPE_FORWARD_ONLY,
                                        ResultSet.CONCUR_UPDATABLE );
            ResultSet data;
            data = stmt.executeQuery(sqlStatement);

            System.out.print("\nRESULTS:\n\n");
            System.out.print(
                "Patient ID   Patient Name         Animal Type\n" +
                "============ ==================== ====================\n");
            while (data.next()) {
                System.out.printf( "%-12s %-20s %-20s\n",
                                    data.getString(1),
                                    data.getString(2),
                                    data.getString(3));
            }
        }
        catch(Exception e) {
            e.printStackTrace();
        }
    }
}
  • Compile the Source File
  • Run the Application with vortex.jar
Parent topic: Source File and String URL Syntax Sample


Compile the Source File

Compile the source file as follows:

java_home_directory/javac sample.java
Parent topic: sample.java


Run the Application with vortex.jar

To run your application, the path of vortex.jar must appear in the CLASSPATH of the Java application. For example:

Windows:

SET CLASSPATH=%ACUXDBC_BIN%\vortex.jar;.;%CLASSPATH%
java_home_directory\java sample

UNIX:

export CLASSPATH=directory_path/vortex.jar:.
java_home_directory/java sample
Note: You must have read and execute permission on vortex.jar to run your program. If you get the error message, vortex.sl. vortex driver, check the permissions that you have on vortex.jar.
Parent topic: sample.java


Troubleshooting

  • Introduction
  • Debug Logging
  • AcuXDBC Client Error Messages
  • AcuXDBC Server Error Messages
  • AcuXDBC SQL Processing Error Messages
  • Indexed File System Error Messages
  • Application Errors
Parent topic: AcuXDBC Version 10.2.0 User's Guide


Introduction

When installing, configuring, or using AcuXDBC components, you may encounter error messages along the way. This help section can help you find the cause of the error by explaining what the error message means. If you encounter an error message, locate it in this section and see if the information provided can help you uncover the underlying cause of the error. If you still cannot determine the cause, use the logging features of AcuXDBC to trace AcuXDBC and COBOL file activities; see the Debug Logging section for more details.

Error messages may originate from the following sources:

  • XDBC Client
  • XDBC Server
  • SQL Processor
  • Indexed File System
  • Client Applications
Parent topic: Troubleshooting
Related reference
Debug Logging


Debug Logging

To help you determine the cause of an error, you can turn on debug logging so that AcuXDBC traces AcuXDBC and COBOL file activities, and writes them to a file.

This logging can be configured so that it is enabled every time you use a particular data source, or for certain connection types, you can enable it dynamically on a connection-by-connection basis.

The easiest way to permanently enable logging for a data source is by using the Logging tab, available when you set up a connection in the ODBC Data Source Administrator. See AcuXDBC Setup: Logging Tab for more information.

To use configuration variables to enable debug logging, set the DEBUG_LOGFILE and DEBUG_LOGLEVEL configuration variables.

For JDBC connections, you can either enable debug logging dynamically, so that it is enabled just for that particular connection, or you can use a configuration file (called vortex.properties), which will be used if placed in the same directory as vortex.jar.

To enable dynamically, append the required GENESIS variables to your connection string; for example, the following string sets full logging:

jdbc://uid/pwd/xvision:acuxdbc.cfg@20222:machinename!acuxdbc04,GENESIS_LOGFILE=/path/to/logfile.log,GENESIS_LOGOPTS=3

Again for JDBC connections, if you place a configuration file (called vortex.properties) in the same directory as vortex.jar, its configuration is used for debug logging. The following sample shows the options available within the configuration file:

# VORTEXJava logging
# logfile is the name of the logfile, e.g. /tmp/logfile
# logfile=/tmp/logfile
# logopts is a list of options, separated by + (optional)
# logopts=FULL+MULTI+TIME
#
# VORTEXjdbc connection commands:
# These are sent to the target after the connection succeeds.
# A maximum of 20 statements are sent and they must be consecutively numbered
# without gaps.
#
# jdbcsql0=set option logfile '/tmp/test_c3po.log'
# jdbcsql1=set option plan on
#
# VORTEX network parameters
# connect_timeout - seconds to wait on a connect
# connect_timeout=15
# read_timeout - seconds to wait on a read response
# read_timeout=1440
# key_connect - integer key to use for uid/pwd obfuscation. Must match the
#               -kn vtxnetd option value.
# key_connect=1999
# environment_variables=VORTEX_HOST_LOGFILE=/tmp/test,VORTEX_HOST_LOGOPTS=FULL

Uncomment (and edit, where required) the options in the configuration file; for example, to enable full logging:

logfile=/tmp/logfile
logopts=FULL

The valid logopts keywords are:

FULL
Verbose output
MULTI
Append a time-stamp to the logfile name
TIME
Inserts time-stamps in the logfile.

You can specify more than one option, separated by +; the order in which you specify each option is not important.

The VORTEXjdbc commands are typically 'set option' commands; no query statements are allowed here. The statements are sent immediately after the connection is made.

The environment_variables value is appended to the connection string to make it easier to manage server-side logging.

Parent topic: Troubleshooting
Related reference
AcuXDBCSetup_LoggingTab
DEBUG_LOGFILE configuration variable
DEBUG_LOGLEVEL configuration variable


AcuXDBC Client Error Messages

Messages are listed in alphabetical order.

  • BADCONV
  • BADINI
  • CANCEL
  • CANFREE
  • CURDUP
  • DATATRUNC
  • DIALOG
  • FUNCSEQ
  • GENONLY
  • INVARG
  • INVAUTH
  • INVBUFLEN
  • INVCOLNUM
  • INVCURNAM
  • INVCURSTA
  • INVDATA
  • MANYCONN
  • MANYSTMT
  • MISSENV
  • MISSINDV
  • NOCONN
  • NOCURNAM
  • NODRV
  • NODSN
  • NOMEM
  • NOTCAP
  • NOTIMP
  • NOWHDL
  • OPTCHG
  • PARMCNT
  • PARMDTY
  • PARMNUM
  • TIDUSED
  • UNDESTYP
  • UNFETTYP
  • UNINTYP
  • UNOPT
  • UNUNOPT
  • UNXACOPR
Parent topic: Troubleshooting


BADCONV

The requested data conversion failed.

Resolution:

Check that the requested data is of the appropriate type. For example, this error occurs when a character column is fetched into an integer and the character data are not all digits.

Parent topic: AcuXDBC Client Error Messages


BADINI

The .ini file is missing, or its contents are invalid.

Resolution:

Check that the file exists and that its settings are correct.

Parent topic: AcuXDBC Client Error Messages
Parent topic: AcuXDBC Server Error Messages


CANCEL

Operation was cancelled by the driver manager.

Resolution:

Informational message; no action necessary.

Parent topic: AcuXDBC Client Error Messages


CANFREE

No processing was being done on the statement, so the call was treated as a call to SQLFreeStmt with the SQL_CLOSE option. Function returns SQL_SUCCESS_WITH_INFO.

Resolution:

Informational message; no action is necessary.

Parent topic: AcuXDBC Client Error Messages


CURDUP

The cursor name is already in use.

Resolution:

Specify a different name.

Parent topic: AcuXDBC Client Error Messages


DATATRUNC

Data has been truncated. Either the data specified is too long or supplied output buffers are too small.

Resolution:

Modify the size of the output buffers.

Parent topic: AcuXDBC Client Error Messages


DIALOG

The connect dialog failed.

Resolution:

Notify your system administrator.

Parent topic: AcuXDBC Client Error Messages


FUNCSEQ

The sequence of functions called is invalid.

Resolution:

Make sure that you follow the sequence specified by the ODBC documentation.

Parent topic: AcuXDBC Client Error Messages


GENONLY

This version of AcuXDBC supports only GENESIS.

Resolution:

Make sure you are attempting to connect to a AcuXDBC database.

Parent topic: AcuXDBC Client Error Messages


INVARG

Invalid arguments specified.

Resolution:

Consult the ODBC documentation for the correct syntax.

Parent topic: AcuXDBC Client Error Messages


INVAUTH

User not authorized to connect to specified data source.

Resolution:

Check your userid and password, or contact your system administrator.

Parent topic: AcuXDBC Client Error Messages


INVBUFLEN

The string or buffer length specified is invalid. Negative values such as SQL_NTS have special meaning, but not all negative values are valid.

Resolution:

Check the ODBC documentation for valid length specifiers.

Parent topic: AcuXDBC Client Error Messages


INVCOLNUM

The specified column number is out of range.

Resolution:

Verify that the correct column number is being used.

Parent topic: AcuXDBC Client Error Messages


INVCURNAM

The specified cursor name is invalid.

Resolution:

See the ODBC documentation for the maximum allowed length.

Parent topic: AcuXDBC Client Error Messages


INVCURSTA

The state of the cursor (such as OPENed, CLOSEd) is not valid for the current operation.

Resolution:

Make sure you've executed the necessary steps before calling this function.

Parent topic: AcuXDBC Client Error Messages


INVDATA

The data for the specified operation is invalid.

Resolution:

Verify that the data being used is correct.

Parent topic: AcuXDBC Client Error Messages


MANYCONN

The concurrent connections limit has been exceeded.

Resolution:

Reduce the number of concurrent connections.

Parent topic: AcuXDBC Client Error Messages


MANYSTMT

The number of allowable statements has been exceeded.

Resolution:

Either increase the limit in the Advanced tab of the Setup Dialog screen, or free any statements you are not using or do not need.

Parent topic: AcuXDBC Client Error Messages


MISSENV

Resolution:

The environment variable GENESIS_HOME is missing.

Set the GENESIS_HOME environment variable.

Parent topic: AcuXDBC Client Error Messages


MISSINDV

NULL data supplied without an indicator variable. If the data is NULL, an address of an indicator variable must be supplied.

Resolution:

Supply an address for the indicator variable.

Parent topic: AcuXDBC Client Error Messages


NOCONN

No connection established. A connect must be performed before any other operations.

Resolution:

Connect to the data source before attempting any database operations.

Parent topic: AcuXDBC Client Error Messages


NOCURNAM

Cursor name was never assigned.

Resolution:

Assign a cursor name.

Parent topic: AcuXDBC Client Error Messages


NODRV

No AcuXDBC driver was specified in the connect.

Resolution:

Verify that the connect string specifies the AcuXDBC driver.

Parent topic: AcuXDBC Client Error Messages


NODSN

The Data Source Name (DSN) was not specified.

Resolution:

Verify that the connect string specifies the DSN.

Parent topic: AcuXDBC Client Error Messages


NOMEM

A memory allocation failed. This is a fatal error. Either there is no more heap memory available (rare) or the heaps have been corrupted.

Resolution:

Notify your system administrator immediately.

Parent topic: AcuXDBC Client Error Messages
Parent topic: AcuXDBC Server Error Messages


NOTCAP

AcuXDBC does not support the requested capability.

Resolution:

Modify your program to not request this capability.

Parent topic: AcuXDBC Client Error Messages


NOTIMP

The feature has not been implemented yet.

Resolution:

Submit an enhancement request to Micro Focus.

Parent topic: AcuXDBC Client Error Messages


NOWHDL

No window handle available to open connect dialog.

Resolution:

Notify your system administrator.

Parent topic: AcuXDBC Client Error Messages


OPTCHG

A value of an option has been changed.

Resolution:

Informational message; no action is necessary.

Parent topic: AcuXDBC Client Error Messages


PARMCNT

The number of parameters specified does not match the number of parameters required by the statement.

Resolution:

Modify your program to use the correct number of parameters for the statement.

Parent topic: AcuXDBC Client Error Messages


PARMDTY

The data type specified for the parameter is unknown.

Resolution:

Consult the ODBC documentation for valid data types.

Parent topic: AcuXDBC Client Error Messages


PARMNUM

The parameter number specified is out of range.

Resolution:

Verify that your program uses the correct parameter number.

Parent topic: AcuXDBC Client Error Messages


TIDUSED

Another thread is currently using the statement.

Resolution:

Verify that your program does not use the same statement as is being used in another thread.

Parent topic: AcuXDBC Client Error Messages


UNDESTYP

The fDescType for SQLColAttributes() is unknown.

Resolution:

Modify your program to use the correct descriptor.

Parent topic: AcuXDBC Client Error Messages


UNFETTYP

Unknown fetch type. Currently only SQL_FETCH_NEXT is supported.

Resolution:

Modify your program to use only SQL_FETCH_NEXT.

Parent topic: AcuXDBC Client Error Messages


UNINTYP

The Info Type is unsupported.

Resolution:

Consult the ODBC documentation for valid values.

Parent topic: AcuXDBC Client Error Messages


UNOPT

The option is unknown.

Resolution:

Consult the ODBC documentation for valid options.

Parent topic: AcuXDBC Client Error Messages


UNUNOPT

The Uniqueness option is unknown.

Resolution:

Consult the ODBC documentation for valid values.

Parent topic: AcuXDBC Client Error Messages


UNXACOPR

The transaction operation is unknown.

Resolution:

Consult the ODBC documentation for valid values.

Parent topic: AcuXDBC Client Error Messages


AcuXDBC Server Error Messages

Messages are listed in alphabetical order.

  • AUTHBAD
  • AUTHFAIL
  • AUTHREQ
  • BADINI
  • CONFIG
  • DLLENTRY
  • DLLLOAD
  • DLLSAFE
  • EVALCORR
  • EVALEXP
  • EXECFAIL
  • HOSTNOT FOUND
  • INVHOSTSYN
  • INVVER
  • KEEPALIVE
  • LINGER
  • NOINTR
  • NOMEM
  • SERVNOT FOUND
  • SOCKET
  • UNDBID
Parent topic: Troubleshooting


AUTHBAD

The authentication syntax is invalid.

Resolution:

Follow the host name with the userid/password.

Parent topic: AcuXDBC Server Error Messages


AUTHFAIL

Authentication on service failed. You are not authorized to execute the requested host service.

Resolution:

Verify that the userid/password are correct or contact your system administrator.

Parent topic: AcuXDBC Server Error Messages


AUTHREQ

The host you are connecting to requires additional authentication.

Resolution:

Follow the host name with the userid/password.

Parent topic: AcuXDBC Server Error Messages


CONFIG

This assertion error notifies you that the first call must always be a CONFIG.

Resolution:

Make sure a CONFIG call precedes any other call.

Parent topic: AcuXDBC Server Error Messages


DLLENTRY

The loaded DLL or shared library does not contain the expected entry point. This error occurs only on machines that support DLLs or shared libraries and usually signals that the wrong DLL has been loaded.

Resolution:

Verify that theAcuXDBC DLLs have not been overwritten by other DLLs or that there are not other DLLs in the path with the same name.

Parent topic: AcuXDBC Server Error Messages


DLLLOAD

Could not load the specified DLL or shared library. The DLL is either missing or invalid. This error occurs only on machines that support DLLs.

Resolution:

Ensure that the DLL or shared library specification is correct (including spelling) and check that the correct DLL is installed.

Parent topic: AcuXDBC Server Error Messages


DLLSAFE

Loaded DLL is not thread safe. Not all database drivers are thread safe.

Resolution:

To avoid this error, run the single-threaded daemon: xdbcsrvr.exe.

Parent topic: AcuXDBC Server Error Messages


EVALCORR

The evaluation license ID has been corrupted.

Resolution:

Download the evaluation software from the Web site again or contact Micro Focus to purchase the software.

Parent topic: AcuXDBC Server Error Messages


EVALEXP

The evaluation license has expired. The timeout period is 4 hours.

Resolution:

To continue the evaluation, restart the AcuXDBC daemon. If you want a copy of the software that doesn't expire, contact Micro Focus to purchase the software.

Parent topic: AcuXDBC Server Error Messages


EXECFAIL

Exec name failed on host name. The service (program) specified in the network connection string could not be started. This error occurs if the service could not be found, does not have the correct permissions, or is not listed as a valid service.

Resolution:

Check that the service exists, is listed as a valid service, and that you are connecting with the correct user name and password.

Parent topic: AcuXDBC Server Error Messages


HOSTNOT FOUND

The host name you are trying to connect to is not found.

Resolution:

Make sure the spelling of the host is correct and that it really exists.

Parent topic: AcuXDBC Server Error Messages


INVHOSTSYN

The host/service syntax is invalid.

Resolution:

See the connect string documentation in mfdbcutil Syntax for information.

Parent topic: AcuXDBC Server Error Messages
Related information
Network Configuration


INVVER

NET version mismatch (host: number, client: number). The version of AcuXDBC Server is not the same as AcuXDBC Client.

Resolution:

Make sure that both sides of the network connection are at the same version level.

Parent topic: AcuXDBC Server Error Messages


KEEPALIVE

This assertion error indicates that the socket option KEEPALIVE failed or was not set.

Resolution:

Notify Micro Focus product support or your system administrator.

Parent topic: AcuXDBC Server Error Messages


LINGER

This assertion error indicates that the socket option LINGER failed or was not set.

Resolution:

Notify Micro Focus product support or your system administrator.

Parent topic: AcuXDBC Server Error Messages


NOINTR

Your program requested a cancel operation. The host you are trying to cancel cannot handle interrupts.

Resolution:

Modify your program so that it does not call the cancel operation.

Parent topic: AcuXDBC Server Error Messages


SERVNOT FOUND

The service and/or protocol name cannot be found.

Resolution:

For UNIX/Linux: Ensure that xdbcsrvr is specified in /etc/services.

For Windows:Ensure that vtxnet is specified in %SystemRoot%\System32\Drivers\etc\services. If it is not, you must add it, or explicitly specify the port number in the connect string.

Parent topic: AcuXDBC Server Error Messages


SOCKET

Call to the socket() function failed. The operating system may have run out of file descriptors.

Resolution:

Notify your system administrator.

Parent topic: AcuXDBC Server Error Messages


UNDBID

Unknown database ID specified in the net.ini file.

Resolution:

Use a valid database ID (from 0 to 3) in the net.ini file.

Parent topic: AcuXDBC Server Error Messages


AcuXDBC SQL Processing Error Messages

Following are error messages related to issuing SQL statements.

  • Cannot open file filename
  • Catalog table name corrupted or out of date
  • Character array too big (max: number)
  • Column name already defined
  • Column name undefined
  • Create view column count mismatch (create: number, select number)
  • Data truncation (max: number)
  • End of buffer reached
  • Ending quote missing
  • Function name not implemented yet
  • GENESIS_HOME environment variable not found
  • Identifier too long
  • If any numeric operand is NULL then only '==' and '!=' are valid
  • Illegal character
  • Illegal number of parameters for built-in function
  • Invalid parameter
  • Invalid password
  • Invalid predicate result (NULL or invalid datatype)
  • No data source specified
  • Non aggregates require a GROUP BY expression
  • No locks available on UPDATE
  • Notify tech support
  • NULL not allowed for column
  • Number of columns does not match number of values
  • Operation requires named authorization
  • Sort column name out of range (1 - number)
  • String too long
  • Sub-query must return a single column
  • Table name undefined
  • to_char/date/ number's format mask must be a constant string
  • Too many columns number (max: number)
  • Too many columns specified
  • Too many cursors opened
  • Too many sort columns (max: number)
  • Too many sub-queries at level number(max: number)
  • Too many tables in SELECT (max: number)
  • Unknown error code
  • Unknown node (type: name)
  • yacc: msg
Parent topic: Troubleshooting


Cannot open file filename

The specified file cannot be opened. The path may be wrong, it may not exist, or the permissions are not set correctly.

Resolution:

Check the spelling and verify the location of filename.

Parent topic: AcuXDBC SQL Processing Error Messages


Catalog table name corrupted or out of date

The specified catalog table cannot be read. It has either been modified directly or it is from a different version of AcuXDBC.

Resolution:

Rebuild the catalog with the correct catalog utility.

Parent topic: AcuXDBC SQL Processing Error Messages


Character array too big (max: number)

The SQL statement contains a character array that is too big.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Column name already defined

The SQL CREATE TABLE/VIEW statement has duplicate column names.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Column name undefined

The SQL statement refers to a column that is not defined in the catalog.

Resolution:

Correct the statement or define the column/table in the catalog.

Parent topic: AcuXDBC SQL Processing Error Messages


Create view column count mismatch (create: number, select number)

The SQL CREATE VIEW statement's column list does not match the number of columns in the SELECT statement's select list.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Data truncation (max: number)

Data was truncated.

Resolution:

Notify Micro Focus product support.

Parent topic: AcuXDBC SQL Processing Error Messages


End of buffer reached

The SQL statement ended prematurely.

Resolution:

Check the syntax for the command you are using.

Parent topic: AcuXDBC SQL Processing Error Messages


Ending quote missing

The SQL statement is missing an ending quote.

Resolution:

Add the missing quote.

Parent topic: AcuXDBC SQL Processing Error Messages


Function name not implemented yet

Not implemented yet.

Resolution:

Contact Micro Focus with an enhancement request.

Parent topic: AcuXDBC SQL Processing Error Messages


GENESIS_HOME environment variable not found

The GENESIS_HOME environment variable is not set.

Resolution:

Set the GENESIS_HOME environment variable, following instructions in the installation procedure.

Parent topic: AcuXDBC SQL Processing Error Messages


Identifier too long

The SQL statement contains an identifier that is too long. Identifiers are limited to 30 characters.

Resolution:

Rename the identifier.

Parent topic: AcuXDBC SQL Processing Error Messages


If any numeric operand is NULL then only '==' and '!=' are valid

The SQL statement's WHERE clause is using an invalid operator with a NULL value.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Illegal character

The SQL statement contains an illegal character at the given position.

Resolution:

Check the statement for legality.

Parent topic: AcuXDBC SQL Processing Error Messages


Illegal number of parameters for built-in function

The SQL statement has the wrong number of parameters for the built-in function.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Invalid parameter

The AcuXDBC COMMAND sent an invalid parameter for the specified command.

Resolution:

Verify that the parameters you use are all valid.

Parent topic: AcuXDBC SQL Processing Error Messages


Invalid password

The connection password is incorrect.

Resolution:

Ensure that you are using a valid password. Contact your DBA.

Parent topic: AcuXDBC SQL Processing Error Messages


Invalid predicate result (NULL or invalid datatype)

The SQL statement's WHERE clause returned a NULL or invalid datatype result.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


No data source specified

The connect string does not contain a data source specification.

Resolution:

Make sure you supplied a valid data source name. If you didn't create a data source name, for information on creating one, see Setting Up Data Source Names (DSNs) on Client.

Parent topic: AcuXDBC SQL Processing Error Messages
Related information
Setting Up DSNs on Client


Non aggregates require a GROUP BY expression

The SQL SELECT statement contains aggregate and non-aggregate select list items, and this requires a GROUP BY expression.

Resolution:

Edit the statement and use GROUP BY or change the statement's structure.

Parent topic: AcuXDBC SQL Processing Error Messages


No locks available on UPDATE

This sometimes happens when you link a file into Microsoft Access and perform an update that affects a large number of rows.

Resolution:

If the number of records affected by an update is less than 8191, set the configuration options MAX_LOCKS and/or LOCKS_PER_FILE to a value slightly higher then the number of records. The maximum setting is 8191.

If the number of records is higher than 8191, set the TRANSACTIONS variable to FALSE. This causes the interface to ignore the transaction command and update the records individually.

Parent topic: AcuXDBC SQL Processing Error Messages


Notify tech support

Internal error.

Resolution:

Notify Micro Focus product support.

Parent topic: AcuXDBC SQL Processing Error Messages


NULL not allowed for column

The SQL INSERT/UPDATE statement is using a NULL value for a not-NULL column.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages
Related information
INSERT command
UPDATE command


Number of columns does not match number of values

The SQL INSERT statement's values do not match the number of columns defined for the table or listed in the column list.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages
Related information
INSERT command


Operation requires named authorization

The SQL statement requires the specified authorization.

Resolution:

Ensure that you have authority to issue the statement. Contact your DBA.

Parent topic: AcuXDBC SQL Processing Error Messages


Sort column name out of range (1 - number)

The SQL SELECT statement's ORDER BY clause refers to a column number that is out of range.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


String too long

The SQL statement contains a string constant that is too long.

Resolution:

Use a bind variable.

Parent topic: AcuXDBC SQL Processing Error Messages


Sub-query must return a single column

The SQL statement contains a sub-query whose select list has more than one column.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Table name undefined

The SQL statement refers to a table that is not defined in the catalog.

Resolution:

Correct the statement to refer to a defined table or define the table in the catalog.

Parent topic: AcuXDBC SQL Processing Error Messages


to_char/date/ number's format mask must be a constant string

The SQL statement uses a data conversion function with a non-constant format mask string.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Too many columns number (max: number)

The SQL statement refers to a table with too many columns.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Too many columns specified

The SQL statement has too many columns defined.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Too many cursors opened

Your application has too many concurrently opened cursors.

Resolution:

Explicitly close cursors when they are no longer needed. If this action does not solve the problem, notify Micro Focus product support.

Parent topic: AcuXDBC SQL Processing Error Messages


Too many sort columns (max: number)

The SQL SELECT statement has too many columns in the ORDER BY clause.

Resolution:

Reduce the number of columns in the ORDER BY clause.

Parent topic: AcuXDBC SQL Processing Error Messages


Too many sub-queries at level number(max: number)

The SQL statement contains too many sub-queries.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Too many tables in SELECT (max: number)

The SQL SELECT statement contains too many tables.

Resolution:

Correct the statement.

Parent topic: AcuXDBC SQL Processing Error Messages


Unknown error code

Internal error.

Resolution:

Notify Micro Focus product support.

Parent topic: AcuXDBC SQL Processing Error Messages


Unknown node (type: name)

Internal error.

Resolution:

Notify Micro Focus product support.

Parent topic: AcuXDBC SQL Processing Error Messages


yacc: msg

The SQL statement cannot be parsed correctly.

Resolution:

Check for invalid keywords.

Parent topic: AcuXDBC SQL Processing Error Messages


Indexed File System Error Messages

Indexed file system (Vision File System) error codes have two numbers. The first number corresponds to a general "SQLSTATE" error. You can find information on SQLSTATE errors in general ODBC manuals, like the ODBC Programmer's Reference. The second number is the native indexed file error code. It lists the native error associated with AcuXDBC operation.

For example, in the following error code:

S1003   102

"S1003" is the SQLSTATE ODBC error number, and "102" is the native indexed file error number. The following are a list of the native indexed file errors that you may encounter.

  • 100
  • 102
  • 104
  • 105
  • 107
  • 111
  • 112
  • 113
  • 116
  • 117
  • 126
  • 127
  • 128
  • 129
  • 130
  • 131
Parent topic: Troubleshooting


100

A duplicate key was detected where duplicates are not allowed.

Parent topic: Indexed File System Error Messages


102

This indicates that a routine was called with an illegal parameter. For example, specifying a key number that is larger than the number of keys in the file would result in this error.

Parent topic: Indexed File System Error Messages


104

An attempt was made to open more files than the system allows open at once.

Parent topic: Indexed File System Error Messages


105

The index file is corrupt or the physical disk file does not match the type of file being opened.

Resolution:

If the index file is corrupt, it should be reconstructed using the appropriate host system utility.

Parent topic: Indexed File System Error Messages


107

The requested record is locked by another process or (for some systems) by another file handle used by this process.

Parent topic: Indexed File System Error Messages


111

The requested record was not found.

Parent topic: Indexed File System Error Messages


112

The current key of reference was in the undefined state when the i_next or i_previous routines were called. There is no current record from which to read forwards or backwards.

Parent topic: Indexed File System Error Messages


113

The file is locked against the current open mode.

Parent topic: Indexed File System Error Messages


116

The system ran out of dynamic memory.

Parent topic: Indexed File System Error Messages


117

An operation was requested that the current open mode doesn't allow. For example, attempting to add a record to a file that is open for input-only results in this error.

Parent topic: Indexed File System Error Messages


126

The requested operation is not supported by this host system.

Parent topic: Indexed File System Error Messages


127

The disk became full while adding a new record.

Parent topic: Indexed File System Error Messages


128

The size of the new record doesn't match the type of file being opened.

Parent topic: Indexed File System Error Messages


129

The system ran out of lock-table entries.

Parent topic: Indexed File System Error Messages


130

The file is missing.

Parent topic: Indexed File System Error Messages


131

Invalid permission for the operation.

Parent topic: Indexed File System Error Messages


Application Errors

You may occasionally receive an application-specific error message when trying to access data through AcuXDBC. For instance, when using Microsoft Query, you may receive an error like the following:

MSQry error:  This program has performed an illegal operation
and will be shut down.  If the problem persists, contact the
program vendor.

If you receive an error like this, try removing and re-adding your data source name (DSN) in the ODBC Data Source Administrator. Occasionally, the application may have difficulty recognizing the DSN; recreating the DSN should solve the problem.

For specific information regarding other application-specific errors, see your application's user documentation or online help.

Parent topic: Troubleshooting


Migrating from AcuODBC to AcuXDBC

  • Setup Differences
Parent topic: AcuXDBC Version 10.2.0 User's Guide


Setup Differences

Because of the increased functionality of AcuXDBC, the procedures for setting up and configuring AcuXDBC differ from AcuODBC. The following chart compares setup methods and highlights key differences between AcuXDBC versus AcuODBC. It also describes where to look for detailed information pertaining to the stated difference.

AcuXDBC | AcuODBC | Differences
Install software | Install software | AcuXDBC uses Microsoft Installer. See Installation and Licensing.
Create XFDs | Create XFDs | No major difference in creating your XFDs. If you already have XFDs from previous versions of AcuODBC or other products, these can be reused.
Set configuration variables in the configuration file Set configuration variables in AcuODBC DSN Setup tabs

To simplify client setup and enable universal configuration, AcuXDBC is configured via a configuration file rather than on each client machine during Data Source Name (DSN) setup.

Many of the options previously configured on the AcuODBC screens are now configured variables that you set in acuxdbc.cfg. This method allows you to use the same configuration file for the entire network by just pointing to the configuration file from each client's DSN setup screen.

Create a system catalog and load it with information from the XFD | Not required for AcuODBC | To provide greater relational database functionality, AcuXDBC refers to the system catalog to construct and display your Vision tables. After this loading phase, your XFDs are no longer needed by AcuXDBC. See General Setup Procedures for more information.
Set system security via SQL GRANT statement. | Set system security via AcuAccess file | The AcuAccess file and manager utility are no longer used with AcuXDBC. Instead, the SQL GRANT command and its variants are used to manage database security. See General Setup Procedures for more information.
Set up DSNs Set up DSNs

If you are migrating from AcuODBC, you need to create new DSNs. You accomplish this in generally the same manner in AcuXDBC; however, many of the variables that once appeared on the AcuODBC configuration screen now appear in the AcuXDBC configuration file (acuxdbc.cfg). This process allows for universal settings for DSNs and simplifies the process of setting up multiple clients in a network setting.

For large network installs, you can also create a .reg file and download the DSN information to your clients.

Parent topic: Migrating from AcuODBC to AcuXDBC


Xcentrisity Business Information Server for extend User's Guide

  • Introducing the Business Information Server
  • Using BIS
  • Server Response Files
  • Replacement Tag Reference
  • Control Flow Tags
  • Service Programs
  • BIS Tutorial
  • Server Variables Reference
  • XML Exchange Request File Format
  • Windows/UNIX Portability Considerations
  • Regular Expression Syntax
  • Log Files
  • BIS Troubleshooting Tips
  • Configuring BIS/IIS after Installation
  • Configuration after Installation (UNIX/Apache)
  • Creating a BIS/IIS Web Application
  • Building and Running BIS Samples
  • Glossary
Parent topic: extend Product Guides


Introducing the Business Information Server

  • Overview
  • Installation on Windows
  • Installation on UNIX
  • Testing the Installation
  • Uninstalling BIS for IIS
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Overview

The Xcentrisity Business Information Server (BIS) is a web server environment that manages COBOL application sessions and makes them available via any web browser or other web user agent that is granted access to the BIS server. BIS offers application developers a real opportunity to build state-of-the-art Service Oriented Architecture (SOA) applications incorporating legacy business data and logic freely mixed with the latest web languages and tools.

With BIS, remote users can access data, perform application functions and execute service programs on one or multiple servers located anywhere in the world. For example, a sales force can check order status for customers during the day and enter new orders in the evening as they travel. Emergency room doctors can read patient histories on primary care physician files in another state and primary care physicians can see insurance claim's status. Bank customers can see account status, pay bills, transfer funds, and make investments, all from the comfort of their own homes. Taxpayers can have access to public records from anywhere. With BIS, any modern application architecture, function, or appearance is possible.

Xcentrisity BIS has two major components:

  • A Request Handler, a web server extension that integrates either with Microsoft Internet Information Server (IIS) or the Apache web server.
  • The Service Engine, which executes COBOL code under the control of the Request Handler.

A service program is the application COBOL code that is executed by the Service Engine. This is application dependent, and provided by the application developer.

In the simplest case, an end user enters a URL into a web browser that specifies a specific web page on a server. The web browser then formats the request using HTTP or HTTPS and sends the request to the server specified in the URL. If the requested page is a reference to a simple HTML file (usually denoted by a file extension of .htm or .html), the contents of the HTML file are sent to the browser without any further processing.

However, if the reference is to a BIS stencil file (usually denoted by a file extension of .srf), the file is read and processed by the server before it is sent to the browser. Specifically, BIS interprets the file, processing any tags embedded in the file's HTML or XML content. A tag is composed of text surrounded by {{ and }} sequences, and tags may be interpreted as processing instructions or placeholders that are replaced by plain text, HTML or XML that is generated by the BIS service engine or by the BIS request handler.

Some useful definitions:

User Agent / Client | The program that is used to request information from a server. This program is frequently a web browser, but it could be any program on the user's machine.
HTTP | Hypertext Transport Protocol, a standard encoding scheme used to transmit requests to web servers and receive responses from web servers. HTTPS is a secure version of HTTP.
URL | Uniform Resource Locator, the location of a resource on the internet. A URL consists of a scheme (in this context, HTTP or HTTPS), the name of a machine, and a path to a file. For example, http://microfocus.com/bis/index.html specifies the file named index.html from directory bis on server machine microfocus.com using the HTTP scheme. When this is typed into a web browser, the browser issues a HTTP GET request on this file.
Request | An HTTP packet that contains a command issued by the user agent. A request may simply GET a file from a web server, PUT a file to the web server, DELETE a file from the web server, or may POST data (such as a form) to the server, or it may cause a program to be run on the server. GET and POST are by far the most frequently used commands.
SOAP | SOAP (Simple Object Access Protocol) is an XML-based web protocol designed to operate on HTTP to facilitate web services. It is particularly well suited to Remote Procedure Call (RPC)-style services.
REST | REST (Representational State Transfer) is an architectural style for distributed hypermedia systems and can be used to implement web services. While there is not a formal standard like SOAP, it is based on the four principle HTTP request types (GET, PUT, POST and DELETE), and URLs. In a REST architecture, a request payload may be in any format desired, including XML.
Web Server | A program that runs on a server and listens for HTTP requests. When a request is received, the web server processes the request or sends it on to another program (such as BIS) for processing. The two most common web servers are Microsoft's Internet Information Server (IIS), which BIS supports on Windows, and Apache, which BIS supports on UNIX.
Response | A HTTP packet that contains the response to the request. The response may be text, to be displayed in a web browser, or data encapsulated by SOAP for consumption by the requesting program.
Session | Requests are stateless, that is, the web server processes each request as if it had never received a previous request from the same user agent. A session is a BIS concept that allows sequential requests from the same user agent to be grouped together and preserves state information across requests on the server.

For more definitions, see the Glossary.

Parent topic: Introducing the Business Information Server


Installation on Windows

This covers installation of Business Information Server on Windows. Installation on UNIX is described in Installation on UNIX.

  • Prerequisites
  • Installation
Parent topic: Introducing the Business Information Server


Prerequisites

These are the prerequisites for BIS for Microsoft Internet Information Server (IIS) running on Microsoft Windows. A host machine running one of the following operating systems is required:

  • Windows XP Professional (32-bit only)
  • Windows Server 2003 (32-bit and 64-bit)
  • Windows Server 2003 R2 (32-bit and 64-bit)
  • Windows Vista (32-bit and 64-bit)
  • Windows Server 2008 (64-bit)
  • Windows Server 2008 R2 (64-bit)
  • Windows 7 (32-bit and 64-bit)
  • Windows 8 (32-bit and 64-bit)
  • Windows Server 2012 (64-bit)
  • Windows 8.1 (32-bit and 64-bit)
  • Windows Server 2012 R2 (64-bit)
  • Windows 10 (32-bit and 64-bit)

In addition, Internet Information Server (IIS) must be installed before BIS can be installed. The procedure for installing IIS is dependent on the version of Windows.

When BIS is installed on certain non-server operating systems, such as Windows XP, Windows Vista, or Windows 7, there are connection limit restrictions that prevent use as a real-world web server. These systems, however, do work well for BIS/IIS application development and testing.

IIS installation depends on the version of Windows:

Windows XP and Window Server 2003 [R2]

  1. Go to Start > Control Panel > Add or Remove Programs.
  2. Select Add/Remove Windows Components.
  3. Check Internet Information Services, then click Details.
  4. Check World Wide Web Service, then click Details.
  5. Check World Wide Web Service.
  6. Click OK in each dialog box, then click Next to complete the installation.

Windows Vista or later

  1. Go to Start > Control Panel > Programs and Features.

  1. Click Turn Windows Features On and Off.

  2. From the Windows Features dialog box, as a minimum, make the following selections:
    • Internet Information Services
      • Web Management Tools
        • IIS Management Console 1
      • World Wide Web Services
        • Application Development Features
          • ASP.NET 2
          • ISAPI Extensions
          • ISAPI Filters
        • Common HTTP Features
          • Default Document
          • HTTP Errors
          • HTTP Redirection
          • Static Content
        • Health and Diagnostics
          • HTTP Logging
          • Logging Tools
          • Request Monitor
        • Performance Features
          • Static Content Compression
        • Security
          • Basic Authentication
          • Request Filtering
          • Windows Authentication

Note that other features may also be required, but are selected by default.

Once configuration is complete, close the Internet Information Server (IIS) Manager window, and reboot if required.

Parent topic: Installation on Windows
1 Previous versions of BIS required that IIS Metabase and IIS 6 configuration compatibility also be selected. This was required by the BISMKDIR configuration utility. This version of BIS includes a new configuration utility, BISMKAPP, that only works on IIS 7 and later (Windows Vista and later). It has all the capabilities of BISMKDIR, but if BISMKDIR (which is still included with the installation) will be used, be sure to also select IIS Metabase and IIS 6 configuration compatibility.
2 Selecting ASP.NET is a fast-track way of selecting most of the other prerequisites. However, it is not part of the minimal set required to run BIS.


Installation

Business Information Server is installed as part of the extend® installation. On the Please select the extend (R) products you with to install page, check the Business Information Server for extend checkbox. The ACUCOBOL-GT Runtime COBOL Virtual Machine™ is also required.

During the installation, a Logon Information page displays. This is the user account under which the Business Information Server runs. This account must have sufficient privileges to access the data files for the COBOL program. If you leave the User Name and Password blank, the Business Information Server runs as the user who is currently logged in. If no one is logged in, Business Information Server does not function. Therefore, it is highly desirable to create a user account specifically for the Business Information Server, especially in a production environment. (See Logon Information for more information.)

  • Logon Information
Parent topic: Installation on Windows


Logon Information

This page selects the Windows logon ID that will be used to run BIS services.

The account chosen must have sufficient privileges to access the .COB program files, and the data files that are required to service BIS requests.

In this page, you must do the following:

  • Enter the user name (logon ID) and password that the BIS Service Engine should impersonate when running programs. The installer will validate the user name and password.

  • To search for an existing user, click the Browse button. Enter the name of a domain, server, or press the browse button to select from a list. Then enter a user name or press the browse button to select from a list. Finally, click the OK button to paste the result into the User name field.

  • To create a new user, click the Create… button. Select a domain or server, a Group, and specify a user name to create along with a password.

Once the User Name and Password have been selected, click Next. The installer will validate the information and report an error if the logon ID or the password is invalid.

Note: The logon ID can be changed at any time on the server-reinstallation is not required. See chapter Configuring BIS/IIS after Installation for more information.
Parent topic: Installation


Installation on UNIX

  • Prerequisites
  • Installation
  • Starting Apache and BIS
Parent topic: Introducing the Business Information Server


Prerequisites

BIS on UNIX supports the following machine environment:

  • x86 running Linux (glibc 2.5) 32-bit

The Apache 2.4 web server must be installed. Apache normally listens for HTTP requests on port 80 and for HTTPS requests 443, and when properly configured, routes BIS requests to the BIS Request Handler. On many versions of UNIX, Apache is available in a binary format that may be installed from the operating system's installation media or downloaded from the operating system's supplier. In order for Apache to use the BIS Request Handler, it must have shared object support. If downloading from a binary installation, make sure that it is configured with shared object support (mod_xbis_so). After downloading the binary installation, follow the supplier's instructions for installing Apache. If your system does not have Apache installed, or you wish to download and install the latest version, go to http://httpd.apache.org for more information.

Parent topic: Installation on UNIX


Installation

This section details installation of Business Information Server on UNIX. Windows installation is described in section Installation on Windows.

After Apache has been successfully configured, either start or restart it for the configuration to take effect.

BIS for UNIX is installed as part of the extend® shared library installation. Following installation, there are a couple of configuration scripts that need to be run to complete the installation of BIS and cause it to execute whenever the UNIX machine boots.

Before running the configuration script, create a new UNIX user account or choose an existing UNIX user account to run the BIS service engine. This account must have the permissions necessary to access the data files for the COBOL program. After choosing this user account, login as root and change directory to the install directory within the installation directory and run the config_bis_daemons.sh shell script.

The config_bis_daemons.sh script asks if you want to configure the BIS Service Engine options; answer Y. The current Service Engine options appear. Enter 1 to change the user account for the Service Engine and then enter the user account that you chose or created above. Finally, enter X to begin the configuration process.

Once the configuration process is complete, the config_bis_daemons.sh script displays the appropriate command to start the service daemons manually. This command is only necessary if you want to start the service daemons without rebooting the machine.

The second configuration script to run is config_bis_apache.sh. This script creates a configuration file named mod_xbis.conf that can be given to Apache to load the BIS Request Handler. On some distributions of Apache, all that is necessary is to copy this file to the Apache's conf.d directory. On others, you must edit the Apache conf/httpd.conf file and insert an include directive to the mod_xbis.conf file. When you run the config_bis_apache.sh script, it displays further instructions on installing the configuration file. Redirect standard output to a file to refer to these instructions later, or use the copy feature of your terminal emulator, if it supports that. See Configuring Apache for more details on configuring Apache.

After Apache has been successfully configured, either start or restart it for the configuration to take effect.

Configuring Apache

Configure the Apache web server so the mod_xbis.conf file produced by the config_bis_apache.sh script is read by Apache when it starts. If your version of the Apache installation has a conf.d directory, place the mod_xbis.conf configuration file into this directory. If your version of Apache does not use a conf.d directory, edit the main httpd.conf configuration file to include the following line:

Include Your-COBOL-Installation-Directory/etc/mod_xbis.conf

Any further changes to the configuration of the Apache portion of BIS should be made to the mod_xbis.conf configuration file.

See Configuration After Installation for more information on configuring the Apache Request Handler.

  • Configuring the Service Engine Options
Parent topic: Installation on UNIX


Configuring the Service Engine Options

When the config_bis_daemons.sh script is run, it will display the following prompt to give you the option to modify the default options for the Service Engine's configuration.

Do you want to configure BIS Service Engine options? [y]

Entering N will accept the default options and proceed with the installation. Accepting the default for this prompt will result in the following messages being displayed:

Current Service Engine options:
    1 User to run services as?   .   .   .   .    bis
    2 Timezone?  .   .   .   .   .   .   .   .    CST06CDT
    3 Default inactivity timeout, in seconds?     600
    4 Default service timeout, in seconds?   .    30
    5 Maximum number of service processes?   .    100
    6 Maximum number of request handler sessions? 200
    7 Name of temp directory?    .   .   .   .    /var/tmp
    8 Name of log files directory?   .   .   .    /var/tmp/bislogs
    X Done editing the Service Engine options

The following prompt will then be displayed:

If you would like to change an option, enter its number.  Press Enter to
redisplay the list of options.  Otherwise, enter 'X' to continue [R]:

If there is an option that you wish to change, enter its number and press Enter. For example, entering 1 will result in the following prompt:

User to run services as? [bis]

Enter the new desired value or accept the default. The prompt requesting the option to change will be displayed again. Enter R or just press Enter to review your changes. Enter a number to make more changes. Enter X to save your changes and proceed with the installation.

Parent topic: Installation


Starting Apache and BIS

Use the following command to start the BIS service engine on systems other than AIX:

/etc/init.d/xbisengd start

Use the following command to start the BIS Service Engine on AIX:

Your-COBOL-Installation-Directory/bin/xbisctl start

Use the following command to start or restart the Apache server.

apachectl graceful
Parent topic: Installation on UNIX


Testing the Installation

The samples are the best way to verify that BIS was successfully installed. To launch the samples on the server for BIS installed on a Windows system:

  • For BIS installed on a Windows system, click All Programs > extend [release number] > Business Information Server > Xcentricity BIS Samples.

To launch the samples on either Windows or UNIX, start a web browser and enter the URL:

http://localhost/acubis10/samples/default.srf

If you installed BIS on a different machine, replace localhost with the name of the Windows or UNIX machine running IIS or Apache. If the web browser is running on the same machine as IIS or Apache, then localhost refers to the current machine and may be used as the host name.

You should see the Welcome to the BIS Samples page:

As an additional test, click on the link to the first sample, verify. The BIS Verify sample page will be displayed, which is running the VERIFYBIS service program. Follow the instructions on this page to complete the verification.

Parent topic: Introducing the Business Information Server


Uninstalling BIS for IIS

To uninstall BIS/IIS, use either the Add or Remove Programs (on Windows XP) or the Programs and Features (on Windows Vista and later) control panel applet:

  1. Click Start > Control Panel and select either Add or Remove Programs or Programs and Features.
  2. Click the version of extend, which will contain options for removing BIS only.
  3. Click the Uninstall button.
  4. When the Program and Features message box appears requesting "Are you sure you want to uninstall Xcentrisity BIS for extend?", press the Yes button.
  • Removing Only the Web Application Samples on IIS
Parent topic: Introducing the Business Information Server


Removing Only the Web Application Samples on IIS

To remove the samples from a Windows IIS web site after installation, log onto the server and then:

  1. Click Start > Control Panel > Administrative Tools > Internet Information Services.
  2. In the Connections pane, expand the machine's name, then expand Sites, then Default Web Site (or your web site, if renamed).
  3. Right-click acubis10 and select Remove from the popup menu.

On IIS version 6 and later (that is Windows Server 2003 R2, Windows Vista, Windows 7, Windows Server 2008, or Windows Server 2008 R2), deleting the web virtual directory/application will not remove the physical folder. To complete the removal, delete the acubis10 physical directory (usually found under c:\inetpub\wwwroot) using Windows Explorer or from the Windows command line.

Parent topic: Uninstalling BIS for IIS


Using BIS

BIS functions as an extension to a web server, providing additional capabilities-namely, the ability to render and serve .srf stencil files, and the ability to quickly make both new COBOL programs and legacy COBOL programs available on the Web.

In order to understand how COBOL programs and the Web interoperate, some web concepts must also be understood. These are described in the next sections.

  • Web Protocols: Requests/Responses
  • Sessions
  • Tracking Sessions
  • Cookies
  • The Session Root Path and Session Scope
  • Timeouts
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Web Protocols: Requests/Responses

Web clients and servers communicate by using a request/response protocol called HTTP, which is an acronym for Hypertext Transfer Protocol. HTTP includes two methods for retrieving and manipulating data: GET and POST.

GET | Retrieves data from the server. The target of the request (referred to as a resource) is specified as a URI (Uniform Resource Identifier). This is usually (but not always) an absolute reference to a file on the server and is referred to as a URL (Uniform Resource Locator) when used in this context. Additional parameters, called Query Parameters, can also be specified.
POST | Posts data back to the server. In addition to a URL and query parameters, a POST request includes a payload. The payload is usually form data, the aggregated contents of the various fields (also called controls) that were in the response.

There are other methods (HEAD, PUT, DELETE), but the above two are the ones used by BIS for SOAP based web services. The other methods are available for REST-based web services.

The general form of a URL is familiar to anyone who has used a web browser:

http:// host [:port] / [absolute_path [ ? query_parameters ] ]

where:

http:// | Indicates that the Hypertext Transfer Protocol is being used to make the request. In a URI, this is referred to as the scheme. BIS supports two schemes: http and https (secure http).
host | The name or location of the computer that will receive the request.
port

An optional integer that specifies the port on the server that will receive the request. If omitted, this defaults to 80 for the http scheme, and 443 for the https scheme.

The combination of host and port (along with host headers, which is a scheme that allows a single host to serve multiple domains) specifies a unique web server.

absolute_path | The absolute location of the resource being requested on the host. This is frequently (but not always) the name of a file. Note that the base directory is not the root directory of the file system, but the root directory of the web tree that is being served by the host on the specified port.
query_parameters | Optional parameters that are made available to the web server and to the service program.

To summarize, a client (web browser or program using SOAP) sends an HTTP request to the web server. The request contains a method (GET or POST), a URI that specifies the file or resource that is being requested, optional query parameters, and optional form data (if a POST).

If the resource being requested is a resource that is associated with BIS by the web server, for example, a .srf file (sometimes also called a stencil), then all of the above information (request type, URI, query parameters, form data) is passed to the BIS Request Handler, which then renders (that is, executes) the tags in that file. If BIS renders a StartService tag, a COBOL service program is started. If BIS subsequently renders an XMLExchange tag, the request is sent to the COBOL program, and the COBOL program's response is rendered into the HTTP response text that is returned to the user agent (browser, SOAP consumer, etc.).

Parent topic: Using BIS


Sessions

HTTP requests are innately stateless. The web server does not provide any built-in mechanism to group consecutive requests together. However, once a service program is started, subsequent requests from the same user agent should be routed to the same service program. To make this possible, BIS creates a Session, which is a container of information for the user agent that persists from one request to the next . A session is automatically created when a request first arrives from a particular user agent. The Session contains information that BIS uses to recognize requests as belonging to a sequence, and associates requests with persistent data and services.

A Session is automatically created when BIS receives a request that cannot be associated with an already existing session. Once a Session is created, it persists until:

  1. The Session is complete: this can be requested by either the service program or by a special handler tag-the SessionComplete tag.
  2. A predetermined but adjustable amount of time passes without an additional request from the user agent, referred to as the Inactivity Timeout period.

Active Sessions use server resources, and if a service program is waiting for a request, this can be significant. Because site visitors may simply close the browser window without performing any action that indicates that they are finished with the application, BIS will free those sessions and resources after a predetermined period of inactivity.

Parent topic: Using BIS


Tracking Sessions

There are three common ways for servers to implement session tracking:
  1. A unique ID may be placed into the URL of subsequent pages.
  2. A unique ID may be placed in the query parameter of subsequent pages.
  3. The server sends a cookie that contains a unique identifier with the response. The user agent saves the cookie, and then includes the cookie with the next request.

BIS uses the third method, cookies, to identify sessions.

Parent topic: Using BIS


Cookies

In order to track user agent sessions, the BIS Request Handler places a Cookie in the responses that is sends to the user agent. The Cookie has a specific name, is associated with a specific URL, and contains the information that the BIS Request Handler can use to identify the session. When the client sends a request to the specific URL (or a URL containing the Cookie's URL), the client also sends the Cookie back in the request.

When the server receives this request, by default, BIS looks for a Cookie in the request to locate a session created by a previous request from the same user agent. When the BIS Request Handler receives a request containing the specially-named cookie, it uses the contents of the cookie to search for an existing session. If the session is located, BIS services the request using that session. If the session is not located, a new session is created for the request and the new session's cookie is included with the response.

The disadvantage of using cookies is that some user agents purposely disable cookies for privacy reasons: unscrupulous web sites can use permanent cookies to track the user agent's repeat visits over a long period of time. BIS uses only session cookies-a type of cookie that is automatically deleted when the user agent terminates-to avoid these concerns. It is also possible to configure a user agent to ignore session cookies. This will, unfortunately, prevent BIS applications from working with that user agent.

Parent topic: Using BIS


The Session Root Path and Session Scope

As stated above, when a session is created, the BIS server will include a Session Cookie that uniquely identifies the session with the response. The user agent saves the cookie, and includes the cookie with subsequent requests. The BIS server uses the cookie to associate requests with sessions.

Cookies are shared by all instances of a particular user agent. This makes it difficult for a particular user agent to gain access to more than one session on the server-if multiple browser windows on the same client machine request the same page, each window will send the same cookie, BIS will see the requests as originating in a single window, and will not create additional sessions. Multiple sessions are desirable if the end user wishes to run multiple BIS applications hosted by the same server in separate windows, or the application developer wishes to include multiple applications in a browser window by using HTML <OBJECT> or <IFRAME> tags.

Fortunately, there is a solution: the scope of a particular session cookie can be restricted to particular URL paths on the server. The user agent will only include the session cookie with a request URL that is as specific as, or more specific than the path that was specified when the cookie was stored in the user agent.

IIS and Apache derive the default application root path differently:

  • IIS defines the web application that contains the BIS application as the application root path. A web application is created during the initial installation, and additional web applications (and hence Application Root Paths) can be created at any time, either using the IIS Administration tool or by using the BISMkApp utility program that is provided with BIS.
  • Apache uses the value of the BIS_ROOT_PATH environment variable as the application root path. This is usually defined in the mod_xbis.conf configuration file and is set during installation. Multiple application root paths may be defined on a single server by defining the environment variable within the appropriate <Directory> section of the configuration file.

The application root path may be changed by using the {{SessionParms}} tag only during the rendering of the session's initial page. The session root directory may be set to:

  1. DEFAULT: the application root path.
  2. The path that directly contains the requested object.
  3. Any path that contains the requested object. However, the path cannot be closer to the root directory than the application root path.

For example, if the request URL is

http://microfocus.com/xbis/apps/states/texas/default.srf

and the default application root path is

/xbis/apps

then the application root path may be changed to any one of

  • /xbis/apps
  • /xbis/apps/states
  • /xbis/apps/states/texas

See The {{SessionParms}} Tag for more information.

Parent topic: Using BIS


Timeouts

BIS supports two kinds of timeouts:

  • Session Inactivity Timeouts
  • Service Timeouts

These timeouts are described in detail in the following sections.

  • Session Inactivity Timeout
  • Service Timeouts
Parent topic: Using BIS


Session Inactivity Timeout

Session inactivity timeouts are used to detect abandoned sessions and free server resources by deleting those sessions. For example, each active service program counts against the BIS Service Engine use count. If abandoned sessions are allowed to idle for an excessively long time, there may be a number of idle service programs consuming resources that could be recycled to handle new requests. The purpose of the session inactivity timeout is to free those resources.

To detect abandoned sessions, BIS stores the time the most recent request was received in the session. At various intervals, BIS determines if a session has been inactive longer than the timeout period set for the session. If so, the session is released.

There are two ways to indicate proactively that a session is complete and may be released:

  • On the page: embed the SessionComplete tag.
  • From a service program: call B_WriteResponse and specify BIS-Response-SessionComplete as the optional parameter.

In all cases, the session is not released until it is inactive; that is, all services within the session have ended and there are no active requests using the session.

  • Setting the Session Inactivity Time
Parent topic: Timeouts


Setting the Session Inactivity Time

The default inactivity timeout value for a BIS session is 600 seconds (10 minutes). However, the inactivity timeout value can be changed in several ways:

  • The timeout value may be globally set for all BIS sessions on the server with the BIS_SESSION_INACTIVITY_TIMEOUT environment variable on BIS/IIS and the Service Engine InactivityTimeout option keyword on BIS/Apache. The value must be specified in seconds. For example, on Windows:
    BIS_SESSION_INACTIVITY_TIMEOUT=600

    This environment variable sets the timeout to 600 seconds (10 minutes). See Setting Environment Variables for information about setting and modifying environment variables on Windows, and Service Engine Configuration for information on configuring BIS on UNIX.

  • The timeout may be set from within a .srf file by using the SessionParms(InactivityTimeout= seconds) tag (see The {{SessionParms}} Tag). Note that this parameter is specified in seconds and takes effect as soon as the tag is rendered.
  • The service program may set the timeout with the B_SetInactivityTimeout call. Note that this call does not take effect until the next time the service program interacts with the BIS Request Handler; that is, the service calls B_ReadRequest and BIS renders an XMLExchange tag.

Of these, the BIS_SESSION_INACTIVITY_TIMEOUT variable and InactivityTimeout option keyword have the lowest priority and are overridden by either the B_SetInactivityTimeout call or the SessionParms tag.

The largest value that the session inactivity timeout interval can be set to is 1,000,000 seconds (about 11 days).

Parent topic: Session Inactivity Timeout


Service Timeouts

When the BIS Request Handler passes a request to a service program, page rendering is suspended while the program performs the required processing. The service timeout value sets an upper bound on the amount of time that page rendering will be suspended.

The default service timeout is 30 seconds. This value can be changed in the following ways:

  • The service timeout value may be globally set for all BIS sessions on the server with the BIS_SERVICE_TIMEOUT environment variable on BIS/IIS and with a Service Engine ServiceTimeout option keyword on BIS/Apache. The value must be specified in seconds. For example, on BIS/IIS:
    BIS_SERVICE_TIMEOUT=30
    This environment variable sets the timeout to 30 seconds. See Setting Environment Variables for information about setting and modifying environment variables on Windows, and Service Engine Configuration for information on configuring BIS on UNIX.
  • The timeout may be set from within a .srf file by using the SessionParms(ServiceTimeout=seconds) tag. Note that this parameter is specified in seconds and takes effect as soon as the tag is rendered.
  • The service program may set the timeout with the B_SetServiceTimeout call. Calling this function with a parameter of 0 restarts the timer without changing the current value. This is useful as a keep-alive function when performing lengthy processing.

Of the above, the BIS_SERVICE_TIMEOUT variable and ServiceTimeout option keyword have the lowest priority and are overridden by either SessionParms tag or the B_SetServiceTimeout call.

Parent topic: Timeouts


Server Response Files

  • Overview
  • Rendering Tags
  • The Rendering Process
  • Tag Options and Parameters
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Overview

The Server Response File is the key control mechanism of BIS and BIS-enabled web applications and services. Each web application and service will contain at least one unique Server Response File, identified by the extension .srf. A Server Response File is also sometimes referred to as a stencil, since it acts as a stencil during the process of composing the content of an HTTP response to a request from a User Agent.

Server Response Files are can be HTML files augmented by additional information to control dynamic (program generated) content. In these cases, there are two differences between Server Response Files and regular HTML files:

  • When the user agent (usually a web browser) requests a .srf file that is contained within a directory served by BIS, the web server automatically loads and activates the BIS Request Handler to serve the file. A Request Handler is a component invoked by a web server such as Internet Information Server (IIS) or Apache to service a particular type of request; in this case, a request for a Server Response File.
  • Server Response Files will normally contain additional, non-HTML Rendering Tags that direct BIS to perform various kinds of processing and substitution while the page is being used to render the response content. This process usually includes execution of, and interaction with, ACUCOBOL-GT-based service programs whose execution is controlled and synchronized by BIS.

If Server Response File is used with web services, the Server Response File only contains the necessary tags to allow the Request Handler to route the request to the service program implementing the web service. Care must be taken when creating Server Response Files for web services not to introduce any extra formatting into the response that will confuse the client.

Parent topic: Server Response Files


Rendering Tags

Rendering tags are text strings embedded in the server response file HTML source code. A rendering tag has this general form:

{{ tag }}
{{ tag (parameter-list) }}

Rendering tags always begin with {{ and end with }} sequence and the tag itself is not case-sensitive, although parameters within the tag may be case-sensitive. Spaces are used in the examples to increase readability but are not required.

The optional parameter list may be formatted in a number of ways:

  • As a space-separated list of tokens:
    {{ ServiceLibs ( xmlif mylibrary ) }}
  • As a comma-separated list of key-value pairs:
    {{ SessionParms( InactivityTimeout=600, ServiceTimeout=30 ) }}

Except where specified, tokens may be enclosed in double or single quotation marks. This is required if a token contains spaces or a comma.

Under Windows, the total length of a tag (from the opening brace to the closing brace) may not exceed 4096 characters.

Important: Important: Both the opening {{ and the closing }} tag delimiters must be contained on a single line; that is, a tag may not contain embedded newline characters. Use caution when creating tags with HTML editors that reformat HTML and make sure that any reformatting does not split tags across multiple lines. Some strategies to avoid line wrapping problems:
  • Turn off line and word wrapping in your HTML editor for .srf files. Note that Visual Studio properly handles tags within the HTML editor.
  • Embed non-rendering tags (that is, tags that do not produce HTML output) in HTML comment sequences, as HTML editors will preserve formatting within comments. For example:
     {{ ServiceLibs( MyVeryLongLibraryName AnotherVeryLongLibraryName ) }}

You may still have to disable word-wrapping and reformatting for .srf files to prevent reformatting, or create tags that do not contain spaces.

Parent topic: Server Response Files


The Rendering Process

When the user agent requests a page from the web server, and the page designates a Server Response File (that is, the file is in a directory associated with BIS and has a .srf suffix), the page is automatically served by the BIS Request Handler. The page is processed from top to bottom and tags are rendered as they are encountered.

There are two basic kinds of rendering tags:

  • Processing Control Tags are tags that are completely removed from the final rendered content.
  • Substitution Tags are completely replaced in the final content by new (possibly empty) text.

If a tag is not recognized, it is rendered literally-that is, the tag appears in the output unchanged.

Note: Tags are order-dependent. A particular tag may affect how subsequent tags are rendered; for example, the StartService tag specifies the service that the XMLExchange tag uses. In addition, the Handler tag must be the first non-comment tag in every file, and it must appear within the first 4096 characters of the file.
  • Processing Control Tags
  • Substitution Tags
Parent topic: Server Response Files


Processing Control Tags

Processing Control Tags control how the page is processed by the BIS Request Handler. There is a tag that specifies the name of the service program to run to serve the page, tags that set processing options, and tags that allow for conditional processing (for example, parts of the page may be skipped).

Processing control tags are always removed from the rendered response.

Parent topic: The Rendering Process


Substitution Tags

Substitution Tags are replaced with new literal text, HTML, or XML. These tags are replaced by output from the service program or by the BIS Request Handler directly without program interaction.

Parent topic: The Rendering Process


Tag Options and Parameters

A particular tag may have one or more options or parameters. If this is the case, the options are specified in parenthesis after the tag name, except for the Handler and Include tags.

  • Pathnames
  • Referencing Files in System Locations
  • Predefined BIS Environment Variables
  • The FILE_PREFIX and CODE_PREFIX Environment Variables
  • Troubleshooting Tags
Parent topic: Server Response Files


Pathnames

There are two kinds of pathnames used within tags:

  • A fully qualified pathname begins with a slash. On BIS/IIS, the slash may optionally be preceded by a drive letter specification.
  • A relative pathname is any pathname that does not follow the above rules.

Relative pathnames are interpreted relative to the current directory. Under BIS, the current directory is the directory that contains the .srf file being processed.

The current directory for the BIS Service Engine is set when the StartService tag is executed. If a .srf file is subsequently served from a different directory, the current directory of the already-started Service Engine is not changed. However, any relative pathnames in the new .srf file are still interpreted relative to the directory that contains that .srf file.

On BIS/IIS, pathname resolution within the BIS service program is affected by the APPLY_FILE_PATH, CODE_PREFIX, EXPAND_ENV_VARS, FILE_ALIAS_PREFIX, FILE_CASE, and FILE_PREFIX runtime configuration variables. (See section File Name Interpretation, in the ACUCOBOL-GT Users Guide for more information.) These may be used to great effect in service programs in conjunction with the SetEnv tag.

Parent topic: Tag Options and Parameters


Referencing Files in System Locations

Several techniques are provided that allow files in system locations to be referenced from within a .srf file.

Under BIS/IIS, the following environment variables are useful in pathnames. Note that EXPAND_ENV_VARS must be set in the service configuration file for these to be useful.

Variable | Description
ProgramFiles | The location of the Windows Program Files directory.
SystemRoot | The drive and directory containing the Windows operating system.
TEMP TMP | The fully qualified path to the directory containing temporary files for the current process. Note that TMP and TEMP normally refer to the same directory, but this is not required.
USERPROFILE | The user's home directory.
WINDIR | Same as SystemRoot .
AllUsersProfile | The home directory for All Users.

On BIS/IIS, you can also define synonyms on the server using the configuration file, or directly define environment variables using the SYSTEM control panel applet:

Start > Control Panel > System > Advanced > Environment Variables

For example, if you add MyPrograms="c:\My Programs" to the environment, and have EXPAND_ENV_VARS in your configuration file, then you can refer to the file abc.cob by specifying a path of $MyPrograms/abc.cob. See Setting Environment Variables for information about setting and modifying environment variables on Windows.

On UNIX, use the xbis.conf configuration file to define BIS environment variables. See Configuring Apache for details.

Parent topic: Tag Options and Parameters


Predefined BIS Environment Variables

BIS adds the following variables to the environment under both IIS and Apache. Note that these variables are dynamically set during execution and are only available in the service program. They are not visible in your shell environment or in the .srf file.

Variable | Description
BIS_PROGRAM_DIR | The directory from which the BIS Service Engine is loaded. On Windows, this is typically XBIS.EXE in C:\Program Files\Micro Focus\extend x.x.x\AcuGT\bin .
BIS_FILENAME

The fully qualified name of the temporary file created for this session used to exchange data between the BIS Request Handler and the COBOL service program.

When the COBOL service program calls B_WriteResponse, the BIS Web Server reads this file to obtain the content (XML, HTML or plain text) replacing the XMLExchange tag in the response.

When the service program calls B_ReadRequest, the current web request document (XML) is written into this file. This includes any content such as the POSTed-back form variables, the request variables, and server variables, all encoded as an XML document.

By default, this file is created in the Windows TEMP

or, on UNIX, the BIS temp directory. This can be controlled during the UNIX installation with the "Name of BIS temp directory?" installation prompt and after the UNIX installation with the TempDir Server Engine Configuration. Both the BIS Request Handler and the Service Engine must have permission to create, read, and write files in this directory. The BIS installation procedure adds the required permissions to this directory.

Parent topic: Tag Options and Parameters


The FILE_PREFIX and CODE_PREFIX Environment Variables

If a relative filename is specified, the BIS service attempts to locate a data file by searching the directories specified by the FILE_PREFIX environment variable and a program object file by searching the CODE_PREFIX environment variable. For full details of how the BIS service program locates files, see Code and Data File Search Paths of the ACUCOBOL-GT User's Guide.

Note that the RunPath tag may be used to insert additional directories before the default FILE_PREFIX and CODE_PREFIX variables from the environment. Also note that this will override the contents of the FILE_PREFIX and CODE_PREFIX configuration variables, so use of the RunPath tag is discouraged.

Parent topic: Tag Options and Parameters


Troubleshooting Tags

If a tag is not performing the expected function, the tag may be malformed or may have been altered by an HTML editor. The following steps can help isolate this problem:

Is the tag itself visible in your web browser?

This indicates that BIS is not recognizing the tag. Check the spelling of the tag and be sure that the HTML editor did not split the tag across multiple lines-tags may not contain line break characters or span lines (you'll have to use the browser's View > Source to examine the raw HTML to be sure). On UNIX, enabling tracing (see below) and setting the BISStencilDebug configuration option will cause the generation of a trace message with the reason why a tag was rejected.

Did the tag fail to perform the requested function?

If a malformed tag is embedded in an HTML comment (see the example in the Rendering Tags section), the tag may fail to render but not be visible in the rendered output. To see such tags, use your web browser's View > Source command. Tags should never appear in the raw HTML that is sent to the web browser.

Does the tag appear in the trace output?

Enable tracing and examine the trace output. If you have access to the .srf file, to quickly enable tracing, insert this tag after the Handler tag:

{{ Trace(start,page) }}

Then request the page using your web browser. This will cause trace output to be appended to the end of the current page. The trace output indicates when most tags are rendered and the results of the rendering.

On BIS/IIS, to direct trace output to a file, replace page with file (or specify both using page,file). This will direct all trace output for the session into a file in the server's temporary directory (normally C:\Windows\Temp), or the directory specified in the trace dir= parameter. If you use this type of tracing, be sure to occasionally delete these files from the temporary directory.

The trace files use the following naming convention:

BIS-ssss-trace.txt

Where ssss are the initial characters from the session identifier. The first four non-slash characters of the session identifier are always used; if a file of that name already exists, BIS will continue to add characters from the session ID until the filename is unique.

On UNIX, trace output is directed to a file if tracing is enabled. A separate trace file is created for each session and is placed in the UNIX /tmp directory unless the BISTraceDirectory configuration option is specified or redirected with the trace dir= parameter. So on UNIX, Trace(start) is sufficient to create a trace file.

Note that on UNIX, the BISMasterTrace configuration option must be enabled before any tracing can occur. See Configuring Apache for details about setting or clearing this option.

Tracing is the most useful of the above techniques and should be enabled during the development process.

Parent topic: Tag Options and Parameters


Replacement Tag Reference

This section presents and discusses each tag that is implemented in Server Response Files.

Here is an example of a basic .srf file. Tags are italicized.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<!-- BIS control tags (removed when page is rendered) -->
<!-- {{ handler * }} -->
<!-- {{ Trace(queryparam=trace) }} -->
<!-- {{ StartService(samp03.acu) }} -->
<html>
<head>
    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title> COBOL Web Server Demonstration Page</title>
</head>

<body>
    <div align="center">
        <h3> COBOL Web Server Demonstration Page</h3>
    </div>
    <p>--- Begin Application-Generated XHTML ---</p>
    <div>
        {{ XMLExchange(OnExit="goodbye.srf") }}
    </div>
    <p>--- End Application-Generated XHTML ---</p>
    {{ TraceDump }}
</body>
</html>
Note that the first three tags in this example are embedded in HMTL comments. This is not strictly necessary from an operational standpoint (and may be undesirable because empty comments will be sent to the browser), but useful to keep an HTML editor like Microsoft FrontPage, Expression Web, Visual Studio or Adobe Dreamweaver from reformatting the text in the handler tag, or possibly splitting the tag across multiple lines. Some of these products support the server response file syntax directly and do not have this issue.
  • The {{Handler}} Tag
  • The {{ContentType}} Tag
  • The {{SessionParms}} Tag
  • The {{ServiceOpts}} Tag
  • The {{ServiceArgs}} Tag
  • The {{ServiceLibs}} Tag
  • The {{StartService}} Tag
  • The {{RunPath}} Tag
  • The {{SetEnv}} Tag
  • The {{XMLExchange}} Tag
  • The {{StopService}} Tag
  • The {{SessionComplete}} Tag
  • The {{Value}} Tag
  • The {{Trace}} Tag
  • The {{TraceDump}} Tag
  • The {{Debug}} Tag
Parent topic: Xcentrisity Business Information Server for extend User's Guide


The {{Handler}} Tag

This tag must appear at or near the beginning of every server response file that is to be processed by BIS. It indicates that this particular .srf file contains Xcentrisity BIS rendering tags.

handler *

The handler tag's parameter indicates the name of the handler to be invoked to render the tags within the stencil, with * indicating the default tag handler. In this release of BIS, the only supported handler tag is the default, so {{ Handler * }} is the recommended format of this tag.

Future versions of BIS may support additional handlers.

  • Notes
Parent topic: Replacement Tag Reference


Notes

  • The handler tag must appear in every .srf file, including .srf files included in other .srf files.
  • The handler tag must precede all other non-comment tags, and must appear within the first 4096 characters of the file. (Note that BIS/IIS allows include tags to precede the handler tag.)
  • Only one handler tag in each .srf file is permitted. On BIS/Apache, multiple handler tags are allowed, but only the first encountered in the file is relevant.
Parent topic: The {{Handler}} Tag


The {{ContentType}} Tag

This tag sets the content type for the HTML response.

ContentType ( value )

BIS does not attempt to interpret the value, which encompasses the entire parameter, including commas and any quotes.

  • Examples
  • Notes
Parent topic: Replacement Tag Reference


Examples

1. {{ ContentType(text/html; charset=utf-8) }}
2. {{ ContentType(text/xml) }}
Parent topic: The {{ContentType}} Tag


Notes

  • If not specified, the default content type is text/html; charset=utf-8. On BIS/Apache, if the content type of the request message indicates an XML message, the default content type of the response is text/xml; charset=utf-8.
  • If {{ContentType}} is specified multiple times on a page, the last instance is used.
Parent topic: The {{ContentType}} Tag


The {{SessionParms}} Tag

This tag allows various session attributes to be set:

SessionParms( InactivityTimeout= seconds | DEFAULT,
              ServiceTimeout= seconds | DEFAULT,
              Path = DEFAULT | path,
              Scope = ALL | ISOLATE )

where:

InactivityTimeout Determines how long a session survives without user interaction.
  • DEFAULT - Resets the timeout to the default setting: 600 seconds or 10 minutes.
  • seconds - An integer that specifies the number of seconds before the session terminates. The minimum value is 10 seconds (useful for testing) and the maximum value is 1,000,000 seconds (about 11 days).
ServiceTimeout Determines the maximum length of time the Service Program may run when a request is received.
  • DEFAULT - Resets the timeout to the default setting: 30 seconds.
  • seconds - An integer that specifies the number of seconds before Service Program termination processing begins. The minimum value is 10 seconds (useful for testing) and the maximum value is 3,600 seconds (one hour).
Path Specifies the root path of the current session. This parameter is ignored unless the page being served is the initial session page.
  • DEFAULT - The session root path is set to the path of the current request. See The Session Root Path and Session Scope for more details.
  • path - Explicitly sets the session root path to path. The path may be specified as a relative or an absolute URL path and must specify a path segment contained in the URL path of the initial page.

    In addition, under IIS, the specified path must contain at least as many path segments as the application root path (the base directory for the BIS application)-that is, the path cannot be closer to the root of the web than the BIS web application.

    For example, if the requested page is

    http://microfocus.com/xbis/apps/states/texas/default.srf

    the default session path is

    /xbis/apps/states/texas

    These paths may be specified to set the session root path to xbis/apps:

    Path="/xbis/apps"
Path=../../

    These paths set the default session path to the directory containing the requested object:

    Path=DEFAULT
Path=.
Path=”/xbis/apps/states/texas”
    These paths are invalid and are reported as being invalid in the trace file:
    Path=/xbis/apps/states/california
Path=../florida

    These directories are not contained in the path.

    In addition, for IIS servers, the path cannot be closer to the root than the application base path (the path that describes the web application that contains the BIS server).

Scope Determines the scope of the current session. This parameter may be specified at any time and is not inherited by new sessions.
  • ALL - All pages served from the session base directory and subdirectories of the session base directory are served as part of the current session. This option is the initial default for all new sessions and is appropriate for most applications.
  • ISOLATE - Only pages served from the session base directory are included in the current session. A new, non-isolated session is started when a page is requested from a subdirectory of the session base directory. The ISOLATE option allows a single user agent to use more than one BIS session as long as the sessions are based in separate directories on the server.
  • Notes
Parent topic: Replacement Tag Reference


Notes

  • All parameters are optional, but at least one parameter must be specified for this tag to be useful.
  • A change to the timeout takes effect as soon as either timeout parameter is parsed and the timer is restarted at that point.
  • It is strongly recommended that the inactivity and service timeout intervals are kept as short as possible. Setting the session inactivity limit to the maximum will keep sessions from automatically terminating when browser sessions are abandoned; this can result in a large number of orphaned BIS sessions that will not be cleaned up for over a week. It is better to set the inactivity timeout to 10 minutes and use a META REFRESH or a JavaScript timer to pull content from the BIS session every few minutes to keep the session active only while the browser window remains open.
  • Setting the service timeout interval too high can also have detrimental effects if a service programs unexpectedly runs away. Such a program can use 100% of the available CPU, preventing any other programs from starting or running effectively. The default setting of 30 seconds will terminate any run-away program within this reasonable amount of time.
  • The session scope determines if pages served from subdirectories of the session base directory are executed in new sessions. For example, if this page created the initial session:
    • http://microfocus.com/xbis/apps/states/default.srf

      and the application contains a link to this page, located in a more specific directory:

    • http://microfocus.com/xbis/apps/states/texas/default.srf
  • If SessionParms(Scope=All) is in effect, the subordinate page will be served from the same session as the initial page. However, if SessionParms(Scope=Isolate) is in effect, a new session will be created for the subordinate page.
  • For a description of the proper usage of the session base and session scope options, see The Session Root Path and Session Scope for more details.
Parent topic: The {{SessionParms}} Tag


The {{ServiceOpts}} Tag

This tag is a support tag for the StartService tag. It is for specifying options to the ACUCOBOL-GT runtime. See the section Using the Runtime System in the ACUCOBOL-GT User's Guide.

ServiceOpts ( options )

where:

options A space separated list of options to be passed to the runtime. Individual options may be quoted, using either single or double quotes, with the opening quote type matching the closing quote type.
  • Notes
Parent topic: Replacement Tag Reference


Notes

  • The options are supplied to the runtime in the order that they are specified in the ServiceOpts tag. Multiple ServiceOpts tags may be specified, with the options presented in the order that the tags are encountered in the SRF file. Only options specified up until the StartService tag are passed to the runtime.
  • If ServiceOpts tag is specified without the ( options ) parameter list, the set of options is emptied.
  • The options are not saved in the session.
Parent topic: The {{ServiceOpts}} Tag


The {{ServiceArgs}} Tag

This tag is a support tag for the StartService tag. It is for specifying parameters to the ACUCOBOL-GT runtime. See section Using the Runtime System in the ACUCOBOL-GT User's Guide.

ServiceArgs ( arguments )

where:

arguments A space separated list of parameters to be passed to the runtime. Individual parameters may be quoted, using either single or double quotes, with the opening quote type matching the closing quote type.
  • Notes
Parent topic: Replacement Tag Reference


Notes

  • The arguments are supplied to the runtime in the order that they are specified in the ServiceArgs tag. Multiple ServiceArgs tags may be specified, with the arguments presented in the order that the tags are encountered in the SRF file. Only arguments specified up until the StartService tag are passed to the runtime.
  • If the ServiceArgs tag is specified without the ( arguments ) parameter list, the set of arguments is emptied.
  • The arguments are not saved in the session.
Parent topic: The {{ServiceArgs}} Tag


The {{ServiceLibs}} Tag

This tag is a support tag for the StartService tag. It is for specifying libraries to the ACUCOBOL-GT runtime via the -y option. See section Using the Runtime System in the ACUCOBOL-GT User's Guide.

ServiceLibs ( libraries )

where:

libraries A space separated list of libraries to be passed to the runtime. Individual options may be quoted, using either single or double quotes, with the opening quote type matching the closing quote type.
  • Notes
Parent topic: Replacement Tag Reference


Notes

  • The libraries are supplied to the COBOL runtime in the order that they are specified in the ServiceLibs tag. Multiple ServiceLibs tags may be specified, with the libraries presented in the order that the tags are encountered in the SRF file. Only libraries specified up until the tag are passed to the runtime.
  • If ServiceLibs tag is specified without the ( libraries ) parameter list, the set of libraries is emptied.
  • The libraries are not saved in the session.
  • On UNIX, if a library does not begin with lib, it is automatically prepended. Furthermore, if the UNIX is a 64-bit operating system, and if 64-bit libraries have a suffix of 64 on this version of UNIX, 64 is appended to the library name. Finally, if library does not end with the proper extension for the UNIX operating system (for example .so or .sl), the proper extension is appended as well. These modifications to the library name are to allow the tag to be portable between Windows and UNIX.
Parent topic: The {{ServiceLibs}} Tag


The {{StartService}} Tag

This tag starts the execution of a service program. Options, parameters and libraries to be used by the service are specified by ServiceOpts, ServiceArgs and ServiceLibs tags.

StartService (  program)

where:

program The name of the service program to run. If a relative path is specified, the path is relative to the directory that contains the .srf file. If no directory is specified, the RUNPATH is searched (see below).

BIS only allows one service program to be active in a session. Note the following:

  • If no service program is currently running, the new service is started.
  • If the specified service program is already running, this tag is ignored.
  • If a service program is running, and program specifies a different service, the currently running service program is stopped (as if a StopService tag had been specified) and the new service program is started.

When a service program is started, BIS saves the name of the program. When another service program is started, BIS compares the new program name against the name of the program currently running. If there is an exact match (ignoring differences in letter case), the service is the same. If there is any difference, the new StartService tag refers to a different service and the currently running service program is stopped.

Once the service program is started, page rendering resumes. Rendering and the service program run in parallel.

Examples:

1. {{ StartService ( myapp ) }}
2. {{ ServiceLibs  ( mylibrary.acu ) }}
   {{ StartService ( myapp ) }}
3. {{ ServiceLibs  ( xmlif mylibrary.acu ) }}
   {{ StartService ( myapp.cob ) }}
4. {{ ServiceOpts  ( -c alt.cfg ) }}
   {{ ServiceLibs  ( xmlif ) }}
   {{ StartService ( myapp ) }}

In the examples above, the .ACU, and library files must be in a directory specified by CODE_PREFIX, and .CFG files must be in the FILE_PREFIX.

  1. Starts the program in file myapp.acu.
  2. Attempts to start program myapp after loading the mylibrary.acu service library. If the library contains a program called myapp, it is run from the library. If the program is not in the library, then the first program in myapp.acu is started.
  3. Starts the program in myapp.acu after loading xmlif and mylibrary.acu.
  4. Starts program myapp.acu after loading xmlif. The alt.cfg file is processed when the service program is loaded.

The StartService tag follows all the regular Service Engine program loading rules. See the ACUCOBOL-GT documentation for a detailed description.

  • Accessing the REQUEST from the Service Program
  • Notes
Parent topic: Replacement Tag Reference


Accessing the REQUEST from the Service Program

In many cases, the service program requires access to the information transmitted in the HTTP request message. This information is passed in the BIS Request XML document that is made available by a call to B_ReadRequest within the service program.

Parent topic: The {{StartService}} Tag


Notes

  • A given server response file can have multiple StartService tags. An additional StartService tag is ignored if it specifies a service that is already running. If it specifies a difference service, the service started by the previous tag is stopped before the new service is started.
  • The StartService tag must precede any tags that depend on the service program being active. Such tags currently include XMLExchange.
Parent topic: The {{StartService}} Tag


The {{RunPath}} Tag

The RunPath tag is a deprecated tag and should not be used. Use the SetEnv tag instead to set the desired PREFIX environment variable.

This tag is used to modify the RUNPATH environment variable that is passed to the Service Engine. The BIS Service Engine uses the RUNPATH to locate service program files and libraries.

RunPath ( [ dir [,dir]… ] )
  • Notes
Parent topic: Replacement Tag Reference


Notes

  • This tag causes the specified list of directories to be prefixed before the contents of any existing RUNPATH environment variable that is inherited from the system environment. Any number of directories may be specified, separated by commas or semi-colons (however, note that colons are not separators). If any dir contains spaces characters, it must be surrounded by double quotes. Directory names may not contain commas or semicolons.
  • This tag is a session attribute and remains in effect until the session ends or another RunPath tag is encountered, which will replace the directory list set by the previous RunPath tag. To clear the run path, specify {{ RunPath() }}. Note that the .srf directory cannot be removed from the RUNPATH sent to the service program.
  • This tag must precede the StartService tag or it will be ignored by the application.
  • Relative directories in the list are interpreted to be relative to the directory that contains the .srf file for the page being processed. This is the current directory that is set when the Service Engine begins to execute.
  • To explicitly reference the directory that contains the current .srf file, add . (that is, current directory) to the path.
  • See Setting Environment Variables for information about setting and modifying environment variables on Windows.
Parent topic: The {{RunPath}} Tag


The {{SetEnv}} Tag

This tag is used to set a variable in the service program's environment.

SetEnv ( name[=value] )
  • Examples
  • Notes
Parent topic: Replacement Tag Reference


Examples

{{ SetEnv ( printer=lpt1 ) }}
{{ SetEnv ( myfile=”c:\temp\scratchfile.tmp” ) }}
Parent topic: The {{SetEnv}} Tag


Notes

  • The SetEnv tag affects only the Service Engine's environment and not the BIS Request Handler's environment. The Value(variable,ENV) tag will not retrieve variables set by this tag.
  • Multiple SetEnv tags may be specified in a .srf file and are processed in the order in which they occur. Note that these tags must precede the StartService tag.
  • On BIS/IIS, the scope of a SetEnv tag is the current request, not the current session. On BIS/Apache, the scope of the SetEnv tag is the current session.
  • To unset an environment variable, omit the =value. Note that an unset variable is different from a variable that has a blank (or empty) value.
  • All characters to the right of the equal sign up to the first space before the right-most parenthesis are stored as the value. If the value is quoted as in the example above, quotes will also be set in the environment.
Parent topic: The {{SetEnv}} Tag


The {{XMLExchange}} Tag

This tag causes the web server to request text (typically XML, XHTML or HTML) from the currently running COBOL service program. The response text generated by the COBOL program replaces the XMLExchange tag in the output stream.

XMLExchange
XMLExchange ( OnExit=url )

The optional OnExit parameter determines the action that BIS takes if the service program is not active or terminates while the XMLExchange is being processed. It causes BIS to return an HTTP return code of 302 (HTTP_REDIRECT_FOUND) to the client. This causes the client to reissue the GET request for the specified URL.

  • Notes
  • Recursive Tag Processing in {{XmlExchange}}
  • The {{FormActionTarget}} Tag in {{XMLExchange}}
Parent topic: Replacement Tag Reference


Notes

  • Do not use OnExit with SOAP requests. SOAP clients may not be able to interpret the 302 error that is returned.
  • On BIS/IIS, the OnExit in the first XMLExchange tag following a StartService tag is ignored. This allows any service startup errors to be reported and corrected.
Parent topic: The {{XMLExchange}} Tag


Recursive Tag Processing in {{XmlExchange}}

BIS recursively processes tags in the service program's response output, as if the response output was a stencil. Tag substitution occurs as the service output is written to the response page (replacing the {{XmlExchange}} tag), and substitution is performed in the context of the page that contains the {{XmlExchange}} tag.

This behavior allows the service program to dynamically generate tags, thereby using BIS tag substitution features in the HTML, XHTML or XML produced by the service program. For example, if the generated HTML contains URLs in links, the {{Value}} tag can be used to process those URLs in the context of the requested page, and make the URLs absolute, based on the URL of the original request. Another example: the service program can also change the content type or character set of the response by generating a {{ContentType}} tag.

The {{FormActionTarget}} tag discussed in the next section is a tag that is specifically intended to be included in generated {{XmlExchange}} output. Also note that any tag may be embedded in the output - even another {{XmlExchange}}.

Parent topic: The {{XMLExchange}} Tag


The {{FormActionTarget}} Tag in {{XMLExchange}}

This tag is replaced by a URI referencing the current page and includes a query parameter that will be automatically checked by BIS to ensure proper sequencing of requests. BIS will check any requests to the current session and will reject (displaying an error page) any request that does not contain the query parameter served by the FormActionTarget tag. By using this tag, the service program may assume that any requests that return control to the service are in the sequence expected by the program.

The FormActionTarget tag should normally only be used as the value of the action attribute of an HTML <form> element. In any case it must be used in such a way that the next expected request will be directed to the URI represented by the tag.

If a response page rendered by BIS does not contain the FormActionTarget tag, no sequence checking will be performed by BIS. The service program may, of course, perform its own checking using other means, such as hidden fields, if required.

Parent topic: The {{XMLExchange}} Tag


The {{StopService}} Tag

This tag terminates the execution of the service program that is attached to the session.

StopService
  • Notes
Parent topic: Replacement Tag Reference


Notes

  • If the service program is not awaiting a request when this tag is rendered, the program must call B_ReadRequest within ServiceTimeout seconds. The call then returns with the BIS-Fail-ProgramTerminated return code. At that point, the program is granted an additional ServiceTimeout seconds to terminate.
  • If the program is still running when either ServiceTimeout period expires, a termination signal is sent.
  • Once the StopService tag is rendered, the service program is immediately disconnected from the session. For example, an XMLExchange tag immediately after a StopService tag is invalid and, if present, the OnExit parameter in that tag will be processed.
  • The StopService tag may be immediately followed by a StartService tag. In this case, a new service program is started. Once the StopService tag is rendered, the service program is considered terminated even if it needs a few additional seconds to actually stop.
  • This tag is ignored if there is no service program attached to this session.
Parent topic: The {{StopService}} Tag


The {{SessionComplete}} Tag

Indicates that the current session is complete and may be released. The session cookie will be deleted when the response for the current page is sent to the client.

SessionComplete
  • Notes
Parent topic: Replacement Tag Reference


Notes

  • If a BIS service program is currently active, this tag implicitly performs a StopService at the point this tag is rendered. See the description of the StopService tag for details about how the service program is informed the session is ending, and the sequence of events that transpire. Note, however, that the current or next call to B_ReadRequest returns the BIS-Fail-SessionTerminated result code instead of BIS-Fail-ProgramTerminated.
  • This tag is most useful on a goodbye page, but is optional because sessions are automatically terminated after a period of inactivity. However, explicitly ending a session can be used to release system resources, or to force a new session to be started for the active client when the next page is requested.
Parent topic: The {{SessionComplete}} Tag


The {{Value}} Tag

This tag looks up a value on the server and the tag is replaced with that value.

Value (variable|”variable” [, source] [,operations]…)

By default, variable is a server variable or a special variable (described below). However, options can direct that the value be obtained from the environment, the server configuration, a submitted form, a cookie, or a query parameter.

On BIS/IIS, if variable is enclosed in quotes, the variable name is treated as a literal string and is not resolved further unless one of the source options below is specified.

On BIS/Apache, if variable begins with a quote, it is treated as a literal and no source option is permitted.

Either single or double quotes may be used as delimiters, and a delimiting quote may be embedded in the string by specifying the quote twice: "abc'""def" becomes abc"def.

The source option determines from where the variable value is obtained. If specified, the source must be the second parameter.

SERVER | Specifies that variable is a server variable. This is the default if none of the other sources below are specified and if the string is not quoted. Under BIS/Apache, ENV and SERVER are identical.
CONFIG | Specifies that variable is a special server configuration value. A list of CONFIG variables appears at the end of this section.
COOKIE | Specifies that variable is a cookie.
ENV | Specifies that variable is an environment variable instead of a server variable. Note that, on BIS/Apache, ENV and SERVER are identical. See Setting Environment Variables for information about setting and modifying environment variables on Windows.
FORM | Specifies that variable is a <form> variable.
QUERYPARAM QP | Specifies that variable is a URL query parameter. QP is accepted as an alias for QUERYPARAM .

These operations modify the retrieved value and are applied from left to right and may be applied multiple times.

DEFAULT=value

Specifies a default value for variable if the variable is empty. This option has no effect unless the variable is empty at the point the DEFAULT operation is performed.

  • If the variable is empty when the end of the entire operations list is reached, the Value tag is simply removed from the output stream.
  • If DEFAULT is encountered and the variable is empty, the tag is replaced by value. If there are additional operations to the right of the DEFAULT operation (that is, GETDIR , TOUPPER, URLENCODE), these are performed on the new defaulted value.
GETDIR Same as GETPATH

(see below), except only the directory portion of the pathname is extracted. This is the part of the pathname that follows the scheme and hostname up to the last slash in the pathname. Note that if variable is a pathname that contains a drive letter, the drive letter is also returned. The extracted pathname never ends in a slash.

GETQUERYSTRING | If variable is a URL, returns the query string. If not present or if variable is a pathname, an empty string is returned.
GETHOST | If variable is a URL, extracts the hostname. If variable is a pathname, or no host name is present, an empty string is returned.
GETNAME | Same as GETPATH , except only the filename portion of the pathname is extracted. This is the part of the pathname that follows the last slash but excludes the #fragment , ?querystring, and ;parameters.
GETPATH | If variable is a URL, extracts the path portion of the URL. This is the portion of the URL that excludes the scheme, the hostname, and the query string. If variable is a pathname, it is unchanged.
GETSCHEME | If variable is a URL, extracts the scheme. This will normally be http or https without the terminating colon or slashes. If variable is a pathname or a URL without a scheme, an empty string is returned.
SUBSTITUTE= pattern/replacement/

SUB=/pattern/replacement/

Allows you to substitute all occurrences of pattern in the value with a replacement pattern. The operation is performed on the current value after all transforms to the left have been performed. Processing continues with the modified value.

SUB is accepted in place of SUBSTITUTE for brevity. Both pattern and replacement are regular expressions. (For more information, see Regular Expression Syntax).
TOUPPER | Converts the value to all upper-case characters. Equivalent to SUBSTITUTE="/.*/\U&/".
TOLOWER | Converts the value to all lower-case characters. Equivalent to SUBSTITUTE="/.*/\L&/".
URLDECODE | Decodes a string that has been URL-encoded. This is primarily useful when retrieving a server variable.
URLENCODE | Encodes a string for reliable HTTP transmission from the web server to a client as a URL. For example, This is a <Test String>. will be encoded as: This%20is%20a%20%3cTest%20String%3e.
HTMLDECODE | Decodes a string that has been HTML-encoded. This is primarily useful when retrieving a server variable.
HTMLENCODE | Encodes a string for reliable HTTP transmission from the web server to a client as HTML. For example, This is a <Test String>. will be encoded as: This is a &lt;Test String&gt;.
MAKEABS Assumes that the string is a relative URL, and makes the URL absolute, using the location of the stencil that was requested by the client as the base URL (see REQUEST_URL in Configuration Variables for details). If the string is not a URL, it is not altered. If the input string is an absolute URL, it is cleaned up (that is, redundancies such as dir/../ are removed) but is otherwise unchanged.

See RFC 3986 for details about how relative URLs are resolved by this operation.

Processing stops when the following option is encountered and the tag always renders as an empty string.

MATCH=regexp Applies the regular expression against the current value and returns true if it matches and false if it does not match but does not return any text for rendering. This allows Value to be used in If tags. See Regular Expression Syntax.

For example, the tag:

{{ VALUE (HTTP_URL, GETDIR, TOLOWER, URLENCODE) }}

is replaced by the directory that contains the page that is currently being served. The name of the directory is converted to lowercase and the directory name is URL-encoded (for example, recommended if the value will be substituted into an HREF attribute). HTTP_URL is a server variable, but it is not necessary to specify the SERVER source parameter because this is the default.

On Windows XP, the tag:

{{ VALUE (PROCESSOR_IDENTIFIER, ENV, DEFAULT=”Unknown”, HTMLENCODE) }}

is replaced by the contents of the PROCESSOR_IDENTIFIER environment variable. If this variable is not defined, the text Unknown (without quotes) is output instead. The output is HTML-encoded so any < or > characters in the environment variable are properly converted.

  • Notes
  • Configuration Variables
Parent topic: Replacement Tag Reference


Notes

  • The Value tag can be referenced in an If tag if the MATCH operation is used, but cannot be nested within any other tags. It can, however, appear anywhere else in the HTML as long as it follows the Handler tag. This tag can therefore be used to provide content for any HTML element.
  • When used in an If tag without the MATCH option, the condition is TRUE if Value evaluates to a non-empty string; otherwise, FALSE.
  • Regular expressions must be delimited. The first nonblank character after the = is the delimiter for the regular expression. The expression begins at the character following the delimiter and extends up to, but not including the next occurrence of that character.

    Single or double quotes are common delimiters, but the delimiter may be any character. Examples:

    1. {{ VALUE (QUERY_STRING, SERVER, MATCH=”?userid=fred\s”) }}
2. {{ VALUE (QUERY_STRING, SERVER, MATCH=/?userid=”fred\s”/) }}

    (Note that QUERY_STRING is a server variable that contains the query string part of the URL.)

    The second regular expression includes quotes, so a delimiter (/) was chosen that does not occur in the expression.

    Another way to accomplish the above is to use the QUERYPARAM source option:

    {{ VALUE(userid, QUERYPARAM, MATCH=”fred\s”, URLENCODE) }}
  • Commas cannot occur inside delimited or quoted strings because commas always separate parameters. If a comma is required, use "%2c" and URLDECODE the string to convert the "%2c" to a comma.
Parent topic: The {{Value}} Tag


Configuration Variables

In addition to server variables and environment variables, some special variables are supported. These variables may not be implemented on all platforms.

HOSTSERVER | Returns IIS or Apache. Note that under IIS, the SERVER_SOFTWARE server variable can be used to retrieve the version number. However, this server variable may be undefined under Apache.
MAXTHREADS

Resolves to the number of threads configured in the BIS thread pool. This is the number of threads that are available for requests. Under Apache, this is undefined (use DEFAULT=1 if portability is desired).
REQUEST_URL | Retrieves the completely qualified URL of the stencil (.srf) file that was requested by the client. This includes the scheme, hostname, port number (if non-standard), path, and parameters, query string, and fragment (if specified).
REQUEST_BASE_URL Retrieves the completely qualified base URL of the current stencil (.srf) file that was requested by the client. This includes the scheme, hostname, port number (if non-standard), and the path (which always ends in a slash).

The base URL is defined as the directory that contains the stencil that was requested by the client.

STARTSERVICE | Returns the entire argument list of the currently active StartService tag, including commas. If there is no active service program, the value is considered undefined and may be overridden with the DEFAULT operation.
SCHEME

Returns the scheme that was used to request the current page: currently returns either http or https. Note that the :// delimiter that follows the scheme is not included. This is useful for constructing URLs:

<a href="{{ Value(SCHEME, CONFIG) }}://
{{ Value(HTTP_HOST,URLENCODE) }}
{{ Value(HTTP_URL,GETDIR,URLDECODE,URLENCODE)
}}/default.srf">

(Note that the above must be on a single line, or spaces will be inserted.) Under BIS/IIS, the scheme is derived from the SERVER_PORT_SECURE server variable, where a value of 0 indicates http and nonzero indicates https.

SERVICENAME | Retrieves the name of the currently active service program. If there is no active service program, the value is considered undefined and may be overridden with the DEFAULT operation.
VERSION | Retrieves BIS version information. The format of the version number is aa.bb.cc.yyyy/mm/dd, where aa.bb.cc indicates the numeric major/minor/patch level version, and yyyy/mm/dd is the build date.
Parent topic: The {{Value}} Tag


The {{Trace}} Tag

Enables or disables trace logging for the current session.

Trace ( options )

The options in the table below control the internal accumulation of trace information on UNIX. Windows always accumulates trace information and these options are ignored.

START | START causes BIS to begin accumulating trace output. If tracing has been started, START has no effect.
STOP | STOP causes BIS to stop accumulating trace output. If tracing has not been started, STOP has no effect.
OFF | Turns tracing off. Equivalent to STOP,NOPAGE,NOFILE,NOTAG,NOEXCHFILES,NOQUERYPARAM,NOIP.

The options in the table below determine where the TRACE output is emitted. They are independent of each other. The underlined options are the defaults.

PAGE | Indicates that the trace is emitted at the end of the page.
NOPAGE | Disables end of page trace output.
FILE | Indicates that the trace is written to a file in directory indicated by the DIR option.
NOFILE | Disables trace output to the file.
TAG | Enables the TraceDump tag and allows it to write trace output is written when it is rendered.
NOTAG | Causes TraceDump tags to be ignored.
EXCHFILES | Enable saving a copy of the XML Exchange request/response files for each session in the trace directory.
NOEXCHFILES | Disables the tracing of XML Exchange request/response files.

If the FILE option is in effect, these options determine how the TRACE output is written to a file.

DIR=dir | dir specifies the directory that will receive trace output if FILE is in effect. If no dir is specified, this option has the same effect as NODIR. If a relative directory is specified for dir , output is written into a directory relative (on BIS/IIS) to the Windows temporary directory or (on BIS/Apache) to the /tmp directory. If an absolute path is specified for dir , output is written into that directory. On BIS/IIS, this directory must exist or the trace file will not be written. On BIS/Apache, the specified directory will be created if it does not exist.
NODIR | Disables the trace directory specified by DIR. If file output is enabled with either FILE or EXCHFILES then all trace output is written (on BIS/IIS) into the Windows temporary directory, or (on BIS/Apache) into /tmp.

The options below allow tracing to be controlled using a query parameter or a cookie:

QUERYPARAM=value

QP=value

QUERYPARAM and QP are synonymous and designate a URL query parameter whose value can be used to dynamically specify the options above. See the section The Trace Query Parameter for more information. Since the ability to dynamically configure the trace system is a potential security issue, the QUERYPARAM option allows you to specify your own query parameter name, rather than BIS supplying a standard one. This will make it harder for an unscrupulous person to obtain control of the tracing, but not impossible, so it is strongly suggested that the QUERYPARAM option not be left in the Trace tag of stencils files in production systems.
NOQUERYPARAM

NOQP

Disable the query parameter set by QUERYPARAM or QP.
IP=xx.xx.xx.xx [-x.xx.xx.xx]

IP=ipv6addr [- ipv6addr ]

IP allows trace output to be restricted to requests originating at one or more IP addresses. If an IP restriction is in effect, trace output is restricted exclusively to requests from those particular IP addresses. A comma-separated list of IP addresses or ranges may be specified. The list of IP restrictors is processed from left to right.

Note that specifying 127.0.0.1 will allow access from a web browser running on the host's console. In this case, access the pages using localhost as the name of the host.

IPv6 addresses may be specified instead of IPv4. For example, ::1 specifies the IPv6 loopback address, and on Windows Vista and Windows 2008 server, localhost resolves to this IPv6 address, while on older versions of Windows, localhost resolves to 127.0.0.1. IPv6 and IPv4 addresses may be mixed in a single IP statement, but not in a single range.

If either an IPv4 or IPv6 loopback address is specified (that is, 127.*.*.* or ::1), the setting applies to both IPv4 and IPv6 loopback addresses.

NOIP Disables the restriction of IP addresses.
  • Notes
  • Examples
  • The Trace Query Parameter
  • The BIS_TRACE_SUFFIX Environment Variable
Parent topic: Replacement Tag Reference


Notes

  • The default trace state is OFF. Note that if Trace(Start) is specified, trace accumulation begins/continues but trace information is not output until one or more output destinations (that is, PAGE, FILE, TAG, EXCHFILES) are specified.
  • The trace mode is part of the session and is sticky. This means that the trace setting persists in the session until it is changed by either another trace tag or a query parameter (if enabled). So if you have more than one page in your application, the trace tag is required only on your initial page.
  • Only .srf files may be traced. If you follow a link to an .htm or .asp page, those pages will not be traced. If those pages link back to a .srf file in this application's virtual directory, then tracing will once again resume as long as the session is still active.
  • Be cautious when enabling tracing in a way that exposes the trace information to site visitors. Trace information will reveal some information about your system that may be useful to intruders. The QUERYPARAM is configurable to help secure your web by allowing tracing to be turned on and off using a keyword that is not easily guessed by intruders.
Parent topic: The {{Trace}} Tag


Examples

{{ trace(page, file, notag, dir=bistrace, ip=127.0.0.1) }}

This Trace tag directs that trace output will be appended to every HTML page, and will also be written to the trace file in a directory named bistrace-note that, on Windows, this directory is relative to the Windows temporary directory, and must exist. The notag option causes TraceDump tags in the stencil file to be ignored and page trace output is only performed if the request originates on the server running BIS via the localhost alias (always 127.0.0.1).

Note that specifying 127.0.0.1 (or any IPv4 loopback address) also enables tracing from ::1 (the IPv6 loopback address), and vice-versa.

Parent topic: The {{Trace}} Tag


The Trace Query Parameter

If the QUERYPARAM option was specified in the Trace tag, it defines a query parameter that may be specified on the URL of a request by the client. If that query parameter is present, then its value will be parsed for trace options to use to configure the tracing. These options are, as with those specified by the Trace tag itself, persistent and will stay with the session until it completes, or a Trace tag or a trace query parameter alters it further.

For example, if the .srf contains the following tag:

{{ trace (QueryParam=ClientQuery) }}

Tracing will not occur for normal requests. However, the following request is made:

http://localhost/acubis10/samples/verify?ClientQuery=page

Page tracing will be turned on for the session, and tracing will be appended to the output for every subsequent request. See The BIS_TRACE_SUFFIX Environment Variable for another example.

Trace options set using the trace query parameter have the highest priority. Note that, for security, the query parameter cannot be used to set or clear IP restrictions or set the trace output directory.

Parent topic: The {{Trace}} Tag


The BIS_TRACE_SUFFIX Environment Variable

On BIS/IIS, the BIS_TRACE_SUFFIX environment variable and, on BIS/Apache, the BISTraceSuffix configuration parameter allows trace parameters to be injected into every trace statement. While this requires administrative access to the web server, this is useful for globally providing specific clients access to trace information.

For example, if your trace statements look like this:

{{ trace(page, noip) }}

and you wish to view trace data from the machine at 192.168.3.54, and control such tracing with the MySecretTrace query parameter, place this into the server environment:

BIS_TRACE_SUFFIX=ip=192.168.3.54,queryparam=MySecretTrace
  • This will effectively append these parameters to every Trace tag executed on the server without requiring the actual .srf file to be edited. Note that the .srf files must contain a Trace tag for this feature to take effect.
  • See Setting Environment Variables for information about setting and modifying environment variables on Windows. See Configuring Apache for information about setting Apache configuration parameters.
Parent topic: The {{Trace}} Tag


The {{TraceDump}} Tag

This tag directs BIS to output the contents of the trace buffer.

TraceDump
  • Notes
Parent topic: Replacement Tag Reference


Notes

  • This tag is ignored (that is, removed from the output) if tracing is not being performed.
  • Because trace information is accumulated as the page is rendered, it is most useful for the TraceDump tag to be specified near the end of the page.
  • If this tag is omitted and page tracing is enabled, BIS/IIS appends trace output to the end of the response (that is, after the </html> tag).
Parent topic: The {{TraceDump}} Tag


The {{Debug}} Tag

This tag enables or disables service engine debugging for the current session.

The Debug tag performs the following functions:

  • Determines if debugging will be enabled or disabled
  • Optionally specifies the addresses of the clients that are allowed to debug this session.

The syntax of the Debug tag:

{{Debug (option [,option]...}}

Options

ON Enables service program debugging in this session.

ON allows service programs that are subsequently created in the current session to be debugged.

OFF

Disables service program debugging in this session.

OFF prevents service programs created in this session from being debugged and clears the list of ID strings and IP restrictions.

TYPE | TYPE describes the type of debugging to invoke. This is an optional parameter. The default is the default for the runtime. For ACUCOBOL-GT, the valid values are xterm, term, and acuthin.
TYPEPARAM TYPEPARAM describes a parameter to be passed to the debugger when it is initiated. This optional parameter usually indicates the external source that will control the debugger.

For ACUCOBOL-GT, when TYPE is xterm, TYPEPARAM contains the xservername:displaynumber of the xterm or set to NULL to allow the xterm to use the default display DISPLAY environment variable.

When TYPE is term, TYPEPARAM contains tty device on which to send and receive commands.

When TYPE is acuthin, TYPEPARAM contains client where client is the name of the machine on which acuthin is executing and port is the port number on which it is listening.

QUERYPARAM

QP

QUERYPARAM and QP are synonymous and contains the name of a query parameter that can be used to dynamically specify debug parameters. Debug options set with QUERYPARAM will override those set in the DEBUG tag. However, for security reasons, the query parameter can only be used to turn debugging on and off.
IP=n.n.n.n [-n.n.n.n]

IP=n.n.n.n /n

IP=ipv6 [- ipv6 ]

IP=ANY|ALL

Restriction: This option is not currently supported in BIS/IIS for extend, but there is an alternative method detailed below.

Allows debugging to be restricted to requests originating from one or more IP address. If an IP address restriction is in effect, debug requests will only be accepted from clients that have IP addresses assigned within the restricted range. A space-separated list of IP addresses or ranges may be specified. The list of IP restrictors is processed from left to right.

If ANY or ALL is specified, requests from any IP may be debugged.

Note that specifying either 127.0.0.1 or ::1 will allow access from a web browser running on the host's console. In this case, access the pages using localhost, 127.0.0.1, or [::1] as the name of the host.

If the OFF action (above) is specified, the IP restriction list is cleared (same as IP=ANY), but any IP restrictions specified in the same or later tags will be processed and stored.

If either an IPv4 or IPv6 loopback address is specified (that is, 127.*.*.* or ::1), the setting applies to both IPv4 and IPv6 loopback addresses.

NOIP | Same as IP=ANY.

Notes:

While IP address restrictions are not currently supported in BIS/IIS for extend, it is possible to enable the {{Debug}} tag itself only for specific computers. For example, this block in the .srf file:

{{ if Value( REMOTE_ADDR, SERVER, TOLOWER,MATCH="^192.168.3.54$" ) }}
{{ Debug( On, Type=Acuthin,TypeParam=DebugHostMachine:5632 ) }}{{//}}
 {{ EndIf }}

Processes the {{Debug}} tag only for requests from 192.168.3.54. To restrict requests to localhost, specify 127.0.0.1 or ::1.

  • IIS Debugging Notes
  • Debugging on Windows
  • Debugging on UNIX
Parent topic: Replacement Tag Reference


IIS Debugging Notes

  • To enable debugging and clear all IDs and IP restrictions that may have been previously set for the current session, specify {{ Debug(OFF,ON) }}.
  • When a service is started and the debugging is enabled, the debugger will start running on the host machine's console. For this reason, it is desirable to restrict debugging to local host.
  • The Debug tag is always removed from the rendered page. If this is the last tag on the line, a newline is output unless this tag is immediately followed by a comment tag. See the Notes section of Comment Tags.
  • The Debug tag is ignored unless debugging is enabled in the BIS web server's configuration.
    Tip: To configure debugging for all pages, place the list of authorized users and IPs into the web.config file and add this tag to all of your .srf files:
    {{ Debug( ON,ID={%DEBUG_USERS, CONFIG%},IP={%DEBUG_IPS,CONFIG%} ) }}
{{ StartService( MAINPROGRAM ) }}
{{ Debug( OFF ) }}

    Then, create or edit the web.config file in the directory containing the .srf file (or any parent) and add the variables below:

    <app.config>
   <configuration>
        ...
      <configSections>
         <sectionGroup name="BIS">
            <sectionGroup name="Config">
               <section name="Variables"
    type="System.Configuration.NameValueSectionHandler,System"/>
            </sectionGroup>
         </sectionGroup>
      </configSections>
        ...
      <BIS>
         <PreRender>
               <add tag=”Debug(ON,ID=Users,IP=ANY” />
         </PreRender>
         <Config>
            <Variables>
               <add key="DEBUG_USERS" value="[spaced-list]"/>
               <add key="DEBUG_IPS" value="[spaced-list]"/>
                 ...
            </Variables>
         </Config>
      </BIS>
        ...
   </configuration>
</app.config>
  • Debug tags are processed in the order that they are encountered during rendering. This means that, in this example:
    {{ Debug( ON, IP=127.0.0.1 ) }}
{{ Debug( OFF ) }}
{{ StartService( MAINPROGRAM ) }}

    Debugging of MAINPROGRAM will be disabled. However, in this case:

    {{ Debug( ON, IP=127.0.0.1 ) }}
{{ StartService( MAINPROGRAM ) }}
{{ Debug( OFF ) }}

    Debugging of MAINPROGRAM will be. Subsequent programs will not be debugged unless an intervening {{ Debug(ON) }} is rendered and a new ID and optional IP restriction is set.

Parent topic: The {{Debug}} Tag


Debugging on Windows

Perform the following steps to debug with acuthin:
  1. On your Windows machine, navigate to the cobolgt\Debug\Win32\bin directory, and execute the following command:
    acuthin --wait --port 6000 --restart

    Where 6000 is the port number it is listening on.

  2. On your UNIX machine, in the SRF, create a tag that looks like this:
    {{ Debug(On, type=acuthin,
typeparam=my-client.microfocus.com:6000)
}}{{//}}

    Where my-client.microfocus.com is the name of the client machine on which acuthin is listening and 6000 is the port number that it is listening on.

When the service program starts, the debugger will appear on your Windows machine. Note that the request handler will only wait so long before it decides that the service will not take a request, so get to the B$ReadRequest as soon as possible.

Parent topic: The {{Debug}} Tag


Debugging on UNIX

Perform these steps to debug with xterm:
  1. Run your machine in X11 mode. Log into the X11 desktop and set the TYPEPARAM to be set to the DISPLAY parameter for the desktop, which is usually :0.0.
  2. Authorize the user ID that the service engine is running on, which will enable you to start a process that connects an X server. In a terminal window on the X session issue this command:
    xauth list $DISPLAY

    You should get output like this:

    xauth add tex-mikes-centos54/unix:0
MIT-MAGIC-COOKIE-1
5a823d65948333914f4bcc795cd283de
  3. Using a terminal emulator, log in to the account that the service engine will be running under. This will probably be root, not the UserName in /etc/xbis.conf. Then enter the command:
    xauth add tex-mikes-centos54/unix:0 MIT-
MAGIC-COOKIE-1
5a823d65948333914f4bcc795cd283de
  4. Copy the underlined parts from the xauth list to the xauth add.
Parent topic: The {{Debug}} Tag


Control Flow Tags

Control flow tags determine how Business Information Server processes a particular server response (.srf) file. These tags are similar to the "C" #if/#else/#endif and #include preprocessor macros.

There are two control flow tags:

  • If/Else/Endif that may be used to prevent a section of the file from being rendered.
  • While/ EndWhile that may be used to repeat a section of HTML code.
  • An Include tag that can be used to embed one stencil or into another.
  • The {{If}} / {{Else}} / {{EndIf}} Tags
  • The {{While}} / {{EndWhile}} Tags
  • The {{ Include }} Tag
  • {{//}} Comment Tags
Parent topic: Xcentrisity Business Information Server for extend User's Guide


The {{If}} / {{Else}} / {{EndIf}} Tags

These tags can be used to conditionally prevent sections of the stencil file from being rendered.

{{ if Value(parameters) }}
     if-content
{{ else }}
     else-content
{{ endif }}
  • Notes
Parent topic: Control Flow Tags


Notes

  • The Value parameters list has the same syntax as the parameters list for the Value tag: see The {{Value}} Tag. However, note that the parameters list must result in a TRUE/FALSE result, and must therefore contain a MATCH operation.
  • The definition of content includes both HTML/XML and replacement tags.
  • Any HTML/XML code in a skipped section is ignored and is not transmitted to the user agent. Server response file tags in a skipped section are ignored and are not evaluated.
  • No special flow layout is implied by this tag: the If, Else, and EndIf tags can be on one line, or can span multiple lines.
  • Blocks may be nested but must be completely nested. It is not permissible to place a While tag in an If block and have the EndWhile tag in a different block.
  • To render on an inverted condition, just omit the if-content: {{ if tag }}{{ else }} content {{ endif }}.
  • If the If / Else / EndIf tag is the last tag on a line, a newline will be added. If this tag is the only tag on the line, a blank line will be output. To avoid this, place a comment tag at the end of the line. For example, {{ EndIf }}{{//}}.
Parent topic: The {{If}} / {{Else}} / {{EndIf}} Tags


The {{While}} / {{EndWhile}} Tags

This tag can be used to omit or duplicate a section of HTML code.

{{ while Value(parameters) }}
     content
{{ endwhile }}
  • Notes
Parent topic: Control Flow Tags


Notes

  • The Value parameters list has the same syntax as the parameters list for the Value tag: see The {{Value}} Tag. However, note that the parameters list must result in a TRUE/FALSE result, and must therefore contain a MATCH operation.
  • The definition of content includes both HTML/XML and replacement tags.
  • No special flow layout is implied by this tag: the While and EndWhile tags can be on one line, or can span multiple lines. These blocks can also be nested.
  • A While block must be completely enclosed within another While block, or the true or false section of an If block. It is not permissible to use an If block to conditionally render an EndWhile tag unless the While tag is in the same block.
  • If the While / EndWhile tag is the last tag on a line, a newline will be added. If this tag is the only tag on the line, a blank line will be output. To avoid this, place a comment tag at the end of the line. For example, {{ EndWhile }}{{//}}.
Parent topic: The {{While}} / {{EndWhile}} Tags


The {{ Include }} Tag

This tag is replaced by the contents of the specified file.

include filepath

Where filepath is the path to a target file whose contents, when rendered, will replace the include tag. You may specify an absolute path or a path relative to the physical location of the .srf file that contains the Include tag.

If the target file is a server response file, and contains a handler tag, the target file is independently processed (rendered) in its own context, and this is recursively repeated for any tags in the target file. When rendering is complete, the rendered output replaces the Include tag.

If the target server response file does not contain a Handler tag, it is treated as a text file and replaces the Include tag without further processing. Any unresolved tags will not be processed, but will remain in the final response

  • Notes
Parent topic: Control Flow Tags


Notes

  • Relative pathnames in filepath are interpreted as relative to the location of the .srf file that contains the include tag. This is also true for any additional nested Include tags: the path is always relative to the server response file that is being processed.
  • If an included .srf file contains a StartService tag, the service program's working directory is the directory that contains the .srf file that rendered the tag.
  • The included file does not need to be a .srf file. For example, an .html file, a .css (cascading style sheet) file, or a .js (JavaScript) file can also be included, and in this case, the Include tag is simply replaced by the content of the specified file.
  • On BIS/IIS, an include tag can appear anywhere in a .srf file-even before the handler tag.
  • If an Include tag is the last tag on a line, it will be followed by a newline unless immediately followed by a comment tag.
Parent topic: The {{ Include }} Tag


{{//}} Comment Tags

This tag is ignored and is simply removed from the output. Comment tags differ from HTML comments, which remain in the output and can be viewed with the browser's View > Source command.

There are two ways to specify a BIS comment:

{{ // comment }}
{{ !-- comment }}
  • Notes
Parent topic: Control Flow Tags


Notes

  • A comment tag can appear anywhere in a server response file-even before the Handler tag.
  • If a comment tag is immediately followed by the end-of-line character, the newline character is removed with the comment tag. This is useful when placing tags into a file where white space is significant. For example, a server response file could be coded like this:
    {{//There must be no whitespace rendered before the exchange tag, }}
{{// hence the newline-eating comment tags }}
{{ Handler * }}
{{ Trace(start,queryparam=trace,ip=127.0.0.1) }}
{{ SetEnv(A_CONFIG=../common/cblconfig.txt) }}
{{ ServiceLibs(xmlif) }}

{{ StartService(webappsample2.acu) }}
{{ XMLExchange(OnExit="gotit.srf") }}

    Here, the Handler, Trace, SetEnv, ServiceLibs, and StartService tags are completely removed from the output, while the XMLExchange tag is replaced by the XML produced by the COBOL program. However, the new line character that follows each of these tags would remain in the output, resulting in four blank lines before the start of the XML produced by the XMLExchange tag.

    To avoid this in this sample, the non-comment Handler, SetEnv, ServiceLibs, and StartService tags are followed by empty comments, which suppress the newline characters. The XMLExchange tag is not followed by a newline-consuming comment because a newline is desirable before the end of the file and, in this case, the emitted XML does not contain any newline characters.

    {{//There must be no whitespace rendered before the exchange tag, }}
{{// hence the newline-eating comment tags }}
{{ Handler * }}{{//}}
{{ Trace(start,queryparam=trace,ip=127.0.0.1) }}{{//}}
{{ SetEnv(A_CONFIG=../common/cblconfig.txt) }}{{//}}
{{ ServiceLibs(xmlif) }}{{//}}

{{ StartService(webappsample2.acu) }}{{//}}
{{ XMLExchange(OnExit="gotit.srf") }}
    Here, the comment tags and the Handler, Trace, SetEnv, ServiceLibs, and StartService tags are completely removed from the output, while the XMLExchange tag is replaced by the XML produced by the COBOL program.
Parent topic: {{//}} Comment Tags


Service Programs

  • Introduction
  • Service Program Lifetime
  • The XML Exchange File
  • BIS Return Codes
  • Service Program Functions
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Introduction

The Service Engine is the BIS component that starts and runs service programs in response to requests. Currently, all BIS service programs are COBOL programs.

The Service Engine is started when a BIS StartService tag is rendered, and runs asynchronously from the BIS web components. BIS and the Service Engine synchronize when:

  1. BIS renders an XMLExchange tag, and
  2. The Service Engine calls B_ReadRequest.

The simplified flow of control is depicted below.

The BIS Request Handler and the BIS Service Engine synchronize when the Request Handler renders an XMLExchange tag and the Service Engine calls B_ReadRequest. Ideally, the Service Engine will be waiting at a synchronization point when the BIS Request Handler is ready to provide a request. To avoid deadlocks, once BIS begins to process the XMLExchange tag:

  • The service program must call the B_ReadRequest function within ServiceTimeout seconds.
  • Alternatively, the program may request additional time by calling B_SetServiceTimeout using 0 to reset the timer.

Once the Service Engine has accepted the request, it is granted a new ServiceTimeout interval to read the XML request, compute the response, write the XML response, and call B_WriteResponse. Alternatively, the service program can terminate, which causes the BIS Request Handler to redirect if an OnExit parameter was specified in the XMLExchange tag. If the response cannot be provided within this interval, the service program must request more time as described above.

When the BIS Request Handler receives the response, it is placed into the page output stream and processing continues. At this point, the Service Engine may:

  • Wait for the next request for the current session by calling B_ReadRequest.
  • Terminate (for example, with GOBACK.)

If the service program does neither of these, but instead keeps running, the Service Engine eventually terminates it with a Service Timeout.

Parent topic: Service Programs


Service Program Lifetime

A service program is started when BIS processes a StartService tag on a .srf page. A service program is considered to be finished when:

  • The program terminates by executing a GOBACK (or equivalent).
  • The program responds to a request by calling B_WriteResponse with an end program or end program and session disposition parameter (described in detail in BIS Return Codes).
  • A StopService tag is rendered. The service program is disconnected from the session, so a subsequent StartService can be processed on the same page.
  • A SessionComplete tag is rendered. The service program and session both end when the page is complete. Note that a StopService can also be specified if the service program must stop immediately.
  • The number of seconds specified in the InactivityTimeout pass without a request. Both the service program and the session are terminated.
  • An XMLExchange tag is rendered and the number of seconds specified in the ServiceTimeout interval pass without a response from the service program. If a service program needs a longer amount of time to complete processing, it should lengthen the ServiceTimeout interval by calling B_SetServiceTimeout(), or call this function with a parameter of zero to reset the timer.

The following general rules apply to service programs:

  • A given BIS session may have only one active service program at any time.
  • When a service program enters the termination state, it is immediately disconnected from the session but is given 30 seconds to clean up and perform a GOBACK. If the program is still running when the timer expires, BIS requests that the program stop at the next statement boundary and the service program is granted another 30 seconds to terminate. If, at the end of the allotted time the program has still not terminated, the process is forcibly terminated and unloaded from memory.

A new service program may be started as soon as the current service program is disconnected from the session. In other words, {{StopService}} {{StartService(…)}} is allowed.

  • ACCEPT and DISPLAY Statements
  • Windows Message Boxes and Dialog Boxes
Parent topic: Service Programs


ACCEPT and DISPLAY Statements

DISPLAY UPON SYSERR statements are allowed in service programs and the data that would normally display on the console is instead placed into the BIS trace output. This is a useful way to debug the service program but this technique cannot be used to communicate with clients.

Because the service program does not have access to the console or the Windows desktop, the behavior of ACCEPT and DISPLAYS that involve screen or terminal I/O is undefined and must be avoided.

Parent topic: Service Program Lifetime


Windows Message Boxes and Dialog Boxes

Because the service program does not have access to the Windows desktop, it is not appropriate to display a message box or a dialog box. If the service program did attempt to interact with the user in this way, it will suspend waiting for a response that cannot ever come. To avoid this problem, BIS detects that the service program is attempting to create a dialog or message box and denies the request.

Parent topic: Service Program Lifetime


The XML Exchange File

The Service Engine is started with a special parameter that specifies the name of the file that will be used for all XML exchange operations. The BIS Request Handler takes the current request, encodes it using XML, and places the request into this file when the service program calls B_ReadRequest. If desired, the B_ReadRequest can also pass the XML Exchange information strictly via memory.

Important: The file is not created until B_ReadRequest is called.

BIS places the fully qualified name of this file into the BIS_FILENAME environment variable when the Service Engine is started. The filename, therefore, is accessible to the COBOL program via the C$GetEnv function:

01 BIS-Exchange-File-Info.
   05 BIS-Exchange-File-Result    PIC 9 BINARY.
   05 BIS-Exchange-File-Name.
      10 FILLER                   PIC X OCCURS 200 TIMES.

CALL "C$GetEnv" USING "BIS_FILENAME",
                      BIS-Exchange-File-Name,
                      BIS-Exchange-File-Result.

On BIS/IIS, the value of this variable is the fully qualified pathname of the file and the filename has this form:

XMLExchange-hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh.xml

The file is created in the Windows TEMP directory. The h characters are replaced by hexadecimal digits, and the name is guaranteed to be globally unique.

On BIS/Apache, the value of this variable is the fully qualified pathname of the file and has this form:

bisiiiiiiiiiiiiiiiiiiiiii-ssss.xml

The file is created in the directory indicated by the Service Engine's TempDir configuration keyword. The i characters are replaced by the session's identifier and the s characters are replaced by a decimal number representing the number of the service within the session.

  • Notes
Parent topic: Service Programs


Notes

  • You do not provide this environment variable. BIS sets the environment variable when a service program is started and creates the file when B_ReadRequest is called.
  • A separate file is created for each service program, and the same file is used by
    • B_ReadRequest to receive requests from BIS.
    • B_WriteResponse to transmit responses to BIS.
  • While the filename is already known when the service engine is started, the file itself is not created until B_ReadRequest is called for the first time by the service program.
Parent topic: The XML Exchange File


BIS Return Codes

Here are the return codes for the B_ functions. These codes are defined in the bisdef.cpy COPY file provided in the samples/common directory. Note that the severity of an error condition increases with the value of the return code

00-09 Success! For B_ReadRequest, the request data is available in the XML exchange file. For B_WriteResponse, the response was accepted by the Request Handler.
  • 00 - BIS-Success: The data transfer succeeded and the XML file contains the result of the operation.
10-19 A non-fatal event occurred, and recovery is possible. While no such conditions currently exist, these codes are reserved for future use.
20-29 A failure occurred but the program should be able to recover. The states of the service program and request handler have not been affected by this operation.
  • 20 - BIS-Warn-RequestTimeExpired: A timeout parameter was specified on the B_ReadRequest call and the timeout expired. To avoid a potential race condition, the service program should not terminate when this occurs-instead, it can do some work and then reissue the request.
  • 21 -BIS-Warn-RequestOutstanding: A request has already been received by B_ReadRequest and the service program has not responded.

    This code is only returned by BIS/Apache; BIS/IIS recreates the exchange file and returns

    BIS_Success each time that B_ReadRequest is called for the same request.

  • 22 - BIS-Warn-ResponseUnexpected: The service program called B_WriteResponse without a pending request.
  • 23 - BIS-Warn-CallNotImplemented: A function was called that is not implemented in this version of BIS.
30-49 A failure occurred. The service program may attempt to recover, correct the problem and retry the operation. The state of the service program and request handler have not been affected by this operation.
  • 30 -BIS-Fail-FileOpen: BIS could not open the XML Exchange file.
  • 31 - BIS-Fail-FileRead: BIS could not read the XML Exchange file.
  • 32 - BIS-Fail-FileWrite:
  • 33 - BIS-Fail-FileClose: BIS could not close the XML Exchange file.
  • 34 - BIS-Fail-FileSize: The XML Exchange file size is too large to load into memory.
  • 39 - BIS-Fail-FileTraceFileIO: BIS could not open or write the trace file.
  • 49 - BIS-Fail-FileFormat: The XML Exchange file format is invalid.
50-79 A failure or possible planned session/service expiration event occurred and the program cannot continue. The XML exchange file was not updated and the program should terminate as soon as possible or BIS will terminate the program after the service timeout interval expires.
  • 50 - BIS-Fail-SessionAbandoned: The session timed out.
  • 51 - BIS-Fail-SessionComplete: The user logged out or ended the session. Note that this does not necessarily indicate a failure-a SessionComplete tag may have been processed.
  • 52 - BIS-Fail-ServiceComplete: The user logged out or ended the session. Note that this does not necessarily indicate a failure-a StopService tag may have been processed.
80-99 A serious error occurred. The XML exchange file was not updated and the program must terminate as soon as possible or BIS will terminate the program after the service timeout interval expires.
  • 80 - BIS-Fail-ServerUnavailable: The service program is not running in the BIS server environment.
  • 81 - BIS-Fail-ServerUnspecified: An unspecified error occurred while the service program was communicating with the BIS Request Handler.
  • 88 - BIS-Fail-ServerInternalError: An internal error occurred while the service program was communicating with the BIS Request Handler.
  • 89 - BIS-Fail-ServerMemoryManagement: A memory management failure occurred in the BIS service program.
  • 90 - BIS-Fail-ServerBadMessage: An internal error occurred while the service program was communicating with the BIS Request Handler.
  • 91 - BIS-Fail-ServerBadLength: An internal error occurred while the service program was communicating with the BIS Request Handler.
  • 92 - BIS-Fail-ServerBadParameter: An internal error occurred while the service program was communicating with the BIS Request Handler.
  • 93 - BIS-Fail-ServerWrongMsg: An internal error occurred while the service program was communicating with the BIS Request Handler.
  • 99 - BIS-Fail-ServerConnectionLost: The connection between the BIS service program and the BIS Request Handler failed.
Parent topic: Service Programs


Service Program Functions

The following COBOL-callable functions may be used in BIS service programs to communicate with BIS. They are detailed in the following sections.

  • B_ReadRequest
  • B_WriteResponse
  • B_SetInactivityTimeout
  • B_SetServiceTimeout
  • B_SetResponseStatus
Parent topic: Service Programs


B_ReadRequest

Note: For backward compatibility with products earlier than extend 10, use the B$ prefix to call the function, instead of B_. From extend 10 onwards, B$ is deprecated.

This function call retrieves the current BIS request for processing by the service program. The syntax of this function call is:

Call "B_ReadRequest" [using TimeoutInSeconds] giving BIS-Status.

When this function is called, execution of the service program is suspended until one of the following events occurs:

Event | Action
The BIS Request Handler renders an XMLExchange tag for the current session | This tag causes the current request data to be encoded into XML and placed into the file specified by the BIS_FILENAME environment variable.
The BIS Request Handler renders a StopService or SessionComplete tag for the current session | This indicates that the service is no longer required. The service program should terminate and is granted [ServiceTimeout] seconds to do so.
The optional TimeoutInSeconds parameter expires | This timeout allows the BIS service program to regain control and perform some work. When complete, the program should call B_ReadRequest again.
The InactivityTimeout period expires | This indicates that the end user has abandoned the session. The service program should terminate and is granted 30 seconds to do so.

The most common result codes are as follows (see BIS Return Codes for a complete table):

BIS-Status Code | Event Description
BIS-Success | A valid request was received.
BIS-Warn-RequestTimeExpired | The TimeoutInSeconds parameter was specified and no request was received before the time elapsed.
BIS-Warn-RequestOutstanding

A request is outstanding. The service program must write a response before another request can be received.

This code is only returned by BIS/Apache; BIS/IIS recreates the exchange file and returns BIS_Success each time that B_ReadRequest is called for the same request.

BIS-Fail-SessionAbandoned | Service termination is being requested because the BIS session inactivity time has elapsed without a request.
BIS-Fail-SessionComplete | Service termination is being requested because a StopService tag was rendered.
BIS-Fail-ServiceComplete | Service termination is being requested because a SessionComplete tag was rendered.

(These values are defined in file bisdef.cpy). Other codes may also be returned; see BIS Return Codes

When execution resumes and the result code is BIS-Success, the file specified by the BIS_FILENAME environment variable contains the request in XML format. The exact format of the request is described in Appendix B, XML Exchange Request File Format.

  • Notes
Parent topic: Service Program Functions


Notes

  • The BIS Service Engine starts the service timer when this function returns. The program is then given ServiceTimeout seconds to process the request and perform one of these actions:
    • Call B_WriteResponse
    • Call B_SetServiceTimeout. In particular, a value of 0 resets the timer and starts another ServiceTimeout interval.
    • Terminate the program.

    If the service program processes for more than the ServiceTimeout interval without performing one of the above functions, the BIS Service Engine assumes the service program is lost and begins termination processing (as if a StopService tag had been rendered).

  • If specifying the optional TimeoutInSeconds parameter and a request does not arrive within the specified amount of time, the function returns a BIS-Warn-RequestTimeExpired status code. The program can then perform some processing and either exit or reissue the B_ReadRequest.

    Specifying a timeout value

    of 0 causes this function to return immediately unless a request is waiting. The routine use of a timeout value of 0 to poll for requests is strongly discouraged as it may significantly impact server performance.

  • If TimeoutInSeconds is not specified, this function does not return until one of the other termination events occur (that is, the default timeout is infinite).
Parent topic: B_ReadRequest


B_WriteResponse

Note: For backward compatibility with products earlier than extend 10, use the B$ prefix to call the function, instead of B_. From extend 10 onwards, B$ is deprecated.

This function call transmits a response to the BIS Request Handler to be inserted into the output stream, replacing the XMLExchange tag in the output stream. The response must be written into the request file (specified by the BIS_FILENAME environment variable) before B_WriteResponse is called unless session or service termination is being requested-in this case, the response is optional (see below).

The response file typically contains an requested HTML or XML that is inserted into the .srf file. It may also contain a SOAP result or anything else that is meaningful to the client program that issued the request.

The syntax of this function call is:

Call "B_WriteResponse"
   [using ProgramDisposition]
    giving BIS-Status.

If this is the final call to B_WriteResponse by this service, the optional ProgramDisposition parameter may be used to indicate that the service program is finished, if the session should be destroyed, and if there is a payload that should be rendered into the response. Here are the values:

 78 BIS-Response-Normal                    Value 0. *> Default normal response
 78 BIS-Response-ServiceComplete           Value 1. *> End program only
 78 BIS-Response-SessionComplete           Value 2. *> End program and session
*78*BIS-Response-RecycleService            Value 3. *> RESERVED FOR FUTURE USE

The ProgramDisposition codes descriptions are as follows:

BIS-Status Code Event Description
BIS-Response-Normal

The default is that BIS makes no assumptions about what the service program will do next. However, the service program is granted only 30 seconds to exit or to read the next request.

This response always requires a valid XML exchange file. If the file has not been updated with a response, or has been deleted, this function will return BIS-Fail-FileNotChanged.

BIS-Response-ServiceComplete BIS assumes that the service has completed processing and longer needs to interact with the session.
  • If the XML exchange file has been updated since the last call to B_ReadRequest, BIS writes the response into the output and does not redirect to the OnExit parameter of the XMLExchange tag.
  • If the XML response file has not been updated or has been deleted, and there is an OnExit parameter in the XMLExchange tag, BIS redirects to the specified page.
  • If the XML response file has not been updated or has been deleted and there is no OnExit parameter in the XMLExchange tag, BIS writes nothing, but removes the XMLExchange tag from the output.

In all cases, the service program disconnects from the session and has 30 seconds to run to completion in the background. If the service program subsequently calls B_ReadRequest it receives a BIS-Fail-ServiceComplete error status.

The session is not destroyed by this response, and if a StartService tag is executed before the session expires, the new service program runs under the current session. The session can be terminated if the page requested by OnExit is a stencil and contains a SessionComplete tag.

This disposition option is logically the same as processing a StopService tag in the requesting stencil or in the XML response.

BIS-Response-ServiceComplete-NoPayload

Same as BIS-Response-ServiceComplete (see above), except the XML exchange response file is always ignored.

  • If there is an OnExit parameter in the XMLExchange tag, BIS redirects to the specified page.
  • If there is no OnExit parameter in the XMLExchange tag, BIS renders nothing and removes the XMLExchange tag from the output.
BIS-Response-SessionComplete BIS assumes that the both the service complete and no longer complete and no longer needed.
  • If the XML exchange file has been updated since the last call to B_ReadRequest, BIS writes the response to the output and does not redirect to the OnExit parameter of the XMLExchange tag.
  • If the XML response file has not been updated or has been deleted, and there is an OnExit parameter in the XMLExchange tag, BIS redirects to the specified page.
  • If the XML response file has not been updated or has been deleted and there is no OnExit parameter in the XMLExchange tag, BIS writes nothing and removes the XMLExchange tag from the output.

In all cases, the service program and the session are both disconnected (becoming inaccessible to subsequent requests) and the service program disconnects from the session and has 30 seconds to run to completion in the background.. If the service program subsequently calls B_ReadRequest it receives a BIS-Fail-SessionComplete error status.

Once the service program terminates, the session is destroyed. If another request is received, a new session is created to process the request.

This is logically the same as processing a SessionComplete tag in the requesting stencil or in the XML response.

BIS-Response-SessionComplete-NoPayload

Same as BIS-Response-SessionComplete (see above), except the XML exchange response file is always ignored.

  1. If there is an OnExit parameter in the XMLExchange tag, BIS will redirect to the specified page.
  2. If there is no OnExit parameter in the XMLExchange tag, BIS writes nothing and removes the XMLExchange tag from the output.
BIS-Response-RecycleService

BIS-Response-RecycleService-NoPayload

Reserved for future use.

The BIS-Status result field and the result codes are defined in bisdef.cpy. Here are the most common return codes:

BIS-Status Code | Event Description
BIS-Success | The BIS Request Handler accepted the response. This does not mean that it was delivered to the user agent. However, the service program should presume success and resume processing.
BIS-Warn-ResponseUnexpected | There is no pending request to respond to.
BIS-Fail-FileNotChanged | The XML exchange file was not written and still contains the request. Note that this code is only returned for the BIS-Response-Normal disposition code, as the exchange file need not be updated if the service or session are terminating.
  • Notes
Parent topic: Service Program Functions


Notes

  • Unlike B_ReadRequest, this call returns as soon the BIS Request Handler accepts the output file. This function call does not block waiting for a response from BIS.
  • After writing a response, the service program will normally either call B_ReadRequest or terminate.
  • The BIS Service Engine starts the service timer when this function returns. The program has 30 seconds to perform one of these actions:
    • Call B_ReadRequest.
    • Call B_SetServiceTimeout. A parameter of 0 restarts the service timer.
    • Terminate.

    If the service program processes for more than 30 seconds without performing one of the above functions, the BIS Service Engine assumes the service program is lost and begins termination processing (as if a StopService tag had been rendered).

  • Other codes may also be returned, but that normally indicates a serious problem has occurred.
  • By default, the response is sent back to the client with the HTTP status of OK, which is the value 200. However, the function B_SetResponseStatus may be used to alter the HTTP status returned.
Parent topic: B_WriteResponse


B_SetInactivityTimeout

Note: For backward compatibility with products earlier than extend 10, use the B$ prefix to call the function, instead of B_. From extend 10 onwards, B$ is deprecated.

This function allows the service program to control the length of time that BIS waits for a request before considering a session to be abandoned.

A timer is started in a session when each request is processed for that session. If a new request is not received before the timer elapses, any active services in that session are terminated and the session is terminated.

If a request is subsequently received for a terminated session, BIS creates a new session.

The syntax of this function call is:

Call "B_SetInactivityTimeout" using TimeoutInSeconds giving BIS-Status.

where TimeoutInSeconds may be:

  • The actual number of seconds this session waits for a new request. Valid values range from 10 to 3600 seconds. All values out of this range other than 0 are treated as if -1 was specified.
  • 0 to restart the inactivity timer without changing the number of seconds allowed between requests.
  • -1 to reset the timeout value to the default value of 600 seconds or 10 minutes.

The BIS-Status result field and the result codes are defined in BISDEF.CPY. Here are the most common return codes:

 | Event Description
BIS-Success | The call is successful.
BIS-Fail-SessionAbandoned | Service termination is already being requested because the BIS session inactivity timeout period has elapsed without a request. This function call has no effect.
BIS-Fail-SessionComplete | Service termination is requested because a SessionComplete tag was rendered. This function call had no effect.
BIS-Fail-ServiceComplete | Service termination is requested because a StopService tag was rendered. This function call had no effect.
  • Notes
Parent topic: Service Program Functions


Notes

  • The default inactivity timeout period is 600 seconds (10 minutes). Session Inactivity Timeout describes how to change the default for all BIS sessions on this server.
  • The inactivity timeout can also be set in a .srf file with the SessionParms tag.
  • All calls to this function restart the timer. Specify 0 to restart the timer without changing the value currently in effect.
  • BIS/IIS defers processing this function until an XMLExchange tag is processed. The main implication of this restriction is that if the client starts the program and then browses pages that do not include an XMLExchange tag while the program calls B_SetInactivityTimeout() followed by B_ReadRequest(), the updated inactivity timeout interval does not take effect until an XMLExchange tag is processed. This is an unlikely scenario because there is no reason to start a service program if an XMLExchange tag is not imminent.
Parent topic: B_SetInactivityTimeout


B_SetServiceTimeout

Note: For backward compatibility with products earlier than extend 10, use the B$ prefix to call the function, instead of B_. From extend 10 onwards, B$ is deprecated.

This function allows the service program to control the length of time that the service program is permitted to run without interacting with BIS.

The service timer is reset when:

  • The service program is started.
  • The service program calls any B_ function.

If the timer elapses, the service program is terminated. The default service timeout interval is 30 seconds.

The syntax of this function call is:

Call "B_SetServiceTimeout" using TimeoutInSeconds giving BIS-Status.

where TimeoutInSeconds may be:

  • The actual number of seconds allowed between calls to BIS B_ functions. Note that the value may range from 10 to 3600 seconds (1 hour). All values out of this range other than 0 are treated as if -1 was specified.
  • 0 to restart the service timer without changing the number of seconds allowed between calls to B_ functions.
  • -1 to reset the timeout value to the default value of 30 seconds.

The BIS-Status result field and the result codes are defined in BISDEF.CPY. Here are the most common return codes:

BIS-Status Code | Event Description
BIS-Success | The call was successful.
BIS-Fail-SessionAbandoned | Service termination is already being requested because the BIS session inactivity time has elapsed without a request. This function call had no effect.
BIS-Fail-SessionComplete | Service termination is already being requested because a SessionComplete tag was rendered. This function call had no effect.
BIS-Fail-ServiceComplete | Service termination is already being requested because a StopService tag was rendered. This function call had no effect.
  • Notes
Parent topic: Service Program Functions


Notes

  • The default service timeout period is 30 seconds. The section titled Service Timeouts describes how the default may be changed for all BIS services on this server.
  • The service timeout may also be set in a .srf file with the SessionParms tag.
  • All calls to this function will restart the timer. Specify 0 to restart the timer without changing the value currently in effect.
  • BIS/IIS defers processing of this function until an XMLExchange tag is processed. The main implication of this restriction is that if the client starts the program and then browses pages that do not include an XMLExchange tag while the program calls B_SetServiceTimeout() then B_ReadRequest(), the updated service timeout interval does not take effect until an XMLExchange tag is processed. This is an unlikely but possible scenario because there is no reason to start a service program if an XMLExchange tag is not imminent.
Parent topic: B_SetServiceTimeout


B_SetResponseStatus

Note: For backward compatibility with products earlier than extend 10, use the B$ prefix to call the function, instead of B_. From extend 10 onwards, B$ is deprecated.

This function allows the service program to control the HTTP status that is returned with a response. By default, the response status will be 200, which is an HTTP status of OK. However, if it is desirable to return a different status, this function may be used to alter the status for the next response. Subsequent responses return OK again unless B_SetResponseStatus is called before B_WriteResponse.

The syntax of this function call is:

Call "B_SetResponseStatus" using ResponseStatus giving BIS-Status.

where ResponseStatus may be:

  • An HTTP status code detailed at http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1. In general, one of the 200, 300 or 400 codes should be used to indicate the result of the operation. Avoid the 500 codes . They are for errors detected by the web server.
  • The following table describes the HTTP status codes specified in RFC 2616, their status names, and a synopsis of the RFC 2616 description.
Status Code | Status Name | HTTP Standard Description
1xx Informational This class of status code indicates a provisional response, consisting only of the Status-Line and optional headers, and is terminated by an empty line. There are no required headers for this class of status code.

A client must be prepared to accept one or more 1xx status responses prior to a regular response, even if the client does not expect a 100 (Continue) status message. Unexpected 1xx status responses may be ignored by a user agent.

100 Informational The client should continue with its request. This interim response is used to inform the client that the initial part of the request has been received and has not yet been rejected by the server. The client should continue by sending the remainder of the request or, if the request has already been completed, ignore this response. The server must send a final response after the request has been completed.

This status code is generated by the web server directly and should not be returned by the service program.

101 Switching Protocols The server understands and is willing to comply with the client's request, via the Upgrade message header field, for a change in the application protocol being used on this connection. The server will switch protocols to those defined by the response's Upgrade header field immediately after the empty line which terminates the 101 response.

This status code is generated by the web server directly and should not be returned by the service program.

2xx | Successful | This class of status code indicates that the client's request was successfully received, understood, and accepted.
200 | OK | The request has succeeded. The information returned with the response is dependent on the method used in the request.
201 | Created | The request has been fulfilled and resulted in a new resource being created. The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field. The response should include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. The origin server must create the resource before returning the 201 status code. If the action cannot be carried out immediately, the server should respond with 202 (Accepted) response instead.
202 Accepted The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for resending a status code from an asynchronous operation such as this.

The 202 response is intentionally non-committal. Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent's connection to the server persist until the process is completed. The entity returned with this response should include an indication of the request's current status and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.

203 | Non-Authoritative Information | The returned meta information in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy. The set presented may be a subset or superset of the original version. For example, including local annotation information about the resource might result in a superset of the meta information known by the origin server. Use of this response code is not required and is only appropriate when the response would otherwise be 200 (OK).
204 No Content The server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta information. The response may include new or updated meta information in the form of entity-headers, which if present should be associated with the requested variant.

If the client is a user agent, it should not change its document view from that which caused the request to be sent. This response is primarily intended to allow input for actions to take place without causing a change to the user agent's active document view, although any new or updated metadata should be applied to the document currently in the user agent's active view.

The 204 response must not include a message-body, and thus is always terminated by the first empty line after the header fields.

205 | Reset Content | The server has fulfilled the request and the user agent should reset the document view which caused the request to be sent. This response is primarily intended to allow input for actions to take place via user input, followed by a clearing of the form in which the input is given so that the user can easily initiate another input action. The response must not include an entity.
206 | Partial Content | The server has fulfilled the partial GET request for the resource.
3xx | Redirection | This class of status code indicates that further action needs to be taken by the user agent in order to fulfill the request. The action required may be carried out by the user agent without interaction with the user if and only if the method used in the second request is GET or HEAD. A client should detect infinite redirection loops, since such loops generate network traffic for each redirection.
300 Multiple Choices The requested resource corresponds to any one of a set of representations, each with its own specific location, and agent- driven negotiation information is being provided so that the user (or user agent) can select a preferred representation and redirect its request to that location.

Unless it was a HEAD request, the response should include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. Depending upon the format and the capabilities of the user agent, selection of the most appropriate choice may be performed automatically. However, this specification does not define any standard for such automatic selection.

If the server has a preferred choice of representation, it should include the specific URI for that representation in the Location field; user agents may use the Location field value for automatic redirection. This response can be cached unless otherwise indicated.

301 Moved Permanently The requested resource has been assigned a new permanent URI and any future references to this resource should use one of the returned URIs. Clients with link editing capabilities ought to automatically re-link references to the Request-URI to one or more of the new references returned by the server, where possible. This response can be cached unless otherwise indicated.

The new permanent URI should be given by the Location field in the response. Unless the request method was HEAD, the entity of the response should contain a short hypertext note with a hyperlink to the new URI(s).

If the 301 status code is received in response to a request other than GET or HEAD, the user agent must not automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued.

302 Found The requested resource resides temporarily under a different URI. Since the redirection might be altered on occasion, the client should continue to use the Request-URI for future requests. This response can only be cached if indicated by a Cache-Control or Expires header field.

The temporary URI should be given by the Location field in the response. Unless the request method was HEAD, the entity of the response should contain a short hypertext note with a hyperlink to the new URI(s).

If the 302 status code is received in response to a request other than GET or HEAD, the user agent must not automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued.

303 See Other The response to the request can be found under a different URI and should be retrieved using a GET method on that resource. This method exists primarily to allow the output of a POST-activated script to redirect the user agent to a selected resource. The new URI is not a substitute reference for the originally requested resource. The 303 response must not be cached, but the response to the second (redirected) request may be cached.

The different URI should be given by the Location field in the response. Unless the request method was HEAD, the entity of the response should contain a short hypertext note with a hyperlink to the new URI(s).

304 | Not Modified | If the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server should respond with this status code. The 304 response must not contain a message-body, and thus is always terminated by the first empty line after the header fields.
305 | Use Proxy | The requested resource must be accessed through the proxy given by the Location field. The Location field gives the URI of the proxy. The recipient is expected to repeat this single request via the proxy. 305 responses must only be generated by origin servers.
306 | (unused) | The 306 status code was used in a previous version of the specification, is no longer used, and the code is reserved.
307 Temporary Redirect The requested resource resides temporarily under a different URI. Since the redirection may be altered on occasion, the client should continue to use the Request-URI for future requests. This response can only be cached if indicated by a Cache-Control or Expires header field.

The temporary URI should be given by the Location field in the response. Unless the request method was HEAD, the entity of the response should contain a short hypertext note with a hyperlink to the new URI(s) , since many pre-HTTP/1.1 user agents do not understand the 307 status. Therefore, the note should contain the information necessary for a user to repeat the original request on the new URI.

If the 307 status code is received in response to a request other than GET or HEAD, the user agent must not automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued.

4xx Client Error The 4xxclass of status code is intended for cases in which the client seems to have erred. Except when responding to a HEAD request, the server should include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents should display any included entity to the user.

If the client is sending data, a server implementation using TCP should be careful to ensure that the client acknowledges receipt of the packet(s) containing the response, before the server closes the input connection. If the client continues sending data to the server after the close, the server's TCP stack will send a reset packet to the client, which may erase the client's unacknowledged input buffers before they can be read and interpreted by the HTTP application.

400 | Bad Request | The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.
401 | Unauthorized | The request requires user authentication. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource. The client may repeat the request with a suitable Authorization header field. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. If the 401 response contains the same challenge as the prior response, and the user agent has already attempted authentication at least once, then the user should be presented the entity that was given in the response, since that entity might include relevant diagnostic information.
402 | Payment Required | This code is reserved for future use.
403 | Forbidden | The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it should describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.
404 | Not Found | The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent. The 410 (Gone) status code should be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.
405 | Method Not Allowed | The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response must include an Allow header containing a list of valid methods for the requested resource.
406 Not Acceptable The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

Unless it was a HEAD request, the response should include an entity containing a list of available entity characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. Depending upon the format and the capabilities of the user agent, selection of the most appropriate choice may be performed automatically. However, this specification does not define any standard for such automatic selection.

If the response could be unacceptable, a user agent should temporarily stop receipt of more data and query the user for a decision on further actions.

407 | Proxy Authentication Required | This code is similar to 401 (Unauthorized), but indicates that the client must first authenticate itself with the proxy. The proxy must return a Proxy-Authenticate header field containing a challenge applicable to the proxy for the requested resource. The client may repeat the request with a suitable Proxy-Authorization header field.
408 | Request Timeout | The client did not produce a request within the time that the server was prepared to wait. The client may repeat the request without modifications at any later time.
409 Conflict The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body should include enough information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required.

Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the entity being PUT included changes to a resource which conflict with those made by an earlier (third-party) request, the server might use the 409 response to indicate that it can't complete the request. In this case, the response entity would likely contain a list of the differences between the two versions in a format defined by the response Content-Type.

410 Gone The requested resource is no longer available at the server and no forwarding address is known. This condition is expected to be considered permanent. Clients with link editing capabilities should delete references to the Request-URI after user approval. If the server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 (Not Found) should be used instead. This response can be cached unless indicated otherwise.

The 410 response is primarily intended to assist the task of web maintenance by notifying the recipient that the resource is intentionally unavailable and that the server owners desire that remote links to that resource be removed. Such an event is common for limited-time, promotional services and for resources belonging to individuals no longer working at the server's site. It is not necessary to mark all permanently unavailable resources as gone or to keep the mark for any length of time -- that is left to the discretion of the server owner.

411 | Length Required | The server refuses to accept the request without a defined Content- Length. The client may repeat the request if it adds a valid Content-Length header field containing the length of the message-body in the request message.
412 | Precondition Failed | The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server. This response code allows the client to place preconditions on the current resource meta information (header field data) and thus prevent the requested method from being applied to a resource other than the one intended.
413 Request Entity Too Large The server is refusing to process a request because the request entity is larger than the server is willing or able to process. The server may close the connection to prevent the client from continuing the request.

If the condition is temporary, the server should include a Retry- After header field to indicate that it is temporary and after what time the client may try again.

414 | Request-URI Too Long | The server is refusing to service the request because the Request-URI is longer than the server is willing to interpret. This rare condition is only likely to occur when a client has improperly converted a POST request to a GET request with long query information, when the client has descended into a URI black hole of redirection (e.g., a redirected URI prefix that points to a suffix of itself), or when the server is under attack by a client attempting to exploit security holes present in some servers using fixed-length buffers for reading or manipulating the Request-URI.
415 | Unsupported Media Type | The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
416 Requested Range Not Satisfiable A server should return a response with this status code if a request included a Range request-header field, and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If-Range request-header field. (For byte-ranges, this means that the first- byte-pos of all of the byte-range-spec values were greater than the current length of the selected resource.)

When this status code is returned for a byte-range request, the response should include a Content-Range entity-header field specifying the current length of the selected resource. This response must not use the multi-part/byteranges content-types.

417 | Expectation Failed | The expectation given in an Expect request-header field could not be met by this server, or, if the server is a proxy, the server has unambiguous evidence that the request could not be met by the next-hop server.
5xx Server Error Response status codes beginning with the digit 5 indicate cases in which the server is aware that it has erred or is incapable of performing the request. Except when responding to a HEAD request, the server should include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. User agents should display any included entity to the user. These response codes are applicable to any request method.

In general, these error codes are generated by HTTP server itself, and the service program should not use them.

500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request.
501 | Not Implemented | The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.
502 | Bad Gateway | The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.
503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay may be indicated in a Retry-After header. If no Retry-After is given, the client should handle the response as it would for a 500 response.
504 | Gateway Timeout | The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.
505 | HTTP Version Not Supported | The server does not support, or refuses to support, the HTTP protocol version that was used in the request message. The server is indicating that it is unable or unwilling to complete the request using the same major version as the client, other than with this error message. The response should contain an entity describing why that version is not supported and what other protocols are supported by that server.

The BIS-Status result field and the result codes are defined in BISDEF.CPY. Here are the most common return codes:

BIS-Status Code | Event Description
BIS-Success | The call was successful.
  • Notes
Parent topic: Service Program Functions


Notes

  • In general, a SOAP-base web service should imbed its response status inside the SOAP response and let the Request Handler manage the HTTP Status.
  • This function call is of most use to a REST-based web service where using the native URL and status codes of HTTP are encouraged.
  • Many of the status codes are intended to control the interaction of the web server and a browser and the code may be used safely to communicate between the service program and a web client. Other codes are intended for consumption by proxy servers (or are intended to be generated by them) and should be avoided.
  • The table of status codes is given here as a reference and is not intended to be a substitute for RFC 2616.
Parent topic: B_SetResponseStatus


BIS Tutorial

  • Prerequisites
  • Introduction
  • What is a web service?
  • Create a simple SOAP/RPC web service
  • Intro to XML Extensions
  • How XSLT processes a SOAP response (high level only)
  • Data flow in BIS
  • BIS Session management
  • Complex design pattern
  • Not quite web service
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Prerequisites

This tutorial has several prerequisites. Make sure you have the following available before proceeding.

  • XML Extensions reference documentation may be found in A Guide to Interoperating with ACUCOBOL-GT, Working with Non-Vision Data.
  • Xcentrisity Business Information Server (BIS) must be installed and operating correctly, as demonstrated by the verification and samples operating correctly.
  • Xcentrisity Business Information Server reference documentation is installed in the Docs\BIS subdirectory of the extend installation directory. This document can also be accessed by choosing Start > All Programs > extend x.x.x > Business Information Server. Note that a PDF viewer is required.
  • The tutorial1.zip file, which is located in %PUBLIC%\documents\micro focus\extend x.x.x\AcuGT\sample\BIS directory on Windows and in .../sample/acubis10/tutorial on UNIX/Linux. Unzip this file into a subdirectory named tutorial1. The tutorial examples, as delivered, create trace information (see the BIS reference documentation for the The {{Trace}} Tag). The trace information is placed in a top level directory named /tmp . If this directory does not exist, either create the directory with permissions that allow BIS to create files in the directory, or edit the tutorial1.srf, tutorial2.srf and tutorial3.srf files to save the trace information in a directory of your choice.
  • A web services client is necessary for testing web services. This tutorial uses soapUI, which may be found at www.soapui.org, as well as Microsoft Visual Studio. Download and install soapUI as a minimum test client.
Parent topic: BIS Tutorial


Introduction

The goal of this tutorial is to provide an introduction to the terminology of web services, to present current technology choices facing the software designer when creating web services, and to demonstrate practical design patterns for web services implemented in ACUCOBOL-GT.

Providing web services involves the use of several technologies: HTTP servers (also known as web servers), XML, and client-server architecture. While successful use of Xcentrisity BIS does not require becoming an expert in any of these technologies, you are encouraged to become familiar with them through the use of online or printed tutorials or reference material.

Parent topic: BIS Tutorial


What is a web service?

Web services are application services, typically combining data and procedural aspects, that are made available over a network such as the internet or an intranet. These services are described in terms of application programming interfaces (API) or web APIs that can be accessed over a network and executed on a remote system hosting the requested services.

A detailed description of web services is beyond the scope of this document. The term web services often includes formal W3C specifications such as SOAP along with less formal, but well described, services such as REST, and even rich internet application (RIA) technologies such as AJAX. This document describes more formal web services, SOAP and REST, with a brief consideration of RIA techniques.

  • The role of HTTP in web services
  • SOAP versus REST
  • SOAP binding style - RPC versus Document
  • WSDL
Parent topic: BIS Tutorial


The role of HTTP in web services

The familiar Hypertext Transfer Protocol (HTTP) is most often associated with the World Wide Web. This is one of the transfer protocols in use on the internet. Others include File Transfer Protocol (FTP) and Simple Mail Transfer Protocol (SMTP). HTTP is by far the most used transport protocol for web services, and it plays a crucial role in REST.

Xcentrisity® Business Information Server (BIS) is an application server that plugs in to the two most popular HTTP servers, Microsoft IIS and the Apache HTTP Server. BIS receives requests from and supplies responses to web-based 'user agents'. BIS is described in more detail later.

The HTTP specification describes messages that represent requests from a client to a server and responses from a server to a client. A message from a client to a server indicates a method (i.e., an action) that is desired for a specific resource designated by a URI, (Universal Resource Identifier). URIs are simply formatted strings which identify by name, location or some other characteristic, a resource located on the internet.

HTTP methods include GET, PUT, POST, DELETE, HEAD, TRACE, and CONNECT. To create web services using BIS, only the first four methods are important. The last three methods are handled by the HTTP server above (in architectural terms) the BIS service programs.

Parent topic: What is a web service?


SOAP versus REST

Web Services fall into two architectural styles, SOAP and REST.

SOAP, originally defined as Simple Object Access Protocol but now simply SOAP, is a formal specification for the exchange of structured information via Web Services. It relies on XML for its message format, and uses HTTP (which is really an application layer protocol) as its transport protocol. Historically, HTTP was the mechanism used to get through firewalls (since almost all firewalls allow HTTP traffic to pass through) and remains in use today. Note also that HTTPS may also be used, since HTTP and HTTPS are identical at the application layer. The XML based message format consists of three parts: - , and a convention for representing procedure calls and responses.

  • An envelope, which defines what is in the message and how to process it.
  • A set of encoding rules for expressing instances of application-defined data types.
  • A convention for representing procedure calls and responses.

Representational State Transfer (REST) is not a formal specification, but a style of software architecture for distributed hypermedia systems. For example, the World Wide Web is considered a REST system. The term Representational State Transfer was defined by Roy Fielding in 2000 in his doctoral dissertation. REST was initially described in terms of the HTTP application layer protocol (Fielding was one of the principal authors of the HTTP specification) but is not limited to HTTP.

REST uses the HTTP methods as its verbs to implement a create/read/update/delete model for resources described by URIs. In particular, the HTTP GET method is a read-only access to a resource, PUT is a create request, POST is update, and DELETE is delete. There are additional constraints on a (so-called) REST-ful system, of which statelessness is the most pertinent to the programmer using BIS.

Proponents of REST consider REST to be superior to SOAP for several reasons:

  • REST makes consistent use of the HTTP methods, whereas SOAP uses only POST, although a GET on a service endpoint URL is interpreted as a request for the WSDL that describes the service. SOAP overloads the POST method which obscures the nature of a request. This interferes with caching and other performance related techniques used on the web.
  • Similarly, REST uses URIs to identify the unique resource being affected by a request. SOAP uses a single URI to identify a 'service endpoint' and describes the resource being affected by a request somewhere in the body of the request. As described above, this interferes with web performance techniques.
  • SOAP is tied to XML, and is considered by some to be wordy. However, modern HTTP servers have built-in compression capability which may counteract this disadvantage for SOAP.
  • REST can be associated with just about any web resource, whether XML-based or not. Remember that the World Wide Web is REST-ful.

Whether to use SOAP or REST in creating BIS service programs is probably decided by requirements external to the application system that cannot be considered in this tutorial. However, it is important to remember that Xcentrisity BIS provides the flexibility to participate in HTTP-based systems of either architecture.

Parent topic: What is a web service?


SOAP binding style - RPC versus Document

There are additional design considerations when using SOAP web services. SOAP, as a specification created by committee, has several possible variations known as bindings. The two main variations are called RPC/encoded and Document/literal, with the latter being extended to Document/literal wrapped.

The Remote Procedure Call (RPC) pattern is used when the consumer views the web service as a single logical application or component with encapsulated data. The request and response messages map directly to the input and output parameters of the procedure call. Examples of this type the RPC pattern might include a payment service or a stock quote service.

The document-based pattern is used in situations where the consumer views the web service as a longer running business process where the request document represents a complete unit of information. This type of web service may involve human interaction for example as with a credit application request document with a response document containing bids from lending institutions. Because longer running business processes may not be able to return the requested document immediately, the document-based pattern is more commonly found in asynchronous communication architectures. The Document/literal variation of SOAP is used to implement the document-based web service pattern.

The RPC/encoded SOAP variation was the initial SOAP mechanism to implement the RPC design pattern. However, inefficiencies and other difficulties in large scale enterprise systems have led to RPC/encoded falling into disuse; it is most likely that eventually this variation will be deprecated by the web standardization committee responsible. A form of the Document/literal variation called document/literal wrapped is now the de facto standard for RPC pattern web services.

Parent topic: What is a web service?


WSDL

WSDL (which stands for Web Services Definition Language or Web Services Description Language) is an XML-based language for describing and locating web services. WSDL is a World Wide Web Consortium recommendation. The term WSDL is often used to mean the description of a specific web service, as in, The WSDL for that web service describes three web service methods, or referring generically to a document implemented in WSDL.

The WSDL document describes a web service using these major elements:

  • <types> - a description of the data elements and type(s) used by the web service;
  • <message> - a description of the data used by each operation available in the web service;
  • <portType> - a description of the operations performed by the web service; and
  • <binding> - a description of the message format and communication protocols used for each <portType>.
In the RPC pattern:
  • The <portType> element describes the functions, or methods, that are available in the web service.
  • The <message> section describes the input and output parameters.
  • The <types> section describes those parameters.
It is not unusual for RPC pattern WSDLs to be derived from underlying functions in standard programming languages, the so-called bottom-up approach.

In the document-based pattern, WSDLs are often developed by system architects using a top-down approach, before any implementation of the service or the clients of the service. Any documents exchanged are typically designed before the WSDLs that use them. These documents are described using XML Schema, another XML-based language used to describe XML documents. The <types> section of a WSDL is actually an embedded XML Schema document. WSDL has an import capability that allows importation of externally defined XML Schema documents.

Parent topic: What is a web service?


Create a simple SOAP/RPC web service

RPC pattern methodology is often the quickest means to expose exiting functionality in a legacy system when creating web services using a bottom-up approach. Xcentrisity Business Information Server provides a simple mechanism to create these web services using XML Extensions.

While a more complex example is created later in this tutorial, this first example uses a simple data lookup. A desired company name, which may be a fragment of a name, will be provided. The desired result is the data from the first'record for which the company name is greater than or equal to the desired company name. Note that the data used for the sample programs in this tutorial is taken from North American Numbering Plan data. The data is not complete and contain inaccuracies to render the data unsuitable for any commercial application.

  • Data naming convention for input/output parameters and methods
  • Simple design pattern
  • Invoke web service using soapUI tool
  • Create clients in PHP, Perl, Java, Python
  • Add a web service to a Visual Studio 2010 project
Parent topic: BIS Tutorial


Data naming convention for input/output parameters and methods

BIS uses a set of naming conventions to define a data area A Data Area defines an RPC pattern web services interface. It is important to follow the naming conventions. The benefit is the ability to create a WSDL, process web service requests, and provide web service responses with a level of simplicity.

Here is the data area definition for the simple look up:

       78 Service-URI          VALUE "{{Value(""tutorial.srf"",HTMLDECODE,MAKEABS)}}".
       78 Service-Name         VALUE "tutorial".
       78 SOAP-Action-URI      VALUE "http://tempuri.org/bis/samples/action/tutorial".
       78 Method-Namespace-URI VALUE "http://tempuri.org/bis/samples/tutorial/".
       78 HTTP-Method-POST     VALUE "POST".
       78 HTTP-Method-GET      VALUE "GET".
       01 SOAP-Request-Response.
          10 HTTP-Method                   VALUE HTTP-Method-POST.
             88 HTTP-Method-Is-POST        VALUE HTTP-Method-POST.
             88 HTTP-Method-Is-GET         VALUE HTTP-Method-GET.
          10 Method-Name PIC X(100)        VALUE SPACES.
             88 Method-Is-Find	           VALUE "find".
          10 Fault-Area.
             20 FaultCode                  PIC X(10) VALUE SPACES.
             20 FaultString                PIC X(30) VALUE SPACES.
             20 FaultDetail                PIC X(80) VALUE SPACES.
          10 Find--Method-Parameters.
             20 Input-Parameters.
                30 desired-company-name    PIC X(50).
             20 Output-Parameters.
                30 Result                  PIC X(80).
                copy  "offcode.rec" replacing ==05== by ==30==.

First a series of constants (level 78) is defined to collect many of the service-specific values into a single block.

  • The Service-URI is a string that encodes a BIS VALUE tag. This tag specifies the SRF file that is the service endpoint. The value tag attributes HTMLDECODE and MAKEABS tell the BIS request handler that the SRF filename (tutorial1.srf in this case) should be made into a URI by adding the additional parts of the URI to the filename. When this value tag is returned in the WSDL, the actual URI of the service endpoint repoaces it before the WSDL is sent to the client. See the Xcentrisity Business Information Server user's Guide for reference information.
  • The Service-Name is a string that identifies the service to clients. It becomes the value of the name attribute in the <wsdl:service> tag. The actual use of the Service-name depends on the programming language of the client. It appears in the client's API, so a meaningful name is recommended.
  • The SOAP-Action-URI is a string that is used to uniquely identify a <soap:operation>. This string should take the form of a URI. As shown in this example, you may use the tempuri.org domain for testing purposes. However, you are encouraged to use a unique, permanent URI for published web services. You can use your company's domain as part of the URI value. Note that this URI does not point to an actual resource on the web.
  • The Method-Namespace-URI is a string that is used in the targetNamespace attribute of the <wsdl:definitions> tag. Like the SOAP-Action-URI, this URI should be unique, and otherwise follow the same guidelines.

In the definition of the 01-level SOAP-Request-Response, the first items (through 10 Fault-Area) should be defined as they are here. These definitions convey values to the XSLT stylesheets that create the WSDL, import the SOAP request, and form the SOAP response, and the names of these items must remain the same. However, condition-names (level 88) may be added, as these do not affect the values. Condition-names may be convenient for enumerating the possible method name values. By default, method name values are all folded to lowercase by the XSLT style sheets.

Method parameter definitions follow 10 Fault-Area, with a separate level 10 group data item defined for each method (function) in the service. The naming convention for these group items is: methodname--method-parameters, where methodname is the desired name of the method, followed by two hyphens. In this first example, there is only one method, named find. (Note that the method name is folded to lower case, so Find, FIND and fInD all result in a method named find.)

Within each method parameter group item, zero, one, two or three group items may exist. The names of these group items are: INPUT-PARAMETERS, OUTPUT-PARAMETERS, and INPUT-OUTPUT-PARAMETERS. Input and output parameters are defined within each of these groups as appropriate.

Note: Complex structures and arrays of structures can sometimes cause difficult programming issues on clients.
Parent topic: Create a simple SOAP/RPC web service


Simple design pattern

The COBOL service program for the web service takes the form of a controller. In the model-view-controller, MVC, web architecture for applications, the controller is the component that receives the GET or POST input and invokes domain objects that contain the business rules that perform a specific task and produce the output.

First, the controller receives the input. Here is the code that does this.

       Preset Section.
       A.
           XML INITIALIZE
           If Not XML-OK Go To Z.

       Preset-Request-Data.

           CALL "C$GetEnv" USING "BIS_FILENAME",
                                 BIS-Exchange-File-Name,
                                 BIS-Exchange-File-Result.

           If not BIS-Exchange-File-Result = 0
               DISPLAY "Could not obtain the BIS Exchange filename"
               STOP RUN.

           Display "BIS Exchange File: " BIS-Exchange-File-Name.

           Perform Process-SOAP-Requests.
           Stop Run.

This is a normal initialization for a BIS service program. The XML Extensions package initializes and the exchange document file that contains the client is found. The dispatcher is PERFORMed.

Tip: The term dispatcher is used in the model-view-controller architecture. The dispatcher code determines what is being requested, and calls the code to perform the request.
Process-SOAP-Requests Section.

       Get-Request.
           XML SET XSL-PARAMETERS
               "Method_Namespace"     Method-Namespace-URI.   *> all
           If Not XML-OK Go To Z End-If.
           Call "B_ReadRequest" Giving BIS-Status
           If Not BIS-OK Go To Z.

      *    At this point, the SOAP request payload elements
      *    are available to the application in the exchange file.

           Initialize SOAP-Request-Response.
           Move HTTP-Method-POST To HTTP-Method.
           move Service-URI to SOAP-Address.
           move SOAP-Action-URI to SOAP-Action-Prefix.
           move Method-Namespace-URI to Method-Namespace.
           move Service-Name to Interface-Name.

           XML IMPORT FILE
               SOAP-Request-Response        *> data item to import into
               BIS-Exchange-File-Name       *> import document file name
               "SOAP-Request-Response"      *> model data-name
               "soap_request_to_cobol.xsl". *> stylesheet for transform
           If Not XML-OK Go To Z.
      *    The request has been imported into SOAP-Request-Response

           If HTTP-Method-Is-GET
      *        GET is the HTTP method that is used to obtain WSDL
               Perform Write-WSDL
               Stop Run
           End-If.

       Dispatch-Request.

The dispatcher code first calls B_ReadRequest, which is a synchronization routine that waits for the BIS request handler (running in the HTTP server) to place the input request document in the exchange file. The request is then imported from the exchange file into the level 01 record area. At this point the dispatcher makes its first decision. If the request is a GET,it creates the WSDL for the web service as the response to the client. Otherwise, the controller knows this is a POST request invoking a method.

  • WSDL creation/response
  • SOAP request/response
Parent topic: Create a simple SOAP/RPC web service


WSDL creation/response

WSDL creation is almost entirely handled by a supplied XSLT style sheet. Here is the code.

Write-WSDL.

           XML ENABLE ATTRIBUTES
           If Not XML-OK Go To Z.

           XML ENABLE ALL-OCCURRENCES
           If Not XML-OK Go To Z.

           XML SET XSL-PARAMETERS
               "SOAP_Address"         Service-URI             *> WSDL
               "SOAP_Action_Prefix"   SOAP-Action-URI         *> WSDL
               "Interface_Name"       Service-Name            *> WSDL
               "Method_Namespace"     Method-Namespace-URI.   *> all
           If Not XML-OK Go To Z End-If.

           XML EXPORT FILE
            SOAP-Request-Response   *> data item to export from
         BIS-Exchange-File-Name  *> exported document file name
         "SOAP-Request-Response" *> model data-name
         "cobol_to_wsdl.xsl"     *> stylesheet for transform
              If Not XML-OK Go To Z End-If
    Call "B_WriteResponse" Using
                 BIS-Response-SessionComplete
                 Giving BIS-Status
        If Not BIS-OK Go To Z End-If.

This paragraph exports the WSDL to the exchange file using the cobol_to_wsdl.xsl style sheet.

This style sheet uses the structure of the SOAP-Request-Response record area to derive much of the information for the WSDL. Attributes and all occurrences are enabled. Additional metadata values pass to the style sheet as XSL parameters. This style sheet depends on the naming conventions properly to identify all the methods and their parameters. B_WriteResponse then notifies the request handler that the response is in the exchange file. The request handler sends the exchange file contents to the client.

Parent topic: Simple design pattern


SOAP request/response

When a SOAP request is detected, the dispatcher invokes the business rules associated with the requested method.

Dispatch-Request.
           If Not Method-Namespace-Is-OK
               Move "env:client" To FaultCode
        Move "bis:WrongNamespace" To FaultString
        Move "Wrong namespace for this interface"
          To FaultDetail
        Perform Indicate-Hard-Fault
           Else
               Evaluate True
                   When Method-Is-Find
                       Perform Process-Find-Method
                   When Other
                    Move "env:client" To FaultCode
                    Move "bis:WrongMethod" To FaultString
                    Move
                         "Method invoked is unknown to this interface" To
                    FaultDetail
                    Perform Indicate-Hard-Fault
               End-Evaluate
           End-If.

           Stop Run.

       Process-Find-Method.
           open input office-code-file.
           move spaces to output-parameters of Find--method-parameters.
           if office-code-success
               move desired-company-name of input-parameters of Find--method-parameters
          to company-name of office-code-file
        start office-code-file key Not < company-name of office-code-file
           invalid key move "Not Found" to result of Find--method-parameters
           not invalid key
               read office-code-file next
               at end move "Not Found" to result of Find--method-parameters
               not at end
   move corr office-code-record
                          to output-parameters of Find--method-parameters
               end-read
          end-start
       else
              move "Unrecoverable Error" to result of Find--method-parameters
       end-if.
       perform Issue-response.

       Issue-Response.
           XML EXPORT FILE
               SOAP-Request-Response         *> data item to export from
               BIS-Exchange-File-Name        *> exported document file name
               "SOAP-Request-Response"       *> model data-name
               "cobol_to_soap.xsl". *> stylesheet for transform
           If Not XML-OK Go To Z.

           Call "B_WriteResponse" Using
               BIS-Response-SessionComplete
               Giving BIS-Status
           If Not BIS-OK Go To Z.

After an import of a request, the method-name field contains the requested method (folded to lowercase) and the input and input-output parameters are stored in the appropriate ??method-parameters area. The dispatching code checks for some errors, such as erroneous calls by a client wanting to use a different service, and then uses the EVALUATE method-name to invoke business rules appropriate to the method. After the business rules execute (the paragraph Process-Find-Method in the example), the SOAP response is exported to the exchange file and B_WriteResponse notifies the request handler that the response is in the exchange file. The request handler sends the exchange file contents to the client.

Parent topic: Simple design pattern


Invoke web service using soapUI tool

Once you have created a web service, it is time to take it out for a test drive. Probably the best known web services test tools is soapUI, which is available in both open source and 'Pro' forms, the former being free to download. soapUI is available for most modern operating systems. (soapUI is implemented in Java, so you will be immediately testing in a cross-language environment.) Install soapUI according to its instructions. (Note that soapUI has many capabilities that will not be exploited in this tutorial.)

When you start soapUI and dismiss its start up screen, you are presented with a work area as shown below:

The left pane provides an area to define projects and the right pane contains windows that are associated with a selected project. Follow these steps to create a project to test the first example.

From the File menu, select New soapUI Project.

A dialog box appears, which allows you to provide a name for your project, as well as the location for finding the WSDL.

Type a name for the project, then in the Initial WSDL/WADL field, enter the following URL:

  • http://localhost/acuxbis/samples/tutorial1/tutorial1.srf

Since our web service provides a WSDL as the result of a GET on the endpoint, we simply enter a name for the project and the URL of the web service end point. Make sure the Create Requests: option is checked so that soapUI creates a prototype request document for each method. After fetching and processing the WSDL, the result is displayed in the left pane:

Note that the tutorialSoapBinding has a single method named find.

Expand the selection for the find method, exposing a prototype request named Request 1. Double click Request 1 to open the prototype request in the right pane:

The prototype request has the question mark (?) character in those areas that need input values to create a valid request. In the case of this tutorial example, we need to supply an alphanumeric value which the web service will use to determine which company name to return. Let's enter BO and press the green arrowhead at the upper left of the request window.

soapUI sends the request to the web service and displays the result:

This indicates that the web service has created a WSDL and successfully processed a web service request.

Parent topic: Create a simple SOAP/RPC web service


Create clients in PHP, Perl, Java, Python

Using a web service involves creation of a client that will marshal input parameters, create and transmit the SOAP request, receive the SOAP response and de-marshal the output parameters into a form usable by the client language. This client is often called a proxy for the web service, presenting the web service as a function call in the client's programming language.

Because web services are so pervasive, each language has one or more tools available for creating web service clients. Some of these are:

  • PHP: native xml-soap extension, SoapClient , NuSOAP
  • Perl: SOAP::Lite, SOAP::WSDL
  • Python: SUDS
  • Java: Many exist including those from Sun and Apache

Using these various packages is beyond the scope of this tutorial. However, there are some cautions about using tools to create web service clients. First, unless you expect the contract represented by the WSDL to change frequently, be sure that the proxy either fetches the WSDL at design time or that the WSDL is cached between multiple invocations of a web service. Second, if you wish to pass typical COBOL hierarchical structures (known as complex types), investigate first to see if the tool you wish to use supports such structures. You may have to simplify your input and output parameters to be able to interoperate with some less capable tools.

Parent topic: Create a simple SOAP/RPC web service


Add a web service to a Visual Studio 2010 project

Visual Studio 2010 provides a sophisticated ability to include web services in projects. Let's take a closer look at this popular programming IDE.

First, create a new project:

After the project is created, you add a service reference to the project.

When the Add Service Reference dialog appears, enter the URL of the SRF file that is the endpoint of the service.

The WSDL will be fetched, at which time the information about the web service is added to the dialog:

The methods available in the service are listed in the 'Operations:' column. Click OK to complete adding the service to the project. Proxy functions are created for the operations (methods) and the service appears in the Solution Explorer.

The generated proxy functions allow you to use the web service's methods in a manner identical to any other function.

Parent topic: Create a simple SOAP/RPC web service


Intro to XML Extensions

XML Extensions is a facility that allows COBOL applications to interoperate freely and easily with other applications that use the XML standard. XML Extensions provide the ability to import and export XML documents to and from COBOL working storage in a natural and intuitive way to the COBOL programmer.

  • Concept of XSLT
  • How XSLT creates a BIS WSDL (high level only)
  • How XSLT processes a SOAP request (high level only)
Parent topic: BIS Tutorial


Concept of XSLT

XSLT, which stands for Extensible Stylesheet Language Transformations, is a declarative, XML-based language used for the transformation of XML documents into other XML documents. The input document is used to create a new output document using the data in the input document along with the rules described in the XSLT document. The style of programming is that of a functional language with string matching, rather than a procedural language. Learning to create XSLT 'programs' is not difficult, but changing to the functional programming paradigm for those accustomed to procedural languages does require a different approach to problem solving.

Note: The term XSL is often used to mean XSLT. XSL is actually a family of standards that includes XSLT. For most practical purposes, this subtle distinction can be ignored

XML Extensions creates (exports) or consumes (imports) only documents which 'match' the hierarchical structure of a COBOL record area. When the external requirements for an XML document do not achieve this match, XSLT is used. For example, SOAP web services require the creation of a very complicated XML document, the WSDL, to describe the web service. Xcentrisity BIS uses XSLT to create the WSDL from a COBOL data description - matching the relatively simple data layout to the complex WSDL XML document.

Note: The following discussion uses terminology that presumes an understanding of XSLT. A thorough explanation of XSLT is beyond the scope of this tutorial. Several excellent books and online tutorials are available that teach XSLT.
Parent topic: Intro to XML Extensions


How XSLT creates a BIS WSDL (high level only)

As described earlier, a BIS service program describes its API using a 01-level group item named SOAP-Request-Response. This data item has specific naming conventions that describe input and output parameters for each method within the web service. The XSLT that describes the transformation from the basic XML document that is exported from SOAP-Request-Response to the WSDL XML document that is returned to the web client is named cobol_to_wsdl.xsl.

cobol_to_wsdl.xsl differs somewhat from other 'normal' XSLT used with XML Extensions. While most XSLT are focused on rearranging data being exported from or imported to the COBOL program, cobol_to_wsdl.xsl instead uses the metadata in the XML document being exported from the COBOL web service program to create another metadata document, the WSDL. The metadata used consists of the values of some parameters, the element names (resulting from the naming conventions used), and information exported due to the use of XML ENABLE ATTRIBUTES.

Let's have a brief review of the naming conventions found in SOAP?Request?Response. Each method in the web service is defined by a group item immediately subordinate to SOAP?Request?Response with the name methodname ??method?parameters (note the two hyphens after methodname), where methodname is the name of the method being defined. Within each of these groups, one to three group items, named input?parameters, output?parameters and/or input?output?parameters, may be defined. The first use of this naming convention can be seen at the beginning of the first <xsl:template>, where a variable named $methods is created and contains all the elements whose names end in ??method?parameters. The $methods variable is then used throughout the rest of the template to iterate over all methods.

Let's look at the major sections of cobol_to_wsdl.xsl, which correspond to the four sections of a WSDL.

The internal schema, which contains most of the complexity of a WSDL, is created inside the <wsdl:types> element. While there is a fairly large amount of code involved, this essentially involves iterating over all the methods and creating XML Schema descriptions of each of the request and response parameters. Special attention is paid to arrays (OCCURS) and to structures (COBOL group items). In particular, arrays must be named in a manner such that the arrays can be identified by the naming convention in an incoming SOAP request where the metadata of the COBOL structure is not available to assist interpretation. 'Wrapper' request and response elements are also created which conform to the requirements of document/literal wrapped SOAP requests.

Next, the <wsdl:message> elements are created for each method, followed by the <wsdl:operation> elements (within the <wsdl:portType> element). These elements are relatively simple in document/literal wrapped SOAP requests.

Finally, the <wsdl:operation> elements for each method are generated within the <wsdl:binding> element. The WSDL is then completed with the <wsdl:service> element creation.

Parent topic: Intro to XML Extensions


How XSLT processes a SOAP request (high level only)

When importing a SOAP request, three things are necessary:

  1. The BIS service program must know the HTTP method being used,
  2. The SOAP method being requested, and
  3. The input parameter values for the SOAP request. The soap_to_cobol.xsl is the XSLT document that describes this transformation.

The BIS request document consists of four major parts.

The actual payload of the request is wrapped inside a <bis:content> element. ,

  1. The cookie values passed by the client are wrapped inside a <bis:cookies> element,
  2. The server variable values are wrapped inside a <bis:server-variables> element, and
  3. The query parameters from the URL are wrapped inside a <bis:query-params> element.

The latter three sets of values may be obtained by the service program by including the following group items (preserving the names) in the SOAP-Request-Response group item:

05  s--cookies.
     07  s--cookie occurs 20.
         09  s--name   pic x(40).
             09  s--value  pic x(100).
05  s--query parameters.
     07  s--query parameter occurs 20.
         09  s--name   pic x(40).
         09  s--value  pic x(100).
05  s--variables.
      07  s--variable occurs 100.
          09  s--name   pic x(40).
          09  s--value  pic x(100).

Cookies, query parameters and server variables are typically presented as name?value pairs. The name?value pairs are stored in the arrays described above.

As part of the retrieval of the server variables, the value of the server variable named REQUEST_METHOD is placed in the http-method.

The remainder of the XSLT is devoted to retrieving the payload information from the <bis:content> element. The payload is a SOAP envelope, which in turn contains a <SOAP:body> element that contains the actual method request..

A document/literal wrapped SOAP request has a single element (the so-called wrapper element) inside the SOAP:body. The name of this element is the name of the requested method. By concatenating the element (method) name with the string xx the subsequent parameter values may be directed (imported) into the appropriate method's input parameter group.

After the method name has been determined, the elements subordinate to the wrapper element are processed to obtain the input parameter values. This processing is straightforward with the exception of discovering array elements which use a naming convention (see the description of WSDL processing above).

Parent topic: Intro to XML Extensions


How XSLT processes a SOAP response (high level only)

Exporting a SOAP response involves forming a correct SOAP envelope which conforms to the response defined by the WSDL. The cobol_to_soap.xsl XSLT is the document that describes this transformation.

The method name for the response is exported, along with all the other data in SOAP?Request?Response. The method name is used to determine which output?parameters contains actual output parameters of interest. And, as in the import of a SOAP request, item names for array elements are adjusted to conform to the naming convention described in the WSDL.

Parent topic: BIS Tutorial


Data flow in BIS

While an in-depth understanding of the inner workings of BIS is not necessary for the successful implementation and use of web services, it is useful to understand the steps the request and response messages go through during the processing of a single web service request. More information about particulars can be found in the reference manual for Xcentrisity Business Information Server.

A BIS server is composed of two cooperating processes: a request handler running under the control of an HTTP server (IIS or Apache), and a service program, programmed in COBOL, running under the control of the Xcentrisity service engine, which is very similar to the AcuCOBOL-GT runtime. A third process is also involved: the web client agent.

  • Request handling
  • SRF file
  • Service program
  • Response handling
Parent topic: BIS Tutorial


Request handling

A web service request begins when a web client agent (for example, JavaScript in a browser) sends an HTTP request for a URL designating an SRF file (also known as a BIS stencil file). When the HTTP server receives this request, it determines that the appropriate 'request handler extension' for such a request is the BIS Request Handler.

The BIS request handler interprets the tags in the SRF file in the order in which the tags appear. A tag is composed of text surrounded by {{ and }} sequences, and tags may be interpreted as processing instructions or placeholders that are replaced by plain text, HTML or XML that is generated by the BIS service engine or by the BIS request handler. In the case of SOAP web services the SRF file is very succinct as shown below.

One of the tags, the XMLExchange tag, causes the request handler to format the request information, including the state of the HTTP server variables, cookies, query parameters and the request payload., into a standard BIS request. The BIS request is transmitted to the service program via the 'exchange file'. Then, the request handler suspends its processing of the request until the service program informs it that a response is available.

Parent topic: Data flow in BIS


SRF file

Let's look at an SRF file for a SOAP web service.

{{ Handler * }}{{//}}
{{ RunPath(bin,../common) }}{{//}}
{{ StartService(tutorial2 -v) }}{{//}}
{{ XMLExchange }}

First, let's understand the rather curious looking tag, {{//}}. This tag has the job of consuming whitespace (that is, preventing the {{//}} tag and any surrounding whitespace from being rendered back into the response payload). Whitespace includes spaces, tabs, form feeds and the like, between the other tags. The use of this tag allows us to write an SRF file that presents each tag on a separate line even though the rules of SOAP responses preclude the inclusion of such whitespace to make the response more human-readable.

The {{Handler}} tag is basically a signature tag that must appear within the first few hundred characters of the SRF file. It is replaced with a zero-length string in the response and is used internally by the HTTP server and request handler.

The {{RunPath}} tag is used to set environment variables for the service program so that the service program can find its object and data files. This is similar to shell script commands that are used to set these environment variables in the normal runtime environment. The {{RunPath}} tag is replaced by a zero-length string in the response.

The {{StartService}} tag is used to request that a service program be started by the service engine. (Note that in stateful applications, the StartService tag is used to determine whether the correct service program is running in the saved state of the session. See the reference documentation for more information.) The {{RunPath}} tag is replaced by a zero-length string in the response.

Finally, the {{XMLExchange}} tag functions as the synchronization point between the request handler and the service program. The request handler suspends processing the request until signaled by the service program.

Parent topic: Data flow in BIS


Service program

The service program designated in the {{StartService}} tag is activated when that tag is processed. However, the contents of the request may not yet be available in the exchange file. It is for this reason that the service program calls B_ReadRequest to wait for the request to be made available.

When the request becomes available, B_ReadRequest returns control to the service program. At that point, the request XML document that is in the exchange file may be imported, using XML Extensions, into the service program's working-storage data area. A provided XSLT style sheet transformation is applied when the only expected request is a SOAP web service request. (Note that a more flexible service program might import the request XML document more than once, in order to determine what kind of request was being presented.)

After the request document is imported, the service program acts upon the request and produces a response, which is placed in the exchange file. Note that this response does not have to be an XML document (for some examples see below) but in the case of a SOAP response, it is the entire SOAP response envelope.

After the response is in the exchange file, the service program signals this fact by calling B_WriteResponse. In a stateless web service environment, the call should include the option that indicates that the session should be terminated. The service program then terminates in a normal, orderly manner.

Parent topic: Data flow in BIS


Response handling

When the service program signals that a response is available, the request handler replaces the XMLExchange tag with the entire contents response contained in the exchange file. During this process, the request handler also examines the contents of the exchange file for certain request handler tags, and processes those tags before sending the response back to the web client. These tags are useful in controlling information such as the MIME type of the response and other information that may only be determined by the service program. Likewise, the service program may wish to send information in the response that is known only by the request handler; replacement tags are used for this purpose.

When the request handler encounters the end of the SRF file, the response that has been accumulated is sent back to the web client.

Parent topic: Data flow in BIS


BIS Session management

The Xcentrisity BIS has session management capabilities that may be exploited. Session management involves the reservation of certain web server resources - memory, processes, etc. - for the use by a specific web client. In the case of BIS, the state of a service program, including data values, open files, current record pointers, etc., may be maintained between requests from a specific web client.

Session management is useful for interacting with services that must return large amounts of data under controlled circumstances. However, session management carries some inefficiency as well; the web client's request must be routed to a specific server, and significant memory and process resources may be held waiting for a misbehaving client that fails to return to use them. Use caution if you are considering a stateful BIS implementation.

BIS uses a cookie hold a session identification key. When a service program indicates that a session is to be maintained, and there are not SRF tags indicating otherwise, a cookie is sent to the web client with the response. The web client then sends this cookie back with its next request; the request handler uses the cookie value to reconnect the request with the correct session, thereby routing the request to a service program already waiting for it.

Parent topic: BIS Tutorial


Complex design pattern

While there may be situations where a simple web service implementing a single method is appropriate, a somewhat more complex design pattern may be illustrative of the controller concept.

  • Using a simple indexed file, create a web service that implements CRUD
  • Optimistic concurrency
Parent topic: BIS Tutorial


Using a simple indexed file, create a web service that implements CRUD

One popular organizing design pattern is the Create, Read, Add, Delete (CRUD) function group for persistent storage in an application. The acronym CRUD is often used to describe this function group. By adding the capability to browse on one or more fields (as provided by tutorial1), and by a careful renaming of the functions, we can create a design pattern known as BREAD (Browse, Read, Edit, Add, Delete).

The BREAD design pattern applied to an indexed file, or a multiple related indexed files, is useful in exposing data in an existing application. tutorial2 provides an example of a web service implementing the BREAD function set on a single indexed file.

tutorial2 illustrates a few more naming conventions that are useful in communicating information between the COBOL service program and the XSLT style sheet. First, if you wish to control the case of the characters that spell a method name, you may override the default behavior of folding the method name to lower case. This is shown on each of the methods. In particular, you place a method--METHOD-NAME data item at the same level as the method--METHOD-PARAMETERS group item. The desired spelling (differing in case only) is entered as the value of the method--METHOD-NAME data item. Note that the values in the method--METHOD-NAME items must be maintained for both WSDL and response export.

In a similar manner, one can control the externally visible naming of parameters. This is illustrated in the Browse method output?parameter definition, where the data item found?item??name is used to rename the very COBOL?like name found?record to FoundRecord. Note that, unlike method names, the desired spelling can be different for data item names that are output parameters; however, spellings for input parameters may differ only in case.

Finally, also in the Browse method output?parameters, the specially named data item found?record??count is used to communicate the number of occurrences that should be exported. A ??count data item may also be used on an imported data item array so that the actual number of array items imported may be known.

Parent topic: Complex design pattern


Optimistic concurrency

Many, if not most, multiuser applications that use indexed files use pessimistic concurrency (record locks) to avoid having two users attempt to update a record at once, thereby losing one of the updates. The name pessimistic concurrency is used because record locks are often obtained and held while a user is making changes.

If pessimistic concurrency (i.e. normal record locks) is used in a web services environment, the service program must be stateful. That is, the service program must continue to exist while the web client is acting on the data, waiting for the web client to release the lock, or to time out. In reality, though, it is often the case that the web client may never return (consider JavaScript in a browser when the user closes the browser window).

The answer to the operation difficulties in a web service environment of pessimistic concurrency is the use of optimistic concurrency. In optimistic concurrency, the contents of a record are recorded or remembered at the time a record is read. Then, when a user desires to change or delete the record, the original contents of the record are compared to the current contents of the record. If the contents have not changed, the update of delete operation is completed. If the contents have changed, the user is notified and the change is not made.

tutorial2 demonstrates a tactic for detecting a change in record contents without storing a copy of the original contents of a record. A message digest (also known as MD5) is computed when the record is originally read, and is sent to the client along with the record contents. (One of the characteristics of a message digest is the fact that changing a single bit in the message - in this case, the record contents - will cause a change in the message digest.) When the client desires to update or delete the record, the original message digest is sent as one of the input parameters of the request. As part of processing the update or delete request, the server first reads the record with lock, recomputes the message digest and compares the computed digest to the digest sent by the client. If the digests are equal, the record has not changed and the request is completed. If the record has changed, it is unlocked and the client is notified that the record contents have changed. (Note that the -Cr option must be used to compile the program that computes the message digest.)

Parent topic: Complex design pattern


Not quite web service

The architecture of Xcentrisity Business Information Server does not restrict its use to SOAP web services. As noted above, BIS can support web applications that use the REST architecture. In addition, BIS may be used to implement other XML- and HTTP-based web technologies. These might include Atom, RSS, Ajax, SVG, and JSON.

  • AJAX/JSON
Parent topic: BIS Tutorial


AJAX/JSON

As an example of the versatility of the combination of BIS and XML extensions, consider tutorial3, which is a BIS service program similar to the tutorial2 browse method that can produce either an XML response or, if the ACTION=JSON query parameter is included on the URL, the service program uses a different XSLT style sheet to export identical data in JSON (JavaScript Object Notation) format.

When invoked with a URL ending in tutorial3.srf?STARTSWITH=C the following XML is returned:

<companies>
        <company>
                <statecode>IA</statecode>
                <areacode>712</areacode>
                <officecode>723</officecode>
                <companyname>C-M-L TELEPHONE COOP. ASSN. OF MERIDEN, IOWA</companyname>
                <ratecenter>ARCHER</ratecenter>
                <assignmentcode>AS</assignmentcode>
        </company>
        <company>
                <statecode>TX</statecode>
                <areacode>512</areacode>
                <officecode>316</officecode>
                <companyname>C3 COMMUNICATIONS, INC. - TX</companyname>
             <ratecenter>AUSTIN</ratecenter>
                <assignmentcode>AS</assignmentcode>
        </company>
        <company>
                <statecode>MT</statecode>
                <areacode>406</areacode>
                <officecode>935</officecode>
                <companyname>CABLE &amp; COMMUNICATIONS CORPORATION</companyname>
                <ratecenter>BROADUS</ratecenter>
                <assignmentcode>AS</assignmentcode>
       </company>
etc

When invoked with a URL ending in tutorial3.srf?STARTSWITH=C&ACTION=JSON the following text is returned:

{ "companies" : [

      {
       "statecode" : "IA",
       "areacode" : 712,
       "officecode" : 723,
       "companyname" : "C-M-L TELEPHONE COOP. ASSN. OF MERIDEN, IOWA",
       "ratecenter" : "ARCHER",
       "assignmentcode" : "AS"
      },
      {
       "statecode" : "TX",
       "areacode" : 512,
       "officecode" : 316,
       "companyname" : "C3 COMMUNICATIONS, INC. - TX",
       "ratecenter" : "AUSTIN",
       "assignmentcode" : "AS"
      },
      {
       "statecode" : "MT",
       "areacode" : 406,
       "officecode" : 935,
       "companyname" : "CABLE & COMMUNICATIONS CORPORATION",
       "ratecenter" : "BROADUS",
       "assignmentcode" : "AS"
      },
      etc.

Additional usage examples may be found on the Micro Focus Supportline Knowledge Base.

Parent topic: Not quite web service


Server Variables Reference

The following table describes the server variables that may be inspected with the Value tag. Note that the descriptions are taken from Microsoft's IIS SDK documentation and not all server variables are displayed in the TRACE output if empty.

Variable | Platform | Description
ALL_HTTP | IIS | All HTTP headers sent by the client.
ALL_RAW | IIS | Retrieves all headers in raw form. The difference between ALL_RAW and ALL_HTTP is that ALL_HTTP places an HTTP_ prefix before the header name and the header name is always capitalized. In ALL_RAW the header name and values appear as they are sent by the client.
APP_POOL_ID | IIS | Returns the name of the application pool that is running in the IIS worker process that is handling the request.
APPL_MD_PATH | IIS | Retrieves the metabase path for the Application for the BIS server
APPL_PHYSICAL_PATH | IIS | Retrieves the physical path corresponding to the metabase path. IIS converts the APPL_MD_PATH to the physical (directory) path to return this value.
AUTH_PASSWORD | IIS | The value entered in the client's authentication dialog box. This variable is available only if Basic authentication is used.
AUTH_TYPE | IIS | The authentication method that the server uses to validate users when they attempt to access a protected script.
AUTH_USER | IIS | The name of the user as it is derived from the authorization header sent by the client, before the user name is mapped to a Windows account. This variable is no different from REMOTE_USER. If you have an authentication filter installed on your web server that maps incoming users to accounts, use LOGON_USER to view the mapped user name.
CERT_COOKIE | IIS | Unique ID for the client certificate, returned as a string. This can be used as a signature for the whole client certificate.
CERT_FLAGS | IIS | Bit 0 set to 1 if the client certificate is present. Bit 1 is set to 1 if the certification authority of the client certificate is invalid (that is, it is not in the list of recognized certification authorities on the server).
CERT_ISSUER | IIS | Issuer field of the client certificate (O=MS, OU=IAS, CN=user name, C=USA).
CERT_KEYSIZE | IIS | Number of bits in the Secure Sockets Layer (SSL) connection key size. For example, 128.
CERT_SECRETKEYSIZE | IIS | Number of bits in server certificate private key. For example, 1024.
CERT_SERIALNUMBER | IIS | Serial number field of the client certificate.
CERT_SERVER_ISSUER | IIS | Issuer field of the server certificate.
CERT_SERVER_SUBJECT | IIS | Subject field of the server certificate.
CERT_SUBJECT | IIS | Subject field of the client certificate.
CONTENT_LENGTH | All | The length of the content as given by the client.
CONTENT_TYPE | All | The data type of the content. Used with queries that have attached information, such as the HTTP queries GET, POST, and PUT.
DOCUMENT_ROOT | Apache | Contains the local directory from which the server is serving pages.
GATEWAY_INTERFACE | All | The revision of the CGI specification used by the server. The format is CGI/revision. Example: CGI/1.1.
HTTP_HeaderName | All | The value stored in the HTTP header HeaderName . Any header other than those listed below must be preceded by HTTP in order for the Value(variable, Server) collection to retrieve its value. This is useful for retrieving custom headers. The server interprets any underscore (_) characters in HeaderName as dashes in the actual header. For example, if you specify HTTP_MY_HEADER, the server searches for a request header named MY-HEADER .
HTTP_ACCEPT | All | Returns the value of the Accept header. For example, image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd.ms-excel.
HTTP_ACCEPT_CHARSET | IIS | The raw contents of the Accept-Charset header: contains a list of character sets that are acceptable in the response. For example, iso-8859-5, unicode-1-1;q=0.8
HTTP_ACCEPT_ENCODING | All | The raw contents of the Accept-Encoding header: contains a list of accepted encoding types, for example, gzip, deflate.
HTTP_ACCEPT_LANGUAGE | All | The raw contents of the Accept-Language header
HTTP_AUTHORIZATION | IIS | The raw contents of the Authorization header.
HTTP_CACHE_CONTROL | All | The raw contents of the Cache-Control header.
HTTP_CONNECTION | All | The raw contents of the Connection header.
HTTP_CONTENT_LENGTH | IIS | The raw contents of the Content-Length header.
HTTP_CONTENT_TYPE | IIS | The raw contents of the Content-Type header.
HTTP_COOKIE | All | Returns the cookie string that was included with the request.
HTTP_DATE | IIS | The raw contents of the Date header.
HTTP_EXPECT | IIS | The raw contents of the Expect header.
HTTP_FROM | IIS | The raw contents of the From header.
HTTP_HOST | All | Returns the name of the web server. This may or may not be the same as SERVER_NAME, depending on type of name resolution you are using on your web server (IP address or host header).
HTTP_IF_MODIFIED_SINCE | IIS | The raw contents of the If-Modified-Since header.
HTTP_IF_NONE_MATCH | IIS | The raw contents of the If-None-Match header.
HTTP_IF_RANGE | IIS | The raw contents of the If-Range header.
HTTP_IF_UNMODIFIED_SINCE | IIS | The raw contents of the If-Unmodified-Since header.
HTTP_MAX_FORWARDS | IIS | The raw contents of the Max-Forwards header.
HTTP_PRAGMA | IIS | The raw contents of the Pragma header.
HTTP_PROXY_AUTHORIZATION | IIS | The raw contents of the Proxy-Authorization header.
HTTP_RANGE | IIS | The raw contents of the Range header.
HTTP_REFERER | All | Returns a string that contains the URL of the page that referred the request to the current page by using an HTML <A> tag. Note that the URL is the one that the user typed into the browser address bar, which may not include the name of a default document. If the page is redirected, HTTP_REFERER is empty. HTTP_REFERER is not a mandatory member of the HTTP specification and some clients allow the end user to disable this information. Note that, in this case, REFERER is spelled with a single R.
HTTP_TE | All | The raw contents of the TE header.
HTTP_TRAILER | All | The raw contents of the Trailer header.
HTTP_TRANSFER_ENCODING | All | The raw contents of the Transfer-Encoding header.
HTTP_UPGRADE | All | The raw contents of the Upgrade header.
HTTP_URL | All | Returns the raw, encoded URL. Example: /xbis/default.srf?query. Note that the scheme and host name are not part of this URL. On Apache, this does not include the query portion.
HTTP_USER_AGENT | All | Returns a string describing the browser that sent the request.
HTTP_VERSION | IIS | The raw contents of the Version header.
HTTP_VIA | IIS | The raw contents of the Via header.
HTTP_WARNING | IIS | The raw contents of the Warning header.
HTTPS | All | Returns ON if the request came in through a secure channel (for example, SSL); or it returns OFF, if the request is for an insecure channel.
HTTPS_KEYSIZE | IIS | Number of bits in the SSL connection key size. For example, 128.
HTTPS_SECRETKEYSIZE | IIS | Number of bits in the server certificate private key. For example, 1024.
HTTPS_SERVER_ISSUER | IIS | Issuer field of the server certificate.
HTTPS_SERVER_SUBJECT | IIS | Subject field of the server certificate.
INSTANCE_ID | IIS | The ID for the IIS instance in textual format. If the instance ID is 1, it appears as a string. You can use this variable to retrieve the ID of the web server instance (in the metabase) to which the request belongs.
INSTANCE_META_PATH | IIS | The metabase path for the instance of IIS that responds to the request.
LOCAL_ADDR | IIS | Returns the server address on which the request came in. This is important on computers where there can be multiple IP addresses bound to the computer, and you want to find out which address the request used.
LOGON_USER | IIS | The Windows account that the user is impersonating while connected to your web server. Use REMOTE_USER, UNMAPPED_REMOTE_USER, or AUTH_USER to view the raw user name that is contained in the request header. The only time LOGON_USER holds a different value than these other variables is if you have an authentication filter installed.
PATH | Apache | Contains the Apache Server's PATH environment variable.
PATH_INFO | IIS | Extra path information, as given by the client. You can access scripts by using their virtual path and the PATH_INFO server variable. If this information comes from a URL, it is decoded by the server before it is passed to the CGI script.
PATH_TRANSLATED | IIS | A translated version of PATH_INFO that takes the path and performs any necessary virtual-to-physical mapping.
QUERY_STRING | All | Query information stored in the string following the question mark (?) in the HTTP request.
REMOTE_ADDR | All | The IP address of the remote host that is making the request.
REMOTE_HOST | IIS | The name of the host that is making the request. If the server does not have this information, it will set REMOTE_ADDR and leave this empty.
REMOTE_PORT | All | The client port number of the TCP connection.
REMOTE_USER | IIS | The name of the user as it is derived from the authorization header sent by the client, before the user name is mapped to a Windows account. If you have an authentication filter installed on your web server that maps incoming users to accounts, use LOGON_USER to retrieve the mapped user name.
REQUEST_METHOD | All | The method used to make the request. For HTTP, this can be GET, HEAD, POST, and so on.
REQUEST_URI | Apache | The complete URI of the request.
SCRIPT_FILENAME | Apache | The complete file name of the script being executed.
SCRIPT_NAME | All | A virtual path to the script being executed. This is used for self-referencing URLs.
SERVER_ADDR | Apache | The IP address to which the request was sent.
SERVER_ADMIN | Apache | Contains the email address of the server's system administrator. (This is contents of the ServerAdmin configuration record.)
SERVER_NAME | All | The server's host name, DNS alias, or IP address as it would appear in self-referencing URLs.
SERVER_PORT | All | The server port number to which the request was sent.
SERVER_PORT_SECURE | IIS | A string that contains either 0 or 1. If the request is being handled on the secure port, then this is 1. Otherwise, it is 0.
SERVER_PROTOCOL | All | The name and revision of the request information protocol. The format is protocol/revision . Example: HTTP/1.1.
SERVER_SIGNATURE | Apache | The name and version of the Apache web server, plus the network name and port number on which the web server is running. Example: Apache/2.0.55 (Unix) mod_ssl/2.0.55 OpenSSL/0.9.8a Server at arokh.liant.com Port 80
SERVER_SOFTWARE | All | The name and version of the server software that answers the request and runs the gateway. The format is name/version. Example: Microsoft-IIS/5.0
SSL_CIPHER | Apache HTTPS | The name of the SSL cipher in use. Example: RC4-MD5
SSL_CIPHER_EXPORT | Apache HTTPS | Contains true if the cipher is an export cipher and false otherwise.
SSL_CIPHER_ALGKEYSIZE | Apache HTTPS | The maximum number of bits permitted in the cipher's. Example: 128
SSL_CIPHER_USEKEYSIZE | Apache HTTPS | The number of bits actually in use in the cipher. Example: 128
SSL_CLIENT_A_KEY | Apache HTTPS | The signature algorithm used in the client key. Example: rsaEncryption
SSL_CLIENT_A_SIG | Apache HTTPS | The signature algorithm used in the client certificate. Example: sha1WithRSAEncryption
SSL_CLIENT_I_DN | Apache HTTPS | The client certificate issuer distinguish name subject. Example: /CN=neo
SSL_CLIENT_I_DN_CN | Apache HTTPS | The computer name of the client certificate issuer distinguish name subject. Example: neo
SSL_CLIENT_M_VERSION | Apache HTTPS | The client certificate's version. Example: 3
SSL_CLIENT_M_SERIAL | Apache HTTPS | The client certificate's serial number. Example: 1DFD4318000000000015
SSL_CLIENT_S_DN | Apache HTTPS | The client certificate distinguished name subject. Example: /C=US/ST=TX/L=Austin/O=Liant/OU=R&D/CN=Mike Schultz/emailAddress=michael.schultz@microfocus.com
SSL_CLIENT_S_DN_C | Apache HTTPS | The country of the client certificate distinguished name subject. Example: US
SSL_CLIENT_S_DN_CN | Apache HTTPS | The contact of the client certificate distinguished name subject. Example: Mike Schultz
SSL_CLIENT_S_DN_Email | Apache HTTPS | The email address of the client certificate distinguished name subject. Example: michael.schultz@microfocus.com
SSL_CLIENT_S_DN_L | Apache HTTPS | The location of the client certificate distinguished name subject. Example: Austin
SSL_CLIENT_S_DN_O | Apache HTTPS | The organization of the client certificate distinguished name subject. Example: Microfocus
SSL_CLIENT_S_DN_OU | Apache HTTPS | The organization unit of the client certificate distinguished name subject. Example: R&D
SSL_CLIENT_S_DN_ST | Apache HTTPS | The state of the client certificate distinguished name subject. Example: TX
SSL_CLIENT_VERIFY | Apache HTTPS | Contains SUCCESS if the client verification was successful.
SSL_CLIENT_V_END | Apache HTTPS | The client certificate's validity end time. Example: Dec 16 20:27:44 2006 GMT
SSL_CLIENT_V_START | Apache HTTPS | The client certificate's validity start time. Example: Dec 16 20:17:44 2005 GMT
SSL_PROTOCOL | Apache HTTPS | The version of the SSL protocol. Example: SSLv3
SSL_SERVER_M_VERSION | Apache HTTPS | The server's certificate's version. Example: 1
SSL_SERVER_M_SERIAL | Apache HTTPS | The server's certificate's serial number. Example: 00
SSL_SERVER_S_DN | Apache HTTPS | The server certificate distinguished name subject. Example: /C=US/ST=Texas/L=Austin/O=Micro Focus/OU=Development/CN=cent32.microfocmi.com/emailAddress=michael.schultz@microfocus.com
SSL_SERVER_S_DN_C | Apache HTTPS | The country of the server certificate distinguished name subject. Example: US
SSL_SERVER_S_DN_CN | Apache HTTPS | The computer name of the server certificate distinguished name subject. Example: cent32.microfocus.com
SSL_SERVER_S_DN_Email | Apache HTTPS | The email address of the server certificate distinguished name subject. Example: michael.schultz@microfocus.com
SSL_SERVER_S_DN_L | Apache HTTPS | The location of the server certificate distinguished name subject. Example: Austin
SSL_SERVER_S_DN_ST | Apache HTTPS | The state of the server certificate distinguished name subject. Example: Texas
SSL_SERVER_S_DN_O | Apache HTTPS | The organization of the server certificate distinguished name subject. Example: Micro Focus
SSL_SERVER_S_DN_OU | Apache HTTPS | The organization unit of the server certificate distinguished name subject. Example: Development
SSL_SERVER_I_DN | Apache HTTPS | The server certificate issuer's distinguished name subject. Example: /C=US/ST=Texas/L=Austin/O=Micro Focus/OU=Development/CN=cent32.microfocus.com/emailAddress=michael.schultz@microfocus.com
SSL_SERVER_I_DN_C | Apache HTTPS | The country of the server certificate issuer's distinguished name subject. Example: US
SSL_SERVER_I_DN_CN | Apache HTTPS | The computer name of the server certificate issuer's distinguished name subject. Example: cent32.microfocus.com
SSL_SERVER_I_DN_Email | Apache HTTPS | The email address of the server certificate issuer's distinguished name subject. Example: michael.schultz@microfocus.com
SSL_SERVER_I_DN_L | Apache HTTPS | The location of the server certificate issuer's distinguished name subject. Example: Austin
SSL_SERVER_I_DN_O | Apache HTTPS | The organization of the server certificate issuer's distinguished name subject. Example: Micro Focus
SSL_SERVER_I_DN_OU | Apache HTTPS | The organization unit of the server certificate issuer's distinguished name subject. Example: Development
SSL_SERVER_I_DN_ST | Apache HTTPS | The state of the server certificate issuer's distinguished name subject. Example: Texas
SSL_SERVER_A_KEY | Apache HTTPS | The signature algorithm of the server's key. Example: rsaEncryption
SSL_SERVER_A_SIG | Apache HTTPS | The signature algorithm of the server's certificate. Example: md5WithRSAEncryption
SSL_SERVER_V_END | Apache HTTPS | The server certificate's validity end time. Example: Jan 13 08:13:27 2006 GMT
SSL_SERVER_V_START | Apache HTTPS | The server certificate's validity start time. Example: Dec 14 08:13:27 2005 GMT
SSL_VERSION_INTERFACE | Apache HTTPS | The version of the SSL interface. Example: mod_ssl/2.0.55
SSL_VERSION_LIBRARY | Apache HTTPS | The version of the SSL library. Example: OpenSSL/0.9.8a
UNMAPPED_REMOTE_USER | IIS | The name of the user as it is derived from the authorization header sent by the client, before the user name is mapped to a Windows account. This variable is no different from REMOTE_USER. If you have an authentication filter installed on your web server that maps incoming users to accounts, use LOGON_USER to view the mapped user name.
URL | IIS | Gives the base portion of the URL.
Parent topic: Xcentrisity Business Information Server for extend User's Guide


XML Exchange Request File Format

Here is a sample request, as written to the file specified by the BIS_FILENAME environment variable. The request is transmitted in XML and is wrapped in the following top-level element:

<?xml version="1.0" encoding="UTF-8" ?>
< bis:request xmlns:bis=http://www.xcentrisity.com/2003/bis/request >
    content, cookies, queryparams, server variables
</ bis:request >

The content , cookies , queryparams , server variables contains the four elements described in the following table:

< bis:content >
    payload data
</ bis:content >
Contains the content part of the request (such as form variables POSTed back to the server). This element will be empty if there is no content data in the request-as is typically true of the first (GET) request.
< bis:cookies >
  < bis:cookie name=name >
      cookie data
  < /bis:cookie >
  …
</ bis:cookies >
Contains an attributed <bis:cookie> element for each cookie that was transmitted with the request.
< bis:query-params >
  < bis:query-param name=name >
      parameter data
  </ bis:query-param >
  …
</ bis:query-params >
Contains an attributed <bis:query-param> element for each query parameter that was transmitted with the request.
< bis:server-variables >
  < bis:server-variable name=name >
      server variable data
  </ bis:server-variable >
  …
</ bis:server-variables >
Contains an attributed <bis:server-variable> element for each server variable associated with this request.

The content of a sample request file is below. Note that this is also visible in the trace output, if tracing is enabled. Also note that the <bis:content> section is application-dependent. This particular example is from the http://localhost/acubis10/samples/sample3 application with the following data entered into the form fields:

Element | Attribute | Value
numberOne |  | 5
numberTwo |  | 2
cookie | BISKIT | Vos9tBgZknXRMTyI4GaJKw

Because this is a web service sample, there are no form fields or query parameters to store into the <bis:content> and <bis:query-params> elements. However the cookies are stored as attributed elements into the <bis:cookies> section. Finally, all server variables are output into the <bis:server-variables> section (not depicted above). Using Xcentrisity XML Extensions and XSLT, the service program can selectively extract any or all of these elements and ignore elements that are not important to the application.

Here is the complete XML exchange file for this example. Note that the XML tags are indented to make the example easier to read.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<bis:request xmlns:bis="http://www.xcentrisity.com/2003/bis/request">
  <bis:content>
    <SOAP-ENV:Envelope
      xmlns=""
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:s="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
      xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
      xmlns:tns="http://tempuri.org/bis/samples/Calculator/"
      xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <SOAP-ENV:Body>
        <Add xmlns="http://tempuri.org/bis/samples/Calculator/">
          <A>5</A>
          <B>2</B>
        </Add>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>
  </bis:content>
  <bis:cookies>
    <bis:cookie name="cookies">true</bis:cookie>
    <bis:cookie name="BISKIT">Vos9tBgZknXRMTyI4GaJKw</bis:cookie>
  </bis:cookies>
  <bis:query-params/>
  <bis:server-variables>
    <bis:server-variable name="BIS_ROOT_PATH">
/acubis10/samples
    </bis:server-variable>
    <bis:server-variable name="HTTP_ACCEPT">*/*</bis:server-variable>
    <bis:server-variable name="HTTP_ACCEPT_LANGUAGE">
en-us
    </bis:server-variable>
    <bis:server-variable name="HTTP_REFERER">
http://tex-mikes-centos54/acubis10/samples/sample3/
    </bis:server-variable>
    <bis:server-variable name="HTTP_SOAPACTION">
"http://tempuri.org/bis/samples/action/Calculator.Add"
    </bis:server-variable>
    <bis:server-variable name="CONTENT_TYPE">
text/xml; charset="UTF-8"
    </bis:server-variable>
    <bis:server-variable name="HTTP_ACCEPT_ENCODING">
gzip, deflate
    </bis:server-variable>
    <bis:server-variable name="HTTP_USER_AGENT">
 Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0; WOW64; Trident/4.0; GTB6.5; SLCC1; .NET CLR 2.0.50727; .NET CLR 3.5.30729; InfoPath.2; OfficeLiveConnector.1.3; OfficeLivePatch.0.0; .NET CLR 1.1.4322; MS-RTC EA 2; MS-RTC LM 8; .NET CLR 3.0.30729)
    </bis:server-variable>
    <bis:server-variable name="HTTP_HOST">
tex-mikes-centos54
    </bis:server-variable>
    <bis:server-variable name="CONTENT_LENGTH">613</bis:server-variable>
    <bis:server-variable name="HTTP_CONNECTION">
Keep-Alive
</bis:server-variable>
    <bis:server-variable name="HTTP_CACHE_CONTROL">
no-cache
    </bis:server-variable>
    <bis:server-variable name="HTTP_COOKIE">
cookies=true; BISKIT=Vos9tBgZknXRMTyI4GaJKw
    </bis:server-variable>
    <bis:server-variable name="PATH">
/usr/kerberos/sbin:/usr/kerberos/bin:/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/root/bin
    </bis:server-variable>
    <bis:server-variable name="SERVER_SIGNATURE"></bis:server-variable>
    <bis:server-variable name="SERVER_SOFTWARE">
Apache/2.2.14 (Unix) mod_ssl/2.2.14 OpenSSL/0.9.8l
    </bis:server-variable>
    <bis:server-variable name="SERVER_NAME">
tex-mikes-centos54
    </bis:server-variable>
    <bis:server-variable name="SERVER_ADDR">10.64.26.41</bis:server-variable>
    <bis:server-variable name="SERVER_PORT">80</bis:server-variable>
    <bis:server-variable name="REMOTE_ADDR">10.64.26.22</bis:server-variable>
    <bis:server-variable name="DOCUMENT_ROOT">
/usr/local/apache22/htdocs
    </bis:server-variable>
    <bis:server-variable name="SERVER_ADMIN">
michael.schultz@microfocus.com
    </bis:server-variable>
    <bis:server-variable name="SCRIPT_FILENAME">
/var/local/acubis10/samples/sample3/calculator.srf
    </bis:server-variable>
    <bis:server-variable name="REMOTE_PORT">63994</bis:server-variable>
    <bis:server-variable name="GATEWAY_INTERFACE">CGI/1.1</bis:server-variable>
    <bis:server-variable name="SERVER_PROTOCOL">HTTP/1.1</bis:server-variable>
    <bis:server-variable name="REQUEST_METHOD">POST</bis:server-variable>
    <bis:server-variable name="QUERY_STRING"></bis:server-variable>
    <bis:server-variable name="REQUEST_URI">
/acubis10/samples/sample3/calculator.srf
    </bis:server-variable>
    <bis:server-variable name="SCRIPT_NAME">
/acubis10/samples/sample3/calculator.srf
    </bis:server-variable>
    <bis:server-variable name="HTTP_URL">
/acubis10/samples/sample3/calculator.srf
    </bis:server-variable>
  </bis:server-variables>
</bis:request>
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Windows/UNIX Portability Considerations

BIS is designed to allow web applications and services to be portable between Windows and UNIX-based web servers and operating systems. This means that, with some care, the developer can produce stencils (that is, .srf files) and service programs that do not depend on platform-specific features or characteristics and are, thus, portable. If a portable application is the goal, the following issues must be considered.

  • The Handler tag is required for all platforms; however the parameter has no effect when rendered on UNIX. For portability, specify {{ Handler * }}.
  • Pathnames referenced by stencils and service programs are subject to the differences between Windows and UNIX file naming conventions/rules. If portability is an objective, they must be chosen carefully. In particular, UNIX file naming is case-sensitive, and Windows is not. This means that a portable application should be consistent in its use of case within file names, and the files themselves should be named in accordance with that consistent use.

    If there is any possibility that a BIS application will be moved between UNIX and Windows, it is a good practice to restrict filenames to all lower-case names without any embedded spaces.

  • Pathnames are also subject to the different conventions regarding the directory edge-name separator (/ vs. \). In order to enable portable .srf files, BIS allows the / to be used on both Windows and UNIX everywhere except in the Handler tag. If portability is the goal, the \ character should not be used as a pathname separator.
  • There are a few features that are implemented in BIS/IIS on Windows, but have not yet been implemented on UNIX. These are called out with the [image] icon in the section of this document where the feature is described.
  • Newer versions of BIS support tags that may not be recognized by older versions.

No application should be assumed to be portable unless it has been tested in every environment to which it is expected to be deployed.

Parent topic: Xcentrisity Business Information Server for extend User's Guide


Regular Expression Syntax

Regular expressions may be used in the MATCH and SUBSTITUTE parameters of the Value tag.

  • Metacharacters
  • Abbreviations
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Metacharacters

This table lists the metacharacters that may be used in {{Value(…MATCH= regexp )}} and {{Value(…SUBSTITUTE= regexp )}}.

Metacharacter | Meaning
. | Matches any single character.
[ ] | Indicates a character class. Matches any character inside the brackets (for example, [abc] matches a, b, and c).
^ | If this metacharacter occurs at the start of a character class, it negates the character class. A negated character class matches any character except those inside the brackets (for example, [^abc] matches all characters except a, b, and c). If ^ is at the beginning of the regular expression, it matches the beginning of the input (for example, ^[abc] will only match input that begins with a, b, or c).
- | In a character class, indicates a range of characters (for example, [0-9] matches any of the digits 0 through 9).
? | Indicates that the preceding expression is optional: it matches once or not at all (for example, [0-9][0-9]? matches 2 and 12).
+ | Indicates that the preceding expression matches one or more times (for example, [0-9]+ matches 1, 13, 666, and so on).
* | Indicates that the preceding expression matches zero or more times.
??, +?, *? | Non-greedy versions of ?, +, and *. These operators match as little as possible, unlike the greedy versions which match as much as possible. Example: given the input <abc><def>, <.*?> matches <abc> while <.*> matches <abc><def>.
( ) | Grouping operator. Example: (\d+,)*\d+ matches a list of numbers separated by commas (such as 1 or 1,23,456).
{ } | Indicates a match group.
\ | Escape character: interpret the next character literally (for example, [0-9]+ matches one or more digits, but [0-9]\+ matches a digit followed by a plus character). Also used for abbreviations (such as \a for any alphanumeric character; see the table below). If \ is followed by a number n , it matches the n th match group (starting from 0). Example: <{.*?}>.*?</\0> matches <head>Contents</head>.
$ | At the end of a regular expression, this character matches the end of the input. Example: [0-9]$ matches a digit at the end of the input.
| | Alternation operator: separates two expressions, exactly one of which matches (for example, T|the matches The or the).
! | Negation operator: the expression following ! does not match the input. Example: a!b matches a not followed by b.
Parent topic: Regular Expression Syntax


Abbreviations

Abbreviations such as \d instead of [0-9] are allowed. The following abbreviations are recognized:

Abbreviation | Expansion | Matches
\a | ([a-zA-Z0-9]) | Any alphanumeric character
\b | ([ \t]) | White space (blank)
\c | ([a-zA-Z]) | Any alphabetic character
\d | ([0-9]) | Any decimal digit
\h | ([0-9a-fA-F]) | Any hexadecimal digit
\n | (\r|(\r?\n)) | Newline (both Windows and UNIX)
\q | (\"[^\"]*\")|(\'[^\']*\') | A quoted string (either single or double quotes)
\w | ([a-zA-Z]+) | A simple word
\z | ([0-9]+) | An integer
Parent topic: Regular Expression Syntax


Log Files

In order to provide usage information over a long period of time, BIS can create a set of log files in a specific directory. The log files can also be used by the web server administrator or BIS application developer to determine usage patterns of web applications on a BIS server system. The BIS log files consist of variable-length records comprised of space-separated fields. If a field contains spaces or special characters, the field is quoted. If a field is omitted, it is replaced by a dash (-) character.

  • Enabling Log Files
  • Log File Location
  • Log File Format
  • Log Record Types
  • Preventing Log File Creation
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Enabling Log Files

Log files are disabled by default. To enable log files under BIS/IIS, set the following global environment variable:

 BIS_LOG=[ OFF | ON | <directory>]

Where the values are:

OFF
Disables logging - the same as if BIS_LOG is not specified, or is left blank.
ON
Enables logging and directs the log files into the default location, which must not be read-only.
<Directory>
Enables logging and directs the log files into the specified directory. You must ensure that the BIS request handler has write permission for this directory. The directory must be an absolute path or network path. If the specified directory does not exist, BIS will attempt to create it. In this case, the containing directory must exist and BIS must have write permission.

The BIS_LOG variable is only examined when the BIS application pool is started or recycled. After setting or changing BIS_LOG, IIS must be restarted in order for the variable to take effect.

Note that an easy way for an administrator to set or clear this environment variable is with the SETX command. To enter this command at a Windows elevated command prompt:

 setx /M BIS_LOG ON

This enables BIS/IIS logging on Windows. The variable can also be set/cleared with the System Control Panel applet.

Parent topic: Log Files


Log File Location

Under BIS/IIS, the log files are written to the BIS application data directory, normally something like:

C:\Documents and Settings\All Users\Application Data\Micro Focus\extend\10.0.0\LogFiles

On Vista and Windows 2008 Server:

C:\ProgramData\Micro Focus\extend\10.0.0\LogFiles

Each log file has the following name, composed from the UTC time when the log file was created:

yyyyMMddhhmmss.log

On UNIX, the log files are written to the directory specified by the LogDirectory (or LogDir) directive in the /etc/xbis.conf file. This is usually a subdirectory of the configured temp directory, such as:

/var/tmp/bislogs

Each log file has the following name, composed from the date portion of the UTC time when the log file was created:

yyyyMMdd.log
Parent topic: Log Files


Log File Format

Each record begins with a timestamp followed by a record type. The content of the record varies and is dependent on the record type. The general format of each log record is:

timeStamp recordType field1 field2 field3…

where:

timeStamp | The UTC time when this record was created. The format is: yyyyMMddhhmmss. This format can be sorted. Note that the loggerBegin record contains a timeLocal local time field, and this may be used to determine the UTC offset.
recordType | A single character that encodes the record type. See the table below.
Fields | One or more space-separated, variable length fields. The type and order of the fields varies with recordType. If a field contains spaces, the field will be surrounded by double quotes. An embedded double quote character is coded with two consecutive double quotes. A single dash replaces any field with an undefined or unknown value. Numeric values have leading and trailing insignificant zeroes suppressed.

The following table lists the record types, the log level of that type, and the values that each record of the specified type contains. The value codes are defined below.

Code | Level | Record Type | Fields
L | 1 | loggerBegin | versionBIS, versionLog, timeLocal
S | 2 | sessionBegin | idSession, countUses, ipUA, idUA, typeIdUA
V | 3 | serviceBegin | idSession, countUses, ipUA, idUA, typeIdUA, idService, nameService
R | 4 | serviceRequest | idSession, countUses, ipUA, idUA, typeIdUA, idService, lengthRequest
r | 4 | serviceResponse | idSession, countUses, ipUA, idUA, typeIdUA, idService, lengthResponse
v | 3 | serviceEnd | idSession, countUses, ipUA, idUA, typeIdUA, idService, tallyRequests, tallyLengthReq, tallyLengthResp, timeCPU, histIO
s | 2 | sessionEnd | idSession, countUses, ipUA, idUA, typeIdUA, tallyRequests, tallyLengthReq, tallyLengthResp, timeCPU, histIO
l | 1 | loggerEnd | tallyRequests, tallyLengthReq, tallyLengthResp, timeCPU, histIO
Z | - | licenseInfo | idBaseLicense, idSerialNumber, nUseCount, strLicenseKey

where:

Code | A character that indicates the record type.
Record Type | The type of record. Each type is discussed in the table below.
Level | The level of this record type. Future versions of BIS will allow logging to be restricted by level.
Fields | The fields that appear in this type of record. The fields are described in the table below.

The record types are nested: there will normally be a matching sessionEnd record for each sessionBegin record. The licenseInfo record is an exception: this record will occur by itself. For BIS/IIS, the licenseInfo record is written after BIS is loaded and the first service is started. Because much of the BIS subsystem is unloaded after a period of idle time and automatically reloaded on demand, this record may occur more than once in a given log file.

Parent topic: Log Files


Log Record Types

Below are the complete definitions of the various record types.

loggerBegin

Field | Description
versionBIS | The BIS version number, set to the current release.
versionLog | The version number of the log. Set to 1 for the first release.
timeLocal | The local time, in yyyyMMddhhmmss format.

sessionBegin

Field | Description
idSession | The cookie value of the session
countUses | The current user count
ipUA | The IP address of the user agent in dotted quad notation (normally the same as the HTTP_REMOTE_ADDR server variable)
idUA | An MD5 digest of user entity identification information (CERT_SUBJECT, AUTH_USER, or - in order of preference, see typeIdUA)
typeIdUA A two digit code that indicates the degree of authentication/specificity of the user ID, as follows:
  • 00 No AUTH_USER and no CERT_SUBJECT
  • 10 AUTH_USER and (HTTPS = = off)
  • 20 AUTH_USER and (HTTPS = = on) and no CERT_SUBJECT
  • 30 CERT_SUBJECT and no AUTH_USER
  • 40 CERT_SUBJECT and AUTH_USER
This implies CERT_TYPE = 1 (i.e., the certificate is valid). Any other CERT_TYPE is treated as if there is no CERT_SUBJECT.

serviceBegin

Field | Description
idSession | The cookie value of the session
countUses | The current user count
ipUA | The IP address of the user agent in dotted quad notation (normally the same as the HTTP_REMOTE_ADDR server variable)
idUA | An MD5 digest of user entity identification information (CERT_SUBJECT, AUTH_USER, or - in order of preference, see typeIdUA)
typeIdUA A two digit code that indicates the degree of authentication/specificity of the user ID, as follows:
  • 00 No AUTH_USER and no CERT_SUBJECT
  • 10 AUTH_USER and (HTTPS = = off)
  • 20 AUTH_USER and (HTTPS = = on) and no CERT_SUBJECT
  • 30 CERT_SUBJECT and no AUTH_USER
  • 40 CERT_SUBJECT and AUTH_USER
This implies CERT_TYPE = 1 (i.e., the certificate is valid). Any other CERT_TYPE is treated as if there is no CERT_SUBJECT.
idService | ID distinguishing different service instances within the current session
idService | ID distinguishing different service instances within the current session
nameService | Service program name

serviceRequest

Field | Description
idSession | The cookie value of the session
countUses | The current user count
ipUA | The IP address of the user agent in dotted quad notation (normally the same as the HTTP_REMOTE_ADDR server variable)
idUA | An MD5 digest of user entity identification information (CERT_SUBJECT, AUTH_USER, or - in order of preference, see typeIdUA)
typeIdUA A two digit code that indicates the degree of authentication/specificity of the user ID, as follows:
  • 00 No AUTH_USER and no CERT_SUBJECT
  • 10 AUTH_USER and (HTTPS = = off)
  • 20 AUTH_USER and (HTTPS = = on) and no CERT_SUBJECT
  • 30 CERT_SUBJECT and no AUTH_USER
  • 40 CERT_SUBJECT and AUTH_USER This implies CERT_TYPE = 1 (i.e., the certificate is valid). Any other CERT_TYPE is treated as if there is no CERT_SUBJECT
idService | ID distinguishing different service instances within the current session
lengthRequest | Length (in bytes) of the BIS exchange file passed by B_ReadRequest

serviceResponse

Field | Description
idSession | The cookie value of the session
countUses | The current user count
ipUA | The IP address of the user agent in dotted quad notation (normally the same as the HTTP_REMOTE_ADDR server variable)
idUA | An MD5 digest of user entity identification information (CERT_SUBJECT, AUTH_USER, or - in order of preference, see typeIdUA)
typeIdUA A two digit code that indicates the degree of authentication/specificity of the user ID, as follows:
  • 00 No AUTH_USER and no CERT_SUBJECT
  • 10 AUTH_USER and (HTTPS = = off)
  • 20 AUTH_USER and (HTTPS = = on) and no CERT_SUBJECT
  • 30 CERT_SUBJECT and no AUTH_USER
  • 40 CERT_SUBJECT and AUTH_USER
This implies CERT_TYPE = 1 (i.e., the certificate is valid). Any other CERT_TYPE is treated as if there is no CERT_SUBJECT.
idService | ID distinguishing different service instances within the current session
lengthResponse | Length (in bytes) of the BIS exchange file passed by B_WriteResponse

serviceEnd

Field | Description
idSession | The cookie value of the session
countUses | The current user count
ipUA | The IP address of the user agent in dotted quad notation (normally the same as the HTTP_REMOTE_ADDR server variable)
idUA | An MD5 digest of user entity identification information (CERT_SUBJECT, AUTH_USER, or - in order of preference, see typeIdUA)
typeIdUA A two digit code that indicates the degree of authentication/specificity of the user ID, as follows:
  • 00 No AUTH_USER and no CERT_SUBJECT
  • 10 AUTH_USER and (HTTPS = = off)
  • 20 AUTH_USER and (HTTPS = = on) and no CERT_SUBJECT
  • 30 CERT_SUBJECT and no AUTH_USER
  • 40 CERT_SUBJECT and AUTH_USER
This implies CERT_TYPE = 1 (i.e., the certificate is valid). Any other CERT_TYPE is treated as if there is no CERT_SUBJECT.
idService | ID distinguishing different service instances within the current session
tallyRequests | The number of requests processed by the service
tallyLengthReq | Total length (in bytes) of the BIS exchange files passed by B_ReadRequest
tallyLengthResp | Total length (in bytes) of the BIS exchange files passed by B_WriteResponse
timeCPU | Total CPU time in milliseconds used by this service or -, if not available
histIO | IO request counts used by this service represented by three integers: # of open operations, # of read operations, # of writes/rewrites/delete operations

sessionEnd

Field | Description
idSession | The cookie value of the session
countUses | The current user count
ipUA | The IP address of the user agent in dotted quad notation (normally the same as the HTTP_REMOTE_ADDR server variable)
idUA | An MD5 digest of user entity identification information (CERT_SUBJECT, AUTH_USER, or - in order of preference, see typeIdUA)
typeIdUA A two digit code that indicates the degree of authentication/specificity of the user ID, as follows:
  • 00 No AUTH_USER and no CERT_SUBJECT
  • 10 AUTH_USER and (HTTPS = = off)
  • 20 AUTH_USER and (HTTPS = = on) and no CERT_SUBJECT
  • 30 CERT_SUBJECT and no AUTH_USER
  • 40 CERT_SUBJECT and AUTH_USER
This implies CERT_TYPE = 1 (i.e., the certificate is valid). Any other CERT_TYPE is treated as if there is no CERT_SUBJECT.
tallyRequests | The number of requests processed by the service
tallyLengthReq | Total length (in bytes) of the BIS exchange files passed by B_ReadRequest
tallyLengthResp | Total length (in bytes) of the BIS exchange file passed by B_WriteResponse since the start of this session
timeCPU | Total CPU time in milliseconds used by services since the start of this session or -, if not available
histIO | IO request counts accumulated since the start of this session represented by three integers: # of open operations, # of read operations, # of writes/rewrites/delete operations

loggerEnd

Field | Description
tallyRequests | The number of requests processed since the start of this log
tallyLengthReq | Total length (in bytes) of the BIS exchange file passed by B_ReadRequest since the start of this log
tallyLengthResp | Total length (in bytes) of the BIS exchange file passed by B_WriteResponse since the start of this log
timeCPU | Total CPU time in milliseconds used by services since the start of this log or -, if not available
histIO | IO request counts accumulated since the start of this log represented by three integers: # of open operations, # of read operations, # of writes/rewrites/delete operations

licenseInfo

Field | Description
idBaseLicense | The base license ID from the Service Engine license file.
idSerialNumber | The serial number from the Service Engine license file.
nUseCount | The use count from the Service Engine license file.
strLicenseKey | The contents of the WebServer license key.
Parent topic: Log Files


Preventing Log File Creation

The BIS logging service is disabled by default. It is only enabled if you set the BIS_LOG system-wide environment variable. The values for BIS_LOG are:

  • OFF - Disables logging (the same as if BIS_LOG is not specified or is blank).
  • ON - Enables logging and directs the log files into the default location, which is guaranteed to be writable.
  • <directory> - Enables logging and directs the log files into the specified directory. The user must ensure that it is writable by the BIS request handler.

    The directory must be an absolute path or network path. If the specified directory does not exist, BIS attempts to create it. Note that the containing directory must exist.

The BIS_LOG variable is only examined when the BIS application pool is started or recycled. Be sure to restart IIS after changing this variable so it takes effect.

Parent topic: Log Files


BIS Troubleshooting Tips

This Appendix outlines the symptoms of some common abnormal conditions, and provides insight as to the possible cause(s) and corrective action(s).

Before troubleshooting, if you are using Internet Explorer, be sure that the Show Friendly HTTP error messages option is not checked. This option can be found in Tools > Internet Options > Advanced > Browsing in either Internet Explorer or Control Panel > Internet Options.

  • Symptom:
    Server Error in Application "Default Web Site/acubis10"

HTTP Error 500.0 - Internal Server Error
Description: Handler "AboMapperCustom-24582078" has a bad module
     "IsapiModule" in its module list
Error Code: 0x8007000d
Notification: ExecuteRequestHandler
Module: IIS Web Core
Requested URL: http://localhost:80/acubis10/samples/default.srf?trace=page
Physical Path: C:\inetpub\wwwroot\acubis10\samples\default.srf

Logon User: Anonymous
Logon Method: Anonymous
Handler: AboMapperCustom-24582078
  • Possible Cause: Indicates that IIS ISAPI extension support is not installed.
  • Suggestion: In Windows Vista or Windows 2008 Server, start Programs and Features in the Windows control panel, and ensure that ISAPI Extensions are enabled (that is, the option is checked) under Internet Information Services > World Wide Web Services > Application Development Features.
  • Symptom:
    Business Information Server Error
An error occurred while BIS was processing your request. Additional
information is below.
XMLExchange failed: the service program returned error
"80004004", which is "Operation aborted". The session has ended.
  • Possible Cause: Indicates that there was a problem starting the Service Engine.
  • Suggestion: To narrow the problem, turn on tracing by adding this tag to your .srf file:
    {{ Trace(start, page) }}

    Then, refresh the page. You should now see a table headed Request Details at the end of the page. Scroll down to Trace Information and look for Service in the left-most column.

    The BIS samples are pre-configured for tracing and tracing may be turned on and off with a query parameter defined in the Trace tag. For example, if the problem occurred running the VERIFYBIS program, log into the server running BIS and use this URL:

    http://localhost/acubis10/verify/default.srf?trace=page

    Trace output will appear at the bottom of the page, and this will include the BIS Service Engine startup messages that should reveal the problem.

  • Symptom: An error 500 occurs.
  • Possible Cause: A replacement tag precedes the Handler tag.
  • Suggestion: The only tags allowed before the Handler tag are comment tags. Move all tags that precede the Handler tag to follow it.
  • Symptom: One of the following error messages is reported:
    Cannot create the trace file for session "nH6shZykCtbZmdDZHo0LhJhiVSq5" (the last attempted filename is "D:\Documents and Settings\UserID\Local Settings\Temp\BIS-nH6s-trace.txt"). The last error code was 80070005

Cannot reopen the trace file for session "nH6shZykCtbZmdDZHo0LhJhiVSq5" (the last attempted filename is "D:\ Documents and Settings\UserID\Local Settings\Temp\BIS-nH6s-trace.txt"). The last error code was 80070005

Could not write the trace file to the directory "D:\ Documents and Settings\UserID\Local Settings \Temp\": the error code was 80004005.
  • Suggestion: To correct this error, give the IWAM_* account write access to this directory. See the Troubleshooting appendix in the User's Guide for more information.
  • Symptom: The following error message appears in the web browser:
    Server Error
LoadLibrary failed.
  • Possible Cause: The Handler tag is missing, invalid, or refers to a missing or invalid library.
  • Suggestion: Make sure that your .srf page has a {{ Handler * }} tag, and that this tag is the first non-comment/non-include tag in the file. For Windows, it must also appear in the first 4096 characters of the .srf file.
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Configuring BIS/IIS after Installation

The Business Information Server Service Engine must be registered with Windows. If it becomes necessary to re-register the server, registration can be performed:

  • by reinstalling BIS/IIS (choose the Repair option), or
  • from the command line

This section describes how to configure the BIS/IIS Service Engine from the command line.

  • Command Line Configuration
  • Configuring the Run As Logon ID
  • Retrieving or Changing the Configured Identity
  • Manual Configuration
  • Setting Environment Variables
  • Setting the Maximum Thread Count
  • Notes
  • Enabling BIS Logging
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Command Line Configuration

BIS is self-registering. Registration is performed by the XBIS.EXE program, which can be found in the installation directory (normally C:\Program Files\Micro Focus\extend x.x.x\AcuGT\bin ). Registration includes these three steps:

  • The BIS Service Engine contained in XBIS.EXE is registered.
  • The Run As identity, that is, the identity that will be used to execute service programs, is set.

The server registration syntax is:

XBIS registration-options

The registration options are detailed below:

/REGSERVER | Registers the Service Engine. Also registers the runtime system located in the same directory as XBIS.EXE.
/UNREGSERVER | Unregisters the BIS Service Engine and the runtime system.
/SHOWSERVER | Displays a dialog box that shows the location of the currently registered BIS and Service Engine.

The server registration option has three additional variations:

/REGSERVERQ | Quietly registers the BIS Service Engine and the runtime system located in the same directory as XBIS.EXE. No confirmation dialog box is displayed .
/REGSERVERO | Only registers the BIS Service Engine. The runtime system registration remains unchanged. This is useful if you want to install the runtime system in a directory separate from the BIS Service Engine.
/REGSERVERQO | Combines the above two options.

The /REGSERVER and /REGSERVERQ options have an additional optional parameter: the pathname of the runtime system or the directory containing the runtime system. It is specified as in these examples:

1. /REGSERVER:pathname
2. /REGSERVERQ:pathname
3. /REGSERVER:directory
4. /REGSERVERQ:directory

If the pathname or directory is specified, the specified file or the server in the specified directory is registered and BIS does not search for the runtime system in the path.

If a directory is specified, it may end with a trailing backslash to differentiate it from a filename. Also note that if the specified name contains spaces, it must be surrounded by single or double quotes.

Parent topic: Configuring BIS/IIS after Installation


Configuring the Run As Logon ID

To execute service programs, Business Information Server must assume the identity of a user authorized to run the programs and access data files required by the programs. This is accomplished by specifying a Logon ID during installation, reinstallation, or server registration.

The Run As identity may be configured during registration interactively with a dialog box, or by specifying options on the command line.

Note that the /RUNAS options below must be specified along with one of the /REGSERVER options described above.

If none of the options in the table below are specified, the server displays the Run As configuration dialog box on the right even if /REGSERVERQ (quiet mode) is specified.

The Run As dialog box has three options that determine the context in which BIS will execute:

/RUNASI

/RUNASIP

Causes the server to run as the INTERACTIVE USER. This is the identity of the user that is logged on to the server's console. This is most useful for developers but is not recommended for deployment.

If the P suffix is specified, BIS prompts for credentials using the dialog box if an error occurs.

/RUNASL

/RUNASLP

Runs the server under the identity of the launching (usually anonymous) user. This will normally be the account named IUSR_machinename, where machinename is the name assigned to the machine.

For example, if your machine is named HILO, the anonymous user's name is IUSR_HILO. It is possible for a system administrator to change this, either for all IIS accounts or for just the BIS. If the name of the machine was changed after IIS was installed, this will be the original name of the machine, not the current name. In this case, please see Manual Configuration, below.

Note that this account usually has very limited privileges and BIS will not even be able to start unless you manually give this account write permission in the BIS installation directory. BIS will not be able to access files in other directories, unless you also give it access to those directories, and will not be able to access files on any network volumes unless your machine is joined to a domain and this name is known to the domain server. See your system administrator for details.

If the P suffix is specified, BIS prompts for credentials using the dialog box if an error occurs.

/RUNAS: id, pw

/RUNASP: id, pw

Runs the server using the specified identity. This is the recommended option. id is the login ID and pw is the password. The password is encrypted by Windows, is stored in the registry, and is not retrievable as plain text once the server is registered. However, caution is required when embedding a clear-text password in a batch file that issues the /RUNAS command.

If an id is specified without a pw , the program prompts for the password. This may be a good compromise between convenience and security.

Either the pw id or the pw may be quoted with single or double quotes (required if either contains spaces). The entire parameter string may also be quoted.

Examples:

/RUNAS:myuserid, mypassword
/RUNAS:”my user id”,”my password”
/RUNAS:”my user id,my password”
/RUNAS:”INTERACTIVE USER”

As a special case, the special logon ID of INTERACTIVE USER is recognized and handled as if /RUNASI were specified. Any password is ignored, and quotes are required due to the embedded space.

If the P suffix is specified, BIS prompts for credentials using the dialog box if an error occurs.

Parent topic: Configuring BIS/IIS after Installation


Retrieving or Changing the Configured Identity

The Windows Component Services configuration utility may be used to examine and change the current Business Information Server configuration.

There are two ways to start the utility:

  • Select Start > Control Panel > Administrative Tools > Component Services. (Alternatively, select Start > Run, enter dcomcnfg in the Open box, and click the OK button.)
  • Select Start > Control Panel > Administrative Tools > Component Services. The program should look like this:

    1. Find Xcentrisity Business Information Server xx in the list, right-click, and select Properties from the popup menu.

    2. Click the Identity tab. The dialog box depicted below displays the current Run As configuration.

      Note that you can change the identity and/or the password that BIS/IIS uses to run service programs here.

Parent topic: Configuring BIS/IIS after Installation


Manual Configuration

To manually change the user ID and password that the Service Engine uses to execute programs, follow these steps after completing the installation:

  1. Select Start > Control Panel > Administrative Tools > Component Services.

    Alternatively, select Start > Run, enter dcomcnfg in the Open box, and click the OK button.

  2. Expand Console Root > Component Services > My Computer > DCOM Config. The program should look like this:

  3. Locate Xcentrisity Business Information Server xx in the list, right-click, and select Properties from the popup menu.
  4. Click the Identity tab, then This user. Enter the user ID and the password that you want to use to run service programs under Business Information Server. Then click the Apply button.
  5. Click the Security tab and under Launch Permissions, click Customize and then click Edit. Click Add and enter the name of your anonymous internet account (see below). Click the Add button; make sure Allow is checked next to Launch Permission and click OK. Then click Apply.
  6. Still on the Security tab, repeat the above step for Access Permissions.
  7. You do not need to change Configuration Permissions. Click OK to close the dialog box.

The name of your anonymous internet account is normally IUSR_machine, where machine is the hostname assigned to your machine. However, the system administrator can change the name of this account, and this is common if you are running more than one web site.

To determine the name of your anonymous internet account:

  1. Select Start > Control Panel > Administrative Tools > Internet Information Services.
  2. Expand Internet Information Services > Local Computer > Web Sites > Default Web Site. (Replace the last node with your site if IIS is serving multiple web sites).
  3. Find the web application that was created to contain the BIS service program. This will be acubis10 for the sample program. Right-click that node and select Properties.
  4. Click Directory Security, then Edit.
  5. The User Name box contains the name of the anonymous account that you can enter above.

Note that the above configuration is very flexible. You can control what users will have access to the COBOL program on a site-by-site, or even a directory-by-directory basis on your web site.

Alternatively, instead of specifying IUSR_machine, you can specify GUEST, or any other group that contains all your anonymous access accounts. However, be cautious before granting too many privileges to too many anonymous processes.

Parent topic: Configuring BIS/IIS after Installation


Setting Environment Variables

Some BIS settings are set from the server environment. To set a BIS environment variable:

  • Log in as Administrator, or an account that is a member of the Administrators group.
  • Click Start > Control Panel > System.
  • Click the Advanced tab.
  • Click the Environment Variables button.
  • Under System Variables, click the New button. Alternatively, if the environment variable has already been set, click the variable name in the list box and then click the Edit button.
  • Enter the variable name and the value and select OK.
  • When done, click OK to dismiss the dialog box.

The changes take effect immediately.

Parent topic: Configuring BIS/IIS after Installation


Setting the Maximum Thread Count

BIS uses a system resource called a Thread to render pages. For efficiency, BIS maintains an internal pool of threads, and when a request for a BIS page arrives, a thread from the pool is dispatched to serve the page. When the page is completely rendered, the thread returns to the pool to await the next request.

If there are no available threads in the pool, the request must wait for a thread to become available. A request will wait for some period of time (normally about 60 seconds) before being denied with a server too busy error page.

BIS pages that do not communicate with the Service Engine normally execute very quickly. However, if a page contains an XMLExchange tag, the BIS thread serving that page must wait until the Service Engine provides the replacement text for the XMLExchange tag. If this is a lengthy process, it is conceivable that BIS will not have enough threads to serve all pending requests. In this case, it may be desirable to increase the size of the BIS thread pool so more pages can be rendered simultaneously.

The BIS_MAX_THREADS environment variable may be used to increase (or decrease) the size of the thread pool. The syntax is:

BIS_MAX_THREADS=value

where:

n Is an integer that specifies the number of threads that will be used by BIS to service requests.
Parent topic: Configuring BIS/IIS after Installation


Notes

  • Since each BIS thread requires system resources, even when idle, it is not desirable to set this value to a large number. The default value, 5 threads, is sufficient for a moderately busy server and should only be increased if requests are being denied or users are waiting for their requests to be serviced.
  • BIS dynamically creates additional threads for each Service Engine started by the StartService tag. These Service Engine threads do not count against the BIS_MAX_THREADS value.
  • The BIS_MAX_THREADS option is only examined when the BIS Request Handler is loaded. The handler is loaded on demand, for example, when the first BIS request arrives after a server restart, and then the handler is automatically unloaded after about 20 minutes of inactivity.
  • The current setting can be retrieved with Value(MaxThreads, Config). On UNIX, this always returns 1.
Parent topic: Configuring BIS/IIS after Installation


Enabling BIS Logging

In current versions of BIS, log files are only written if this feature is enabled.

Under IIS, the BIS_LOG system environment variable controls this behavior:

  BIS_LOG=[ OFF | ON | <directory> ]

Valid values include:

  • OFF disables logging (the same as if BIS_LOG is not specified or is blank).
  • ON enables logging and directs the log files into the default location, which is guaranteed to be writable.
  • <directory> enables logging and directs the log files into the specified directory. The user must ensure that it is writable by the BIS request handler.

    The directory must be an absolute path or network path. If the specified directory does not exist, BIS attempts to create it. Note that the containing directory must exist.

    The BIS_LOG variable is only examined when the BIS application pool is started or recycled. Be sure to restart IIS after changing this variable so it takes effect.

BIS logging can also be configured from an elevated command prompt:

setx /M BIS_LOG ON

This command enables BIS logging. Replace ON with OFF to disable logging, or a quoted absolute directory name to enable logging in a specific directory.

Parent topic: Configuring BIS/IIS after Installation


Configuration after Installation (UNIX/Apache)

  • Configuring Apache
  • Service Engine Configuration
  • xbisctl Utility
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Configuring Apache

The Apache configuration file for BIS is named mod_xbis.conf and is included in the Apache server configuration by an Include directive placed in the main httpd.conf configuration file. This shows the Include directive.

1Include /opt/microfocus/acuxxx/etc/mod_xbis.conf

If available, copy or link the mod_xbis.conf file to the /etc/httpd/conf.d directory. This circumvents the necessity of editing the main httpd.conf configuration file.

The BIS Configuration File

The BIS configuration file contains several sets of Apache configuration directives. The first set of directives configures Apache direct requests to the BIS Request Handler module. This sample shows this set of directives.

LoadFile                /opt/microfocus/acuxxx/lib/libxml.so
LoadModule xbis_module  /opt/microfocus/acuxxx/lib/mod_xbis22.so
AddHandler bis-stencil  srf
AddType    text/html    srf
AddType    text/x-component .htc

The LoadFile directive is required and should not be changed. It causes Apache to dynamically load the shared object containing the BIS Request Handler's XML parser when Apache starts.

The LoadModule directive is required and should not be changed. It causes Apache to dynamically load the shared object containing the BIS Request Handler when Apache starts.

The AddHandler directive causes all URIs that request files ending with srf to be processed by the BIS Request Handler. If it is desired to have the Request Handler process requests with other file extensions, add additional AddHandler directives.

The AddType directive causes the default content type of a response for a URI ending with srf to be text/html. An AddType directive should be added for each AddHandler directive added to serve an addition file extension.

The AddType directive for the .htc extension is necessary to cause Apache to serve HTML Components files (a Microsoft extension) with the correct content type.

These directives affect the amount and location of trace information produced by BIS.

BISTraceDirectory /var/xbis
BISTraceFile trace.log
BISKeepTraceFiles Off
BISTruncateTraceFile Off
BISTraceSuffix Page
BISMasterTrace On
BISMainDebug On
BISStencilDebug On
BISSEDebugLevel 0

The BISTraceDirectory directive specifies the directory where trace files are written. The default is /var/xbis. If this directive does not specify an absolute path, it is assumed to be relative to a default (/tmp on some systems).

The BISTraceFile directive indicates the name of the trace file. This directive should only be used when all tracing for all requests are written to the same file. If this directive does not specify an absolute path, it is relative to the directory specified by BISTraceDirectory.

The BISKeepTraceFiles directive controls whether trace files are kept after a session completes. The value of Off is the default, and it causes trace files to be deleted, unless a FILE option in a Trace tag (in a stencil file) requests that they be kept. The value of On causes trace files to be retained regardless of the presence of a FILE trace option.

The BISTruncateTraceFile directive controls whether trace files are truncated at the beginning of each request. The value of Off is the default and causes all requests of a session to be placed in the trace file. The value of On cause only the last request of the session to be placed in the trace file.

The BISTraceSuffix directive adds additional options to Trace tags (in a stencil file) whenever one is processed. The value of this directive is processed after the options specified in the Trace tag, but before the options specified in the trace query parameter. There is no default for this directive. The options are described in the Trace tag section. All Trace tag options are allowed.

The BISMasterTrace directive is a master switch that controls all tracing activity. The value of Off is the default and will prevent all tracing. This is the appropriate value for a production environment. The value of On allows tracing to occur.

The BISMainDebug directive controls tracing of tags as they are executed. The value of Off is the default and prevents trace messages. The value of On allows trace messages during execution of the stencil. This tracing approximates the tracing performed by BIS/IIS.

The BISStencilDebug directive controls tracing tags as they are parsed. The value of Off is the default and prevents trace messages. The value of On will cause trace messages diagnosing syntax errors in tags to be produced.

The BISSEDebugLevel directive controls tracing of the BIS Service Engine. The values are 0, 1, and 2. 0 is the normal level of tracing and is appropriate for seeing DISPLAY statements from the service program. 1 and 2 supply additional tracing and should only be used when directed by customer support.

BISRefreshDirectory /var/tmp/xbis.refresh

The BISRefreshDirectory directive names a directory where server responses are stored temporarily, in case the client user agents such as web browsers request a refresh (see the XMLExchange tag.) The indicated directory should have permissions which allow create, reading, write, and delete access by the Apache child process. If no directory is named, or if this directive is omitted, the BIS Request Handler will not attempt to provide correct responses to refresh requests which lead to unnecessary session sequence errors.

BISErrorMessage ErrorName Error Text

The BISErrorMessage directive overrides the text for one of the BIS Request Handler's error messages. One reason to do this is to provide error messages in a language other than English. The first operand of the directive is the name of the error to be overridden. The remainder of the directive is the new text to be displayed when ErrorName is encountered. The current set of the Request handler's error names and their text are present within mod_xbis.conf as commented out BISErrorMessage directives.

BISSesDaemonKey xxxxxxxx

The optional BISSesDaemonKey directive allows the shared memory key with which to contact the Service Engine to be specified. This directive should only be used when it is desired to run multiple Service Engine daemons on the same UNIX server. This is rare. The value is an 8-hex digit value that must match the SharedMemory option keyword of the configuration of the Service Engine to use.

Alias URL-Path Directory-Path

This standard Apache directive allows stencils (as well as other documents) to be served from directories outside of the Apache web server's document root. The URL-Path value is a string that is to be matched to the leading part of the path of desired URLs. When a match occurs, it is removed and replaced with the Directory-Path value to produce the actual file name of the requested document. When an Alias directive is used, create a corresponding Directory directive to specify additional configuration directives for the directory named Directory-Path.

<Directory Directory-Path>
    SetEnv BIS_ROOT_PATH /xbisvc22/samples
    SetEnv TEMP /var/xbis
    DirectoryIndex default.srf
</Directory>

This set of standard Apache directives demonstrates tailoring Apache directives to document directories. The Directory-Path value is the name of the directory to which the directives apply.

The SetEnv directives demonstrate setting server environment variables. The value of such a variable is available in a stencil in a Value tag. It is also available by enclosing its name between "%" characters. In the above example, %TEMP% in a stencil served from this directory would be replaced by /var/xbis.

The DirectoryIndex directive specifies the name of the default document to serve if only the directory name is specified in the requested URL.

Parent topic: Configuration after Installation (UNIX/Apache)
1 xxx represents the version of extend that you are running


Service Engine Configuration

The BIS Service Engine runs as a UNIX daemon process and one or more service processes which the daemon creates, as needed. There are always one or more idle service processes waiting for the Request Handler (the Apache part) to process a StartService tag.

Because the Service Engine runs as daemon, it normally starts when the operating starts, without any direct user interaction. It gets all of its options from a configuration file, its command line and its environment. The configuration file is usually named /etc/xbis.conf, but this can be changed by the ?f command-line option. Each line in the configuration file is either a blank line, comment line or an option line. A comment line is a line in which the first nonblank character is a # character. On an option line, the line begins with a keyword, which is followed by one or more spaces or tabs and then by the option value. A # character may follow the option value to introduce an in-line comment.

The configuration file option keywords are:

BinDir | Specifies the name of the directory where the BIS binary executable files are located. There is no reason for a user to alter this parameter after installation.
LibDir | Specifies a colon separated list of directory names that will be placed into the standard search path environment variable for the UNIX platform when the Service Engine is started. Usually the environment variable is LD_LIBRARY_PATH, but it is LIBPATH for AIX, SHLIB_PATH for 32-bit HP-UX, and LD_LIBRARY_PATH_64 for 64-bit Solaris. The value of this option is prepended to the current value of the library search environment variable. There is no reason for a user to alter this parameter after installation.
LogDir | Specifies the name of the directory where the BIS log files are placed.
MaxChildren | Specifies the maximum number of service (child) processes. This is normally set to 250.
MaxSessions | Specifies the maximum number of BIS sessions. It defaults to twice the MaxChildren value.
PageSize | Specifies the amount of space allocated in the Sessions file for each session. This holds the information about a session between requests. It must be a power of two and it must be at least 512 but no more than 16384. It defaults to 2048, which should be sufficient unless your stencils define unusually long paths or a large number of environment variables.
SaveFiles | If specified, copies of all request and response files are saved in the temporary directory. This is a debugging tool, typically used during development of a web site.
ServiceTimeout | Default service timeout, in seconds. This is the preferred way to set the default service timeout. If BIS_SERVICE_TIMEOUT is set in the Apache configuration file for BIS (bis.conf), the Request Handler uses that value to override the value of the -T option. Doing so delays the start of each service program slightly.
SharedMemory | If present, specifies the shared memory key that the Service Engine is to use. This directive should only be used when it is desired to run multiple Service Engine daemons on the same UNIX server. The value is an 8-hex digit value that must be matched by the value BISSesDaemonKey directive in use by the Request Handler. Only specify this keyword option when directed by Micro Focus Technical Support.
Socket | Specifies the name of the socket used by the Request Handler to communicate with the Service Engine daemon. There is no reason for a user to alter this parameter after installation.
TempDir | Specifies the name of the directory where temporary files are created.
UserName | Specifies the UNIX user name used by each service (child) processes. Although the Service Engine daemon process runs as root, each of the child service processes runs as the user specified by this option. This determines the files that a service process can read and write, as well as the home directory of each service process.

Options on the Service Engine daemon's command line may modify the configuration as determined by the configuration file and the built-in defaults. The command-line options are in a string that is assigned to an environment variable named OPTIONS. All of the Service Engine's environment variables, including OPTIONS, are set in a file named /etc/sysconfig/xbis. This file is created during the install of BIS.

The command-line options are:

-f file | Specifies the name of the Service Engine configuration file. If this option is present, it must be the first option on the command line. If omitted, the configuration file name defaults to /etc/xbis.conf.
-c count | Specifies the maximum number of service (child) processes. This is normally set to 9999 to indicate that the number of service processes is limited only by the license, but it may be set to a smaller value as a throttle.
-i count | Specifies the number of idle service (child) processes. This is normally set to 1 but a small increase in this may improve response time on a server which receives many requests in rapid succession.
-T timeout | Default service timeout, in seconds. This is the preferred way to set the default service timeout. If BIS_SERVICE_TIMEOUT is set in the Apache configuration file for BIS (bis.conf), the Request Handler uses that value to override the value of the -T option. Doing so delays the start of each service program slightly.
-u user | Specifies the UNIX user name used by each service (child) processes. Although the Service Engine daemon process runs as root, each of the child service processes runs as the user specified by this option. This determines the files that a service process can read and write, as well as the home directory of each service process.
-t dir | Specifies the name of the directory where temporary files are created.
-r | If specified, copies of all request and response files are saved in the temporary directory. This is a debugging tool, typically used during development of a web site.
-L file | Specifies the name of the Service Engine event log file. The Service Engine records certain important events in this file. This is a debugging tool.
-s file | Specifies the name of the socket used by the Request Handler to communicate with the Service Engine daemon. There is no reason for a user to alter this parameter after installation.
-U file | Specifies the name of a file used by the Service Engine daemon to communicate with the Request Handler. There is no reason for a user to alter this parameter after installation.

If the BIS Service Engine options need to be changed, the configuration file ( /etc/xbis.conf) may be edited or (on systems other than AIX) the file /etc/sysconfig/xbis may be edited. If the configuration file is changed, the Service Engine can be instructed to reread it by using a kill command to send the Service Engine daemon a SIGHUP signal. However, the Service Engine does not read /etc/sysconfig/xbis directly. Instead, the shell script which starts the Service Engine reads this file. For any changes to take effect, the Service Engine must be restarted, either by restarting the operating system, by changing the runlevel, or by executing the shell script which starts the Service Engine ( /etc/init.d/xbisengd). This script accepts one parameter, which must be one of the following:

Start | Starts the BIS Service Engine.
Stop | Stops the BIS Service Engine.
Restart | Stops the BIS Service Engine, and then starts it again.
Condrestart | If the Service Engine is running, stop it, and then start it again. Otherwise, do nothing.
Status | Displays the status of the Service Engine.

Note that stopping the Service Engine stops all of the service processes immediately, terminating any running service programs. This should not be used when users are connected to the server.

Parent topic: Configuration after Installation (UNIX/Apache)


xbisctl Utility

The xbisctl utility can be used by a root user to control the Service Engine and the BIS Session/Logging daemon. It can also display the BIS sessions and, if necessary terminate a session. The xbisctl utility may be copied or linked to a directory in the user's path; it is located in the bin subdirectory of the directory where BIS was installed.

The xbisctl utility may be run in one of two ways. If no parameters are specified on the command line, it reads commands from standard input. Alternatively, a single command may be specified on the command line. The following table lists the commands that xbisctl recognizes:

Start | Starts the Service Engine and the Session/Logging daemon.
Stop | Stops the Service Engine and the Session/Logging daemon.
Status | Displays a one-line status for Service Engine and the Session/Logging daemon.
Refresh | Refreshes the Service Engine and the Session/Logging daemon. This tells the BIS daemons to reread their configuration file.
Sessions | List the current sessions.
Kill | Terminate a session.
Exit | Stop reading standard input. Alternatively, press ctrl-D to end input.

Status information can be displayed in a browser window. At the end of the supplied mod_xbis.conf file, there are two ScriptAlias directives. Uncomment one or both of these to enable this feature. The path may be changed to suit your needs. These run a shell script that executes the xbisctl utility with the status command on the command line.

Parent topic: Configuration after Installation (UNIX/Apache)


Creating a BIS/IIS Web Application

You can use the BISMkApp program to create and configure a web application that is ready to run a BIS application. The BISMkApp program is installed in:

C:\Program Files\Micro Focus\extend x.x.x\AcuGT\bin

  • Running the BISMkApp Program
  • Creating the Web Application
  • Testing the New Directory
  • 64-Bit Windows Considerations
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Running the BISMkApp Program

Run this program from the Start menu: click Start > All Programs > extend x.x.x > Business Information Server > Create BIS Xcentricity BIS Web Application.

Alternatively, to run this program from Windows Explorer or the command line, navigate to the following directory and either double-click the BISMkApp icon or run BISMkApp.exe.

 C:\Program Files\Micro Focus\extend x.x.x\AcuGT\bin

On 64-bit Windows when a 32-bit-only system is installed, replace Program Files with Program Files (x86).

When execution begins, you will see the following dialog box:

This dialog box has the following fields:

  • Server Name

    In this release, always contains localhost. Note that this program currently has to be run on the system that contains the IIS server.

  • Target Website on Server

    Select the website on the server that will serve the new web application.

  • New Web Application Name

    Enter the name of the web application that you wish created. For example, the default installation creates a web application named acubis10.

    Note that, in this version of BISMkApp, the At Root checkbox is always disabled.

  • Physical Directory for Web Application

    Enter the pathname of the physical directory that will contain the files that are served when the user issues requests against the Web Application Name.

    For example, when BIS is installed in the default way and you request this page:

    http://localhost/acubis10/samples/default.srf

    The requested content is served from:

    C:\inetpub\wwwroot\acubis10\samples\default.srf

    This is because the BIS installer creates a physical directory named acubis10 in the default web tree, and copies the sample programs into this directory. The installer then creates a virtual root directory named acubis10, configures it so it runs a BIS application (see below) and points it at the previously created physical directory.

    Notes:

    • The physical directory is not created if it does not exist.
    • The physical directory must also have the appropriate permissions (for example, anonymous user read access) or BIS will not be able to serve files from this directory.
    • It is usually convenient to create the physical directory in the web tree (for example, c:\inetpub\wwwroot) because the physical directory will inherit the permissions from the IIS parent directory. Otherwise, IIS will only manage the web application permissions (read, write, execute), and the physical directory permissions must be separately managed.
    • You may use the Browse button to browse for the directory.
  • Application Pool

    The content of this drop-down list depends on the version of Windows that you are running. For versions of IIS that support application pools, this drop-down contains a list of application pools that were found on the server. The name of the application pool will be suffixed with (32-bit) or (64-bit).

  • Checkboxes

    The checkboxes control how the web application is created.

    • Read determines if web clients will have read permission to this web application. This must be checked if BIS programs will be run in this web application.
    • Write determines if web clients will be able to write to this web application.
      Note: This should be enabled only for special purposes, as it is a security risk.
    • Execute determines if programs can be executed in this web application. This should not be enabled unless you are also using this web application as a CGI-type directory and plan to run programs out of this web application on the web server.
    • Script determines if scripts can be executed in this web application. This must be checked if BIS programs will be run in this web application.
    • NTLM Authentication should be checked to use this kind of authentication in this web application. In general, this box should be checked.
    • BIS Installation Path

      This is the path to the BIS server program directory (the directory that contains BISISAPI.DLL). This field is preset to the directory where you last installed BIS. You can override this by pressing the Browse button and browsing to a new directory; by typing a directory name; or by typing the full path where BISISAPI.DLL can be found.

Parent topic: Creating a BIS/IIS Web Application


Creating the Web Application

When all of the above fields are filled, click the Create BIS Web Application button to begin the process of creating the web application. Be patient-it can take 30 seconds to create the directory. Once the program finishes, messages will appear in the box at the bottom of the window. At that point, you can create another web application or close the program.

Parent topic: Creating a BIS/IIS Web Application


Testing the New Directory

To determine if the newly created web application is functional, create a text file named default.srf in the physical directory that you specified above. Type the following:

<html>
{{handler *}}
<head>
</head>
<body>
You requested page:
http://{{Value(HTTP_HOST,HTMLENCODE)}}{{Value(HTTP_URL,URLDECODE,HTMLENCODE)}}
</body>
</html>

Then enter the following into your web browser:

http://localhost/vdir

(replacing vdir with the name of your web application).

You should see a page containing only this text:

You requested page: http://localhost/vdir/

Notice how the Value tags were replaced with the server variables. If the Value tags were properly substituted, BIS is operational in this directory.

Parent topic: Creating a BIS/IIS Web Application


64-Bit Windows Considerations

On 64-bit versions of Windows that run Internet Information Server version 7 or later and on which a 64-bit system is installed, a 64-bit application pool is created during installation and is detected when BISMkApp is launched.

In a Windows Internet Information Server (IIS) environment, the security for your BIS web application and its program (service) and data files is provided by the built-in security mechanisms of IIS. These are based on the We Application system maintained by IIS and can be manipulated by any user with sufficient Administrator privileges. For this Appendix, Windows Server 2003 is assumed to be the host system, although the procedures for Windows Server 2000 and Windows XP Professional are very similar.

Within the IIS 6.0 Help system, go to Internet Information Services | Server Administration Guide | Security section. There you will find an extensive description of the Windows web security mechanism.
Parent topic: Creating a BIS/IIS Web Application


Building and Running BIS Samples

The BIS Samples include an installation verification application and several simple applications that illustrate the major Xcentrisity techniques for constructing web applications and services using BIS. These samples include complete source code as well as all of the XSLT transforms necessary to run them. In addition, each includes a batch file (or shell script) that will build the operational web application from source. This is convenient if you wish to experiment with modifications to the samples, or if you want to use the samples as the basis for your own web application.

Be sure that a command prompt is present and the current directory is the src directory for the sample you are building. At this point the sample may be built by typing (for BIS/IIS):

acubuild.bat

or (for BIS/Apache):

acubuild.sh

After the processing has been completed and a command prompt appears, you will have rebuilt the sample and generated new files in the bin directory

Parent topic: Xcentrisity Business Information Server for extend User's Guide


Glossary

  • Application Root Path
  • BIS Request Handler
  • HTTP
  • Response Content
  • Request Content
  • Request Document
  • Server Response File
  • Service Engine
  • Service Instance
  • Service Program
  • Session
  • Session Root Path
  • Stencil
  • URI
  • URL
  • URL Path
Parent topic: Xcentrisity Business Information Server for extend User's Guide


Application Root Path

A URL path that groups all of the pages of a BIS application. Under IIS, this is the URL path of the web application that was specified during installation, or was created with the BISMkApp utility.
Parent topic: Glossary


BIS Request Handler

The BIS components activated when a Stencil (Server Response File) is the target of an HTTP request. The BIS Request Handler performs the processing of the Stencil, including the management of Sessions and the creation and destruction of Service Instances.
Parent topic: Glossary


HTTP

HyperText Transport Protocol, a standard protocol and encoding scheme used to transmit requests to web servers and receive responses from web servers. HTTPS is a secure version of HTTP.
Parent topic: Glossary


Response Content

The data included in the content area of an HTTP Response message.
Parent topic: Glossary


Request Content

The data included in the content area of an HTTP Request message.
Parent topic: Glossary


Request Document

An XML document produced by the BIS Web Server and including the information contained in an HTTP Request message as well as various values indicating the user agent and server environment in which the request was issues and is being processed.
Parent topic: Glossary


Server Response File

A file, usually with the extension .srf, which is used to direct the BIS Web Server in responding to a request. Also referred to as a Stencil.
Parent topic: Glossary


Service Engine

The BIS components responsible for performing the execution of a user-supplied Service Program and the synchronization and interaction between the Service Program and the BIS Web Server.
Parent topic: Glossary


Service Instance

An execution of a Service Program within a particular Session.
Parent topic: Glossary


Service Program

A user-supplied ACUCOBOL-GT program object file that is invoked by the BIS Request Handler and executed by the BIS Service Engine.
Parent topic: Glossary


Session

A stateful sequence of HTTP request/response interactions between a web user agent (for example, browser) and a BIS Request Handler. The session identification is preserved in the user agent by means of a session cookie provided in the response to the first request of the session. All subsequent requests containing that cookie are assumed to be for the designated session.
Parent topic: Glossary


Session Root Path

The URL path that contains the object that caused the current session to be created. For example, if the requested URL is http://localhost/acubis10/default.srf, the session root path is acubis10. By default, all pages that contain the session root path in their URL path will be served using the same session. This can be overridden by specifying Scope=ISOLATE in a SessionParms tag.

Parent topic: Glossary


Stencil

A file, usually with the extension .srf, which is used to direct the BIS Request Handler in responding to a request. Also referred to as a Server Response File.
Parent topic: Glossary


URI

A Uniform Resource Identifier, the naming convention for objects on the Internet. A URI consists of a scheme, followed by a colon, followed by a scheme specific name. A URI can be further classified as a Locator, or a Name, or both. The term "Uniform Resource Locator" (URL) refers to the subset of URI that identify resources via a representation of their primary access mechanism (e.g., their network "location"), rather than identifying the resource by name or by some other attribute(s) of that resource. The term "Uniform Resource Name" (URN) refers to the subset of URI that are required to remain globally unique and persistent even when the resource ceases to exist or becomes unavailable.
Parent topic: Glossary


URL

A Uniform Resource Locator, the location of a resource on the internet. A URL is a type of URI (Uniform Resource Identifier), and consists of a scheme (in this context, HTTP or HTTPS), the name of a machine (sometimes also called the authority), and a path to a resource (for example, a file). For example, http://localhost/acubis10/index.html specifies the file named index.html from directory acubis10 on server machine localhost using the HTTP scheme. When this is typed into a web browser, the browser issues an HTTP GET request on this resource.
Parent topic: Glossary


URL Path

The path portion of a URL - that is, the part after the server identifier up to the end of the URL, the query string, or fragment (whichever comes first). For example, in the URL http://localhost/acubis10/default.srf?query=yes#top, the URL path is acubis10/default.srf.
Parent topic: Glossary


extend Programming Guides

  • Transitioning to ACUCOBOL-GT Version 10.2.0
  • A Programmer’s Guide to the Internet Version 10.2.0
  • A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0
Parent topic: extend Interoperability Suite


Transitioning to ACUCOBOL-GT Version 10.2.0

  • Introduction
  • RM/COBOL Conversions
  • ICOBOL Conversions
  • HP COBOL Conversions
  • IBM DOS/VS COBOL Conversions
  • Copyright and Legal Information
  • Notations and Conventions
Parent topic: extend Programming Guides


Introduction

  • Transitioning Your COBOL
  • Organization
  • Contacting Technical Support
Parent topic: Transitioning to ACUCOBOL-GT Version 10.2.0


Transitioning Your COBOL

Businesses convert their mission-critical applications to ACUCOBOL-GT for many reasons:

  • Some are forced to migrate off their current platform, but they don't want to lose their investment in COBOL.
  • Others no longer want to pay to maintain an obsolete platform, and they want to move to open systems.
  • Others feel that their COBOL no longer meets their needs. They may have issues with their vendor. They may desire modern features.

Whatever your reason, converting your programs to ACUCOBOL-GT can breathe new life into your COBOL code without losing functionality or assuming the cost of rewriting.

To smooth your transition, ACUCOBOL-GT provides compatibility with many other COBOL dialects, RM COBOL, HP COBOL, VS COBOL, ICOBOL, IBM Mainframe COBOL, and more. We offer:

  • Compatibility switches
  • Conversion tools
  • Professional Services Organization consultation
  • Migration partners that offer everything from toolkits to turnkey solutions

Once your applications are in ACUCOBOL-GT, you can take advantage of our many COBOL modernization and interoperability features to help you reach your business objectives. You can re-host from one hardware platform to another–all without rewriting your proven business applications.

Parent topic: Introduction


Organization

The Transitioning to ACUCOBOL-GT Guide describes how to convert from several of the most popular COBOLs to ACUCOBOL-GT. It is organized as follows:

  • Introduction
  • RM COBOL Conversions
  • ICOBOL Conversions
  • HP COBOL Conversions
  • IBM DOS/VS COBOL Conversions
Parent topic: Introduction


RM/COBOL Conversions

  • Compile-Time Options
  • Runtime Options
  • Memory Management
Parent topic: Transitioning to ACUCOBOL-GT Version 10.2.0


Compile-Time Options

This chapter provides information about how to convert programs written for the RM/COBOL compiler to ACUCOBOL-GT. This is particularly directed at users who are new to ACUCOBOL-GT and are not familiar with its many options. The information contained here is specifically directed to programs written for version 2.X of the RM/COBOL 1974 compiler. Most of this information is also applicable to versions 1.5 and 1.6 of that compiler, as well as to RM/COBOL-85. See Converting RM/COBOL Data Files for information about converting RM/COBOL data files.

Several compile-time options should be used when you are compiling a program written for RM/COBOL with ACUCOBOL-GT. You should always use the " -Cr" flag to indicate RM/COBOL compatibility mode. You will also probably want to use the "-R8vais" flags to cause certain reserved words to be treated as user-defined words. This will cause all words not reserved by RM/COBOL to be treated as user-defined words. If you are converting programs from RM/COBOL-85, then you should use "-Rvais" instead.

Many applications will also need to use the "-Ds" flag. This flag specifies that the PICTURE element "S" for a USAGE DISPLAY item is treated as a separate character. This is the same as implying the SIGN IS TRAILING SEPARATE clause for that item. RM/COBOL version 1.6 behaved this way. RM/COBOL version 2.X can optionally behave this way. For applications that date from earlier versions of the RM/COBOL compiler, you will probably need to use this flag. If the application was written originally with version 2.0 or later, then you may or may not need to use this flag. You will need to examine the source to see if the S picture element counts in the size of an item or not. It is important to determine whether or not this flag should be used, particularly if you plan to convert existing data files. Otherwise, records loaded from your RM/COBOL files may not match the record layout of your new ACUCOBOL-GT files.

You may also want to use either the "-Vh" or "-Vl" flags. These flags determine the default video intensity to use when it is not explicitly stated in an ACCEPT or DISPLAY statement. The default action for ACUCOBOL-GT is to use the terminal's default intensity. The "-Vh" flag causes ACUCOBOL-GT to default to high intensity and the "-Vl" flag to low intensity. With RM/COBOL, the default intensity for UNIX machines is high intensity and for MS-DOS machines is low intensity. You may want to match the default intensity used by RM/COBOL for the machine the programs were written for.

By default, in the Identification Division the compiler allows an Area A line to start in column 8 or 9 (ANSI format), or 1 or 2 (terminal format). The --noRmMargin option can be used to apply a more stringent rule. When specified, lines in Area A of the Identification Division must begin in column 8 (ANSI format) or column 1 (terminal format).

The table below shows the RM/COBOL Compatibility Switches ("*" indicates an optional flag).

  • Version 1.6 | Version 2.x | RM-85
    General | -Cr | -Cr | -Cr
    Reserved words | -R8vais | -R8vais | -Rvais
    Data storage | -Ds | -Ds* | -Ds*
    Video -Vh (for UNIX)

    -Vl (for DOS)

            -Vh (for UNIX)

    -Vl (for DOS)

            -Vh (for UNIX)

    -Vl (for DOS)

    Area A | --noRmMargin* | --noRmMargin* | --noRmMargin*

You will probably want to set the COPYPATH environment variable in order to locate your COPY libraries on your system. For details on how to do this, see Compiler and Runtime.

Parent topic: RM/COBOL Conversions


Runtime Options

There are several runtime options that you may want to employ. The -w flag suppresses warning messages from the runtime system. In particular, it inhibits the warning message NONNUMERIC DATA IN NUMERIC ITEM. This message is printed whenever a numeric field is used in a numeric fashion and that field does not contain a valid number. The default action for ACUCOBOL-GT is to print the warning message and then treat the value as zero. RM/COBOL does not check for this case and proceeds to do some undefined action. Because it does not test for this condition, it shows up in programs surprisingly often. When the "-w" runtime flag is specified, ACUCOBOL-GT does not print a message and acts on the field with its current value. The results are not well defined but usually are the same as the same program run under RM/COBOL.

By default, ACUCOBOL-GT uses 1985 ANSI standard file status codes. These codes differ from those used by RM/COBOL in several respects. If your programs are written to the 1974 RM/COBOL standard, you should add the following line to the configuration file to cause ACUCOBOL-GT to use those file status codes:

FILE-STATUS-CODES  74
Note: If you are converting programs from RM/COBOL-85, and use the default 1985 standard status codes, do not add this line to the configuration file.

RM/COBOL (but not RM/COBOL-85) also automatically closes all non-print files in a subprogram when that program exits. This is in conflict with the ANSI standard which states that a subprogram remains in the same state until explicitly canceled. ACUCOBOL-GT follows the ANSI standard. If your programs depend on this behavior, however, you can add the following line to the configuration file to cause ACUCOBOL-GT to act the same way that RM/COBOL does:

CLOSE-ON-EXIT  1

You will also need to edit the configuration file to describe which printers are attached to your system. You may also want to set the PATH entry to describe where your object-code files reside. These procedures are described in Compiler and Runtime.

Parent topic: RM/COBOL Conversions


Memory Management

RM/COBOL supports two forms of memory management. One form is the standard ANSI COBOL form. This is also the memory management scheme used by ACUCOBOL-GT. If your RM/COBOL application uses the ANSI-style of memory management, then you do not need to make any changes to run under ACUCOBOL-GT.

The RM/COBOL implementation of the ANSI memory management is very restrictive, however, in that the main program plus the set of all called programs must fit in 64K bytes (except for those that are canceled). For this reason, many applications use RM/COBOL's alternate mode of memory management. In this mode, all of the currently active programs must fit in 64K bytes, but programs that are not currently active need not. This has the effect of dynamically canceling inactive subprograms as needed to free up enough space. This has the advantage that the programmer largely does not need to worry about canceling subprograms. When this style of memory management is used, however, the programmer cannot depend on a subprogram's remaining loaded in memory. This can cause variables to lose values. RM/COBOL also causes open files in a subprogram to be closed when that subprogram exits (except for files assigned to a printer).

ACUCOBOL-GT has a much larger address space, and thus has no need for this scheme. Furthermore, this form of memory management results in unpredictable behavior, since the state of a called and exited subprogram is unknown. For these reasons, ACUCOBOL-GT does not directly support the alternate form of RM/COBOL memory management.

ACUCOBOL-GT does, however, have several techniques that can be used when you are converting programs that use this style of memory management. Virtually any RM/COBOL program will run under the ACUCOBOL-GT memory management scheme. The only significant problem that applications face has to do with handling menus. These applications have one or more master menus that the user selects specific tasks from. Usually, each of these tasks is a separate program that is called from the menu program when selected. Since ACUCOBOL-GT abides by the ANSI/ISO standard, each of these programs remain in memory until explicitly canceled. As the user chooses more and more menu selections, the memory used can become large. This could eventually overrun the amount of memory available in the machine.

The ANSI/ISO solution to this problem is to cancel the task-handling subprograms when they are finished. This would normally happen when control is returned to the menu program. ACUCOBOL-GT has an extension to the CANCEL verb to make this task easier. This is the statement CANCEL ALL. This statement has the effect of canceling every program except for those that are currently active. This has the following advantages over the standard CANCEL statement:

  • You do not need to know the name of the program being canceled. Thus you can place this one statement in the main loop in your menu program to handle all of the menu selections.
  • The CANCEL ALL statement also cancels subprograms called by intervening programs. Suppose the menu program calls program A, which in turn calls program B. If you explicitly cancel program A, the ANSI standard states that program B will remain unconcealed. The CANCEL ALL statement, on the other hand, will cancel both program A and B.

This is probably the easiest way to handle the memory management problem. Another technique, however, that gives you greater control is to use the INITIAL PROGRAM attribute. Any program that has the initial attribute is automatically canceled whenever it exits. You can specify the initial attribute by either of these methods:

  • Specify IS INITIAL PROGRAM in the PROGRAM-ID clause.
  • Use the -Zi compile-time option.

You can use this technique if you want greater control over memory management than the CANCEL ALL statement gives you.

Finally, do not overlook the standard CANCEL verb. This has the advantage that it is part of both the 1974 and 1985 COBOL standards.

For more information about run-time memory management, see Memory Management.

  • Converting RM/COBOL Data Files
Parent topic: RM/COBOL Conversions


Converting RM/COBOL Data Files

Data files written by RM/COBOL programs can be converted for use by ACUCOBOL-GT programs. The exact procedure depends on the version of RM/COBOL used to create the data files.

Sequential and relative files created by RM/COBOL version 2 programs are directly usable by ACUCOBOL-GT programs. These files have exactly the same internal format. (Note, however that this is not true for variable-length binary sequential files or variable-length relative files.)

RM/COBOL version 2 produces two types of indexed files: single-file format and dual-file format. The dual-file format consists of two physical files for each logical file. One of these files is a binary sequential file that contains the raw data records. The other is a file that contains the key information. You can convert one of these files by using the "load" option of vutil. To do this, first create an empty ACUCOBOL-GT indexed file either with a COBOL program (by doing an OPEN OUTPUT) or with the "generate" option of vutil. Then use the "load" option of vutil, specifying the RM/COBOL data file as the input file. Note that the RM/COBOL key file is not used. For more information, see Debugger and Utilities.

A single-file format indexed file must first have its records unloaded into a binary sequential file with an RM/COBOL program. Then this file can be loaded into an ACUCOBOL-GT indexed file with the procedure described for the dual-file format.

Line sequential and fixed-length binary sequential files created by RM/COBOL-85 are directly usable by ACUCOBOL-GT. Use the following procedures to convert other RM/COBOL-85 formats to fixed-length binary sequential.

  • Converting relative files with variable-length records
  • Converting binary sequential files with variable-length records
  • Converting relative files with fixed-length records
  • Converting indexed files
Parent topic: Memory Management


Converting relative files with variable-length records

You can write a program in RM/COBOL-85 to convert variable-length relative files to fixed-length binary sequential files that ACUCOBOL-GT can use. To do this:

  1. Write a program that reads the desired file using a DEPENDING ON phrase in the RECORD clause of the input file's FD. The variable depend will be filled in with the record size.
  2. Define the output file as follows:
    • Records should be fixed-length binary sequential.
    • Each record must begin with two bytes that are COMP-4, and those two bytes should be filled in with the value of depend.
    • The remainder of the record should be the actual record contents from the input file.
  3. Write the output records to a new file. Use this new fixed-length binary sequential as your ACUCOBOL-GT data file.
Note: ACUCOBOL-GT binary sequential and relative files have essentially the same format.
Parent topic: Converting RM/COBOL Data Files


Converting binary sequential files with variable-length records

To convert binary sequential files with variable-length records, follow Converting relative files with variable-length records.

Parent topic: Converting RM/COBOL Data Files


Converting relative files with fixed-length records

To convert relative files with fixed-length records, write an RM/COBOL program that reads the file and writes the records to a fixed-length binary sequential file. The resulting relative file is usable by ACUCOBOL-GT.

Parent topic: Converting RM/COBOL Data Files


Converting indexed files

vutil can convert an indexed file created by RM/COBOL-85 into a Vision file. This is useful when you are moving data from an RM/COBOL-85 application to an ACUCOBOL-GT application. The command is:

vutil  -convert  [ -ac ]  [ +c ]  [ -f # ]  [ -3456 ]
                 [ -q ]  [ -d dir ]  [ files ]

The "convert" option starts with the same letter as the "check" option described earlier. You must use at least two letters of the word "convert" in order to specify this option. If you just use "-c", vutil will assume that you are specifying the "check" option.

The "convert" function will take each named file and convert it from an RM/COBOL-85 indexed file to a corresponding Vision file. The Vision file replaces the original RM/COBOL-85 file, so you should have a current backup of the original files. If no files are specified, then the standard input is read for a list of files to convert.

Normally the resulting Vision file will be compressed if the original file has compressed records (this is the RM/COBOL-85 default). Specifying the "-c" option will cause the resulting file to have uncompressed records regardless of the original file; using "+c" will cause the resulting records to be compressed.

The "-f #" option sets the compression factor to be used when the file is converted. This option does not force the use of compression, it merely sets the compression factor if compression is used. The compression factor, a numeric literal, specifies how much of the space saved by compression is actually to be removed from the record.

Normally vutil will warn the user about the impending conversion and ask if he or she wants to continue. The "-a" (for "automatic") option suppresses this warning. This can be useful when you are calling vutil from another program.

The -6 option specifies that you want the resulting file to be in Vision Version 6. The -5 option specifies that you want the resulting file to be in Vision Version 5. The -4 option specifies a Vision Version 4 file. A -3 means a Version 3 file.

The "-d" option specifies that you want the converted files to be placed in a new directory. Dir should be the name of a directory on the machine other than the directory containing the files to be converted. When "-d" is specified, the original files are not destroyed. Instead, the converted files are placed in dir. The "-d" option implies the "-a" option.

The "-q" option causes vutil to exit (with status 99) if user interaction is required.

There are a few types of files that cannot be converted due to restrictions in Vision. Any of the following properties will cause vutil to print a message and leave the file alone:

  1. A record size or block size greater than 32 KB.
  2. More than 120 keys.
  3. An individual key with more than 250 bytes in it.
  4. A non-ASCII code-set or collating sequence.

Some files cannot be converted due to unresolved format differences. A file with split keys cannot be converted for this reason.

If the original file has variable size records, vutil will convert these to fixed size records with space padding. These files should be compressed to keep disk usage down.

vutil makes a copy of the file while it is converting it. You must have adequate disk space for vutil to complete its conversion. Also, RM/COBOL-85 indexed files and Vision files differ in the amount of disk space they use. This difference is fairly unpredictable and can vary quite widely. Sometimes the Vision files are smaller, and sometimes the RM/COBOL-85 files are smaller. Be sure to have plenty of spare disk space when you start converting files to accommodate the potential difference.

Parent topic: Converting RM/COBOL Data Files


ICOBOL Conversions

  • Compile-Time Options
  • Runtime Options
  • Differences
Parent topic: Transitioning to ACUCOBOL-GT Version 10.2.0


Compile-Time Options

This chapter discusses how to convert a program written for Data General ICOBOL to ACUCOBOL-GT. ACUCOBOL-GT provides a great deal of compatibility with ICOBOL, but there are a few differences that you will want to address.

It is important that you use the correct compile-time options to provide the greatest compatibility with your existing ICOBOL programs. The most important option is the "-Ci" option that puts the compiler into its ICOBOL compatibility mode. When you use this option, most ICOBOL syntax will be accepted by ACUCOBOL-GT. In addition, the meaning of certain phrases will be altered to match the ICOBOL usage. When ICOBOL compatibility mode is specified, the "-Zr" compile-time option is automatically implied. This option allows for recursive PERFORM statements.

There are a few other options that you will probably want to use. The "-Vx" option enables the entry of function keys on all ACCEPT statements. If you do not specify this, then only ACCEPT statements with an ON ESCAPE clause will allow the entry of function keys. If you want to use ICOBOL's default handling of high and low intensity, then you should specify "-Vah". This causes all input and update fields to be displayed in high intensity, while all literal and output fields are shown in low intensity.

You may also want to use the "-Dz" compile-time option to modify the way that COMPUTATIONAL data items are handled. Specifying this option causes the runtime system to compute the size error condition based on the physical size of the data item in memory, not on its PICTURE clause. For example, this would allow the value 255 to be placed in a PIC 99 COMP data item. Without this option, the largest value that can be placed in such an item is 99.

Finally, you may need to suppress certain reserved words used by ACUCOBOL-GT. If you want to suppress all of the reserved words not used by ICOBOL, you should specify "-Rarsv". If you plan to use some of the features of ACUCOBOL-GT not found in ICOBOL, then you will probably have to allow for some more reserved words. For details on your choices about reserved words, see Reserved Word List.

When you select ICOBOL compatibility mode, the storage of COMPUTATIONAL items is changed to match that of ICOBOL. You should not specify any of the compile-time options that affect COMPUTATIONAL storage, because they will override the ICOBOL settings. The following table summarizes the storage of COMPUTATIONAL items.

# of 9's | Unsigned | Signed
1-2 | 1 | 1
3-4 | 2 | 2
5-6 | 3 | 3
7 | 3 | 4
8-9 | 4 | 4
10-11 | 5 | 5
12 | 5 | 6
13-14 | 6 | 6
15-16 | 7 | 7
17-18 | 8 | 8
Parent topic: ICOBOL Conversions


Runtime Options

When you use ICOBOL compatibility, the compiler generates code that has the same meaning used by ICOBOL. The default screen interface, however, is controlled by the runtime system. If you want to simulate ICOBOL keyboard handling, you should add the following lines to your configuration file. For more information, see Compatibility Modes.

SCREEN Input-Display=Prompt
SCREEN Numeric-Updates=Unchanged
SCREEN Edited-Updates=Left-Adjust
KEYBOARD   Cursor-Past-End=Yes
KEYSTROKE  Edit=Next  Terminate=0 ^M
KEYSTROKE  Edit=Next  Terminate=0 ^J
KEYSTROKE  Edit=Next  Terminate=0 kd
KEYSTROKE  Edit=Previous  ku
KEYSTROKE  Edit=Next  Terminate=0 ^I
KEYSTROKE  Exception=1  27
KEYSTROKE  Exception=2  k1
KEYSTROKE  Exception=3  k2
KEYSTROKE  Exception=4  k3
KEYSTROKE  Exception=5  k4
KEYSTROKE  Exception=6  k5
KEYSTROKE  Exception=7  k6
KEYSTROKE  Exception=8  k7
KEYSTROKE  Exception=9  k8

The exact meaning of these entries is described in Terminal Manager At some point, you should read this chapter to acquaint yourself with the various options available. The listing above covers only function keys 1 - 8. If you use more of the function keys, you will need to make additional KEYSTROKE entries to define those keys.

Use the ICOBOL_FILE_SEMANTICS runtime configuration variable to get ICOBOL compatible behavior when reading past the beginning or ending of a file. For more details, ICOBOL Runtime Configuration Variable.

You can use ICOBOL-compatible file status codes by entering the following line to your configuration file:

     FILE-STATUS-CODES  DG
  • ICOBOL Runtime Configuration Variable
Parent topic: ICOBOL Conversions


ICOBOL Runtime Configuration Variable

The ICOBOL_FILE_SEMANTICS configuration variable affects the behavior of indexed and relative files when reversing direction after reading past the beginning or end of a file. Normally, if you perform a series of READ NEXTs that reach to the end of the file (returning file status 10), a subsequent READ PREVIOUS returns the last record in the file.

The file pointer's position after each READ NEXT is just past the end of the last record. Similarly, reading past the beginning of the file and then executing a READ NEXT returns the first record in the file.

Under ICOBOL, these conditions produce different results. The record returned by READ PREVIOUS is the second-to-last record in the file, and the record returned by READ NEXT is the second record in the file. Essentially, when a series of READs passes either end of the file, the record pointer remains on the first or last record.

Setting ICOBOL_FILE_SEMANTICS to 1 (on, true, yes) causes the runtime to emulate ICOBOL's handling. This is useful when porting ICOBOL programs to ACUCOBOL-GT. This option is effective only in programs that have been compiled for ACUCOBOL-85 2.0, or later. The default value is 0 (off, false, no).

Parent topic: Runtime Options


Differences

ACUCOBOL-GT contains certain differences from ICOBOL, even when you are using ICOBOL compatibility mode. These differences are:

ASSIGN TO DISPLAY and KEYBOARD

ICOBOL allows an ASSIGN clause to use the word DISPLAY to refer to the user's screen and KEYBOARD to refer to the user's input device. ACUCOBOL-GT allows these terms, but when they are used a file name must be specified. This allows (as ICOBOL does) the specification of a text file. However, ACUCOBOL-GT does not support the direct assignment to the user's screen or keyboard. To do this, you will have to add code to identify the device name of the user's terminal and ASSIGN to that name. You can use the ACCEPT FROM SYSTEM-INFO verb to return the user's station id.

ACCEPT FROM LINE NUMBER

This form of the ACCEPT statement returns a 3-digit number corresponding to the console device that is controlling the executing program. Because most of the machines that run ACUCOBOL-GT do not use device numbers, but use alphanumeric names instead, ACUCOBOL-GT computes the device number by the following procedure. First, the device name is converted to uppercase and hyphens are converted to underscores (on UNIX systems, the initial /dev/ is removed). This name is then searched for in the environment (including the configuration file). If it is found, then the value of the name is returned. If it is not found, a number is constructed from any digits found in the device name. If no digits are present, the value "0" is used.

ACCEPT FROM EXCEPTION

This statement, which returns the reason the last CALL statement failed, is not supported. A similar function can be coded using the C$CALLERR library routine described in Appendix I of the ACUCOBOL-GT Manual Set.

Library Routines

ICOBOL contains several library routines that can be called. These routines start with a "#" character. ACUCOBOL-GT does not support these routines and will ignore them if you call them with the CALL PROGRAM verb. You will have to rename the routines and code them in C or COBOL if you want to use them.

Parent topic: ICOBOL Conversions


HP COBOL Conversions

  • Introduction to HP COBOL Compatibility
  • ACUCOBOL-GT in HP e3000 Emulators
  • The -Cp HP COBOL Compatibility Switch
  • Preprocessor for HP COBOL
  • System Intrinsics
Parent topic: Transitioning to ACUCOBOL-GT Version 10.2.0


Introduction to HP COBOL Compatibility

ACUCOBOL-GT provides extensive compatibility with HP COBOL II/XL. It supports HP COBOL syntax extensions and the HP COBOL preprocessor functions. HP COBOL syntax extensions have the same meaning and generate the same results on all platforms. The ACUCOBOL-GT HP COBOL preprocessor provides the same functional capabilities on all platforms.

ACUCOBOL-GT and HP COBOL share a common core of ANSI/ISO standard COBOL. In addition, most HP COBOL extensions to the ANSI/ISO standard are supported by ACUCOBOL-GT via the -Cp compiler option. The -Cp option, set either on the command line or in the CBLFLAGS environment string, puts the ACUCOBOL-GT compiler in HP COBOL compatibility mode. In this mode, ACUCOBOL-GT performs actions and accepts features of HP COBOL that it does not otherwise perform or allow.

Note: The term Compatibility describes how ACUCOBOL-GT is compatible with HP COBOL. The specific version of HP COBOL with which ACUCOBOL-GT is compatible is defined in HP COBOL II/XL Reference Manual. References to HP COBOL in this topic refer to HP COBOL II/XL.

Users of ACUCOBOL-GT's HP COBOL compatibility mode, in addition to getting HP COBOL support, gain the benefit of many useful ACUCOBOL-GT extensions and a powerful set of complementary technologies. For a list of ACUCOBOL-GT extensions to the ANSI/ISO standard, see Extensions. For a brief introduction to these technologies, see Product Overview.

ACUCOBOL-GT includes an integrated development environment (IDE) for COBOL called AcuBench. AcuBench extends and enhances the ACUCOBOL-GT compiler and runtime system with an advanced suite of GUI-based development tools for COBOL. AcuBench lets you develop and maintain your COBOL applications in an integrated, developer-friendly Microsoft Windows environment and deploy them on any system supported by ACUCOBOL-GT.

Parent topic: HP COBOL Conversions
Related reference
Extensions
Product Overview


ACUCOBOL-GT in HP e3000 Emulators

ACUCOBOL-GT supports HP COBOL compatibility mode in HP e3000 emulators. This section discusses how to use ACUCOBOL-GT (and its debugger) in these environments. It also discusses how to access KSAM, relative, and sequential files from an ACUCOBOL-GT program.

  • Using ACUCOBOL-GT with HP e3000 Emulators
  • Accessing KSAM, Relative, and Sequential Files
Parent topic: HP COBOL Conversions


Using ACUCOBOL-GT with HP e3000 Emulators

Several companies offer software that to varying degrees emulates the MPE/iX operating system on non-HP e3000 hardware. In some situations, these emulators provide a viable rehosting path for moving HP COBOL applications to a new platform with minimum changes to the source code. Because they provide varying degrees of support for the full capabilities of MPE/iX, each emulator should be carefully evaluated for its ability to meet the needs of your applications. In most cases, ACUCOBOL-GT can be easily configured to run within these emulators.

The information in this section is designed to help you configure ACUCOBOL-GT for HP COBOL compatibility. Typically, the configuration steps are modest, requiring only that you enable the MPE file system and assign values to a small number of environment and runtime variables.

This section assumes that you are familiar with your emulator software and that you have successfully compiled your HP COBOL program with the ACUCOBOL-GT compiler on the new host.

  • Enabling the MPE file system
  • Setting run-time configuration variables
  • Setting environment variables
Parent topic: ACUCOBOL-GT in HP e3000 Emulators


Enabling the MPE file system

The ACUCOBOL-GT runtime does not come pre-configured to support the MPE file system. Therefore, if you want to access MPE files you must first enable the MPE file system in the runtime. This requires relinking the runtime. The steps for doing this are given below.

Before starting, it is helpful to verify the version and configuration of your ACUCOBOL-GT runtime. On the system, enter:

runcbl  -vv

The "-vv" option causes the runtime to display detailed version and configuration information. On an HP-UX system the output is similar to:

ACUCOBOL-GT runtime version 10.2.0
Serial number 999999
Licensed for 1 user(s)
AcuServer client
Vision version 6 file system
XML version expat_1.95.4 file system
Copyright (c) Micro Focus 1985-2016 All rights reserved.

The end of the first line of output indicates the version of the runtime. To get MPE file system support, you must have Version 7.0.0, or later.

To enable MPE file system support, follow the steps below. The steps include relinking the runtime. Relinking requires that you have access to the host system's native C compiler. For complete information on relinking, see Relinking the Runtime System.

Note: By default, the ACUCOBOL-GT files needed to relink the runtime are located in the "lib" subdirectory of your ACUCOBOL-GT installation.
  1. Make a backup copy of your current runcbl file.
  2. Optionally, include other libraries.
  3. Enable (or disable) the MPE file system. Edit filetbl.c (in the lib subdirectory of your ACUCOBOL-GT installation) and look for the list of define statements. The list contains entries such as:
    #define USE_VISION | 1
    #define USE_RMS | 0
    #define USE_CISAM | 0
    #define USE_BTRIEVE | 0
    #define USE_MPE | 0

    Locate USE_MPE and set the value to "1". The file systems that are set to "1" are those that are enabled and linked. Those set to "0" are disabled and not linked. Any or all file systems may be enabled at the same time; the more systems you link, the larger your runtime system becomes.

  4. Edit Makefile (in the lib subdirectory of your ACUCOBOL-GT installation) and add ksam.o to the FSI_SUBS definition. The line for FSI_SUBS should look like:
    FSI_SUBS = ksam.o

    To remove support for MPE, remove ksam.o from FSI_SUBS.

  5. Relink the runtime. Make your current working directory the lib subdirectory of your ACUCOBOL-GT installation and enter:
    make

    This compiles sub.c and filetbl.c, and links the runtime.

To verify that MPE file system support is enabled, enter runcbl -vv. The output should now include the line:

KSAM version MPE/iX native and compatibility
   mode file system
Parent topic: Using ACUCOBOL-GT with HP e3000 Emulators
Related reference
Relinking the Run-time System


Setting run-time configuration variables

Typically, you need to set a few run-time variables before using ACUCOBOL-GT with your HP e3000 emulator.

To ensure that the ACUCOBOL-GT runtime performs as expected, you may need to set the DEFAULT_FILESYSTEM, SHARED_LIBRARY_EXTENSION, and SYSINTR_NAME run-time configuration variables.

Note: For an introduction to the function and use of the ACUCOBOL-GT runtime configuration file, see Run-time Configuration. All ACUCOBOL-GT runtime configuration variables are described in Configuration Variables.
  • DEFAULT_FILESYSTEM
  • SHARED_LIBRARY_EXTENSION
  • SYSINTR_NAME
Parent topic: Using ACUCOBOL-GT with HP e3000 Emulators
Related reference
Run-Time Configuration
Configuration Variables


DEFAULT_FILESYSTEM

The value of this variable tells the runtime which file system to use when the application opens an existing file or creates a new file. You can override this setting for an individual file with the filename_FILESYSTEM variable. See filename_FILESYSTEM.

To direct the runtime to use the MPE file system by default, set DEFAULT_FILESYSTEM to MPE. The line in the configuration file should look like:

DEFAULT_FILESYSTEM MPE
Parent topic: Setting run-time configuration variables


SHARED_LIBRARY_EXTENSION

This variable defines the filename extension for UNIX shared libraries. The default value is .so. On HP-UX systems, set the value to .sl, as in:

SHARED_LIBRARY_EXTENSION = .sl

This variable has meaning only on systems that support UNIX shared libraries.

Parent topic: Setting run-time configuration variables


SYSINTR_NAME

For some HP e3000 emulators, this variable defines the location of the SYSINTR file. This variable must be specified with HFS syntax and set to the full path of the SYSINTR file. For example:

SYSINTR_NAME /opt/mpe/etc/sysintr.txt
Parent topic: Setting run-time configuration variables


Setting environment variables

Depending on your host system, the run time may require that the SHLIB_PATH or LD_LIBRARY_PATH environment variable be defined.

  • SHLIB_PATH (HP-UX systems only)
  • LD_LIBRARY_PATH (UNIX/Linux systems, except HP-UX)
Parent topic: Using ACUCOBOL-GT with HP e3000 Emulators


SHLIB_PATH (HP-UX systems only)

The environment variable SHLIB_PATH must include the path to the HP e3000 emulator's shared libraries. You can include a path with these Bourne Shell commands:

SHLIB_PATH=$SHLIB_PATH:/opt/mpe/lib
export SHLIB_PATH

You can also include a path with this C Shell command:

setenv SHLIB_PATH=$SHLIB_PATH:/opt/mpe/lib

You can add these commands to the each user's .profile or .cshrc start-up file. To make the definition effective for all users, change /etc/profile. Changing /etc/profile requires root privileges.

Parent topic: Setting environment variables


LD_LIBRARY_PATH (UNIX/Linux systems, except HP-UX)

The environment variable LD_LIBRARY_PATH must include the path to the HP e3000 emulator's shared libraries. This can be accomplished with the following Bourne Shell commands:

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/mpe/lib
export LD_LIBRARY_PATH

or with the following C Shell command:

setenv LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/mpe/lib

You can add these commands to the each user's start-up file (.profile or .cshrc), or to make the definition effective for all users, to /etc/profile. Changing /etc/profile requires root privileges.

Parent topic: Setting environment variables


Accessing KSAM, Relative, and Sequential Files

You can access KSAM, relative, and sequential files through HP COBOL system intrinsic functions or via standard COBOL I/O statements. If your programs use system intrinsics to access MPE files, you do not need to make any changes to your code or set any special runtime configuration variables. If your programs use standard COBOL I/O statements to access MPE files, you will need to check the setting of one or more ACUCOBOL-GT runtime configuration variables. How to configure ACUCOBOL-GT to access MPE files via standard COBOL I/O statements is discussed in the remainder of this section.

Note: ACUCOBOL-GT supports duplicate primary key values. For more information, see File-Control Paragraph.
  • Selecting a file system
  • File I/O trace information
  • KSAM system limits and ranges
  • Enabling and disabling the MPE interface
Parent topic: ACUCOBOL-GT in HP e3000 Emulators
Related information
File-Control Paragraph


Selecting a file system

ACUCOBOL-GT allows a program to interface with more than one external file system in the same program. The file systems supported by the run time are identified and enabled in the file filetbl.c (located in the LIB directory).

To specify the indexed file system that the program uses, set the DEFAULT_FILESYSTEM configuration variable. To define a file system for use with a particular file, you set the filename_HOST configuration variable. For an introduction to ACUCOBOL-GT runtime configuration variables and the configuration file, see Runtime Configuration.

  • DEFAULT_FILESYSTEM
  • filename_HOST
Parent topic: Accessing KSAM, Relative, and Sequential Files
Related reference
Runtime Configuration


DEFAULT_FILESYSTEM

DEFAULT_FILESYSTEM specifies the default file system to be used for all file I/O. The default value is Vision. If you want to use HP COBOL's MPE file system instead, add the following to the cblconfig file:

DEFAULT_FILESYSTEM MPE

This tells the runtime to use KSAM files instead of Vision files. If you specify Vision, the relative and sequential files will be in bytestream format instead of MPE format.

Parent topic: Selecting a file system


filename_HOST

This variable specifies the file system to use for a particular file. For example, if DEFAULT_FILESYSTEM is set to MPE, and the file CUSTFILE is a Vision file, in your cblconfig you could specify:

CUSTFILE_HOST VISION

This definition directs the runtime to treat CUSTFILE as a Vision file. Note that the file name may not include any path or directory name and should not include the file extension.

DEFAULT_FILESYSTEM and filename_HOST are described in detail in DEFAULT_FILESYSTEM and filename_HOST respectively.

When your program executes, each time a file is opened, the ACUCOBOL-GT runtime checks filename_HOST and DEFAULT_FILESYSTEM to determine which file system to use. You can change the value of these variables, just before you open the file, by including the following in your code:

SET ENVIRONMENT "DEFAULT_FILESYSTEM" TO value

or

SET ENVIRONMENT "filename_HOST" TO value

where value is a Working Storage item containing the name of the file system, or is a literal in quotation marks. SET ENVIRONMENT thus enables you to change file systems during the execution of your program.

Parent topic: Selecting a file system


File I/O trace information

Both the ACUCOBOL-GT runtime and debugger support an option to output file I/O trace information during program execution. This facility can be very helpful when you are investigating program execution problems. When file tracing is enabled, the runtime outputs a message to the error file for every file I/O-related action that it executes.

To enable file tracing, the trace level must be set to "7" or higher.

To learn how to enable file tracing, see Handling Program Execution Problems and FILE_TRACE.

Parent topic: Accessing KSAM, Relative, and Sequential Files


KSAM system limits and ranges

KEYS |  | 1-16 keys
KEY SIZE | byte | 1-255 bytes
 | integer | 1-255 bytes of integer data
 | real | 1-255 bytes of real number data
 | IEEE real | 4, 8, or 16 bytes of IEEE real number data
 | numeric | 1-28 bytes of numeric data
 | packed | 1-14 bytes of packed decimal data (odd # of char)
 | *packed | 2-14 bytes of signed packed decimal data (even # of char)
REC SIZE |  | 1-32,767 fixed-length and undefined-length ASCII files
 |  | 1-32,766 variable-length ASCII, fixed, variable and undefined length binary
FILE SIZE |  | 4 gigabytes, KSAM XL file
 |  | 128 gigabytes, KSAM64 file

Other limits apply as described in Limits and Ranges.

Parent topic: Accessing KSAM, Relative, and Sequential Files


Enabling and disabling the MPE interface

ACUCOBOL-GT's support for MPE files is not enabled by default. If you want to enable/disable support, you can include or remove it from the runtime by performing the following steps.

  1. Make a backup copy of your current runcbl file.
  2. Edit filetbl.c (in the LIB directory). In a text editor, look for the list of define statements. The list contains entries such as:
    #define USE_VISION   1
#define USE_RMS      0
#define USE_CISAM    0
#define USE_BTRIEVE  0
#define USE_INFORMIX 0
#define USE_MPE      1

    Set a value in the list to "0" (zero) to disable that system, or to "1" (one) to enable it. The file systems that are set to "1" are the ones you plan to link and use. Any or all may be enabled at the same time; the more systems you link, the larger your runtime system becomes.

  3. Locate and edit the Makefile (in the LIB directory). In a text editor, add ksam.o to the FSI_SUBS definition. The line with FSI_SUBS should look like this:
    FSI_SUBS  =  ksam.o

    To remove support for KSAM, remove ksam.o from FSI_SUBS.

  4. Link the runtime system. Be sure that your current working directory is the lib subdirectory of your ACUCOBOL-GT directory.

    To link the runtime, enter:

    make

    This compiles sub.c and filetbl.c, and then links the runtime.

  5. To specify MPE as the default file system, edit cblconfig (the runtime configuration file) and add the following line:
    DEFAULT_FILESYSTEM MPE

    You can override this default in your programs via the SET ENVIRONMENT statement or by setting the filename_HOST variable.

  6. Test the system.

    The interface is now in place. To ensure that ACUCOBOL-GT is writing and reading records via KSAM, move to the directory containing the sample program iobench. Create a temporary configuration file named temp.ttt. In this file, place one line:

    DEFAULT_FILESYSTEM MPE

    At the system prompt, type:

    :runcbl  "-v"
:ccbl  "-x  -Cr  -Si  ACU  iobench.cbl"
:runcbl  "-c  temp.ttt"

    This displays the version number of the interface and then compiles and executes a sample program that generates several file I/O activities.

    We use the file temp.ttt to prevent the runtime system from using your usual cblconfig file. This ensures that the iobench program creates its files in the current directory.

Parent topic: Accessing KSAM, Relative, and Sequential Files


The -Cp HP COBOL Compatibility Switch

The -Cp compiler switch allows ACUCOBOL-GT to accept HP COBOL extensions to the ANSI 1985 Standard. These extensions are described in the following subsections, organized in the order in which the extension occurs in a COBOL program.

The use of the -Cp option with the ACUCOBOL-GT compiler triggers the following HP COBOL-specific behavior.

  • The ACUCOBOL-GT precompiler for HP COBOL is invoked. The precompiler supports conditional compilation via these directives.
    • $IF
    • $SET
    • $COMMENT
    • $PREPROCESSOR
    • $DEFINE
    • $INCLUDE
    Macro substitutions with parameters are supported. $CONTROL directives are not supported. However, many of the actions accomplished by $CONTROL directives can be accomplished with ACUCOBOL-GT compiler switches. The precompiler is discussed in detail in Preprocessor for HP COBOL.
  • STRING/UNSTRING statements and relation conditions are accepted.
  • The following HP COBOL extensions are accepted:
    • The percent character (%) is allowed as an indicator of an octal-based numeric literal.
    • HP extensions to the COPY statement, including those that copy a file from a resident library. COPY REPLACING statements within nested Copy books are not supported.
    • Special Names Paragraph switches SW0 through SW15
    • The Special Names TOP and NO SPACE CONTROL phrases with the ADVANCING clause of the WRITE statement.
    • The HP meaning of RANDOM in the File-Control paragraph
    • The Procedure Division registers: CURRENT-DATE, TALLY, TIME-OF-DAY, and WHEN-COMPILED
    • HP extensions to the ACCEPT statement
    • HP extensions to the CALL statement
    • The ENTRY statement
    • The EXAMINE statement

  • The following HP COBOL extensions are not supported. These extensions are not commonly used and are largely considered to be obsolete.

    The following extensions cause ACUCOBOL-GT to issue a warning but do not cause compilation to terminate:

    • COBOLLOCK
    • COBOLUNLOCK
    • EXCLUSIVE
    • UN-EXCLUSIVE

    These unsupported extensions are not recognized by the compiler and cause compilation to terminate:

    • BEGINNING
    • COMMON
    • ENABLE
    • ENDING
    • FILE-LIMITS
    • MORE-LABELS
    • PROCESSING
    • SEEK

Successful compilation results in the creation of an ACUCOBOL-GT object file that is ready for immediate execution by the runtime. There is no link step.

Support for HP COBOL extensions and the call interface to HP COBOL system intrinsics is built directly into the ACUCOBOL-GT compiler and runtime. ACUCOBOL-GT supports KSAM, IMAGE, and VPLUS through the HP COBOL intrinsic procedures and functions specific to those components. KSAM can also be used with standard COBOL I/O (see section Accessing KSAM Relative and Sequential Files). For more information about ACUCOBOL-GT support for system intrinsics, see System Intrinsics.

  • COPY Statement
  • Special-Names Paragraph
  • File-Control Paragraph
  • Procedure Division Register Extensions
  • Procedure Division Statements
  • Conversion Issues
  • Operating System and Runtime Limitations and Differences
Parent topic: HP COBOL Conversions
Related information
Preprocessor for HP COBOL
Accessing KSAM, Relative, and Sequential Files
System Intrinsics


COPY Statement

The HP COBOL syntax of the COPY statement is:

COPY source-file [ {OF} library-name ] [ NOLIST ]
                   {IN}

   [ REPLACING  { { old-text } BY { new-text } } ... ].

If the "-Cp" option is specified, ACUCOBOL-GT supports the HP COBOL variant of the COPY statement that copies a file from a resident library. In this usage, library-name is a one to eight character alphanumeric name that specifies the resident library in which the source file is located. This library is a KSAM or text file that contains one or more source files.

If library-name is not specified, the compiler assumes that the library name is COPYLIB. If source-file cannot be found in the library, then ACUCOBOL-GT checks to see if source-file is in the current directory.

Note: HP COBOL assumes the name of the source file is in uppercase. If an uppercase name is not found in the current directory, the rules that ACUCOBOL-GT uses for source-file and library-name will be used (described below).

If the "-Cp" option is not specified, the standard rules that ACUCOBOL-GT applies to source-file and library-name are used. This means that library-name is interpreted as a directory name. If you have a resident library, you will need to unload its contents. In the working directory in which you perform compilations, create a subdirectory of the same name and case as library-name. Unload the library's source files into this subdirectory using the same name and case as specified by source-file. The next time you compile, ACUCOBOL-GT will find source-file in the directory you created. For example, if your COBOL COPY statement reads:

COPY support IN common

During compilation, ACUCOBOL-GT will translate that statement into:

COPY "./common/support"

If library-name is not specified, ACUCOBOL-GT checks to see if source-file is in the current directory. If source-file is not found in the current directory, the rules that ACUCOBOL-GT uses for finding source-file are applied. (For more information about ACUCOBOL-GT's treatment of the COPY statement and the use of the COPYPATH environment variable for locating copy files, see COPY Libraries.

NOLIST is supported by ACUCOBOL-GT in HP COBOL compatibility mode. NOLIST has the same meaning as SUPPRESS in ACUCOBOL-GT's default mode. For details, see COPY Statement.

old-text and new-text have the same meaning in HP COBOL as in ACUCOBOL-GT. For details, see COPY Statement.

Note: COPY REPLACING within nested Copy books is not supported.
Parent topic: The -Cp HP COBOL Compatibility Switch


Special-Names Paragraph

This section discusses ACUCOBOL-GT's compatibility with the non-ANSI features of HP COBOL that affect the Special-Names Paragraph of the Environment Division.

  • Program switches
  • TOP and NO SPACE CONTROL
  • CONDITION-CODE
Parent topic: The -Cp HP COBOL Compatibility Switch


Program switches

ACUCOBOL-GT in HP COBOL compatibility mode lets you specify the HP COBOL program switches in the Special-Names Paragraph. HP COBOL specifies those switches as SW0 through SW15. ACUCOBOL-GT in the default mode uses SWITCH-1 through SWITCH-26.

Parent topic: Special-Names Paragraph


TOP and NO SPACE CONTROL

With ACUCOBOL-GT in HP COBOL compatibility mode, you can include TOP and NO SPACE CONTROL as Special Names in the ADVANCING clause of the WRITE statement. These Special Names can be used in Format 1 of the WRITE statement when the program accesses sequential files.

Format

WRITE record-name [FROM source] [{BEFORE} ADVANCING {mnemonic-name}
                                 {After}

Syntax Rules

  • record-name is the name of a record associated with a file described in the File Section of the Data Division. The associated file may not be a sort file. For more information, see WRITE Statement.
  • source is a data item or literal. It may not share any storage area with record-name. For more information, see WRITE Statement.
  • mnemonic-name is a user-defined word that may be used to change the state of the associated program switch or to refer to a device. For details, see syntax rule 2 in Special-Names Paragraph.

General Rules

  • mnemonic-name assigned to TOP advances the line to the next page boundary (same as specifying PAGE).
  • mnemonic-name assigned to NO SPACE CONTROL suppresses spacing and keeps the line printer from advancing.

TOP and NO SPACE CONTROL are system-names accepted by ACUCOBOL-GT in HP COBOL compatibility mode. (For details, see syntax rule 3 in Special-Names Paragraph.

Parent topic: Special-Names Paragraph


CONDITION-CODE

As with HP COBOL, CONDITION-CODE is set to the condition code returned by a system intrinsic function when the function is called with the CALL statement. It can also be set by a called C program if the following code is included in the C program.

Extern   int32_t   Ahp_ccode;

   Ahp_ccode = 0;

CONDITION-CODE takes the value of "Ahp_ccode" in the COBOL program.

Parent topic: Special-Names Paragraph


File-Control Paragraph

This section discusses ACUCOBOL-GT's compatibility with the non-ANSI features of HP COBOL that affect the File-Control Paragraph of the Environment Division.

  • RANDOM and DYNAMIC keywords
  • WITH DUPLICATES on primary keys
Parent topic: The -Cp HP COBOL Compatibility Switch


RANDOM and DYNAMIC keywords

In HP COBOL compatibility mode, the keyword RANDOM loses its default ACUCOBOL-GT meaning and means the same as the keyword DYNAMIC. For example, either of these can be used to specify DYNAMIC access to a file.

ACCESS IS RANDOM
ACCESS IS DYNAMIC

See File-Control Paragraph for usage syntax and general rules for DYNAMIC.

When compiling for object versions 8.1 and greater, the compiler accepts the ACTUAL KEY feature for relative files opened in RANDOM access mode. For such files, the relative key numbers is zero-based, rather than one-based as with RELATIVE KEY. For example, if you have a relative file with a fixed record length of 3 bytes and a relative file with the contents AAABBBCCC, the record keys for the different modes are:

     RELATIVE  ACTUAL
AAA:    1        0
BBB:    2        1
CCC:    3        2
Parent topic: File-Control Paragraph


WITH DUPLICATES on primary keys

In HP COBOL compatibility mode, duplicate primary key values are allowed if the indexed file system supports them and the WITH DUPLICATES phrase is specified in the File-Control paragraph. Vision and KSAM support duplicate primary key values. The syntax is:

RECORD KEY IS key-name [= seg-name] [WITH [NO] DUPLICATES]

The phrase WITH NO DUPLICATES is commentary because, by default, duplicate values are not allowed for the primary key.

The phrase WITH DUPLICATES indicates that duplicate primary key values are allowed. If WITH DUPLICATES is used with a file system that doesn't support duplicate primary keys, when the file is created via the OPEN statement a status of 0M is returned, indicating that the file was successfully created but that duplicate primary keys are not supported.

When WITH DUPLICATES is used with Vision, KSAM, and other file systems that support it, the rules that govern how REWRITE and DELETE operations are handled are determined by the file system. This is because support for duplicate primary keys is not part of the ANSI 1985 Standard, few files systems support it, and therefore no common rules exist. The rules for Vision are given in General Rule 14 of File-Control Paragraph.

There are some small but important differences between how KSAM and Vision handle REWRITE and DELETE when duplicate primary keys are allowed.

Under KSAM, the first record is rewritten or deleted unless the file is open with ACCESS SEQUENTIAL mode. These latter programs should convert easily to Vision because Vision's default lock handling will cause the correct record to be locked and result in the same set of records being updated.

For RANDOM and DYNAMIC access files, there could be a difference between how KSAM and Vision update records depending on how the records are read before they are rewritten or deleted. Note that the HP COBOL II Reference Manual advises against allowing duplicates primary key values with RANDOM or DYNAMIC access files. KSAM's behavior can be mimicked with Vision by always reading the record immediately before rewriting or deleting it. This ensures the correct record is accessed. Otherwise, KSAM and Vision rules are generally compatible unless the program does a series of READ NEXT's and then rewrites or deletes a record other than the one last read.

Parent topic: File-Control Paragraph


Procedure Division Register Extensions

HP COBOL supports special register words. These words reference memory storage that is generated at compile time and initialized at compile time or run time. ACUCOBOL-GT treats them as reserved words when in HP COBOL compatibility mode. In that mode, you cannot use any of the HP COBOL-specific special register words as user-defined words.

  • CURRENT-DATE
  • TALLY
  • TIME-OF-DAY
  • WHEN-COMPILED
Parent topic: The -Cp HP COBOL Compatibility Switch


CURRENT-DATE

This register stores the current date. CURRENT-DATE can be used with a MOVE or DISPLAY statement.

Format

MOVE CURRENT-DATE TO {dest-item} ...
DISPLAY CURRENT-DATE [ UPON new-window ] ...
DISPLAY CURRENT-DATE [ UPON mnemonic-name ] ...

The value of CURRENT-DATE is stored in an 8-character alphanumeric field in the format "MM/DD/YY", where "MM" is the month (01 for January, 02 for February, etc.), "DD" is the day of the month, and "YY" is the last two digits of the year. For example, the date February 15, 2001 is formatted as "02/15/01".

Parent topic: Procedure Division Register Extensions


TALLY

See EXAMINE statement for information about the special register TALLY.

Parent topic: Procedure Division Register Extensions


TIME-OF-DAY

This register stores the current time of day. TIME-OF-DAY can be used with a MOVE or DISPLAY statement.

Format

MOVE TIME-OF-DAY TO {dest-item} ...
DISPLAY TIME-OF-DAY [ UPON new-window ] ...
DISPLAY TIME-OF-DAY [ UPON mnemonic-name ] ...

The value of TIME-OF-DAY is stored in the format "hhmmss", where "hh" is the hour, "mm" is the minute, and "ss" is the second, based on a 24-hour clock. For example, 5:30 p.m. is stored as "173000".

The DISPLAY output of TIME-OF-DAY is edited to include colons (":") as separators, so the displayed format is "hh:mm:ss". For example, 5:30 p.m. is displayed as "17:30:00".

Parent topic: Procedure Division Register Extensions


WHEN-COMPILED

This register stores the date and time that the program was compiled. It can be used with a MOVE or DISPLAY statement.

Format

MOVE WHEN-COMPILED TO {dest-item} ...
DISPLAY WHEN-COMPILED [ UPON new-window ] ...
DISPLAY WHEN-COMPILED [ UPON mnemonic-name ] ...

The value of WHEN-COMPILED is stored in the format "MM/DD/YY hh:mm:ss".

Parent topic: Procedure Division Register Extensions


Procedure Division Statements

This section discusses ACUCOBOL-GT's compatibility with the non-ANSI features of HP COBOL that affect the Procedure Division.

The HP COBOL Procedure Division supports special formats of the ANSI-standard statements, as well as non-ANSI verbs. They are presented here in alphabetical order.

  • ACCEPT statement
  • CALL statement
  • EXAMINE statement
Parent topic: The -Cp HP COBOL Compatibility Switch


ACCEPT statement

  • CONVERT phrase
  • FREE phrase
  • Format 10 (HP COBOL)
  • Format 11 (HP COBOL)
  • Format 12 (HP COBOL)
  • Syntax Rules
  • General Rules
Parent topic: Procedure Division Statements


CONVERT phrase

HP COBOL programs allow numeric or numeric edited receiving fields on the ACCEPT statement by default.

With ACUCOBOL-GT in HP COBOL compatibility mode, the CONVERT phrase is implied on numeric ACCEPT statements. When the "-Cp" option is specified, the compiler sets the variable AUTO_CONVERT to "TRUE".

ACUCOBOL-GT, in the default mode, requires that you use the CONVERT phrase on the ACCEPT statement, or use the "-Vc" compiler option that sets the variable AUTO_CONVERT to "TRUE".

For details, see Format 1, syntax rule 1 in ACCEPT Statement.

Parent topic: ACCEPT statement


FREE phrase

The ACUCOBOL-GT compiler in its HP COBOL compatibility mode supports the following HP COBOL formats of the ACCEPT statement.

Note: Format 10, Format 11, and Format 12 are the numbers given to the ACCEPT statement formats. ACUCOBOL-GT formats of the ACCEPT statement are documented in Procedure Division Statements.
Parent topic: ACCEPT statement
Related reference
Procedure Division Statements


Format 10 (HP COBOL)

ACCEPT identifier [FREE]  [FROM { SYSIN         }]
                                { CONSOLE       }
                                { mnemonic-name }
Parent topic: ACCEPT statement


Format 11 (HP COBOL)

ACCEPT identifier FREE    [FROM { SYSIN         }]
                                { CONSOLE       }
                                { mnemonic-name }

[ON INPUT ERROR imperative-statement-1]
[NOT ON INPUT ERROR imperative-statement-2]

[END-ACCEPT]
Parent topic: ACCEPT statement


Format 12 (HP COBOL)

ACCEPT identifier FROM { DATE        }
                       { DAY         }
                       { DAY-OF-WEEK }
                       { TIME        }
Parent topic: ACCEPT statement


Syntax Rules

  1. identifier is a data item that receives the accepted data.
  2. mnemonic-name is a user-defined word declared in Special-Names that refers to a display device, or is the name of a display device. See ACCEPT Statement for more information.
  3. imperative-statement-1 and imperative-statement-2 are COBOL statements. The INPUT ERROR phrase in which the statement appears can be used only if the FREE phrase is used. For more information, see General Rule 3 in General Rules.
Parent topic: ACCEPT statement


General Rules

  1. CONSOLE and SYSIN are system devices. For more information, see Special-Names Paragraph.
  2. The FREE phrase allows the use of the free-field format. The free-field format allows you to continue the input into the next line when the input field is smaller than the defined length of identifier. In this format, the ampersand character ("&") acts as a continuation character when it is the last non-blank character in the input line, thus allowing the input to be continued in the next line. The pound sign ("#") acts as a line terminator (but is not required when the input comes from the terminal). To specify the "#" character and circumvent its use as a line terminator, use two "#" characters in succession.
  3. The ON INPUT ERROR and NOT ON INPUT ERROR phrases can be used only with the FREE statement. They allow the handling of the following input error conditions:
    • An illegal character in a numeric item.
    • Too many digits in a numeric item.
    • An input string that is too long for the receiving field.
Parent topic: ACCEPT statement


CALL statement

The ACUCOBOL-GT compiler in its HP COBOL compatibility mode supports the following HP COBOL extensions to the CALL statement.

Note: Format 4 is the number given to the HP CALL statement extensions. Format 4 is described via the link below. Other CALL statement formats are described in Procedure Division Statements.
  • Format 4 (HP COBOL)
  • Syntax Rules
  • General Rules
  • CALLing intrinsics
  • USING phrase (non-COBOL subprograms)
  • Passing file handles to subroutines
  • Recursive CALLs
Parent topic: Procedure Division Statements
Related reference
Procedure Division Statements


Format 4 (HP COBOL)

CALL { identifier-1            } [ USING { \\             } ... ]
     { [ INTRINSIC ] literal-1 }         { @identifier-2  }
                                         { identifier-2   }
                                         { literal-2      }
                                         { \identifier-2\ }
                                         { \literal-2\    }
     [ GIVING identifier-n ]

     [ ON {EXCEPTION} statement-1 ]
          {OVERFLOW }

     [ NOT ON {EXCEPTION} statement-2 ]
              {OVERFLOW }

     [ END-CALL ] ]
Parent topic: CALL statement


Syntax Rules

  1. Identifier-1 is an alphanumeric data item whose value is a program name. See General Rules for a description of conditions that may occur when you use this operation.
  2. Literal-1 is a nonnumeric literal whose value is either an operating system intrinsic name or a program name. When you are naming an intrinsic, literal-1 must be preceded by the keyword INTRINSIC.
  3. "\\" represents a null value passed as a parameter to an intrinsic or to a System Programming Language (SPL) program that includes the OPTION VARIABLE clause. When the intrinsic option is not specified, the compiler assumes a one-word parameter.
  4. @identifier-2 indicates that the byte address of the data item represented by identifier-2 is to be passed as a parameter. These types of parameters may be passed only to non-COBOL programs.
  5. Identifier-2 is the name of any data item in the calling program, or is a file named in an FD-level entry in the File Section of your program.
  6. Identifier-2 cannot be a function-identifier (i.e., it cannot reference an intrinsic function).
Parent topic: CALL statement


General Rules

  1. When you use the identifier-1 form of the CALL statement, the value of identifier-1 determines which subprogram is called. When the program is executed, an attempt is made to load the subprogram. If the load fails, an exception condition occurs.
  2. Identifier-2 must be described in the File, Working-Storage, or Linkage section of your program. When this value is passed to another program, it is passed by reference.
  3. If identifier-2 names a file, the called program must not be a COBOL program.
  4. \identifier-2\ and \literal-2\ indicate that the literal or data item enclosed in backslashes is to be passed by value to the called program or intrinsic. This may be used only when the called program is not a COBOL program. If an identifier is used in this way, it must represent a numeric data item of not more than 18 digits.
  5. Identifier-n is the name of a binary data item in the calling program. It is used in calls to non-COBOL programs and in calls to COBOL programs that return a value in the RETURN-CODE special register. Identifier-n cannot be a function-identifier (i.e., it cannot reference an intrinsic function).
Parent topic: CALL statement


CALLing intrinsics

The INTRINSIC phrase is used to indicate that the CALL statement is calling an operating system intrinsic function, rather than a subprogram. When the INTRINSIC phrase is used, literal-1 must be used and must name an operating system intrinsic. The USING phrase specifies the various parameters to be passed to the intrinsic. When the intrinsic is a "typed procedure," the GIVING phrase specifies the parameter to be returned by the intrinsic.

As with subprograms, the parameters passed to intrinsics are specified by position. If a parameter of an intrinsic is optional, and you do not want to pass a value for that parameter, you must specify two consecutive backslashes ("\\") in the position within the USING phrase of the CALL statement that corresponds to that parameter's position.

Unlike subprograms, if an intrinsic expects a parameter to be passed by value rather than by reference, you don't need to enclose the literal or identifier in backslashes. The intrinsic automatically assumes that the parameter is being passed by value.

The special register CONDITION-CODE holds the condition code returned by the intrinsic function. The following special relation operators can be used after the call to check the condition code:

mnemonic-name { [ NOT ] { <  } } 0
              {         { =  } }
              {         { >  } }
              {         { >= } }
              {         { <= } }
              {         { <> } }

When CALL INTRINSIC is used for intrinsics in a system file:

  • the special symbols "@" and "\" are optional.
  • data conversions for parameters passed by value are performed automatically.
Note: On HP e3000 emulators, ACUCOBOL-GT supports calls to most system intrinsic functions. Nothing in ACUCOBOL-GT's CALL interface limits support for intrinsics. However, we have not tested support for all intrinsic functions. In particular we have not tested the more obscure functions or variants of functions that take unusual or undocumented parameter types. Should you encounter unexpected behavior, please contact Micro FocusSupportLine.
Parent topic: CALL statement


USING phrase (non-COBOL subprograms)

Data is passed from the calling program to the called program on a positional basis, rather than by name. Therefore, the third name in a USING phrase of a calling program corresponds to the third name in the arguments of the called program.

This positional correspondence extends to non-COBOL called programs. Thus, for example, if the called program is a Pascal program, then the names in the parameter list of the procedure declaration in that program are identified with those data items whose names appear in the corresponding position of the USING phrase in the calling program.

As stated above in the description of identifier-2, identifier-3, and so forth, these identifiers may name files to be passed to a called program. Furthermore, although you can enclose such a file identifier between backslashes (which are ignored), preceding it with an @ symbol results in an error.

If the file name from the FD is passed, the file number of that file is passed by value. If the subprogram is an SPL procedure, the procedure parameter corresponding to the file name must be declared as type INTEGER or LOGICAL, and it must be specified as a value parameter. The file must be opened in the calling program.

To pass a data item by value, you must enclose the associated identifier in backslashes. If the value passed is a literal, the backslashes are optional. Passing a data item by value leaves the data item in the calling program unchanged following execution of the called program.

If an identifier is not passed by value (that is, is not enclosed in backslashes), it is passed as a byte pointer (that is, by reference). Thus, the data in the calling program can be altered by the called program if it is passed in this manner. In calls to COBOL programs, this is the standard method of referencing common data.

Two consecutive backslashes ("\\") may be specified in a USING phrase of a CALL statement if the called program is a Pascal procedure with OPTION DEFAULT_PARMS or EXTENSIBLE. Using two consecutive backslashes indicates that a parameter is not being sent and should not be expected.

Whenever an OPTION VARIABLE SPL procedure is called, an additional parameter must be added to the end of the USING parameter list. This parameter is called a bit mask and is used to tell the SPL procedure which parameters are being passed. The bit mask consists of one or two 16-bit binary words, where a 0 represents a missing parameter and a 1 represents an existing parameter (this allows up to 32 parameters to be passed). A parameter in the bit mask must be a numeric data item, and it represents the value derived from the bit mask.

Parameters are matched, starting from the right, in both the bit mask and the USING list, excluding the value in the USING list used for the bit mask parameter. For example,

CALL "SPLPROC" USING \TESTER\ \\ @RESULT \ERROR\ \%13\

The bit mask in this case is 0000000000001011, which is represented by the octal value "\%13\", showing that the fourth, third, and first parameters are being passed, while the second parameter is not being passed.

The bit mask is generated automatically by the compiler if you specify the INTRINSIC option.

Parent topic: CALL statement


Passing file handles to subroutines

In HP COBOL compatibility mode, you can pass the operating system's file handle for an open COBOL file to a subroutine by referring to that file's SELECT name in the CALL statement. One reason for doing this is to call an operating system function that allows the file to retrieve information not available through COBOL. For example:

ENVIRONMENT DIVISION.
FILE-CONTROL.
SELECT MY-FILE
ASSIGN TO DISK
SEQUENTIAL.

DATA DIVISION.
FILE SECTION.
FD MY-FILE.
01 RECORD-1     PIC X(80).

PROCEDURE DIVISION.
MAIN-LOGIC.
   OPEN INPUT MY-FILE.
   CALL "SUB" USING MY-FILE.
   CLOSE MY-FILE.

These rules apply when passing file handles to subroutines:

  • For compatibility with HP COBOL, a file handle is automatically passed BY VALUE unless immediately preceded by a BY REFERENCE or BY CONTENT specification. Use BY REFERENCE or BY CONTENT to pass an open file handle to a COBOL subroutine because COBOL routines cannot take BY VALUE parameters.
  • If the called subroutine is a COBOL routine, the handle passed is PIC S9(4) COMP-5. You can override this with the compiler option fileIdSize=# where # is the number of bytes you want in the passed integer (2, 4 or 8).
  • If the called subroutine is not COBOL, the handle is passed as a signed native integer using the host's default integer size.
  • The file handle passed is the host file system's identifying value for the open file. For all current implementations, this is the value returned by the C OPEN function. This may change in a future implementation.
  • If the host file system does not have this information available, then -1 is used. This can happen if the host system is not a file (for example, Acu4GL for Oracle) or the host system does not provide a way of obtaining the handle (for example, the C-ISAM interface). Files served by AcuServer also use -1 since there is no useful way to use a remote process' open file handle.
  • For Vision files in the multi-file format, the handle used is the handle of the first data segment. This is the same as the file name used when opening the file.
  • It is best to avoid performing actual I/O on the file using this file handle because the COBOL file system is unaware of any state changes to the file and may perform incorrectly, potentially leading to data corruption.
Parent topic: CALL statement


Recursive CALLs

In ACUCOBOL-GT, as in HP COBOL, a program may directly or indirectly call itself. Such a CALL statement is termed a recursive call. By default, ACUCOBOL-GT creates a new copy of data for each instance of the program. To share the initial data with all recursive calls, as is the default with HP COBOL, set the RECURSION_DATA_GLOBAL configuration variable. For more information, see RECURSION and RECURSION_DATA_GLOBAL .

Parent topic: CALL statement


EXAMINE statement

The EXAMINE statement is used to count the number of occurrences of a given character in a data item. ACUCOBOL-GT accepts the EXAMINE statement in the HP COBOL compatibility mode. HP COBOL's EXAMINE statement duplicates some of the functionality of the ACUCOBOL-GT Format 1 INSPECT statement, but with slightly different syntax. See Procedure Division Statements for a detailed discussion of the INSPECT statement.

  • Format 1
  • Format 2
  • Syntax Rules
  • General Rules
Parent topic: Procedure Division Statements


Format 1

EXAMINE identifier-1 TALLYING {ALL        } literal-1 [REPLACING BY literal-2]
                          {LEADING    }
                              {UNTIL FIRST}
Parent topic: EXAMINE statement


Format 2

EXAMINE identifier-1 REPLACING {ALL } literal-1 BY literal-2
                           {FIRST }
                               {LEADING }
                               {UNTIL FIRST}
Parent topic: EXAMINE statement


Syntax Rules

  1. identifier-1 is the name of a data item containing characters to be counted or replaced. Its USAGE must be DISPLAY (implicitly or explicitly).
  2. Each literal is a single-character literal or one of the following figurative literals:
    • ZERO
    • ZEROS
    • ZEROES
    • SPACE
    • SPACES
    • QUOTE
    • QUOTES
    • LOW-VALUE
    • LOW-VALUES
    • HIGH-VALUE
    • HIGH-VALUES
  3. ACUCOBOL-GT does not enforce the one-character limitation. If a string literal has two or more characters, it uses only the first character.
Parent topic: EXAMINE statement


General Rules

  1. The number of characters in Format 1 that obey certain conditions are counted by a special register named TALLY. Its PICTURE is 9(5) and USAGE is COMP-N. Its default value is zero.
  2. The characters to be counted and replaced are determined by the key words following TALLYING or REPLACING. Counting is done only in Format 1, and replacement is done only in Format 2 and when specified in Format 1.
    Key Words | Characters To Be Counted And Replaced
    ALL | Count and/or replace all instances of literal-1 with literal-2.
    FIRST | Replace the first (left-most) instance of literal-1 with literal-2.
    LEADING | Count and/or replace all instances of literal-1 that appear before (to the left of) any other character in the data item.
    UNTIL FIRST | Count and/or replace all characters to the left of the first (left-most) instance of literal-1 with literal-2. If literal-1 does not appear in the data item, count and replace all characters in the data item.
  3. Literal-1 is the character to be counted. Literal-2 is the character that will replace literal-1. Note that the substitution of literal-2 for characters other than literal-1 occurs only when UNTIL FIRST is specified.
  4. The contents of the TALLY register are unchanged in Format 2. In Format 1, its contents are replaced by the appropriate character count, regardless of the previous contents.
Parent topic: EXAMINE statement


Conversion Issues

This section addresses source code conversion issues.

  • Unsupported HP COBOL extensions
  • Unrecognized HP COBOL extensions
Parent topic: The -Cp HP COBOL Compatibility Switch


Unsupported HP COBOL extensions

The HP COBOL extensions are considered unsupported by ACUCOBOL-GT when recognized at compile time but ignored at run time. Such extensions, when present, cause the compiler to return a warning message indicating that this is an unsupported operation. They do not prevent the compiler from creating an object.

The following HP COBOL extensions are not supported by ACUCOBOL-GT in HP COBOL compatibility mode:

COBOLLOCK

COBOLUNLOCK

EXCLUSIVE

UN-EXCLUSIVE

Note: These extensions are listed as Reserved Words in the HP COBOL II/XL Reference Manual.
Parent topic: Conversion Issues


Unrecognized HP COBOL extensions

The HP COBOL extensions are said to be unrecognized by ACUCOBOL-GT when they prevent the compiler from successfully compiling the COBOL source. Statements that include these words cannot be compiled. The words must be removed or commented out.

The following HP COBOL extensions are not recognized by ACUCOBOL-GT in HP COBOL compatibility mode:

BEGINNING

COMMON

ENABLE

ENDING

FILE-LIMIT

FILE-LIMITS

MORE-LABELS

PROCESSING

SEEK

Parent topic: Conversion Issues


Operating System and Runtime Limitations and Differences

The following sections describe some notable differences between the way HP COBOL and ACUCOBOL-GT handle certain aspects of program execution.

  • Divide by zero
  • File I/O error handling
  • File name case
  • Mismatched EXTERNAL data items
Parent topic: The -Cp HP COBOL Compatibility Switch


Divide by zero

At run time, DIVIDE statements that do not include an ON SIZE ERROR phrase and that produce a division by zero error are handled differently by HP COBOL and ACUCOBOL-GT. Programs compiled with HP COBOL output an error message and terminate. The behavior of programs compiled with ACUCOBOL-GT is undefined. In some cases the program does not terminate. It is strongly recommended that you always use the ON SIZE ERROR phrase with any arithmetic statement that could generate a size error.

Parent topic: Operating System and Runtime Limitations and Differences


File I/O error handling

In most cases, HP COBOL and ACUCOBOL-GT handle file I/O errors in exactly the same way. Specifically, if the program includes a USE statement procedure, an INVALID KEY phrase, or an AT END phrase, and a file I/O error occurs, the appropriate code is executed. However, when a FILE STATUS variable is specified with a file, the behavior of the two COBOLs can differ. For example, when a FILE STATUS variable is specified and an OPEN INPUT statement attempts to open the file but the file does not exist, HP COBOL sets the FILE STATUS item and the program continues to execute. In contrast, ACUCOBOL-GT sets the FILE STATUS item and halts the program. ACUCOBOL-GT can be made to behave like HP COBOL by setting the ERRORS_OK configuration variable. When ERRORS_OK is set to a value of "1", file I/O errors are ignored. The result being that when ACUCOBOL-GT attempts to OPEN a file that doesn't exist, FILE STATUS is set and the program continues to execute. For complete information on the ERRORS_OK configuration variable, see ERRORS_OK.

Parent topic: Operating System and Runtime Limitations and Differences


File name case

HP COBOL and ACUCOBOL-GT treat file name case differently. When HP COBOL creates a new file via the OPEN OUTPUT statement, the name of the file (as specified in the ASSIGN TO phrase) is always created in upper case. For example:

ASSIGN TO "myfile"
.
.
.
OPEN OUTPUT . . .

creates a file with the name MYFILE. In ACUCOBOL-GT, the name of the file retains the case specified in the ASSIGN TO phrase (in the example above, myfile). This difference in behavior can produce unexpected results (for example, although MYFILE may exist, ACUCOBOL-GT won't find it; instead it creates a new file named "myfile"). You can make ACUCOBOL-GT behave like HP COBOL by setting the FILE_CASE configuration variable. The value of FILE_CASE causes the case of data file names to be adjusted at run time. Accepted values for FILE_CASE include:

2 Data file names are translated to upper case.

1 Data file names are translated to lower case.

0 (default) No case translation is performed.

For complete information on the FILE_CASE configuration variable, see Appendix H of the ACUCOBOL-GT documentation set.

Parent topic: Operating System and Runtime Limitations and Differences


Mismatched EXTERNAL data items

HP COBOL and ACUCOBOL-GT treat the indexes of external tables slightly differently. In ACUCOBOL-GT, indexes attached to an external table are also external. As a result, all programs that share an external table must also have matching indexes for the table. (Note that the 1985 ANSI standard leaves the handling of INDEXED BY data items up to the implementor.)

The incompatibility exhibits itself at runtime. HP COBOL programs that are compiled with ACUCOBOL-GT using the -Cp option and share an external table but that do not have identical indexes for that table get following run-time error:

Mismatched EXTERNAL data item: data_item_name

The problem is illustrated by the following example. If the called program defines

01 main-01 external.
      03 item-01   pic x occurs 20
                        indexed by idx1.
01 redef1 redefines main-01.
      03 item-01   pic x occurs 20
                        indexed by idx2.

and the calling program defines

01 main-01 external.
      03 item-01  pic x occurs 20
                       indexed by idx1.

then the Mismatched EXTERNAL data item error is raised at runtime. Although redef1 is a REDEFINES of main-01, idx2 is still a new data item and it must be present in all of the programs that share main-01 or the index must be eliminated. Note that if a SEARCH statement references redef1, idx2 must be present.

The following code does not raise the error. The called program defines:

01 main-01 external.
      03 item-01  pic x occurs 20
                       indexed by idx1.
01 redef1 redefines main-01.
      03 item-01  pic x occurs 20
                       indexed by idx2.

and the calling program defines:

01 main-01 external.
      03 item-01  pic x occurs 20
                       indexed by idx1, idx2.
Parent topic: Operating System and Runtime Limitations and Differences


Preprocessor for HP COBOL

The ACUCOBOL-GT compiler includes a preprocessor that is written specifically for providing compatibility with HP COBOL programs. ACUCOBOL-GT automatically invokes the preprocessor for HP COBOL when you specify the -Cp option. This preprocessor handles macro calls with parameters, as well as conditional compilation with these directives.

  • $IF
  • $SET
  • $COMMENT
  • $PREPROCESSOR
  • $DEFINE
  • $INCLUDE
Note: $CONTROL directives are ignored by the ACUCOBOL-GT preprocessor for HP COBOL. The $CONTROL directives are handled by the compiler command arguments.

The compiler determines the source format automatically by examining the first character of the first non-blank line. If that character is blank or a digit, the file is assumed to be an ANSI file, otherwise it is assumed to be in terminal format. You can also specify the format of the source with the -Sa or -St compile options.

The ACUCOBO-LGT preprocessor for HP COBOL currently supports the following directives. They are discussed in more detail below.

$COMMENT

$DEFINE

$IF

$INCLUDE

$PREPROCESSOR

$SET

The $CONTROL directive is not supported by the preprocessor; however, ACUCOBOL-GT provides compile options that handle most of the functionality supported by $CONTROL.

  • $COMMENT Directive
  • $CONTROL Directive
  • $DEFINE Directive
  • $PREPROCESSOR Directive
  • $IF and $SET Directives
  • $INCLUDE Directive
Parent topic: HP COBOL Conversions
Related information
$CONTROL Directive
Source Options


$COMMENT Directive

Format

$COMMENT [comment-text]

The preprocessor treats any line that has the $COMMENT directive as whitespace. If the line ends with the line continuation character, (ampersand ("&") is the default line continuation character), the following line is also treated as a commented line.

Parent topic: Preprocessor for HP COBOL


$CONTROL Directive

The $CONTROL directive in HP COBOL provides a method for specifying compilation and list options. The $CONTROL directive is not supported by ACUCOBOL-GT and is not included in the compiled object or listing file.

ACUCOBOL-GT uses command line arguments to perform the same functions that $CONTROL directives perform for HP COBOL. The following table correlates HP COBOL $CONTROL options to equivalent ACUCOBOL-GT options. The string <default> indicates that the option is enabled by default in ACUCOBOL-GT. To make it easier to specify multiple compiler options, you can use the CBLFLAGS environment variable. For information on the use of CBLFLAGS, see CBLFLAGS Environment Variable.

HP COBOL $CONTROL option | ACUCOBOLGT compiler option
ANSISORT | <none>
ANSISUB | <default>
BOUNDS | -Za
CHECKSYNTAX | -Lf
CODE | <default>
NOCODE | <none>
CROSSREF | -LC
NOCROSSREF | <default>
DEBUG | -Gd
DIFF74 | <none>
DIFF74=OBS | <none>
DIFF74=INC | <none>
DYNAMIC | -Zi
ERRORS=number | <none>
LINES=number | -Ll
LIST | -Lf
NOLIST | <default>
LOCKING | <none>
LOCOFF | <default>
LOCON | -Lf
MAP | -Ls
NOMAP | <default>
MIXED | <none>
NOMIXED | <default>
QUOTE = " ' | <none>
SOURCE | -Lo
NOSOURCE | <default>
STAT74 | use the runtime configuration variable: FILE_STATUS_CODES = 74
STDWARN | <none>
NOSTDWARN | <none>
SUBPROGRAM | <none>
SYMDEBUG | -Gy
SYNC16 | -D12
SYNC32 | -D14
USLINIT | -Di
VERBS | -Lc
NOVERBS | <default>
WARN | -a
NOWARN | -w
Parent topic: Preprocessor for HP COBOL


$DEFINE Directive

The $DEFINE preprocessor directive associates a string of text with a macro name. When the preprocessor encounters a defined macro name in the source program, it invokes the macro and passes the associated string of text.

The string of text may specify up to nine formal parameters. If the string of text uses parameters, then the macro call can specify actuals for these parameters; otherwise, they are ignored.

Format

$DEFINE macro-name=[string-text]#

where:

macro-name is the name of the macro. Macro names begin with a non-alphanumeric character. By default, it is the percent symbol ("%");

string-text is a string of text to replace occurrences of the macro call within the body of the program code. The string of text may contain formal parameters (which are sometimes referred to as variables). These are designated by an exclamation point followed by an integer in the range of 1 to 9. string-text may also contain other macro calls, which recursively expand; and

string-text is delimited by the equal sign ("=") and pound sign ("#"). The pound sign marks the end of the definition. The pound sign is the default delimiter and it can be changed with the $PREPROCESSOR command.

Note: Use of an "&" character is interpreted as part of the macro definition and not as a continuation (as it would in the $COMMENT command).

If the string-text starts on the same line as the macro name, the replacing text is expanded from exactly the same column as the macro call. Otherwise, the replacing text starts at the beginning of the next line.

The two different forms of the macro call are:

macro-name

and

macro-name(p1#,p2#,...,pn#)

where

"p1", "p2", ..., "pn" are actual parameters that replace the formal parameters in the string of text. Each actual parameter can be a null character or any combination of characters, including spaces;

n is an integer in the range of 1 to 9; and

"#" is a delimiter.

Formal parameters that are not specified with an actual parameter in the macro call are ignored. You can specify which formal parameters should be ignored by entering only a pound sign ("#") in the appropriate position within the macro call. For example, to ignore the first parameter, you write the call like this:

macro-name(#,p2#,...,pn#)
Parent topic: Preprocessor for HP COBOL


$PREPROCESSOR Directive

The default delimiter characters used in macro text strings and macro names are the pound ("#"), percent ("%"), and the exclamation point ("!"). These characters can be changed with the $PREPROCESSOR directive.

Format

$PREPROCESSOR parameter=new-character
   [, parameter=new-character, ...]

where:

parameter specifies which character to modify; and

new-character specifies the new character.

The following parameters can be modified.

KEYCHAR - defines the initial character of a macro name. The default character is "%".

DELIMITER - defines the character that delimits the end of macro text strings and the actual parameters used with macro calls. The default character is "#".

PARMCHAR - defines the initial character of each formal parameter within macro text string. The default character is "!".

Parent topic: Preprocessor for HP COBOL


$IF and $SET Directives

The $IF and $SET directives allow for partial compilation of a source file based on the states of software switches. Ten software switches (0 through 9) can be independently changed between binary states ("on" or "off") using the $SET directive. Sections of the source program can then be processed or skipped, depending on the state of any one or a combination of switches used in the $IF directive.

The $IF and $SET directives can be specified on the command line used to invoke the compiler. When specified in that way, the directive must be preceded with a hyphen ("-"). For example:

   :ccbl "-Cp -$SET X0=ON HELLOCBL"
  • $SET Format
  • $IF Format
Parent topic: Preprocessor for HP COBOL


$SET Format

$SET [Xn={ ON } [, Xr={ ON }]]
         { OFF}       { OFF}

where:

"Xn" and "Xr" are software switches; and

n and r are integers in the range of 0 to 9.

All switches are "OFF" by default.

When the $SET directive is used by itself, it sets all switches to "OFF".

Parent topic: $IF and $SET Directives


$IF Format

$IF [ Xn={ ON } ]
         { OFF}

where "Xn" is a software switch.

When the $IF directive is used by itself, it evaluates to true and any following program source is processed.

A $IF directive always ends the influence of any preceding $IF directive.

Parent topic: $IF and $SET Directives


$INCLUDE Directive

The $INCLUDE directive allows you to include a file as part of your source file.

Format

$INCLUDE filename

where filename is the name of the file. The contents of filename are inserted beginning where the $INCLUDE statement appears.

Parent topic: Preprocessor for HP COBOL


System Intrinsics

On HP e3000 emulators, ACUCOBOL-GT supports calls to most system intrinsic functions. Most notably, this includes support for the TurboIMAGE/XL database and VPLUS interface. Nothing in ACUCOBOL-GT's CALL interface specifically limits support for system intrinsics. However, not all intrinsic functions are tested. In particular, the more obscure functions and variants of calls that take unusual or undocumented parameter types have not been tested.

On HP e3000 emulators that support TurboIMAGE/XL, VPLUS, or other intrinsics, if the emulator or environment does not provide transparent support, you can access the intrinsics from ACUCOBOL-GT using the direct method of interfacing to C subroutines. For more information, see Calling C Programs via the Direct Method.

After editing direct.c, you must relink the run time. Create a new run time using the method described in Relinking the Runtime System.

  • CREATEPROCESS Intrinsic Function
  • CREATE/ACTIVATE Intrinsic Functions
  • GETINFO Intrinsic Function
Parent topic: HP COBOL Conversions
Related reference
Calling C Programs via the Direct Method
Relinking the Run-time System


CREATEPROCESS Intrinsic Function

In HP COBOL compatibility mode, ACUCOBOL-GT supports the use of the CREATEPROCESS intrinsic function to start separate, directly executable programs. CREATEPROCESS statements that launch such programs do not have to be modified in any way. CREATEPROCESS statements cannot, however, be used to start programs that have been compiled with ACUCOBOL-GT. Such programs can be started directly with the CALL or CALL RUN statement. Existing CREATEPROCESS statements that call programs that are now compiled with ACUCOBOL-GT, must be converted to use the CALL or CALL RUN statement.

Parent topic: System Intrinsics


CREATE/ACTIVATE Intrinsic Functions

In HP COBOL compatibility mode, ACUCOBOL-GT supports the use of the CREATE and ACTIVATE intrinsic functions to load and start separate, directly executable programs. Processes started in this way run asynchronously to the calling program (in a separate thread).

CREATE and ACTIVATE statements that load and launch separately executable programs do not have to be modified in any way. CREATE and ACTIVATE cannot, however, be used to load and launch programs that have been compiled with ACUCOBOL-GT. Existing CREATE and ACTIVATE statements that call programs that are now compiled with ACUCOBOL-GT, must be converted to use the CALL THREAD statement.

Parent topic: System Intrinsics


GETINFO Intrinsic Function

The GETINFO intrinsic function returns the string specified in the INFO argument of the command line. A typical HP COBOL command line includes program parameters in the INFO argument. The structure of the ACUCOBOL-GT command line includes the name of the COBOL program as well as the program parameters in the INFO argument.

To cause GETINFO to return only the arguments that follow the COBOL program name (identical behavior to HP COBOL), you must include a " ;" delimiter between the COBOL program name and the other parameters in the INFO argument.

For example, if the HP COBOL command line looks like:

:RUN MYPROG;INFO='info1 info2'

a call to GETINFO will return info1 info2. To get the same result with ACUCOBOL-GT, the command line must look like:

:RUN /ACUCOBOL/bin/runcbl;INFO='MYPROG ;info1 info2'

If the " ;" delimiter is left out of the INFO argument, a call to GETINFO will return MYPROG info1 info2. Note that there must be a space before the semi-colon and no space after the semi-colon.

Parent topic: System Intrinsics


IBM DOS/VS COBOL Conversions

  • Support for DOS/VS COBOL
  • ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features
  • Reserved Words
  • COMP-1 and COMP-2 are Floating-Point
  • External Floating-Point (EFP)
  • IBM DOS/VS Error Codes
Parent topic: Transitioning to ACUCOBOL-GT Version 10.2.0


Support for DOS/VS COBOL

The command-line option -Cv (either on the command line or in the CBLFLAGS environment string) gives the ACUCOBOL-GT compiler compatibility with IBM DOS/VS COBOL. In this mode, it accepts features of IBM DOS/VS COBOL that are not otherwise accepted by ACUCOBOL-GT.

Since there are slight differences between IBM COBOL versions, -Cv also takes the following optional arguments:

-Cv=OSVS specifies OSVS compatibility.

-Cv=VSC2 specifies VSC2 compatibility.

-Cv by itself defaults to OSVS mode. The two modes are very similar, except that in VSC2 compatibility mode, the following words are not reserved:

  • CURRENT-DATE*
  • EXAMINE
  • TIME-OF-DAY
  • TRANSFORM

CURRENT-DATE is a valid function in any compatibility mode.

This chapter provides information about the IBM DOS/VS COBOL features that the ACUCOBOL-GT compiler supports. Complete IBM DOS/VS COBOL compatibility is, unfortunately, not feasible. However, this chapter contains a list of IBM DOS/VS-specific features, what they do, and whether they are supported by ACUCOBOL-GT through the -Cv command line option, .

IBM DOS/VS COBOL compatibility is available only with Version 5.0 or later. Therefore, the compiler aborts with its usage message if both -Cv and a backward object compatibility option, for example -Z32, are specified.

Parent topic: IBM DOS/VS COBOL Conversions


ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features

IBM DOS/VS COBOL-specific features that cannot be supported by the ACUCOBOL-GT compiler are reported as general errors. The following list contains the specific features of IBM DOS/VS COBOL, along with an explanation of what each feature does, whether it is accepted or not via the command line option "Cv," and any operational information that is helpful in using the "-Cv" command line option.

  • ACTUAL KEY Clause and SEEK
  • ADVANCING in WRITE Statement
  • AFTER POSITIONING Clause
  • APPLY Clause Options
  • Arithmetic Statements
  • BASIS, INSERT, DELETE
  • COM-REG
  • COPY SUPPRESS Statement
  • CURRENT-DATE
  • DATE-COMPILED
  • Debugging Features
  • DISPLAY UPON SYSPUNCH
  • EJECT, SKIP in Listing
  • ENTER Statement
  • EXAMINE
  • FILE-LIMIT Clause
  • File Status Codes
  • IDENTIFICATION Division Arrangement
  • IF OTHERWISE
  • LENGTH OF Expression
  • NOTE Statement
  • Password Protection of Files
  • PROCESSING MODE Clause
  • PROGRAM-ID Program Name
  • RECORDING MODE Clause
  • REVERSED Sequential Input Files
  • SORT Statement Registers
  • SPECIAL-NAMES
  • TIME-OF-DAY
  • TRACK-AREA Clause
  • TRANSFORM Statement
  • USE GIVING
  • VALUE OF Clause
  • WHEN-COMPILED
  • WRITE ADVANCING Special-Name
  • XLM GENERATE and PARSE
Parent topic: IBM DOS/VS COBOL Conversions


ACTUAL KEY Clause and SEEK

In IBM DOS/VS compatibility mode, when compiling for object versions 8.1 and greater, the compiler accepts the ACTUAL KEY feature for relative files opened in RANDOM access mode. For such files, the relative key numbers will be zero-based, rather than one-based, as with RELATIVE KEY. For example, if you have a relative file with a fixed record length of 3 bytes and a relative file with the following contents:

AAABBBCCC

The record keys for the different modes are:

     RELATIVE  ACTUAL
AAA:    1        0
BBB:    2        1
CCC:    3        2

ACUCOBOL-GT does not support SEEK and reports an Unsupported Operation error if it is present.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


ADVANCING in WRITE Statement

In the absence of either an ADVANCING or POSITIONING clause, a WRITE statement for a sequential PRINT file advances one line before printing for ACUCOBOL-GT without the "-Cv" option, and one line after printing for IBM DOS/VS COBOL or ACUCOBOL-GT with the"-Cv" option.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


AFTER POSITIONING Clause

IBM DOS/VS COBOL has a Format 2 WRITE statement that is similar to the ACUCOBOL-GT Format 1 WRITE statement, except that the ADVANCING clause is replaced by a POSITIONING clause:

ACUCOBOL-GT:

     {BEFORE} ADVANCING {number [LINE ]}
     {AFTER }           {       [LINES]}
                        {PAGE          }
IBM DOS/VS COBOL:
     AFTER POSITIONING {identifier} LINES
                       {integer   }

If the line count in the IBM form is an identifier, it must be a one-character alphanumeric item, interpreted as follows:

Character | ACUCOBOL-GT Equivalent
' ' | AFTER ADVANCING 1
'0' | AFTER ADVANCING 2
'-' | AFTER ADVANCING 3
'+' | AFTER ADVANCING 0
'1' | AFTER PAGE
others | invalid or not supported in ACUCOBOL-GT (implemented as AFTER ADVANCING 1)

If the line count in the IBM form is an integer literal, it is interpreted as follows:

Value | ACUCOBOL-GT Equivalent
0 | AFTER PAGE
1 | AFTER ADVANCING 1
2 | AFTER ADVANCING 2
3 | AFTER ADVANCING 3
others | invalid or not supported in ACUCOBOL-GT (implemented as AFTER ADVANCING 1)

ACUCOBOL-GT accepts the IBM form (along with its own form, even in the same file) if the "-Cv" option is in effect. ACUCOBOL-GT does not enforce the one-character limit on the line count and uses only the first character or digit if there are two or more.

Note: In the absence of either an ADVANCING or POSITIONING clause, a WRITE statement for a sequential PRINT file advances one line BEFORE printing for ACUCOBOL-GT without the "-Cv" option, and one line AFTER printing for IBM DOS/VS COBOL or ACUCOBOL-GT with the "-Cv" option.
Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


APPLY Clause Options

IBM DOS/VS COBOL allows the clauses of the I-O-CONTROL paragraph of the ENVIRONMENT division to appear in any order. It also accepts the following forms of the APPLY clause that ACUCOBOL-GT does not accept:

APPLY WRITE-ONLY ON file-name-1 [file-name-2] ...

APPLY EXTENDED-SEARCH ON file-name-1 [file-name-2] ...

APPLY WRITE-VERIFY ON file-name-1 [file-name-2] ...

APPLY CYL-OVERFLOW OF integer TRACKS ON file-name-1 [file-name-2] ...

APPLY CORE-INDEX TO data-name ON file-name-1 [file-name-2]

APPLY {MASTER-INDEX} TO device-number ON file-name-1 [file-name-2] ...
      {CYL-INDEX   }

These options affect the efficiency of file operations in IBM DOS/VS COBOL but not the program logic. As a result, ACUCOBOL-GT treats these forms of the APPLY clause as comments when in the IBM DOS/VS COBOL compatibility mode, and it accepts the clauses in any order regardless of the mode.

You may put APPLY clauses of the IBM DOS/VS COBOL type into the I-O-CONTROL paragraph, but only when the compiler is in the IBM DOS/VS COBOL compatibility mode. Such clauses are scanned but otherwise ignored.

The clauses of the I-O-CONTROL paragraph may be arranged in any order, and the existing APPLY clause may be used, regardless of the compiler mode.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


Arithmetic Statements

ACUCOBOL-GT includes a compiler option, "--ArithmeticVSC2", that causes intermediate results in arithmetic statements to be truncated following the rules of VS COBOL II and COBOL/370. Note that this option matches the Micro Focus ARITHMETIC"VSC2" compiler directive.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


BASIS, INSERT, DELETE

The BASIS statement is a variant of the COPY statement. Because the BASIS statement is a debugging technique, it is not portable and ACUCOBOL-GT does not support it.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


COM-REG

This special register in IBM DOS/VS COBOL corresponds to bytes 12 to 22 of the DOS Communication Region. It is not portable and is not supported by ACUCOBOL-GT.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


COPY SUPPRESS Statement

The word SUPPRESS in the COPY statement causes the compiler to omit the copied file from the program listing. This feature of IBM DOS/VS COBOL has been incorporated into ACUCOBOL-GT. For more information, see COPY Statement.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


CURRENT-DATE

IBM DOS/VS COBOL has a CURRENT-DATE register that contains the current date in either MM/DD/YY or DD/MM/YY format, where MM is the month (01 for January, 02 for February, etc.), DD is the day of the month, and YY is the last two digits of the year. Leading zeros are used where necessary to ensure two-digit values. For example, November 2, 2000 is expressed as either 11/02/00 or 02/11/00. This register is valid only as the source of a MOVE statement without conversion.

When ACUCOBOL-GT is in the IBM DOS/VS COBOL compatibility mode, CURRENT-DATE may be used as the source of a Format 1 MOVE statement:

     MOVE CURRENT-DATE TO {dest-item} ...

If there are two or more destination items in the same MOVE statement, all are guaranteed to receive the same value, even if the clock ticks and midnight passes while the statement is being processed.

As usual, the value is truncated or padded with blanks at the right end to make it fit into the destination.

The runtime configuration variable CURRENT-DATE determines which format to use. If this variable is "0", which is the default condition, MM/DD/YY is used. If this variable is "1", DD/MM/YY is used. Other values produce undefined results.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


DATE-COMPILED

IBM DOS/VS COBOL replaces the comment in the DATE-COMPILED paragraph with the compilation date in the program listing. ACUCOBOL-GT does not need to do this because it puts the compilation date elsewhere in the listing.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


Debugging Features

ACUCOBOL-GT does not support IBM DOS/VS-specific debugging features. The ACUCOBOL-GT compiler marks as errors the debugging statements that begin with the following words:

READY
RESET
EXHIBIT
ON
DEBUG
Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


DISPLAY UPON SYSPUNCH

The IBM DOS/VS COBOL SYSPUNCH (or SYSPCH) option refers to punchcards, which are obsolete. The ACUCOBOL-GT compiler redirects punchcard output to a special file called SYSPUNCH.TXT.

Format 9 of the DISPLAY statement (ANSI DISPLAY) is in most cases treated in a slightly different manner by IBM DOS/VS COBOL.

IBM DOS/VS COBOL has special names for card punch output, which may appear after the reserved word UPON either as SYSPUNCH (or SYSPCH) or as a "mnemonic" associated with one of these in the SPECIAL-NAMES paragraph.

In the IBM DOS/VS COBOL compatibility mode, ACUCOBOL-GT accepts these names, or their mnemonics, and it emulates a card punch by writing the card images to a disk file (or a device that looks like a disk file to the operating system). The default file specification is SYSPUNCH.TXT (in the current directory), but you may specify another file by putting a line of the following form in the runtime configuration file:

SYSPUNCH = <file specification used instead of SYSPUNCH.TXT>

Each card image is 80 characters wide, and is terminated in the manner appropriate for the runtime environment (carriage return and line feed for Windows, line feed for UNIX).

The leftmost 72 columns contain data from the DISPLAY UPON SYSPUNCH statement. If the data is longer than this, excess characters spill over to the next card image. If the data is shorter than this, it is padded with blanks at the right end to make it 72 characters long.

The other 8 columns of each card image contain the program name from the PROGRAM-ID phrase of the IDENTIFICATION division. If the program name is more or less than eight characters long, it is truncated or padded with spaces at the right end.

If the file specified for card images already exists, the card images are added to the end of the file.

The WITH NO ADVANCING phrase may be used with DISPLAY UPON SYSPUNCH, although it is not part of IBM DOS/VS COBOL. It may cause subsequent text to go into the same card image, if it fits.

DISPLAY UPON CONSOLE, DISPLAY UPON SYSLST, DISPLAY UPON SYSLIST and DISPLAY UPON SYSOUT behave in a slightly different manner when the IBM DOS/VS COBOL compatibility mode is in effect. In this mode, each line must be 100 characters long for DISPLAY UPON CONSOLE, and 120 characters long for the other forms. A line that is too short is padded with blanks at the right end, and a line that is too long spills over to the next line.

The IBM DOS/VS COBOL compatibility mode has no effect on the DISPLAY UPON SYSERR statement.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


EJECT, SKIP in Listing

In the IBM DOS/VS COBOL compatibility mode, the following reserved words may be used to control spacing of the program listing:

Word | Effect
EJECT | start a new page
SKIP1 | skip one line before the next line (double spacing)
SKIP2 | skip two lines before the next line (triple spacing)
SKIP3 | skip three lines before the next line (quadruple spacing)

IBM DOS/VS COBOL requires these words to appear in Area B. The reserved word must be the only thing on the line, other than tabs and spaces.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


ENTER Statement

IBM DOS/VS COBOL scans but ignores the ENTER statement as follows:

     ENTER  language-name  [routine-name].

ACUCOBOL-GT also ignores this statement when it is in the IBM DOS/VS COBOL compatibility mode.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


EXAMINE

IBM DOS/VS COBOL has an EXAMINE statement, which duplicates some of the functionality of the ACUCOBOL-GT INSPECT statement, but with slightly different syntax. ACUCOBOL-GT accepts this statement in the IBM DOS/VS COBOL compatibility mode.

  • Format 1:
  • Format 2:
Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


Format 1:

EXAMINE identifier-1 TALLYING {ALL        } literal-1 [REPLACING BY literal-2]
                          {LEADING    }
                              {UNTIL FIRST}
Parent topic: EXAMINE


Format 2:

EXAMINE identifier-1 REPLACING {ALL } literal-1 BY literal-2
                           {FIRST }
                               {LEADING }
                               {UNTIL FIRST}

Here identifier-1 is the name of a data item containing characters to be counted or replaced. Its USAGE must be DISPLAY (implicitly or explicitly). Each literal is a single-character literal or one of the following figurative literals:

ZERO
ZEROS
ZEROES
SPACE
SPACES
QUOTE
QUOTES
LOW-VALUE
LOW-VALUES
HIGH-VALUE
HIGH-VALUES

ACUCOBOL-GT does not enforce the one-character limitation. If a string literal has two or more characters, it uses only the first character.

The special register TALLY, whose PICTURE is 9(5) and whose USAGE is

COMP-N, counts the number of characters in Format 1 that obey certain conditions.

The characters to be counted and replaced are determined by the key words following TALLYING or REPLACING. Counting is done only in Format 1, and replacement is done only in Format 2 and when specified in Format 1.

Key Words | Characters To Be Counted And Replaced
ALL | Count all instances of literal-1 in the data item and replace them with literal-2.
FIRST | Replace the first (leftmost) instance of literal-1 in the data item to literal-2.
LEADING | Count the instances of literal-1 in the data item that appear before (to the left of) any other character in the data item, and replace them with literal-2.
UNTIL FIRST | Count the characters to the left of the first (leftmost) instance of literal-1 and replace them with literal-2. If literal-1 does not appear in the data item, count and replace all characters in the data item.

It should be noted that the substitution of literal-2 for characters other than literal-1 occurs only in the last case.

The contents of the TALLY register are unchanged in Format 2. In Format 1, its contents are replaced by the appropriate character count, regardless of the previous contents.

Parent topic: EXAMINE


FILE-LIMIT Clause

IBM DOS/VS COBOL permits an optional clause in a SELECT statement (also called a "file-control-entry"):

     {FILE-LIMIT IS  }  limits-1  [limits-2] ...
     {FILE-LIMITS ARE}

Here limits-1, limits-2, etc., are phrases of the form:

     {data-name-1} THRU {data-name-2}
     {literal-1  }      {literal-2  }

IBM DOS/VS COBOL treats this clause as a comment. ACUCOBOL-GT ignores it in the IBM DOS/VS COBOL compatibility mode.

Put the FILE-LIMIT clause in any convenient spot after the ASSIGN clause.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


File Status Codes

Some of the numeric status codes returned for file operations are different in IBM DOS/VS COBOL and ACUCOBOL-GT. The following list contains codes returned for each.

Code | IBM DOS/VS COBOL | ACUCOBOL-GT
00 | Success | Same
10 | EOF | Same
21 | Invalid key, sequence error | Same
22 | Duplicate key | Same
23 | Key not found | Same
24 | Boundary violation (indexed VSAM | Same
30 | Permanent error | Same
34 | Boundary violation (sequential VSAM) | Same
91 | Password failure | Not supported closest alt.: 3707
92 | Logic error | Presumably 4x
93 | Resource not available | Presumably 05/35
94 | No current record for seq. Request | 43
95 | Invalid or incomplete file information. | Not supported closest alt.: 39xx
96 | No DLBL card | Not supported
Zx | User-defined errors | Not supported
  • FILE STATUS Extensions
Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


FILE STATUS Extensions

The compiler supports the specification of a second FILE STATUS item, which is treated as commentary. The FILE STATUS phrase of the File-Control paragraph supports the following format:

[ File STATUS Is status-variable [status-variable-2] ]

Status-variable must be the name of an alphanumeric (or USAGE DISPLAY numeric) Working-Storage or Linkage data item with a size of 2 characters. Status-variable-2 must be the name of a group item that is 6 characters in length (this is not checked by the compiler).

When the FILE STATUS clause is specified, a value will be moved into status-variable after the execution of every statement that references the corresponding file. This value indicates the status of the statement.

Parent topic: File Status Codes


IDENTIFICATION Division Arrangement

IBM DOS/VS accepts these paragraphs in any order in the IDENTIFICATION division.

  • AUTHOR
  • INSTALLATION
  • DATE_WRITTEN
  • DATE_COMPILED
  • SECURITY
  • REMARKS

ACUCOBOL-GT does the same, even when not in the IBM DOS/VS compatibility mode.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


IF OTHERWISE

IBM DOS/VS COBOL optionally accepts the reserved word OTHERWISE instead of ELSE in IF statements. In the IBM DOS/VS COBOL compatibility mode, ACUCOBOL-GT accepts OTHERWISE as a synonym for ELSE.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


LENGTH OF Expression

The LENGTH OF construct works differently in ACUCOBOL-GT than in IBMCOBOL when the data item used is a table. ACUCOBOL-GT returns the size of the entire table, while IBM returns the size of a single element of the table. For example, consider the following:

01  my-data.
    03  my-table occurs 20 times.
        05  my-element-1   pic x(10).
 05  my-element-2   pic 99.
MOVE LENGTH OF my-element-1 TO data-size.
MOVE LENGTH OF my-table TO data-size.
MOVE LENGTH OF my-table(1) TO data-size.

ACUCOBOL-GT and IBM COBOL both treat the first MOVE as MOVE 10 TO data-size, and the third MOVE as MOVE 12 TO data-size. However, is treated differently. ACUCOBOL-GT treats the second MOVE as MOVE 240 TO data-size, while IBM COBOL treats the second MOVE as MOVE 12 TO data-size.

When using IBM compatibility mode, the ACUCOBOL-GT compiler treats LENGTH OF in the same way as IBM COBOL.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


NOTE Statement

IBM DOS/VS COBOL accepts a NOTE statement in the PROCEDURE division:

NOTE  character string(s)

The entire statement is treated as a comment.

If the NOTE statement is not first statement in its paragraph, then it ends when the first of these instances occurs.

  • the first period followed by a space
  • the beginning of the next paragraph
  • the end of the source code.

If the NOTE statement is the first statement in a paragraph, then it ends when the first of these instances occurs.

  • The beginning of the next paragraph
  • The end of the source code.

All subsequent statements in the same paragraph are also ignored.

In IBM DOS/VS COBOL compatibility mode, ACUCOBOL-GT accepts the NOTE statement as IBM DOS/VS COBOL does, with one slight difference. When a NOTE statement is the first statement in a paragraph, IBM DOS/VS COBOL parses subsequent statements in the same paragraph, and presumably flags any syntax errors found in them. ACUCOBOL-GT, however, does not perform any syntax parsing in such cases.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


Password Protection of Files

IBM DOS/VS COBOL implements password protection for files. You may put a PASSWORD clause into a SELECT statement, but only when the compiler is in the IBM DOS/VS COBOL compatibility mode. A SELECT statement (also called a file-control-entry) for a password-protected file must contain a PASSWORD clause of the following format:

     PASSWORD IS data-name-1

Here, data-name-1 is the name of an alphanumeric data item in the WORKING-STORAGE section of the Data Division. This data item must contain a valid password when the file is opened; otherwise, the OPEN statement fails.

To be compatible with IBM DOS/VS, ACUCOBOL-GT ignores the PASSWORD clause when in IBM DOS/VS compatibility mode.

Put the PASSWORD clause in any convenient spot after the ASSIGN clause.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


PROCESSING MODE Clause

IBM DOS/VS COBOL permits an optional PROCESSING MODE clause in a SELECT statement (also called a file-control-entry):

PROCESSING MODE IS SEQUENTIAL

IBM DOS/VS COBOL ignores this clause. Compatibility with IBM DOS/VS COBOL requires that ACUBOL-GT ignore it also.

You may put a PROCESSING MODE clause into a SELECT statement, but only when the compiler is in the IBM DOS/VS COBOL compatibility mode.

Put the PROCESSING MODE clause in any convenient spot after the ASSIGN clause.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


PROGRAM-ID Program Name

In IBM DOS/VS COBOL, the program name in the PROGRAM-ID item of the IDENTIFICATION division may be placed between quotation marks. This is especially useful if the program name contains embedded spaces or is otherwise incompatible with identifier syntax.

The ACUCOBOL-GT compiler accepts a program name in quotation marks, whether it is in the IBM DOS/VS COBOL compatibility mode or not.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


RECORDING MODE Clause

IBM DOS/VS COBOL permits an optional RECORDING MODE clause in a SELECT statement, also called a file-control-entry.

     RECORDING MODE IS mode

The mode must be F, V, U, or S. It describes the manner in which records are placed into blocks, which is irrelevant under DOS, Windows or Unix. Compatibility with IBM DOS/VS COBOL means that ACUCOBOL-GT ignores it.

You may put a RECORDING MODE clause into a SELECT statement, but only when the compiler is in the IBM DOS/VS compatibility mode.

Put the RECORDING MODE clause in any convenient spot after the ASSIGN clause.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


REVERSED Sequential Input Files

IBM DOS/VS COBOL contains a REVERSED option for input files, which is specified when the file is opened:

     OPEN INPUT file-name REVERSED.

The file must be a sequential file with a fixed record length. The OPEN operation fails if this is not the case.

The records in a REVERSED file are read in reverse order by ordinary READ statements. An attempt to read past the beginning of the file produces the same result as an attempt to read past the end of a regular sequential file.

ACUCOBOL-GT accepts this feature when in the IBM DOS/VS compatibility mode.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


SORT Statement Registers

IBM DOS/VS COBOL has 11 special registers associated with the SORT statement. ACUCOBOL-GT supports five of these. When in the IBM DOS/VS compatibility mode, ACUCOBOL-GT treats these as dummy registers, as though they had been declared at the beginning of the WORKING-STORAGE section as follows:

01  SORT-MESSAGE PIC X(8) EXTERNAL
77  SORT-FILE-SIZE PICTURE S9(8) USAGE COMP-4 VALUE 0.
77  SORT-CORE-SIZE PICTURE S9(8) USAGE COMP-4 VALUE 0.
77  SORT-MODE-SIZE PICTURE S9(5) USAGE COMP-4 VALUE 0.
77  SORT-RETURN PICTURE    S9(4) USAGE COMP-4 VALUE 0.

Special registers are reserved words that name storage areas, which are generated by the compiler. They do not need to be declared in the Working-Storage section of your program, and they can still be referenced as data items in your program. It's important to understand the data format for which they implicitly are created and to understand that they behave as though they were declared variables. These registers cannot be used as operands of ACCEPT or DISPLAY statements (as in IBM DOS/VS COBOL), but values can be moved to and from them.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


SPECIAL-NAMES

The following system names are supported by ACUCOBOL-GT in the SPECIAL-NAMES Paragraph:

SYSPCH
SYSPUNCH
C01 through C12
CSP
S01 through S05

The SYSPCH and SYSPUNCH names do not represent an actual card punch in ACUCOBOL-GT. Instead, output directed to the card punch is written to the file SYSPUNCH.TXT.

To enable printing to printer channels C01-C12, set the run time configuration variable called COBLPFORM. For details on setting this variable, see COBLPFORM.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features
Related information
DISPLAY UPON SYSPUNCH


TIME-OF-DAY

IBM DOS/VS COBOL has a TIME-OF-DAY register that contains the current time of day in HHMMSS format, where HH is the hour (on a 24-hour clock), MM is the minute, and SS is the second. Leading zeros are used where necessary to ensure two-digit values. For example, 8 AM would be 080000.

This register is valid only as the source of a MOVE statement without conversion.

When ACUCOBOL-GT is in the IBM DOS/VS COBOL compatibility mode, TIME-OF-DAY may be used as the source of a Format 1 MOVE statement:

     MOVE TIME-OF-DAY TO {dest-item} ...

If there are two or more destination items in the same MOVE statement, all are guaranteed to receive the same value, even if the clock ticks while the statement is being processed.

As usual, the value is truncated or padded with blanks at the right end to make it fit into the destination.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


TRACK-AREA Clause

IBM DOS/VS COBOL permits an optional TRACK-AREA clause in a SELECT statement (also called file-control-entry:

     TRACK-AREA IS integer-1 CHARACTERS

integer-1 is an integer.

This clause increases the efficiency of some file operations on the IBM System/360 Disk Operating System but is meaningless on other systems. ACUCOBOL-GT ignores it to remain compatible with IBM DOS/VS.

You may put a TRACK-AREA clause into a SELECT statement, but only when the compiler is in the IBM DOS/VS compatibility mode.

Put the TRACK-AREA clause in any convenient spot after the ASSIGN clause.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


TRANSFORM Statement

IBM DOS/VS COBOL has a TRANSFORM statement with the following syntax:

TRANSFORM  identifier-1  CHARACTERS FROM pattern-1 TO pattern-2

Each pattern is one of the following:

ZERO
ZEROS
ZEROES
SPACE
SPACES
QUOTE
QUOTES
LOW-VALUE
LOW-VALUES
HIGH-VALUE
HIGH-VALUES
nonnumeric-literal
identifier-2

identifier-2 must not be more than 255 characters long. If it is more than 255 characters long, the results in IBM DOS/VS COBOL are undefined; in ACUCOBOL-GT only the first 255 characters are used.

Each figurative constant (ZERO, ZEROS, ZEROES, SPACE, SPACES, QUOTE, QUOTES, LOW-VALUE, LOW-VALUES, HIGH-VALUE and HIGH-VALUES) is equivalent to a one-character nonnumeric literal containing the associated character. For example, ZERO is equivalent to 0 and HIGH-VALUE is equivalent to xFF.

One of the following conditions must hold:

  • pattern-1 and pattern-2 are the same length;
  • pattern-1 contains more than one character and pattern-2 contains exactly one character.

The effect of the TRANSFORM statement on the contents of identifier-1 is undefined if neither of these conditions holds. The effect on the contents of identifier-1 is also undefined if pattern-1 contains duplicate characters. However, the statement finishes in a reasonable time and control passes normally to the next statement in any case.

At run time, every character in identifier-1 that matches a character in pattern-1 is replaced by the character in the corresponding position in pattern-2. If there is no corresponding position, because pattern-2 is shorter than pattern-1, then it is replaced by the sole character in pattern-2.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


USE GIVING

IBM DOS/VS COBOL has a form of the USE statement in the DECLARATIVES section that normally is not recognized by ACUCOBOL-GT:

USE AFTER STANDARD ERROR PROCEDURE ON file-name GIVING
    data-name-1 [data-name-2]

This form is accepted by ACUCOBOL-GT when the -Cv option is in effect. For the format and rules governing the usage of this statement, see USE Statement. See IBM DOS/VS Error Codes for the IBM DOS/VS COBOL error codes.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


VALUE OF Clause

IBM DOS/VS COBOL and ACUCOBOL-GT ignore the following clause in a file description entry statement:

VALUE OF  value-pair-1  {value-pair-2} ...

Each value-pair is of the form

data-name-1 IS  {data-name-2 }
                {literal-1   }

You may put a VALUE OF clause into a file description entry, but only when the compiler is in the IBM DOS/VS compatibility mode.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


WHEN-COMPILED

IBM DOS/VS COBOL contains a reserved word, WHEN-COMPILED, that can be used as the source of a MOVE statement. The value copied into the destination or destinations is a string of the form MM/DD/YYhh.mm.ss, representing the time and date when the compilation began, where

MM | is the month (01 = Jan., 02 = Feb., etc.)
DD | is the day (01 to 31, inclusive)
YY | is the year, modulo 100 (99 for 1999, 00 for 2000, 01 for 2001, etc.)
hh | is the hour, on a 24-hour clock (00-23)
mm | is the minute (00-59)
ss | is the second (00-59)

ACUCOBOL-GT does the same when it is in the IBM DOS/VS COBOL compatibility mode. However, ACUCOBOL-GT also allows the programmer to use WHEN-COMPILED wherever a string constant can be used, not just as the source of a MOVE statement.

Note: The ACUCOBOL-GT object file (.ACU) contains an embedded compilation time and date, which is used for other purposes but is identical to COMPILE-TIME.
Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


WRITE ADVANCING Special-Name

IBM DOS/VS COBOL allows the following form of the ADVANCING clause in a Format 1 WRITE statement:

     {BEFORE}  ADVANCING  {identifier-2 LINES}
     {AFTER }             {integer LINES     }
                          {special-name      }

The special-name option is the only one that is not also in ACUCOBOL-GT. The special-name is one of the following special names, or a mnemonic for it defined in the SPECIAL-NAMES paragraph:

Special Name | Equivalent
CSP | 0 LINES
C01 | PAGE
C02 | none
C03 | none
C12 | none
S01 | none
S02 | none
S05 | none

Only CSP and C01 are implemented in ACUCOBOL-GT in the IBM DOS/VS COBOL compatibility mode. The others depend on particular hardware features and cannot be ported. They will generate error messages.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


XLM GENERATE and PARSE

ACUCOBOL-GT supports the IBM Enterprise COBOL XML GENERATE and XML PARSE statements. XML PARSE gives you a way to parse XML data and process it in a COBOL program, associating processing procedures with the exception and non-exception cases that can result from the parse. XML GENERATE gives you a way to translate COBOL data into XML.

As before, ACUCOBOL-GT also includes AcuXML, a run time-resident interface that transparently converts XML data to sequential files for COBOL processing, and C$XML, a library routine that gives you precise control over which elements or attributes of the data to parse. A developer utility called xml2fd creates File Descriptors (FDs) and SELECT statements from existing XML files to support AcuXML.

All three of these approaches can be used to parse records-based XML files, but note that only C$XML and XML PARSE can be used to parse non-records-based XML files.

Parent topic: ACUCOBOL-GT and IBM DOS/VS COBOL-Specific Features


Reserved Words

The following words are reserved in IBM DOS/VS, but not in ACUCOBOL-GT. They are, however, treated as reserved words by ACUCOBOL-GT when in IBM DOS/VS COBOL compatibility mode. You need to avoid using any of the IBM DOS/VS-specific reserved words as user-defined words.

ACTUAL | DISPLAY-ST | SKIP
BEGINNING | EJECT | SORT-CORE-SIZE
C01 | ENDING | SORT-FILE-SIZE
C02 | ENTRY | SORT-MODE-SIZE
C03 | EXAMINE* | SORT-RETURN
C04 | EXTENDED-SEARCH | SUPPRESS
C05 | FILE-LIMIT | SYSPCH
C06 | MASTER-INDEX | SYSPUNCH
C07 | NOMINAL | TALLY
C08 | NOTE | TIME-OF-DAY*
C09 | OTHERWISE | TRACK-AREA
C10 | PASSWORD | TRANSFORM*
C11 | POSITIONING | WHEN-COMPILED
C12 | PROCESSING | WRITE-ONLY
COM-REG | S01 | WRITE-VERIFY
CORE-INDEX | S02 |
CSP | S03 |
CURRENT-DATE* | S04 |
CYL-INDEX | S05 |
CYL-OVERFLOW | SEEK |

* In VSC2 mode these words are NOT reserved. See Support for DOS/VS COBOL for details on this mode. Note that CURRENT-DATE is a valid function in any compatibility mode.

Parent topic: IBM DOS/VS COBOL Conversions


COMP-1 and COMP-2 are Floating-Point

The treatment of COMP-1 (a.k.a. COMPUTATIONAL-1) and COMP-2 (a.k.a. COMPUTATIONAL-2) is different in IBM DOS/VS COBOL. They are equivalent to FLOAT and DOUBLE, respectively, and they cannot be used with PICTURE phrases.

ACUCOBOL-GT already has a command-line option ("-Df") to specify that COMP-1 and COMP-2 are to be treated as in IBM DOS/VS COBOL. The "-Cv" option automatically turns on this "-Df" option, and so additionally specifying "-Df" is unnecessary.

Take care to observe the proper syntax and usage of COMP-1 and COMP-2 variables for the mode in effect.

Parent topic: IBM DOS/VS COBOL Conversions


External Floating-Point (EFP)

The format of external floating-point (EFP) items is compatible with IBM DOS/VS COBOL. However, ACUCOBOL-GT will accept it even if it is not in the IBM DOS/VS compatibility mode.

Note: If a command-line option, such as "-Z4", is used to force the compiler to generate code for external floating-point items for a version of ACUCOBOL-GT prior to Version 5.0, then the compiler issues an "invalid picture" error.
  • External Floating-Point Data Type
  • The Picture
Parent topic: IBM DOS/VS COBOL Conversions


External Floating-Point Data Type

External floating-point (EFP) is a machine-independent floating-point data type defined with a PICTURE phrase. An EFP item is a numeric item. It is not an edited numeric item.

EFP items in ACUCOBOL-GT can be written to, and read from, data files, and they can be converted to and from other numeric data types.

An EFP item may be used anywhere a floating-point item may be used. When it is used in a DISPLAY statement, the assumed decimal point is shown, but no other editing is performed.

Note: Mixed-type operations are not well-defined in COBOL. Therefore, it is not advisable to mix internal floating-point (FLOAT or DOUBLE), external floating-point, and fixed-point numeric operands, except in simple MOVE statements.

EFP operations are always rounded off, even if the ROUNDED option is not used.

No USAGE, SIGN, SYNCHRONZED, JUSTIFIED or VALUE clause may be used with an EFP item.

Parent topic: External Floating-Point (EFP)


The Picture

An external floating-point (EFP) data item is defined by a picture that strongly resembles a floating-point numeric literal:

{+} mantissa E {+} 99
{-}            {-}

The mantissa is a string containing:

  • from one to sixteen "9"s, and
  • one assumed decimal point (that does not appear in the data) represented by the letter "V", or one actual decimal point (that does appear in the data) represented by a period ".".

The exponent is always exactly two digits long, so the last two characters of the picture must be "99".

A plus sign "+" in the picture indicates that a nonnegative mantissa or exponent will be preceded by a plus sign; a minus sign "-" indicates that a nonnegative mantissa or exponent will be preceded by a space.

A negative mantissa or exponent is always preceded by a minus sign.

When a numeric value is converted to EFP format, the result is normalized so that the leftmost digit of the mantissa is nonzero, if this can be done without reducing the exponent below "-99". Zero is represented by a mantissa and exponent consisting entirely of zeros.

When exponent overflow occurs, the mantissa of the result consists entirely of "9"s, and its exponent is "+99".

When exponent underflow occurs, the result is not normalized, and may be zero if it is too small to be represented in this format.

Examples:

picture | value | data | notes
+9.999E+99 | 123 | +1.230E+02 |
+9.999E+99 | 123.0E99 | +9.999E+99 | exponent overflow
-9V999E+99 | 123 | 1230E+02 |
-9V999E-99 | 123 | 1230E 02 |
+V9999E-99 | 0.0123 | +1230E-01 | note normalization
+V9999E-99 | 0.01E-99 | +0100E-99 | exponent underflow
-99999.E+99 | 123 | 12300.E-02 |
Parent topic: External Floating-Point (EFP)


IBM DOS/VS Error Codes

IBM DOS/VS COBOL has a form of the USE statement in the DECLARATIVES section that is not recognized by ACUCOBOL-GT:

USE AFTER STANDARD ERROR PROCEDURE ON file-name GIVING
       data-name-1 [data-name-2]

This form is accepted by ACUCOBOL-GT when the -Cv option is in effect.

When an error handler introduced by this statement is invoked, the runtime puts special error codes into the eight-byte data item data-name-1. Each byte is loaded with 1s if the corresponding error condition is true. If the corresponding error condition is false, ACUCOBOL-GT loads it with zeros.

Here are the IBM conditions:

byte | indexed | direct | sequential
1 (leftmost) | DASD error | data check in count | parity error
2 | wrong record length | wrong record length | wrong record length
3 | prime data full | no room found |
4 | cylinder index too small | data check in key or data |
5 | master index too small |  |
6 | overflow area full |  |
7 | no EOF record written in prime data area |  |

This is how the preceding error conditions are mapped into the conditions detected by ACUCOBOL-GT:

85 | 74 | Vax | DG | IBM | data-name-1
00 | 00 | 00 | 00 | 00 | 10000000
48 | 91 | 48 | 92 | 13 | 10000000
49 | 91 | 49 | 92 | 13 | 10000000
47 | 91 | 47 | 92 | 13 | 10000000
42 | 91 | 94 | 91 | 92 | 10000000
38 | 93 | 38 | 92 | 93 | 10000000
41 | 92 | 41 | 91 | 93 | 10000000
37 | 95 | 37 | 91 | 93 | 10000000
93 | 93 | 91 | 94 | 93 | 10000000
94 | 94 | 97 | 97 | 93 | 01000000
48 | 90 | 48 | 92 | 13 | 10000000
24 | 24 | 24 | 24 | 24 | 00100000
22 | 22 | 22 | 22 | 22 | 00010000
24 | 24 | 24 | 24 | 24 | 00010000
34 | 34 | 34 | 34 | 34 | 00100000
30 | 30 | 30 | 30 | 30 | 10000000
48 | 90 | 48 | 92 | 13 | 10000000
49 | 90 | 49 | 92 | 13 | 10000000
23 | 23 | 23 | 23 | 23 | 01000000
99 | 99 | 92 | 94 | 23 | 10000000
44 | 97 | 44 | 92 | 21 | 01000000
43 | 90 | 43 | 92 | 23 | 01000000
47 | 90 | 47 | 92 | 13 | 10000000
10 | 10 | 10 | 10 | 10 | 01000000
42 | 91 | 42 | 92 | 92 | 10000000
05 | 00 | 05 | 00 | 10 | 10000000
39 | 94 | 39 | 9A | 95 | 01000000
46 | 96 | 46 | 10 | 21 | 01000000
9A | 9A | 9A | 9A | 23 | 10000000
02 | 02 | 02 | 00 | 00 | 00010000
35 | 94 | 35 | 91 | 93 | 10000000
37 | 90 | 39 | 91 | 93 | 10000000
98 | 98 | 30 | 9B | 93 | 01000000
94 | 94 | 39 | 92 | 93 | 01000000
9B | 9B | 9B | 9B | 23 | 10000000
02 | 02 | 00 | 00 | 00 | 00010000
07 | 00 | 07 | 00 | 00 | 10000000
14 | 00 | 14 | 00 | 00 | 01000000
24 | 00 | 24 | 00 | 24 | 10000000
21 | 21 | 21 | 21 | 21 | 00010000
9C | 9C | 9C | 9C | 23 | 10000000
0M | 0M | 0M | 0M | 00 | 10000000
9D | 9D | 9D | 9D | 92 | 10000000
9Z | 9Z | 9Z | 9Z | 92 | 10000000
9E | 9E | 9E | 9E | 92 | 10000000
Parent topic: IBM DOS/VS COBOL Conversions


Copyright and Legal Information

  • Copyright and Trademarks
Parent topic: Transitioning to ACUCOBOL-GT Version 10.2.0


Copyright and Trademarks

Copyright © Micro Focus 1984-2018. All rights reserved. The software and information contained herein are proprietary to, and comprise valuable trade secrets of, Micro Focus, which intends to preserve as trade secrets such software and information. This software is an unpublished copyright of Micro Focus and may not be used, copied, transmitted, or stored in any manner other than as expressly provided in a written instrument signed by Micro Focus and the user. This software and information or any other copies thereof may not be provided or otherwise made available to any other person.

Micro Focus has made every effort to ensure that this book is correct and accurate, but reserves the right to make changes without notice at its sole discretion at any time. The software described in this document is supplied under a license and may be used or copied only in accordance with the terms of such license, and in particular any warranty of fitness of Micro Focus software products for any particular purpose is expressly excluded and in no event will Micro Focus be liable for any consequential loss.

MICRO FOCUS, the Micro Focus logo, and Micro Focus product names are trademarks or registered trademarks of Micro Focus IP Development Limited or its subsidiaries or affiliated companies in the United States, United Kingdom, and other countries. All other marks are the property of their respective owners.

IBM®, z/OS®, CICS®, DB2®, MQSeries®, RACF® and WebSphere® are registered trademarks, and IMS™ is a trademark, of International Business Machines Corporation.

All other trademarks are the property of their respective owners.

Reference to third party companies, products and web sites is for information purposes only and constitutes neither an endorsement nor a recommendation. Micro Focus provides this information only as a convenience to users. Micro Focus makes no representation whatsoever regarding the content of any other web site or the use of any such third party products. Micro Focus shall not be liable in respect of your use or access to such third party products/web sites.

No part of this publication, with the exception of the software product user documentation contained on a CD-ROM, may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to any electronic medium or machine-readable form without prior written consent of Micro Focus.

Licensees may duplicate the software product user documentation contained on a CD-ROM, but only to the extent necessary to support the users authorized access to the software under the license agreement. Any reproduction of the documentation, regardless of whether the documentation is reproduced in whole or in part, must be accompanied by this copyright statement in its entirety, without modification.

U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and the Documentation were developed at private expense, that no part is in the public domain, and that the Software and Documentation are Commercial Computer Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFAR 252.227-7013 et. seq. or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at FAR 52.227-19, as applicable. Contractor is Micro Focus, One Irvington Center, 700 King Farm Boulevard, Suite 400, Rockville, Maryland 20850. Rights are reserved under copyright laws of the United States with respect to unpublished portions of the Software.

2018-03-23

Parent topic: Copyright and Legal Information


Notations and Conventions

COBOL Conventions
  • PIC X is used rather than PIC 99 with the COMP-X and COMP-5 data types. Unlike PIC 99, PIC X shows the length of the data item and so demonstrates more clearly the use of COMP-X, which is to define a binary item of the specified number of bytes.
Command Line Format
  • Words printed in italics are generic terms representing names to be devised by you.
  • Words printed in nonitalic characters are the actual words you must enter. You must type them in upper or lower case as shown.
  • Material enclosed in square brackets [ ] is optional.
  • When material is enclosed in braces { }, you must choose from the options within them. If there is only one option in the braces, the braces indicate repetition.
  • The ellipsis (. . .) follows { } or [ ] and means you can repeat the material in the { } or [ ]. The number of repetitions allowed is unlimited unless otherwise stated. If the ellipsis is used with [ ] the material can be omitted altogether.
  • If a command line does not fit across the page, it is continued on the next line; the continuation line is indented.
Keyboard Keys
  • Key names and menu choices are emboldened within the text.
  • Enter refers to the carriage return or Enter key. Where commands to be typed are shown, the Enter key is not explicitly shown; it is treated as implicit that Enter must be pressed at the end of the line.
Numbers
  • Hexadecimal numbers are enclosed in quotation marks and preceded by a lower-case "x" or "h"; for example, x"9D", h"03FF". The "x" is used when the hexadecimal number represents a character string; the "h" when it represents a numerical value.
Path Specifications
  • All path specifications are based on installation to the default installation directory. If you have installed Visual COBOL to a non-default installation directory, adjust the path specifications accordingly.
User Interface
  • Menu choices, and UI control and field names are emboldened within the text.
  • In some environments, you might notice that what appears on your screen differs in minor ways (for example, version numbers) from that illustrated in this Help. This does not affect the operation of your software.
Parent topic: Transitioning to ACUCOBOL-GT Version 10.2.0


A Programmer’s Guide to the Internet Version 10.2.0

  • Copyright Statement
  • Introduction
  • Choosing a Deployment Method
  • Using the Thin Client to Launch Web Applications
  • Launching Web Applications Through CGI
  • Using the ACUCOBOL-GT Web Runtime
  • Other Internet Solutions
  • Appendix A. Adding Internet Features to Your Program
  • Appendix B: Using the Runtime as a Helper Application or Viewer
Parent topic: extend Programming Guides


Introduction

  • Introduction
  • Purpose/Scope of Book
  • What You Need to Know
  • What You Don't Need to Know
  • Product Integration
  • Technical Services
Parent topic: A Programmer’s Guide to the Internet Version 10.2.0


Introduction

Unlike anything before it or since, the Internet has taken the world of computing by storm. It is said that over 800 million people have Internet access today, that there are over 400 million Web sites. Even after the implosion of the dot com era, some industry watchers report that the number of Internet users is growing at a rate of 10% per month, and that the number of Web sites grows by 1.5 million each day.

So it's no wonder that the Internet, the Web, and the promise of electronic commerce remain a vital concern to corporate IS departments. How can they take advantage of the infrastructure that's in place, not to mention the user base that it reaches? Do companies have to start over, retrain their development staff, spend most of their computing budget?

On the contrary, Internet commerce is closer at hand than you might think. Rather than rebuilding your applications with a new "Internet" language, you can provide access to applications and data over the Internet without ever leaving COBOL!

Using extend technologies, you can deploy existing ACUCOBOL-GT® applications on the Internet today. This book explains how. You can make your applications accessible through popular Internet browsers and the World Wide Web, or you can harness the Internet in a more secure TCP/IP networking configuration. When new Internet initiatives surface, you can perform your development in ACUCOBOL-GT, or you can combine your COBOL programs with other Internet languages and technologies.

Parent topic: Introduction


Purpose/Scope of Book

This book is designed to teach ACUCOBOL-GT developers how to deploy applications on the Internet. It includes a glossary of Internet technology and terminology, a description of alternative approaches to Internet deployment, specific instructions on implementing each approach, and samples where appropriate.

After reading this book, ACUCOBOL-GT developers will have a clear understanding of how to integrate COBOL programming with their current Internet strategies, how to shape future Internet strategies, and how to minimize development time and expense.

References to Windows in this manual denote any of the supported Windows platforms, which are listed in the Product Availability section on the Micro Focus SupportLine Web site: http://supportline.microfocus.com/prodavail.aspx. Where it is necessary to make a distinction, the specific version name/number is specified.

Parent topic: Introduction


What You Need to Know

Although you may believe that the Internet is quite complex, all that you need to know to deploy your ACUCOBOL-GT applications over the Internet is COBOL. You can choose to use popular Internet languages like HTML, XML, and Java to deploy your applications, but you don't have to. You can even write your CGI (Common Gateway Interface) programs in COBOL, if you use them at all. This book explains both how to stay with what you know, COBOL, and how to combine COBOL with other Internet technologies.

So what are your prerequisites for using this book?

You must be a COBOL developer familiar with ACUCOBOL-GT.

That's it!

Parent topic: Introduction


What You Don't Need to Know

To use this book, you do not need to be expert in:

  • HTML
  • XML
  • CGI
  • Java

This book provides an overview to all of these languages and technologies. If you choose to use them in your application deployment, this book gives you some valuable guidelines and instructions as well as references to more detailed information. It also provides alternatives so that you can leverage your expertise in COBOL whenever possible.

Parent topic: Introduction


Product Integration

This book describes several methods for deploying ACUCOBOL-GT applications over the Internet. All of the methods described involve one or more technologies from the extend family of solutions. Just as all of the technologies in the extend family work together to provide a complete enterprise computing solution, the extend technologies work together to provide a complete Internet solution as well. extend technologies can work alone or in combination with other technologies, depending on the functions that you require. For example:

  • If you want to provide access to remote Vision, relative, or sequential data and object files over the Internet, you can use our AcuServer® file server technology.
  • If you want to provide access to that data from a Web link, you can combine our Web thin client or Web runtime technology with AcuServer. Our AcuConnect® application server may be used to serve the thin client requests or to launch remote application components in a distributed environment.
  • If you want to provide access to remote RDBMSs and applications, you can use our Acu4GL® COBOL-to-RDBMS interface in combination with AcuConnect and/or the thin client. Or you can embed SQL into your COBOL application and use our AcuSQL® precompiler in combination with these technologies.
  • If you want to provide a user interface in HTML, you can write CGI programs in ACUCOBOL-GT to bridge the HTML and COBOL.
  • And the list goes on . . .

For clarity, this book describes the simplest scenarios. Remember that a combination of approaches may in fact be more ideal for you.

Note: Although you can use earlier versions of extend technologies to deploy your applications and data on the Internet, the information included in this book is specific to the extend Version 8 and higher. For Internet-related information on previous versions of our technologies, please refer to an earlier version of this book.
Parent topic: Introduction


Technical Services

You can reach Technical Services in the United States Monday through Friday from 6:00 a.m. to 5:00 p.m. Pacific time, excluding holidays. You can also raise and manage product issues online and follow the progress of the issue or post additional information directly through our website. Following is our contact information:

Phone: | +1 858.795.1902
Phone: | 800.399.7220 (in the USA and Canada)
Fax: | +1 858.795.1965
E-mail: | support@microfocus.com
Online: | http://supportline.microfocus.com

For worldwide technical support information, please visit:

http://supportline.microfocus.com

Parent topic: Introduction


Choosing a Deployment Method

  • What Are My Options?
  • Helping You Decide
Parent topic: A Programmer’s Guide to the Internet Version 10.2.0


What Are My Options?

We offer a variety of different solutions for deploying COBOL applications on the Internet.

Some of them allow you to make your COBOL programs and data accessible on the Web from popular Internet browsers. Others allow you to harness the Internet in a more secure TCP/IP networking configuration.

When discussing your alternatives, we frequently make a distinction between the Internet and Web. We define the Internet as a global TCP/IP network, and the Web as a mechanism for finding and viewing information on the Internet.

Our Web-based solutions involve the use of browsers and often links on a Web page. Our other Internet solutions use more traditional methods of launching applications.

  • Web Solutions
  • Other Internet Solutions
Parent topic: Choosing a Deployment Method


Web Solutions

Following are some of the ways you can deploy your applications on the Web:

  • You can add the ACUCOBOL-GT® Web Thin Client to your Web page so that when users visit your site, the thin client downloads and installs on their machines and automatically launches your application on the server. In thin client architectures, the application logic runs on the server. Only the user interface displays on the client.
  • You can add the ACUCOBOL-GT Web Runtime to your Web page so that when users visit that page, the runtime downloads and installs on their machines and automatically launches your application locally.
  • You can create a Web interface to your COBOL application and allow users to interact with pages on your Web site via an HTTP browser or mobile device using our COBOL CGI technology.

These options are described below in more detail. If your users already have a licensed copy of the ACUCOBOL-GT runtime on their machine, they can also gain access to your applications on the Web by setting up the runtime as an Internet helper application or viewer inside their browser. When they click a link on your Web site, the browser knows to associate the application with the ACUCOBOL-GT runtime. This is discussed in Use the Runtime as a Helper Application or Viewer.

In addition to all of these approaches to Web application deployment, ACUCOBOL-GT includes a WEB-BROWSER control that lets you add a variety of Internet features to your COBOL program. With this control, your programs can support Web browsing, display HTML pages, invoke e-mail, Telnet, and FTP services, and more.

Web Thin Client

If you want Windows users to launch applications from your Web site and have the applications run exclusively on the remote server, you can use the ACUCOBOL-GT Web Thin Client. In this scenario, end users simply visit your Web site. The Web browser searches for the Web thin client on their machines. If successful, it launches the program on the server. If it cannot locate the Web thin client, it provides the software automatically with users' permission. It then invokes the server application transparently and "projects" the user interface back onto the client. The Web thin client is an ActiveX version of our thin client solution.

Alternatively, end users can install the standard ACUCOBOL-GT Thin Client on their local machine. They can install it from any ACUCOBOL-GT media or, subject to appropriate licensing agreements, you can distribute it on your Web site so that end users can download and install it from there. Using an Active Server Page (ASP), Java Server Page (JSP), Visual Basic, or Perl script, you can automate the download and install process for users if you like. Once they have the thin client installed, they can visit your Web site and click a link to invoke your application.

Thin client users always have the option of executing the acuthin command with an Internet server or IP address as part of the command parameters. acuthin can launch programs on any server in a TCP/IP network, including the Internet. The only components required on the client in this case are the thin client software and an Internet connection. Users don't even need to have a Web browser.

With any of these thin client options, all application processing is performed on the server. Usually, data access is considered local because the data resides on the same server machine as the application. If you want to keep data on a different server in a multi-tiered configuration, you can combine the thin client with our AcuServer® technology. Please note that although the thin client supports only Windows clients, it gives access to both Windows and UNIX servers running the AcuConnect® application server software.

Using the Thin Client to Launch Web Applications describes Internet application access via the ACUCOBOL-GT Thin Client and Web thin client.

COBOL CGI

Perhaps you want customers or users to run your applications by clicking a link on your Web site, but you don't want to require anything special of the user's machine (for instance, the presence of any ACUCOBOL-GT runtime, be it a standard, thin client, or Web runtime). In this case, you can create a new interface to your application using a markup language such as HTML, WML, or XML. With a Web interface, your application can be interpreted directly by the user's HTTP browser or mobile device, and the processing logic can remain in COBOL on the Web server.

In this scenario, you create your Web interface using one of many popular authoring tools. Then you write a Common Gateway Interface (CGI) program that can read CGI variables submitted by the client to the server. This program can launch your COBOL application or it can be a COBOL program itself. You can write it using ACUCOBOL-GT or any other language you choose. If you write the program in ACUCOBOL-GT, you do not have to UNSTRING the CGI variables in the program, because ACUCOBOL-GT takes care of this for you through special IS EXTERNAL-FORM syntax.

By default, your CGI program reads and writes HTML content for use in standard HTTP browsers and mobile devices. But using configuration variables, you can associate your program with the MIME content type for WML so that data can be displayed on WML-based devices as well.

Once you build a Web front end and write a CGI program, your customers or users can then visit your Web site and gain instant access to your COBOL application running on the server.

Note that CGI programs are inherently stateless–that is, they do not store information about previous browser actions. If you require a persistent connection to the browser, you can achieve this by adding pointers and cookies to your CGI program, or you may choose a different method.

This option runs on any platform where ACUCOBOL-GT runs, but it also requires the most coding. You can employ the CGI method wherever a user interface via DISPLAY/ACCEPT statements is not used. This includes batch processes, processes that use socket routines to communicate with an external UI, component adapter technology processes, BEA Tuxedo processes, and processes launched via AcuConnect in distributed processing mode, to name a few. The CGI method is described in Launching Web Applications Through CGI.

Web Runtime

Another way to give end users access to your applications on the Web is to provide runtime services through the ACUCOBOL-GT Web Runtime.

Using this approach, you set up a Web site and embed a link to your ACUCOBOL-GT application. Because the Web runtime is freely distributable (in accordance with the terms and conditions of your Micro Focus extend license agreement), you embed the runtime in the link as well by designating the URL of our Web site in your HTML coding. Users can then visit your site and click a link to launch the program. If the Web browser detects that users do not yet have a runtime installed on their machine, it automates the install process, with the users' permission, and then launches the COBOL program locally.

The Web runtime is available only on supported Windows machines, but it gives users access to programs or data hosted on other platforms using AcuServer and AcuConnect.

The ACUCOBOL-GT Web Runtime is geared for Internet Explorer environments. It relies on ActiveX technology and does not run on any current versions of Netscape.

Using the ACUCOBOL-GT Web Runtime describes this option in detail.

Parent topic: What Are My Options?


Other Internet Solutions

Following are some of our solutions for harnessing the Internet in a secure TCP/IP networking configuration:

  • AcuServer can be used to provide access to Vision data over the Internet.
  • AcuConnect can be used to provide access to server-resident COBOL programs over the Internet, even programs that are distributed across a number of different servers.
  • The AcuXDBC™ interface can be used to give users of Windows applications access to Vision data over the Internet. AcuXDBC is combined with AcuXDBC Server for remote processing of SQL requests.
  • The Acu4GL® interface and the AcuSQL® precompiler can be used to provide access to relational databases over the Internet.
  • AcuXML can be used to provide access to XML documents over the Internet.

All of our technologies are designed to work in TCP/IP networks. Because the Internet is just a large TCP/IP network, you can use these same proven technologies in Internet deployments. For details, see Web Solutions.

Parent topic: What Are My Options?


Helping You Decide

Many factors go into deciding your Internet implementation. In this section, we present some questions to think about as you proceed. In the chapters that follow, we use examples to demonstrate how these questions will affect your decision on how to deploy Internet- or Web-based applications.

How much do you want the user to do?

Simply visit your site? | —> | Write a Web interface to your application then write a small CGI program to handle the communications between the interface and the program on the server, or embed the Web runtime or Web thin client on your Web page.
Download and install a free runtime? | —> | Include the standard thin client on your Web page.
Click a link? | —> | Create a hyperlink to the Web runtime or Web thin client on your Web page; or set up the runtime as a helper application or viewer in the browser.
Purchase a fully-licensed runtime? | —> | Set the runtime up as a helper application or viewer in the browser.

How much programming are you willing to undertake?

Perform no new programming? | —> | Use the Web runtime or possibly Web thin client. (If you're already using the thin client, no new programming is required.)
Re-engineer the application to distribute the processing among several machines? | —> | Use AcuConnect.
Write a markup language front-end and a small CGI program in COBOL? | —> | Use our COBOL CGI solution.
Write an entirely new Internet program? | —> | Write it in ACUCOBOL-GT. You can feed COBOL data to browsers using our CGI syntax, and you can embed Internet browsing into your program using our WEB-BROWSER control.

Do you need to provide remote access to programs, data, or both?

Programs | —> | Use any of our thin client or AcuConnect solutions.
Data | —> | Use AcuServer, Acu4GL or AcuXDBC.
Programs and data | —> | Use a combination of these technologies.

Do you want to provide Web access or more private access?

Web access | —> | Use our Web thin client, COBOL CGI solution, or Web runtime.
More private access | —> | Use AcuServer, AcuConnect, or thin client.

How is your application designed?

Does your application perform lots of file I/O? | —> | Distribute the processing via AcuConnect or offload all the processing onto the server via the thin client or Web thin client.
Does the executing program require client computer access? | —> | Use the Web runtime or a fully-licensed runtime.
Does the program need to execute if a network is unavailable? | —> | Use the Web runtime or a fully-licensed runtime.

Do you require a persistent connection to the server (i.e., Does the server need to remember the last action from the browser)?

Yes —> Use the thin client, Web thin client, Web runtime with AcuConnect, or add pointers and cookies to your CGI program to store browser information. (CGI programs are inherently stateless.)

How frequently do you update your programs and data?

Frequently —> Use a server-processing solution like the standard thin client, Web thin client, and/or AcuConnect, or a remote file server like AcuServer.

What are the operating environments of your user population?

Windows clients and servers? | —> | You may use any of our Internet solutions.
UNIX clients and servers? | —> | Use our COBOL CGI solution for Web access. Use our other technologies such as AcuServer, AcuConnect, and Acu4GL in Internet deployments.
Windows clients and UNIX servers | —> | You may use any of our Internet solutions.
Parent topic: Choosing a Deployment Method


Using the Thin Client to Launch Web Applications

  • What Is the Thin Client?
  • How the Thin Client Works
  • Thin Clients and the Internet
  • Specifying an Internet Address on the Command Line
  • Providing Thin Client Links on the Web
  • Using the ACUCOBOL-GT Web Thin Client
Parent topic: A Programmer’s Guide to the Internet Version 10.2.0


What Is the Thin Client?

Our thin client technology is an innovation that lets you display the user interface portion of your server-based application on Windows graphical display hosts.

The thin client technology is designed for two main purposes:

  • To allow ACUCOBOL-GT® programs running on a UNIX or Windows server to present a full Windows graphical user interface (GUI) on PCs networked with TCP/IP. To present a graphical user interface, you must convert the application screens to graphical, if you have not done so already. Character-based user interfaces are also supported, with some restrictions. In either case, your application stays in one piece on the UNIX or Windows server.
  • To allow both UNIX and Windows users to enjoy the benefits of centralized application maintenance and to adopt the performance characteristics of a thin architecture, reducing the total cost of ownership (TCO). Many applications perform better when deployed in a thin fashion compared to other networking techniques such as remote file access (fat clients) or distributed processing. This is because thin client configurations execute COBOL programs on the server where data access is local.

Although designed for local and wide-area TCP/IP networks, our thin client solution is well-suited to low-bandwidth, high-lag connections like the Internet because it eliminates the file I/O occurring over the network.

Sample Scenario

Your inventory program is UNIX-based. However, you know that many of your users typically work at Windows PCs or laptops, rather than UNIX workstations. On the road, sales people often connect to your application from their hotel rooms at low data speed connections.

The ACUCOBOL-GT Thin Client provides a way for you to keep your UNIX program, yet enable users to work in a graphical Windows environment. Users can simply visit your Web site to launch the program. They never know that they are running a UNIX program because all they see is the Windows UI.

Because processing is done on the server, your users don't have to be running especially powerful machines to be able to work efficiently with your program. The thin client's low bandwidth abilities make it especially desirable for users who are out of office and using cellular connections to laptops.

If the data file for the inventory program is remote to the application, you can use the AcuServer® file system interface to give your customers and staff access to that file.

Parent topic: Using the Thin Client to Launch Web Applications


How the Thin Client Works

In a thin client configuration, your application is composed of two logical layers: a user interface (UI) layer on the display host (client) and a COBOL layer on the application host (server). The UI layer handles screen, mouse, and keyboard activity, and the COBOL layer performs application processing. Because no application components are required on the client (unless you use ActiveX controls), it is considered to be "thin."

Rather than forcing you to split your application into client and server components, the ACUCOBOL-GT runtime has been split so that your existing application can be displayed on the client. The portion that is installed on the client is known as the ACUCOBOL-GT Thin Client. Currently, the thin client runs only on Windows machines. The full ACUCOBOL-GT runtime is installed on the server.

To function, the split runtime makes use of the AcuConnect® application server software. The role of AcuConnect is to listen for requests from clients to launch the ACUCOBOL-GT runtime on the server. You license the server runtime for a specific number of concurrent users.

Together, the ACUCOBOL-GT Thin Client, the ACUCOBOL-GT runtime, and AcuConnect are the enabling technologies that make up our thin client solution.

For a comprehensive look at the thin client technology, please refer to the AcuConnect User's Guide.

Parent topic: Using the Thin Client to Launch Web Applications


Thin Clients and the Internet

Our thin client can be deployed over the Internet just as easily as a local- or wide-area network. There are three ways to accomplish this:

  1. You can specify the name and port number or IP address of the server you are accessing when you enter thin client command line parameters. See Specifying an Internet Address on the Command Line for details.
  2. You can create a command line file that contains all the information needed by the ACUCOBOL-GT Thin Client to launch your application. You can then create a link on your Web page to this file, and if your license permits it, to a self-extracting archive for the thin client. Users can then download the thin client from your Web site and click a link to launch your program. See Providing Thin Client Links on the Web for details on this method.
  3. You can place an ActiveX version of the thin client, known as the ACUCOBOL-GT Web Thin Client, on your Web page. When set up properly, the Web thin client automates the process of download and install for end users, and it automatically invokes your application as well. See Using the ACUCOBOL-GT Web Thin Client for details.
Note: Review the license agreements of any third-party product that may be invoked when you are accessing the server from a remote location through the ACUCOBOL-GT Thin Client. For instance, if you will be accessing a Windows server through a virtual private network, you should review Microsoft's end user license agreement.
Parent topic: Using the Thin Client to Launch Web Applications


Specifying an Internet Address on the Command Line

The ACUCOBOL-GT Thin Client can work in an Internet environment independent of the Web and Web browsers. After all, the Internet is just a big TCP/IP network. When end users invoke the ACUCOBOL-GT Thin Client in an Internet environment, they type command line parameters that specify the server name, optionally the port number of the server they are accessing over the Internet, the name of the application, and any additional runtime command line parameters. For example:

acuthin bigserver.acucorp.com:5632 myprog1 10 20 30

Note that clients must have a live Internet connection when they execute this command, and the server name that they enter must be resolvable by the Internet name server used by their service provider. The Internet name server then resolves the name with its IP address.

If the server name is not exposed to Internet name servers, end users can enter the explicit IP address on the ACUCOBOL-GT Thin Client command line as in the following example:

acuthin 128.110.121.42:5632 myprog1 10 20 30

If the server is through a Virtual Private Network (VPN), the user must connect to the network before entering the acuthin command.

Note: If desired, users can set up a Windows shortcut so that they do not have to enter a command line in order to launch the thin client.
Parent topic: Using the Thin Client to Launch Web Applications


Providing Thin Client Links on the Web

If you want to give users access to your application on the Web, one way to do this is to distribute the thin client software on your Web page (license agreement permitting), and provide a link to a command line file that launches your application. Users visit your page, download and install the thin client software, and click the command file link to run your program.

To provide this method of Web access, do the following:

  1. Install your COBOL application on your application server host. This machine must also contain the ACUCOBOL-GT runtime, AcuConnect, and several additional components. These are listed in the AcuConnect User's Guide. Note that your application does not need to reside on the same host as your Web Server.
  2. Create a thin client command line file that contains all the information needed by the ACUCOBOL-GT Thin Client to launch your application. The format of this file is described in Thin Client Command-Line Files.
  3. Place the command line file and, license agreement permitting, the self-extracting archive for the thin client on your Web server. The archive name is ' extend(R) Thin Client Version 10.1.1.exe'. Create links to these files from an appropriate Web page. See Using Anchor Tags for instructions on creating links.
  4. To ensure that your thin client will be recognized across a wide variety of browsers, configure your Web server to generate the HTTP Content-type response header field containing the MIME type application/vnd.acucorp.thincommandline for the extensions .atc and .acutc. This is particularly necessary if your end users have newer versions of Windows (such as Windows XP, SP2). Refer to your Web server documentation for instructions on adding a MIME type.

After you have followed these steps, instruct your users to visit your Web page and click the thin client link to download and install the thin client. It is a self-extracting archive that will guide your users through the installation process. If you prefer, your users can install the ACUCOBOL-GT Thin Client on their machines from any of our media, or they can download the thin client from the support section of our Web site, http://www.microfocus.com.

After they have the thin client on their machines, users can visit your Web site anytime and click the program link to launch your thin client application. The program runs on your application server host and the display occurs in an application window on the users' machine, outside of their browser.

Note: If you want to automate the process for end users, you can write an ASP, JSP, VB, or Perl script that uses cookies to check for thin client installations. The user can activate the script by clicking a link on your Web site. The cookie can search for thin client installations on the user's machine, verify that the version is current if one is located, then launch the server application automatically. If a thin client installation is not found or is outdated, it can prompt the user to download new thin client software.
  • Thin Client Command-Line Files
  • Using Anchor Tags
  • Security and the ACUCOBOL-GT Thin Client
Parent topic: Using the Thin Client to Launch Web Applications


Thin Client Command-Line Files

When users install the ACUCOBOL-GT Thin Client on a Windows display host, the .atc and .acutc file extensions are automatically associated with the thin client executable (acuthin.exe). As a result, when your browser downloads one of these files, it uses these associations to invoke acuthin.exe. To establish the command line parameters that the executable should use, including the name and location of the server application it should launch, you must create a thin client command line file.

Format the thin client command line file as you would any ACUCOBOL-GT configuration file, with each entry on its own line. You can include any of the following variables in the file:

Variable name | Description
atc-server | the name or IP address of the server to connect to (a required variable with no default value)
atc-port | the TCP port number to use to grant access to thin client applications (default value is 5632)
atc-runtime-options | runtime options passed to the runtime via AcuConnect (no default value)
atc-alias | an alias that identifies a COBOL application on the server (a required variable with no default value)
atc-user | the username with which you want to log onto the AcuConnect server
atc-password | the password assigned to this username for granting access to AcuConnect.
atc-splash-screen | when set to off (0, false, no), an option that disables the thin client start-up splash screen
atc-cobol-args | COBOL arguments passed to your COBOL program via AcuConnect (no default value)
atc-trace | trace options passed to the runtime via AcuConnect (default 0, meaning no trace). Equivalent to the -t command-line option.

Note that comment lines (preceded by the "#" character) are allowed in this file, as they are in other configuration files.

When you are done, save the file with an .atc or .acutc extension.

The contents of the .atc or .acutc file are interpreted by the thin client as the following command line:

acuthin <atc-server>[:<atc-port>] [atc-runtime-options]
        <atc-alias> [<atc-cobol-args>]
Parent topic: Providing Thin Client Links on the Web


Using Anchor Tags

Use the HTML Anchor tags to create two separate links: one to your COBOL application and another to the self-extracting archive of the thin client runtime. The HTML Anchor tags, <A> and </A>, are closed elements that, when combined with the HREF attribute, highlight text or images, making them clickable. When users click on a highlighted item on your Web page, they are transferred to the linked document.

In the case of the thin client runtime, when the user clicks the highlighted item, the runtime automatically downloads to the user's machine. When the download is complete, the self-extracting archive guides the user through an automated installation process.

In the case of the thin client command line file, when the user clicks the highlighted item, the thin client application is automatically invoked.

To turn text into a hypertext anchor, enclose the clickable text in the Anchor tags. For example, enter the following HTML command onto your Web page:

<A HREF=" extend(R) Thin Client Version
          10.1.1.exe">Click here to download the thin client</A>
<A HREF="myprog.atc">Click here to run the application</A>

where extend(R) Thin Client Version 10.1.1.exe is the name of the self-extracting archive for the thin client runtime, and myprog.atc is the name of the command line file that you created for your thin client application.

The HREF attribute is used within the starting anchor tag to specify the document to be linked (or retrieved). See any commercially available HTML text for more information on anchors and hypertext links.

Parent topic: Providing Thin Client Links on the Web


Security and the ACUCOBOL-GT Thin Client

Security is a key consideration as you set up your thin client environment. By its very nature, in a thin client environment traffic is flowing into and out of your network.

You should consider setting up a firewall to limit access to your data and enforce your organization's access control policy. When you set up a firewall, you'll need to indicate the port number through which the thin client, AcuConnect, and the ACUCOBOL-GT runtime can communicate. The default port number for both the thin client and AcuConnect is 5632.

You can indicate an alternate port number for AcuConnect using the configuration variable, ACURCL_PORT. To indicate a port number for the thin client, set ATC_PORT in the thin client command line file.

If you want to encrypt data before transmitting it across the network, you can use the AGS_SOCKET_ENCRYPT runtime configuration variable on the server. You can also use the ENCRYPTION_SEED variable to initialize an industry-standard 128-bit AES encryption algorithm.

Parent topic: Providing Thin Client Links on the Web


Using the ACUCOBOL-GT Web Thin Client

The ACUCOBOL-GT Web Thin Client is a special 32-bit version of the thin client that is based on Microsoft's ActiveX technology. It is itself an ActiveX control that you can embed on your Web page. It makes your existing thin client applications accessible through browsers that support ActiveX, particularly Microsoft Internet Explorer. While the Web thin client runs only on Windows machines, it can access files or run programs on UNIX and other platforms using AcuConnect.

With the Web thin client, users who visit your site are automatically provided the software they need to run your application on the remote host, providing that they grant permission first. Software installation and program invocation are transparent.

Here is the general process:

  1. The end user visits a page on your Web site.
  2. The Web browser software looks for the Web thin client on the user's machine. If it locates the Web thin client, it runs it, and the Web thin client launches the program on the server.
    If the Web browser cannot find the Web thin client locally, it downloads the file from the specified location and asks the user
    Do you want to install and run ACUCOBOL-GT Web Thin Client?
    This message may appear in a dialog box, or in newer versions of Windows (such as Windows XP, SP2), it may appear in an Information Bar at the top of the browser window. To assure the user that the installation is safe, the Web thin client is supplied as a cabinet (CAB) file with a digital signature from Acucorp.

    If the user grants permission, the Web thin client is sent to the client machine, where it automatically installs itself and launches your program on the server. The server then projects the user interface back onto the client.

Note: For automatic installation to be performed, you program your Web page with the CODEBASE attribute of the OBJECT tag as instructed in Using the OBJECT Tag.
  • Windowing Options
  • How Your Program Executes
  • Browser Versions Supported by the Web Thin Client
  • Deploying Applications via the Web Thin Client
  • Setting Up a Web Site
  • Coding Considerations
  • Updating Your Web Page to Invoke Your COBOL Application
  • Using the <OBJECT> Tag
  • Licensing Considerations
  • The User's Job
  • Troubleshooting
  • Security and the Web Thin Client
Parent topic: Using the Thin Client to Launch Web Applications


Windowing Options

With the thin client, even though your program executes on the server, the user interface is projected onto the client. You can choose whether the UI displays inside the user's browser window or in a separate application window. How and where your program starts depends on the HTML commands that you use to include it on your Web site. See Updating Your Web Page to Invoke Your COBOL Application for details. Listed below are some things to consider when choosing a windowing method.

Inside the User's Web Browser

In this case, your COBOL program starts inside the user's browser window. Nearly all of the ordinary functions of your COBOL program are available to your user and your program has access to library routines that can be used to communicate with the browser.

In this mode, users also have access to browser functions like Forward, Back, and Search, but when they use these functions, the COBOL program terminates. To avoid losing data, the COBOL program should be designed to handle the closing action gracefully within ten seconds. If users return to the page from which they launched the ACUCOBOL-GT application, it reloads like any Web page.

Note that because of a Microsoft child window restriction, applications running inside a browser window cannot display a main window menu bar as you or your users might expect. To work around this restriction, you can program your application's menu functions to be accessed from a toolbar or a pop-up menu that is activated with the right mouse button.

In a Separate Application Window

In this mode, your COBOL program starts in a window separate from the browser, making it look the same as it would if it were launched locally. All the functions of your original program are available to users, including a main window menu bar.

Although your program cannot access the library routines used to communicate with the browser in this mode, users can still access functions like Forward, Back, and Search simply by activating the browser window. However, when the user selects a browser function, the runtime object terminates. This is because the runtime object executes as an object related to the HTML page, even when running in a separate window.

Parent topic: Using the ACUCOBOL-GT Web Thin Client


How Your Program Executes

With the Web thin client, your program executes on the server, and only the user interface displays on the client.

Note: The Web thin client only supports a single instance.

The recommended method of executing the ACUCOBOL-GT Web Thin Client is with the <OBJECT> tag. See Using the OBJECT Tag.

The browser loads the Web thin client (which you recall is an ActiveX control) and feeds it the data coming from the Web server. In this context there is no concept of a command line.

To pass "command line" style parameters to the ACUCOBOL-GT Web Thin Client, you use the AcuCommandLine property of the <OBJECT> tag when you invoke the application in your Web page.

The Web think client only supports a single instance. Internet Explorer 6 introduced tabs that allow more than on web page to e displayed in a single browser. IE 6 and 7 load all tabs into the same process. IE 8 loads the first couple of tabs in separate processes but eventually (depending on the client computer's resources) will start loading subsequent tabs in a previous tab's process. So it may be possible to run more than one Think Client application in a single Internet Explorer window using version 8.

Whenever a user attempts to run a second instance of the Web Thin Client in a process, the second instance of the control will detect this condition and enter a blocked state. This means the acuthin DLLs haven't been loaded and the Think Client application is not executing on this page/tab. The Web Thin Client control has properties to detect this state and give the developer choices in how to handle it. See Object interface for the Web thin client.

Parent topic: Using the ACUCOBOL-GT Web Thin Client


Browser Versions Supported by the Web Thin Client

The Web thin client is designed for browsers that support ActiveX controls. We have confirmed that the Web thin client runs on Internet Explorer Versions 5.5 Service Pack 2 and later. Browsers that do not support ActiveX controls cannot use the Web thin client. Currently, this includes Netscape browsers, and some earlier versions of Internet Explorer.

Parent topic: Using the ACUCOBOL-GT Web Thin Client


Deploying Applications via the Web Thin Client

To deploy your application on the Web via the Web thin client, the developer has three tasks:

  1. Set up a Web site. See Setting Up a Web Site for details.
  2. Consider whether you need to make any coding adjustments to your program. See Coding Considerations for coding considerations.
  3. Update your Web page to invoke your thin client application. To do this, you typically embed the URL of the Web thin client along with the URL of your application on your Web page using an <OBJECT> element and the CODEBASE attribute. See Updating Your Web Page to Invoke Your COBOL Application.

After your work is done, the user has only one task:

  1. Visit your Web site. The Web thin client will install itself and launch your program automatically.

    Note that two dialog boxes may be displayed in the process: one containing a security message if required by the security setting of the user's browser, and the other containing a click-wrap license agreement from Micro Focus. See Security and the Web Thin Client for more information.

Parent topic: Using the ACUCOBOL-GT Web Thin Client


Setting Up a Web Site

Setting up a Web site is probably the most time-intensive portion of this method, but it is not very difficult to do. Adding Internet Features to Your Program gives general information about setting up a Web site, including information on Web servers, posting a site, and promoting a site. Many different tools are available to help you create a Web page quickly and easily.

Parent topic: Using the ACUCOBOL-GT Web Thin Client


Coding Considerations

If you plan to have your application run inside the user's browser window, it cannot display the main window menu bar to which you may be accustomed. This is a Microsoft child window restriction. In this case, you will need to program your application's menu functions to be accessed from a toolbar or a pop-up menu that is activated with the right mouse button. You can avoid this restriction by having your application run in its own separate window. You can specify this as a parameter of the <OBJECT> tag or by setting the AcuEmbedded property supplied with the object interface. See Using the OBJECT Tag for more information.

Parent topic: Using the ACUCOBOL-GT Web Thin Client


Updating Your Web Page to Invoke Your COBOL Application

To invoke your COBOL application and the Web thin client from your Web page, you use the HTML <OBJECT> tag. The <OBJECT> tag allows you to invoke both of these items with a single HTML element. If you add the CODEBASE attribute, users can automatically download the control the first time they access the application, and they can get updates automatically. The browser checks the CLASSID property and downloads a new version of the control, if one is available.

In addition, we have developed an object interface containing several properties and methods for communicating with browsers. If desired, you can implement all of the properties in the object interface as attributes of the <OBJECT> tag.

Advanced users may choose to instantiate their application with the <OBJECT> tag, and then write scripts with the object interface to invoke the application. Please note that scripting the Web thin client may require changes to your end users' security settings. See How Internet Explorer security affects the Web thin client for more information.

Parent topic: Using the ACUCOBOL-GT Web Thin Client


Using the <OBJECT> Tag

When authoring Web pages to launch your application, you can use the <OBJECT> tag to invoke the Web thin client and start your program at the same time. For example, you could include the following in your HTML code:

<OBJECT ID="AcuThinAX" WIDTH=512 HEIGHT=384
   CLASSID="CLSID:087C768D-64C1-4AC1-845D-4589B4B2C24E"
   CODEBASE="http://www.acucorp.com/support/downloads/acuthinax/
   acuthinax800.cab#version=8,0,0,900">
   <PARAM NAME="SRC" VALUE="http://yourserver/yourdirectory/
   yourcommandlinefile.acutc">
</OBJECT>

where the following values are described as:

ID | Optional. The name of the instance of the object. This name is only used for scripting the object interface. It is a user-defined value to which you refer in your script.
CLASSID The GUID (globally unique identifier) assigned to the ACUCOBOL-GT Web Thin Client control, specifically this value:
CLSID:087C768D-64C1-4AC1-845D-4589B4B2C24E
CODEBASE  The CODEBASE URL, from which the Web thin client can be downloaded and installed automatically by end users, specifically:
http://www.acucorp.com/support/downloads/acuthinax/acuthinax###.cab

where ### is a 3-digit segment that identifies the cab file version. You can also append the version information that applies to the control, including a build number, by adding it as described in subsequent sections.

Although the CODEBASE attribute is optional, using it is now a common practice among software vendors to provide access to controls in this way. This allows you to distribute the control easily.

If you do not use the CODEBASE attribute, you must direct users to the download page on the Micro Focus Web site. Or, with a proper written license agreement, you may provide the control on your own distribution media or Intranet site.

HEIGHT | Optional. The height (in pixels) of the object's window. Use to define the area within the browser window that the application object will occupy.
WIDTH | Optional. The width (in pixels) of the object's window. Use to define the area within the browser window that the application object will occupy.

By default, the application appears in the browser window, using the HEIGHT and WIDTH attributes, if provided, to define the area that the application occupies.

If desired, you can add any of the properties and methods of the Web thin client object interface as parameters of the <OBJECT> tag. To do so, add PARAM NAME= followed by the property name from the object interface enclosed in quotes. You then supply the VALUE attribute.

For example, if you want to have your application appear in its own window rather than in the browser window, set the AcuEmbedded property of the object interface to FALSE as follows:

 <PARAM NAME="AcuEmbedded" VALUE="FALSE">

The following example illustrates how you might display your application in a separate window.

<OBJECT ID="AcuThinAX" WIDTH="512" HEIGHT="384"
CLASSID="clsid:087C768D-64C1-4AC1-845D-4589B4B2C24E"
<OBJECT ID="AcuThinAX" WIDTH="512" HEIGHT="384"
   CLASSID="clsid:087C768D-64C1-4AC1-845D-4589B4B2C24E"
   CODEBASE="http://www.acucorp.com/support/downloads/acuthinax/acuthinax800.cab#version=8,0,0,900">
   <PARAM NAME="AcuEmbedded" VALUE="FALSE">
   <PARAM NAME="SRC" VALUE="http://yourserver/yourdirectory/yourcommandlinefile.acutc">
</OBJECT>

Note that there are two ways to specify command-line parameters for your program: you can use the SRC property or the AcuCommandLine property of the object interface, but you never use both at the same time. The original example in this section showed the SRC form:

<PARAM NAME="SRC" VALUE="http://yourserver/yourdirectory/yourcommandlinefile.acutc">

This points to a separate file containing the command-line parameters that you wish to invoke on start-up. See Thin Client Command-Line Files for more details on creating command line files. If you already have such a file that you're using for the thin client, then this will likely be your preferred method.

Alternatively, you can use the AcuCommandLine form:

<PARAM NAME="AcuCommandLine" VALUE="myserver.mysite.com:5632 myalias">

The advantage of the AcuCommand Line property is that you can specify the command line directly in the <OBJECT> tag without maintaining a separate file.

For more information on the object interface and its properties, including SRC and AcuCommandLine, refer to the subsequent sections.

  • How the <OBJECT> tag works
  • Version number of Web thin client
  • Object interface for the Web thin client
  • AcuIsActive
  • AcuExecute
  • AcuShutdownAx
  • AcuGetLastError
  • AboutBox
  • AcuEmbedded
  • AcuShowLogo
  • AcuCommandLine
  • SRC
  • IsBlockedInstance
  • BlockedInstanceAction
  • BlockedInstanceMsgText
  • Scripting with the object interface
Parent topic: Using the ACUCOBOL-GT Web Thin Client


How the <OBJECT> tag works

The CODEBASE parameter indicates to the browser where to look for the Web thin client if it is not installed on the target system. Internet Explorer automatically offers to download and install the Web thin client, prompting most users to accept the digital signature provided by Micro Focus.

Note: If the user's security settings are high or customized to prohibit ActiveX controls, the user cannot install the Web thin client. If the user's security settings are low, the control installs without confirmation from the user.

In the HTML document, you can introduce the Web thin client with the <OBJECT> tag and then supply a script to invoke the object through either a window event or a push-button event. For information on using the object interface, see the next section. However, you need not use scripting in order to invoke the control with the <OBJECT> tag.

Parent topic: Using the <OBJECT> Tag


Version number of Web thin client

The name of the CAB file identified in the CODEBASE URL is version-specific. Therefore, acuthinax800.cab always contains the Version 8.0.0 Web thin client. However, you can implement your CODEBASE URL with a version string that refers to the version number as well as the build number.

If, for example, you deploy your Web site with the following CODEBASE value:

http://www.acucorp.com/support/downloads/acuthinax/acuthinax800.cab

a control associated with the specified CLASSID will be used (if found), regardless of version. If no associated control is available on the client machine, the CAB file will be downloaded, installed, and executed.

On the other hand, if your Web site contains the following value:

http://www.microfocus.com/support/downloads/acuthinax/acuthinax800.cab#version=8,0,0,900

Users with an earlier version of the control will automatically be prompted to download the new version the next time they visit your Web site. The convention for the Web thin client control is therefore:

acuthinaxMmr.cab#version=M,m,r,b

where M,m,r,b represent the Major, minor, release, and build numbers of the particular version of the control. This allows you to determine which version of the control is available to your end users.

To determine the version and build number of a Web thin client control, you can use the AboutBox method available in the object interface. See the next section for more information. You can also obtain the version number by following these steps:

  1. Locate the file, acuthinax.ocx, for the version you want to deploy.
  2. In Windows Explorer, right-click on the control and select Properties.
  3. Select the Version tab and view the value in the File Version field.
Parent topic: Using the <OBJECT> Tag


Object interface for the Web thin client

The Web thin client's object interface consists of the following methods and properties. Some are bi-directional (B) and others are read only ®). The component also has a default property (D).

Note: Using the object interface is optional. The <OBJECT> tag exposes the same properties (but not methods). The object interface is available for the advanced user who prefers scripting and wishes to use the available methods. However, please be aware that support for specific scripting languages and their implementations should be obtained from the appropriate vendor.
Parent topic: Using the <OBJECT> Tag


AcuIsActive

Returns the status of the Web thin client. AcuIsActive takes no input parameters.

Parameter Type | Input | Output
( ) | [ ] | [TRUE, FALSE]

The return value is of the data type BOOL:

  • TRUE = the thin client is executing
  • FALSE = the thin client is not executing

For example:

If AcuThinAX.AcuIsActive() = TRUE

AcuIsActive may be executed any time after the Web thin client (in this example, AcuThinAX) has been invoked.

Parent topic: Using the <OBJECT> Tag


AcuExecute

Starts the Web thin client and returns the result of the action.

If you invoke your application directly by specifying the SRC or AcuCommandLine property in the <OBJECT> tag, you do not need to call AcuExecute. Your application will start automatically.

The AcuExecute method takes no parameters.

Parameter Type | Input | Output
() | [ ] | [0, -4, -5, >0]

The return value is of data type LONG.

Value | Explanation
0 | Success, Web thin client started.
-4 | The Web thin client is already running.
-5 | The acuthin DLL could not be found, or the acuthin DLL is the wrong version.
>0 | Unexpected error.

For example:

Return_value = AcuThinAX.AcuExecute()

Do not invoke this method until you have set either the SRC or AcuCommandLine property to specify the command line file to use; otherwise, AcuExecute will not have the information necessary to start your application.

Parent topic: Using the <OBJECT> Tag


AcuShutdownAx

This is an optional method that forces a shutdown of a specific Web thin client instance. For example:

AcuThinAX.AcuShutdownAx()

shuts down the thin client instance known as AcuThinAX, if it is running.

AcuShutdownAx terminates the COBOL application invoked by the Web thin client. In general, you need not use it because the Web thin client either terminates as a result of the COBOL program execution, or because the browser either displays another URL or closes. If, for some reason, you want to force shutdown of the Web thin client instance, this method is available.

Parameter Type | Input | Output
() | [ ] | [ ]

The shutdown action assumes that the COBOL application is currently in idle mode. If the Web thin client is not idle, the browser hangs, waiting for the application to idle. This method takes no parameters, and there is no return value for this function.

AcuShutdownAx implicitly terminates the Web thin client when you terminate the COBOL application you are running. So, when you execute this method, the Web thin client is terminated, closing files properly, even though data that was not stored permanently is lost.

Parent topic: Using the <OBJECT> Tag


AcuGetLastError

Returns the last known error code.

Parameter Type | Input | Output
() | [ ] | [ ]

This method takes no parameters, and the return value, which is the error code, is of data type LONG. See AcuExecute for more information.

For example:

AcuThinAX.AcuGetLastError()

AcuGetLastError may be executed any time after the Web thin client has been invoked.

Parent topic: Using the <OBJECT> Tag


AboutBox

Displays a dialog box that presents version information about the Web thin client.

Parameter Type | Input | Output
() | [ ] | [ ]

There is no return value.

For example:

AcuThinAX.AboutBox()

AboutBox may be executed any time after the Web thin client (AcuThinAX in this example) has been invoked.

Parent topic: Using the <OBJECT> Tag


AcuEmbedded

Determines whether the Web thin client should run in an independent window or as a frame within the document.

Parameter Type | Input | Output
(BOOL) | [TRUE, FALSE ] | [TRUE, FALSE]

The AcuEmbedded property accepts a BOOL as a value. When this property is set to TRUE, the default, the window appears embedded in the browser document. Set it to FALSE when you want the window to appear independently, outside the browser.

For example:

AcuThinAX.AcuEmbedded = TRUE
if AcuThinAX.AcuEmbedded

The AcuEmbedded property is available any time after the Web thin client has been invoked. Its contents are read and applied to the Web thin client when AcuExecute is invoked.

Note that if you use the HEIGHT and WIDTH attributes of the <OBJECT> tag and you set AcuEmbedded to FALSE, the Web thin client's logo screen will occupy that area on the HTML page while the application runs in its own window.

Parent topic: Using the <OBJECT> Tag


AcuShowLogo

Determines whether to display the ACUCOBOL-GT Web Thin Client logo when you invoke your application.

Parameter Type | Input | Output
(BOOL) | [TRUE, FALSE ] | [TRUE, FALSE]

For example:

AcuThinAX.AcuShowLogo = TRUE
if AcuThinAX.AcuShowLogo

To use this property, specify it as part of the <OBJECT> element where you invoke the application. The default is TRUE.

Parent topic: Using the <OBJECT> Tag


AcuCommandLine

The command line that you would normally specify for the acuthin executable. See the AcuConnect User's Guide for a list of valid acuthin command-line options. The minimum value is a server name and alias name. For example:

myserver.mysite.com:5632 myalias
Parameter Type | Input | Output
(BSTR) | [ ] | [ ]

Do not specify this property if you are using SRC.

Parent topic: Using the <OBJECT> Tag


SRC

Contains a URL (in HTTP notation) for the thin client command line file to load. See Thin Client Command-Line Files for a discussion of command line files and how to create them. SRC is the default property of the Web thin client ActiveX control. Do not specify this property if you are using AcuCommandLine.

Parameter Type | Input | Output
(BSTR) | [ ] | [ ]

The following example demonstrates using the <OBJECT> element to specify the program for execution:

<OBJECT
   CLASSID="CLSID:087C768D-64C1-4AC1-845D-4589B4B2C24E"
   ID="AcuThinAX" width="512" height="384">
   <PARAM NAME="AcuEmbedded" VALUE="TRUE">
   <PARAM NAME="SRC" VALUE="http://server.acucorp.com/location/commandlinefile.acutc">
</OBJECT>

The SRC property is intended for HTTP URLs only. However, you may also address local files if the path is prefixed with file:// rather than http://, as shown below. Note that this is also considered URL notation.

For example:

<OBJECT
   CLASSID="CLSID:087C768D-64C1-4AC1-845D-4589B4B2C24E"
   ID="AcuThinAX" WIDTH="512" HEIGHT="384">
   <PARAM NAME="AcuEmbedded" VALUE="TRUE">
   <PARAM NAME="SRC" VALUE="file://c:/webdemo/commandlinefile.acutc">
</OBJECT>

When you use the SRC property to call a file, the downloaded file is given a temporary name and is stored in the current master temporary directory for the user, as specified in Windows. Note that the Web thin client automatically captures the temporary name and uses it internally; however, the internal name is not exposed.

Parent topic: Using the <OBJECT> Tag


IsBlockedInstance

Indicates whether or not the Web thin client has detected that it is a second instance and is blocked.

IsBlockedInstance is Read Only.

Parameter Type | Input | Output
(BOOL ) | N/A | [TRUE, FALSE]

The property is of the data type BOOL.

TRUE = the Web Thin Client control is blocked and will not run the Thin Client application.

FALSE = the control is the first instance and will run the Thin Client application.

For example:

If AcuThinAX.IsBlockedInstance = TRUE

The IsBlockedInstance property may be checked any time after the Web thin client (in this example, AcuThinAX) has been invoked.

Parent topic: Using the <OBJECT> Tag


BlockedInstanceAction

Indicates whether or not the Web thin client has detected that it is a second instance and is blocked.

IsBlockedInstance is Read Only.

Parameter Type | Input | Output
SHORT | [0, 1, 2] | [0, 1, 2]

The property is of the data type SHORT

Value | Description
0 | Display nothing. For use in scripting.
1 | Display the default message, ACUCOBOL-GT WebThin Client may only be loaded once. in the upper left corner of the client area. This is the default setting.
2 | Display a custom message in the upper left corner of the client area.

For exampe:

AcuThinAX.BlockedInstanceAction = 1
Return_value = AcuThinAX.BlockedInstanceAction
Parent topic: Using the <OBJECT> Tag


BlockedInstanceMsgText

Contains the text that will display when the Web Thin Client is blocked due to being a second instance and the BlockedInstanceAction property is set to 2 (custom message).

Parameter Type | Input | Output
(BSTR) | [ ] | [ ]

For example:

The following example demonstrates using the <OBJECT> element to specify the custom message :

<OBJECT
  CLASSID="CLSID:087C768D-64C1-4AC1-845D-4589B4B2C24E"
  ID="AcuThinAX" width="512" height="384">
  <PARAM NAME="AcuEmbedded" VALUE="TRUE">
  <PARAM NAME="BlockedInstanceAction" VALUE="2">
  <PARAM NAME="BlockedInstanceMsgText" VALUE="The Web Thin
Client is already loaded.">
</OBJECT>
Parent topic: Using the <OBJECT> Tag


Scripting with the object interface

Scripting is an optional method for invoking the Web thin client. While it is possible to invoke the Web thin client without scripting, some users may want to take advantage of all the methods and properties in the object interface.

The following VB Script example illustrates how to invoke the Web thin client object by a push button event using a script:

<INPUT id=button1 name=button1 type=button value=Button>
<SCRIPT LANGUAGE="VBScript">
sub button1_onclick()
   call AcuThinAX.SRC("http://www/Acucorp.com/demo/demo.acutc")
   call AcuThinAX.AcuEmbedded(1)
   call AcuThinAX.AcuExecute()
end sub
</SCRIPT>
Note: Only one instance of the Web thin client is allowed. You cannot have multiple instances of the Web thin client in one browser instance.
Parent topic: Using the <OBJECT> Tag


Licensing Considerations

The ACUCOBOL-GT Web Thin Client is licensed with a runtime license on a server running AcuConnect, licensed for the number of concurrent users anticipated.

There is no licensing requirement on the end user client machine.

Parent topic: Using the ACUCOBOL-GT Web Thin Client


The User's Job

To use your application via our Web thin client, end users typically have just one task: they must visit your Web site. If the user's browser supports the Web thin client and you have implemented the CODEBASE in your HTML code, users install the Web thin client automatically the first time they visit your Web site, and the Web thin client automatically launches your application.

If your customers do not already have the ACUCOBOL-GT Web Thin Client installed on their machine when they try to launch your application, they are informed that a control for the file type was not found, and they are asked if they want to install and run your program. If they respond Yes, the Web thin client installs with no further user interaction and automatically launches your program.

Note: Users must configure the browser to enable ActiveX controls. To do this in Internet Explorer, they should check the appropriate box in the Security tab of the Internet Explorer Options dialog.

For most users installing the Web thin client, they will be prompted to accept the digital signature of the control. The system also displays the terms and conditions for using the ACUCOBOL-GT Web Thin Client. Users must agree to the terms of the agreement in order to use the Web thin client.

Parent topic: Using the ACUCOBOL-GT Web Thin Client


Troubleshooting

Users may encounter the following message when installing or using the Web thin client:

A plug-in for this file type was not found.

Users receive this message if they do not have the Web thin client installed on their machine when they try to launch your application and, for some reason, cannot install one automatically using the CODEBASE implementation. They should obtain a copy of the ACUCOBOL-GT Web Thin Client through another means (extend media or Web site, for example) and install it on their machine.

You can try reinstalling the control, running regsvr32 to register it, or accessing an HTML document where the CODEBASE attribute is correctly implemented.

Parent topic: Using the ACUCOBOL-GT Web Thin Client


Security and the Web Thin Client

Security for the Web thin client begins with the following provisions:

  • Warning messages appear the first time users launch the Web thin client.
  • We supply the Web thin client with a digital signature indicating that Micro Focus verifies the content. This enables users to run the control using a medium security setting on their Internet Explorer browser.

Since we distribute the Web thin client via the Internet, it is packaged as a signed Cabinet (CAB) file. This ensures your users that the code is safe. The CAB file contains a compressed version of the control, with information that tells Internet Explorer how to install it.

CAUTION:

Although we have built in a number of security features, the Web thin client allows COBOL programs to call library routines, DLLs, and ActiveX controls on target machines. Because we have no control over the programs that are executed by the Web thin client, we cannot fully guarantee that they are safe.

  • Digital signature of Web thin client
  • How Internet Explorer security affects the Web thin client
  • Security warning messages
Parent topic: Using the ACUCOBOL-GT Web Thin Client


Digital signature of Web thin client

A digital signature provides users with a way of identifying who published the software they are downloading from the Internet.

By distributing the Web thin client with a CAB file and digital signature, we ensure that most standard configurations of Microsoft Internet Explorer will accept the Web thin client application after the user responds yes to the Security Warning dialog when it is installed. Users who have set their browser security level to low will not see this dialog, since their browsers automatically accept digitally signed components.

Note: Users with security levels set to high cannot run any ActiveX-based controls, regardless of the digital signature.

Because the CAB installation does depend on some Microsoft files, it contains an embedded link to a file on the Micro Focus Web site to ensure that it can obtain the proper files. If these files are needed, users are prompted to install the Microsoft files; doing so may impact the download and installation time of the control, due to the file size of some of these required files.

Parent topic: Security and the Web Thin Client


How Internet Explorer security affects the Web thin client

Certain security settings of Internet Explorer can affect how it handles the Web thin client. The following table outlines the security settings that could have an effect on your end users, depending on their configuration of Internet Explorer.

Security Setting Option | Low | Medium Low | Medium | High
Download signed ActiveX controls | Enable | Prompt | Prompt | Disable *
Download unsigned ActiveX controls | Prompt | Disable | Disable | Disable
Initialize and script ActiveX controls not marked as safe | Prompt | Disable | Disable | Disable
Run ActiveX controls and plug-ins | Enable | Enable | Enable | Disable*
Script ActiveX controls marked safe for scripting | Enable | Enable | Enable | Disable**
Don't prompt for client certificate | Enable | Enable | Disable | Disable
Active Scripting | Enable | Enable | Enable | Disable**

* If your users have selected Disable for either of these settings–either via the default High security setting or a custom setting–they cannot run the Web thin client.

**If your users have selected Disable for either of these settings, and they are using the scripting facilities, they cannot run the Web thin client.

Parent topic: Security and the Web Thin Client


Security warning messages

In general, programs run with Web controls can potentially damage an end user's computer system or corrupt memory. Therefore, to help reduce the chances of this happening, the Web thin client displays warnings to end users, asking them to accept responsibility. Based on your end users' expectations, you may need to provide instructions for handling these messages.

Parent topic: Security and the Web Thin Client


Launching Web Applications Through CGI

  • What Is CGI?
  • How CGI Works
  • Deploying Your Applications on the Web Using CGI
  • Creating a Web Interface
  • Writing a CGI Program
  • Creating a Runtime Configuration File for Your CGI Program
  • Configuring the Web Server
Parent topic: A Programmer’s Guide to the Internet Version 10.2.0


What Is CGI?

If you want to deploy your COBOL applications on the Web without any configuring of the user machine, you can develop a Web interface to your application and write a CGI program on the server. CGI stands for Common Gateway Interface. It is an Internet standard that defines how a Web server communicates with an external program.

Using CGI, your application becomes immediately available to any user with a Web browser or mobile device. The end user does not require any special runtime or plug-in to interface with your application, because the CGI script handles the communication for them.

The CGI program (also known as the CGI script) can be written in any language, including COBOL. By writing it in the ACUCOBOL-GT® Development System, you can take advantage of your COBOL programming experience, as well as many other benefits.

This option gives the most flexibility and platform independence, but it requires the development of a new user interface and a modest amount of COBOL programming.

Why Write CGI Programs in ACUCOBOL-GT?

ACUCOBOL-GT has features designed to simplify CGI programming. For instance, using familiar ACCEPT and DISPLAY syntax, you can accept CGI input data and write HTML, WML, or XML output forms. It also has configuration variables that address special formatting and storage issues in this environment.

By writing CGI programs in a language you already know, you have to learn only what the Web server expects, and how it formats messages that it passes back and forth across the network.

Another advantage is that your CGI program is compiled when it is written in ACUCOBOL-GT. This not only speeds up processing, but it reduces the size of the finished product, and secures your program from anyone who might try to acquire and modify it. Your CGI program is not sent across the Internet, only the data (if any) and response (if any). Users won't know if your CGI program is written in COBOL or another language. They see only the results.

Sample Scenario

Your inventory program allows customers to place orders online. They fill out an HTML form on your Web site, which provides input to a CGI program (written in COBOL). The CGI program updates inventory information in your database to reflect the customer order, and then returns a confirmation notice in HTML format to the customer's browser. Alternatively, the notice may be sent in WML format to the customer's mobile phone or other wireless device.

Parent topic: Launching Web Applications Through CGI


How CGI Works

The flow of typical CGI implementation is as follows:

  1. From a client machine–which could be anything from a Web browser to a mobile phone–a form or query is sent to the Web server. The user might launch a request by pressing a button or clicking a link.
  2. The Web server forwards the request to the CGI program, in this case, written in ACUCOBOL-GT. This program ACCEPTs the CGI data sent by the client into an external form which you define in working storage.
  3. The request is either processed by the CGI program itself, or passed to another ACUCOBOL-GT program for execution.
  4. The CGI program uses the DISPLAY verb to merge processing results with an HTML, XML, or WML template, and sends the result to the Web server in the standard output stream. The ACUCOBOL-GT runtime creates and outputs the appropriate content response headers automatically.
  5. The Web server sends the content response header followed by the appropriate content message to the user's machine or mobile device where it is displayed.

Note that this diagram shows the CGI program and ACUCOBOL-GT application as separate components. In many instances, you may choose to add CGI functions directly to your COBOL application, making them one in the same thing.

In addition, any and all connectivity options available to extend customers can be applied in the third step if desired. For instance, the CGI program can CALL a remote program using the AcuConnect® application server for connectivity. Likewise, the CGI program or CALLed program can access any file system or database that we support to perform a lookup. If the file system resides on another machine, the program can use the AcuServer® remote file server to achieve access. If a relational database access is desired, the Acu4GL® interface or AcuSQL® precompiler can be used to translate the request into SQL.

The CGI method is best suited for programs that do not use a user interface (UI) based on COBOL DISPLAY/ACCEPT statements–for instance, programs with a Web interface, batch processes, processes that use socket routines to communicate with an external UI, component adapter technology processes, and BEA Tuxedo processes.

Parent topic: Launching Web Applications Through CGI


Deploying Your Applications on the Web Using CGI

To deploy your applications on the Web using CGI, you perform the following steps:

  1. Create a Web interface to your application, targeted for your intended environment. Include pointers to the CGI program that you will develop. See Creating a Web Interface.
  2. Write a CGI program in COBOL that will read CGI variables, perform the processing task or launch a separate program to do so, and generate output from the results. Note that ACUCOBOL-GT has been designed to make CGI programming easy. See Writing a CGI Program.
  3. Create a runtime configuration file for your CGI program. In it, define input and output requirements, such as output content type, headers, caching, and stripping carriage returns. See Creating a Runtime Configuration File for Your CGI Program.
  4. Place your CGI program and ACUCOBOL-GT application on the Web server, along with the necessary configuration, license, and data files.
  5. Configure your Web server software. Have it run the program with the f runtime option or set the A_CGI environment variable to 1. This tells the runtime to run in CGI mode and not perform user interface functions. If your program will be running on UNIX, also specify the -b option. See Configuring the Web Server.
  6. Follow normal procedures for creating the license files for Windows and UNIX environments. If you ordered a CGI license file, see Running Your Programs.
Parent topic: Launching Web Applications Through CGI


Creating a Web Interface

To make your COBOL program directly accessible to Web browsers–whether on computers, personal digital assistants (PDAs), or mobile phones–you should develop a Web interface to replace your application's current graphical or character-based front end.

For HTTP browsers like Internet Explorer and Netscape, you typically develop an interface in hypertext markup language (HTML) or extensible markup language (XML). HTML is the most common language for Web pages viewed with HTTP browsers, although XML is rapidly gaining ground for display dynamic content on the Web.

For mobile device browsers based on Wireless Application Protocol (WAP), you typically develop an interface in Wireless Markup Language (WML), but you can also develop an XML interface if desired.

XML documents are typically transformed to the output format of their targeted environment through the use of style sheets and a style sheet transformation language (XSLT). For instance, if a Web browser client makes a request, XML documents are typically transformed to HTML or PDF format for output. If a WAP device issues the request, they are typically transformed to WML. It is a published form of the document that is returned to the client, not the XML document itself. XML Web publishing vendors can provide more information on this subject, as well as the tools to develop such a solution.

HTML, XML, and WML are all markup languages that tell devices how to present information. All three of these languages use headers and tags to pass structure, formatting, hyperlink, and form description information to the receiving device. If you choose to, you can use other languages like VB script or Java script to develop your user interface. The only restriction is that the targeted browser or WAP device must be able to support the version of the language that you use.

To develop a markup language interface to your COBOL program, you can use any of several authoring tools. Many are available over the Internet free of charge. For instance, Cocoon Project is an open-source XML Web publishing framework from Apache. A search on HTML authoring tools turns up literally thousands of suggestions.

Whichever language you choose, you typically create fill-out forms to collect information from the user and send it to your CGI program for processing. The form must include information about how and where to send the information so that it can be processed. In HTML, this is accomplished with the METHOD and ACTION attributes of the <FORM> tag.

The Creating HTML Forms topic describes how to construct a form in HTML. For information on constructing XML and WML forms, refer to XML and WML reference books.

Note: If desired, you can display an HTML interface using the WEB-BROWSER control described in Use the Runtime as a Helper Application or Viewer. Then the HTML interface can interact with CGI programs on the Web server.
  • Creating HTML Forms
  • FORM Components
Parent topic: Launching Web Applications Through CGI


Creating HTML Forms

To create a form in HTML, you use the <FORM> tag. As with many HTML tags, you need to place a beginning tag at the start of the form and a closing tag at the end of the form, in this case <FORM> and </FORM> respectively. More than one form can be in a single document, but forms cannot be nested.

Forms can contain single- and multiple-line entry fields, check boxes, radio buttons, list boxes, push buttons, and hidden data. Every form has a Submit button that users can press to have their data sent to the Web server for processing. This data is a list of NAME/VALUE pairs, one for each component of the form. The NAME and, optionally, the initial VALUE of each form component is specified in the HTML code. Then the user can fill out the form and modify the VALUEs.

Here is an example of an HTML form:

<FORM METHOD="POST" ACTION="/cgi-bin/name.acu">
Please enter your name or leave the entry field
blank for "anonymous":
  <INPUT TYPE="text" NAME="username" SIZE=60>
  <INPUT TYPE="submit" VALUE="Submit">
</FORM>

The FORM tag has two attributes that must be defined:

  • The METHOD attribute tells the browser how to send the information gathered in the form to the Web server.
  • The ACTION attribute tells the browser where to send the encoded form information, typically the URL (uniform resource locator) of the CGI program that will process the form.
  • METHOD attribute
  • ACTION attribute
Parent topic: Creating a Web Interface


METHOD attribute

The METHOD part of the <FORM> tag tells the browser how to send the information gathered in the form to the Web server. METHOD has only two possible values: GET and POST. The difference between these two methods is how the browser encodes the data to be sent to the server.

The GET method encodes the NAME/VALUE pairs into the URL itself. Then the Web server moves the NAME/VALUE list into an environment variable, QUERY_STRING, before calling the CGI program.

The drawback of GET is that the NAME/VALUE list is limited to 255 characters including the special URL encoding symbols. The advantage is that all of the input data is visible in the URL (although this could be considered a disadvantage as well). After submitting the form, the user can bookmark the URL or save a copy of the URL text for future quick access to the results of the submittal.

On the other hand, the POST method sends the data to the Web server as a data stream. Using this method, the NAME/VALUE list is limited to 2,147,483,647 characters. With the POST method, the browser does not modify the URL. Instead, it connects to the Web server and sends the NAME/VALUE list as a stream of data. The Web server pipes this data stream through the standard input stream (STDIN) of the CGI program.

All Web servers support the GET method, and most modern Web servers support the POST method. ACUCOBOL-GT supports both methods. This means that when you write your CGI program using the ACUCOBOL-GT CGI enhancements, the method you choose makes absolutely no difference in the way you code your CGI program. You may change the method in the HTML FORM tag without recoding or even recompiling your CGI program.

Parent topic: Creating HTML Forms


ACTION attribute

ACTION tells the browser where to send the encoded form information. This is the URL of the CGI program that will process the form. In the example above, the browser is going to send the form information to a COBOL program called name.acu on the same server as the HTML document. The program name.acu is located in a directory called /cgi-bin/. Note that /cgi-bin/ is not necessarily the name of an actual file system directory on the Web server. The Web server is configured to map URL paths to disk directories. You must examine your Web server settings to determine the actual disk directory represented by a URL path.

You can also include the complete URL within the ACTION attribute as follows:

<FORM METHOD="POST" ACTION="http://www.mycompany.com/cgi-bin/name.acu">
Parent topic: Creating HTML Forms


FORM Components

In the following syntax diagrams, square brackets, [ ], are used to indicate optional attributes, and curly braces, { }, to enclose a set of choices.

  • INPUT Tag
  • TYPE Attribute
  • Single-line Entry Fields
  • Multiple-line Entry Fields
  • Check Boxes and Radio Buttons
  • List Boxes
  • Submit and Reset Buttons
  • Hidden Fields
Parent topic: Creating a Web Interface


INPUT Tag

Use the INPUT tag to specify how you want users to enter data into the form. It tells the browser to get ready for some sort of data input.

Parent topic: FORM Components


TYPE Attribute

Use the TYPE attribute to tell the browser what kind of data will be entered and how it should look on the form. The default value for TYPE is "TEXT" (i.e. TYPE="TEXT").

Parent topic: FORM Components


Single-line Entry Fields

To create a single-line entry field, use the following syntax:

<INPUT TYPE="{TEXT|PASSWORD}" NAME="name"
  [VALUE="default_text"][SIZE="width,height"]
  [MAXLENGTH="width"]>

where:

  • TYPE selects the type of input field (text box or password box).
  • NAME assigns a name to the field.
  • VALUE assigns default text that will be entered in the box when the form is displayed.
  • SIZE specifies a width and height (in characters) for the box (default is width 20 and height 1).
  • MAXLENGTH specifies the maximum number of characters that may be entered.

The main difference between the TEXT and PASSWORD types is that when you use PASSWORD, anything the user types into the field is displayed as asterisks.

Parent topic: FORM Components


Multiple-line Entry Fields

To create a multiple-line entry field, use the following syntax:

<TEXTAREA NAME="name" [ROWS=rows] [COLS=columns]>
[Default_text]
</TEXTAREA>

where:

  • NAME assigns a name to the field.
  • ROWS specifies the number of rows in the field.
  • COLS specifies the number of columns in the field.
Parent topic: FORM Components


Check Boxes and Radio Buttons

Check boxes allow the user to select one or more options. Each check box must have a unique name. Radio buttons allow only one choice within a group of buttons. Each radio button within a group should have the same name. You can create more than one group of radio buttons by using different names.

<INPUT TYPE="{CHECKBOX|RADIO}" NAME="name" VALUE="value" [CHECKED]>

where:

  • TYPE selects the type of field (checkbox or radio button).
  • NAME assigns a name to the field.
  • VALUE assigns the value that will be sent to the CGI program if the user selects this field.
  • CHECKED specifies that this field should be selected by default when the form is displayed.
Parent topic: FORM Components


List Boxes

List boxes allow the user to select from a number of options, using either a pull-down menu or a scrolling list box. They are similar to groups of radio buttons or check boxes, but they take up less space for long lists of items.

<SELECT NAME="name" [SIZE="size"] [MULTIPLE]>
<OPTION [SELECTED]>Option 1
<OPTION [SELECTED]>Option 2
...
</SELECT>

where:

  • NAME assigns a name to the field.
  • SIZE specifies how many lines should be visible at once (default is 1).
  • MULTIPLE allows the user to select more than one option (i.e. check box behavior).
  • OPTION designates a list item; the text beside the tag will be the value sent to the CGI program.
  • SELECTED specifies that this list item should be selected by default when the form is displayed.
Parent topic: FORM Components


Submit and Reset Buttons

When users finish filling out the form, the submit button allows them to send the contents of the form to your CGI program. The reset button allows them to clear the form, resetting the fields to their default values.

<INPUT TYPE="{SUBMIT|RESET}" [VALUE="value"]>

where:

  • TYPE specifies the type of button (submit or reset).
  • VALUE assigns text that will be displayed in the button (default text is "Submit" or "Reset").

If you want to enable the <Enter> key so that users can press <Enter> to submit a completed form, add the USE-RETURN style to the WEB-BROWSER control. See Use the Runtime as a Helper Application or Viewer for more information on the WEB-BROWSER control.

Parent topic: FORM Components


Hidden Fields

Hidden fields allow you to send data to the CGI program without showing that data to the user.

<INPUT TYPE="HIDDEN" NAME="name" VALUE="value">

where:

  • TYPE specifies that this should be a hidden field.
  • NAME assigns a name to the field.
  • VALUE assigns the value that will be sent to the CGI program.

Note that "Hidden" fields are not completely hidden from users, because any user can select the "View Source" option in their browser to see the value of these fields.

Parent topic: FORM Components


Writing a CGI Program

Each element of your HTML, XML, or WML interface has a corresponding CGI variable. Your application must be able to interpret the CGI input data and return an appropriate response to the user. This is where your CGI program comes in.

Your CGI program must perform three basic functions:

Function | Description
Read CGI input data from the client | When a user enters information onto the form, that information is sent to the CGI program in the form of CGI data. Your program must be able to read CGI input data. In ACUCOBOL-GT, this is accomplished with the ACCEPT verb.
Process the input data and arrive at results | Typically, this involves either a calculation, database lookup, or file read, but it could involve a CALL to an existing COBOL program on a local or remote machine.
Generate output that can be read by the client browser | Minimally, this includes an HTTP response header with a URL pointer to the response data. Otherwise, the header may be followed by response data formatted in HTML, WML, or XML. In ACUCOBOL-GT, HTTP output is accomplished using the DISPLAY verb.

In the simplest case, your ACUCOBOL-GT CGI program can contain one ACCEPT statement and one DISPLAY statement. Even if your program is more complicated, it will always start with an ACCEPT and end with a DISPLAY. Few languages make CGI programming so simple.

When writing your CGI program, consider the following:

  • CGI programs must be written to be non-interactive. They take a set of input data, process it, and produce output.
  • While the CGI program is running, the user is waiting for a response in the Web browser. CGI programs should be kept small and do their job quickly to reduce the user wait time.
  • If users get tired of waiting and press the Stop button on their browsers, the Web server generally kills the CGI program. The output from the CGI program is discarded.
  • One of the limitations of CGI is that it does not automatically maintain any state information. It is the CGI programmer's responsibility to record state information in a file or database and then encode a "key" to that state information in the HTML, XML, or WML output.

    For example, if a client invokes a CGI program to "log in" to your application or to add an item to his/her "shopping cart," the CGI program must record that fact along with any user identification information in a file or database. When the CGI program generates the output, it should encode a user ID or key in a CGI variable that will get passed to the next CGI program that the client invokes. The next CGI program can then look up the user state information (for example, shopping cart contents) from the database. The user state information should also include a date/time "stamp" so that a maintenance program can delete records for users who haven't logged on in a specified amount of time or who left the application without logging out.

  • If you choose to use ANSI style ACCEPT and DISPLAY statements instead of–or in addition to–the ACCEPT and DISPLAY external-form-item syntax described in this section, you must include the UPON SYSOUT phrase or else compile with the -Ca option. -Ca implies UPON SYSOUT for all ANSI DISPLAY statements.

With these considerations in mind, you are ready to write your CGI program. The following sections describe how to accomplish the necessary I/O and processing tasks. The topic Sample CGI Programs provides some sample code for your reference.

  • Reading CGI Input Data
  • Processing the User's Request
  • Generating Output
  • Sample CGI Programs
Parent topic: Launching Web Applications Through CGI


Reading CGI Input Data

With ACUCOBOL-GT, there are two ways to read CGI input data:

  • With the ACCEPT verb. Use this method in most cases.
  • With the C$GETCGI library routine. Use this method when converting existing COBOL CGI programs to ACUCOBOL-GT.
  • Using the ACCEPT Verb
  • Using the C$GETCGI Routine
Parent topic: Writing a CGI Program


Using the ACCEPT Verb

To read CGI variables from the client machine, you can use the ACCEPT verb in your CGI program. ACUCOBOL-GT includes special syntax for accepting HTML, XML, or WML form records. The syntax is:

ACCEPT external-form-item

where external-form-item is an input record for an HTML, XML, or WML form. It is a group data item (declared with the IS EXTERNAL-FORM clause) that has one or more elementary items associated with CGI variables. For "input forms," the association is made using the IDENTIFIED BY clause in the description of the elementary item. The value of external-name is the name of the CGI variable. If the IDENTIFIED BY phrase is omitted, the data item's own name (data-name) is used as the name of the CGI variable.

External-form-item may also be an output record for an HTML, XML, or WML form. In this case, the group item is declared with both the IS EXTERNAL-FORM and IDENTIFIED BY clauses.

The "external form" is called an "output form" if the IDENTIFIED BY clause is used in the description of the group item to associate it with a template file.

For example, the following is an input form:

01  CGI-FORM   IS EXTERNAL-FORM.
    03  CGI-VAR1   PIC X(10).
    03  CGI-VAR2   PIC X(10).

and here is an output form:

01  HTML-FORM   IS EXTERNAL-FORM IDENTIFIED BY "tmplate1".
    03  HTML-VAR1   PIC X(10).
    03  HTML-VAR2   PIC X(10).

The ACCEPT verb treats input and output forms the same. ACCEPT sets the value of each elementary item in the external form, in order, to the value of its associated CGI variable, padding with trailing spaces. ACCEPT automatically decodes and translates the CGI input data before moving it to the elementary items of external-form-item. The value of each CGI variable is converted to the appropriate COBOL data type when it is moved to the external form.

Please note that when some browsers encounter multiple-line entry fields (also known as HTML TEXTAREAs, they send a carriage return line feed sequence to the CGI program. If carriage returns are not desired, as in operating systems that automatically terminate text lines with line feed characters, you can have them removed by using the CGI_STRIP_CR runtime configuration variable.

Also note that CGI variable names are case-sensitive. However, for convenience, if ACCEPT cannot identify a CGI variable, it will repeat the search for the variable ignoring the case.

If the CGI variable is empty or does not exist, ACCEPT sets the value of numeric data items to zero and nonnumeric data items to spaces.

If the CGI variable is repeated in the CGI input data, as in the case where multiple items have been selected from a "choose-many" list, the external form item that is identified with the CGI variable must be in a table using the OCCURS clause. Otherwise, only the first CGI value is moved to the external form item.

For example:

01  CGI-FORM   IS EXTERNAL-FORM.
    03  CGI-TABLE   OCCURS 10 TIMES.
        05  CGI-VAR1   PIC X(10).
        05  CGI-VAR2   PIC X(10).

or

01  CGI-FORM   IS EXTERNAL-FORM.
    03  CGI-VAR1   PIC X(10) OCCURS 10 TIMES.
    03  CGI-VAR2   PIC X(10) OCCURS 10 TIMES.

ACCEPT moves the values of the CGI variable to the items in the table. After all of the CGI values have been moved to items in the COBOL table, the remaining items in the table are set to "0" if they are numeric items and spaces otherwise.

Parent topic: Reading CGI Input Data


Using the C$GETCGI Routine

The C$GETCGI library routine retrieves CGI variables from the environment or the standard input stream, "stdin", like other types of COBOL CGI programs. The C$GETCGI routine should be used by those with existing COBOL CGI programs to retrieve CGI variables as normal while incrementally converting to ACUCOBOL-GT's external form method of CGI data retrieval. Although "ACCEPT from stdin" and "ACCEPT external-form-item" cannot be used together, you may use C$GETCGI instead of or in combination with external forms. The C$GETCGI routine retrieves the exact size of a CGI variable.

To use C$GETCGI, include a CALL in your CGI program using the following syntax:

CALL "C$GETCGI"
   USING VARIABLE-NAME, DEST-ITEM, VALUE-INDEX
   GIVING VALUE-SIZE

where the following are defined in the Working-Storage or Data Division sections of your program.

Parameter | Type | Description
VARIABLE-NAME | PIC X(n) | Contains the name of the CGI variable.
DEST-ITEM | PIC X(n) | Receives the value of the given CGI variable.
VALUE-INDEX | Numeric value | Contains the CGI value index. This optional parameter contains an index that is used when a CGI variable has multiple values in the CGI input data. This typically happens when multiple items have been selected from a "choose-many" list box. For example, to receive the third selected value, pass 3 for VALUE-INDEX. If VALUE-INDEX is greater than the total number of values in the input stream for the given CGI variable, spaces are moved to DEST-ITEM.
VALUE-SIZE | Signed numeric value | Receives the size of the resulting value. This may be "0" to indicate that the variable exists but has no value or "-1" to indicate that the variable does not exist.

C$GETCGI automatically determines whether to read the CGI variable from the environment or "stdin" depending on the value of the "REQUEST_METHOD" environment variable, which is set by the Web Server. The first time C$GETCGI is called, it reads all of the CGI variables and values into a variable-length buffer. If REQUEST_METHOD is "GET", the data is read from the QUERY_STRING environment variable. If the REQUEST_METHOD is "POST", it is read from "stdin".

Each time C$GETCGI is called, it searches for the variable name passed in the first parameter, translates the value from CGI format into standard format, and moves the result to the destination item passed in the second parameter.

Note: When some browsers encounter multiple-line entry fields (also known as HTML TEXTAREAs), they send a carriage return line feed sequence to the CGI program. If carriage returns are not desired, as in operating systems that automatically terminate text lines with line feed characters, you can have them removed by using the CGI_STRIP_CR runtime configuration variable. See Creating a Runtime Configuration File for Your CGI Program for details.

An optional third parameter specifies a CGI value index. This index is used when a CGI variable has multiple values in the CGI input data, as in the case where multiple items have been selected from a "choose-many" list.

Parent topic: Reading CGI Input Data


Processing the User's Request

The second function of most CGI programs is to process the CGI input data or user's request. Usually, this is a calculation, database lookup, or file read, although CGI programs can invoke modules of an existing application to perform a function and return data. This is the part of CGI programming that is most familiar to COBOL developers: the application processing component.

It is important to note that since CGI programs are executed on the Web server machine by the Web server itself, they are not allowed to perform any user interface operations directly. If a CGI program attempts any operation that waits for a user response, it may cause the Web server to "hang."

Therefore, when writing CGI programs, you should be especially careful not to include code that waits for user input (using the ACCEPT verb).

There are some cases when the runtime displays a message box even before loading the COBOL program. There are other cases when the runtime shuts down due to an error that is not handled by the COBOL program. In these cases the runtime displays a message box containing the text of the message and waits for the user to press the OK button. This can cause a problem when the runtime is executed by a Web server.

To solve this problem, when you are configuring the Web server to execute the runtime, be sure to use the "-f" command line option or to configure your environment with the A_CGI environment variable. Both of these methods cause the runtime to suppress warning messages that are normally displayed in a message box. When the runtime shuts down due to an error that is not handled by the COBOL program, it constructs an HTML, XML, or WML page containing the shutdown message and sends it to the standard output stream before terminating. for more information, see Configuring the Web Server.

Parent topic: Writing a CGI Program


Generating Output

Your CGI program can generate many types of output, including–but not limited to–HTML, WML, and XML. By default, it returns HTML output for users accessing your program on a Web site. If you want the output to be in XML format, or if you intend for it to be displayed on a WAP device, you must configure your program to generate XML or WML output instead. To do so, you use the runtime configuration variable, CGI_CONTENT_TYPE. (SeeCGI_CONTENT_TYPE for more information on this variable.)

Regardless of the format, to generate output, your CGI program must use the DISPLAY statement. With ACUCOBOL-GT, the DISPLAY verb constructs HTTP response headers for you automatically and routes them to "stdout". The response header that the DISPLAY verb generates can include a pointer to a URL where response data can be found, or it can be followed by an HTML, WML, or XML document. Headers that point to URLs have the content type "location". Headers that include form data have the content type "text/html", "text/wml", or "text/xml".

Note that the runtime can DISPLAY virtually any type of content, as long as the content type ID corresponds to the form specified in the DISPLAY syntax.

  • Using the DISPLAY Statement
Parent topic: Writing a CGI Program


Using the DISPLAY Statement

You can use the DISPLAY statement to display records from many types of forms, including HTML, WML, and XML forms. To do so, use the following syntax:

DISPLAY external-form-item

where external-form-item is an output record for the form when used in a Common Gateway Interface (CGI) program. It is a group data item (declared with the IS EXTERNAL-FORM and IDENTIFIED BY clauses) that may have one or more elementary items associated with fields in an HTML, WML, or XML template. The association is made using the IS IDENTIFIED BY clause.

External-form-item may also be an input record for a form. In this case, the group item is declared with only the IS EXTERNAL-FORM clause. This is used primarily when you are debugging your CGI program.

The DISPLAY verb treats input and output forms differently. For output forms, DISPLAY merges the data contained in the elementary items into the associated template file and sends the result to the standard output stream in conformance with the CGI specification. To do this, DISPLAY scans the template file for data names delineated by two percentage signs on either side (i.e., %%dataname%%). It then replaces those data names with the contents of the associated elementary items from the output form, stripping trailing spaces.

The maximum length of a single line in the template file is 256 bytes. The maximum length of a single output line is 512 bytes. No conversion is performed on the output form items before they are merged with the template file.

You may specify a series of directories for locating template files. To do this, use the HTML_TEMPLATE_PREFIX configuration variable, even if you are specifying a directory for locating XML or WML templates. See Creating a Runtime Configuration File for Your CGI Program for details. For related information about file content, see also the configuration variable CGI_CONTENT_TYPE.

When associating the template file with the IS IDENTIFIED BY clause, you may omit the template file suffix if it is either ".html" or ".htm"; otherwise, you must include the suffix. If the suffix is omitted, DISPLAY first appends ".html" to the specified file name and tries to open it. If that fails, DISPLAY appends ".htm" to the file name and tries to open it. If that fails, DISPLAY tries to open the file exactly as specified. If all these attempts fail, the following error message is sent to the standard output stream in HTML format:

Can't open HTML template "template-file-name"

When the Web server executes your CGI program, the current working directory depends on the configuration of the specific Web server that is running. In many cases the current working directory is the same as the Web server's "root" directory. As part of the CGI specification, when the Web server executes your CGI program, it sets an environment variable called PATH_TRANSLATED to the directory containing your CGI program. You may want to use this information to locate your template files.

For example, if your template files are in the same directory as your CGI programs, set the HTML_TEMPLATE_PREFIX configuration variable to the value of PATH_TRANSLATED as follows:

01  CGI-DIRECTORY   PIC X(100) VALUE SPACES.
...
ACCEPT CGI-DIRECTORY FROM ENVIRONMENT "PATH_TRANSLATED".
SET CONFIGURATION "HTML_TEMPLATE_PREFIX" TO CGI-DIRECTORY.

The output from a CGI program must begin with a "response header". DISPLAY automatically generates a "Content-Type" response header if the specified template file is a local file (i.e., not a URL).

You may specify the EXTERNAL-FORM clause for an item that has no subordinate items. This is useful for displaying static Web pages. To do this, specify the name of the static Web page in the IDENTIFIED BY clause. For example, if you have a Web page called "webpage1.html", add the following lines to your COBOL program:

01  WEB-PAGE-1   IS EXTERNAL-FORM
IDENTIFIED BY "webpage1"
...
DISPLAY WEB-PAGE-1.

You may also specify a complete URL instead of a template file name in the IDENTIFIED BY clause. In this case, DISPLAY generates a "Location" response header that contains the URL. This header specifies that the data you're returning is a pointer to another location. To determine whether the template file name is a URL, DISPLAY scans it for the "://" string. DISPLAY does not apply the HTML_TEMPLATE_PREFIX when the template file name is a URL.

For example, if your program determines that the information the user has requested is on another Web server, and its URL is "http://www.theinfo.com", add the following lines to your COBOL program:

01  THE-INFO-URL   IS EXTERNAL-FORM
IDENTIFIED BY "http://www.theinfo.com"
...
DISPLAY THE-INFO-URL.

The length of the URL must not exceed 256 bytes.

Only one response header is sent to the standard output stream. Your CGI program should exit immediately after sending a location header (i.e., after displaying an external form identified by a URL).

You may use as many template files as you like in a single program. A common way to use multiple template files is to have three output forms:

a header, body, and footer. Each of these has a corresponding template file. You first display the header form, then move each row of data to the body form and display it, and finally display the footer form.

When an input form is specified in a DISPLAY statement, the names and values of each elementary item are sent to the standard output stream in the format specified by the CGI_CONTENT_TYPE variable (HTML, WML, XML, etc.). One line is generated for each elementary item. The line consists of the name of the item followed by " = ", followed by the first 100 bytes of the item's value. This can be useful when you are testing and debugging your CGI program.

Parent topic: Generating Output


Sample CGI Programs

The following CGI programs were written in ACUCOBOL-GT.

  • Oscars Sample
  • Hello User sample
  • Substituting a URL Sample
Parent topic: Writing a CGI Program


Oscars Sample

The first program, oscars, is designed to return the names of actors and actresses who won Oscar awards in a specified year. Notice the definition of external form items in the Working-Storage section of this program. Notice also that the ACCEPT statement in the main logic section ACCEPTs these external form items, and that the DISPLAY statement defines the HTML templates to be used: "HTML-header-form," "HTML-footer-form," and "body-para." The contents of these templates follows.

identification division.
program-id. oscars.
remarks.
working-storage section.
01  cgi-form       is external-form.
    05 y2004       pic x(5) is identified by "y2004".
    05 y2003       pic x(5) is identified by "y2003".
    05 y2002       pic x(5) is identified by "y2002".
01  cgi-form-table redefines cgi-form.
    05  cgi-year   pic x(5) occurs 5 times.
01  html-header-form is external-form identified by "header".
    05  opening-message    pic x(40).
01  html-body-form is external-form identified by "body".
    05  ryear      pic x(5).
    05  html-oscar-info.
        10  rmovie       pic x(25).
        10  ractor       pic x(42).
        10  ractress     pic x(42).
01  html-footer-form is external-form identified by "footer".
    05  closing-message  pic x(40).
01  movie-values.
     05  2004-oscar.
        10 movie     pic x(25) value "THE LORD OF THE RINGS".
        10 actor     pic x(42) value "Sean Penn MYSTIC RIVER".
        10 actress   pic x(42) value "Charlize Theron MONSTER".
     05  2003-oscar.
        10 movie     pic x(25) value "CHICAGO".
        10 actor     pic x(42) value "Adrien Brody THE PIANIST".
        10 actress   pic x(42) value "Nicole Kidman THE HOURS".
     05  2002-oscar.
        10 movie     pic x(25) value "A BEAUTIFUL MIND".
        10 actor     pic x(42) value "Halle Berry MONSTER'S BALL".
        10 actress  pic x(42) value "Denzel Washington TRAINING DAY".
01  movie-table redefines movie-values occurs 5 times.
     05  oscar-winners.
         10  best-movie   pic x(25).
         10  best-actor   pic x(42).
         10  best-actress pic x(42).
01  various-counters.
     05 idx-1              pic 99 value 1.
procedure division.
main-logic.
accept cgi-form.
     if cgi-form = space
          move "You did not select any years!" to opening-message
          display html-header-form
          move "Back up and try again." to closing-message
     else
          move "Acucorp CGI in action." to opening-message
          display html-header-form
          perform display-body-para
          move "THE END." to closing-message
     end-if.
     display html-footer-form.
     stop run.
display-body-para.
     perform varying idx-1 from 1 by 1 until idx-1 > 12
          if cgi-year(idx-1) = space
               continue
          else
               move cgi-year(idx-1) to ryear
               move movie-table(idx-1) to html-oscar-info
               display html-body-form
          end-if
     end-perform.

Header.htm

<HTML><HEAD><TITLE>ACUCOBOL-GT CGI Header</TITLE></HEAD>
<BODY>
<H2>%%opening-message%%</H2>
<CENTER><H1>Oscar Winners</H1>
<HR>
<TABLE border cellspacing=0 cellpadding=5>
<TR>
<TH colspan=4 align=center>Your Selections</TH>
</TR>
<TR align=center>
<TH>Year</TH>
<TH>Best Movie</TH>
<TH>Best Actor</TH>
<TH>Best Actress</TH>
</TR>

Footer.htm

</TABLE>
</CENTER>
<H2>%%closing-message%%</H2>
<HR>
<P>The information you requested was processed by the ACUCOBOL-GT CGI program.
<BR>Following the CGI standard, ACUCOBOL-GT was able to send
<BR>the requested data items to the appropriate templates and
<BR>return the completed HTML document back to you.</P>
</BODY></HTML>

Body.htm

<TR align=center>
<TD>%%ryear%%</TD>
<TD>%%rmovie%%</TD>
<TD>%%ractor%%</TD>
<TD>%%ractress%%</TD>
</TR>

Oscar.htm

<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
<META NAME="Generator" CONTENT="Microsoft Word 97">
<TITLE>ACUCOBOL-GT CGI Example</TITLE>
<META NAME="Template" CONTENT="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot">
</HEAD>
<BODY LINK="#0000ff" VLINK="#800080">
<H2>ACUCOBOL-GT CGI Example using ACUCOBOL-GT.</H2>
<H3>This example shows how easily you can use ACUCOBOL-GT to act as a CGI program.
<BR>User input is transferred from the following HTML page to a ACUCOBOL-GT program running <BR>
on the web server. The appropriate output is returned.</H3>
<P><HR></P>
<H1 ALIGN="CENTER">Oscar Trivia</H1>
<P>Select a year(s)and press the Submit Query button. <BR>
The Best Picture, Best Actor and Best Actress for each year selected will be returned. </P>
<FORM ACTION="http://your_server_name/Scripts/oscars.acu" METHOD="post">
<P>Year: </P>
<P>
<INPUT TYPE="checkbox" NAME="y2004" VALUE="2004">
2004
<INPUT TYPE="checkbox" NAME="y2003" VALUE="2003">
2003
<INPUT TYPE="checkbox" NAME="y2002" VALUE="2002">
2002
<P>
<INPUT TYPE="submit"  VALUE="Submit Query" >
</P></FORM></BODY>
</HTML>
Parent topic: Sample CGI Programs


Hello User sample

The following CGI program assumes that the user has been asked to enter his or her name, and that the entered name is stored in the CGI variable "username". This can be accomplished using the following HTML form:

<body>
<form action="/cgi-bin/simple.acu" method="get">
Please enter your name or leave blank for "anonymous":
<input type="text" name="username" size=60>
<input type="submit" value="Submit">
</form>
</body>

This program also uses an HTML template, "greeting.html". Here is an example:

<body>
Hello %%username%%
This Web page is still under construction.
Please try again in a few days.
</body>

The CGI program then, is as follows:

identification division.
program-id. simple.
remarks.
data division.
working-storage section.
01  input-output-form is external-form is identified by "greeting".
    03  user-name  pic x(60) identified by "username".
procedure division.
main-logic.
    accept input-output-form.
    display input-output-form.
Parent topic: Sample CGI Programs


Substituting a URL Sample

This program demonstrates using an external form to substitute a URL for the output.

identification division.
program-id. acusrch.
remarks.
data division.
working-storage section.
01  acucorp-search-url   pic x(40) is external-form
          identified by "http://www.acucorp.com/cgi-bin/acusearch".
procedure division.
main-logic.
     display acucorp-search-url.
Parent topic: Sample CGI Programs


Creating a Runtime Configuration File for Your CGI Program

You can configure many aspects of input and output handling by including a runtime configuration file with your CGI program on the Web server. For instance, you can configure the type of output to be generated by using the CGI_CONTENT_TYPE variable. Name and format the configuration file as you would any ACUCOBOL-GT runtime configuration file. For details, see Runtime Configuration. The configuration file for your CGI runtime can contain any or all of the following variables:

  • CGI_STRIP_CR
  • CGI_CONTENT_TYPE
  • CGI_NO_CACHE
  • CGI_AUTO_HEADER
  • HTML_TEMPLATE_PREFIX
  • CGI_CLEAR_MISSING_VALUES
Parent topic: Launching Web Applications Through CGI


CGI_STRIP_CR

When some browsers encounter multiple-line entry fields (also known as HTML TEXTAREAs), they send a carriage return line feed sequence to the CGI program. When this sequence is subsequently output to files on operating systems that terminate text lines with line feed characters, the data may appear to be double spaced.

If desired, you can configure the runtime to automatically remove carriage return characters from HTML data entered in multiple-line entry fields. To do so, set the runtime configuration variable CGI_STRIP_CR to "1" (on, true, yes). Stripping the carriage returns from this kind of input prevents double-spacing problems, as well as conflicts that may arise if the data is used in a context that does not expect a carriage return character to precede each line feed character. The default value for this variable is "0" (off, false, no).

For example, if an end user enters the following three lines in a TEXTAREA for a field called "thetext":

Sometext line 1
Sometext line 2
Sometext line 3

The browser sends the following to the CGI program:

thetext=Sometext+line+1%0D%0ASometext+line+2%0D%0ASometext+line+3%0D%0A

If the CGI_STRIP_CR is set to "1" (on, true, yes), the runtime strips the carriage return characters so that the input line is the following:

thetext=Sometext+line+1%0ASometext+line+2%0ASometext+line+3%0A
Parent topic: Creating a Runtime Configuration File for Your CGI Program


CGI_CONTENT_TYPE

By default, the output generated by your CGI program is mapped as HTML content. To associate your CGI output with a MIME content type other than "text/html", use the CGI_CONTENT_TYPE configuration variable. This variable lets you control the content type information in the header of output files created by ACUCOBOL-GT. Such information informs recipients of the type of content that they are about to receive.

Using this variable, you can configure your CGI program for many types of output, including eXtensible Markup Language (XML) or Wireless Markup Language (WML) for Wireless Application Protocol (WAP) devices like mobile phones.

Whichever format you choose, the US-ASCII character set is applied to the output by default. If you want the CGI output to be mapped to an alternate character set such as ISO-8859-I (Western European), then you can specify the character encoding set to use with the variable as well.

Include this variable in your runtime configuration file as follows:

CGI_CONTENT_TYPE contenttype;  charset=encoding_set

Where contenttype is the MIME content type of the generated output, and encoding_set is the preferred character encoding set to use.

For example, the WML content type for WAP mobile phones is "text/vnd.wap.wml". To associate your CGI output with WML, include the following in your configuration file:

CGI_CONTENT_TYPE text/vnd.wap.wml

If you want your WML output to be mapped to the Western European character set, include the following:

CGI_CONTENT_TYPE text/vnd.wap.wml; charset=iso-8859-I

The content type for eXtensible Markup Language (XML) documents is "text/xml". If your program generates XML data, include the following:

CGI_CONTENT_TYPE text/xml
Note: To avoid overriding other Content-Type associations, we suggest that you create a different configuration file for each of the MIME Content-Type associations that you make in your Web server setup.

Please note that if you use this variable, the external forms indicated in your program's DISPLAY syntax must contain the appropriate content. In other words, if you associate your program with the "text/xml" content type, the forms must be ".xml" documents with XML syntax. If you associate it with "text/vnd.wap.wml", the forms must be ".wml" documents with WML syntax. Your program can DISPLAY virtually any type of data, as long as the Content-Type ID corresponds to the external form file that you provide.

Be aware that if you do not use the proper file extension for your external form documents, the Web server will interpret the data as HTML and display the wrong data. WML and XML are also more sensitive to syntax errors than HTML.

In addition, note that the capabilities of the configuration entry CGI_NO_CACHE may be affected by the content type that you choose.

Parent topic: Creating a Runtime Configuration File for Your CGI Program


CGI_NO_CACHE

Using the runtime configuration variable CGI_NO_CACHE, you can choose whether or not the HTML output of your CGI program will be cached by the requesting client. By default, the runtime generates "Pragma: no-cache" in the HTTP response header that gets sent to the standard output stream. If you set CGI_NO_CACHE to "0" (off, false, no) in the runtime configuration file, the runtime suppresses this line of the response header. The default value is "1" (on, true, yes).

Parent topic: Creating a Runtime Configuration File for Your CGI Program


CGI_AUTO_HEADER

Set the runtime configuration variable CGI_AUTO_HEADER to "0" (off, false, no) if you want to suppress the output of the HTML header. This can be useful when you want to execute a CGI program and include its output into an existing flow of HTML text. For example, with server-side includes (SSI), you can instruct the Web server to execute a subprogram in the manner of CGI and incorporate its output right into the HTML document before sending it to the requesting client. SSIs are commands in an HTML document that are interpreted by the Web server. They are used when you want to include the contents of another file in the current HTML document or to execute a script whose output will be included in the current HTML document before being sent to the browser client. Refer to any HTML documentation for information on using SSIs.

Parent topic: Creating a Runtime Configuration File for Your CGI Program


HTML_TEMPLATE_PREFIX

Use this configuration variable to specify a series of directories for locating HTML, XML, or WML template files. This variable is similar to FILE_PREFIX and CODE_PREFIX. Specify the directories as a sequence of space-delimited prefixes to be applied to the file name. All directories in the sequence must be valid names. The current directory can be indicated by a period (regardless of the host operating system). For example:

HTML_TEMPLATE_PREFIX . /html/templates

tells the runtime to look for templates in the current directory and the "/html/templates" directory.

If the template name specified in your CGI program's IS IDENTIFIED BY clause is a URL with "\\" characters, the runtime ignores the HTML_TEMPLATE_PREFIX setting.

Parent topic: Creating a Runtime Configuration File for Your CGI Program


CGI_CLEAR_MISSING_VALUES

This variable lets you to control the behavior of the ACCEPT statement when CGI variables are empty or do not exist in the CGI input data.

By default, ACCEPT sets the value of numeric data items to zero and non-numeric data items to spaces if a CGI variable is empty or does not exist. Set the CGI_CLEAR_MISSING_VALUES configuration variable to "0" (off, false, no) if you do not want ACCEPT to clear the value of the data item in this case.

Parent topic: Creating a Runtime Configuration File for Your CGI Program


Configuring the Web Server

Most Web servers must be specially configured to invoke the ACUCOBOL-GT runtime to execute your CGI program. For instance, using IIS on Windows machines, you map the ".acu" extension with the ACUCOBOL-GT runtime ("wrun32.exe") in the Web server configuration settings. On UNIX machines using Apache, you must provide a small shell script to invoke the runtime along with the COBOL CGI program.

Although we have included helpful suggestions in this section for configuring Web server products for this purpose, please be aware that we are unable to provide technical assistance for Web server configuration efforts. Configuration procedures vary with each Web server product, so be sure to refer to your Web server documentation for specific details.

Although configuration procedures vary with Web server platforms, each Web server shares one characteristic: if a CGI program attempts any operation that waits for a user response, it will cause the CGI process to "hang." At best this wastes system resources. At worst, it may cause the entire Web server to "hang." Even if your code does not wait for user input, there may be some cases when the runtime displays a message box even before loading the COBOL program, or when shutting down due to an error that is not handled by the COBOL program.

To help you avoid problems with the Web server when running your CGI program, configure the Web server with the “-f” runtime command line option as shown in the procedures below. If you prefer, you can accomplish the same thing by configuring the environment with the A_CGI environment variable. In general, we recommend that you use the "-f" option, because environment variables can affect other COBOL programs as well.

In addition, if you will be running your CGI program on a UNIX system, you should include the “-b” runtime option. It inhibits terminal initialization, which can lead to problems with CGI.

  • To Configure IIS on a Windows 2000 Server
  • To Configure Apache on a UNIX Server
  • -b Runtime Option
  • -f Runtime Option
  • A_CGI Environment Variable
Parent topic: Launching Web Applications Through CGI


To Configure IIS on a Windows 2000 Server

Following is a procedure for associating your ".acu" applications with the ACUCOBOL-GT runtime using Microsoft's Internet Information Server (IIS) Version 5.0 on a Windows 2000 Server. Your own Web server software may vary.

  1. Start the Internet Services Manager, normally available under Start/Programs/Administrative Tools/Internet Services Manager.
  2. Select "Default Web Site" (or the Web site you wish to configure) in the left pane.
  3. Expand this node and select the directory (or virtual directory) containing your ACUCOBOL-GT CGI program files.
  4. From the Action menu, select Properties.
  5. In the Properties sheet, select the Directory (or Virtual Directory) tab.
  6. Uncheck the "Read" check-box. This will prevent the Web server from trying to deliver your object files to the client.
  7. Create an application by clicking the Create button under Application Settings. (If the application has already been created, you will see a Remove button instead of a Create button. If so, skip this step.)
  8. Set the "Application name" field to any name of your choosing. The default value is the name of the containing directory or virtual directory.
  9. Make sure the "Execute Permissions" field is set to "Scripts only". This is the default.
  10. Click the Configuration... button. A configuration screen appears with the "App Mappings" tab selected.
  11. Click the Add button.
  12. In the "Executable" field, enter the path to the ACUCOBOL-GT runtime ("wrun32.exe"), or use the Browse button to locate it.
  13. To the end of this path, add your desired runtime options, followed by a space and "%s". Be sure to include the "-f" runtime option.

    For instance:

    C:\Program Files\Micro Focus\Acucbl900\AcuGT\bin\wrun32.exe -f "%s"
  14. In the "Extension" field, enter the extension you use for your ACUCOBOL-GT object files (by default, ".acu").
  15. Click OK three times to close the Add dialog, the Configuration screen, and the Properties sheet.
Parent topic: Configuring the Web Server


To Configure Apache on a UNIX Server

If you are using the Apache HTTP server on a UNIX machine, a small shell script is required to invoke the runtime and your COBOL CGI program. Depending on your Web server settings, you may need to place this script in a particular directory (called a ScriptAlias directory in Apache), or you may need to assign it a particular extension, such as ".cgi". In Apache, you normally set extensions using the AddHandler directive.

A typical script to invoke an ACUCOBOL-GT program called "myprog.acu" might look like this:

#!/bin/sh
RUNTIME=/usr/acucobol/bin/runcbl
exec $RUNTIME –f –b myprog.acu

Note that both the "-f" and "-b" runtime options are specified. These options are described in the following sections.

Parent topic: Configuring the Web Server


-b Runtime Option

If you will be running your CGI program on a UNIX system, you should include the "-b" runtime option to prevent the runtime from attempting terminal initialization. If you do not, the runtime will attempt to open the file "/etc/a_termcap" (or the file named in the A_TERMCAP environment variable). It will then try to match the value of either the A_TERM or TERM environment variables, if set, to an entry in the "a_termcap" file. If any of these files or variables is not set up properly, the runtime will terminate with an error. By using the "-b" option, this entire process is bypassed. In addition, using the "-b" option prevents extraneous characters from being displayed in the HTML output.

This option has no effect on Windows platforms.

Parent topic: Configuring the Web Server


-f Runtime Option

The "-f" command-line option ensures that the runtime does not perform user interface functions when running as a CGI program. It is recommended for both Windows and UNIX CGI implementations.

When executed with "-f", the server runtime suppresses warning messages that are normally displayed in a message box. When the runtime shuts down because of an error that is not handled by the COBOL program, it constructs an HTML page containing the shutdown message and sends it to the standard output stream before terminating.

Parent topic: Configuring the Web Server


A_CGI Environment Variable

The A_CGI environment variable also ensures that the runtime does not perform user interface functions when running as a CGI program, but it does so by changing the entire server environment. As with any environment variable, A_CGI may affect other COBOL programs in addition to your CGI program.

When A_CGI is set to "1" in the environment, the runtime suppresses warning messages that are normally displayed in a message box. When the runtime shuts down due to an error that is not handled by the COBOL program, it constructs an HTML page containing the shutdown message and sends it to the standard output stream before terminating.

Parent topic: Configuring the Web Server


Using the ACUCOBOL-GT Web Runtime

  • What Is the Web Runtime?
  • How the Web Runtime Works
  • Deploying Applications via the Web Runtime
  • Setting Up a Web Site
  • Preparing Your ACUCOBOL-GT Application for the Web Runtime
  • Invoking Your COBOL Application with the Web Runtime
  • Obtaining and Distributing the Web Runtime
  • The User's Job
  • Security
  • Troubleshooting
  • Migrating from the Web Plug-in to the Web Runtime
Parent topic: A Programmer’s Guide to the Internet Version 10.2.0


What Is the Web Runtime?

The ACUCOBOL-GT® Web Runtime is a special 32-bit version of the ACUCOBOL-GT runtime that enables you to run existing ACUCOBOL-GT applications over the Internet. The Web runtime is based on Microsoft's ActiveX technology. It is itself an ActiveX control that you can embed on your Web page. It takes your existing COBOL applications and quickly makes them accessible through browsers that support ActiveX, particularly Microsoft Internet Explorer.

The Web runtime extends the built-in capabilities of Web browsers, allowing you to execute a COBOL program over the Internet without opening and running it as a separate application.

Because it works with existing applications, the Web runtime provides an easy way for you to deploy your applications on the Internet or in an intranet or extranet. For example, if your corporation has employees or distributors dispersed throughout a region, you can give these users remote access to sales and inventory applications via the Web.

The Web runtime is designed to run applications that make use of our AcuServer® or AcuConnect® technologies on the data or application host. While the Web runtime runs only on Windows machines, it can access files or run programs on UNIX and other platforms using these remote file and application server technologies, or through other file system interfaces like the Acu4GL® interface.

Although it would be unusual to do so, you can run the Web runtime without AcuServer and AcuConnect if your application does not need access to remote files. If the Web runtime cannot find a license to AcuServer or AcuConnect, it runs in restricted mode. For more details, please see Licensing Considerations.

Parent topic: Using the ACUCOBOL-GT Web Runtime


How the Web Runtime Works

The ACUCOBOL-GT Web Runtime works by communicating between the end user at a client machine and the remote server. The process is simple:

  1. The end user visits your Web site.
  2. The Web browser software looks for the Web runtime on the user's machine. If it locates the Web runtime, it runs it. The Web runtime, in turn, requests your application via HTTP, and launches the application locally.

    If the Web browser cannot find the Web runtime locally, it downloads the file from the specified location and asks the user "Do you want to install and run ACUCOBOL-GT Web Runtime?" This message may appear in a dialog box, or in newer versions of Windows (such as Windows XP, SP2), it may appear in an "Information Bar" at the top of the browser window. To assure the user that the installation is safe, the Web runtime is supplied as a cabinet (CAB) file with a digital signature from Micro Focus.

    If the user grants permission, the runtime and program are sent to the client machine, where the runtime automatically installs itself and launches your program locally.

Note: For automatic installation to be performed, you must program your Web page with the CODEBASE attribute of the OBJECT tag, as instructed in the topic Using the <OBJECT> Tag.

As the following diagram illustrates, data may reside on a remote server, or the ACUCOBOL-GT application may be distributed over several servers. In this instance, sites will require AcuServer for remote file access or AcuConnect for remote application access.

Data Distribution on Remote Servers

  • Windowing Options
  • How Your Program Executes
  • Browser Versions Supported by the Web Runtime
Parent topic: Using the ACUCOBOL-GT Web Runtime
Related information
Using the OBJECT Tag


Windowing Options

You can program the ACUCOBOL-GT Web Runtime to execute COBOL objects in their own application window or inside the user's Web browser window. How and where your program starts depends on the HTML commands that you use to include it on your Web site. For details, please see Invoking Your COBOL Application with the Web Runtime.

Listed below are some things to consider when choosing a windowing method.

  • Inside the User's Web Browser
  • In a Separate Application Window
Parent topic: How the Web Runtime Works


Inside the User's Web Browser

In this case, your COBOL program starts inside the user's browser window. Nearly all of the ordinary functions of your COBOL program are available to your user and your program has access to library routines that can be used to communicate with the browser.

In this mode, users also have access to browser functions like Forward, Back, and Search, but when they use these functions, the COBOL program terminates. To avoid losing data, the COBOL program should be designed to handle the closing action gracefully within ten seconds. If users return to the page from which they launched the ACUCOBOL-GT application, it reloads like any Web page.

Note that because of a Microsoft child window restriction, applications running inside a browser window cannot display a main window menu bar as you or your users might expect. To work around this restriction, you can program your application's menu functions to be accessed from a toolbar or a pop-up menu that is activated with the right mouse button.

Parent topic: Windowing Options


In a Separate Application Window

In this mode, your COBOL program starts in a window separate from the browser, making it look the same as it would if it were launched locally. All the functions of your original program are available to users, including a main window menu bar.

Although your program cannot access the library routines used to communicate with the browser in this mode, users can still access functions like Forward, Back, and Search simply by activating the browser window. However, when the user selects a browser function, the runtime object terminates. This is because the runtime object executes as an object related to the HTML page, even when running in a separate window.

Parent topic: Windowing Options


How Your Program Executes

To execute your program, the Web runtime actually makes a copy of it, delivers the copy to the browser client, and then executes the copy. Because the Web runtime utilizes the browser cache, the cache retains a copy of the object file as long as it is not reloaded. When the application is closed, the copy is removed as well.

Because of browser limitations, you cannot run multiple instances from a single Web page. When your browser shuts down, the Web runtime instance also shuts down. For each browser process, you can run only one instance of the Web runtime. However, you can run multiple browser processes, each hosting a single instance of the Web runtime.

Although the recommended method of executing the ACUCOBOL-GT Web Runtime is with the <OBJECT> tag, it can be executed by the browser in direct response to receiving data with the MIME content type, "application/vnd.acucobol." Internet Explorer looks at the Windows Registry to execute the program.

The browser loads the Web runtime and feeds it the data coming from the Web server. In this context there is no concept of a command line.

To pass "command line" style parameters to the ACUCOBOL-GT Web Runtime, you must specify them in HTML when you invoke the application in your Web page. Note that any file specified as a runtime option that requires write access (such as "errors.txt") is written to the directory listed in the authorization file, "acuauth.txt". If the authorization file is missing, an error results.

Parent topic: How the Web Runtime Works
Related information
Invoking Your COBOL Application with the Web Runtime


Browser Versions Supported by the Web Runtime

The Web runtime is designed for browsers that support ActiveX controls. We have confirmed that the Web runtime runs on Internet Explorer Versions 5.5 Service Pack 2 and later. Browsers that do not support ActiveX controls cannot use the Web runtime. Currently, this includes Netscape browsers, and some earlier versions of Internet Explorer.

Parent topic: How the Web Runtime Works


Deploying Applications via the Web Runtime

To deploy your application on the Web via the Web runtime, you (the developer) have three tasks:

  1. Set up a Web site.

    For details, see Setting Up a Web Site.

  2. Prepare and configure your ACUCOBOL-GT application for use with the Web runtime.

    Minimally, this could mean creating a library file with your application resources and configuration files, but optionally, you can also add Web-related library routines. See Preparing Your ACUCOBOL-GT Application for the Web Runtime.

  3. Update your Web page to invoke your COBOL program.

    To do this, you typically embed the URL of the Web runtime along with the URL of your application on your Web page using an <OBJECT> element and the CODEBASE attribute. See Invoking Your COBOL Application with the Web Runtime.

Once your work is done, the user has only one or two tasks:

  1. Visit your Web site.

    The Web runtime will install itself and launch your program automatically. Note that two dialog boxes may be displayed in the process: one containing a security message if required by the security setting of the user's browser, and the other containing a click-wrap license agreement from Micro Focus. For more information, see Security Warning Messages.

  2. If your application requires access to local resources or local network resources, the user has one additional task: to edit an authorization file.

    See How the Authorization File Works. If you write your application in such a way that the resources are accessed remotely (using AcuConnect and AcuServer), this step is not required.

Parent topic: Using the ACUCOBOL-GT Web Runtime
Related information
Setting Up a Web Site
Preparing Your ACUCOBOL-GT Application for the Web Runtime
Invoking Your COBOL Application with the Web Runtime
Security Warning Messages
How the Authorization File Works


Setting Up a Web Site

Setting up a Web site is probably the most time-intensive portion of this method, but it is not very difficult to do. Adding Internet Features to Your Program gives general information about setting up a Web site, including information on Web servers, posting a site, and promoting a site. Many different tools are available to help you create a Web page quickly and easily.

Parent topic: Using the ACUCOBOL-GT Web Runtime


Preparing Your ACUCOBOL-GT Application for the Web Runtime

The Web runtime component is significantly different from standard ACUCOBOL-GT runtimes in that you invoke it to process a single file. The single file may be either:

  • A library file that "packages" all of the objects and resources of your application into a single file.

    The library file can contain optional configuration files, together with bitmap or JPEG images. It can also contain eXtended file descriptors (".xfd" files) for use with Acu4GL.

  • The initial object of your COBOL application, with the remaining objects residing on a server.

    (This approach requires the use of AcuServer or AcuConnect technologies.)

The procedure for preparing your application for use with the Web runtime depends on whether you will be deploying your application in a distributed or non-distributed environment.

  • To prepare your application for use in a non-distributed environment:
  • To prepare your application for use in a distributed environment:
  • Coding for the Web Runtime
  • Configuring the Web Runtime
  • Packaging Your Application and Resources
Parent topic: Using the ACUCOBOL-GT Web Runtime


To prepare your application for use in a non-distributed environment:

  1. Code your application as usual, or use an existing application.
  2. As needed, include the appropriate library routines or fields described in the section Coding for the Web Runtime.

    Be sure to refer to the special coding considerations listed at the end of that section.

  3. Compile your programs with ACUCOBOL-GT.

    The resulting object file can be executed from within a browser on any Windows machine that has a Web runtime component installed.

  4. Configure the Web runtime if desired.

    This procedure is described in the section Configuring the Web Runtime. Note that you cannot access a configuration file on the client machine.

  5. Package your COBOL objects and resources into a single library file. You can also bundle configuration files, bitmaps, and ".xfd" files into the package, if desired.

    This procedure is described in Packaging Your Application and Resources. (Please note that if you have a single-object application and you are not using a separate configuration file, bitmaps, or Acu4GL, there is no need to package your application into a library.)

  6. Include the library file or single object in your Web site as described in Invoking Your COBOL Application with the Web Runtime.
Parent topic: Preparing Your ACUCOBOL-GT Application for the Web Runtime


To prepare your application for use in a distributed environment:

  1. Identify the files or processes that you want to distribute onto the server.

    Distributing files involves the use of AcuServer, our file server. Distributing processes involves the use of AcuConnect, our application server.

  2. Code your application as usual, or review your existing code for usefulness in the distributed Web runtime environment.

    As needed, include the appropriate library routines or fields described in Coding for the Web Runtime.

    Be sure to refer to the special coding considerations listed at the end of that section. If you plan to distribute processes, you may need to make some programming changes.

  3. Compile your initial program using ACUCOBOL-GT.

    The resulting object file can be executed from within a browser on any Windows machine that has the Web runtime installed.

  4. Create client/server configuration files as described in the AcuServer and AcuConnect User's Guides.

    Minimally, the client configuration file should contain the path of the server files or processes. You can achieve this using the FILE_PREFIX or CODE_PREFIX configuration variables.

  5. Configure the Web runtime as needed. This is described in the section Configuring the Web Runtime.
  6. Move all programs except the initial program onto the server.
  7. Set up and run AcuServer and/or AcuConnect on the server machine.
  8. Include the initial object file in your Web site using one of the methods described in the section Invoking Your COBOL Application with the Web Runtime.
Parent topic: Preparing Your ACUCOBOL-GT Application for the Web Runtime


Coding for the Web Runtime

Following are several optional library routines and fields included with ACUCOBOL-GT. These library routines and fields are designed specifically for use with the Web runtime.

Field/Routine | Description
W$BROWSERINFO routine | Returns the version and name of the requesting browser.
W$STATUS routine | Displays status information in the host browser's status bar.
IS-PLUGIN field in ACUCOBOL.DEF | Indicates whether or not the application is running in a Web browser via the ACUCOBOL-GT Web Runtime. Defined in ACUCOBOL.DEF.
W$GETURL routine | Passes a given URL to the browser. Lets you give end users access to other Web pages and the ability to send e-mail messages, conduct Web searches, and execute JavaScript.

Each of these routines and fields is described briefly below. For precise syntax and usage information, see the ACUCOBOL-GT User's Guide or ACUCOBOL-GT Reference Manual.

The Web runtime component (acugtax.ocx) supports the same ACUCOBOL-GT syntax as the standard runtime, with one exception. The following command is not supported:

ACCEPT mystring FROM COMMAND-LINE.

To pass parameters for the Web runtime, the instantiation of the object must call the methods "AcuParam1" through "AcuParam14" to set parameters for the application. In the COBOL code, you must then use the C$GETVARIANT function to retrieve parameters and C$SETVARIANT to return parameters.

  • W$BROWSERINFO Routine
  • W$STATUS Routine
  • IS-PLUGIN Field in ACUCOBOL.DEF
  • W$GETURL Routine
  • Other Coding Considerations
Parent topic: Preparing Your ACUCOBOL-GT Application for the Web Runtime


W$BROWSERINFO Routine

Sometimes, you may want your application to respond in different ways to different browsers. In this case, you can use the W$BROWSERINFO library routine to determine the version and name of the requesting browser, that is, the one that will be hosting the COBOL application.

CALL this routine using the following syntax:

CALL "W$BROWSERINFO" USING BROWSERINFO-DATA

Parameters:

BROWSERINFO-DATA Group item as follows:

01  BROWSERINFO-DATA.
    03  USER-AGENT-STRING          PIC X(50).
    03  BROWSER-MAJOR-VERSION      PIC X COMP-X.
    03  BROWSER-MINOR-VERSION      PIC X COMP-X.

BROWSERINFO-DATA is found in the COPY library "ACUCOBOL.DEF."

Upon return from W$BROWSERINFO, all of the data elements contained in BROWSERINFO-DATA are filled in. If you call W$BROWSERINFO and the COBOL application is not running in a Web browser via the Web runtime, the first field is set to spaces and the last two fields are set to zero. The BROWSERINFO-DATA fields have the following meaning:

Field | Description
USERAGENT-STRING | The browser's user_agent field. This contains the name of the browser software as it is sent to the HTTP server. It may also contain version numbers, product name, and operating system name. Netscape browsers set the first seven characters of this field to "Mozilla". Microsoft Internet Explorer sets this field to "Microsoft Internet Explorer".
BROWSERMAJORVERSION | The major version number reported by the browser. This is not the same as the major version number displayed in the browser's "About" screen. For example, both Netscape and Internet Explorer put "0" in this field.
BROWSER-MINOR-VERSION | The minor version number reported by the browser. This is not the same as the minor version number displayed in the browser's "About" screen. For example, both Netscape and Internet Explorer put "9" in this field.
Parent topic: Coding for the Web Runtime


W$STATUS Routine

If desired, you can display status information in the host browser's status bar by CALLing the W$STATUS routine.

CALL this routine using the following syntax:

CALL "W$STATUS" USING STATUS-MESSAGE

Where STATUS-MESSAGE, PIC X(n), contains the message to be displayed in the browser's status bar.

Note:

This routine is available only when the calling COBOL program is running in a Web browser window via the ACUCOBOL-GT Web Runtime. This routine is unavailable to programs run in a separate window when it is executed by a Web browser. The RETURN-CODE register is set to "1" after a successful call and "0" if this routine is unavailable.

Parent topic: Coding for the Web Runtime


IS-PLUGIN Field in ACUCOBOL.DEF

Using a field in ACUCOBOL.DEF, your COBOL program can determine whether or not it is running in a Web browser via the ACUCOBOL-GT Web Runtime. The field, known as IS-PLUGIN, is defined in the SYSTEM-INFORMATION group of ACUCOBOL.DEF.

For example, you might include the following code:

ACCEPT SYSTEM-INFORMATION FROM SYSTEM-INFO.
if IS-PLUGIN then
   display message box "Running via the Web runtime"
else
   display message box "Running via stand-alone runtime"
end-if.
Parent topic: Coding for the Web Runtime


W$GETURL Routine

If desired, you can enhance your COBOL program to give your end users access to other Web pages and the ability to send e-mail messages, conduct Web searches, and execute JavaScript. You determine how much functionality you want to give to your end users, and you code those functions into your application by passing URLs to the Web browser with the W$GETURL library function.

The W$GETURL library routine tells the runtime to pass a given URL to the host browser. The browser will handle the URL as if it were typed in the URL entry field.

Each URL that you pass with the W$GETURL routine contains a protocol and a path, separated by a colon.

Accessing a Web page uses the "http" protocol. For example,

http://www.acucorp.com/

tells the browser to contact the Web server "www.acucorp.com" and ask for the root page (/).

Sending e-mail uses the "mailto" protocol. For example,

mailto:support@acucorp.com

opens an e-mail message to the user "support" at the machine "acucorp.com".

JavaScript is also supported as a protocol, so you can execute JavaScript sequences that display dialog boxes, create Web pages, build text files, and much more.

Use this library routine as follows:

CALL "W$GETURL" USING URL, TARGET

where:

URL, PIC X(n), contains the complete URL. This can be of any type, such as http, FTP, news, mailto, gopher, or javascript.

TARGET, PIC X(n), represents the destination for displaying the URL. This can be a window or a frame. You can specify "_blank", "_parent", "_self", or "_top". You can also write the response data to a frame by specifying the frame name as the target parameter.

  • "_blank" loads the link into a new unnamed window.
  • "_parent" loads the link into the immediate parent of the document in which the link is contained.
  • "_self" loads the link into the same window where the link was clicked, causing the page to be repainted.
  • "_top" loads the link into the full body of the current window.
  • "<window_name>" loads the link into a named HTML frame. If no frame or window exists that matches the specified target name, a new window is opened for the link.

After a CALL is made to W$GETURL, subsequent URL requests are ignored until the CALL completes.

Note:

This routine is available only when the calling COBOL program is running in a Web browser window via the ACUCOBOL-GT Web Runtime. This routine is unavailable to programs run in a separate window when it is executed by a Web browser. The RETURN-CODE register is set to "1" after a successful call and "0" if this routine is unavailable.

Parent topic: Coding for the Web Runtime


Other Coding Considerations

When coding for the Web runtime, also consider the following points:

  • If you plan to have your application run inside the user's browser window, it cannot display the main window menu barto which you may be accustomed. (This is a Microsoft child window restriction.)

    In this case, you will need to program your application's menu functions to be accessed from a toolbar or a pop-up menu that is activated with the right mouse button.

    You can avoid this restriction by having your application run in its own separate window. You can specify this as a parameter of the <OBJECT> tag or use the AcuEmbedded method supplied with the object interface. For information on these options, see the topics Using the <OBJECT> Tag and Web Runtime Object Interface.

  • When running in QUIT-MODE, your program may not accept or display anything after an ACCEPT terminates with the QUIT-MODE exception.

    If your program attempts to accept or display anything, the runtime terminates immediately as if the program has executed a stop run.

  • If there is a file in the cache with the same name as your object file, it will be reused rather than downloaded from your Web site. You may need to implement a file naming scheme to prevent this.
  • When required, consider how your application will access local resources without affecting end user security.

    for security issues that affect coding. See Security.

  • Applications designed for the Web runtime should accommodate situations where a runtime license file cannot be found or the maximum number of allowable connections has been exceeded. In some cases, the application can provide messages that explain why program functions may be restricted. In other cases, the application can prompt users to try to access the server again later. See Licensing Considerations for more information.
  • To prevent file I/O restrictions, you may want to design your program in such a way that one of the first activities it performs is to open a file with AcuServer. This enables the program to "check out" or secure a runtime license, thereby ensuring that end users have full access to runtime functions. If a license file is found, the serial number is available in the "SERIAL-NUMBER" field of the SYSTEM-INFORMATION group in "acucobol.def".
  • To minimize the amount of setup work required by users, we recommend that you write your application in such a way that resources are always accessed remotely (using AcuConnect and AcuServer). If your application requires access to local resources or local network resources, your users will have to edit the authorization file accordingly. See Editing the authorization file for information on editing this file.
  • For security purposes, COBOL programs run in the Web runtime are not permitted to call certain library routines. For a complete list of these routines, see Restricted library routines.
Parent topic: Coding for the Web Runtime
Related information
Editing the authorization file
Licensing Considerations
Restricted library routines
Security
Using the OBJECT Tag
Web Runtime Object Interface


Configuring the Web Runtime

Once you've coded your application for the Web runtime, you canconfigure the runtime system in one of two ways: programmatically using the SET CONFIGURATION or SET ENVIRONMENT variables, or with a runtime configuration file.

  • Programmatic configuration
  • Runtime configuration files
Parent topic: Preparing Your ACUCOBOL-GT Application for the Web Runtime


Programmatic configuration

To configure the runtime programmatically, use the SET CONFIGURATION or SET ENVIRONMENT phrase in your source code. For example, if your application uses a configuration file with the entries:

FILE_PREFIX @hal:/u2/serverfiles
COMPRESS_FILES 1
KEYSTROKE EDIT=PREVIOUS EXCEPTION=52 kl

Add the following lines to your COBOL initialization code:

SET CONFIGURATION "FILE_PREFIX" TO "@hal:/u2/serverfiles".
SET CONFIGURATION "COMPRESS_FILES" to "1".
SET CONFIGURATION "KEYSTROKE" TO "EDIT=PREVIOUS EXCEPTION=52 kl".

MAX_FILES, MAX_LOCKS, and LOCKS_PER_FILE cannot be modified with the SET verb. These variables are used during the runtime initialization that occurs before the COBOL program is executed. In order to allow a wider range of applications to be used with the ACUCOBOL-GT Web Runtime, these variables have been given new default values.

When you are using the ACUCOBOL-GT Web Runtime, these variables are initialized to the following values:

MAX_FILES 255

MAX_LOCKS 512

LOCKS_PER_FILE 256

Note that the COBOL program can read environment variables using ACCEPT FROM CONFIGURATION (or ACCEPT FROM ENVIRONMENT).

Parent topic: Configuring the Web Runtime


Runtime configuration files

Create a configuration file for the Web runtime the same way that you would for the standard ACUCOBOL-GT runtime. Instructions can be found in the ACUCOBOL-GT User's Guide > Compiler and Runtime > Runtime Configuration.

Once you have a configuration file, you can access it via AcuServer, using the standard @ServerName:/pathname syntax, or you can bundle it into a library file along with the COBOL object files and resources. For information on using AcuServer to access your configuration files, see Setting up Accounts. For information on creating library files, see Packaging your Application and Resources.

Note that if you choose the library file method, you must also specify the name of the configuration file as an option when you invoke the Web runtime. (This is described in Invoking your COBOL Application with the Web Runtime.)

The Web runtime loads the configuration file by performing the equivalent of a SET CONFIGURATION statement for each line of the configuration file. Note that there are a few configuration variables that cannot be modified this way. They are MAX_FILES, MAX_LOCKS and LOCKS_PER_FILE. When you are using the ACUCOBOL-GT Web Runtime, these variables are initialized to the following values:

MAX_FILES 255

MAX_LOCKS 512

LOCKS_PER_FILE 256

Note that FILE_PREFIX is initially set to the list of directories specified in the "acuauth.txt" security file. This authorization file specifies the directories to which your COBOL programs have access on the user's machine. The path given in "acuauth.txt" is limited to 4096 characters, like the FILE_PREFIX variable. The path given in this file must be enclosed in quotation marks. If you define an alternate FILE_PREFIX in the configuration file that you embed with your object library, that value overrides the "acuauth.txt" setting.

Parent topic: Configuring the Web Runtime
Related information
Invoking Your COBOL Application with the Web Runtime
Packaging Your Application and Resources - Using the ACUCOBOL-GT Web Runtime


Packaging Your Application and Resources

When planning to package your application and resources, remember that the Web runtime is designed to process a single file. Therefore, if your application contains more than one object file and you do not plan to distribute your application across a client/server network, you must package all your COBOL object files and bitmap resources into a single library file. You can then access this file using the Web runtime.

If you will be using a configuration file, you can package the configuration file into the library file as well, or the configuration file must be on the remote computer. If your application will be accessing a relational database through our Acu4GL technology, you can package the ".xfd" files into the library file.

To create the library file package, you use the cblutil utility, the COPY RESOURCE statement, or a combination of the two.

If you are creating a library containing multiple COBOL objects, we recommend using "cblutil -lib" instead of using COPY RESOURCE. Using cblutil, you do not need to worry about the order in which COBOL objects are compiled (if you use COPY RESOURCE, you must ensure that the copied object is compiled first), and cblutil also checks for duplicated program names while COPY RESOURCE does not.

  • Using cblutil
  • Using COPY RESOURCE
Parent topic: Preparing Your ACUCOBOL-GT Application for the Web Runtime


Using cblutil

The cblutil utility lets you embed resources, which are defined as pieces of static data, directly into an object file. For the purposes of the Web runtime, these resources can be applications, bitmap or JPEG image files, wave files, configuration files, and extended file descriptors (.xfd files). The program treats the resource as if it were a disk file, but the resource is not actually a separate file in the target environment.

Using cblutil -lib, you can specify any type of file as an input file. If an input file is a COBOL object, cblutil includes it in the resulting library as a COBOL object. If an input file is another library, each component of the library is individually added to the resulting library. Any other file is included as a resource.

To use the cblutil utility program, type cblutil -lib followed by the desired options, main program name, and all the modules you want to include, separated by a space. Be sure to add the main or initial program to the library first, because the Web runtime executes the first program it finds in the library.

Syntax:

cblutil -lib [options] main_program modules

Example:

cblutil -lib -v -o mylib.acu prog1.obj prog2.obj
  logo.bmp cblconfi data1.xfd data2.xfd

When using cblutil -lib, you must use the -o option to specify the name of the output file. Because the Web runtime is registered to run files with the .acu extension, the output library file must have the .acu extension. In the example above, mylib.acu is the specified output file.

Parent topic: Packaging Your Application and Resources


Using COPY RESOURCE

If you are creating a simple, single object library without ".xfd" files, you can use the COPY RESOURCE statement to package your applications, bitmaps, and configuration file instead of or in addition to the cblutil utility.

Use the COPY RESOURCE statement as follows:

COPY RESOURCE resource-name [ {IN} path-name ] .
                              {OF}

where resource-name and path-name identify a resource file to be included in the resulting object file.

The effect of a COPY RESOURCE statement is to add resource-name to a list of resources that the compiler embeds into the resulting COBOL object file. The resources are added to the end of the COBOL object in the same order as the corresponding COPY statements. Since the resources are added to the end of the object, the location of the corresponding COPY RESOURCE statement in the COBOL program is irrelevant. Conventionally, COPY RESOURCE statements are placed either in Working-Storage or at the end of the program, but any location is acceptable.

If resource-name resolves to a COBOL object or library file, the compiler includes this object or library in the resulting object in a manner similar to cblutil -lib. These are not considered resources, but are embedded COBOL objects.

If you are creating a library containing multiple COBOL objects, we recommend using cblutil -lib instead of using COPY RESOURCE. Using cblutil, you do not need to worry about the order in which COBOL objects are compiled (if you use COPY RESOURCE, you must ensure that the copied object is compiled first), and cblutil also checks for duplicated program names while COPY RESOURCE does not.

Although technically you can include .xfd files in a library using COPY RESOURCE, these files must exist before you compile with the COPY RESOURCE statement. Because .xfd files are created at compile time, this means you must compile more than once. For this reason, the cblutil method is also preferred for including .xfd files in your object library.

Parent topic: Packaging Your Application and Resources


Invoking Your COBOL Application with the Web Runtime

There are a number of approaches you can take to invoke your COBOL application from your Web page. You can:

  • Use the <OBJECT> tag to invoke the application and Web control.

    Using an <OBJECT> tag, you can invoke your application and the Web runtime with a single HTML element. If you add the CODEBASE attribute, users can automatically download the control the first time they access the application, and get updates automatically. The browser checks the clsid attribute and downloads a new version of the control, if one is available. In addition, we have developed a Web runtime object interface containing several properties and methods for communicating with browsers. If desired, you can implement all of the properties in the object interface as attributes of the <OBJECT> tag. Advanced users may choose to instantiate their application with the <OBJECT> tag, and then write scripts with the Web runtime object interface to invoke the application. Please note that scripting the Web runtime may require changes to your end users' security settings. The <OBJECT> tag is by far the most flexible method of invoking your application with the Web runtime; therefore, it is the method that we recommend for most situations. See How Internet Explorer Security Affects the Web Runtime for more information.

  • Embed your COBOL application in the HTML document using the HTML <EMBED> tag.

    This is convenient for sites that have already used the <EMBED> element with our Web Plug-in; however, the <EMBED> tag does not offer the capability of automatically downloading the Web runtime component, and it is not strictly part of the HTML specification. If you EMBED an application on your Web page, end users who visit your site and have already installed the ACUCOBOL-GT Web Runtime immediately start executing the first embedded object code on the page.

  • Create a hyperlink to your COBOL application by placing the HTML anchor tags <A> and </A> in the HTML document.

    If you set up your object as a hyperlink (using the <ANCHOR tags>), end users who visit your Web page can run the program by clicking on the program's link. However, this method gives you the least amount of control over how your application is displayed, and it does not offer the capability of automatically downloading the Web runtime component.

  • Using the <OBJECT> Tag
  • Using the <EMBED> Tag
  • Using a Hyperlink to Launch Your Application
Parent topic: Using the ACUCOBOL-GT Web Runtime


Using the <OBJECT> Tag

When authoring Web pages to launch your application, you can use the <OBJECT> tag to invoke the Web runtime and start your program at the same time.

For example, include the following in your HTML code:

<OBJECT ID="AcuGTAX1" WIDTH=512 HEIGHT=384
CLASSID="CLSID:077C768D-64C1-4AC1-845D-4589B4B2C24E"
CODEBASE="http://www.acucorp.com/support/downloads/acugtax/acugtax800.cab#Version=8,0,0,900">
<PARAM NAME="SRC" VALUE="http://192.168.128.100/webinfo.acu">
</OBJECT>

where the following values must equal:

ID | The name of the instance of the object. This name is used for scripting the object interface. It is a user-defined value to which you refer in your script.
CLASSID The GUID (globally unique identifier) assigned to the ACUCOBOL-GT Web Runtime control, specifically this value:
077C768D-64C1-4AC1-845D-4589B4B2C24E
CODEBASE The CODEBASE URL, from which the Web runtime can be downloaded and installed automatically by end users, specifically:
http://www.acucorp.com/support/downloads/acugtax/acugtax###.cab

where ### is a 3-digit segment that identifies the cab file version. You can also append the version information that applies to the control, including a build number, by adding it as described in the next section. Although the CODEBASE attribute is optional, using it is now a common practice among software vendors to provide access to controls in this way. This allows you to distribute the control easily. If you do not use the CODEBASE attribute, you must direct users to the download page on the Acucorp Web site. Or, with a proper written license agreement, you may provide the control on your own distribution media or Intranet site.

HEIGHT | Optional. The height (in pixels) of the object's window. Use to define the area within the browser window that the application object will occupy.
WIDTH | Optional. The width (in pixels) of the object's window. Use to define the area within the browser window that the application object will occupy.
SRC | The ACUCOBOLGT application you want to run. Typically the name of the library file package with a ".acu" extension.

By default, the application appears in the browser window, using the HEIGHT and WIDTH attributes, if provided, to define the area that the application occupies.

If desired, you can add any of the properties and methods of the Web runtime object interface as parameters of the <OBJECT> tag. To do so, add PARAM NAME= followed by the property name from the object interface enclosed in quotes. You then supply the VALUE attribute.

For example, if you want to have your application appear in its own window rather than in the browser window, set the AcuEmbedded property of the object interface to "FALSE" as follows:

 <PARAM NAME="AcuEmbedded" VALUE="FALSE">

To supply runtime options or specify the name of a configuration file that was included in the library file, use the "AcuOptions" property, as shown below:

<PARAM NAME="AcuOptions"  VALUE="-d -c cblconfi">

The following options are valid for the Web runtime: -c, -d, -e, -l, -v, or -x.

The following example illustrates how you might debug your application and display it in a separate window.

<OBJECT ID="AcuGTAX1" WIDTH="512" HEIGHT="384"
CLASSID="clsid:077C768D-64C1-4AC1-845D-4589B4B2C24E"
CODEBASE="http://www.acucorp.com/support/downloads/acugtax/acugtax800.cab#Version=8,0,0,900">
<PARAM NAME="AcuEmbedded" VALUE="FALSE">
<PARAM NAME="SRC" VALUE="http://yourserver/yourdirectory/yourprogram.acu">
<PARAM NAME="AcuOptions"  VALUE="-d -c cblconfi">
</OBJECT>
Note: Since this example invokes the runtime in debug mode instantly, no scripting is necessary. In this case, "yourprogram.acu" is the name of a library.

For more information on the object interface, see Web runtime object interface.

  • How the <OBJECT> tag works
  • Version number of Web runtime
  • Web runtime object interface
  • Scripting with the object interface
Parent topic: Invoking Your COBOL Application with the Web Runtime


How the <OBJECT> tag works

The CODEBASE parameter indicates to the browser where to look for the Web runtime if it is not installed on the target system. Internet Explorer automatically offers to download and install the Web runtime, prompting most users to accept the digital signature provided by Micro Focus.

Note: If the user's security settings are high or customized to prohibit ActiveX controls, the user cannot install the Web runtime. If the user's security settings are low, the control installs without confirmation from the user.

In the HTML document, you can introduce the Web runtime with the <OBJECT> tag and then supply a script to invoke the object through either a window event or a push-button event. For information on using the object interface, refer to Web runtime object interface. However, you need not use scripting in order to invoke the control with the <OBJECT> tag.

Parent topic: Using the <OBJECT> Tag


Version number of Web runtime

The name of the CAB file identified in the CODEBASE URL is version-specific. Therefore, acugtax900.cab always contains the Version 9.0 Web runtime. However, you can implement your CODEBASE URL with a version string that refers to the version number as well as the build number.

If, for example, you deploy your Web site with the following CODEBASE value:

http://www.acucorp.com/support/downloads/acugtax/acugtax900.cab

a control associated with the specified CLASSID will be used (if found), regardless of version. If no associated control is available on the client machine, the CAB file will be downloaded, installed, and executed.

On the other hand, if your Web site contains the following value:

http://www.acucorp.com/support/downloads/acugtax/acugtax900.cab#Version=8,0,0,900

users with an earlier version of the control will automatically be prompted to download the new version the next time they visit your Web site. The convention for the Web runtime control is therefore:

acugtaxMmr.cab#Version=M,m,r,b

where M,m,r,b represent the Major, minor, release, and build numbers of the particular version of the control. This allows you to determine which version of the control is available to your end users.

To determine the version and build number of a Web runtime control, you can use the AboutBox method available in the object interface. See Web runtime object interface.

for more information. You can also obtain the version number by following these steps:

  1. Locate the file, acugtax.ocx, for the version you want to deploy.
  2. In Windows Explorer, right-click on the control and select Properties.
  3. Select the Version tab and view the value in the File Version field.
Parent topic: Using the <OBJECT> Tag


Web runtime object interface

The Web runtime's object interface consists of the following methods and properties. Some are bi-directional (B), some are write only (W), and others are read only (R). The component also has a default property (D).

Note: Using the object interface is optional. The <OBJECT> tag exposes the same properties (but not methods). The object interface is available for the advanced user who prefers scripting and wishes to use the available methods. However, please be aware that support for specific scripting languages and their implementations should be obtained from the appropriate vendor.

Methods

AcuIsActive | R
AcuExecute | R
AcuShutDownAx | R
AcuGetLastError | R
AboutBox | R

Properties

AcuParam1 | W
AcuParam2
AcuParam3 | W
AcuParam4 | W
AcuParam5 | W
AcuParam6 | W
AcuParam7 | W
AcuParam8 | W
AcuParam9 | W
AcuParam10 | W
AcuParam11 | W
AcuParam12 | W
AcuParam13 | W
AcuParam14 | W
AcuOptions | B
AcuEmbedded | B
AcuShowLogo | B
AcuProgram | B
SRC | BD

Syntax

The following sections describe the methods and properties for the Web thin client control. Each method or property name is listed, followed by the type of the input parameter. (The type is shown in parentheses.) Finally, the input value and the output value (returned value) are shown, with acceptable values indicated in square brackets "[ ]". Empty brackets indicate that the value is not limited, or takes no input.

Examples of limited values include Booleans, which can be only "True" or "False". The output of the AcuIsActive method uses this limited value.

You will notice that the syntax examples in the following sections refer to "AcuThinAX". This refers to the HTML object ID assignment of the Web thin client control given in the <OBJECT> tag. For example:

<object classid="clsid:087C768D-64C1-4AC1-845D-4589B4B2C24E"
ID="AcuThinAX" width="251" height="144">
  • AcuIsActive
  • AcuExecute
  • AcuShutdownAx
  • AcuGetLastError
  • AboutBox
  • AcuParam1 ... AcuParam14
  • AcuOptions
  • AcuEmbedded
  • AcuShowLogo
  • AcuProgram
  • SRC
Parent topic: Using the <OBJECT> Tag


AcuIsActive

Returns the status of the runtime. AcuIsActive takes no input parameters.

Parameter Type | Input | Output
( ) | [ ] | [TRUE, FALSE]

The return value is of the data type BOOL:

  • TRUE = the runtime is executing
  • FALSE = the runtime is not executing

For example:

If AcuGTAX1.AcuIsActive() = TRUE

AcuIsActive may be executed any time after the Web runtime (in this example, "AcuGTAX1") has been invoked.

Parent topic: Web runtime object interface


AcuExecute

Starts the Web runtime, using the program specified in AcuProgram, and returns the result of the action.

Note:

If you invoke your application directly using SRC as opposed to scripting, you do not need to call AcuExecute. Your application will start automatically.

The AcuExecute method takes no parameters.

Parameter Type | Input | Output
() | [ ] | [0, -4, -5, >0]

The return value is of data type LONG.

Value | Explanation
0 | Success, runtime started.
-4 | The runtime is already running.
-5 | The runtime DLL could not be found, or the runtime DLL is the wrong version.
>0 | COBOL error.

For example:

Return_value = AcuGTAX1.AcuExecute()

Do not execute this method until you have executed AcuProgram to specify the program to run; otherwise, AcuExecute does not know which program to run.

Parent topic: Web runtime object interface


AcuShutdownAx

This is an optional method that forces a shutdown of a specific Web runtime instance. For example:

AcuGTAX1.AcuShutdownAx()

shuts down the runtime instance known as "AcuGTAX1", if it is running.

AcuShutdownAx terminates the COBOL application invoked by the Web runtime. In general, you need not use it because the Web runtime either terminates as a result of the COBOL program execution, or because the browser either displays another URL or closes. If, for some reason, you want to force shutdown of the Web runtime instance, this method is available.

Parameter Type | Input | Output
() | [ ] | [ ]

The shutdown action assumes that the COBOL application is currently in idle mode. If the runtime is not idle, the browser hangs, waiting for the application to idle. This method takes no parameters, and there is no return value for this function.

AcuShutdownAx implicitly terminates the Web runtime when you terminate the COBOL application you are running. So, when you execute this method, the Web runtime is terminated, closing files properly, even though data that was not stored permanently is lost.

Parent topic: Web runtime object interface


AcuGetLastError

Returns the last known COBOL error code.

Parameter Type | Input | Output
() | [ ] | [ ]

This method takes no parameters, and the return value, which is the COBOL error code, is of data type LONG. Note that if the COBOL code could not be executed, the output is an error code indicating why the code could not execute. See AcuExecute for more information.

For example:

AcuGTAX.AcuGetLastError()

AcuGetLastError may be executed any time after the Web runtime has been invoked.

Parent topic: Web runtime object interface


AboutBox

Displays a dialog box that presents version information about the Web runtime.

Parameter Type | Input | Output
() | [ ] | [ ]

There is no return value.

For example:

AcuGTAX.AboutBox()

AboutBox may be executed any time after the Web runtime ("AcuGTAX" in this example) has been invoked.

Parent topic: Web runtime object interface


AcuParam1 ... AcuParam14

AcuParam1...AcuParam14 is a variant data item. It can hold values to be passed to the COBOL application as parameters, or you can set the data item before execution and have data returned when the program terminates.

Note that you will not get any data until the application has halted with STOP RUN, GOBACK or EXIT PROGRAM. You should call the method, AcuIsActive, before trying to access the data. When AcuIsActive returns false ("0"), the data is available, provided there is any data.

Parameter Type | Input | Output
variant | [ ] | [TRUE, FALSE]

Because this is variant, the properties accept any variant-compliant data type: numbers, float, strings, etc.

For example:

AcuGTAX.AcuParam1 = "C:\TMP"
CurrentParam = AcuGTAX.AcuParam1

These properties are available any time after the Web runtime has been invoked. The contents of each property specified are read and applied to the runtime when AcuExecute is invoked.

You can use these additional properties to specify more parameters for the COBOL application. Note that to access properties, you must use C$GETVARIANT in your COBOL program.

Here is a Visual Basic example:

' Cobol test variables
Public testNum As Variant
Public testStr As Variant
Public testLongNum As Variant
Public testfloatNum As Variant

Dim CobolApp As Object
Set CobolApp = New AcuGT

' Set up config and error files
strCommandLine = _
   "-c acuvb.cfg -dle acuerr.log"

CobolApp.Initialize strCommandLine
' Set initial values
testNum = 123
testStr = "qwertyuiopasdfghjklzxcvbnm"
testLongNum = 1234567890
testfloatNum = 23.4
Label1.Caption = testNum
Label2.Caption = testStr
Label3.Caption = testLongNum
Label4.Caption = testfloatNum
Label9.Caption = "Before Cobol Call"

returnValue = CobolApp.Call("astest", testNum, testStr, testLongNum, testfloatNum)

'Values after cobol program. This did not work before.
Label1.Caption = testNum
Label2.Caption = testStr
Label3.Caption = testLongNum
Label4.Caption = testfloatNum
Label9.Caption = "After Cobol Call"
Parent topic: Web runtime object interface


AcuOptions

Sets runtime options, such as "-d" to run the debugger or "-c configfile" to set the configuration file. The following options are valid for the Web runtime: "-c", "-d", "-l", "-e", "-x", or "-v". Note that you must have a local license file to run the debug option.

Parameter Type | Input | Output
(BSTR) | [ ] | [ ]

The AcuOptions property accepts a BSTR as a value.

For example:

AcuGTAX.AcuOptions = "-d -c cblconfi"
CurrentParam = AcuGTAX.AcuOptions

The AcuOptions property is available any time after the Web runtime has been invoked. Its contents are read and applied to the runtime when AcuExecute is invoked.

Parent topic: Web runtime object interface


AcuEmbedded

Determines whether the runtime should run in an independent window or as a frame within the document.

Parameter Type | Input | Output
(BOOL) | [TRUE, FALSE ] | [TRUE, FALSE]

The AcuEmbedded property accepts a BOOL as a value. When this property is set to "TRUE", the default, the window appears embedded in the browser document. Set it to "FALSE" when you want the window to appear independently, outside the browser.

For example:

AcuGTAX.AcuEmbedded = TRUE
if AcuGTAX.AcuEmbedded

The AcuEmbedded property is available any time after the Web runtime has been invoked. Its contents are read and applied to the runtime when AcuExecute is invoked.

Note that if you use the HEIGHT and WIDTH attributes of the <OBJECT> tag and you set AcuEmbedded to "FALSE", the Web runtime's logo screen will occupy that area on the HTML page while the application runs in its own window.

Parent topic: Web runtime object interface


AcuShowLogo

Determines whether to display the ACUCOBOL-GT Web Runtime logo when you invoke your application.

Parameter Type | Input | Output
(BOOL) | [TRUE, FALSE ] | [TRUE, FALSE]

For example:

AcuGTAX.AcuShowLogo = TRUE
if AcuGTAX.AcuShowLogo

To use this property, specify it as part of the <OBJECT> element where you invoke the application. The default is TRUE.

Parent topic: Web runtime object interface


AcuProgram

Sets the COBOL application to run. You must use the absolute path even if the COBOL application resides inside the current directory and you have not specified the directory with the AcuOptions property.

Parameter Type | Input | Output
(BSTR) | [ ] | [ ]

The security on your network may have an impact on which disks and directories an instance of the runtime is allowed to access.

The AcuProgram property accepts a BSTR as a value.

The AcuProgram property is available any time after the Web runtime has been invoked. Its contents are read and applied to the runtime when AcuExecute is invoked.

For example:

AcuGTAX.AcuProgram = "c:\tmp\myprog.acu"
CurrentProgram = AcuGTAX.AcuProgram

If you are using scripting, rather than implicit activation (with the <OBJECT> element), a call to AcuExecute() is necessary to activate the runtime.

Use AcuProgram for MS-DOS and UNC paths only, such as "c:\mydir\myprog.acu" or "\\myserver\c\mydir\myprog.acu". Use the SRC property instead for URL paths. You can use SRC or AcuProgram, but not both.

Parent topic: Web runtime object interface


SRC

Required if you are using a URL path as the default property of the Web runtime. The value of the SRC property uses HTTP notation to specify the name of the remote ACUCOBOL-GT object to load. If you are using a local file path to specify the name of the ACUCOBOL-GT object, you must use AcuProgram instead.

Parameter Type | Input | Output
(BSTR) | [ ] | [ ]

The Web runtime provides this default property, since a browser may invoke a control by associating its file extension with the MIME type. This means the browser passes the .acu file to the object as the default property, so the Web runtime knows which program to run.

You can use SRC or AcuProgram, but not both.

The following example demonstrates using the <OBJECT> element to specify the program for execution:

<OBJECT
CLASSID="CLSID:077C768D-64C1-4AC1-845D-4589B4B2C24E"
ID="AcuGTAX1" width="512" height="384">
<PARAM NAME="AcuEmbedded" VALUE="TRUE">
<PARAM NAME="SRC" VALUE="http://server.acucorp.com/location/webinfo.acu">
</OBJECT>

The SRC property is intended for HTTP URLs only. However, you may also address local files if the path is prefixed with "file://" rather than "http://", as shown below. Note that this is also considered URL notation. For example:

<OBJECT
  CLASSID="CLSID:077C768D-64C1-4AC1-845D-4589B4B2C24E"
  ID="AcuGTAX1" WIDTH="512" HEIGHT="384">
  <PARAM NAME="AcuEmbedded" VALUE="TRUE">
  <PARAM NAME="SRC" VALUE="file://c:\webdemo\webinfo.acu">
</OBJECT>

When you use the SRC property to call a file, the downloaded file is given a temporary name and is stored in the current master temporary directory for the user, as specified in Windows. Note that the runtime automatically captures the temporary name and uses it internally; however, the internal name is not exposed.

Parent topic: Web runtime object interface


Scripting with the object interface

Scripting is an optional method for invoking the Web runtime. While it is possible to invoke the Web runtime without scripting, some users may want to take advantage of the methods and properties in the object interface.

The following VB Script example illustrates how to invoke the object by a push button event using a script:

<INPUT id=button1 name=button1 type=button value=Button>
<SCRIPT LANGUAGE="VBScript">
sub button1_onclick()
   call AcuGTAX.src("http://www/Acucorp.com/demo/demo.acu")
   call AcuGTAX.AcuEmbedded(1)
   call AcuGTAX.AcuExecute()
end sub
</SCRIPT>

Only one instance of the Web runtime is allowed. You cannot have multiple instances of the runtime in one browser instance.

To script runtime options, use the AcuOptions property. For example, to implement the configuration file and error file options with VB Script, you would use:

<SCRIPT LANGUAGE="VBScript>
Sub window_onLoad()
  call AcuGTAX1.SRC("http://www.acucorp.com/demo.acu")
  call AcuGTAX1.AcuEmbedded(1)
  call AcuGTAX1.AcuOptions(" -c cblconfi –e error.txt")
  call AcuGTAX1.AcuExecute()
  end sub
</SCRIPT>
Parent topic: Using the <OBJECT> Tag


Using the <EMBED> Tag

You can use the HTML <EMBED> tag to embed your COBOL application in the HTML document. Using this tag, you define a rectangular area within your Web page that your COBOL application should use as its initial "window."

When you include a configuration file in the library, you must also specify the name of the file using the OPTIONS attribute of the <EMBED> element. This ensures that the application uses the correct configuration file rather than defaulting to another that may reside on the user's system. You can also specify runtime options using the OPTIONS keyword. The following options are valid for the Web runtime: "-c", "-d", "-e", "-l", "-v", or "-x".

For example:

<EMBED SRC="myprog.acu" WIDTH=400 HEIGHT=200
   OPTIONS="-c cblconfi -dlex myerrs">
</EMBED>

embeds "myprog.acu" on the Web page and makes it accessible using the Web runtime, with configuration file "cblconfi" and various options. In this example, "myprog.acu" could be an entire COBOL application, or it could be the initial COBOL object of a distributed application using AcuServer or AcuConnect, or it could be the name of a library file.

When a user visits this Web page, the embedded object ("myprog.acu") is automatically sent from the Web server to the client machine where it immediately starts running inside the user's browser window. Configuration variables are read from the configuration file "myconfig", and errors are written to the error file "myerrs".

While the COBOL object or library is downloading and after the COBOL program exits, the control displays a splash screen in the browser window. You can disable this feature by setting the AcuShowLogo property to FALSE.

Please note that your application is not able to display its own main window menu bar when running inside a browser window. If you choose to use this method, you must program another way for your users to access your menu functions.

When invoking the Web runtime with the <EMBED> element, you can also specify runtime options and other properties using the AcuOptions attribute of the object interface.

If, for example, you want to specify both a configuration file and error file for the Web runtime, you could use:

<EMBED SRC="myprog.acu" WIDTH=400 HEIGHT=200
   AcuOptions="-c cblconfi -e errors.txt">
</EMBED>

The following code demonstrates using the property for instant debugging with the Web runtime:

<EMBED SRC="http://server.acucorp.com/activex/
   webinfo.acu"
   HEIGHT=384 WIDTH=512 AcuOptions="-d">
</EMBED>

These examples assume that the Web runtime has been installed and registered. When you use the <EMBED> tag, the Web runtime is not automatically downloaded, as it may be when you specify the CODEBASE attribute and a valid URL with the <OBJECT> element.

Do not use the AcuProgram property when the ACUCOBOL-GT object is accessed via a URL. See Web runtime object interface for more information.

Parent topic: Invoking Your COBOL Application with the Web Runtime


Using a Hyperlink to Launch Your Application

You can use the HTML anchor tags, <A> and </A>, to create a link to your COBOL application in the HTML document.

Anchor tags are closed elements that highlight text or images. When users click a highlighted item on your Web page, they are transferred to the linked document. Because the link in this case is a COBOL program, when users click the highlighted item, the COBOL program is automatically invoked.

To run your COBOL application in a separate window using the anchor tags, you must set up the standard ACUCOBOL-GT runtime as a helper application as described in Use the Runtime as a Helper Application or Viewer. To run your COBOL application in a separate window with the Web runtime, use the <EMBED> tag, the <OBJECT> tag, or the scripting method.

To turn text into a hypertext anchor, enclose the text in the anchor tags. The browser usually displays it underlined and in a different color. For example, your HTML document may include this:

<A HREF="myprog.acu">Click here to run the application</A>

The "HREF" attribute is used within the starting anchor tag to specify the document to be linked (or retrieved). Then when the user clicks on the highlighted text, "Click here to run the application," on your Web page, the COBOL object "myprog.acu" is retrieved from the specified location on the Web server and run inside the user's browser window.

To use images as hypertext anchors, you place the <IMG> element within the Anchor tags. For example:

<A HREF="myprog.acu">
<IMG SRC="myprog.gif" ALT="Click here to run application">
</A>

Then when the user clicks on the "myprog.gif" image on your Web page, the COBOL object "myprog.acu" is retrieved from the specified location on the Web server and run inside the user's browser window. While the graphic file is loading (or if the user's browser does not support images), the browser displays the alternate text, "Click here to run the application". Clicking this text invokes the application as before.

If you use a hyperlink to invoke the Web runtime, you must also configure your Web server software to generate the appropriate response header when it sends the object files to the client. The extension ".acu" has been registered as a MIME content type that is embedded in the Web runtime. The end user's browser will execute the Web runtime only if the MIME content type field of your response header contains "application/vnd.acucobol". For this reason, be sure to add a new File Extension/MIME Content Type mapping for ".acu" and "application/vnd.acucobol". Your Web server software provides instructions for making MIME Content Type associations.

Parent topic: Invoking Your COBOL Application with the Web Runtime


Obtaining and Distributing the Web Runtime

End users must place the Web runtime on the client machine, along with all the necessary license and data files. You can obtain the Web runtime from any ACUCOBOL-GT media or download it at no cost from the Acucorp Web site, http://www.acucorp.com/support/downloads/. (It cannot be loaded from the ACUCOBOLGT runtime module.)

To make it easy for your end users to obtain the Web runtime, we have instructed you to embed the URL of the Acucorp download site to your Web page so that you can automate the download and installation process for your users. Your runtime license agreement must permit this form of distribution.

If you want, you can also distribute the Web runtime internally. If the target machine has Internet Explorer Version 5.5 Service Pack 2 or later installed, all that you need to do is copy the file "acugtax.ocx" to the preferred directory, and register it with the computer as described in the topic Manual Registration of the Web Runtime.

The capabilities of the Web runtime depend on its ability to locate a runtime license file either locally or via a server running AcuServer. If a runtime license file is found and available, the Web runtime has the capabilities of the standard ACUCOBOL-GT runtime. If a license file is not found, or if the maximum limit allowed by the runtime license provided by an AcuServer connection has been reached, the Web runtime runs in a restricted mode.

  • Licensing Considerations
  • File System Dependencies
  • Manual Registration of the Web Runtime
Parent topic: Using the ACUCOBOL-GT Web Runtime


Licensing Considerations

The ACUCOBOL-GT Web Runtime is licensed in one of two ways.

  1. With a runtime license on a server running AcuServer, licensed for the number of concurrent users anticipated.
  2. With a runtime license on a local machine or network server.
  • Licensing the server
  • Licensing by machine
Parent topic: Obtaining and Distributing the Web Runtime


Licensing the server

Most often, you install an ACUCOBOL-GT runtime license on the server running AcuServer. The license should accommodate the number of concurrent Web runtime users that you anticipate. (If you anticipate 100 concurrent users, you need a 100-user runtime license file on the server in addition to the AcuServer license file.) AcuServer detects the Web control connections and checks out a standard runtime license for each connection if a local license file is not found. When a Web runtime user disconnects from AcuServer by exiting the COBOL program, the runtime license authorization is released and made available to subsequent users. If the number of users exceeds the number of authorizations available on the server at any given time, the COBOL program receives a file status code 9D/105 and this message is output to AcuServer's error log:

You have exceeded the licensed number of clients for
AcuServer. If you would like to add clients, please
contact your customer service representative

If your COBOL program receives a status code of 9D/105, we recommend that you display a message box stating that the Web file server is busy, and to please retry later.

It is important to note that the Web runtime continues to run even when no license file is available, but in a restricted mode. In restricted mode, programs cannot use the following features:

  • Indexed files
  • Acu4GL
  • The AcuSQL™ precompiler
  • Debugging
  • Printing
  • Calling DLLs

If an end user tries to perform an activity that is not permitted, your program should present a message that explains why the activity cannot be completed. For example, if an end user tries to print something in restricted mode, your program could display a message that says A software license could not be found. XYZ Software is unable to print. Otherwise, the user might think that the printer is turned off, unplugged, or jammed. Your program should accommodate all of the limitations of a restricted runtime in some manner.

Programs running in restricted mode can use AcuConnect to call programs on a server machine that can use Acu4GL, AcuSQL, and the server's printing facilities. AcuConnect counts the number of concurrent runtimes it launches on the server. Programs running in restricted mode can also use COBOL applets, local sequential and relative files in permissible directories, C$GETURL, ActiveX, and OLE.

If you want to test from COBOL whether a Web control application is running in restricted mode, you can test the SERIAL-NUMBER field of the SYSTEM-INFORMATION item after an ACCEPT from SYS-INFO. If the SERIAL-NUMBER field is SPACES, the COBOL program is being run in restricted mode.

Parent topic: Licensing Considerations


Licensing by machine

Alternatively, users can purchase a runtime license and install the Web runtime on their local machine or network server. Upon execution, the control searches for a license file in the same directory as the executable.

The license file for the Web runtime is named "wrun32.alc." If a license file is found, the Web runtime has all the power of a standard ACUCOBOL-GT runtime. If no license file is available, the capabilities are restricted until the Web runtime tries to open a file with AcuServer. At that point, AcuServer checks for an AcuServer license file. If one is found, the OPEN succeeds, indicating that AcuServer has checked out an authorization for it. Then the control runs in unrestricted mode.

If you move the control's executable (.dll or .ocx) to a new directory, be sure to move the corresponding license file.

If you are licensed for additional extend technologies, such as Acu4GL or AcuSQL, a license file for each product the Web runtime will work with must reside in the same directory as the executable. Contact your Micro Focus extend representative for additional details.

Nothing in this section is intended to amend the terms and conditions of the applicable license agreement between you and Micro Focus. Rather, this section is meant to summarize the various aspects of our licensing technology that are required to operate the Web runtime. The terms and conditions of your licensing of extend software shall continue to be governed by the applicable license agreement between you and Micro Focus.

Parent topic: Licensing Considerations


File System Dependencies

If you use file systems such as Pervasive.SQL or an Acu4GL product, the Web runtime depends on DLLs for these file systems.

The dependencies for these file systems must be stored in the same directory as the Web runtime (acugtax.ocx ) because the system looks in the path of the control to load the additional files. However, since the installation directory of the Web runtime is determined by Windows and includes a registry entry, its dependencies can be stored in any directory. During installation, the control is registered so the operating system can locate the control and load it from that location.

Parent topic: Obtaining and Distributing the Web Runtime


Manual Registration of the Web Runtime

Registration of the ActiveX control will occur automatically during installation of your ACUCOBOL-GT development system, and for your users when they download the CAB file. As a result, there is no requirement to ever perform manual registration. However, should you need to do this as part of your development or testing, you can use the following commands.

Using the basic syntax with no options, a dialog box appears, indicating success or failure of the registration:

regsvr32 acugtax.ocx

You can omit the dialog box in silent mode by adding the "/s" parameter:

regsvr32 acugtax.ocx /s

To unregister the Web runtime, use the "/u" parameter:

regsvr32 acugtax.ocx /u

The "regsvr32.exe" utility is a Microsoft system tool and most Windows installations already contain the utility.

Parent topic: Obtaining and Distributing the Web Runtime


The User's Job

To use your application via the Web runtime, end users typically have just one task: they must visit your Web site. If the user's browser supports the Web runtime and you have implemented the CODEBASE in your HTML code, users install the Web runtime automatically the first time they visit your Web site, and the Web runtime automatically launches your application.

If your customers do not already have the ACUCOBOL-GT Web Runtime installed on their machine when they try to launch your application, they are informed that a control for the file type was not found, and they are asked if they want to install and run your program. If they respond "Yes", the runtime installs with no further user interaction and automatically launches your program. The installation script automatically makes a file type association for ACUCOBOL-GT object files (".acu" extension) with the Web runtime.

Users must configure the browser to enable "ActiveX controls ". To do this in Internet Explorer, they should check the appropriate box in the Security tab of the Internet Explorer Options dialog.

For most users installing the Web runtime, they will be prompted to accept the digital signature of the control. The system also displays the terms and conditions for using the ACUCOBOL-GT Web Runtime. Users must agree to the terms of the agreement in order to use the Web runtime.

If your application requires access to local resources or local network resources, the user has one additional task: to edit an authorization file. If you write your application in such a way that the resources are accessed remotely (using AcuConnect and AcuServer), this step is not required. See How the Authorization File Works for more information.

Parent topic: Using the ACUCOBOL-GT Web Runtime


Security

Security for the Web runtime begins with the following provisions:

  • The "acuauth.txt" file contains a list of directories where COBOL applications are authorized to create or delete files and subdirectories.
  • Calls to certain library routines are disallowed to prevent potentially damaging operations.
  • Warning messages appear the first time users launch the Web runtime.
  • We supply the Web runtime with a digital signature indicating that Micro Focus verifies the content. This enables users to run the control using a medium security setting on their Internet Explorer browser.

Since we distribute the Web runtime via the Internet, it is packaged as a signed Cabinet (CAB) file. This ensures your users that the code is safe. The CAB file contains a compressed version of the control, with information that tells Internet Explorer how to install it.

Although we have built in a number of security features, the Web runtime allows COBOL programs to be executed on target machines. Because we have no control over the programs that are executed by the Web runtime, we cannot fully guarantee that they are safe.

  • Digital Signature of Web Runtime
  • How Internet Explorer Security Affects the Web Runtime
  • Security Warning Messages
  • How the Authorization File Works
Parent topic: Using the ACUCOBOL-GT Web Runtime


Digital Signature of Web Runtime

A digital signature provides users with a way of identifying who published the software they are downloading from the Internet.

By distributing the Web runtime with a CAB file and digital signature, we ensure that most standard configurations of Microsoft Internet Explorer will accept the Web runtime application after the user responds "yes" to the Security Warning dialog when it is installed. Users who have set their browser security level to low will not see this dialog, since their browsers automatically accept digitally signed components.

Users with security levels set to high cannot run any ActiveX-based controls, regardless of the digital signature.

Because the CAB installation does depend on some Microsoft files, it contains an embedded link to the Microsoft Web site to ensure that it can obtain the proper files. If these files are needed, users are prompted to install the Microsoft files; doing so may impact the download and installation time of the control, due to the file size of some of these required files.

Parent topic: Security


How Internet Explorer Security Affects the Web Runtime

Certain security settings of Internet Explorer can affect how it handles the Web runtime. The following table outlines the security settings that could have an effect on your end users, depending on their configuration of Internet Explorer.

Security Setting Option | Low | Medium Low | Medium | High
Download signed ActiveX controls | Enable | Prompt | Prompt | Disable *
Download unsigned ActiveX controls | Prompt | Disable | Disable | Disable
Initialize and script ActiveX controls not marked as safe | Prompt | Disable | Disable | Disable
Run ActiveX controls and plug-ins | Enable | Enable | Enable | Disable*
Script ActiveX controls marked safe for scripting | Enable | Enable | Enable | Disable**
Don't prompt for client certificate | Enable | Enable | Disable | Disable
Active Scripting | Enable | Enable | Enable | Disable**

* If your users have selected "Disable" for either of these settings–either via the default High security setting or a custom setting–they cannot run the Web runtime.

**If your users have selected "Disable" for either of these settings, and they are using the scripting facilities, they cannot run the Web runtime.

Parent topic: Security


Security Warning Messages

In general, programs run with Web controls can potentially damage an end user's computer system or corrupt memory through pointers or Working-Storage tables. Therefore, to help reduce the chances of this happening, the Web runtime displays warnings to end users, asking them to accept responsibility. Based on your end users' expectations, you may need to provide instructions for handling these messages.

Web runtime warnings

Parent topic: Security


How the Authorization File Works

When a user first installs the Web runtime, the installation creates a default authorization file, "acuauth.txt", and places it in the same directory that contains "acugtax.ocx". If downloaded from our Web site, these files are installed into a hidden directory such as "Temporary Internet Files" or "Downloaded Program Files," depending on the browser configuration.

If installed from our distribution media, "acuauth.txt" and "acugtax.ocx" are placed in the "C:\Program Files\Micro Focus\Acucbl900\AcuGT\bin\" directory.

By default, the "acuauth.txt" file contains one line that specifies a list of directories where COBOL programs may create or delete files and subdirectories. The directories are specified as a sequence of pathnames delimited by quotation marks. The purpose of this file is to allow applications that create local temporary files to work immediately.

If you install the Web runtime as part of the ACUCOBOL-GT Development System, "acuauth.txt" contains only the following line:

"C:\Program Files\Micro Focus\controldir\plgndata"

where controldir is the directory that contains "acugtax.ocx".

If a COBOL application requires access to other directories or disks on the user's machine, you must instruct your end users to add those directories to the "acuauth.txt" file manually. In this way, end users can accept responsibility for specifying which directories on the client machine may be made accessible to Web runtime applications.

You cannot change this file programmatically.

We recommend designing your application so that this is not necessary. Using AcuServer and/or AcuConnect, you can design your application to utilize remote application and data resources.

However, if you do need access to the client machine, you might want to use messages to help users manage the file. For example, if an application receives file status "37,07" (access denied) when trying to open a file on the local machine, the program can display a message that indicates the problem and instructs the user to add the directory name to the file.

You can also instruct users to add other information to the file, for example, to access restricted library routines. See Using the authorization file for access for more information.

Once the file is edited, applications executed by the Web controls are allowed to read and write data in these directories, as well as create and delete subdirectories. No other area of the user's local or network file system will be accessible to the COBOL programs executed by the Web controls. This provides some measure of protection for the end user's machine and network.

If the "acuauth.txt" file is empty or missing when the Web runtime is invoked, the COBOL application is denied access to the local machine's file system.

  • FILE_PREFIX override
  • Editing the authorization file
  • Restricted library routines
  • Using the authorization file for access
Parent topic: Security


FILE_PREFIX override

FILE_PREFIX is initially set to the list of directories specified in the "acuauth.txt" file. If you define an alternate FILE_PREFIX in the configuration file that you embed with your object library, that value overrides the "acuauth.txt" setting. The COBOL program may use ACCEPT FROM ENVIRONMENT to get the initial value of FILE_PREFIX and add to it or reset it. APPLY_FILE_PATH may come in handy for existing programs. The override is generally useful only if you set FILE_PREFIX with remote name notation for use with AcuServer. If you specify local directories in FILE_PREFIX, please note that your program will have permission to access these directories only if users add them to the "acuauth.txt" file on their machines. If the files being accessed are indexed files, the Web runtime must first obtain a valid license, which may be either located on the client or obtained by AcuServer.

Parent topic: How the Authorization File Works


Editing the authorization file

If your COBOL application requires access to other directories or disks on a user's machine, the user must add those directories to the "acuauth.txt" file. For example, if the application requires access to the client directory, "c:\myfiles", the user would add "c:\myfiles" to the end of the first line in the "acuauth.txt" file as follows:

"C:\Program Files\Acucorp\Acucblxx\acugt\plgndata" "c:\myfiles"

All directories must be included on a single line, separated by spaces. If a directory name includes embedded spaces, you must enclose it in quotation marks. You may always use quotation marks if you choose. Up to 4096 characters can be included on the line.

Note that all files and folders of the directories listed in this file become accessible.

Parent topic: How the Authorization File Works


Restricted library routines

By default, COBOL programs that are run via the Web runtime are not allowed to call the following library routines:

  • C$CHAIN
  • C$MEMCPY
  • C$RUN
  • C$SYSTEM
  • M$ALLOC
  • M$FREE
  • M$GET
  • M$PUT
  • REG-CREATE-KEY
  • REG-CREATE-KEY-EX
  • REG-DELETE-KEY
  • REG-DELETE-VALUE
  • REG-SET-VALUE
  • REG-SET-VALUE-EX
  • SYSTEM

Calling any of these routines results in a failure. If the CALL statement has no EXCEPTION phrase, the Web control displays the message "call_name: Access denied", where "call_name" is the name of the library routine and where "call_name" terminates the COBOL program. C$CALLERR returns error code 23 if access was denied for the previous CALL.

Parent topic: How the Authorization File Works


Using the authorization file for access

If you want to allow programs executed by the Web runtime to call a library routine that is normally disallowed, you should instruct your users to add a line to the "acuauth.txt" file containing the name of the routine. In addition, if you want to allow programs executed by the Web control to call DLLs, instruct your users to add a separate line containing the word "DLL".

Parent topic: How the Authorization File Works


Troubleshooting

This section describes messages that users may encounter when installing or using the Web runtime.

  • Access denied.
  • Blank screen on install.
  • Error Locating Object Handler...
Parent topic: Using the ACUCOBOL-GT Web Runtime


Access denied.

If the "acuauth.txt" file is empty or missing from the client machine when the Web control is invoked, the COBOL application is denied access to the local machine's file system. The user should edit or create an "acuauth.txt" file that contains the names of all required directories.

Parent topic: Troubleshooting


Blank screen on install.

If users receive a blank screen from Microsoft Internet Explorer when they try to use a Web control, they may not have all the necessary DLLs copied into the appropriate directory. Users should place a copy of "wrun32.dll" and "acme.dll" in the directory that contains the control, along with the license file and "ajpg32.dll", and then try to run the install again. These files are part of the CAB file distribution.

Another possible cause of blank screens is a misspelling of the WIDTH or HEIGHT attributes in an EMBED statement. This results in a silent failure, where the misspelled attribute is set to zero.

Parent topic: Troubleshooting


Error Locating Object Handler...

Internet Explorer users receive this message if the required file, "acme.dll", is missing from the directory that contains the Web runtime control. Users should place a copy of "acme.dll", the executable ("acugtax.ocx"), the license file, and "ajpg32.dll" in the Web runtime directory, and then try to use the Web runtime again. These files can be found in the AcuGT\bin directory on the ACUCOBOL-GT distribution media, and they are part of the CAB file distribution. You can get more information using the Web runtime AcuGetLastError method.

Parent topic: Troubleshooting


Migrating from the Web Plug-in to the Web Runtime

If you have already implemented the Web Plug-in control to provide Web access to your ACUCOBOL-GT application, read this section for information on how to upgrade your implementation to the Web runtime. You can add the appropriate HTML code to make the new Web runtime available to your users.

The major task is to invoke the Web runtime component from your HTML page. If you are distributing the Web runtime internally to users with no Internet access, you may need to supply it on your own media.

Although it is possible to invoke your application with the <EMBED> and <ANCHOR> tags as you have for the plug-in, we recommend that you invoke it with the <OBJECT> tag and the component's CLASSID. For more information, see Using the OBJECT Tag.

  • Changing your HTML code
Parent topic: Using the ACUCOBOL-GT Web Runtime


Changing your HTML code

To add the Web runtime to your current implementation, the minimal steps you need to take are:

  1. Create the <OBJECT> tag in your HTML documents to invoke the Web runtime (acugtax.ocx) control.
  2. Remove the <EMBED> or <ANCHOR> tag currently used to launch the Web Plug-in. Provided you add the <OBJECT> element to your Web page and include the CODEBASE attribute, your users will automatically download the Web runtime the next time they visit the Web page.

Adding the <OBJECT> element there causes the user to install the Web runtime component. If your users can invoke the application from more than one Web page, you need to revise all the pages to use the <OBJECT> element.

Parent topic: Migrating from the Web Plug-in to the Web Runtime


Other Internet Solutions

  • LAN, WAN, or Internet
  • Accessing Vision Data Over the Internet
  • Accessing COBOL Programs Over the Internet
  • Accessing Vision Data from ODBC Applications
  • Accessing Relational Data Over the Internet
  • Accessing XML Data Over the Internet
Parent topic: A Programmer’s Guide to the Internet Version 10.2.0


LAN, WAN, or Internet

Because the Internet is a large TCP/IP network, you can design an Internet configuration using any of our networking or data access technologies. The Web runtime and CGI technologies were designed for communicating with Web browsers, but you can use our standard technologies to access applications and data across the Internet outside of the World Wide Web.

  • Our AcuServer® remote file server can provide access to Vision data over the Internet.
  • Our AcuConnect® remote application server can provide access to server-resident COBOL programs over the Internet, even programs that are distributed across a number of different servers.
  • Our AcuXDBC™ interface can give users of ODBC and JDBC applications access to Vision data over the Internet. AcuXDBC is combined with AcuXDBC Server for remote processing of SQL requests.
  • Our Acu4GL® interface and AcuSQL® precompiler can provide access to relational databases over the Internet.
  • Our AcuXML interface or C$XML library routine can be used to provide access to XML documents over the Internet.

The procedures for using these technologies on the Internet are not much different from the procedures outlined in the product user's guides for local- and wide-area networks (LANs and WANs). Special Internet considerations are discussed in this chapter.

Please note that when accessing extend products on remote servers via the Internet or a virtual private network, products or technologies from third-party vendors such as Microsoft may be invoked. Carefully review any license agreements from these third-party vendors before proceeding with the remote connection.

Parent topic: Other Internet Solutions


Accessing Vision Data Over the Internet

AcuServer provides access to remote data and object files. Sites may choose to place files on a remote server because, for example, many users must access the files or the files may be updated frequently.

With AcuServer, ACUCOBOL-GT® programs on client machines have access to data and/or object files that are stored on remote servers and connected via TCP/IP. When the clients request data in a file system that resides somewhere in a network, AcuServer serves that request transparently, regardless of the client or server operating system.

A simple AcuServer environment looks something like this.

As you can see from the illustration, the configuration is essentially the same whether you are using TCP/IP on a local- or wide-area network or using the Internet. This means that you can run your ACUCOBOL-GT application as usual on a Windows or UNIX client, store your data on a remote server, and access it over the Internet. AcuServer can give your users access to your Vision, relative, or sequential data and object files over the Internet as well as over a smaller network.

Using AcuServer is an easy way to take advantage of the Internet. In many cases, no reprogramming is required. You can indicate the location of the remote server through a runtime configuration variable. Your users do not require a Web browser to access remote data files.

  • Internet Considerations for AcuServer
Parent topic: Other Internet Solutions


Internet Considerations for AcuServer

Although Internet implementations of AcuServer are configured the same as LAN or WAN configurations, there are some special considerations for providing remote file access over the Internet. For instance, how do you point to remote files over the Internet, and how do you keep your data files secure in this environment? This section provides the answers.

Note that end users must have a live Internet connection when they run the program that accesses AcuServer over the Internet. In addition, the server name in the client configuration file must be resolvable by the Internet name server used by their service provider. The Internet name server then resolves the name with its IP address. If the server name is not exposed to Internet name servers, you can enter the explicit IP address in the runtime configuration file on the client.

If the server is through a Virtual Private Network (VPN), the user must connect to the network before running the COBOL program.

For general information on setting up and using AcuServer, please see the AcuServer User's Guide.

  • Defining Internet pathnames
  • Security and AcuServer
Parent topic: Accessing Vision Data Over the Internet


Defining Internet pathnames

In both standard client/server and Internet configurations, enabling your applications to use AcuServer requires that your applications refer to remote files with remote name notation.

The easiest way to enable your applications to use AcuServer is to update the FILE_PREFIX and CODE_PREFIX runtime configuration variables to include paths with remote name notation. This holds true whether the remote path is a standard remote server address or an Internet address.

To add a remote search path, you simply append or insert the name and path of the remote directory to the variable's definition. For Internet configurations, you include the domain name of the AcuServer server that users are accessing over the Internet. For example, if the name of the server is "condor," you could define the configuration variables as follows:

FILE_PREFIX   @condor.XYZCorp.com:/usr/data
CODE_PREFIX   @condor.XYZCorp.com:/usr/objects

Of course, you could define "condor" as an alias for condor.XYZCorp.com, and simplify the remote name notation in these variables to "@condor:/usr/data" and "@condor:/usr/objects". This would not include the port number, but the port number is not always required.

If you want to enter the explicit IP address of the server, you may do so as shown in the following example:

FILE_PREFIX @128.110.121.42:/usr/data
CODE_PREFIX @128.110.121.42:/usr/objects

Alternatively, for highest performance, you can map the Vision filename directly to the Internet pathname by defining a file name alias in your runtime configuration file. A file name alias is a substitute string for the literal name that appears in the ASSIGN TO clause of a SELECT statement. Defining the alias shown below allows you to bypass FILE-PREFIX for "customer.dat":

CUSTOMER @condor.XYZCorp.com:/usr/data/customer.dat

By not requiring the runtime to connect to the server to see whether a file exists, you can open the file more quickly. For information on using name aliases, see Using Name Aliases.

Parent topic: Internet Considerations for AcuServer


Security and AcuServer

If you use AcuServer to give users access to data over the Internet, you will want to provide security measures to ensure that your data is safe from corruption or unauthorized access.

Setting up a firewall limits access to your data and enforces your organization's access control policy. When you set up a firewall, you'll need to indicate the "port number" through which applications gain access to your data. The default port number for AcuServer is 6523. You can indicate this setting through the ACUSERVER_PORT configuration variable.

Another way to secure your data is to encrypt it within your application before it is sent to AcuServer. Encryption provides an extra layer of security over and above the firewall your organization employs. Encryption is enabled with two configuration variables: ENCRYPTION_SEED and AGS_SOCKET_ENCRYPT.

AcuServer can also provide built-in password protection for access to files on the server. It provides a great deal of flexibility in assigning access permissions and password validation based on the client machine name, user name, or both. ACUCOBOL-GT runtimes provide built-in password-handling routines, or you can create your own password handling in your COBOL code using the Acu-Client-Password external variable.

In addition, AcuServer uses a security file called AcuAccess to support a wide range of access privileges, from very open to very restrictive. You choose the level of security best suited to your needs. The AcuAccess file is an encrypted Vision file. It contains one or more access records defining which users of which clients are permitted access to AcuServer. AcuAccess lets you specify individual user IDs that give users exactly the privileges they need, and no more.

Parent topic: Internet Considerations for AcuServer


Accessing COBOL Programs Over the Internet

If you want users to be able to launch remote applications from their local machine, you can use our remote application server, AcuConnect, to accomplish your goal. Reasons for this may be that the application itself is revised frequently or the application is processing-intensive.

With AcuConnect, users or programs on client machines can launch applications on server machines, whether those servers are part of a local area network, wide area network, or global Internet. Some portions of your application can continue to run on the client while the resource-intensive portions run on the server, or all but the user interface can run on the server, in a thin client configuration.

In Using the Thin Client to Launch Web Applications, we described how to launch a thin client from a Web page or over the Internet from the command line. But you can also use AcuConnect with the standard ACUCOBOL-GT runtime to distribute your application resources between the client and one or more servers on the Internet. Exactly how much processing is performed on the client and how much on the server is up to you.

AcuConnect also provides users access to remote Vision data. If the data is on the same remote server as AcuConnect, data is considered local and no special software is required. If the data is on a third data server, AcuConnect can work in tandem with AcuServer to provide seamless data access. AcuConnect can also work with Acu4GL, our COBOL-to-RDBMS bridge, to provide access to relational data wherever it resides.

The following figures show AcuConnect in two-tier and three-tier environments. In a two-tier environment, applications and data are stored on the same remote server as follows:

AcuConnect in a two-tier environment

In a three-tier configuration, the data files reside on a different server than the application. Sites may do this for security purposes or because this may make for more efficient use of system resources. When the applications and data are on different servers, the data files are considered remote, and AcuServer is required.

AcuConnect in a three-tier environment

Consider using AcuConnect when your program is I/O-intensive or if you have reason to believe that the program will be updated frequently. You can determine how much reprogramming you want to do to facilitate remote application access for your users – either by embedding COBOL calls into your program or dividing it into client and server components. Your users do not require a Web browser for remote application access.

  • Internet Considerations for AcuConnect
Parent topic: Other Internet Solutions


Internet Considerations for AcuConnect

Although Internet implementations of AcuConnect are configured the same as LAN or WAN configurations, there are special considerations for providing application and data access on the Internet: primarily, how you define the Internet application path and how you keep your applications and data secure in this environment. This section provides the answers.

Note that end users must have a live Internet connection when they run the program that accesses AcuConnect over the Internet. In addition, the server name in the client configuration file must be resolvable by the Internet name server used by their service provider. The Internet name server then resolves the name with its IP address. If the server name is not exposed to Internet name servers, you can enter the explicit IP address when configuring the client runtime.

If the server is accessed through a Virtual Private Network (VPN), the user must connect to the network before running the client program.

For general information on setting up and using AcuConnect, please see the AcuConnect User's Guide. For information on using the thin client or Web thin client on the Internet, see Using the Thin Client to Launch Web Applications.

  • Defining an Internet application path
  • Security and AcuConnect
Parent topic: Accessing COBOL Programs Over the Internet


Defining an Internet application path

With AcuConnect, you define the pathname of your remote COBOL objects in a configuration file on the client. (This configuration file must be associated with the initial COBOL object.) In this file, you use the CODE_PREFIX variable to define the location of the object programs being CALLed.

In an Internet environment, the CODE_PREFIX variable should include the domain name of the AcuConnect server being accessed over the Internet. For example:

CODE_PREFIX *condor.XYZCorp.com:/usr/prog2

where prog2 is the directory containing the ACUCOBOLGT object code, and "condor" is the name of the application server running AcuConnect. If you define "condor" as an alias for condor.XYZCorp.com, you could simplify the remote pathname to "*condor:/usr/prog2". This would not include the port number, but the port number is not always required.

If you want to enter the explicit IP address of the server, you may do so as in the following example:

CODE_PREFIX *128.110.121.42:/usr/prog2

Notice that the name of the server is preceded by the asterisk character, "*". The asterisk indicates that the program is located on the server and that it should be run on the server as well. If you want the program to run on the client, you can simply change the "*" to "@". This emulates AcuServer notation.

When the client program executes a CALL, it determines which directory contains the program by looking in CODE_PREFIX, and then it executes the program on either the client or server as specified.

Parent topic: Internet Considerations for AcuConnect


Security and AcuConnect

If you use AcuConnect to grant application access, you'll want to take the proper security measures to prevent unauthorized access.

One way to do this is with a firewall. When you set up a firewall, you'll need to indicate the "port number" through which clients gain access to the application on the server. The default port number for AcuConnect is 5632. You can indicate this setting through the ACURCL_PORT configuration variable.

In addition, AcuConnect uses a security file called AcuAccess to support a wide range of access privileges, from very open to very restrictive. You choose the level of security best suited to your needs. The AcuAccess file is an encrypted Vision file. It contains one or more access records defining which users of which clients are permitted access to AcuConnect. AcuAccess lets you specify individual user IDs that give users exactly the privileges they need, and no more.

Every access record can include a password entry that the application or user must match before AcuConnect establishes a connection.

Parent topic: Internet Considerations for AcuConnect


Accessing Vision Data from ODBC Applications

AcuXDBC can be configured to give users of popular Windows applications access to Vision data over the Internet. With AcuXDBC, you can retrieve and update ACUCOBOL-GT® indexed or relative data files from many Windows-based applications, including Microsoft Word, Excel, Access, Query, and Crystal Reports. These applications can access your files whether they reside on the same Windows PC, on a different computer in an enterprise network, or on a UNIX or Windows server in a LAN, WAN, or Internet configuration.

To gain access to remote Vision files over the Internet, you must have AcuXDBC Server installed on the server.

With AcuXDBC Server, the SQL query is processed on the server and just the result is returned to the client. This reduces network traffic and often leads to performance gains.

AcuXDBC w/AcuXDBC Server configuration, for remote SQL processing

  • Internet Considerations for AcuXDBC
Parent topic: Other Internet Solutions


Internet Considerations for AcuXDBC

Although Internet implementations of AcuXDBC are configured the same as LAN or WAN configurations, there are some special considerations for accessing data over the Internet. For instance, how do you point to remote files over the Internet, and how do you keep your data files secure in this environment? This section provides the answers.

Note that end users must have a live Internet connection when they try to import Vision data into their applications from the Internet. In addition, the server name indicated in the AcuXDBC configuration manager (described below) must be resolvable by the Internet name server used by their service provider. The Internet name server then resolves the name with its IP address. If the server name is not exposed to Internet name servers, you can enter the explicit IP address when setting up the AcuXDBC configuration.

If the server is through a Virtual Private Network (VPN), the user must connect to the network before running the COBOL program.

For general information on setting up and using AcuXDBC, please see the AcuXDBC User's Guide.

  • Defining Internet pathnames: AcuXDBC Server configuration
  • Security and AcuXDBC
Parent topic: Accessing Vision Data from ODBC Applications


Defining Internet pathnames: AcuXDBC Server configuration

In an AcuXDBC Server configuration, where data is both accessed and processed remotely, you define the location of the server using the AcuXDBC configuration manager on the client machine, and then you define the data pathname when you set up the DSN on the server.

On the client machine, you define only the Data Source Name field, the name or IP address of the remote AcuXDBC Server host, and the port number on the General tab of the AcuXDBC DSN Setup screen. For Internet configurations, you might enter the following Host Name:

condor.XYZCorp.com

or IP Address:

128.110.121.42
Parent topic: Internet Considerations for AcuXDBC


Security and AcuXDBC

If you decide to use AcuXDBC to give users access to data over the Internet, you will want to provide security measures to ensure that your data is safe from corruption or unauthorized access.

Setting up a firewall limits access to your data and enforces your organization's access control policy. When you set up a firewall, you'll need to indicate the "port number" through which applications gain access to your data. To define the port number for AcuXDBC Server, use the dialog box. The default port number for AcuXDBC Server is 20222.

Another way to secure your data is to encrypt it within your application before it is sent to AcuXDBC Server. Encryption provides an extra layer of security over and above the firewall your organization employs.

AcuXDBC Server uses typical relational database table permissions using the GRANT SQL syntax.

Parent topic: Internet Considerations for AcuXDBC


Accessing Relational Data Over the Internet

If you want users of ACUCOBOL-GT programs to access a relational database over the Internet, you can do so using our Acu4GL or AcuSQL technologies.

Acu4GL is a COBOL-to-RDBMS interface that automatically translates COBOL file I/O into database-specific SQL requests and vice versa. You do not need to know SQL to use this technology, because the translation occurs "behind the scenes" using a data dictionary map that is created at compile time. Typically, you don't even need to change your source code. With Acu4GL, COBOL users gain transparent access to RDBMS data in any TCP/IP network.

Acu4GL on the Internet

AcuSQL is an embedded SQL (ESQL) precompiler that lets you embed database-specific SQL directly into your ACUCOBOL-GT program. You control the precise fourth generation Structured Query Language commands that are sent to the database, and the precompiler automatically translates the SQL into COBOL CALL statements that your program understands. Compiled again with the ACUCOBOL-GT compiler, your COBOL code is ready to access relational data wherever it resides.

AcuSQL in Internet environments

Each of these technologies gives users of ACUCOBOL-GT applications access to information stored in Relational Database Management Systems (RDBMS) such as Oracle, Informix, Sybase, and Microsoft SQL Server as well as ODBC-compliant data sources. The data can be stored on the same machine as the ACUCOBOL-GT application, or on a different machine in a TCP/IP network, including the Internet.

  • Internet Considerations for Acu4GL and AcuSQL
Parent topic: Other Internet Solutions


Internet Considerations for Acu4GL and AcuSQL

With relational database systems, the database manages remote connections. Therefore, when working with an RDBMS, you perform all remote path definition, including Internet path definition, using the database client software–for instance, the Oracle client or DB2 Connect client.

Please refer to your database guide for instructions on how to configure the client software for Internet environments. Pay close attention to database security features when providing data access across the Internet.

Refer to the Acu4GL User's Guide or the AcuSQL User's Guide for instructions on using these database technologies.

Parent topic: Accessing Relational Data Over the Internet


Accessing XML Data Over the Internet

There are two ways to access XML data from ACUCOBOL-GT:

  1. Via the C$XML library routine, which gives you low-level control over the XML data that is parsed.
  2. Via AcuXML, which provides a transparent file system interface between ACUCOBOL-GT applications and XML documents.

With either method, an ACUCOBOL-GT program can read whatever XML files a user indicates, and/or output data in XML format. It doesn't matter whether the data is in a LAN, WAN, or Internet configuration. Both methods support Internet notation for remote filenames.

Accessing XML data on the Internet

Although AcuServer can be used to provide remote file access to XML documents, it is not required. ACUCOBOL-GT applications can process XML streams directly on socket connections.

For more information on using AcuXML, see ACUCOBOL-GT User's Guide. For information on using the C$XML library routine, see C$XML.

  • Internet Considerations for AcuXML and C$XML
Parent topic: Other Internet Solutions


Internet Considerations for AcuXML and C$XML

Both AcuXML and C$XML make use of Internet notation to provide direct access to XML data on the Internet. The procedures for using Internet notation are provided in the next sections.

If you prefer to use AcuServer to access the XML files over the Internet, you can combine it with AcuXML or C$XML. In this case, you include the domain name of the file server in the FILE_PREFIX variable, but you are required to have AcuServer installed on the machine hosting the XML files. The procedure for using AcuServer is also provided below.

Whichever method you choose, make sure that the server name that you specify is resolvable by the Internet name server that will be used. Of course, end users must have a live connection to the Internet or VPN to make use of the remote files.

  • Using Internet notation with C$XML
  • Using Internet notation with AcuXML
  • Using AcuServer with AcuXML or C$XML
  • Security and XML
Parent topic: Accessing XML Data Over the Internet


Using Internet notation with C$XML

To parse an XML file with the C$XML routine, you call C$XML using the CXML-PARSE-FILE op-code, and pass the filename and path of the XML document to parse. If the document is located on the Internet, you pass the filename with URL syntax. For example:

CALL "C$XML" using CXML-PARSE-FILE, "http://myserver.mycomp.com/xmldata/bookfile.xml"

For more information on using this routine, see C$XML.

Parent topic: Internet Considerations for AcuXML and C$XML


Using Internet notation with AcuXML

With AcuXML, the file path is specified in the runtime configuration file, "cblconfig."

To read a file from the Internet, you set up a filename alias in the runtime configuration file, and use Internet notation to map the data files directly to a URL. For example, to read "bookfile.xml" over the Internet, you might define a name alias for "bookfile" in your configuration file like this:

BOOKFILE  http://myserver.mycomp.com/xmldata/bookfile.xml

Whenever your application refers to "bookfile" in a SELECT statement, the alias "http://myserver.mycomp.com/xmldata/bookfile.xml" is substituted.

To specify that "bookfile" should be treated as XML data for translation by AcuXML, you must also set the filename_HOST variable to "XML" as follows:

BOOKFILE_HOST XML

With AcuXML, you include a separate entry for each XML document name.

For more information on setting up file aliases, see File Name Assignments.

Parent topic: Internet Considerations for AcuXML and C$XML


Using AcuServer with AcuXML or C$XML

To access remote XML files using AcuServer, you use the FILE_PREFIX configuration variable to define the location of the remote files. You simply append or insert the name and path of the remote directory to the variable's definition.

For Internet configurations, you include the domain name of the server that users are accessing over the Internet. (The remote server that contains the XML documents must be running AcuServer.) For example, if the name of the server is "condor," you could define the configuration variables as follows:

FILE_PREFIX   @condor.XYZCorp.com:/usr/data

Of course, you could define "condor" as an alias for condor.XYZCorp.com, and simplify the remote name notation in this variable to "@condor:/usr/data". Or if you want to enter the explicit IP address of the server, you may do so as in the following example:

FILE_PREFIX @128.110.121.42:/usr/data

If you are using AcuServer with AcuXML, you must use the filename_HOST variable to designate the data files as XML files, as in the following example:

file1-HOST XML
file2-HOST XML
file3-HOST XML

This lets the ACUCOBOL-GT runtime know to use the AcuXML file interface to translate the XML input for the COBOL application.

Parent topic: Internet Considerations for AcuXML and C$XML


Security and XML

If you decide to use AcuXML or C$XML to give users access to XML data over the Internet, you will want to provide security measures to ensure that your data is safe from corruption or unauthorized access. If you are using AcuServer, you can take advantage of AcuServer's access privileges and password protection to aid in the process. See the AcuServer User's Guide for more information.

Parent topic: Internet Considerations for AcuXML and C$XML


Appendix A. Adding Internet Features to Your Program

  • WEB-BROWSER Control
Parent topic: A Programmer’s Guide to the Internet Version 10.2.0


WEB-BROWSER Control

The ACUCOBOL-GT® Development System includes an Internet-related graphical control called WEB-BROWSER. This control broadens the usefulness and scope of your COBOL programs by giving them all of the capabilities of Microsoft Internet Explorer's Web browser control Version 4.0 and later (this control is designed for Windows users only). For instance, the WEB-BROWSER control lets you:

  • Facilitate seamless Web browsing from your COBOL application.
  • Display Web pages containing HTML, scripting, ActiveX controls and Java applet content.
  • Display HTML pages distributed with your COBOL application.
  • Include a variety of graphical and multimedia file types in your COBOL application.
  • Invoke e-mail, telnet, and FTP services from your COBOL application.
  • Display word processing, accounting, or presentation documents from your COBOL application.
  • Display Windows objects such as folders and files from your COBOL application.
  • Display Windows dialog boxes such as "Print," "Print Preview," and "Page Setup," allowing users to print the contents delivered by the control.
  • Display the Windows "Save As" dialog box allowing the user to save the current control content to a file.
  • Perform "Select All" and "Copy" clipboard operations.

ACUCOBOL-GT's WEB-BROWSER control is used just as any other graphical control in ACUCOBOL-GT is used, except that it opens a resource such as an HTML page, graphical image, video, audio, e-mail program, file folder or any other resource that a Web browser can open. When you include the WEB-BROWSER control in your source code, your application launches Microsoft Internet Explorer (MS IE) on your user's machine and displays the resource you specified.

For the control to work, your users must have Microsoft Internet Explorer Version 4.0 or later on their machine.

You specify the resource using standard URL naming conventions with any protocol that Internet Explorer recognizes, such as http:, ftp:, mailto:, file:, or javascript:.

For example to display our Web page on the user's machine, you might create a WEB-BROWSER control identified by the name BROWSER-1, then add the following lines to a Screen Section item:

03  BROWSER-1 WEB-BROWSER, VALUE "www.acucorp.com"
    COLUMN 5, LINE 5, SIZE 60, LINES 20.

or add the following Procedure Division code:

DISPLAY WEB-BROWSER, VALUE "www.acucorp.com"
 COLUMN 5, LINE 5, SIZE 60, LINES 20.

You can then close the screen, close the window, or destroy the control as you would destroy any other ACUCOBOL-GT control.

The VALUE of the WEB-BROWSER control determines which resource to display. Therefore, if you include:

DISPLAY WEB-BROWSER, VALUE "mailto:info@acucorp.com".

your application launches your user's default e-mail program and creates a new message with the "To:" field prefilled. This allows your user to quickly compose and mail a message to the specified address.

The default settings used by Internet Explorer when it performs these Web browser functions (such as the "home page," security options, e-mail program) are included in the user's control panel under the Internet option. Users who want to alter the behavior of the browser controls should modify their control panel Internet settings.

As with any ACUCOBOL-GT control, you can add the WEB-BROWSER control to user interface screens using the AcuBench® Screen Designer. The control can be found on the screen design control palette along with the other controls. Click the control, fill in its value clause, and the Screen Painter will show you what the screen will look like to the user.

Your WEB-BROWSER control can be as simple or involved as you like. In its simplest form, the WEB-BROWSER control is activated in a single DISPLAY statement. If desired, you can specify the size and color of the resulting browser window; you can activate the browser control's back, forward, home, and search buttons; or you can capture events such as download progress, status bar text changes or resource title change so you can communicate them to your user.

For information on the methods, properties, events, and event properties of the WEB-BROWSER control, see User Interface Programming.

  • Adding Web Browsing to Your COBOL Applications
  • Displaying HTML Pages Distributed With Your Application
  • Including Graphical and Multimedia Files in Your Applications
  • Invoking e-mail, Telnet, and FTP Services from Your Applications
  • Displaying Word Processing, Accounting, or Presentation Documents from Your Applications
  • Displaying Windows Objects Such as Folders and Files
  • Performing Print, File, and Clipboard Operations
  • Sample Web Browser Program
Parent topic: Appendix A. Adding Internet Features to Your Program


Adding Web Browsing to Your COBOL Applications

To add Web browsing to your COBOL applications, you include the Web address (or URL) in the VALUE clause of the DISPLAY WEB-BROWSER statement. For example:

display web-browser, value "www.microfocus.com"
   column 5, line 5, size 60, lines 20.

Using this method, your COBOL program can display Web pages containing HTML, scripting, ActiveX controls, Java applet content and more.

Alternatively, your COBOL program can send Internet Explorer to the user's predefined home page (the one defined in the user's control panel, Internet Properties setting). To do this, you use the GO-HOME feature of the WEB-BROWSER control, as in:

display web-browser, go-home = 1

Or, if you want to enable your users to search the Web, you can send the browser to Microsoft's Web portal site using the GO-SEARCH feature, as in:

display web-browser, go-search = 1

If desired, you can dynamically change the browser's location using the MODIFY verb. For instance, if your program displays a combo-box offering many different URL choices, you may need to MODIFY the location of the browser based on a user response (mouse click).

Modify web-browser, value  "www.cobol.com"
Parent topic: WEB-BROWSER Control


Displaying HTML Pages Distributed With Your Application

To display HTML pages distributed with your application, you include the HTML filename in the VALUE clause of the DISPLAY WEB-BROWSER statement. For example:

display web-browser, value "myfile.htm".

This opens and displays the file "myfile.htm" inside the WEB-BROWSER control.

Using this method, you can display an HTML forms-based front end for your application. To pass user input values from the HTML form to your COBOL application, you must write a CGI program as described in Writing a CGI Program. Then the HTML program can interact with the CGI program on the Web server, and the CGI program can interact with your COBOL code.

If you want the <Enter> key to be active on an HTML page, add the USE-RETURN style to the WEB-BROWSER control. This permits users to press <Enter> after filling out a form to submit the form. If you do not add the USE-RETURN style, pressing the <Enter> key will normally terminate input (e.g., generate a button-pushed event for the default push-button).

Parent topic: WEB-BROWSER Control


Including Graphical and Multimedia Files in Your Applications

Using the WEB-BROWSER control, you can include many types of files in your COBOL applications, including those with compressed graphical formats, compressed sound formats, movie-file formats, animated GIF formats, PDF formats, and more.

To include a graphical or multimedia file in your program, you include the filename in the VALUE clause of the DISPLAY WEB-BROWSER statement. For example:

display web-browser, value "movie1.avi".

This example would launch the user's default movie viewer and play the movie on the user's screen.

Parent topic: WEB-BROWSER Control


Invoking e-mail, Telnet, and FTP Services from Your Applications

To invoke e-mail, telnet, or FTP services from your COBOL application, you include a standard mailto, telnet, or FTP path in the VALUE clause of the DISPLAY WEB-BROWSER statement. For example, to open the user's default e-mail program and create a new message addressed to "info@acucorp.com", you would include:

display web-browser, value "mailto:info@acucorp.com".

To open the login screen to a server called "sun" over telnet, you would include:

display web-browser, value "telnet://sun".

If desired, you can even use this interface to log on to a UNIX system from your Windows environment.

To go to the FTP site "ftp://ftp.acucorp.com", you would include:

display web-browser, value "ftp.acucorp.com".

This opens a directory view of Acucorp's FTP server.

Parent topic: WEB-BROWSER Control


Displaying Word Processing, Accounting, or Presentation Documents from Your Applications

To display word processing, accounting, or presentation documents that have been distributed with your COBOL program, you include a path and filename in the VALUE clause of the DISPLAY WEB-BROWSER statement. For example, you can "embed" a Word document, Excel spreadsheet, or PowerPoint slide presentation in your application, as in the following example:

display web-browser, value "c:\presentations\training.ppt".

This example opens PowerPoint inside the browser on the user's machine and displays the presentation named "training.ppt". Note that the menus and toolbars normally available to PowerPoint users do not appear in the browser. Users can access a subset of menu options by right-clicking in the control.

Parent topic: WEB-BROWSER Control


Displaying Windows Objects Such as Folders and Files

To display Windows objects such as directory folders and files (as in the Windows Explorer directory structure), you include a pathname in the VALUE clause of the DISPLAY WEB-BROWSER statement. For example:

display web-browser, value "C:\Program Files\Micro Focus\Acucbl900\acugt\bin".

This displays the folders and files contained in the "\acucorp\acucbl5x\acugt\bin" directory on the user's local machine in a manner similar to Windows Explorer. The user can open files by double-clicking them. To view the options normally displayed in the Windows Explorer menu bar or toolbar, users can right-click in the control. They will see a pop-up menu that contains many useful options for browsing directories.

Parent topic: WEB-BROWSER Control


Performing Print, File, and Clipboard Operations

The WEB-BROWSER control includes special properties that allow users to perform standard Windows print, file, and clipboard operations from your COBOL application.

There are five special properties relating to the Windows Print function. They are designed to let users print the contents of the WEB-BROWSER control (i.e., the Web page that is being displayed). These are:

Special Property | Function
PRINT | Displays the "Print" dialog
PRINT-NO-PROMPT | Prints without displaying a dialog first
PRINT-PREVIEW | Displays the "Print Preview" dialog
CUSTOM-PRINT-TEMPLATE | Defines the name and location of the custom template to use for printing and print previewing. (For use with IE versions 5.5 and later)
PAGE SETUP | Displays the "Page Setup" dialog

To display the "Print" dialog so that users can choose a printer, page range, and so on, set the Print property equal to "1" as such:

display web-browser PRINT = 1.

To assign a custom print template to use when printing with the dialog, add a pathname to the CUSTOM-PRINT-TEMPLATE property, then set PRINT equal to "1". For example:

display web-browser CUSTOM-PRINT-TEMPLATE = " \templates\mytemplate.html", PRINT = 1.

In addition to the print properties, the WEB-BROWSER control has several special properties relating to the Windows file and clipboard operations. These are:

Special Property | Function
COPY-SELECTION | Copies current selection to clipboard
CLEAR-SELECTION | Clears current selection from clipboard
SELECT-ALL | Selects the active HTML page, frame, or entry field, depending on cursor location
SAVE-AS | Displays the "Save As" dialog
SAVE-AS-NO-PROMPT | Saves frame contents to disk without prompting (for early version of IE only)
FILE-NAME | Defines path of file to be used in Save As operation
PROPERTIES | Displays the "Properties" dialog

To copy the current selection to the clipboard, set the COPY-SELECTION property to "1" as shown below:

display web-browser, COPY-SELECTION = 1.

For complete information on the WEB-BROWSER control special properties, see Web Browser

Parent topic: WEB-BROWSER Control


Sample Web Browser Program

The following sample program, "browser.cbl", demonstrates usage of the ACUCOBOL-GT WEB-BROWSER control. Additional samples have been provided in the sample directory on your ACUCOBOL-GT distribution media. See webbrows.cbl for another useful example.

identification division.
program-id.  Browser.

* Copyright (c) 1988 - 2003 by Acucorp, Inc.  Users of ACUCOBOL
* may freely modify and redistribute this program.

remarks.
This program illustrates the WEB BROWSER control type.

***************************************************************
data division.
working-storage section.
copy "acucobol.def".
copy "acugui.def".

77  key-status
         is special-names  crt status    pic 9(4) value 0.
         88  exit-button-pushed          value 27.

01  event-status
         is special-names event status.
    03  event-type                       pic x(4) comp-x.
    03  event-window-handle              usage handle.
    03  event-control-handle             usage handle.
    03  event-control-id                 pic x(2) comp-x.
    03  event-data-1                     usage signed-short.
    03  event-data-2                     usage signed-long.
    03  event-action                     pic x comp-x.

78  event-occurred                       value 96.
78  go-btn-pressed                       value 707.
78  back-btn-pressed                     value 708.
78  forward-btn-pressed                  value 709.
78  home-btn-pressed                     value 710.
78  refresh-btn-pressed                  value 711.
78  search-btn-pressed                   value 712.
78  stop-btn-pressed                     value 713.
77  ef-url                               pic x(1000).
77  wb-1-url                             pic x(1000).
77  wb-1-title                           pic x(100).
77  wb-1-status                          pic x(100).
77  wb-1-progress                        pic 9(7).
77  wb-1-max-progress                    pic 9(7).
77  progress-percent                     pic 9(9).

77  gt-bitmap                            pic s9(9) comp-4.

01  configuration-data.
  05 current-lines                       pic s99999V99 value 25.
  05 current-size                        pic s99999v99 value 73.

      *****************************************************************
screen section.
01  screen-1.

    03  entry-field, column 5, line 4, size 55 max-text = 0
        value ef-url.

    03  push-button, "&Back",
        column 5, line 2, size 9
        self-act
        termination-value = back-btn-pressed.

    03  push-button, "&Forward",
        column + 2, size 9
        self-act
        termination-value = forward-btn-pressed.

    03  push-button, "&Home",
        column + 2, size 9
        self-act
        termination-value = home-btn-pressed.

    03  push-button, "&Refresh",
        column + 2, size 9
        self-act
        termination-value = refresh-btn-pressed.

    03  push-button, "&Find",
        column + 2, size 9
        self-act
        termination-value = search-btn-pressed.

    03  push-button, "&Stop",
        column + 2, size 9
        self-act
        termination-value = stop-btn-pressed.

    03  push-button, "&Go", default-button
        column 55.2, line 4,
        termination-value = go-btn-pressed.

    03  status-frame-1 frame, line 22, column 5,
        lines 2 size 65 cells lowered.

    03  status-text-1 label, line 22.5, column 5.5,
        size 64 cells
        value wb-1-status.

    03  progress-meter-1 frame line 24 column 5
        lines 1.5 size 24
        fill-color = red, fill-color2 = white,
        fill-percent = 0, lowered.

    03  exit-1 push-button, "E&xit",
        cancel-button, line 24, column 32, size 11.

    03  busy-bitmap bitmap bitmap-handle = gt-bitmap,
        size 39, bitmap-start = 1, bitmap-end = 15,
        bitmap-timer = 0,
        line 2, column 65.

    03  wb-1 web-browser
        column 5, line 6,
        lines 16 cells, size 65 cells
        event procedure is browser-event-handler.

***************************************************************
procedure division.
main-logic.
    display standard window,
         title "Web Browser Sample - browser.cbl"
         lines current-lines, size current-size,
         resizable
         background-low.

    call "w$bitmap" using wbitmap-load, "gtanima.bmp",
         giving gt-bitmap.

    display screen-1.

    perform, with test after, until exit-button-pushed
         accept screen-1
         evaluate key-status
           when go-btn-pressed
             move ef-url to wb-1-url
             modify wb-1 value=wb-1-url
           when back-btn-pressed
             modify wb-1 go-back=1
           when forward-btn-pressed
             modify wb-1 go-forward=1
           when home-btn-pressed
             modify wb-1 go-home=1
           when search-btn-pressed
             modify wb-1 go-search=1
           when refresh-btn-pressed
             modify wb-1 refresh=1
           when stop-btn-pressed
             modify wb-1 stop-browser=1
           when event-occurred
             if event-type = ntf-resized
               divide event-data-1 by 100 giving current-lines
               divide event-data-2 by 100 giving current-size
               modify wb-1
                 lines current-lines - 9
                 size current-size - 8
               modify status-frame-1
                 line current-lines - 3
                 size current-size - 8
               modify status-text-1
                 line current-lines - 2.5
                 size current-size - 9
               modify progress-meter-1
                 line current-lines - 1
               modify exit-1
                 line current-lines - 1
             end-if
         end-evaluate
    end-perform.
    stop run.

browser-event-handler.
    evaluate event-type
        when msg-wb-navigate-complete
            inquire wb-1 value in wb-1-url
            if wb-1-url is not = ef-url then
                move wb-1-url to ef-url
                display screen-1
            end-if
        when msg-wb-progress-change
            inquire wb-1 progress in wb-1-progress
            inquire wb-1 max-progress in wb-1-max-progress
            move wb-1-progress to progress-percent
            multiply 100 by progress-percent
            divide wb-1-max-progress into progress-percent
            if progress-percent = 100
                move 0 to progress-percent
            end-if
            modify progress-meter-1,
                fill-percent = progress-percent
            if progress-percent = 0
                modify busy-bitmap bitmap-timer = 0
                    bitmap-number = 1
            else
                modify busy-bitmap bitmap-timer = 10
            end-if
        when msg-wb-status-text-change
            inquire wb-1 status-text in wb-1-status
            display status-text-1
        when msg-wb-title-change
            inquire wb-1 title in wb-1-title
            display wb-1-title upon global window title
    end-evaluate.
Parent topic: WEB-BROWSER Control


Appendix B: Using the Runtime as a Helper Application or Viewer

  • What Are Helper Applications and Viewers?
  • Deploying Applications with the Runtime as a Helper Application or Viewer
  • Preparing Your ACUCOBOL-GT Application
  • Creating a Link to Your COBOL Object
  • The User's Job
  • Security and the Helper Application or Viewer
Parent topic: A Programmer’s Guide to the Internet Version 10.2.0


What Are Helper Applications and Viewers?

If your users already have a licensed copy of the ACUCOBOL-GT® runtime on their machine and they want to be able to access COBOL applications on a Web site, one way to do this is to set up their runtime as an Internet helper application or viewer inside their browser.

Helper application and viewer are browser terms referring to user-based software that can read and process files of a given type. Netscape uses the term "helper application" to refer to such software. Microsoft Internet Explorer uses the term "viewer."

Since the ACUCOBOL-GT runtime has the ability to read and process COBOL objects, it allows users to run COBOL programs that they encounter when browsing your Web page.

Relationship between the browser client and the server

The main difference between this and a standard runtime configuration is that your COBOL object files are on the Web server and transmitted to the client machine via HTTP.

Keep in mind that the helper application/viewer is a fully-featured runtime; it has full access to your users' machines, including system calls, memory, disk and network access. Therefore, it should be used only with programs from trusted sources, or in conjunction with the Internet security you have in place.

If your users do not already have an ACUCOBOL-GT runtime installed, a thin client or Web runtime may be a better option for them. These client technologies are available on the Micro Focus Web site, and they provide additional capabilities designed for accessing remote COBOL resources in Internet environments. See Using the Thin Client to Launch Web Applications and Using the ACUCOBOL-GT Web Runtime for more information on these Web deployment methods.

Sample Scenario

The runtime as a helper application makes it very easy for your mobile work force to "stay in touch." With the runtime running as a helper application on their laptops, remote staff can access the appropriate page on your Web site and click on the link to start your inventory program on their local machines. To access Vision data on the server, the runtime makes use of the AcuServer® file system interface. This enables the sales person to access the inventory data files and update them with new information from a remote location.

Parent topic: Appendix B: Using the Runtime as a Helper Application or Viewer


Deploying Applications with the Runtime as a Helper Application or Viewer

To deploy your application on the Web using the helper application/viewer method, you (the developer) have three tasks, described in the following topics:

  1. Setting Up a Web Site
  2. Preparing Your ACUCOBOL-GT Application for the Web Runtime
  3. Creating a Link to Your COBOL Object

Once your work is done, runtime users also have two tasks, described in these topics:

  1. Defining the Runtime as a Helper Application or Viewer
  2. Launching the Application
Parent topic: Appendix B: Using the Runtime as a Helper Application or Viewer


Preparing Your ACUCOBOL-GT Application

There are no special coding considerations for using this method of Web deployment. However, runtime configuration and packaging do require some thought.

  • Configuring the Runtime
  • Packaging Your Application and Resources
Parent topic: Appendix B: Using the Runtime as a Helper Application or Viewer


Configuring the Runtime

When used as a helper application or viewer, the ACUCOBOL-GT runtime is invoked to execute a single file. If your application contains more than a single object file, it must be packaged in a library file that "packages" all of the objects and associated resources of your application into a single file. For more information, see Packaging Your Application and Resources.

There are two ways to configure the runtime for use as a helper application:

  • Programmatically, using the SET CONFIGURATION or SET ENVIRONMENT variables, or
  • Bundling a configuration file into the library file along with the COBOL object files and resources.

If you choose the library file method and the library contains a configuration file, the client machine must be set up to specify the name of the configuration file when users define the runtime as a helper application in their browser. Be aware, however, that this will affect all COBOL applications that your users run as a helper application. For instructions, see Defining the Runtime as a Helper Application or Viewer.

If you choose to configure the runtime programmatically, you should use the SET CONFIGURATION (or SET ENVIRONMENT) phrase in your source code.

For example, if your application uses a configuration file with the following entries:

FILE_PREFIX @hal:/u2/serverfiles
COMPRESS_FILES 1
KEYSTROKE EDIT=PREVIOUS EXCEPTION=52 kl

Add the following lines to your COBOL initialization code:

SET CONFIGURATION "FILE_PREFIX" TO "@hal:/u2/serverfiles".
SET CONFIGURATION "COMPRESS_FILES" to "1".
SET CONFIGURATION "KEYSTROKE" TO "EDIT=PREVIOUS EXCEPTION=52 kl"

Note that MAX_FILES, MAX_LOCKS, and LOCKS_PER_FILE cannot be modified using the SET verb and that the COBOL program can read environment variables using ACCEPT FROM CONFIGURATION (or ACCEPT FROM ENVIRONMENT).

Parent topic: Preparing Your ACUCOBOL-GT Application


Packaging Your Application and Resources

In order to be used as a helper application or viewer, your COBOL application must be packaged in a single library file that contains all of the necessary COBOL objects, bitmap resources, and if desired, a configuration file. If you will be interfacing your application with a relational database through Acucorp's Acu4GL® product, you can package the ".xfd" files into the library file as well.

To create your library "package," you use the cblutil utility, the COPY RESOURCE statement, or a combination of the two. An overview of these two techniques is provided below. For more information, see ACUCOBOL-GT Reference Manual.

  • Using cblutil
  • Using COPY RESOURCE
Parent topic: Preparing Your ACUCOBOL-GT Application


Using cblutil

The cblutil utility lets you embed resources, which are defined as pieces of static data, directly into an object file. For the purposes of the helper application, these resources can be applications, bitmaps, wave files, configuration files, and extended file descriptors (".xfd" files). The program treats the resource as if it were a disk file, but the resource is not actually a separate file in the target environment.

Using "cblutil -lib", you can specify any type of file as an input file. If an input file is a COBOL object, cblutil includes it in the resulting library as a COBOL object. If an input file is another library, each component of the library is individually added to the resulting library. Any other file is included as a resource.

To use the cblutil utility program, type "cblutil -lib" followed by the desired options, main program name, and all the modules you want included, separated by a space. Be sure to add the main or initial program to the library first, because the runtime executes the first program it encounters in the library.

Syntax

cblutil -lib [options] main_program modules
Note: Since the helper application identifies content with the ".acu" extension, the output library file must have the ".acu" extension. For this reason, be sure to use the "-o" option to specify the name of the output file when using "cblutil -lib". In the example above, "mylib.acu" is the specified output file.

Example

cblutil -lib -v -o mylib.acu prog1.obj prog2.obj logo.bmp cblconfi data1.xfd data2.xfd
Note: Since the helper application identifies content with the ".acu" extension, the output library file must have the ".acu" extension. For this reason, be sure to use the "-o" option to specify the name of the output file when using "cblutil -lib". In the example above, "mylib.acu" is the specified output file.
Parent topic: Packaging Your Application and Resources


Using COPY RESOURCE

If you are creating a simple, single-object library, you can use the COPY RESOURCE statement to package your applications, bitmaps, and configuration file instead of the cblutil utility.

Use the COPY RESOURCE statement as follows:

COPY RESOURCE resource-name [ {IN} path-name ] .
                              {OF}

where resource-name and path-name identify a resource file to be included in the resulting object file.

The effect of a COPY RESOURCE statement is to add resource-name to a list of resources that the compiler embeds into the resulting COBOL object file. The resources are added to the end of the COBOL object in the same order as the corresponding COPY statements. Because the resources are added to the end of the object, the location of the corresponding COPY RESOURCE statement in the COBOL program is irrelevant. Conventionally, COPY RESOURCE statements are placed either in Working-Storage or at the end of the program, but any location is acceptable.

If resource-name resolves to a COBOL object or library file, the compiler includes this object or library in the resulting object in a manner similar to "cblutil -lib". These are not considered resources, but are embedded COBOL objects.

Parent topic: Packaging Your Application and Resources


Creating a Link to Your COBOL Object

To place your COBOL application on your Web page for use with a helper application or viewer, you create a hyperlink by placing the HTML Anchor tags in your HTML document. End users who visit your Web page can then run the program by clicking on the program's link.

The HTML Anchor tags, <A> and </A>, are closed elements that, when combined with the HREF attribute, highlight text or images, making them clickable. When users click on a highlighted item on your Web page, they are transferred to the linked document. Since the link in this case is a COBOL program, when users click on the highlighted item, the COBOL program is automatically invoked. (See any commercially available HTML text for more information on anchors and hypertext links.)

To turn text into a hypertext anchor, enclose the clickable text in the Anchor tags. The browser usually displays this text underlined and in a different color. For example, your HTML document may include this:

<A HREF="myprog.acu">Click here to run the application</A>

The HREF attribute is used within the starting anchor tag to specify the document to be linked (or retrieved). Then when the user clicks on the highlighted text, "Click here to run the application," on your Web page, the COBOL object "myprog.acu" is retrieved from the specified location on the Web server and run in a normal ACUCOBOL-GT window.

To use images as hypertext anchors, you place the <IMG> element within the Anchor tags. For example:

<A HREF="myprog.acu">
<IMG SRC="myprog.gif" ALT="Click here to run the application">
</A>

Then when the user clicks on the "myprog.gif" image on your Web page, the COBOL object "myprog.acu" is retrieved from the specified location on the Web server and run in a normal ACUCOBOL-GT window. While the graphic file is loading (or if the user's browser does not support images), the browser displays the alternate text, "Click here to run the application". Clicking this text invokes the application as before.

Parent topic: Appendix B: Using the Runtime as a Helper Application or Viewer


The User's Job

Once your work is done, runtime users have two tasks:

  1. Defining the Runtime as a Helper Application or Viewer in Their Browsers
  2. Visiting Your Web site and Launching the Application
  • Defining the Runtime as a Helper Application or Viewer
  • Launching the Application
Parent topic: Appendix B: Using the Runtime as a Helper Application or Viewer


Defining the Runtime as a Helper Application or Viewer

The process for defining helper applications or viewers varies according to the browser. While many browsers support helper applications or viewers, this section describes Microsoft Internet Explorer.

  • To define the runtime as a viewer in Internet Explorer
Parent topic: The User's Job


To define the runtime as a viewer in Internet Explorer

To invoke viewers, Internet Explorer uses the file type associations that users have set up for their Windows configurations. The procedure to add a file type association for ACUCOBOL-GT object files depends on your operating system.

Windows NT, 2000, ME, and XP users do the following:

  1. Start Windows Explorer.
  2. From the Tools menu, select Folder Options and click the File Types tab.
  3. Click New to open the Create New Extension dialog box.
  4. Type .acu for extension and click OK.

    Create New Extension dialog box

  5. On the File Types tab, click Advanced.

    File Types Tab

  6. From the Edit File Type box, select New... from the Actions field.
  7. Click inside each field in the box and do the following:
    Field Action
    Action: Type OPEN
    Application used to perform action: Browse to and select ACUCOBOL-GT runtime file "wrun32.exe". Click at the end of this field and type "%1" preceded by a space. Include the quotation marks. This indicates the complete path to the COBOL program file.

    Note: If users want to specify command line options, they may do so by typing the option after the executable name.

    The New Action dialog box should look similar to this:

    New Action dialog box

  8. Click OK to accept the new action.
  9. Change the icon for the application as desired. The Edit File Type box should look similar to this:

    Edit File Type dialog box

  10. Click OK to accept the new file type.
Parent topic: Defining the Runtime as a Helper Application or Viewer


Launching the Application

Now for the easy part. Once the runtime is installed on the local machine and set up as a helper application or viewer in the browser, users just start their browsers and visit your Web site. Since your application was included as a hyperlink, users simply click the highlighted text or image associated with the hyperlink to invoke your COBOL program.

The browser recognizes ACUCOBOL-GT object files, invokes the ACUCOBOL-GT runtime as a helper application, and runs your application on the end user's machine. The application runs just as if the user had invoked it directly on a local machine, using the full screen and ACUCOBOLGT user interface. The browser continues to run in the background.

Parent topic: The User's Job


Security and the Helper Application or Viewer

It is important to realize that the ACUCOBOL-GT runtime is a fully enabled runtime, even when used as a helper application or viewer. Unlike the ACUCOBOL-GT Web Runtime, it does not contain any extra Internet security mechanisms; it has full access to your users' machines, including system calls, memory, disk and network access.

For this reason, you should warn your users not to download COBOL applications from other sources to use with this runtime, unless the applications are from a trusted source. When your users try to download a file of a new type under Netscape, they are warned that the file may contain malicious code or scripting instructions, and they are given a chance to decline the operation. Nevertheless, users should be reminded that their helper application is a full-featured runtime without access limitations.

Parent topic: Appendix B: Using the Runtime as a Helper Application or Viewer


A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0

  • Copyright Statement
  • Introduction
  • Working with Java Technology
  • Working with Windows Technologies
  • Using ActiveX Controls and COM Objects
  • Working with .NET Assemblies
  • Working with C and C++ Programs
  • Deploying ACUCOBOL-GT Applications on the Web
  • Accessing ACUCOBOL-GT Applications from Mobile Devices
  • Working with Transaction Processing Systems
  • Working with Messaging Middleware
  • Working with Non-Vision Data
Parent topic: extend Programming Guides


Introduction

  • Introduction
  • Documentation Overview
  • Contacting Technical Support
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


Introduction

For companies with mission-critical COBOL business applications, the ability to interoperate with other technologies while retaining their time-proven programs can present some interesting opportunities. Imagine your legacy code interacting with applications in another language, working with XML documents, accessing data in a variety of databases, or operating in an application server environment. Such possibilities can help you refresh a long-established application and, perhaps more importantly, provide the needed edge for your company to compete successfully in today's tight marketplace.

For companies with ACUCOBOL-GT® applications, interoperability with other technologies is an attainable goal. The extend® family of technologies includes many opportunities for extending and enhancing your legacy applications, allowing you to integrate that code with other enterprise information technology components regardless of their platform, language, database, or network infrastructure. You can combine our technologies in a number of ways to solve your business issues, while protecting your valuable investment in legacy applications. A Guide to Interoperating with ACUCOBOL-GT provides information to help you facilitate this integration as the need arises.

Parent topic: Introduction


Documentation Overview

This documentation includes:

  • Working with Java Technology - Provides information that can help your ACUCOBOL-GT applications interoperate with Java. The chapter includes details about methods for calling COBOL from Java and calling Java from COBOL. You can also learn about mapping Java data types, J2EE application server technology, and Web services.
  • Working with Windows Technologies - Explains how to leverage Microsoft Windows technologies in your ACUCOBOL-GT programs. The chapter includes information about calling dynamic link libraries (DLLs), accessing the Windows Application Programming Interface (API), and using some Windows-specific ACUCOBOL-GT features.
  • Using ActiveX Controls and COM Objects - Describes how to include Microsoft ActiveX controls and COM objects in your ACUCOBOL-GT program.
  • Working With .NET Assemblies - Describes how to call .NET assemblies from your ACUCOBOL-GT program and how to invoke COBOL from a .NET assembly. It also discusses interacting with .NET Web services from COBOL.
  • Working with C and C++ Programs - Provides information about how your ACUCOBOL-GT applications can interoperate with C and C++ programs. Learn about direct calls from C to COBOL and from COBOL to C, interfacing to COBOL from C via the ACUCOBOL-GT C API, and matching C data items.
  • Deploying ACUCOBOL-GT Applications on the Web - Explains our various technologies that help you deploy your ACUCOBOL-GT applications on the Internet. The chapter includes descriptions of the ACUCOBOL-GT Web Thin Client and Web Runtime, our Common Gateway Interface (CGI) extensions, and more.
  • Accessing ACUCOBOL-GT Applications from Mobile Devices - Explores the basic concepts of accessing COBOL programs from mobile devices running non-COBOL applications. You receive background information on mobile terminology, infrastructure, and platform trends. Some mobile system design issues are covered, and a sample mobile system with a COBOL back end is described.
  • Working with Transaction Processing Systems - Discusses how ACUCOBOL-GT can interoperate with online transaction processing (OLTP) systems. You learn about transaction processing in general, and then find out how ACUCOBOL-GT can work with specific transaction processing technologies.
  • Working with Messaging Middleware - Explains how to integrate ACUCOBOL-GT applications with message passing middleware, specifically IBM WebSphere MQ (formerly MQ Series).
  • Working with Non-Vision Data - Explains how ACUCOBOL-GT applications can interoperate with external data sources, including XML documents, SQL databases, ODBC-compliant data sources, C-ISAM and KSAM files, and file systems that use an EXTFH interface to access files.

Other manuals in the extend documentation set are referenced in this book as well. These manuals may be accessed from support section of the Micro Focus Web site or installed from your product media.

Parent topic: Introduction


Working with Java Technology

  • COBOL/Java Interoperability
  • Calling COBOL from Java
  • Calling Java from COBOL
  • Mapping Java Data Types
  • J2EE Application Servers
  • Web Services
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


COBOL/Java Interoperability

Businesses want to deploy Java technology for a variety of reasons. They include:

  • The flexibility of JavaServer Pages™ for graphical front ends, Internet portals, mobile devices, etc.
  • The availability of an enterprise standard, Java2 Enterprise Edition (J2EE™)
  • The promise of application server technology from vendors such as BEA, IBM, Sun, and Oracle

Despite the opportunities that Java affords, many businesses recognize that their legacy applications have high value to them. They know that COBOL runs their business. Their COBOL programs have been time-tested, fine-tuned, and proven reliable and scalable. They have been custom-fitted to their business processes.

Rather than replacing COBOL with Java, many organizations integrate their legacy assets with the newer Java components.

Parent topic: Working with Java Technology


Calling COBOL from Java

With ACUCOBOL-GT®, there are many ways to achieve interoperability with Java. If you want to call COBOL from a Java application, you can:

  • Use ACUCOBOL-GT's Java compiler options to generate Java classes that call your ACUCOBOL-GT program. Java programmers can then invoke these classes as they would any native Java code.
  • Use the Java native interface, "CVM.jar", to interact with the COBOL program at the API level. "CVM.jar" contains a singleton class, CVM, that encapsulates the ACUCOBOL-GT runtime. With the CVM, the Java programmer can programmatically instantiate an instance of the ACUCOBOL-GT runtime and invoke a COBOL program. The programmer can use other classes or methods of CVM to specify runtime options and program options.
  • Use the C$SOCKET library routine to facilitate interprocess communication via sockets. C$SOCKET is a low-level option, but it is very flexible.
  • Use our CGI extensions. The Java programmer can use CGI to call a remote COBOL procedure through a Web server.
  • Use the Java Native Interface (JNI) to call the ACUCOBOL-GT runtime dynamic link library (DLL) in Windows or shared library in UNIX.
  • Use named pipes to pass data between your COBOL and Java applications if they reside on the same host machine. Passing data through named pipes is a low-level solution requiring the development of C code. Named pipes are a good option for legacy applications that perform strictly file I/O.
  • Use AcuXDBC™ to access COBOL Vision data from a Java Database Connectivity (JDBC)-enabled application.
  • Calling COBOL from a Java Command Line
  • Using the Java Compiler Options
  • Using the Java API CVM.jar
  • Using C$SOCKET
  • Using ACUCOBOL-GT's CGI Extensions
  • Using the Java Native Interface (JNI)
  • Using Named Pipes
  • Using AcuXDBC
Parent topic: Working with Java Technology


Calling COBOL from a Java Command Line

You can call COBOL from a Java command line and without having to write a Java program. This is done by specifying a Java command line that calls the ACUCOBOL-GT Java Native Interface "CVM.jar", specifies the path to the ACUCOBOL-GT runtime, and passes an ACUCOBOL-GT runtime command.

Syntax

java -cp path-to-CVM.jar com.acucorp.acucobolgt.runcbl --acugt path-to-AcuGT-runtime [java-options] runtime-command-line path-to-cobol-program

Syntax Definitions and Parameters

java -cp path-to-CVM.jar com.acucorp.acucobolgt.runcbl | Required syntax for calling the AcuGT CVM
--acugt | Required parameter that brings in the AcuGT runtime.
path-to-AcuGt-runtime | Required syntax that specifies the location of the AcuGT runtime.
java-options | Optional parameters described in the next table.
runtime-command-line | Any valid runtime command line options. See Runtime Options for details on runtime command lines.
cobol-program | The name of the COBOL program to run.
java-options | Description
--log | Creates a log
--logfile | Creates a log file
--verbose | Creates detailed log
--libs

There is a default list of libraries that automatically get loaded for both UNIX and Windows. On most systems the Java runtime will determine the correct list to load.

The default library list on UNIX is: acme, acuterm, vision, clnt, axml, runcbl

The default list on Windows is: acme, atermmgr, avision5, expat, axml32, wrun32

Note: 64-bit versions of these libraries have a 64 suffix, where available.

On some systems such as HP-UX, it may be required to specify these files manually by using the --libs option. The library names must be separated by either commas or semi-colons. The library names should also be specified in the order given above.

In most UNIX and Windows cases, it should not be necessary to use this option.

--libtext | Used to specify the library name's file extension. This option may be needed on certain systems such as HP-UX. In most UNIX and Windows cases, it should not be necessary to use this option.

Syntax Example

The following is a sample Java command line for calling a COBOL program named tour.acu.

Windows:

Java -cp "C:\Program Files (x86)\Micro Focus\extend 10.2.0\AcuGT\bin\CVM.jar" com.acucorp.acucobolgt.runcbl --acugt "C:\Users\Public\Documents\Micro Focus\extend 10.2.0\sample\tour.acu"

UNIX:

java -cp /usr/acu/10-2-0/tools/CVM.jar com.acucorp.acucobolgt.runcbl --acugt /usr/acu/10-2-0/lib tour.acu
  • Static Method RunCbl
Parent topic: Calling COBOL from Java


Static Method RunCbl

It also possible to call the ACUBOBOL-GT Java command line functionality from another Java program by calling the static method RunCbl in the runcbl class, and passing a Java String array that contains a valid runtime command line and logging switches.

There are two versions of the static method RunCbl. This version takes command line arguments only:

RunCbl(String[])

This version takes command line arguments and linkage section parameters as an object array:

RunCbl(String[], Object[])
Parent topic: Calling COBOL from a Java Command Line


Using the Java Compiler Options

There are two compiler options that make it easy for you to provide COBOL services to a Java program:

Compiler Option | Description
--javaclass | Generates a Java class that calls your COBOL program
--javamain | Generates a Java class with a main method
  • --javaclass
  • --javamain
Parent topic: Calling COBOL from Java


--javaclass

When you specify the "--javaclass" option at compile time, the compiler generates a ".java" file in addition to a ".acu" file. The ".java" file has the same prefix as the ".acu" file and is placed in the same directory. This ".java" file is a Java class that calls the COBOL program being compiled. Java programmers can then invoke this class as they would any native Java code.

Parent topic: Using the Java Compiler Options


--javamain

Same as "--javaclass" except "--javamain" generates a class with a main method added.

Parent topic: Using the Java Compiler Options


Using the Java API CVM.jar

Another way to call COBOL from Java is to use the application programming interface (API) contained in the Java archive, "CVM.jar". This interface can be used by Java developers to call COBOL functionality (such as programs and entry points) from their Java class.

Note: This feature is available only to shared library or DLL versions of the ACUCOBOL-GT runtime. On Windows, the DLL version is automatically available. To see if this feature is available to you on UNIX, type ls lib from the ACUCOBOL-GT installation directory. If you see the filename libruncbl.so or libruncbl.sl, then the feature is available. For instructions on creating a shared library for HPUX 11.0, see Building a Shared Library for HP-UX 11.0.

"CVM.jar" consists of two main classes:

Class | Description
CVM | CVM is a singleton class representing the ACUCOBOL-GT runtime. This class allows Java developers to programmatically manage the ACUCOBOL-GT runtime, giving them low-level control of COBOL objects from Java.
CALL_OPTIONS | This options class is used for setting options for each called COBOL program.

Note that you can call COBOL from Java locally or remotely. You can even have the runtime execute remotely without a COBOL object executing on the client. All you need on the client is a Java program and a runtime. For this to work, you set CODE_PREFIX in the configuration file that you provide with the runtime initialization to point to a remote server hosting your COBOL application. The remote server must also be running AcuConnect. AcuConnect is able to execute a COBOL object remotely and share data with the local runtime. For more information on executing remote COBOL programs with AcuConnect, see the AcuConnect User's Guide.

  • CVM Class
  • CALL_OPTIONS Class
  • Sample Use Case
  • Configuration and Deployment
  • Security
  • Example of Java Calling COBOL
  • Sample Programs for Java Interoperability
  • Building a Shared Library for HP-UX 11.0
Parent topic: Calling COBOL from Java


CVM Class

CVM is a Java class representing the ACUCOBOL-GT runtime. The CVM class exposes public methods for setting runtime options, calling and cancelling programs, getting object libraries, and much more.

The following table contains a description of each method. Please note that the get method returns the current value of a particular property or string. The set method sets the string or property value. For example, "setErrorsOut" sets the name of the file to which to send error messages, and "getErrorsOut" returns the filename that is currently set for the error log.

Boolean properties like TerminalInit are set to false by default. If you want to set a boolean property to true, then you call the set method for that property. For example, TerminalInit is set to false by default, meaning that terminal initialization is not inhibited. If you want to inhibit terminal initialization, set TerminalInit to true by calling "setTerminalInit" passing in true. Call "getTerminalInit" to see what boolean value is currently set for this property.

Public Method | Description
initialize( RT_OPTS options ) | Initializes the ACUCOBOL-GT CVM
initialize( String cmdLine ) | Initializes the CVM with command-line options
callProgram( String name, Object params[ ], CALL_OPTIONS options ) | Calls the named COBOL program using specified parameters and program options
cancelAllPrograms() | Cancels all programs
cancelProgram( String name ) | Cancels the named program and holds it in memory
unloadAllPrograms() | Empties memory of all programs
unloadProgram( String name ) | Empties memory of the named program
shutdown() | Shuts down the CVM
CVM GET_INSTANCE() | Returns the instance of the CVM in this process
CVM GET_INSTANCE( String logPropertiesFile ) | Specify a Java String that is the name of the logging properties file. This enables you to use a different file which is not the default Java logging properties file.
CVM GET_INSTANCE( String logPropertiesFile, String libLoc, String ext ) | The first String parameter has the same meaning as the previous GET_INSTANCE. The second String parameter is the location of the Acu shared libraries. On windows, this is where the acu dlls are installed ( "c:\Program Files\Acucorp\Acucbl810\AcuGT\bin. The third parameter is the extension of the shared libraries — on Windows the extension is ".dll", on Linux it is ".so", and on some versions of HP-UX it is ".sl".
setLog( Logger log) | Overrides the default log with a user-specified log
StatusInfo GetStatusInfo() Checks the status of a called COBOL program that has finished running. Use StatusInfo as follows:
class StatusInfo {
  public long cobol_return_code;
  public int exit_code;
  public int signal_number;
  public int call_error;
  public String exit_msg;};
getCVMError() | Gets the last error message of the CVM object class
getLastErrorMsg() | Returns the last error message string from the runtime
get/setSwitches() | Gets or sets the list of Special Names switches to turn on
get/setConfigFile() | Gets or sets an alternate configuration file
get/setErrorsOut() | Gets or sets an error messages file
get/setErrorsAppend() | Gets or sets a file to append error messages to
get/setKeyFile() | Gets or sets a keyboard input file
get/setImport() | Gets or sets a variable for importing graphical screens
get/setPlays() | Gets or sets a file of input keystroke scripts
get/setDisplayOut() | Gets or sets a file for display output
get/setDisplayAppend() | Gets or sets a file to append display output
get/setDebugCmds() | Gets or sets a file containing debugger commands
get/setTerminalOut() | Gets or sets a file to capture terminal output
get/setObjLib() | Gets or sets an object file library
get/setEmbeddedLib() | Gets or sets a configuration file from a COBOL object library
get/setTerminalInit() | Inhibits terminal initialization
get/setCGIWarnings() | Suppresses warning messages in CGI programs
get/setIgnoreSignals() | Ignores terminal hang-up signals
get/setListConfig() | Lists contents of the configuration file
get/setNoSaveDebug() | Prevents the debugger from reading and writing adb
get/setSafeMode() | Runs in safe mode
get/setNonNumeric() | Suppresses warnings when non-numeric data is used as numeric data
get/setExtendedError() | Displays extended error codes for file error "30"
get/setDumpMem() | Dumps memory for memory access violations
get/setThrowErrors() | Displays error message text in a MessageBox
get/setCharToGui() | Converts character screens to GUI equivalent
get/setZipErrorFile() | Compresses the error file
get/setLinkageLength() | Disables Linkage item length test

To set options in the CVM class (that is, to set runtime options), use the specific "setOption" method such as "setConfigFile" and the value to set. You can also call "setOption" with the option name passed as a string.

Call "cvm.initialize" after setting options. After "initialize" is called, setting options has no effect until you call "initialize" again.

Parent topic: Using the Java API CVM.jar


CALL_OPTIONS Class

The CALL_OPTIONS class represents the options for each called COBOL program. If you want to pass program options to the "cvm.callProgram" method that runs the COBOL program, create a CALL_OPTIONS object, then add options to it. The CALL_OPTIONS class is structured as follows:

class CALL_OPTIONS {
 public String GetOption( String key );
 public void SetOption( String key, String value );
};

Valid call options include:

  • cache — an unsigned value that determines whether the runtime should maintain the program in a memory cache after it has been canceled.

    This parameter is useful for application servers like CICS that allow each program to be configured as resident or nonresident.

    If "cache" is FALSE ("0"), the runtime removes the program from memory and sets the Working-Storage to its initial state on subsequent calls.

    If "cache" is TRUE ("1"), it marks the program as "cached" and resets Working-Storage for the next call; the program remains in memory according to the caching rules. For information on managing logical and physical cancels that may affect the behavior of "cache", and see also LOGICAL_CANCELS.

  • debug_method (-dn) where n is 0-3:

    0 = ADM_NONE for no debugging

    1 = ADM_XTERM to debug using a new xterm

    2 = ADM_TERMINAL to debug using an existing terminal through runcbl

    3 = ADM_THINCLIENT to debug using a waiting thin client

    Based on the debug_method selected, you may need to also specify debug_method_string.

  • debug_method_string — a char* that sets the display setting for the debug_method

    For ADM_XTERM, set to the Xservername:displaynumber of the xterm or set to NULL to allow the xterm to use the default display given by the DISPLAY environment variable. For ADM_TERMINAL, set the string to the tty device on which you will execute runcbl. For ADM_THINCLIENT, set to client:port where the client is the host on which acuthin is executing and port is the port on which it is listening.

    Note: The value of debug_method_string overrides the value, if any, in the DISPLAY configuration variable for the xterm.

    See Background Debugging Options for more information on background debugging.

  • no.stop — an unsigned input value that, when set to "1", causes STOP RUN to be ignored.
  • program.name — the name of the COBOL program being called

The CALL_OPTIONS class contains a linkage_signature property that describes the data in the linkage section. For example, a linkage_signature of "X45X20SSIJ" describes two PIC X items of 45 and 20 bytes respectively, two shorts, an integer, and a long.

The linkage_signature ensures that there is enough memory for Java strings to get passed in, even when the Java string has a shorter length than the PIC X data item in the linkage section. For example, a Java string of length 10 can be passed into a PIX X(45) data item. In this case, 45 bytes are allocated to memory, not 10 bytes.

Parent topic: Using the Java API CVM.jar


Sample Use Case

CVM cvm = CVM.GET_INSTANCE();
cvm.setErrorsOut("/tmp/errfile");
cvm.setConfigFile("c:/myproject/config");
cvm.initialize();

CALL_OPTIONS co = new CALL_OPTIONS();
co.setOption("debug_method", "1");

Object objInt = new Integer(1);
Object objString = new String("Test String Parameter");
Object params[] = {
objInt,
objString
};
cvm.callProgram("TestJavaToCobol", params, co);
cvm.cancelProgram("TestJavaToCobol");
cvm.shutdown();
Parent topic: Using the Java API CVM.jar


Configuration and Deployment

To call COBOL from Java using the CVM, perform the following steps:

  1. Install and correctly configure the ACUCOBOL-GT runtime. Optionally, install AcuBench® if the system will also be used for COBOL development.
  2. Install and correctly configure a Java Runtime Environment (JRE) Version 1.4.2 or later. Optionally, install a J2SE Software Developer's Kit (SDK) if the same system will also be used for Java development.
  3. Place the path to the JRE /bin directory in the PATH environment variable. Here is an example:
    PATH =D:/j2sdk1.4.2_04/bin.

    If the ACUCOBOL-GT installation directory is not the current directory, then that directory should also be placed on the path. The runtime path must be correctly configured so that a call to LoadLibrary("wrun32.dll") or loading the shared library "libruncbl.so" succeeds.

  4. Place the path to "CVM.jar" in the CLASSPATH environment variable. Also ensure that the class or JAR (Java Archive) file that contains the declaration of main is included in the classpath. For JAR files, include the filenames in the classpath. For class files, include the directory where the class files reside. Here is a Windows example:
    CLASSPATH=d:\cobol7\bin\acuUtilities.jar;d:\cobol7\bin\CVM.jar;c:\cobol7\JavaProject

    For UNIX platforms, use a colon as a delimiter instead of a semicolon.

  5. Add the location of the runtime DLLs and shared libraries to the variable LD_LIBRARY_PATH. For example, on Windows:
    LD_LIBRARY_PATH=C:\Program Files\Acucorp\Acucbl900\AcuGT\bin

    On UNIX or Linux, the shared libraries are located in /AcuGT/lib.

  6. Do one of the following:
    1. Place a copy of the COBOL program to be called in the same directory as the ACUCOBOL-GT runtime. This would be the compiled ".acu" file that contains the COBOL program.
    2. Pass the fully qualified filename of the COBOL program to be called to the runtime.
    3. Use a configuration variable to identify the location of the COBOL program.
  7. Ensure that all configuration options located in the configuration file are set up correctly. This includes the location of the JRE, preloading the JVM, and the command line that will be passed to the JVM.
  8. The Java class being used to call COBOL must provide a main function such as this:
    public static void main(String[] args)
  9. The Java program calling COBOL must include an import statement that imports the ACUCOBOL-GT Java class that is used. Here is an example:
    import com.acucorp.acucobolgt.*;
  10. The Java program calling COBOL must declare two objects: one of type CVM and one of type CALL_OPTIONS. The following is sample Java code that shows how to call a COBOL program, passing two parameters, using the "CVM.class":
    CVM cvm = CVM.GET_INSTANCE();
cvm.setErrorsOut("/tmp/errfile");
cvm.setConfigFile("c:/myproject/config");
cvm.initialize();

CALL_OPTIONS co = new CALL_OPTIONS();
co.setOption("debug_method", "1");

Object objInt = new Integer(1);
Object objString = new String("Test String Parameter");
Object params[] = {
objInt,
objString
};
cvm.callProgram("TestJavaToCobol", params, co);
cvm.cancelProgram("TestJavaToCobol");
cvm.shutdown();
  11. The COBOL program being called must provide a Linkage Section that matches the order and type of the Java parameters passed in the Java Object array. This is done by the COBOL programmer. Here is an example of a Linkage Section that does this for the above program:
    linkage section.
77 test-integer-parameter usage is signed-int.
77 test-string-parameter pic x(21) value spaces.
Parent topic: Using the Java API CVM.jar


Security

The CVM class in "CVM.jar" supports the default security manager class in Java, known as java.lang.SecurityManager. For information on this class or overriding the default security manager, please refer to the Java API documentation provided by Sun Microsystems.

Parent topic: Using the Java API CVM.jar


Example of Java Calling COBOL

Java Program

import com.acucorp.acucobolgt.*;
public static void main(String[] args) throws IOException {
  try{
     CVM cvm = CVM.GET_INSTANCE();
     cvm.setErrorsOut("/tmp/errfile");
     cvm.setConfigFile("c:/myproject/config");
     cvm.initialize();

     CALL_OPTIONS co = new CALL_OPTIONS();
     co.setOption("debug_method", "1");

     int intParam = 1;
     Integer objInt = new Integer(intParam);

     byte byteParam = 'a';
     Byte objByte = new Byte(byteParam);

     char charParam = 'b';
       Character objChar = new Character(charParam);

     Object params[] = {
       objInt,
       objByte,
       objChar
     };
     cvm.callProgram("TestJavaToCobol", params, co);
     cvm.cancelProgram("TestJavaToCobol");
     objInt = (Integer)params[0];
     objByte = (Byte)params[1];
     objChar = (Character)params[2];

     System.out.println("COBOL changed value to " +
        objInt.intValue());
     System.out.println("COBOL changed value to " +
        objByte.byteValue();
     System.out.println("COBOL changed value to " +
        objChar.charValue());

     cvm.shutdown();
   } catch (Exception e){
    e.printStackTrace();
   }
}

COBOL Program

identification division.
program-id. TestJavaToCobol.
data division.
working-storage section.
COPY "java.def".
01 status-val pic 9(02) value zero.

linkage section.
01 integer-parameter usage is signed-int.
01 byte-parameter pic x.
01 char-parameter pic x.

procedure division
   using integer-parameter, byte-parameter,
   char-parameter.
main-logic.
   move 3 to integer-parameter.
   move "d" to byte-parameter.
   move "e" to char-parameter.
   exit program.
Parent topic: Using the Java API CVM.jar


Sample Programs for Java Interoperability

Your ACUCOBOL-GT distribution includes Java interoperability sample programs. You will find them in the %PUBLIC%\Documents\Micro Focus\extend x.x.x\sample\java directory. The directory also contains text files that include detailed instructions.

Parent topic: Using the Java API CVM.jar
Parent topic: Calling the C$JAVA Routine


Building a Shared Library for HP-UX 11.0

Because we do not offer a shared library distribution of ACUCOBOL-GT on HP-UX 11.0 or before, customers who want to use the Java API feature need to create the shared library manually. To do so, follow these instructions:

  1. Add the following five lines to the end of $ACUCOBOL/lib/Makefile. Note that the whitespace before the fourth and fifth lines must be tabs, not spaces.
    SHAREDLIB_LDFLAGS = -s +b $(ACUVERSPATH)/lib:$(ACUPATH)/lib:.:../stdlib:/usr/lib:/lib
libruncbl.sl: amain.o $(SUBS)
        ld -b $(SHAREDLIB_LDFLAGS) -o libruncbl.sl amain.o $(SUBS) \
              $(RUNTIME_LIB) $(LIBS) $(SYS_LIBS)
  2. Run "make libruncbl.sl" from the $ACUCOBOL/lib directory.

    This creates a file named "libruncbl.sl" that can be loaded by the CVM class when calling COBOL from Java. You can also add "libruncbl.sl" to the "clean" target so that "make clean" will remove "libruncbl.sl".

Parent topic: Using the Java API CVM.jar


Using C$SOCKET

If desired, you can facilitate communication between Java and COBOL programs on a socket level. ACUCOBOL-GT includes a library routine, known as C$SOCKET, to perform interprocess communication.

When calling COBOL from Java:

  1. The COBOL programmer uses the C$SOCKET routine to create a server socket (op-code 1) and wait for and accept a connection from the Java client (op-code 2).
  2. The Java programmer creates a socket, connects via TCP/IP to the port of the COBOL program, and writes data to it.
  3. Via C$SOCKET, the COBOL program reads the data (op-code 6), processes it, and returns data to the socket (op-code 5).

Of course, because the data format is totally open and undefined, the COBOL and Java programmers must agree on a common format.

Following is sample code to demonstrate this capability:

*The following code creates a server socket.
CALL "C$SOCKET" USING AGS-CREATE-SERVER, 8765
GIVING SOCKET-HANDLE-1.
*The following code waits for a connection.
CALL "C$SOCKET" USING AGS-NEXT-READ, SOCKET-HANDLE-1,
TIMEOUT.

*If have a connection request. Accept the connection.
CALL "C$SOCKET" USING AGS-ACCEPT, SOCKET-HANDLE-1.

*Read data from the connecting socket.
CALL "C$SOCKET" USING AGS_READ, SOCKET-HANDLE-2,
SOCKET-IN, IN-DATA-LENGTH
GIVING READ-AMOUNT.

*Write outgoing data back to the client socket:
CALL "C$SOCKET" USING AGS-WRITE, SOCKET-HANDLE-2,
SOCKET-OUT, OUT-DATA-LENGTH.

See General Syntax and Library List for information on the C$SOCKET library routine.

Parent topic: Calling COBOL from Java


Using ACUCOBOL-GT's CGI Extensions

ACUCOBOL-GT offers extensions designed to simplify communication with Web servers using the Common Gateway Interface (CGI) standard. These CGI extensions can be used to connect a Java program to an ACUCOBOL-GT program.

You develop a CGI program to act as an interface between the Web server and the ACUCOBOL-GT program. The CGI program can be written in ACUCOBOL-GT. See Writing a CGI Program for programming details.

From Java, you then open an HTTP connection to the Web server with a URL. The URL must have a pointer to the CGI program in it, encoded using CGI encoding.

Through CGI extensions to ACCEPT and DISPLAY syntax, your CGI program accepts CGI input data from the Java program; launches or subsumes your ACUCOBOL-GT application; and generates HTML, WML, or XML output forms from the results–whatever the Java program requires. The output could be considered a service, it could use SOAP, or it could be simple markup language output.

When you place your CGI program and ACUCOBOL-GT application on the Web server, along with the necessary configuration, license, and data files, your ACUCOBOL-GT application becomes immediately available to end users of the Java application. Conceptually, you're using CGI to do a remote procedure call.

See Launching Web Applications Through CGI for full details on using ACUCOBOL-GT's CGI syntax.

Parent topic: Calling COBOL from Java


Using the Java Native Interface (JNI)

Java programs can also call COBOL programs through a C calling interface known as the JNI. You can use JNI to call the ACUCOBOL-GT runtime DLL in Windows or a shared library that contains COBOL code routines in UNIX.

Windows

To simplify the process of calling an ACUCOBOL-GT program from other programming languages in a Windows environment, the ACUCOBOL-GT runtime is encapsulated in a DLL file, "wrun32.dll".

To call the ACUCOBOL-GT runtime DLL from JNI, you add declarations to the source program for the DLL's initialization, shutdown, and call libraries. Then you call those libraries to initialize the runtime, call the COBOL program, and shut down when you are finished.

For more information on calling the ACUCOBOL-GT runtime DLL, see Calling the Runtime DLL.

UNIX

To access COBOL from Java in UNIX environments, you can place native COBOL code routines in shared libraries and call them from your Java programs via JNI.

Note: To disable the JNI_OnLoad function during the loading of the ACUCOBOL-GT runtime, set the environment variable ACU_RUNCBL_JNI_ONLOAD_DISABLE to 1.
Parent topic: Calling COBOL from Java


Using Named Pipes

Another way to pass data between COBOL and Java programs is through named pipes. Named pipes are a method for exchanging information between two unrelated processes.

Note:

To communicate via named pipes, the COBOL and Java programs must be on the same host machine.

Technically, named pipes are files with known pathnames. Because a named pipe is associated with a pathname, unrelated processes can open the file to begin communications with one another. Because a Java program can open a named pipe just as it would a normal file, no special Java or JNI code is required. By opening the file for reading, a process has access to the reading end of the pipe, and by opening the file for writing, a process has access to the writing end of the pipe. In effect, named pipes allow independent processes to "rendezvous" their I/O streams.

Named pipes can be created in two ways–via the command line or from within a program.

In UNIX, to create a named pipe with the file named "npipe" you can use the following command on the command line:

% mkfifo npipe

Alternatively, you could create the named pipe from within your program using:

int mkfifo(const char *path, mode_t mode)

where "path" is the path of the file and "mode_t" is the mode (permissions) with which the file should be created.

A named pipe can be opened using the open( ) system call or the fopen( ) standard C library function. See Working with C and C++ Programs for information on interfacing ACUCOBOL-GT programs to C routines.

As with normal files, if the call succeeds, you get either a file descriptor or a "FILE" structure pointer, depending on how you opened the file. You can then use this information for reading or writing, depending on the parameters you passed to open( ) or fopen( ).

Reading from and writing to a named pipe are very similar to reading from and writing to a normal file. You can use the standard C library function calls read( ) and write( ).

Named pipes can also be used on Windows systems. You create Windows pipes with the CreateNamedPipe( ) API. You can then use the OpenFile( ) API to access the other end of the newly created named pipe.

Although named pipes can be very effective for communicating between COBOL and Java applications, bear in mind the following issues:

  • Named pipes work only for processes on the same host machine.
  • Named pipes can be created only in the local file system of the host.
  • Named pipe data is a byte stream, and no record identification exists.
  • Named pipes provide only a half-duplex flow of data. They are also known as "fifos" for their method of "first in, first out" communication. To establish full-duplex communication, you must create and manage two pipes, which can be complicated and result in file deadlocks if you are not careful.
Parent topic: Calling COBOL from Java
Parent topic: Calling Java from COBOL


Using AcuXDBC

If you want to access COBOL Vision data from a Java Database Connectivity (JDBC)-enabled application, you can use AcuXDBC Enterprise Edition. AcuXDBC is a data management system, designed to integrate ACUCOBOL-GT data files into a relational database-like environment. In addition to database-like features, the enterprise editions of AcuXDBC can give users of JDBC-enabled Java applications seamless access to ACUCOBOL-GT Vision files.

See the AcuXDBC User's Guide for more information.

Parent topic: Calling COBOL from Java


Calling Java from COBOL

To call Java from your COBOL application, you can:

  • Call the C$JAVA library routine. You can use configuration variables to preload the JVM and pass command-line options to it.
  • Use the C$SOCKET library routine to facilitate interprocess communication via sockets
  • Call the Java Virtual Machine (JVM) DLL or shared library
  • Use the C$SYSTEM library routine to send a Java command line to the host machine
  • Use named pipes to pass data between your COBOL and Java applications if they reside on the same host machine
  • Calling the C$JAVA Routine
  • Using C$SOCKET
  • Calling the Java Virtual Machine (JVM) DLL or Shared Library
  • Using C$SYSTEM
  • Using Named Pipes
Parent topic: Working with Java Technology


Calling the C$JAVA Routine

An easy, effective way to call Java from COBOL is via the C$JAVA library routine. A call to C$JAVA causes the JVM to be loaded (if it is not already) and the specified Java class to be loaded.

The COBOL statement used to make a call to Java from COBOL has the following syntax:

CALL "C$JAVA"
      USING OP-CODE, CLASS-NAME, METHOD-NAME, METHOD-SIGNATURE,
          FIELD-INT, FIELD-RETURN
       GIVING STATUS-VAL.

For example:

CALL "C$JAVA"
     USING CJAVA-NEW, "acuCobolGT/CAcuCobol", "()V"
     GIVING OBJECT-HANDLE.

The default CALL C$JAVA statement is designed to call a Java method. It requires a class name fully qualified with the package name if necessary. It also requires a method name and a method signature describing the parameter types and return types. After the method signature, pass the parameters that the method requires, and finally pass a parameter to hold the Java return value from the method. If the method is void, no return parameter is required. A giving value is returned to pass any other error code that may have occurred.

See C$JAVA for complete information on the C$JAVA library routine and its op-codes.

Note: To call Java from COBOL, HP-UX users must relink the runtime so that it is statically linked to "libjvm.sl". For instructions, see Linking the Runtime to libjvm.sl on HP-UX.
  • Method Signatures
  • Supported Parameter Types
  • Creating and Using Java Objects in COBOL
  • Creating and Using Java Arrays in COBOL
  • Using Java Logging from COBOL
  • Creating and Using a JDBC ResultSet
  • Java Remote Method Invocation (RMI) Interoperability
  • Handling Java Exceptions
  • Releasing Memory
  • C$JAVA Configuration Variables
  • Configuration and Deployment
  • Linking the Runtime to "libjvm.sl" on HP-UX
  • Example
  • Sample Programs for Java Interoperability
Parent topic: Calling Java from COBOL


Method Signatures

Parameter signatures are used by the JNI functions to get the method ID of a method in a Java class so that it can be called by non-Java programs. Two examples are "(I)I" and "(Z)Z". The first one describes a Java method taking an int parameter and returning an int value. The second is a Java method taking a boolean parameter and returning a boolean value. For a Java method like this:

int MyJavaMethod( boolean param1, int param2, long param3, double param4)

The signature would look like this:

(ZIJD)I.

The return value comes last after the close parenthesis. "Z" was chosen to represent boolean because "B" is used to describe a byte data value. The topic Supported Parameter Types shows a list of the parameter types supported by ACUCOBOL-GT. An "L" represents some object type. "J" is used for longs. Everything else in Java is an object (strings, arrays, etc.), and the signatures look like this:

Object Types | Signature
String | Ljava/lang/String
Object | Ljava/lang/Object
Array of strings | [Ljava/lang/String

Example syntax is shown in the following table:

Signature | Description
()V | Java-defined void method taking no parameters
(Z)I | Takes boolean, returns int
(ZISDJ)Z | Takes boolean, int, short, double, long, returns boolean
(B[J[I)X | Takes byte, long array, int array, returns string
(XLjava/lang/Object;)Ljava/lang/String; | Takes string, object, returns string
(C)C | Takes char, returns char
Parent topic: Calling the C$JAVA Routine


Supported Parameter Types

Following is a list of Java parameter types that are supported by ACUCOBOL-GT:

V – void
Z - boolean
B - byte
C - char
S - short
I - int
J - long
F - float
D - double
X - string
LString;
Ljava/lang/String;
Ljava/lang/Object;

[Z - boolean array
[B - byte array
[C - char array
[S - short array
[I - int array
[J - long array
[F - float array
[D - double array
[X - string array
[LString; - string array
[Ljava/lang/String; - string array
[Ljava/lang/Object; - object array
Parent topic: Calling the C$JAVA Routine


Creating and Using Java Objects in COBOL

Using the C$JAVA routine, you can create new Java objects in COBOL, call methods on Java objects, and destroy Java objects. The following sections describe how.

  • Creating a New Java Object
  • Calling Methods on Java Objects
  • Destroying Java Objects
Parent topic: Calling the C$JAVA Routine


Creating a New Java Object

Create a new Java object using the CJAVA-NEW op-code to the C$JAVA routine. Be sure to pass a fully qualified package/class name and a constructor signature. Use the GIVING statement to return the object handle. Here is an example of how to create a new Java object:

CALL "C$JAVA" USING CJAVA-NEW, "acuCobolGT/CAcuCobol", "()V" GIVING OBJECT-HANDLE.
Parent topic: Creating and Using Java Objects in COBOL


Calling Methods on Java Objects

You can call Java methods as static methods, virtual methods, or non-virtual methods by using op-codes 8-10 of the C$JAVA routine, or you can call a Java main method using op-code 29. If you do not use an op-code when you call C$JAVA, the default runtime behavior is to try to call the method statically, and then virtually by trying to create an object using a default constructor. A non-virtual method is called on the specific object that is being used. A virtual method can be called on a method that is inherited from one of the object's superclasses. Here are examples of each of the types of calls:

Default:

CALL "C$JAVA" USING "acuCobolGT/CAcuCobol", "CobolCallingJavaChar", "(C)C", FIELD-CHAR, FIELD-CHARRET GIVING STATUS-VAL.

Virtual:

CALL "C$JAVA" USING CJAVA-CALL, OBJECT-HANDLE, "acuCobolGT/CAcuCobol", "CobolCallingJavaLong", "(J)J", FIELD-LONG, FIELD-LONGRET GIVING STATUS-VAL.

Non-virtual:

CALL "C$JAVA" USING CJAVA-CALLNONVIRTUAL, OBJECT-HANDLE, "acuCobolGT/CAcuCobol", "CobolCallingJavaBoolean", "(Z)Z", FIELD-BOOL, FIELD-BOOLRET GIVING STATUS-VAL.

Static:

CALL "C$JAVA" USING CJAVA-CALLSTATIC, "acuCobolGT/CAcuCobol", "CobolCallingJavaDouble", "(D)D", FIELD-DOUBLE, FIELD-DOUBLERET GIVING STATUS-VAL.

Main:

CALL "C$JAVA" USING C
JAVA-CALLJAVAMAIN, "CobolCallingJava", "StrParam1",
    "StrParam2", "StrParam3", "StrParam4" GIVING STATUS-VAL.

This example calls a Java main method with the following signature:

public static void main( String[] args );

Additional examples:

CALL "C$JAVA" USING CJAVA-CALLNONVIRTUAL, OBJECT-HANDLE, "acuCobolGT/CAcuCobol", "CobolCallingJavaVoid", "()V" GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-CALL, OBJECT-HANDLE, "acuCobolGT/CAcuCobol", "CobolCallingJavaStringV", "(X)X", FIELD-STRING, FIELD-STRINGRET GIVING STATUS-VAL.
Parent topic: Creating and Using Java Objects in COBOL


Destroying Java Objects

To destroy a Java object, use C$JAVA's CJAVA-DESTROY op-code, and pass a valid object handle:

CALL "C$JAVA" USING CJAVA-DESTROY, OBJECT-HANDLE GIVING STATUS-VAL.
Parent topic: Creating and Using Java Objects in COBOL


Creating and Using Java Arrays in COBOL

You can use the C$JAVA routine to create and pass Java arrays of primitive types, objects, and strings; to get and set array elements; to clear arrays; and to convert COBOL tables to Java arrays and vice versa.

  • Creating and Passing Arrays of Primitive Types
  • Creating and Passing Arrays of Objects
  • Creating and Passing Arrays of Strings
  • Getting and Setting Array Elements
  • Getting and Setting Array Regions
  • Clearing Arrays
  • Implicit COBOL Table/Java Array Conversion
  • Explicit COBOL Table/Java Array Conversion
Parent topic: Calling the C$JAVA Routine


Creating and Passing Arrays of Primitive Types

To create Java arrays, use the op-code CJAVA-CREATEARRAY and pass in the type of the array and the size of the array. Return the array handle through the GIVING statement.

In the example below, an array of ints is created, and ARRAY-SIZE is declared USAGE IS SIGNED-INT VALUE 10. An object method that would take this array would have a parameter in its signature of type [I such as "([I)I". The primitives array types are documented in the topic Method Signatures.

CALL "C$JAVA" USING CJAVA-CREATEARRAY, CJAVA-INTARRAY, ARRAY-SIZE GIVING ARRAY-HANDLE.
Parent topic: Creating and Using Java Arrays in COBOL


Creating and Passing Arrays of Objects

You can create an object array as shown here:

CALL "C$JAVA" USING CJAVA-CREATEARRAY, CJAVA-OBJECTARRAY, 10 GIVING ARRAY-HANDLE.

In this case, the array consists of an array of object handles. Here is an example of calling a Java method that takes an array of objects:

CALL "C$JAVA" USING CJAVA-CALL, OBJECT-HANDLE, "acuCobolGT/CAcuCobol", "CobolCallingJavaObjectArray", "([Ljava/lang/Object;)X", ARRAY-HANDLE, FIELD-STRINGRET GIVING STATUS-VAL.
Parent topic: Creating and Using Java Arrays in COBOL


Creating and Passing Arrays of Strings

Even though strings in Java are objects, they are treated separately for the convenience of using them with PIC X tables. Here is an example of creating a string array:

CALL "C$JAVA" USING CJAVA-CREATEARRAY, CJAVA-STRINGARRAY, 10 GIVING ARRAY-HANDLE.

Here are examples of setting a string array element. In this example, STRING-TABLE is declared PIC X(20) OCCURS 10.

MOVE "99999999999999999999" TO STRING-TABLE(10)

CALL "C$JAVA" USING CJAVA-SETARRAYELEMENT, ARRAY-HANDLE, 1, STRING-TABLE(10), GIVING STATUS-VAL.

This example demonstrates how to call a Java method that takes an array of strings as a parameter:

CALL "C$JAVA" USING CJAVA-CALL, OBJECT-HANDLE, "acuCobolGT/CAcuCobol", "CobolCallingJavaStringArray", "([Ljava/lang/String;)X", ARRAY-HANDLE, FIELD-STRINGRET GIVING STATUS-VAL.
Parent topic: Creating and Using Java Arrays in COBOL


Getting and Setting Array Elements

You set array elements using the CJAVA-SETARRAYELEMENT op-code and passing in an array handle, the position in the array to set, and the value to set. In the following example, the first element of an array is set with the first value from an integer table that is USAGE IS SIGNED-INT OCCURS 10.

CALL "C$JAVA" USING CJAVA-SETARRAYELEMENT, ARRAY-HANDLE, 1, INT-TABLE(1), GIVING STATUS-VAL.

Getting array elements is done using a similar syntax with the op-code CJAVA-GETARRAYELEMENT. This call requires an array handle, the position in the array to get, and the variable into which the array value will be placed. Here is an example:

CALL "C$JAVA" USING CJAVA-GETARRAYELEMENT, ARRAY-HANDLE, 5, INT-TABLE(1), GIVING STATUS-VAL.

In this case, we are getting element 5 from the array and placing it in the first element of an integer table.

Parent topic: Creating and Using Java Arrays in COBOL


Getting and Setting Array Regions

You set array regions using the CJAVA-SETARRAYREGION op-code. This op-code takes a Java array object copies the elements from a COBOL table data item into a specified range. Getting array regions is done using a similar op-code, CJAVA-GETARRAYREGION. This op-code takes a Java array object, gets the specified range of elements, and copies them into a COBOL table data item.

Parent topic: Creating and Using Java Arrays in COBOL


Clearing Arrays

Clearing arrays is straightforward. Use the op-code CJAVA-CLEARARRAY and pass in the array handle of the array to be cleared, as shown:

CALL "C$JAVA" USING CJAVA-CLEARARRAY, ARRAY-HANDLE GIVING STATUS-VAL.
Parent topic: Creating and Using Java Arrays in COBOL


Implicit COBOL Table/Java Array Conversion

Restriction: Implicit conversion of string arrays is not supported; string arrays must be converted explicitly.

With ACUCOBOL-GT, it is possible to pass a COBOL table directly to a method that requires a Java array. The contents of the table are automatically converted to an array of the type the Java method expects. When the method completes, the contents of the table are updated with what is in the array. You do not have to explicitly convert the COBOL table to a Java array and convert it back again. No special op-code is required to do the conversion. When the runtime sees the array type in the signature, it tries to convert that table parameter to an array. Here is an example of a table being passed to a Java method that takes an array parameter:

CALL "C$JAVA" USING CJAVA-CALL, OBJECT-HANDLE, "acuCobolGT/CAcuCobol", "CobolCallingJavaIntArray", "([I)I", INT-GROUP, FIELD-RET GIVING STATUS-VAL.

In the above example, INT-GROUP is declared:

01 INT-GROUP.
    03  INT-DATA occurs 10 times.
        05  INT-ELEMENT signed-int.

The values for INT-GROUP are set as follows:

    MOVE 1111 to INT-ELEMENT(1)
    MOVE 2222 to INT-ELEMENT(2)
    MOVE 3333 to INT-ELEMENT(3)
    MOVE 4444 to INT-ELEMENT(4)
    MOVE 5555 to INT-ELEMENT(5)

It should be noted that the type of the table passed into the Java method should be the appropriate type, that is, data of the same element size (in bits). The size of the Java array will be the number of elements in the table.

Parent topic: Creating and Using Java Arrays in COBOL


Explicit COBOL Table/Java Array Conversion

With ACUCOBOL-GT, you can also use C$JAVA op-codes to explicitly convert Java arrays to COBOL and COBOL tables to Java. This functionality gives you more precise control over the conversion process.

The op-code to convert a Java array to a table is JAVA-CONVERTARRAYTOTABLE. Here is an example of an array of Java ints being converted to a USAGE SIGNED-INT OCCURS 10 COBOL table:

CALL "C$JAVA" USING CJAVA-CONVERTARRAYTOTABLE, ARRAY_HANDLE, 10, 0, INT-TABLE(1) GIVING STATUS-VAL.

The call takes the array handle, the number of elements to convert, the starting element position in the array, and the COBOL table variable in which to place the converted array.

To explicitly convert a COBOL table to Java, you can use the C$JAVA op-code CJAVA-CONVERTTABLETOARRAY. Here is an example of a call that converts a table to an array:

CALL "C$JAVA" USING CJAVA-CONVERTTABLETOARRAY, INT-TABLE(1), 10, 0, ARRAY-HANDLE, GIVING STATUS-VAL.

In this case, the call requires the COBOL table from which the values are taken, the number of elements, the position of the first element, and the handle of the destination array.

Parent topic: Creating and Using Java Arrays in COBOL


Using Java Logging from COBOL

With the C$JAVA routine, you can also log Java messages and configure the Java log.

  • Logging Messages
  • Configuring the Java Log
Parent topic: Calling the C$JAVA Routine


Logging Messages

If you want to log Java messages from a COBOL program, use the CJAVA-LOGMESSAGE op-code as follows:

CALL "C$JAVA" USING CJAVA-LOGMESSAGE, "Message to log".

The advantage of using the Java log is that it is thread-safe, and all of the messages from a given thread of execution are written to the same log whether that thread is executing COBOL or Java. Also, logs in Java are highly configurable. Note that the sample log output shown below is formatted to report date, time, class, method, and log level before the message.

11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM acu_cobol INFO -->
             COBOL LOG --> Entered TestJavaToCobol
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM acu_cobol INFO -->
             COBOL LOG --> Exiting TestJavaToCobol
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM acu_cobol INFO -->
             call.error = 0, exit.code = 0, signal.number = 0
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM acu_cobol INFO -->
             exit message =
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM cblLog INFO -->
             Call error: 0
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM cblLog INFO -->
             Exit code: 0
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM cblLog INFO -->
             Signal number: 0
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM cblLog INFO -->
             Exit message:
11/30/04 2:13:57 PM acuCobolGT.CAcuCobol cblLog INFO -->
             CobolCallingJavaTest: Complete
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM acu_cobol INFO -->
             CobolCallingJavaReentrantTest ()V
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM acu_cobol INFO -->
             call.error = 0, exit.code = 0, signal.number = 0
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM acu_cobol INFO -->
             exit message =
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM cblLog INFO -->
             Call error: 0
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM cblLog INFO -->
             Exit code: 0
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM cblLog INFO -->
             Signal number: 0
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM cblLog INFO -->
             Exit message:
11/30/04 2:13:57 PM com.acucorp.acucobolgt.CVM acu_shutdown INFO
             --> shutdown called - shutdown param: 0
11/30/04 2:13:57 PM acuUtilities.AcuJavaTest main INFO -->
             shutdown complete
11/30/04 2:13:57 PM acuUtilities.AcuJavaTest main INFO -->
             calling cobol end
Parent topic: Using Java Logging from COBOL


Configuring the Java Log

To configure the Java log created with the CJAVA-LOGMESSAGE op-code, modify the "logging.properties" file that is located in the runtime directory. The output location of the log (console or file) can be specified, as well as the log level, for example, INFO or SEVERE. Below is a sample of the "logging.properties" file:

# setting to limit messages printed to the console.
.level= INFO
#.level= FINEST

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

# default file output is in user's home directory.
#java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.pattern = CVM.log
java.util.logging.FileHandler.limit = 500000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.append = false
java.util.logging.FileHandler.level = INFO
#java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
#java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.formatter = com.acucorp.acucobolgt.logFormat

# Limit the message that are printed on the console to INFO and above.
#java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.level = INFO
#java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.ConsoleHandler.formatter = com.acucorp.acucobolgt.logFormat

############################################################
# Facility specific properties.
# Provides extra control for each logger.
############################################################

# For example, set the com.acucorp.acucobolgt.CVM logger to only log SEVERE
# messages:
#com.acucorp.acucobolgt.CVM.level = SEVERE
com.acucorp.acucobolgt.CVM.level = INFO
#acuCobolGT.CAcuCobol.level = SEVERE
acuCobolGT.CAcuCobol.level = INFO
#acuUtilities.AcuJavaTest.level = SEVERE
acuUtilities.AcuJavaTest.level = INFO
Parent topic: Using Java Logging from COBOL


Creating and Using a JDBC ResultSet

With ACUCOBOL-GT, there are two ways to create and use a Java Database Connectivity (JDBC) ResultSet in COBOL:

  • Using a class called DBConnect that is included in ACUCOBOL-GT's COBOL Virtual Machine Java archive file, "CVM.jar". See CVM Class for more information on ACUCOBOL-GT's CVM class.)
  • Using the CJAVA-DBCONNECT and CJAVA-DBQUERY op-codes to the C$JAVA routine
  • Using DBConnect Class to get a ResultSet Object
  • Using Op-codes to get a ResultSet Object
Parent topic: Calling the C$JAVA Routine


Using DBConnect Class to get a ResultSet Object

ACUCOBOL-GT's "CVM.jar" package contains a class for connecting to JDBC data sources, and querying those data sources for ResultSet objects. The class is called DBConnect.

The DBConnect class has two public static methods called "connect" and "query". The "connect" method takes two string parameters: a JDBC driver string, and a JDBC connection string, and returns a java.sql.Connection object. The "query" method takes two parameters: a query string, and a java.sql.Connection object, and returns a ResultSet object. The ResultSet object can then be used to access and update the data.

Here is an example of using the DBConnect class in COBOL:

MOVE "sun.jdbc.odbc.JdbcOdbcDriver" to DB-DRIVERSTR.

MOVE "jdbc:odbc:DefaultDir=D:\cobol7\bin;Driver={Microsoft Text Driver (*.txt; *.csv)};DriverId=27;UID=admin;Initial Catalog=D:\cobol7\bin" to DB-CONNECTSTR.

MOVE "SELECT * FROM dataFile.csv" to DB-QUERY.

CALL "C$JAVA" USING CJAVA-NEW, "java/lang/Object", "()V" GIVING DB-CONNECT.

CALL "C$JAVA" USING CJAVA-NEW, "java/lang/Object", "()V" GIVING DB-RESULTSET.

CALL "C$JAVA" USING "com/acucorp/acucobolgt/DBConnect", "connect", "(XX)Ljava/sql/Connection;", DB-DRIVERSTR, DB-CONNECTSTR, DB-CONNECT GIVING STATUS-VAL.

CALL "C$JAVA" USING "com/acucorp/acucobolgt/DBConnect", "query", "(XLjava/sql/Connection;)Ljava/sql/ResultSet;", DB-QUERY, DB-CONNECT, DB-RESULTSET GIVING STATUS-VAL

CALL "C$JAVA" USING CJAVA-CALL, DB-RESULTSET, "java/sql/ResultSet", "next", "()Z", FIELD-BOOLRET GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-CALL, DB-RESULTSET, "java/sql/ResultSet", "getRow", "()I", FIELD-RET GIVING STATUS-VAL.

MOVE 1 to FIELD-INT.

CALL "C$JAVA" USING CJAVA-CALL, DB-RESULTSET, "java/sql/ResultSet", "getString", "(I)X", FIELD-INT, FIELD-STRINGRET GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-DELETE, DB-CONNECT GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-DELETE, DB-RESULTSET GIVING STATUS-VAL.

In this example, the JDBC driver used was the jdbc:odbc bridge that ships with the Java SDK. The ODBC driver is the Microsoft Text driver, and a text CSV file was used as the data source. Two new object handles are created to contain the Connection and ResultSet handles. The ResultSet method "next" is called to move to the first row, the "getRow" method is called to find the current row number, and the "getString" method is called to get the value in column one which happens to be of type string. Finally, the two objects are deleted.

Parent topic: Creating and Using a JDBC ResultSet


Using Op-codes to get a ResultSet Object

Another way to access JDBC ResultSet objects is to issue a call to the C$JAVA routine using the op-codes CJAVA-DBCONNECT and CJAVA-DBQUERY. To do this, you must include the "java.def" file that comes with ACUCOBOL-GT in the COBOL program's working storage section. "java.def" is located in the sample/def directory where you installed ACUCOBOL-GT.

This method is somewhat more efficient than using the CVM's DBConnect class, because the Connection and ResultSet handles do not have to be created prior to being used. Here is an example of using the op-codes:

MOVE "sun.jdbc.odbc.JdbcOdbcDriver" to DB-DRIVERSTR

MOVE "jdbc:odbc:DefaultDir=D:\\cobol7\\bin;Driver={Microsoft Text Driver (*.txt; *.csv)};DriverId=27;UID=admin;Initial Catalog=D:\\cobol7\\bin" to DB-CONNECTSTR

MOVE "SELECT * FROM dataFile.csv" to DB-QUERY.

CALL "C$JAVA" USING CJAVA-DBCONNECT, DB-DRIVERSTR, DB-CONNECTSTR GIVING DB-CONNECT.

CALL "C$JAVA" USING CJAVA-DBQUERY DB-QUERY, DB-CONNECT GIVING DB-RESULTSET.

CALL "C$JAVA" USING CJAVA-CALL, DB-RESULTSET, "java/sql/ResultSet", "next", "()Z", FIELD-BOOLRET GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-CALL, DB-RESULTSET, "java/sql/ResultSet", "getRow", "()I", FIELD-RET GIVING STATUS-VAL.

MOVE 1 to FIELD-INT.

CALL "C$JAVA" USING CJAVA-CALL, DB-RESULTSET, "java/sql/ResultSet", "getString", "(I)X", FIELD-INT, FIELD-STRINGRET GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-DELETE, DB-CONNECT GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-DELETE, DB-RESULTSET GIVING STATUS-VAL.
Parent topic: Creating and Using a JDBC ResultSet


Java Remote Method Invocation (RMI) Interoperability

The following sections describe how to use the ACUCOBOL-GT runtime class, CVM, as a RMI client and RMI server. They also describe how to use the C$JAVA routine to connect to an RMI server.

  • Using the Runtime as a Java RMI Client
  • Using the Runtime as a Java RMI Server
  • Using an Op-code to Connect to an RMI Server
Parent topic: Calling the C$JAVA Routine


Using the Runtime as a Java RMI Client

ACUCOBOL-GT's "CVM.jar" package contains a class for connecting to an RMI server and returning an object through which remote methods can then be called on the RMI server. The class is called RemoteConnect. For more information, see the topic CVM Class.

The RemoteConnect class has a public static method called "CreateRemoteObject" that takes two strings and an int as parameters and returns a java.rmi.Remote object handle. The strings it requires are the host name of the server, the name of the RMI server object, and the int is the port number on which the server is listening. Once the remote object handle has been returned, remote methods on that object can be called in the same way as methods as any other Java object handle. Here is an example of using the RemoteConnect class in COBOL:

CALL "C$JAVA" USING CJAVA-NEW, "java/lang/Object", "()V" GIVING REMOTE-OBJ.

CALL "C$JAVA" USING "com/acucorp/acucobolgt/RemoteConnect", "CreateRemoteObject", "(XXI)Ljava/rmi/Remote;", "localhost", "TestRemoteInterface", PORT-NUMBER, REMOTE-OBJ GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-CALL, REMOTE-OBJ, "acuUtilities/TestRemoteInterface", "TestRemoteMethod",  "()X", FIELD-STRINGRET GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-DELETE, REMOTE-OBJ GIVING STATUS-VAL.

In this example, an instance of the object is created, and then the method "CreateRemoteObject" in RemoteConnect is called. In this case, the host is localhost, and the name of the remote interface is "TestRemoteInterface". "TestRemoteInterface" extends Remote and has one remote method called "TestRemoteMethod". The port number is "0" here. Passing in "0" causes the method to look for the object on the default RMI port, 1099. Note that for this to work, the RMI registry needs to have been previously started using the command "start rmiregistry" from the command line, and then the server object must be registered with the RMI registry.

Parent topic: Java Remote Method Invocation (RMI) Interoperability


Using the Runtime as a Java RMI Server

To create and use a Java RMI server object, you must first create a class for the object. This takes two steps. First, you must create an interface that extends the Java interface "java.rmi.Remote". Not only does the interface need to extend Remote, all the methods that can be called remotely must throw the RemoteException. Second, you must write a class that implements the interface. Once this is done, you can create an RMI server object and register it for use with the Java RMI Registry.

Here is a very simple illustration of this concept. First, an interface must be created in Java:

public interface TestRemoteInterface extends Remote {
    String TestRemoteMethod() throws RemoteException;
}

Next, a class that implements the TestRemoteInterface must be written. In the case of the methods of this class, you do not need to throw RemoteException, because the interface method declarations have that. Here is an example of such a class in Java:

public class TestRMIServer implements TestRemoteInterface {

    public TestRMIServer() {}

    public String TestRemoteMethod() {
 return "TestRemoteMethod successfully called.";
    }
}

Once this has been written, compiled, and packaged, you can register the server with the RMI registry. First, you must start the RMI registry on the host that will be the RMI server. You can do this using the command "start rmiregistry". Next, you can use a COBOL program to start the RMI server. In this COBOL program, make a call to the C$JAVA routine with the op-code CJAVA-STARTREMOTESERVER.

Here is an example of the code required to start an RMI server which uses the interface and server classes shown above:

CALL "C$JAVA" USING CJAVA-NEW, "acuUtilities/TestRMIServer", "()V" GIVING REMOTE-SERVER.
CALL "C$JAVA" USING CJAVA-STARTREMOTESERVER, REMOTE-SERVER, "TestRemoteInterface", PORT-NUMBER GIVING STATUS-VAL.

The first step is to create the server object. The second step is to start the server. CJAVA-STARTREMOTESERVER takes the remote server object handle just created, the name of the remote server to register, and the port number on which the server will listen. Once the server has started, that instance of the runtime that started it will block and remain running, listening for requests for the server from RMI clients.

Parent topic: Java Remote Method Invocation (RMI) Interoperability


Using an Op-code to Connect to an RMI Server

It is also possible to connect to an RMI server by calling the C$JAVA routine with op-code CJAVA-NEWREMOTEOBJECT. It is very much like the CJAVA-NEW op-code, but instead of creating an object in the local JVM, it creates an instance of a remote object. This op-code takes three parameters: the host name, the server name, and the port number. Here is an example of the call:

CALL "C$JAVA" USING CJAVA-NEWREMOTEOBJECT, "localhost", "TestRemoteInterface", PORT-NUMBER GIVING REMOTE-OBJ.

CALL "C$JAVA" USING CJAVA-CALL, REMOTE-OBJ, "acuUtilities/TestRemoteInterface", "TestRemoteMethod",  "()X", FIELD-STRINGRET GIVING STATUS-VAL.

CALL "C$JAVA" USING CJAVA-DELETE, REMOTE-OBJ GIVING STATUS-VAL.
Parent topic: Java Remote Method Invocation (RMI) Interoperability


Handling Java Exceptions

The C$JAVA library routine includes two op-codes for handling exceptions that are thrown by Java: CJAVA-EXCEPTIONOCCURRED and CJAVA-GETEXCEPTIONOBJECT.

CJAVA-EXCEPTIONOCCURRED is returned by any call to C$JAVA that returns a status value, but during which an exception was thrown.

CJAVA-GETEXCEPTIONOBJECT returns the exception object of the last exception thrown. Once the exception object is returned, you can call any of the methods on the exception object that are documented in the Java documentation.

In addition, exception information is now written to stderr or the error file specified by the "-le" command line option when a Java exception occurs. This information is formatted like a normal Java stack trace.

Parent topic: Calling the C$JAVA Routine


Releasing Memory

The Java Virtual Machine (JVM) doesn't have an explicit method to allocate and free memory. For this reason, if the COBOL program gets a reference to an object from the JVM, it is the COBOL program's responsibility to release the reference, otherwise the JVM might exhaust machine resources.

To aid in this effort, we suggest that you establish a JVM trace file using the following configuration variables:

  • A_JAVA_TRACE_FILENAME — Names the file where you want to store trace information
  • A_JAVA_TRACE_VALUE — Specifies the types of calls to trace

Using the JVM trace file, you can determine when a call to the JVM returns an object reference that must be released, then you can call C$JAVA with CJAVA_DESTROY or CJAVA_DELETE to remove the reference.

For there to be no memory leaks, any call that returns a reference to a Java object needs to be paired with a call to release that reference. When the runtime gets an object reference from the JVM, it is the runtime's responsibility to release the reference. When the runtime calls the JVM, it deletes the local reference to any memory the JVM allocated on behalf of the runtime.

In the JVM, an entity known as the JVM garbage collector also de-allocates memory that is no longer being used. To specify how often the runtime should call the JVM garbage collector, use the A_JAVA_GC_COUNT configuration variable.

See Configuration Variables for more information on these and other configuration variables.

Parent topic: Calling the C$JAVA Routine


C$JAVA Configuration Variables

ACUCOBOL-GT includes several configuration variables for calling Java via the C$JAVA routine.

Configuration Variable | Purpose
PRELOAD_JAVA_LIBRARY | Tells the runtime to preload the JVM on startup
JAVA_LIBRARY_NAME | Specifies the name and path of the JVM library to load
JAVA_OPTIONS | Specifies Java command-line options
A_JAVA_TRACE_FILENAME | Names the file where you want to store JVM call trace information
A_JAVA_TRACE_VALUE | Specifies the types of calls to trace
A_JAVA_GC_COUNT | Specifies how often the runtime should call the JVM garbage collector
A_JAVA_CHARSET | Specifies the character set that the runtime should use when mapping Java strings or PIC X data items containing characters outside of the ISO-8859-1 range. The default setting is "IS0-8859-1".

All of these variables are optional. If desired, you include them in your runtime configuration file, just as you would any ACUCOBOL-GT configuration variable. See Configuration Variables for details on using these variables.

For Java interoperability, your configuration file may look like this:

PRELOAD_JAVA_LIBRARY 1
JAVA_LIBRARY_NAME jvm.dll  (Windows)
JAVA_LIBRARY_NAME libjvm.so (UNIX)
JAVA_OPTIONS -Djava.library.path=c:\java\lib -Xms128m -Xmx128m -classpath c:\java\MyClasses\myclasses.jar (Windows)
JAVA_OPTIONS -Djava.library.path=/java/lib -Xms128m -Xmx128m -classpath /java/MyClasses/myclasses.jar (UNIX)

Both CLASSPATH (java.class.path system property) and the java.library.path must be configured in order for C$JAVA to locate the Java class to run. The CLASSPATH is the location of ".jar" or ".class" files. The java.library.path is the location DLLs or shared objects that are required either by the runtime or by the Java Virtual Machine (JVM).

You can set these properties using the JAVA_OPTIONS variable. This is the first place that the runtime looks when trying to call Java from COBOL. If you prefer, you can set them in the environment:

  • To set the Java system property, java.library.path, set LD_LIBRARY_PATH in the environment.
  • To set the java.class.path property, set a CLASSPATH configuration or environment variable.
Parent topic: Calling the C$JAVA Routine


Configuration and Deployment

To call Java from COBOL using the C$JAVA routine, perform the following steps:

  1. Install and correctly configure an ACUCOBOL-GT runtime. Optionally, install AcuBench if the system will also be used for COBOL development.
  2. Install and correctly configure a JRE version 1.4.2 or later. Optionally, install a J2SE SDK if the same system will also be used for Java development.
  3. Configure the ACUCOBOL-GT runtime as appropriate by creating a runtime configuration file.

    By default, the JVM is loaded by the runtime the first time it executes a CALL "C$JAVA" statement. If you want to preload the JVM, use the PRELOAD_JAVA_LIBRARY variable. Use the JAVA_LIBRARY_NAME variable if you want to specify the DLL that exports the JNI API for loading the JVM. If desired, specify Java command-line options using the JAVA_OPTIONS variable. You can specify additional libraries and classpaths here as well.

  4. Issue a CALL "C$JAVA" statement to call the C$JAVA library routine.
Parent topic: Calling the C$JAVA Routine


Linking the Runtime to "libjvm.sl" on HP-UX

To call C$JAVA on HP-UX platforms, you must first relink the runtime so that it is statically linked to the "libjvm.sl" shared library. Here are instructions:

  1. Edit "Makefile", located in the ACUCOBOL-GT /lib directory. Modify the CC and EXTRA_LDFLAG entries as shown for your port below:

    32-bit Static:

    Original: CC = cc -Ae +DAportable -Wl,+s -D_LARGEFILE64_SOURCE
Modified: CC = cc -mt -Ae +DAportable -Wl,+s -D_LARGEFILE64_SOURCE
Original: EXTRA_LDFLAG =
Modified: EXTRA_LDFLAG = -L /opt/java1.5/jre/lib/PA_RISC2.0/server -ljvm

    32-bit Shared:

    Original: CC = cc -Ae +DAportable -Wl,+s -D_LARGEFILE64_SOURCE +z
Modified: CC = cc -mt -Ae +DAportable -Wl,+s -D_LARGEFILE64_SOURCE +z
Original: EXTRA_LDFLAG = -Wl,+b -Wl,$(ACUVERSPATH)/lib:$(ACUPATH)/lib:.:/usr/lib:/lib
Modified: EXTRA_LDFLAG = -Wl,+b -Wl,$(ACUVERSPATH)/lib:$(ACUPATH)/lib:.:/usr/lib:/lib \   -L /opt/java1.5/jre/lib/PA_RISC2.0/server -ljvm

    64-bit Static:

    Original: CC = cc -Ae +DS2.0 +DA2.0W +DD64 -Wl,+s
Modified: CC = cc -mt -Ae +DS2.0 +DA2.0W +DD64 -Wl,+s
Original: EXTRA_LDFLAG =
Modified: EXTRA_LDFLAG = -L /opt/java1.5/jre/lib/PA_RISC2.0W/server -ljvm

    64-bit Shared:

    Original: CC = cc -Ae +DS2.0 +DA2.0W +DD64 -Wl,+s +z
Modified: CC = cc -mt -Ae +DS2.0 +DA2.0W +DD64 -Wl,+s +z
Original: EXTRA_LDFLAG = -Wl,+b -Wl,$(ACUVERSPATH)/lib:$(ACUPATH)/lib:.:/usr/lib:/lib
Modified: EXTRA_LDFLAG = -Wl,+b -Wl,$(ACUVERSPATH)/lib:$(ACUPATH)/lib:.:/usr/lib:/lib \  -L /opt/java1.5/jre/lib/PA_RISC2.0W/server -ljvm
  2. Rebuild the runtime. In the ACUCOBOL-GT /lib directory execute "make runcbl".
  3. Copy the new "runcbl" to the ACUCOBOL-GT /bin directory.
  4. Set the following in the runtime configuration file:

    32-bit:

    JAVA_LIBRARY_NAME /opt/java1.5/jre/lib/PA_RISC2.0/server/libjvm.sl

    64-bit:

    JAVA_LIBRARY_NAME /opt/java1.5/jre/lib/PA_RISC2.0W/server/libjvm.sl
All:
JAVA_OPTIONS -XX:+UseAltSigs
  5. Set the following in the environment:

    32-bit:

    SHLIB_PATH=/opt/java1.5/jre/lib/PA_RISC2.0/server:/opt/java1.5/jre/lib/PA_RISC2.0;$SHLIB_PATH

    64-bit:

    LD_LIBRARY_PATH=/opt/java1.5/jre/lib/PA_RISC2.0W/server:/opt/java1.5/jre/lib/PA_RISC2.0W;$LD_LIBRARY_PATH
Parent topic: Calling the C$JAVA Routine


Example

The following sample code is a simple COBOL program calling a Java program. It shows the minimum necessary pieces to call a Java method from a COBOL program.

identification division.
program-id.  CobolToJava.
data division.
working-storage section.

01 CLASS-NAME   PIC X(80).
01 METHOD-NAME   PIC X(80).
01 METHOD-SIGNATURE  PIC X(80).
01 STATUS-VAL   PIC S9(02) VALUE ZERO.
01 FIELD-INT  USAGE IS SIGNED-INT.
01 FIELD-RETURN  USAGE IS SIGNED-INT.

procedure division.
main-logic.

move "com.acucobolgt.CVM" TO CLASS-NAME
move "CobolCallingJavaInt" TO METHOD-NAME
move "(I)I" TO METHOD-SIGNATURE
move 0 to FIELD-INT
move -1 to FIELD-RETURN

CALL "C$JAVA" USING CLASS-NAME, METHOD-NAME, METHOD-SIGNATURE, FIELD-INT, FIELD-RETURN GIVING STATUS-VAL.
Parent topic: Calling the C$JAVA Routine


Using C$SOCKET

You can also use the C$SOCKET library routine to facilitate interprocess communication between Java and COBOL programs via sockets. C$SOCKET is a low-level option, but it is very flexible.

When calling Java from COBOL:

  1. The Java programmer creates a server socket and waits for and accepts a connection to the COBOL client.
  2. The COBOL programmer uses the C$SOCKET routine to create a client socket (op-code 1), connect via TCP/IP to the port of the Java program, and write data to the socket (op-code 5).
  3. The Java program reads the data, processes it, returns data to the socket.
  4. The COBOL program uses C$SOCKET to read the data (op-code 6).

Of course, because the data format is totally open and undefined, the COBOL and Java programmers must agree on a common format.

The following sample code demonstrates this capability:

*Create a Client Socket.
CALL "C$SOCKET" USING AGS-CREATE-CLIENT, 8765, SERVER-NAME
GIVING SOCKET-HANDLE.

*Write data to socket.
CALL "C$SOCKET" USING AGS-WRITE, SOCKET-HANDLE,
DATA-FROM-CLIENT, DATA-LENGTH.

*Read the return data from the socket.
CALL "C$SOCKET" USING AGS-READ, SOCKET-HANDLE,
DATA-FROM-CLIENT, DATA-LENGTH.

*Close the socket.
CALL "C$SOCKET" USING AGS-CLOSE, SOCKET-HANDLE.

See C$SOCKET for complete information on the C$SOCKET library routine.

Parent topic: Calling Java from COBOL


Calling the Java Virtual Machine (JVM) DLL or Shared Library

If desired, you can invoke a Java program from COBOL by calling the JVM shared library or DLL and then invoking the routines in that library. In the case of JRE 1.4.2_04, these files are called "jvm.dll" and "libjvm.so". You can call these files in one of two ways:

  1. Load the JVM shared library or DLL into your COBOL program using the CALL statement, then make calls to the JVM functions. For example, in UNIX:
    CALL "libjvm.so"
CALL "JVMfunction"

    For more information on calling DLLs and shared libraries and their functions, see Working with Windows Technologies and Using ActiveX Controls and COM Objects.

    In Windows, you can CALL the DLL to load it, as shown here:

    CALL "JVM.dll"

    Then you can call any of the routines contained in the DLL using the direct C interface. This is described in Working with C and C++ Programs.

  2. Call the JVM through C. ACUCOBOL-GT can make calls to C, and C can make calls to the JVM. See Working with C and C++ Programs for information on how to call C subroutines from ACUCOBOL-GT.
Parent topic: Calling Java from COBOL


Using C$SYSTEM

Another way to invoke a Java program from COBOL is to send a Java command line to the host operating system. You can do this using ACUCOBOL-GT's C$SYSTEM library routine. This routine combines the functionality of the "SYSTEM" and "C$RUN" routines.

To call a Java program from COBOL via C$SYSTEM, you:

  1. Call the C$SYSTEM library routine as described in C$SYSTEM.
  2. Send a Java command line to C$SYSTEM to invoke the Java program. For example, to call the Java program AcuOrders, you might use this code:
    move "javaw -classpath cvm.jar;./ acuprod.AcuOrder"
to the-run-command.
call "C$SYSTEM" using the-run-command.

    The C$SYSTEM routine submits the command line to the host operating system as if it were a command keyed in from the terminal.

    Note that you can call C$RUN instead of C$SYSTEM to run the Java program asynchronously, as in: call "C$RUN" using the-run-command.

  3. Pass data from the Java program to the COBOL program through a disk file or communicate through a database.

See C$SYSTEM and C$RUN for complete information on these library routines.

Parent topic: Calling Java from COBOL


Mapping Java Data Types

When interfacing with external Java systems, it is often necessary to map COBOL data types to Java data types. Following are the Java primitive types:

boolean - 8 bits, unsigned
byte - 8 bits, signed
char - 16 bits, unsigned
short - 16 bits, signed
int - 32 bits, signed
float - 32 bits, signed, floating point
long - 64 bits, signed
double - 64 bits, signed, floating point

All other types are objects that are composed of other objects or primitive types. For example, the String type is an object. Note that encoding of native Java strings and numbers in memory may be different from way you represent data in COBOL.

Even on 32-bit platforms, Java represents longs as 64 bits. On 32-bit platforms, the ACUCOBOL-GT runtime truncates longs to 32 bits regardless of whether the "-Dw32" or "-Dw64" flags are used for compilation. In order to effectively interoperate using Java longs and use all 64 bits on a 32-bit platform, you must use the PIC S9(18) COMP-5 declaration shown below. Also, in order to use the entire range available to Java shorts and ints (short 32767 to -32768 int 2147483647 to -2147483648) with USAGE IS SIGNED-INT and USAGE IS SIGNED-SHORT declarations, the "-Dw32" flag must be specified at compile time.

The following sample declarations have been used to test COBOL/Java interoperability.

01 FIELD-INT USAGE IS SIGNED-INT.
01 FIELD-BOOL pic 9.
01 FIELD-BYTE pic x.
01 FIELD-CHAR pic x.
01 FIELD-SHORT USAGE IS SIGNED-SHORT.
01 FIELD-LONG PIC S9(18) COMP-5.
01 FIELD-FLOAT USAGE IS FLOAT.
01 FIELD-DOUBLE USAGE IS DOUBLE.
01 FIELD-STRING PIC X(80).

Another method of declaring ints and shorts is shown below. With these two declarations, the use of the "--TruncANSI" compiler switch is required so that the range checking is correct for the range the native platform allows. See Truncation Options for information about the "--TruncANSI" option.

01 FIELD-INT PIC S9(9) COMP-5.
01 FIELD-SHORT PIC S9(5) COMP-5.

Currently, ACUCOBOL-GT converts Unicode UTF-16 Java strings to UTF-8 for representation in PIC X variables. If your program uses code points that require more than 16 bits to represent supplementary characters or if it uses UTF-32, then you should use arrays of Java ints to represent the data.

If your Java strings or PIC X data items contain characters outside of the ISO-8859-1 range, you need to instruct the runtime which character set to use by specifying it in the A_JAVA_CHARSET runtime configuration variable. The default setting is "IS0-8859-1". Be aware of a common misconception that ISO-8859-1 is equivalent to Windows-1252. This is for the most true, but there are characters in the range 0x80 - 0x9F that differ. Windows-1252 uses these numbers for letters and punctuation while the ISO-8859-1 uses these for control codes.

Note that Java implementations represent data in big endian format regardless of platform. For considerations on moving data between big endian and little endian hosts, see C$SOCKET and Usage Clause.

Note: Be careful when sending numeric data across the network via sockets, because some machines use different byte ordering than others, and native numeric data can appear swapped on different machines. COMP-4 data is in the order that most network servers expect binary data to be in, so if you are communicating with a non-COBOL client or server, you should use COMP-4 data of the correct size for the machine in question. If your client and server are both COBOL, you can use standard COBOL types.
Parent topic: Working with Java Technology


J2EE Application Servers

In recent years, growing demand for infrastructure that can manage hundreds or thousands of applications, integrate them, perform load balancing, provide messaging services, and so on, has led to a fiercely competitive application server market.

One type of application server software revolves around Sun Microsystems' Java 2 Platform, Enterprise Edition (J2EE). BEA WebLogic Server and IBM WebSphere are the two leading application server products for the development of enterprise Java applications. Other vendors such as Sun, Oracle, SAP, and Sybase also compete in this area.

The second category is the Microsoft Platform, which relies on Windows, .NET, COM+, and other technologies. While Microsoft does not have an application server per se, it provides features in its Windows Server editions that compete with the J2EE application servers.

We provide interoperability with applications written for both the J2EE and Microsoft application server platforms. This section describes integration with J2EE application server platforms. Working with .NET Assemblies describes how to integrate COBOL with .NET.

  • Working with J2EE Application Server Products
Parent topic: Working with Java Technology


Working with J2EE Application Server Products

ACUCOBOL-GT applications can be integrated with application server platforms using any of the methods described in this chapter. Your Java components are managed by the application server, but they can still gain access to COBOL using our CVM class, the C$SOCKET routine, CGI programs, the runtime DLL, or named pipes.

Similarly, your COBOL applications can access your Java components, managed by the application server, via our C$JAVA routine, the C$SOCKET routine, the CALL statement, the C$SYSTEM routine, or named pipes.

Parent topic: J2EE Application Servers


Web Services

Web services are self-contained, modular applications that can be published, located, and invoked across the Web from any location, allowing you to transcend hardware and operating system boundaries. An implementation of SOA, Web services use a standard interface technology to make the services available.

Web service applications perform discrete functions ranging anywhere from simple requests to complicated business processes that combine information from multiple sources. Web services can be developed and componentized internally, or brought in and reused from the outside. To create a robust business solution, you assemble Web services like building blocks into a cohesive entity, mixing and matching software components as you need.

Conceptually, Web services are similar to any application services. What makes them unique is that they describe themselves to the outside world, revealing what functions they perform, how they can be accessed, and what kinds of data they require. Today, this is accomplished with the following standards:

  • Self-description is accomplished via Web Service Description Language (WSDL). Using WSDL, you provide information on all publicly available functions, address information for locating the service, and so on.
  • Services are published and found in the white, yellow, and green pages of a business registry conforming to the Universal Description, Discovery, and Integration (UDDI) specification.
  • All communications to a Web service are encoded in eXtensible Markup Language (XML), using SOAP. SOAP is used to describe how to instantiate a remote procedure call, including the passed data and the returned results.
  • Providing Web Services from COBOL
  • Consuming Web Services in COBOL
Parent topic: Working with Java Technology


Providing Web Services from COBOL

XcentrisityTM Business Information Server

Business Information Server (BIS) is a web server environment for version 9.0 and higher ACUCOBOL-GT applications. It provides a web server extension that integrates with either Microsoft Internet Information Server (IIS) or the Apache web server. it also provides a service engine, which executes ACUCOBOL-GT applications under the control of the web server extension. BIS manages application sessions and makes them available via any web browser or other web user agent that is granted access to the BIS server. BIS offers application developers a real opportunity to build state-of-the-art Service Oriented Architecture (SOA) applications incorporating legacy business data and logic freely mixed with the latest web languages and tools.

BIS is a separately sold and licensed product. See the Xcentrisity BIS Users Guide for more details.

Other Solutions

For those using the J2EE platform, we offer a native Java interface that encapsulates the ACUCOBOL-GT runtime in a JAR file. By invoking the Java class contained in this archive, a Web service running on J2EE can start the runtime and run your COBOL program. Your program becomes a service to another program or service.

Consumers of the COBOL service use their own tools to incorporate a client proxy into their application. On the WebLogic platform, for instance, they use the Web Services Tool Kit (WSTK) of WebLogic Workshop to update their Web service.

As with any Web service, the consumer application must also contain logic for connecting to the COBOL server. It must also be programmed to issue a Web service request to the specified URL via XML/SOAP.

Parent topic: Web Services
Parent topic: COBOL Web Services


Consuming Web Services in COBOL

To enable a COBOL program to consume a Web service, we provide the C$JAVA library routine. The Java programmer packages the WSDL from the Web service in a WAR file with all the necessary resources including a Java client proxy, and the COBOL programmer invokes the service by calling the C$JAVA routine and naming the proxy as a USING parameter.

Parent topic: Web Services


Working with Windows Technologies

  • COBOL and Windows
  • Calling COBOL From Other Windows Programs
  • Calling DLLs from COBOL
  • Working With Open Database Connectivity (ODBC)
  • Accessing the Windows API
  • Using Visual C++ .NET
  • Windows-specific Features of ACUCOBOL-GT
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


COBOL and Windows

ACUCOBOL-GT® is a graphical COBOL language that is uniquely suited for graphical Windows environments. ACUCOBOL-GT not only supports all major Windows technologies, but it runs on most 32-bit and 64-bit versions of the Windows operating system.

Component Object Model (COM), ActiveX®, and .NET are large enough subjects to warrant their own chapters. To learn how to leverage COM and ActiveX in your COBOL programs, see Using ActiveX Controls and COM Objects. To learn to interact with .NET assemblies, see Working With .NET Assemblies.

For information on graphical user interface (GUI) programming (including concepts such as windows, handles, events, methods, menus, and color mapping), see ACUCOBOL-GT User Interface Programming.

Parent topic: Working with Windows Technologies


Calling COBOL From Other Windows Programs

To simplify the process of calling an ACUCOBOL-GT program from other programming languages in a Windows environment, the ACUCOBOL-GT 32-bit Windows runtime is encapsulated in a DLL file. This DLL file has been further encapsulated in a COM server.

To call ACUCOBOL-GT from other Windows programs, you can do one of two things:

  1. Create an object for the ACUCOBOL-GT COM server in the source program and call the methods of that object. This is covered in the topic Using the ACUCOBOL-GT COM server.
  2. Call the ACUCOBOL-GT runtime DLL in the source program. This call requires special declarations, and is explained in Calling the Runtime DLL.

The advantage of using the COM server is that you can treat the ACUCOBOL-GT system as a COM object. You do not need to insert declarations into the source code of the other programming language, you can operate in a multi-threaded environment, and the development environment is more intuitive. Using the ACUCOBOL-GT runtime DLL instead of the COM server can provide slightly improved performance and makes application distribution smaller and installation easier. However, the DLL can be called only from a single thread of execution. For example, if you call a COBOL program from a user interface control's event procedure, and the event procedure is called again before the COBOL program returns, you must detect this case and either wait or inform the user of the error.

Regardless of which approach you choose, when a program written in another language calls an ACUCOBOL-GT program, the data is passed as a pointer to a variant type for each parameter. The ACUCOBOL-GT program receives a handle for each parameter and uses a library routine to convert the data to COBOL types. When ACUCOBOL-GT data items are passed back to this program, they pass through another library routine that converts the data back into variant types. The C$GETVARIANT and C$SETVARIANT library routines are detailed in Library Routines.

The parameters of the COM server methods, or exported DLL functions, are all null-terminated strings, integers, or variant type variables. In some programming languages, such as Visual Basic (VB), the variant type is used by default for any variables that have not been assigned a data type. Because the variant type is used to represent many different types of data, you generally don't have to convert these types of data when they are assigned to a variant variable. The programming language automatically performs any necessary conversion. Because the ACUCOBOL-GT COM server and runtime DLL routines take variant type parameters, it is easy to receive variables from, or return variables to, other languages.

Note: All the examples in this section use Visual Basic as the source language for code samples. Microsoft conventions for object description language are used for the descriptions of method usage.
  • Using the ACUCOBOL-GT COM Server
Parent topic: Working with Windows Technologies
Related concepts
Calling the Runtime DLL


Using the ACUCOBOL-GT COM Server

For ease of use in Windows environments, the ACUCOBOL-GT runtime is available as a COM server. With the COM server, you can treat the ACUCOBOL-GT system as a COM object and include it in applications that support COM.

To use the COM server in other programs:

  1. Register the ACUCOBOL-GT COM server. Registration occurs automatically when you load the ACUCOBOL-GT runtime using the setup program that comes with the software.

    When you distribute your application, if you are not using the ACUCOBOL-GT setup program, you will have to install and register the COM server on each user's machine. If you are using it as a remote server, you must install and register the ACUCOBOL-GT runtime with the COM server option on the server machine. Register the ACUCOBOL-GT COM server by running it with no command-line options or with the "/RegServer" option. This command-line option is not case sensitive.

    Note: On 64-bit operating systems you must run with elevated priviliges.

    The ACUCOBOL-GT COM server executable is in the ACUCOBOL-GT bin directory after installation. This file is named "AcuGT.exe". The ACUCOBOL-GT COM server requires the same files as the ACUCOBOL-GT runtime, except for "wrun32.exe". Two additional files, "AcuGT.exe" and "AcuGT.tlb", must be installed on the machine in a single directory. For the COM server to work, the runtime DLL "wrun32.dll" must either be in the same directory as "AcuGT.exe" or somewhere else in the Windows DLL search path. If you move "AcuGT.exe" to a different directory, you must register it again from the new location.

    Note:

    If you ever need to unregister the ACUCOBOL-GT COM server, run "AcuGT /UnregServer".

  2. Start the other programming language's development environment and add the current "ACUCOBOL-GT Library" to your project references.
  3. Add code to declare and create the AcuGT object. For example, in Visual Basic you could enter:
    Dim cblObj As Object
Set cblObj = New AcuGT
  4. Control the ACUCOBOL-GT COM server using the "Initialize", "Call", "Call50", "Cancel", and "Shutdown" methods described in Methods of the COM server object. For example, from Visual Basic you would enter:
    cblObj.Initialize "-d"   ' Start ACUCOBOL-GT in debug mode
retVal = cblObj.Call(programName, arg0, arg1, arg2)
cblObj.Shutdown

    or use the "With" construct. For example:

    With cblObj
  .Initialize "-e @myserver:\myprogs\errorfile"
  .Call "*myserver:\myprogs\program1.acu", "call1", 1.2, 37
  .Call "*myserver:\myprogs\program1.acu", "call2", 2.3, 38
  .Call "*myserver:\myprogs\program1.acu", "call3", 3.4, 39
  .Cancel "*myserver:\myprogs\program1.acu"
End With

If you don't explicitly call "Initialize", the COM server calls it for you, passing an empty command-line parameter. Likewise, if you don't explicitly call "Shutdown", the COM server calls it for you when the object is destroyed.

In this example, after the AcuGT object is created in Visual Basic, "Initialize" is called automatically. Then, when the AcuGT object is destroyed at the end of the subroutine, the "Shutdown" method is called automatically:

Private Sub Command1_Click()
  Dim cblObj As Object
  Set cblObj = New AcuGT
  cblObj.Call "program"
End Sub

If you have several COBOL calls to make, it is much more efficient to create the AcuGT object as a Public variable in the module, class, or form initialization. For example, this may be done using the Visual Basic CreateObject function:

Dim cblObj As Object
Set cblObj = CreateObject("AcuGT.Application");

The Visual Basic CreateObject function takes an optional second parameter–the name of the network server where the object is created. For example, if you want to run the COBOL program on a remote machine named MOOSE, use the following syntax:

Set cblObj = CreateObject("AcuGT.Application", "MOOSE");

The COM server sets the "current directory" for COBOL programs to the directory containing "AcuGT.exe". This allows you to use relative directory paths when you specify file names. For example, suppose you have installed the COM server in C:\AUTOSRV\BIN, the COBOL programs and configuration files you want to use in C:\AUTOSRV\PROGRAMS and the data files in C:\AUTOSRV\DATA. You could then call the "Initialize" method with "-c ..\PROGRAMS\CONFIG", set CODE_PREFIX to "..\PROGRAMS" and set FILE_PREFIX to "..\DATA".

The ACUCOBOL-GT COM server is thread-safe, meaning that you can run COBOL programs asynchronously. To do this, you must create a new thread and a new AcuGT object in that thread. Then you call the COBOL program from that thread.

For an example of how to create new threads in Visual Basic, see Creating a Multithreaded Test Application in the Visual Basic documentation.

It is a good idea to trap errors and handle them with your own Visual Basic error handler. For example:

   On Error GoTo ErrHandler
   cblObj.Call "program"
Exit Sub

ErrHandler:
   myval = MsgBox(Err.Description, vbOKOnly,
      "Call not successful")
End Sub
  • Methods of the COM Server Object
  • Calling the Runtime DLL
Parent topic: Calling COBOL From Other Windows Programs
Related information
Methods of the COM server object


Methods of the COM Server Object

The ACUCOBOL-GT COM server object has the following methods:

  • Initialize
  • Shutdown
  • Call
  • Call50
  • Cancel
  • Initialize
  • Shutdown
  • Call
  • Call50
  • Cancel
Parent topic: Using the ACUCOBOL-GT COM Server


Initialize

Initializes the ACUCOBOL-GT runtime

Usage

HRESULT Initialize([in] VARIANT *cmdLine)

Return value

"Initialize" returns one of the following result codes (note that these values are given in hexadecimal format):

Name | Value | Description
S_OK | 0 | Call succeeded
ACUGT_E_UNEXPECTED | 80040200 | Unexpected error
ACUGT_E_INITIALIZE | 80040201 | COM initialization failed. Make sure that the COM libraries are the correct version.
Parent topic: Methods of the COM Server Object


Shutdown

Shuts down the runtime

Usage

void Shutdown(void)
Parent topic: Methods of the COM Server Object


Call

Calls the runtime

Usage

HRESULT Call([in] VARIANT *name,
   [in, out, optional] VARIANT *arg0,
   [in, out, optional] VARIANT *arg1,
   [in, out, optional] VARIANT *arg2,
   [in, out, optional] VARIANT *arg3,
   [in, out, optional] VARIANT *arg4,
   [in, out, optional] VARIANT *arg5,
   [in, out, optional] VARIANT *arg6,
   [in, out, optional] VARIANT *arg7,
   [in, out, optional] VARIANT *arg8,
   [in, out, optional] VARIANT *arg9,
   [in, out, optional] VARIANT *arg10,
   [in, out, optional] VARIANT *arg11,
   [in, out, optional] VARIANT *arg12,
   [in, out, optional] VARIANT *arg13 )

Return value

"Call" returns one of the following result codes (note that these values are given in hexadecimal format):

Name | Value | Description
S_OK | 0 | Call succeeded
ACUGT_E_UNEXPECTED | 80040200 | Unexpected error
ACUGT_E_MULTIPLE_THREADS | 80040203 | Call (or Call50) has been called in multiple threads. For more information, see Calling the Runtime DLL.
ACUGT_E_INITIALIZE_FAILED | 80040204 | Initialize failed. (Initialize cannot be called after Shutdown in a single process.) For more information, see Calling the Runtime DLL.
ACUGT_E_PROGRAM_MISSING | 80040205 | Program missing or inaccessible
ACUGT_E_NOT_COBOL | 80040206 | Not a COBOL program
ACUGT_E_CORRUPTED | 80040207 | Corrupted program
ACUGT_E_INADEQUATE_MEMORY | 80040208 | Inadequate memory available
ACUGT_E_UNSUPPORTED | 80040209 | Unsupported version of object code
ACUGT_E_PROGRAM_IN_USE | 8004020A | Program already in use
ACUGT_E_TOO_MANY | 8004020B | Too many external segments
ACUGT_E_CONNECTION_REFUSED | 8004020C | Connection refused; perhaps AcuConnect® is not running.
Parent topic: Methods of the COM Server Object
Related information
Calling the Runtime DLL


Call50

"Call50" calls the runtime in the same way as "Call", except that you may have up to 50 optional parameters. Substitute "Call50" for the word "Call" in the Visual Basic syntax. The return values are exactly the same.

Note:

When you call using "Call" or "Call50", you may not exceed 14 parameters for "Call" or 50 parameters for "Call50".

Parent topic: Methods of the COM Server Object


Cancel

Cancels a COBOL program

Usage

void Cancel([in] VARIANT *program )
Parent topic: Methods of the COM Server Object


Calling the Runtime DLL

For 32-bit Windows users, the ACUCOBOL-GT runtime is available in a DLL file.

To call the runtime DLL from another programming language, you must add certain declarations to the source program. This example shows what you would use in Visual Basic:

Declare Function AcuInitialize Lib "wrun32.dll" _
   (Optional ByVal cmdLine As String) As Integer

Declare Sub AcuShutdown Lib "wrun32.dll" ()

Declare Function AcuCall Lib "wrun32.dll" _
   (ByVal name As String, _
     Optional param1, _
     Optional param2, _
     Optional param3, _
     Optional param4, _
     Optional param5, _
     Optional param6, _
     Optional param7, _
     Optional param8, _
     Optional param9, _
     Optional param10, _
     Optional param11, _
     Optional param12, _
     Optional param13, _
     Optional param14) As Integer

Declare Function AcuCall50 Lib "wrun32.dll" _
   (ByVal name As String, _
     Optional param1, _
...
     Optional param50) As Integer
Note: Two declarations are shown. "AcuCall" supports 14 optional parameters, and "AcuCall50" supports 50 optional parameters. "AcuCall50" has the same format as "AcuCall", except that you must include the full list of 50 parameters in your declaration. The code example for "AcuCall50" was abbreviated.
Declare Function AcuGetCallError Lib"wrun32.dll" () As Integer

Declare Sub AcuCancel Lib "wrun32.dll" (ByVal name As String)

After you add the declarations, you initialize the runtime, call the COBOL program(s) passing the program name and parameters, and shut down when you are finished. For example, in Visual Basic you would perform the following steps:

  1. Call "AcuInitialize" to pass the runtime's command-line options. For example:
    returnValue = AcuInitialize("-c myconfig -le myerrors")

    "AcuInitialize" returns a value of "0" on success and "-1" on failure. You can safely call "AcuInitialize" multiple times. The command line from the first call is used and is ignored on subsequent calls.

    You may use the runtime "-d" option to debug your ACUCOBOL-GT program. Specify "-d" in the command line to "AcuInitialize", and the debugger window appears when you actually call a COBOL program.

  2. Call "AcuCall" or "AcuCall50", passing the program name and parameters. For example, to call the program "vb-test" with "AcuCall", enter:
    returnValue = AcuCall("vbtest.acu", testNum,
   testStr, testLongNum, testFloat)

    "AcuCall" returns "0" on success and "-1" on failure. If "AcuInitialize" hasn't been called yet, "AcuCall" calls it, passing an empty command line. If "AcuCall" returns "-1", you may call "AcuGetCallError" to get the error code. The error codes are as follows:

    -4 | "AcuCall" (or "AcuCall50") has been called in multiple threads.
    -3 | "AcuInitialize" failed. ("AcuInitialize" cannot be called after "AcuShutdown" in a single process.)
    1 | Program missing or inaccessible
    2 | Not a COBOL program
    3 | Corrupted program
    4 | Inadequate memory available
    5 | Unsupported version of object code
    6 | Program already in use
    7 | Too many external segments
    25 | Connection refused; perhaps AcuConnect is not running
    27 | Program contains object code for a different processor
    28 | Incorrect serial number
    30 | License error
    Note: Two calls are available to you. "AcuCall" supports 14 optional parameters, and "AcuCall50" supports for up to 50 optional parameters. "AcuCall50" calls the runtime in the same way as "AcuCall", just use the appropriate name in the Visual Basic syntax. The return values are exactly the same. The declaration is similar, but you must declare all 50 parameters.
  3. Call "AcuShutdown" after you are completely finished using COBOL in your Visual Basic application. It is absolutely essential to call "AcuShutdown" from the VB program after the final call to COBOL. Failure to call "AcuShutdown" before the VB program ends will likely cause the Visual Basic integrated environment to crash, resulting in the loss of any unsaved VB program changes.
    Note: If a COBOL program issues a STOP RUN, "AcuCall" returns, the runtime environment is initialized, and the calling process continues running. This sequence occurs so that STOP RUN does not shut down the calling application or development environment you are using.
  4. To cancel a COBOL program, call "AcuCancel" passing the name of the program. For example:
    AcuCancel("vbtest.acu")
Parent topic: Using the ACUCOBOL-GT COM Server


Calling DLLs from COBOL

ACUCOBOL-GT programs can call native code subroutines located in DLLs. This includes files with a ".dll" extension and Windows system files with a ".drv" or ".ocx" extension. You do not need to relink the runtime to access the routines in DLLs.

To use a routine located in a DLL, you must first load the DLL in one of three ways:

  • Using the CALL statement
  • Using configuration variables
  • Using the "-y" runtime option
Note: If you are loading a DLL that contains Windows API functions, please see Accessing the Windows API. This topic contains some specific guidelines and procedures that you should know when calling Windows API functions.
  • Loading DLLs with the CALL Statement
  • Loading DLLs with Configuration Variables
  • Loading DLLs with the -y Runtime Option
Parent topic: Working with Windows Technologies
Related information
Accessing the Windows API


Loading DLLs with the CALL Statement

To load the dynamic link library "mylib.dll", you would CALL either "mylib.dll" or simply "mylib". The runtime automatically appends ".dll" when searching for a DLL. The runtime searches for DLLs after it has searched for COBOL programs. It first searches the paths defined in the CODE_PREFIX configuration variable, and then in the System and Windows folders, respectively (actually, folder names vary depending on the specific version of Windows and user customizations). If you do not want the runtime to look in the System or Windows folders, set the DLL_USE_SYSTEM_DIR configuration variable to "0" (off, false, no).

Note: By default, the runtime also recognizes ".drv" and ".ocx" files, which enables you to load these file types just as you would a ".dll". For backwards compatibility, you can turn this feature off by setting the runtime configuration variable "USE_WINSYSFILES" to "0" (off, false, no). Then, only calls to ".dll" files are supported.

You can give the runtime a simpler name for a DLL. The runtime will prepend various append various suffixes to the name given, searching sequentially through the list of names until a name is found that can be loaded.

On Windows, the runtime will first try the name as given and then append in order ".dll" and ".ocx".

The CALL statement that loads a DLL simply makes the routines contained in the DLL available to the COBOL program. The one exception to this is if the DLL contains a routine whose name is the same as the DLL. In this case, the routine is immediately called. For example, if the DLL "mylib.dll" contains a routine called "mylib", then

CALL "mylib"

both loads the DLL and executes the MYLIB routine. To load the library and avoid calling the subroutine of the same name, specify ".dll" explicitly in the CALL statement, as shown below:

CALL "mylib.dll"

Thin client applications may call DLLs on the display host (client) by adding "@[DISPLAY]:" to the beginning of the CALL name. For example, to call a DLL named "mylib" on the client, you would use the following code:

CALL "@[DISPLAY]:mylib.dll"

For complete information, Calling Dynamic Link Libraries (DLLs), in the AcuConnect User's Guide.

Once the library has been loaded, all of the routines it contains can be called. For example:

CALL "funcA"

Loaded DLLs are searched immediately prior to searching for COBOL programs on disk. Routines contained in a DLL are called using either the direct C interface or the Pascal/WINAPI interface. As a result, you may pass parameters BY VALUE if that is required by the routine.

Routines called by this method are assumed to use either the cdecl (standard C) or stdcall (Pascal/WINAPI) parameter passing conventions. Most of the Windows API library functions are stored in DLLs and must be called using the stdcall (Pascal/WINAPI) calling convention.

By default, the runtime uses the value of the DLL_CONVENTION configuration variable to determine the calling convention. A maximum of 16 parameters can be passed using the stdcall DLL_CONVENTION. A maximum of eight parameters can be passed using the cdecl (standard C) DLL_CONVENTION (the default). See DLL_CONVENTION for more details. If you attempt to call a routine that uses a different calling convention, the results are undefined (and usually fatal).

You can override the calling convention for an individual function by specifying it after the function name in the CALL statement.

To specify the stdcall calling convention, append one of the following strings to the function name: @, @1, @WINAPI, @__stdcall. (The @__stdcall string has two underscores.) For example:

CALL "funcA@"

or

CALL "funcA@1"

or

CALL "funcA@WINAPI"

or

CALL "funcA@__stdcall"

calls funcA using the stdcall calling convention.

To specify the cdecl calling convention, append one of the following strings to the function name: @0, @STDC, @__cdecl. (The @__cdecl string has two underscores.) For example:

CALL "funcB@0"

or

CALL "funcB@STDC"

or

CALL "funcB@__cdecl"

calls funcB using the cdecl calling convention.

The runtime uses the specified calling convention and ignores the value of the DLL_CONVENTION configuration variable. Note that you cannot specify the calling convention for a DLL when specifying a DLL name in a CALL statement. You can, however, specify the calling convention for DLLs using configuration variables. Specifying conventions for individual functions in the CALL statement overrides any other conventions specified for the DLL name.

If desired, you could specify the calling convention for individual functions in the runtime configuration file instead of in the CALL statement. To do this, set the CODE_MAPPING variable to "1". If you use the following configuration entries:

CODE_MAPPING=1
funcA=funcA@__stdcall
funcB=funcB@__cdecl

then

CALL "funcA"

calls funcA using the stdcall calling convention and

CALL "funcB"

calls funcB using the cdecl convention.

If you have access to a library (".lib") file for the DLL, you can determine the calling convention for a particular function using the Microsoft COFF Binary File Dumper utility. Run "dumpbin /exports <library name>". If the function name is preceded by an underscore and followed by an "at" sign ("@") and a decimal number, the function expects to be called using the stdcall calling convention. If the name of the function is not followed by an at sign, then the function expects to be called using the cdecl convention.

Like other programs that are loaded with a CALL statement, you can unload a CALLed DLL with a CANCEL statement. When you CANCEL a DLL, you may no longer call its component libraries. Also, unless the logical cancels feature is enabled, all memory used by the program is released. For information about runtime memory management and the logical cancels feature, see Memory Management.

Note: The CANCEL_ALL_DLLS configuration variable can be used to control whether CANCEL ALL frees DLLs. See CANCEL ALL for more details.
Parent topic: Calling DLLs from COBOL


Loading DLLs with Configuration Variables

Another way to load DLLs is to list them in the SHARED_LIBRARY_LIST configuration variable. SHARED_LIBRARY_LIST lets you specify a list of libraries to be automatically loaded by ACUCOBOL-GT at run time. It can be set in the environment, in the runtime configuration file, or programmatically with the SET ENVIRONMENT statement.

The library names in SHARED_LIBRARY_LIST are delimited by spaces or colons on UNIX and spaces or semicolons on Windows (like directories specified in the PATH variable). You can also specify both the name of the DLL and the calling convention to use. Any calling convention specified this way overrides the DLL_CONVENTION variable setting.

For example, to specify the stdcall calling convention for "mylib.dll", you might include the following in your configuration file:

SHARED_LIBRARY_LIST=mylib.dll@__stdcall

This indicates that every function in "mylib.dll" should be called using the stdcall convention, regardless of the DLL_CONVENTION setting.

To specify the cdecl calling convention, you might include:

SHARED_LIBRARY_LIST=mylib.dll@__cdecl

This indicates that every function in "mylib.dll" should be called using the cdecl convention, regardless of the DLL_CONVENTION setting.

If you have access to a library (".lib") file for the DLL, you can determine the calling convention for a particular function using the Microsoft COFF Binary File Dumper utility, as described in the previous section. Run "dumpbin /exports <library name>". If the function name is preceded by an underscore and followed by an at sign and a decimal number, the function expects to be called using the stdcall calling convention. If the name of the function is not followed by an at sign, then the function expects to be called using the cdecl convention.

Note that the SHARED_LIBRARY_LIST configuration variable does not load client-side DLLs for thin client applications that make calls using the CALL verb @[DISPLAY]: syntax. These applications must explicitly load the DLL by calling it with the CALL verb before calling a function within the DLL. You can, however, call DLLs on the server using SHARED_LIBRARY_LIST.

See Configuration Variables for more information on any of the configuration variables discussed in this section.

Note: To use shared libraries without CALLing them first, you can use the "-y" runtime option to place shared libraries on the command line. The runtime then uses the usual search logic to find the specified libraries when trying to resolve CALLs.
Parent topic: Calling DLLs from COBOL


Loading DLLs with the -y Runtime Option

You can load DLLs by specifying "-y" on the command line at run time. You enter "-y" followed by the DLL name to load. Specifying:

 -y lib1.dll -y lib2.dll -y lib3.dll

is equivalent to specifying

SHARED_LIBRARY_LIST=lib1.dll;lib2.dll;lib3.dll

You can also specify the calling convention in the "-y" argument. For example:

wrun32 ... -y lib1.dll@_stdcall -y lib2.dll@_cdecl

Note that the "-y" runtime option does not load client-side DLLs for thin client applications that make calls using the CALL verb @[DISPLAY]: syntax. These applications must explicitly load the DLL by calling it with the CALL verb before calling a function within the DLL. You can, however, call DLLs on the server using the "-y" option.

See Using the Compiler for more details on the "-y" runtime option.

Parent topic: Calling DLLs from COBOL


Working With Open Database Connectivity (ODBC)

To provide flexible interaction between your COBOL applications and data and popular commercial applications and data in the Windows environment, we offer two different ODBC interface technologies.

The first, Acu4GL® for ODBC, is designed to give your ACUCOBOL-GT applications access to ODBC-compliant data sources such as Microsoft Access. You can use standard COBOL I/O statements to access these data sources, locally or remotely.

The second, AcuXDBC™, gives ODBC-enabled applications such as Microsoft Word, Excel, and Access access to Vision data. Business Intelligence tools such as Crystal Reports® Professional, and custom applications developed in ODBC supported environments such as Visual Basic® are supported as well. AcuXDBC also works with Java Database Connectivity (JDBC).

This section provides general information about using our ODBC interfaces. For detailed instructions, see the Acu4GL User's Guide and the AcuXDBC User's Guide.

  • What Is ODBC?
Parent topic: Working with Windows Technologies


What Is ODBC?

Developed by Microsoft, ODBC is a library of standardized data access functions used to connect Windows applications to relational and non-relational databases. It is intended to give programmers a way to access and manipulate data in a variety of dissimilar data sources. ODBC can access a wide variety of file systems because it takes advantage of their common properties and common standards.

With traditional call-level interfaces, you need to learn the API for each data source and application. If you want to extend an application to support an additional data source, or port an application from one data source to another, you must write a complete new access module.

ODBC was designed expressly to provide access to any ODBC-compliant data source. It offers a standard API that can be used to manipulate data in a Microsoft Access database on your PC, or connect from your PC to an Oracle database on a UNIX host. It can even access files that are not databases, such as Excel spreadsheets.

Our two ODBC products, AcuXDBC and Acu4GL for ODBC, are designed to ease the use of ACUCOBOL-GT applications and data in a Microsoft Windows environment. Together, these ODBC interfaces give our customers a broad level of application and data flexibility.

The front-end ODBC product is known as Acu4GL for ODBC. ACUCOBOL-GT uses Acu4GL libraries to access information stored in relational database management systems (RDBMSs). Data dictionaries generated by the compiler guide the libraries in mapping the field names and data types that are passed between COBOL and the database engine. The essence of Acu4GL libraries is that standard COBOL I/O statements are used to access databases. Acu4GL dynamically generates industry-standard SQL from the COBOL I/O statements. As the ACUCOBOL-GT runtime module is executing your COBOL application, Acu4GL is running "behind the scenes" to match up the requirements and rules of both COBOL and the RDBMS to accomplish the task set by your application.

AcuXDBC can be used as a back-end ODBC product. AcuXDBC gives ODBC-enabled Windows applications seamless access to ACUCOBOL-GT Vision files. AcuXDBC Server is an add-on to AcuXDBC that supports remote processing on a Windows NT/2000/2003/2008, UNIX, or Linux server. Whether your Vision data is on a Windows machine, network server, or UNIX server, AcuXDBC can make it accessible to many popular Windows applications, including Excel, Word for Windows, Access, and Microsoft Query.

Parent topic: Working With Open Database Connectivity (ODBC)


Accessing the Windows API

The Windows API lets you develop applications that take advantage of the features and capabilities of the Windows operating system. In essence, the Windows API provides building blocks that can be used by applications written for Windows, regardless of the language those applications are written in.

If desired, you can call Windows API functions from ACUCOBOL-GT, giving your COBOL program features and functions that are unique to Windows. You can give your application a graphical user interface; display graphics and formatted text; and manage system objects such as memory, files, and processes. Literally hundreds of Windows API functions are available.

Windows API functions are contained in DLLs. To access a Windows API function from ACUCOBOL-GT, you load the DLL and then call the function. The procedure for this is outlined in Calling a Windows API Function from ACUCOBOL-GT.

Before you get started, you should become familiar with the documentation that is available, the DLLs that you'll use most often, and some guidelines specific to ACUCOBOL-GT and data mapping. This information is provided in the section Windows-specific Features of ACUCOBOL-GT.

  • Microsoft Documentation
  • Useful Windows API DLLs
  • Calling a Windows API Function from ACUCOBOL-GT
Parent topic: Working with Windows Technologies


Microsoft Documentation

Microsoft Corporation documents the Windows APIs in two main places: in the Microsoft Software Developer's Kit (SDK), and on the Web site, msdn.microsoft.com. Both of these are excellent sources of information on the various Windows API functions. In order to learn how to access and use a Windows API function, you need to refer to these documents frequently.

In the documentation for each function, you can learn the DLL name that contains the function (the DLL name to call) and whether or not ANSI and Unicode versions are available (for functions that handle text). All of this information is listed in the requirements table for the function.

If both Unicode and ANSI versions of the function are available, you must append an "A" or "W" to the function name when you call it in ACUCOBOL-GT. "A" stands for ANSI, "W" for wide code/Unicode. For instance, the GetUserName function is implemented as GetUserNameW (Unicode) and GetUserNameA (ANSI). In some cases, the requirements table supplies the function names for Unicode and ANSI. In other cases it simply states:

Unicode:  Implemented as Unicode and ANSI versions

Either way, be sure to include the "A" or "W" in the function name to indicate which version you want to call.

Note that Windows API function names are case sensitive. You must adhere to case sensitivity of the function name when you call it.

Finally, the Microsoft documentation defines the parameters for the Windows API functions. You will create variables for each of these parameters in your program's Working-Storage Section.

Parent topic: Accessing the Windows API


Useful Windows API DLLs

Although many Windows API DLLs are available, the following three may be used frequently:

  • "user32.dll", for clipboard functions
  • "kernel32.dll", for Getxxx functions
  • "mpr.dll", for network functions

To see a list of the functions available in these or any DLLs, place the DLL in your \system directory then run the utility known as "depends.exe". The "depends.exe" file is in the \tools directory of the Microsoft SDK.

Parent topic: Accessing the Windows API


Calling a Windows API Function from ACUCOBOL-GT

The following sections provide some general rules and guidelines for calling a Windows API function from ACUCOBOL-GT.

  • General Rules
  • Data Mapping
  • Limits
  • Procedure
Parent topic: Accessing the Windows API


General Rules

  1. You must load the DLL to call it's function. (Even if it is already loaded by the system, you must implement it.) There are three ways to load a DLL in ACUCOBOL-GT: you can CALL it, use the "-y" runtime option, or use the SHARED_LIBRARY_LIST configuration variable. These are described fully in the section Calling DLLs from COBOL of this chapter.
  2. If you CALL a DLL, you can enter any of the following:
    CALL "MyDll"
CALL "MyDll.dll"
CALL "C:\MyDir\MyDll.dll"

    We recommend the middle option. The last won't work if your system is mobile. If you set CODE_PREFIX, the runtime looks for the DLL in the CODE_PREFIX directory. If it is not found, it also tries the Windows system directory.

  3. You must indicate the DLL calling convention in your COBOL program. The vast majority of the time, the convention for Windows API DLLs is WINAPI also known as stdcall. You can specify calling conventions in ACUCOBOL-GT in several ways:
    • Using the DLL_CONVENTION variable. To indicate WINAPI/stdcall, you would set DLL_CONVENTION to "1".
    • Using the SHARED_LIBRARY_LIST variable
    • In the CALL statement for individual library functions
    • Setting the CODE_MAPPING variable to "1", then using configuration entries to specify the calling convention for individual functions
    • Using the "-y" runtime option

      See Loading DLLs with the CALL Statement for a description of the nuances of specifying calling conventions.

  4. You must indicate "A" or "W", ANSI/wide, in the function name if both ANSI and Unicode versions of the function are available. See Microsoft Documentation for a more detailed description.
  5. You must adhere to case sensitivity of the function name.
  6. You must terminate any strings that you pass to a function. Use x"00" (LOW-VALUES) as in the following examples:
    STRING "My example" LOW-VALUES DELIMITED BY SIZE INTO target-string.

    or

    INSPECT target-string REPLACING TRAILING SPACES BY x"00".
  7. Do not use literals with Windows functions.
  8. You must map your ACUCOBOL-GT handle to the Windows handle. For example:
    INQUIRE acuhandle SYSTEM HANDLE IN syshandle

    Then "syshandle" can be passed on to the Windows API function. You declare the handle in Working-Storage like this:

    77 syshandle USAGE PIC X(4) COMP-N.
  9. You should cancel the DLL when finished using it. For example:
    CANCEL "mydll.dll".

    Note that DLLs loaded with "-y" or SHARED_LIBRARY_LIST cannot be cancelled or unloaded.

  10. Always pass string variables BY REFERENCE. In C, BY REFERENCE is indicated by an "&". You can also use BY REFERENCE when the data type is prefixed with LP, as in LPSTR.

    You can pass a numeric value BY REFERENCE or BY VALUE, depending on how the function is implemented. See Microsoft Documentation for more information.

    CALL a function BY CONTENT to make a copy of it and provide an address to the copy. This lets users read, not modify, content.

  11. Most Windows API functions return only "true" or "false" when they succeed or fail. You must call GetLastError for specific reasons.
  12. Whatever memory you allocate via ACUCOBOL-GT's M$ALLOC routine, it is your responsibility to release/free via M$FREE.
Parent topic: Calling a Windows API Function from ACUCOBOL-GT


Data Mapping

  1. When mapping Windows API data types to COBOL, you can use COMP-5 or COMP-N as shown below:
    Windows | COBOL | Data Size
    char[n], str[n], tchar[n] | PIC X(n) | n bytes
    long, int PIC X(4) COMP-N

    or

    PIC S9(9) COMP-5

             4 bytes
    dword, ulong, lpxxx, float PIC X(4) COMP-N

    or

    PIC 9(9) COMP-5

             4 bytes
    short PIC X(2) COMP-N

    or

    PIC S9(5) COMP-5

             2 bytes
    word, ushort PIC X(2) COMP-N

    or

    PIC 9(5) COMP-5

             2 bytes

    We recommend using COMP-N for most cases, although COMP-N data types are HEX, unsigned, and thus difficult for negative numbers.

    If you want to use COMP-5, be sure to use the "--TruncANSI" compiler option. This causes truncation in binary to the capacity of the allocated storage for COMP-5 items. (By default, ACUCOBOL-GT truncates in decimal to the number of digits given in the PICTURE clause on arithmetic and non-arithmetic stores into COMP-5 items.) Note that the "-Dz" option overrides "--TruncANSI".

  2. When defining C data types in COBOL, remember to maintain the data size shown in the table. It is imperative to make items the same, static size.
  3. A structure is a group of data, a virtual container for many different C data items. To include a C structure (struct) in ACUCOBOL-GT, ignore the first and last line in the structure, and create a COBOL group item as shown in the following example:

C structure to include:

typedef struct _WIN32_FIND_DATA {
  DWORD     dwFileAttributes;
  FILETIME  ftCreationTime;
  FILETIME  ftLastAccessTime;
  FILETIME  ftLastWriteTime;
  DWORD     nFileSizeHigh;
  DWORD     nFileSizeLow;
  DWORD     dwReserved0;
  DWORD     dwReserved1;
  TCHAR     cFileName[ MAX_PATH ];
  TCHAR     cAlternateFileName[ 14 ];
} WIN32_FIND_DATA, *PWIN32_FIND_DATA;

Resulting ACUCOBOL-GT group item:

01 WIN32-FIND-DATA.
  03 dwFileAttributes   PIC X(4) COMP-N.
  03 ftCreationTime.
     05 dwLowCreateDT   PIC X(4) COMP-N.
     05 dwHighCreateDT  PIC X(4) COMP-N.
  03 ftLastAccessTime.
     05 dwLowAccessDT   PIC X(4) COMP-N.
     05 dwHighAccessDT  PIC X(4) COMP-N.
  03 ftLastWriteTime.
     05 dwLowWriteDT    PIC X(4) COMP-N.
     05 dwHighWriteDT   PIC X(4) COMP-N.
  03 nFileSizeHigh      PIC X(4) COMP-N.
  03 nFileSizeLow       PIC X(4) COMP-N.
  03 dwReserved0        PIC X(4) COMP-N.
  03 dwReserved1        PIC X(4) COMP-N.
  03 cFileName          PIC X(260).
  03 cAlternateFileName PIC X(14).
Parent topic: Calling a Windows API Function from ACUCOBOL-GT


Limits

ACUCOBOL-GT does not support:

  • Callback functions
  • Microsoft Foundation Class (MFC) objects

In addition, the GetMessage function causes the ACUCOBOL-GT runtime to stop while the function waits for a message. Use PeekMessage instead. If no message is sent, the function returns.

Parent topic: Calling a Windows API Function from ACUCOBOL-GT


Procedure

To call a Windows API function:

  1. Determine the name of the desired function and the DLL containing the function by looking at Microsoft's documentation. Also determine if both ANSI and Unicode versions are supported. For example:
    Unicode:  Implemented as GetUserNameW (Unicode) and GetUserNameA (ANSI)
Required DLL:  AdvAPI32.DLL
  2. Find the parameters for the desired function in the documentation. For example, the parameters for GetUserName are:

    lpBuffer: Pointer to the buffer to receive the null-terminated string containing the user's logon name

    nSize: On input, this variable specifies the size of the lpBuffer buffer, in TCHARs. On output, the variable receives the number of TCHARs copied to the buffer, including the terminating null character.

  3. In your ACUCOBOL-GT program's Working-Storage Section, create a variable for each of the Windows API function parameters. For example:
    77 user-name PIC X(40).
77 var-size PIC 9(9) COMP-5.
  4. Set the DLL calling convention for the function in your program's Procedure Division. For example:
    set environment "dll_convention" to 1.
  5. Load the DLL containing the Windows API function. For example:
    Call "advapi32.dll"
On exception go to err-load
  6. Call the Windows API function. For example:
    Set var-size to size of user-name.
call "GetUserNameA" using
by reference user-name
by reference var-size

    Other functions have parameters requiring the use of BY VALUE instead of BY REFERENCE. Read the Microsoft documentation carefully to make sure you pass parameters the proper way.

  7. Terminate any strings that will be returned by the function. For example:
    inspect user-name replacing all low-values by space.
  8. Cancel or unload the DLL if appropriate. For example:
    cancel "advapi32.dll"

    Note that DLLs loaded with "-y" or SHARED_LIBRARY_LIST cannot be cancelled or unloaded.

These general steps should be enough to get you started.

Parent topic: Calling a Windows API Function from ACUCOBOL-GT


Using Visual C++ .NET

This section describes how to use ACUCOBOL-GT in conjunction with Visual C++ .NET. Visual C++ .NET, together with Visual Studio .NET, provides a 32-bit Windows software development kit.

Generally speaking, you use Visual C++ .NET to write various C subroutines that provide a specialized interface between your COBOL applications and the Windows operating system interfacing to under Windows. You then build a new ACUCOBOLGT runtime that contains these C subroutines, and you make calls to these routines from your COBOL application. You can also use this procedure to call code produced by code generators.

The remainder of this section assumes you are familiar with C and Visual C++ .NET. For information on including .NET assemblies in your COBOL program, or calling COBOL from a .NET application, see Working With .NET Assemblies.

  • Building a New Runtime
  • User Interface Approaches
Parent topic: Working with Windows Technologies


Building a New Runtime

Working with C and C++ Programs covers the details of writing C subroutines and passing parameters between those routines and COBOL. You may use any of the interface methods described there to call your C routines.

After you've written your routines, you'll need to link them into the runtime system. This process builds a new "wrun32.dll" that contains your routines.

In order to build a new runtime, you must have the ACUCOBOL-GT Windows runtime and Visual C++ .NET installed. The files that you need to rebuild the runtime can be found in the "library" subdirectory of the main ACUCOBOL-GT directory. To link, load "wrun32.sln" into Visual C++ .NET and perform a build. For more information, see Working with C and C++ Programs.

Important tips before you rebuild the runtime

You may add your C routines directly to the "sub.c" or "mswinsub.c" files provided with ACUCOBOL-GT. More likely, you'll want to create your own files that hold your routines. If you do this, add the files to the "wrun32" project.

The file "mswinsub.c" contains useful declarations that you may want to use in your C subroutines. In particular, you will find variables for the "instance" and "main window" handles used by ACUCOBOL-GT. Also, you will find a start-up routine to which you can add your initialization code.

Parent topic: Using Visual C++ .NET


User Interface Approaches

You can use Visual C++ .NET for many things that don't directly affect the user interface. For example, you can add dynamic data exchange with another application. If you want to add user interface code, however, you must decide whether to build your user interface using a mix of COBOL and C, or whether to use C alone. This decision affects how your code interacts with the runtime system.

  • Using C Only, no COBOL
  • Using C and COBOL
Parent topic: Using Visual C++ .NET


Using C Only, no COBOL

If you build your interface entirely in C, then you have complete flexibility in how the interface works. In this case, you either want to run the runtime system with the "-b" command-line option, or set the configuration variable NO_CONSOLE to "1". When you do this, the runtime won't create its own application window. Instead, your C code must build its own window. When you take this approach, you may not use ACCEPT or DISPLAY verbs in your COBOL program (except for those that don't interact with the screen or keyboard). This approach also works well with a user interface created by a code-generating tool.

Parent topic: User Interface Approaches


Using C and COBOL

If you want to use COBOL in conjunction with C, you must take care to cooperate with the runtime system in how the screen is displayed.

In some cases, you don't need to worry about the runtime system, because 32-bit Windows manages everything. Generally speaking, this occurs when your C code displays data in its own window. For example, you can display and accept data from a dialog box without interacting with the runtime system (all you need is the handle of the runtime's window, which you have in "mswinsub.c").

In other cases, you'll need to cooperate with the runtime's message handler. For example, if you want to display a graphical object in the main application window, you must monitor "paint" messages to the runtime system and draw your object when appropriate. The general technique for doing this is called "subclassing." When you subclass a window, you instruct 32-bit Windows to pass all of its messages to your own message handler. Typically, your message handler acts on one or more messages and then passes all the messages to the original message handler. For detailed instructions on subclassing, see any 32-bit Windows programming text. The following is an example of a typical case.

Suppose that you want to intercept messages to the runtime system and pass them to a routine called "MyMsgHandler". You would first declare "MyMsgHandler" as a function designed to be called from 32-bit Windows:

LRESULT CALLBACK MyMsgHandler( HWND, UINT, WPARAM, LPARAM );

Next, in your start-up code, you would get the address of the ACUCOBOL-GT message handler and then direct 32-bit Windows to send messages to your handler instead. The code reads like this:

FARPROC  lpfnMyMsgHandler, lpfnAcuWndProc;

lpfnMyMsgHandler = MakeProcInstance((FARPROC) MyMsgHandler, hAcuInstance );
lpfnAcuWndProc = (FARPROC) GetWindowLong( hAcuWnd, GWL_WNDPROC );
SetWindowLong( hAcuWnd, GWL_WNDPROC, (long) lpfnMyMsgHandler );

At this point, all messages that 32-bit Windows would normally direct to the ACUCOBOL-GT main window procedure are instead received by "MyMsgHandler". Your message handler should intercept and act on the messages it cares about. At the end, it should pass each message on to the original message handler and return the result. This is usually done with a line that reads like this:

return CallWindowProc( lpfnAcuWndProc, hWnd, iMsg, wParam, lParam );

For reference, ACUCOBOL-GT for 32-bit Windows currently acts on the following messages:

WM_ACTIVATE | WM_LBUTTONUP
WM_ACTIVATEAPP | WM_MBUTTONDBLCLK
WM_CHAR | WM_MBUTTONDOWN
WM_CLOSE | WM_MBUTTONUP
WM_COMMAND | WM_MEASUREITEM
WM_CREATE | WM_MOUSEMOVE
WM_CTLCOLOR | WM_NCLBUTTONDBLCLK
WM_CTLCOLORBTN | WM_NCLBUTTONDOWN
WM_CTLCOLOREDIT | WM_NCPAINT
WM_CTLCOLORLG | WM_PAINT
WM_CTLCOLORLISTBOX | WM_PALETTECHANGED
WM_CTLCOLORMSGBOX | WM_QUERYDRAGICON
WM_CTLCOLORSCROLLBAR | WM_QUERYENDSESSION
WM_CTLCOLORSTATIC | WM_QUERYNEWPALETTE
WM_DESTROY | WM_RBUTTONDBLCLK
WM_DRAWITEM | WM_RBUTTONDOWN
WM_ENDSESSION | WM_RBUTTONUP
WM_ERASEBKGND | WM_SETCURSOR
WM_GETMINMAXINFO | WM_SETFOCUS
WM_HSCROLL | WM_SIZE
WM_INITMENU | WM_SIZING
WM_INITMENUPOPUP | WM_SYSCHAR
WM_KEYDOWN | WM_SYSCOLORCHANGED
WM_KILLFOCUS | WM_SYSCOMMAND
WM_LBUTTONDBLCLK | WM_TIMER
WM_LBUTTONDOWN | WM_VSCROLL

See the Visual C++ .NET documentation for details about these messages.

Parent topic: User Interface Approaches


Windows-specific Features of ACUCOBOL-GT

The following sections describe ACUCOBOL-GT behaviors that are unique to 32-bit Windows environments.

  • Message Boxes
  • Hardware Error Handling
  • Special Characteristics of 32-bit Windows
  • Memory
  • SYSTEM Library Routine
  • C$SYSTEM Library Routine
  • ACCEPT SYSTEM-INFORMATION FROM SYSTEM-INFO
  • Assembly Routines
  • C$CHAIN Library Routine
  • Windows-specific Library Routines
Parent topic: Working with Windows Technologies


Message Boxes

ACUCOBOL-GT applications deployed in 32-bit Windows environments can make use of the native Windows message box facility. A message box is a simple pop-up window that provides information to the user. In some instances it accepts a response (such as Yes or No) from the user. For further details, see DISPLAY MESSAGE BOX.

Parent topic: Windows-specific Features of ACUCOBOL-GT


Hardware Error Handling

Use the WIN_ERROR_HANDLING configuration variable to determine how hardware errors are handled.

When this variable is set to "1" (the default), certain errors are handled directly by 32-bit Windows, and do not automatically return a file error code. For these errors, a dialog box is displayed that describes the error and offers Cancel and Retry buttons. The user may correct the error and click Retry. If the user clicks Cancel, then your program receives the file error that it would have normally received.

If you set WIN_ERROR_HANDLING to "0", then the dialog box is not shown and your program receives the error directly.

Parent topic: Windows-specific Features of ACUCOBOL-GT


Special Characteristics of 32-bit Windows

In many ways, the 32-bit Windows environment operates quite differently from other environments. Included in these differences are memory access methods, interfaces to other languages, file extensions, and hardware error messages. Some of these differences could affect the way your programs execute.

Parent topic: Windows-specific Features of ACUCOBOL-GT


Memory

The ACUCOBOL-GT runtime for 32-bit Windows is designed to handle memory management issues for you automatically.

Parent topic: Windows-specific Features of ACUCOBOL-GT


SYSTEM Library Routine

The SYSTEM routine can be used to initiate 32-bit Windows and console-mode programs. In either case, the program you start runs in its own window. While the called program is running, the window containing the calling program does not accept input from the user.

When CALL "SYSTEM" is used to initiate a program, it looks only for files with a ".exe" extension. If you want to call a ".com" or ".bat" file, you must explicitly add that extension in your code. For example:

CALL "SYSTEM" USING "MYBATCH.BAT"

See SYSTEM for more information.

Parent topic: Windows-specific Features of ACUCOBOL-GT


C$SYSTEM Library Routine

The C$SYSTEM routine allows you to run other programs from inside a COBOL application by combining the functionality of the SYSTEM and C$RUN routines. For more information, see C$SYSTEM.

Parent topic: Windows-specific Features of ACUCOBOL-GT


ACCEPT SYSTEM-INFORMATION FROM SYSTEM-INFO

ACUCOBOL-GT for 32-bit Windows returns "WIN/NT" as its host operating system when you use the ACCEPT FROM SYSTEM-INFO verb. This allows you to easily code 32-bit Windows-specific sections in your programs. The file "acucobol.def" contains SYSTEM-INFORMATION data items.

Parent topic: Windows-specific Features of ACUCOBOL-GT


Assembly Routines

Assembly routines cannot be linked into the 32-bit Windows runtime.

Parent topic: Windows-specific Features of ACUCOBOL-GT


C$CHAIN Library Routine

The 32-bit Windows version of C$CHAIN behaves differently than it does in most other environments. A mechanism for "chaining" programs is not provided in 32-bit Windows. Instead, ACUCOBOLGT initiates the chained-to program as an independent program and then halts the chained-from program.

Although this has the correct effect, 32-bit Windows causes the active program to shift from the chained-to program to some other program when the chained-from program halts. The runtime cannot determine which program is selected by 32-bit Windows as the active one.

The net effect is that the chained-to program pops up, but then becomes inactive and must be reactivated with either the mouse or the keyboard in order for the user to enter data. A mechanism for suggesting which program to activate when a program halts does not exist in 32-bit Windows.

Parent topic: Windows-specific Features of ACUCOBOL-GT


Windows-specific Library Routines

ACUCOBOL-GT offers several Windows-specific library routines.

  • WIN$PLAYSOUND lets you play a ".wav" file on Microsoft Windows machines.
  • WIN$PRINTER enhances COBOL's ability take advantage of the Windows print spooler.
  • WIN$VERSION lets you retrieve version information from Windows host machines.
  • A number of library routines enable you to create and query Windows Registry keys.

For more information on these routines, see General Syntax and Library List.

Parent topic: Windows-specific Features of ACUCOBOL-GT


Using ActiveX Controls and COM Objects

  • Leveraging Ready-made Controls
  • Adding ActiveX Controls or COM Objects to Your COBOL Program
  • Passing COBOL Data to Methods or Properties as SAFEARRAYs
  • Using COBOL Data Types as ActiveX and COM Object Parameters
  • ActiveX and COM Events
  • ACTIVE-X Control Type
  • Name Clashes
  • Useful Files
  • Multiple Object Interfaces
  • ActiveX Library Routines
  • Distributing Applications Containing ActiveX Controls
  • Deployment Guidelines
  • Creating COM Objects on Remote Network Servers
  • Qualified ActiveX Control and Object Names
  • Enumerators
  • ActiveX Color Representation
  • ActiveX Error Handling
  • ActiveX Debugging
  • ActiveX Troubleshooting
  • ActiveX Examples
  • AXDEFGEN Utility Reference
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


Leveraging Ready-made Controls

You can use many different ActiveX® controls and COM objects in your ACUCOBOL-GT® program. When you add an ActiveX control or COM object to your program, whether it is graphical or non-graphical, the control or object becomes part of the development and run-time environment and instantly provides the application with new functionality.

COM objects are application components that perform well-defined functions, often involving a graphical user interface. ActiveX controls are COM objects that subscribe to the ActiveX component model originally developed by Microsoft. As such, they behave in a manner that developers can predict, they are reusable, and they are toolable. Pre-programmed controls (such as calendars, clocks, and gauges) are sold by third-party vendors along with the licensing rights to use them in your Windows application. Non-graphical controls and objects such as spell checkers and COM servers are also available, widening the opportunities for your COBOL application even further.

By supporting ActiveX controls and COM objects, ACUCOBOL-GT allows you to take advantage of existing software functionality, as well as create applications that conform to the Windows standard.

This chapter provides a general overview of ActiveX and COM programming, including information on how to add ActiveX and COM objects to your program, avoid name clashes, distribute a program that contains an ActiveX or COM object, respond to events, handle errors, and more. Reference material is also provided in the ACUCOBOL-GT documentation set:

  • The ACCEPT, CREATE, MODIFY, INQUIRE, and USE statements are described in the ACUCOBOL-GT Reference Manual, along with common screen options.
  • ActiveX terms, methods, events, control types, and color settings are described in ACUCOBOL-GT User Interface Programming.
  • ActiveX configuration variables and library routines are described in ACUCOBOL-GT Appendices.
Note: Please note that ACUCOBOL-GT does not support windowless ActiveX controls. If you want to use a windowless control, see if it is available as a .NET assembly, then use our .NET interface to invoke the control. See Using .NET Assemblies in COBOL for details.
Parent topic: Using ActiveX Controls and COM Objects


Adding ActiveX Controls or COM Objects to Your COBOL Program

You add ActiveX controls and COM objects to your ACUCOBOL-GT program using the utility program called AXDEFGEN. AXDEFGEN is provided on the ACUCOBOL-GT installation media for your convenience. You can launch it from Windows Explorer or AcuBench®, whichever you choose.

  • The AXDEFGEN Utility
Parent topic: Using ActiveX Controls and COM Objects
Related information
AXDEFGEN Utility Reference


The AXDEFGEN Utility

The role of AXDEFGEN is to locate the names of ActiveX controls and COM objects currently registered on the system and generate a COBOL COPY file for the control or object that you select. This COPY file is used by the ACUCOBOL-GT compiler for syntax and parameter type checking as well as efficient code generation. Where the control or object requires additional runtime licensing, AXDEFGEN also creates and embeds the required license key.

The COPY file contains a Special-Names Class definition for the ActiveX control/COM object. After generating the COPY file with AXDEFGEN, you must copy the COPY file into the COBOL program's Special-Names paragraph in the Environment Division/Configuration Section. Please note that the Special-Names paragraph must end with a period. However, the COPY file generated by AXDEFGEN does not end with a period. This is so other definitions can be made in the Special-Names paragraph after the COPY statement that copies this COPY file. To complete the paragraph, you must add a period.

The Special-Names Class definitions in the COPY file generated by AXDEFGEN contain all of the information the compiler needs to know about the ActiveX control or COM object. This eliminates the need for the compiler to read the system registry or instantiate the ActiveX control during compilation of the COBOL program. As a result, the COBOL program can be compiled later on a UNIX or VMS machine, or on a Windows machine that does not have the particular ActiveX control or COM object registered.

In order for the control to function in your COBOL program, you must add it to your program. For ActiveX, you typically modify the Screen section to include the name of the control's primary interface. This name can be determined by looking at the COPY file section ***Primary Interface***. Occasionally, you may want to create an ActiveX control in your Procedure Division. In this case, you use the DISPLAY statement.

Note: If you are using the AcuBench integrated development environment (IDE), you can drag the ActiveX control from the Screen Component Toolbox and drop it onto your screen in the Screen Designer. When run from AcuBench, AXDEFGEN automatically populates the toolbox with the ActiveX controls of your choice. see the AcuBench User's Guide for details.

To create a COM object, you add a CREATE statement to your program's Procedure Division. Unlike ActiveX controls, COM objects cannot be created using the Screen section or DISPLAY statement.

  • To Add an ActiveX Control or COM Object to Your ACUCOBOL-GT Program
Parent topic: Adding ActiveX Controls or COM Objects to Your COBOL Program


To Add an ActiveX Control or COM Object to Your ACUCOBOL-GT Program

  1. If it is not installed already, install and register the ActiveX control or COM object of interest on your development system.

    Complex controls may come with their own setup programs, licensing, and registration wizards. Look for a setup program or "readme" file in the directory containing the control. Run the setup program if you find one. This program will likely install and register the control for you. Read the "readme" file, if one exists, for any installation and registration instructions. If you cannot find any instructions on the control, you can also visit the control vendor's Web site.

    For simple controls, you can usually accomplish installation and registration by copying the ActiveX control files (at least a ".ocx" or ".dll" file) to your hard disk and executing the following command:

    regsvr32 <ocx or dll name>

    The “regsvr32.exe” file is normally located in your \windows\system directory. Do not assume that it is in your search path. Even if the control is already installed on your machine (for instance, if it came with other software that you’ve purchased) you may still need to register the control with “regsvr32.exe”

  2. Use Windows Explorer to locate "axdefgen.exe". You'll find it in the \AcuGT\bin directory wherever you installed ACUCOBOL-GT on your machine (c:\Program Files\Micro Focus\extend xxx\ by default).
  3. Double-click the AXDEFGEN icon to start the utility. A list of all the controls and COM objects currently in the local machine's Windows registry appears.
    Note: You can launch "AXDEFGEN" from the command line. See AXDEFGEN Utility Reference for applicable command-line options.

    AXDEFGEN dialog box

  4. Select the ActiveX control or COM object that you'd like to include in your COBOL program, then specify an output path and filename for the COPY file. Click OK when done. The utility automatically generates a COPY file for the chosen control and appends the .def filename extension to the file.

    If the control or object requires a runtime license (in addition to a development license), it is automatically embedded in the .def file, and no further licensing action is required in order to use it: the .def file contains the additional LICENSE-KEY property in the *** Primary interface *** section. If you have also specified a LICENSE-KEY property within your source code, although it will not cause any problems, we recommend that you remove it and rely on AXDEFGEN to deal with the runtime licensing requirements. If you have specified a LICENSE-KEY property in your source code, it will take precedence at runtime over the one created by AXDEFGEN.

    Many ActiveX controls and COM objects have documentation available. If they do, the ActiveX Help push button on the right side of this box is enabled. Click the button to read the help file for the selected ActiveX control or COM object. If the ActiveX Help push button is disabled, then AXDEFGEN could not locate a help file for the selected control.

  5. In a code editor, open your ACUCOBOL-GT program and go to its Environment Division/Configuration Section.
  6. Copy the new COPY file into the COBOL program's Special-Names paragraph. If you are adding several controls, copy several COPY files into this paragraph. Add a period at the end of the paragraph. For example:
    SPECIAL-NAMES.
COPY "calendar.def".
COPY "chart.def".

    ACUCOBOL-GT includes an acuclass.def file, which contains stock class definitions for ActiveX. We recommend that you also copy it into your program's Special-Names paragraph, as in: COPY "acuclass.def".

  7. Add the control to your program. If you are adding a COM object, you add the object using the CREATE statement in your program's Procedure Division. For example:
    *Create an instance of the Outlook application
CREATE Application OF Outlook
     HANDLE IN myOutlook
     EVENT PROCEDURE OUTLOOK-EVENTS.

    If you are adding an ActiveX control, however, you can do one of two things:

    1. Add the new control to your screen in your program's Screen Section. For example:
      SCREEN SECTION.
...
03 calendar-item Calendar column 5,
   line 5, size 60, lines 20
...

      or

    2. Create the control using the DISPLAY statement in your program's Procedure Division. For example:
      *Declare the calendar control's handle.
   77 CALENDAR-1 USAGE IS HANDLE OF Calendar.
   ...
*Create an instance of the calendar control
   DISPLAY Calendar line 4, column 6,
      lines 10, size 40
      EVENT PROCEDURE IS CALENDAR-EVENT-HANDLER
      HANDLE IN CALENDAR-1.

      You can determine the name of the control by opening the COPY file (".def" file) and looking at the section called "***Primary Interface***." Look for the name of the control after the word "CLASS" in the primary interface definition. If you set a property of the ActiveX control in the control property panel (thus storing it in the resource file) and that property has a corresponding ACUCOBOLGT property (e.g., ENABLED), then the COBOL program must explicitly set the corresponding ACUCOBOL-GT property in the Screen section or Procedure Division. For example, if the ActiveX ENABLED property is set to "false" in the ActiveX control property panel, then a line must be included in the initialization code of the COBOL program to set the ACUCOBOL-GT ENABLED property to "false", as in:

      MODIFY ActiveXcontrol ENABLED FALSE
      Note:

      The runtime ignores events from all controls while it is creating an ActiveX control. If you are using a control that delivers significant information using events and you don't want to miss those events while you are creating a new control, set the CONTROL_CREATION_EVENTS runtime configuration variable to "1" (on, true, yes). Alternatively, you could avoid creating an ActiveX control when you are expecting an event.

  8. If desired, you can modify a control's properties or invoke methods using the MODIFY verb as in the following example:
    MODIFY ActiveXcontrol Method ("parameters").

MODIFY ActiveXcontrol Property-name = property-value.

    or

    MODIFY ActiveXcontrol PROPERTY 37 = ("parameters").

    Note that 37 is the ActiveX or COM "property" number of Property-name or Method. You can determine the property number by opening the COPY file and searching for the name of the property or method. The "property" number, also known as the dispatch id or dispid, precedes the name in the COPY file. The equal sign is optional.

    To disable an ActiveX control, you use the MODIFY statement:

    MODIFY ActiveXcontrol ENABLED FALSE.

    If the ActiveX control has its own property named ENABLED, the MODIFY statement must explicitly set both the ACUCOBOLGT ENABLED property and the ActiveX property (@ENABLED; the "@" symbol signifies that the property is a property of the ActiveX control). For example:

    MODIFY ActiveXcontrol ENABLED FALSE @ENABLED FALSE.

    To enable the control:

    MODIFY ActiveXcontrol ENABLED TRUE @ENABLED TRUE.

    To inquire about the value of one of a control's properties, use the INQUIRE verb, as in:

    INQUIRE ActiveXcontrol Property-name IN value-item.

    or

    INQUIRE ActiveXcontrol PROPERTY 37 IN value-item.
  9. If desired, modify your program to respond to one of the control's events (e.g., a mouse click). For example:
    calendar-1-event.
   evaluate event-type
      when msg-ax-event
         evaluate event-data-2
            when CalendarClick
               Perform ...
         end-evaluate.
      ...
   end-evaluate.

    You can view a list of control events by opening the COPY file created by AXDEFGEN and looking at the section "Event Interface for the xxx Control."

  10. Compile and run your modified program.
Note: In order for the control to work on your end user's machine, it must be installed and registered. If you are licensed to do so, you can distribute the control along with your application. See Distributing Applications Containing ActiveX Controls, for information about distributing an application that contains an ActiveX object.
Parent topic: The AXDEFGEN Utility


Passing COBOL Data to Methods or Properties as SAFEARRAYs

When programming with ActiveX controls and COM objects, you can pass one- or two-dimensional COBOL tables to methods or properties that expect SAFEARRAY parameters. The runtime automatically converts a one- or two-dimensional COBOL table to a COM SAFEARRAY, as long as it contains only one elementary item that is USAGE HANDLE or USAGE HANDLE OF VARIANT.

The COM SAFEARRAY data type can contain elements of any type. Therefore, you must convert your COBOL data into variant type data before adding it to the array. Use the C$SETVARIANT library routine to create a new variant that stores the data if the initial value of the handle item passed to it is LOW-VALUES or SPACES. You need to free this variant using the DESTROY verb.

To use SAFEARRAYs, you should do the following:

  1. Declare a table in Working-Storage that has one or two OCCURS clauses. If specified, the second OCCURS clause must be on an item that is subordinate to the item with the first OCCURS clause. The table must contain only one elementary item that is USAGE HANDLE or USAGE HANDLE OF VARIANT. (OF VARIANT is optional but makes the code more readable.)
  2. Call C$SETVARIANT for each handle item in the table to convert the COBOL data to variant type data.
  3. Use the name of this table wherever a property or method requires a SAFEARRAY.

For example, Microsoft Chart Control has a property called ChartData. The value of this property is a SAFEARRAY. Each element of the array is a data point value for the chart.

01  myTable.
    03  filler occurs 5 times.
        05  chart-data     usage handle of variant.

screen section.
01  screen-1.
    03  mschart-1
        MSChart
        line 3, column 5, size 50, lines 16.

    03  my-button push-button, "E&xit Program",
        ok-button,
        line 32, cline 23, column 27, size 13.

procedure division.
Main-Logic.

    perform varying col-number from 1 by 1
      until col-number > 5
        call "c$setvariant"
            using col-number, chart-data(col-number)
    end-perform.

    display standard graphical window,
        title "ActiveX Table MSChart Sample - tblchart.cbl"
        lines 37, size 66, background-low.

    display screen-1.

    modify mschart-1
           ChartData = myTable.

    perform, with test after, until exit-button-pushed
        accept screen-1
    end-perform.

    perform varying col-number from 1 by 1
       until col-number > 5
        destroy chart-data(col-number)
    end-perform.
    destroy screen-1.
    stop run.

Notice that the initial values of the chart-data table elements are spaces. When C$SETVARIANT is called with the chart-data items set to spaces, it creates new variant handles and sets the chart-data item to the variant handle.

The DESTROY statement destroys these handles and releases the associated memory. The DESTROY statement also sets the chart-data item to low-values to allow multiple destroys of the same handle item without any negative effects.

The following code is an example of a table with two OCCURS clauses passed as a two-dimensional SAFEARRAY to the ChartData property. Microsoft Chart Control takes the "string" elements of this array to be the x-axis labels and the numeric elements to be two series of chart data.

77  col-label       pic x(20).
77  series-2-data   pic 99.

01  myTable.
    03  filler occurs 5 times.
        05  filler occurs 3 times.
            07  chart-data   usage handle of variant.

screen section.
01  screen-1.
    03  mschart-1
        MSChart
        line 3, column 5, size 50, lines 16.

    03  my-button push-button, "E&xit Program",
        ok-button,
        line 32, cline 23, column 27, size 13.

procedure division.
Main-Logic.

    perform varying col-number from 1 by 1
       until col-number > 5
        string "Label " delimited by size
            col-number delimited by size
            into col-label
        call "c$setvariant"
            using col-label, chart-data(col-number,1)
        call "c$setvariant"
            using col-number, chart-data(col-number,2)
        multiply col-number by 2 giving series-2-data
        call "c$setvariant"
            using series-2-data, chart-data(col-number,3)
    end-perform.

    display standard graphical window,
        title "ActiveX Table MSChart Sample - tblchart.cbl"
        lines 37, size 66, background-low.

    display screen-1.

    modify mschart-1
           ChartData = myTable.

    perform, with test after, until exit-button-pushed
        accept screen-1
    end-perform.

    perform varying col-number from 1 by 1
       until col-number > 5
        destroy chart-data(col-number,1)
        destroy chart-data(col-number,2)
        destroy chart-data(col-number,3)
    end-perform.
    destroy screen-1.
    stop run.

Some ActiveX and COM objects that use SAFEARRAYs accept that some items in the array may be empty (for example, Microsoft ADO). Items that are empty are normally passed using the VT_EMPTY variant type.

If an element in an array that you want to pass is optional (i.e., it may sometimes be empty), you must tell the runtime this by coding one of the following:

01 VariantParam.
   03 VariantTable usage handle of variant occurs 5.

   call "c$setvariant" USING x"00" VariantTable(1)

or

   call "c$setvariant" USING "" VariantTable(1)

This tells the runtime to convert the content of VariantTable(1) to VT_EMPTY. If you use the latter approach, you may receive and ignore compiler warnings that an empty literal was encountered.

Parent topic: Using ActiveX Controls and COM Objects


Using COBOL Data Types as ActiveX and COM Object Parameters

When programming with ActiveX controls and COM objects, you can MODIFY property values using COBOL data items, literals, and figurative constants. You can also pass them as parameters to methods using MODIFY.

When passing parameters to an ActiveX control or COM object method, the ACUCOBOL-GT runtime converts the COBOL parameters into variant parameters. Variant parameters have a data type associated with them. More than 40 different variant types exist. Each type name starts with "VT_". For example, VT_I4 is a 4-byte signed integer. VT_R8 is an 8-byte real (floating point) number. VT_BSTR is a string. The rules applied by the runtime to determine the variant type are given at the end of this section.

A method or property can act differently depending on the type of data passed to it in a variant. For example, a type of variant parameter called VT_UNKNOWN is commonly used to represent COM objects. A property or method might expect either VT_I4 or VT_UNKNOWN (that is, IUnknown pointer) and will act differently depending on which one it receives. If the runtime converts a COM object handle to a VT_I4 instead of a VT_UNKNOWN, the property or method being called might not act as expected. The runtime determines which of the two variant types to pass based on the USAGE parameters of the COBOL data item.

Some ActiveX and COM methods and properties take VT_VARIANT parameters, a generic variant type. This usually means that these methods accept more than one type of variant parameter. For example, you could pass a VT_I4, VT_R8, or a VT_BSTR as a VT_VARIANT parameter. The ActiveX or COM property or method could convert the passed parameter into a specific variant type. It could also act differently depending on the type of variant that was passed. For example, suppose an ActiveX or COM object had a table where rows could be referred to by a character string name or by their numeric index. A method that returns a row in the table could take either the name or index of the row as a parameter. The method could assume that if the parameter is a VT_BSTR, it is a row name; and if the parameter is a VT_I4, it is a numeric index.

If the ActiveX control or COM object property or method parameter is one of the standard variant types, ACUCOBOL-GT attempts to convert the COBOL data to the expected type. For example, if an ActiveX control property is type VT_I4 (i.e., 4-byte integer), and the COBOL data type is PIC X(10), ACUCOBOL-GT tries to convert the value of the PIC X(10) item into a number and pass it as a VT_I4 type variant.

If the property or method parameter type is VT_VARIANT, then ACUCOBOL-GT converts the COBOL data item into a specific variant type parameter using the following rules:

  1. The PICTURE and USAGE clauses determine the type.
  2. If the data item is alphabetic, alphanumeric, or alphanumeric edited, it is passed as a VT_BSTR.
  3. If the data item is USAGE HANDLE or POINTER, and the property or method parameter type is VT_VARIANT, it is passed as a VT_UNKNOWN. If the data item is another binary (USAGE COMP-..., BINARY, HANDLE, POINTER, etc.), it is passed as a VT_I4.
  4. If the data item is USAGE FLOAT or DOUBLE, it is passed as a VT_R8.
  5. If the data item is another numeric type, it is passed as a VT_I4.

Note that the compiler generates an error message if a figurative constant is passed as a parameter where the method or property expects a " by reference" parameter. That error message is, " Illegal parameter: literal". This is the same error message you get when passing a figurative constant as a USING parameter in a CALL statement. One way to tell that the ActiveX/COM method expects a "by reference" parameter is by viewing the entry in the COPY file for that control or object. If the type has "BYREF" or if the numeric value divided by 16384 is odd, then you may not pass a figurative constant.

Parent topic: Using ActiveX Controls and COM Objects


ActiveX and COM Events

ActiveX control and COM object events can have any number and type of associated parameters or no parameters. The event parameters are used to provide information about the event to the program. They can also be used to get information from the program in response to the event.

When an ActiveX control or COM object event occurs, the control or object invokes its event procedure. The EVENT-STATUS data item reflects the invoking event. EVENT-TYPE is either CMD-GOTO, CMD-HELP, MSG-VALIDATE, or MSG-AX-EVENT. For a description of these events, see Control Events.

MSG-AX-EVENT (value 16436) occurs when an ActiveX control or COM object has "fired" an event. EVENT-DATA-2 contains the control's event type. For COM objects, you can use the C$SETEVENTDATA and C$GETEVENTDATA library routines to set and get event the event parameters for the current event.

For ActiveX controls, however, you can use C$GETEVENTDATA/C$SETEVENTDATA, or you can use the C$GETEVENTPARAM/C$SETEVENTPARAM routines to get and set individual event parameters.

For example:

01 DATE-1
    03 MONTH PIC 99.
    03 FILLER PIC X VALUE '/'.
    03 DAY PIC 99.
    03 FILLER PIC X VALUE '/'.
    03 YEAR PIC 99.
77 KEY-ASCII PIC X USAGE COMP-X.
77 KEY-CHAR PIC X REDEFINES KEY-ASCII.
...

* Handle events
...
 CALENDAR-EVENT-HANDLER.
      EVALUATE EVENT-TYPE
         WHEN MSG-AX-EVENT
              EVALUATE EVENT-DATA-2
                 WHEN CalendarBeforeUpdate
* Don't allow years >= 2020
                     INQUIRE EVENT-CONTROL-HANDLE
                        Value IN DATE-1
                     IF YEAR OF DATE-1 >= 2020
* Cancel the update (set the 'Cancel' parameter to 1)
                         CALL "C$SETEVENTPARAM" USING
                          EVENT-CONTROL-HANDLE, "Cancel", 1
                     END-IF
                 WHEN CalendarKeyPress
* Stop run if the user presses 'X'
                     CALL "C$GETEVENTPARAM" USING
                          EVENT-CONTROL-HANDLE, "KeyAscii",
                             KEY-ASCII
                     IF KEY-CHAR = 'X' STOP RUN END-IF
...

Note that the CalendarBeforeUpdate event has one parameter, CANCEL. For details, see the CalendarBeforeUpdate definition in the control's COPY file.

In this example, EVENT-CONTROL-HANDLE contains the handle of the control that fired the event (e.g., CALENDAR-1). C$SETEVENTPARAM is used to set the CANCEL parameter to "1" in response to a CalendarBeforeUpdate event when the year is 2020 or later. C$GETEVENTPARAM is used in the handling of the CalendarKeyPress event to get the key value and stop the runtime if it is "X".

For another example, suppose you have displayed an ActiveX control called "AX" whose handle is in AX-1. Further suppose that this control fires an event called AxEventOne, which has three parameters. You would use the following COBOL syntax to get the event parameters, add "2" to each one, and set the event parameters to their new values:

evaluate event-type
    when w-event
        evaluate event-data-2
            when AxEventOne
              call "c$geteventdata"
                 using event-control-handle,
                   param-1, param-2, param-3
              add 2 to param-1
              add 2 to param-2
              add 2 to param-3
              call "c$seteventdata"
                 using event-control-handle,
                   param-1, param-2, param-3

To use C$GETEVENTPARAM and C$SETEVENTPARAM, you must know the actual names of the parameters. You can determine these names by reading the ActiveX control's documentation or by looking at the definitions in the COPY file for the ActiveX control.

Note:

Using the C$SETEVENTPARAM approach, you do not need to pass all of the event parameters. You need to specify only the name of the particular parameter you want to set. With C$SETEVENTDATA you don't need to specify parameter names, but you must pass an ordered parameter list up to the parameter you want to set.

An event commonly receives many parameters. C$GETEVENTPARAM and C$SETEVENTPARAM allow you to get and set the values of only the parameters you care about. Suppose in the above example that PARAM-1 and PARAM-2 contain information about the event and that only PARAM-3 is meant to be set by the event procedure. Because PARAM-3 is the third parameter, to set it you would have to pass two "dummy" parameters to C$SETEVENTDATA. For example,

call "c$seteventdata" using event-control-handle,
      0, 0, param-3.

Suppose you determined that the name of PARAM-3 in the ActiveX control was "Param3". You could then use C$SETEVENTPARAM to accomplish the task in our example in a more elegant and readable way. For example:

call "c$seteventparam" using event-control-handle,
      "param3", param-3.

In the Calendar example, you would use:

call "c$seteventparam" using event-control-handle,
      "cancel", 1

instead of:

call "c$seteventdata" using event-control-handle, 1

And you would use:

call "c$geteventparam" using event-control-handle,
      "KeyAscii", key-ascii

instead of:

call "c$geteventdata" using event-control-handle, key-ascii

Using these routines can make your code more readable. The object code will be a little larger, and your program will run slightly slower. However, these differences may be unnoticeable and the benefits of readable code can outweigh the performance and size considerations.

To determine in which specific window and control the event occurred, you can use the EVENT-WINDOW-HANDLE, EVENT-CONTROL-HANDLE, and/or EVENT-CONTROL-ID fields in the event procedure.

  • EVENT-WINDOW-HANDLE holds the handle of the floating window in which the event occurred. If the event occurred in a control, this item is the handle of the floating window that contains the control.
  • EVENT-CONTROL-HANDLE holds the handle of the control in which the event occurred. If the event did not occur in a control, this item is set to NULL.
  • EVENT-CONTROL-ID holds the ID of the control in which the event occurred. IDs are assigned by the application when each control is created. If the event did not occur in a control, this item has the value zero.

During an ActiveX or COM event, you can refer to the control which "fired" the event using the EVENT-CONTROL-HANDLE item.

For more information on the C$GETEVENTDATA, C$SETEVENTDATA, C$GETEVENTPARAM, and C$SETEVENTPARAM library routines, see Library Routines.

  • Event Timing
Parent topic: Using ActiveX Controls and COM Objects


Event Timing

In order to properly handle ActiveX and COM events, it is important to understand how the runtime behaves in certain situations. Following are default runtime behaviors. If you want to change the behavior, you can add configuration variable(s) to your runtime configuration file.

  • The runtime ignores events from all controls while it is creating an ActiveX control or COM object. If you are using a control that delivers significant information using events and you don't want to miss those events while you are creating a new control, set the CONTROL_CREATION_EVENTS runtime configuration variable to "1" (on, true, yes).
  • The runtime suspends ActiveX and COM events when the application is not processing an ACCEPT statement; in other words, it suspends events in between ACCEPT statements. If your control does not support the suspend/resume behavior and you are using it with the ACUCOBOL-GT Thin Client, this can be problematic. To prevent problems, set the TC_RESTRICTS_AX_EVENTS thin client configuration variable to "1" to mimic the runtime behavior.
  • The runtime allows events to trigger while it is processing other events. If this is not handled properly, the runtime could execute the same code simultaneously in two threads on the same data. Set NESTED_AX_EVENTS to "0" (off, false, no) if you do not want event procedures to be nested. Be aware that this option may cause you to lose certain events (typically events triggered by modifications made in the event procedure).

For details on these configuration variables, please see Configuration Variables.

Parent topic: ActiveX and COM Events


ACTIVE-X Control Type

To use an ActiveX control in your COBOL program, we recommend that you define a new control type with properties, methods and events using the SPECIAL-NAMES CLASS clause. You can do this with the ActiveX definitions file generator, AXDEFGEN.

ACUCOBOL-GT defines a control type named "ACTIVE-X" that it uses internally whenever you CREATE, MODIFY, INQUIRE, or DESTROY an ActiveX control. For a complete description of the ACTIVE-X control type, refer to ACUCOBOL-GT User Interface Programming > Control Type Reference > ActiveX .

Parent topic: Using ActiveX Controls and COM Objects


Name Clashes

An ActiveX control may have property, method, or event names that are the same as COBOL reserved words or ACUCOBOL-GT standard property or style names. This situation creates ambiguity for the compiler. In addition, because ActiveX class names are used in the USAGE HANDLE clause of data description entries, in Screen Section items, and in DISPLAY statements, they may also cause ambiguities with COBOL reserved words.

To avoid these ambiguities, AXDEFGEN prepends an "at" sign character ("@") to every class, property, method, and event name in the generated COPY file.

In addition, ambiguity may occur with event names when two or more ActiveX controls define the same event name. To reduce this possibility, AXDEFGEN prepends the control name to each event name. For example, if an ActiveX control named "MyControl" has an event called "RightMouseButtonClick", AXDEFGEN names the control "@MyControl" and the event "@MyControlRightMouseButtonClick".

The "@" sign is not required unless ambiguities exist in the meaning in a certain context. However, to guard against unanticipated name conflicts and to ensure clarity in the reading and maintenance of the source code, we strongly recommend that you always use "@" when referring to an ActiveX property, style, or method in your source code.

If you do not use an "@" sign and a clash occurs, a compiler error results. For example, if you had a component named Editor that has a method Open, the following would cause a compiler error because Open clashes with ACUCOBOL-GT syntax:

...
77 hDocument HANDLE OF Editor.
...
PROCEDURE DIVISION.
MAIN.
     DISPLAY Editor LINE 1, COLUMN 1, LINES 10, SIZE 80,
          HANDLE IN hDocument.
     MODIFY hDocument Open("myfile.txt").
...

To address this, prepend the method name with an "@" as shown below:

...
77 hDocument HANDLE OF Editor.
...
PROCEDURE DIVISION.
MAIN.
     DISPLAY Editor LINE 1, COLUMN 1, LINES 10, SIZE 80,
          HANDLE IN hDocument.
     MODIFY hDocument @Open("myfile.txt").
...

If a class name immediately follows the level number in a Screen Section item, you must either use the "@" prefix or specify FILLER between the level number and class name.

Parent topic: Using ActiveX Controls and COM Objects


Useful Files

We provide two files that are useful to developers involved in ActiveX and COM programming. The "activex.def" file contains useful definitions for ActiveX. We recommend that you copy it into your program's Working-Storage section.

The "acuclass.def" file contains stock class definitions for ActiveX. We recommend that you copy it into your program's Special-Names paragraph.

Parent topic: Using ActiveX Controls and COM Objects


Multiple Object Interfaces

Some ActiveX controls are designed with multiple (object) interfaces. For example, "Microsoft Chart Control, version 6.0 (OLEDB)" has 42 public interfaces. Each interface is equivalent to a new object definition. In order to access the full feature set of the Microsoft Chart control, ACUCOBOL-GT must allow the property modification and method invocation of 42 different objects. For example, to set the Microsoft Chart legend, you get the value of the Legend property. This value is an object that you may then modify to change the legend. The Legend object has properties whose values are other objects, and so on.

Here's how you would set the text and backdrop parameters for a chart legend in Visual Basic.

Private Sub Command1_Click()
   With MSChart1.Legend
      ' Make Legend Visible.
      .Location.Visible = True
      .Location.LocationType = VtChLocationTypeRight
      ' Set Legend properties.
      .TextLayout.HorzAlignment = _
      VtHorizontalAlignmentRight   ' Right justify.
      ' Use Yellow text.
      .VtFont.VtColor.Set 255, 255, 0
      .Backdrop.Fill.Style = VtFillStyleBrush
      .Backdrop.Fill.Brush.Style = VtBrushStyleSolid
      .Backdrop.Fill.Brush.FillColor.Set 255, 0, 255
   End With
End Sub

In ACUCOBOL-GT this task is accomplished in a similar way with the USE verb, "^" and "::" operators. For example:

MODIFY MS-CHART-1 Legend::Location::Visible = 1.
MODIFY MS-CHART-1 Legend::Location::LocationType =
       VtChLocationTypeRight.
MODIFY MS-CHART-1 Legend::TextLayout::HorzAlignment =
       VtHorizontalAlignmentRight.
MODIFY MS-CHART-1 Legend::VtFont::VtColor::
       Set ( 255, 255, 0 ).
MODIFY MS-CHART-1 Legend::BackDrop::Fill::Style =
       VtFillStyleBrush.
MODIFY MS-CHART-1 Legend::BackDrop::Fill::Brush::Style =
       VtBrushStyleSolid.
MODIFY MS-CHART-1
       Legend::BackDrop::Fill::Brush::FillColor::
             Set ( 255, 0, 255 ).

or:

USE MS-CHART-1 Legend
MODIFY ^Location::Visible = 1
       ^Location::LocationType = VtChLocationTypeRight
       ^TextLayout::HorzAlignment =
              VtHorizontalAlignmentRight
       ^VtFont::VtColor::Set ( 255, 255, 0 )
       ^BackDrop::Fill::Style =
             VtFillStyleBrush
       ^BackDrop::Fill::Brush::Style =
             VtBrushStyleSolid
       ^BackDrop::Fill::Brush::FillColor::
             Set ( 255, 0, 255 )
END-USE

This syntax can be described as follows. In this format, the word following MODIFY must always be a control handle or "^". Each property or method name can be followed by "::" and then another property or method name to invoke methods inline. "MethodName1::MethodName2" means invoke the method "MethodName1" of the current object and set the current object to the return value. When a property or method name is followed by a token other than '::', then it means to actually invoke the method on the current object passing the specified arguments or set the property to the specified value and reset the current object to null.

For example, the following code:

MODIFY MS-CHART-1
       Legend::BackDrop::Fill::Brush::FillColor::
             Set ( 255, 0, 255 ).

can be broken down as follows:

MODIFY
MS-CHART-1
Legend
::
BackDrop
::
Fill
::
Brush
::
FillColor
::
Set
( 255, 0, 255 ).

which means MODIFY MS-CHART-1 in the following ways:

  1. Set the current object to the chart control.
  2. Invoke the "Legend" method of the current object (the chart control).
  3. Release the current object.
  4. Set the current object to the value returned by Legend.
  5. Invoke the "BackDrop" method of the current object (the Legend object).
  6. Release the current object.
  7. Set the current object to the value returned by BackDrop.
  8. Invoke the "Fill" method of the current object (the BackDrop object).
  9. Release the current object.
  10. Set the current object to the value returned by Fill.
  11. Invoke the "Brush" method of the current object (the Fill object).
  12. Release the current object.
  13. Set the current object to the value returned by Brush.
  14. Invoke the "FillColor" method of the current object (the Brush object).
  15. Release the current object.
  16. Set the current object to the value returned by FillColor.
  17. Invoke the "Set" method of the current object (the FillColor object) passing ( 255, 0, 255 ) as arguments.
  18. Release the current object.
Parent topic: Using ActiveX Controls and COM Objects


ActiveX Library Routines

ACUCOBOL-GT includes the following six library routines related to ActiveX:

C$GETEVENTDATA | retrieves all event parameters from the control's event procedure
C$GETEVENTPARAM | retrieves specific event parameters from the control's event procedure
C$EXCEPINFO | retrieves information about an object exception that has been raised
C$RESOURCE | loads a control "state" resource file and either retrieves or destroys the resource handle associated with it
C$SETEVENTDATA | sets all event parameters to be sent back to the control when the control's event procedure exits
C$SETEVENTPARAM | sets specific event parameters to be sent back to the control when the control's event procedure exits

These routines are documented in Library Routines.

Parent topic: Using ActiveX Controls and COM Objects


Distributing Applications Containing ActiveX Controls

To distribute your application, you need the object files and the resources they use. If you have added ActiveX controls to your application, you need to distribute files associated with the ActiveX controls along with the bitmap, ".wav", XFD, and configuration files required by your application. In addition, you need to modify your installation program to install and register the controls on the end-user's machine. Typically, you can accomplish this by copying the ActiveX control files (at least a ".ocx" or ".dll" file) to the directory where your application will be installed on the user's hard disk and calling the following command from your install shield script or batch file:

regsvr32 <ocx or dll name>

The "regsvr32.exe" file is normally located in the user's \windows\system directory. It is also included on the ACUCOBOL-GT Windows installation CD. Do not assume that it is in the user's search path or that it is pre-installed on Windows 98 and Windows NT 4.

Note: We recommend that you test your component installation by using the Declaratives section to catch exceptions when creating an instance of an ActiveX control. See C$EXCEPINFO for details. In addition, note that "regsvr32" can be used to unregister a control as well as register it. This may be useful if you want to test whether or not your installation script is properly registering the control. When you type "regsvr32" with no command-line options, a list of available options is displayed.

Complex controls may have more complicated installation and registration procedures. If this is the case, control vendors typically provide instructions on distributing their controls. Look for instructions in the form of "readme" files or online help files in the directory where your control is stored. You can also refer to a vendor's Web site for instructions.

Some ActiveX controls require a deployment license that is different than the development license. The vendor may or may not include that deployment license as part of the control's installation, depending on the ability of the appropriate development tool to discover that deployment license and embed it in the application. AXDEFGEN is able to discover the deployment license, and set a LICENSE-KEY property in the generated COPY file. In this case, your application is ready for distribution with only the ActiveX control.

Parent topic: Using ActiveX Controls and COM Objects


Deployment Guidelines

Listed below are some guidelines to consider when deploying a COM object or ActiveX control:

  1. Is there an end-user license?
    • Check with the vendor.
    • Use AXDEFGEN to generate a COBOL COPY file, which automatically embeds the required end-user license in your COBOL application.
    • If you are not using AXDEFGEN, make sure the LICENSE-KEY phrase is filled in with any necessary license information.
    • If you are using the Microsoft common controls included on the product CD, you do not need to worry about licensing. The end-user license is automatically checked out by the ACUCOBOL-GT runtime.
    • Licensing implications are discussed in Distributing Applications Containing ActiveX Controls.
  2. Are there any file dependencies?
    • What files are required (if any) to execute the control? The control vendor can tell you this. Don't ship the entire developer's installation unless you must, because this typically includes unnecessary components.
    • If external files are required, what versions should they be?
    • Does the dependent file have a dependency? If your control is made with any version of Visual Studio, it may depend on the presence of the Microsoft Visual C runtime library, or the Microsoft foundation classes of a particular version. Normally you don't have to think about this, because the COBOL Virtual Machine™ already depends on these and provides them. Make a note of it though, because your component may rely on a different version and may behave oddly in the case of a mismatch.
    • For the Microsoft common controls shipped on the product CD, we provides a text file describing the control dependencies. This file is stored in the same folder as the controls.
  3. When should you install component and additional files?
    • ACUCOBOL-GT's Declaratives section covers object exceptions, or cases where an ActiveX control or COM object either did not display or terminated during execution. You can trap these kinds of events in the Object Exception part of the Declaratives. You should do this to make sure that you can control the full execution of the control, and if nothing else, make a graceful termination for your application. See Active Error Handling for additional details.
    • With the Object Exception section in place, you can use the standard DISPLAY or CREATE verb to determine if the control you are about to use is already installed. If you have an Object Exception section and create an object that is not installed, your program is thrown into the Declaratives. Using the C$EXCEPINFO library function, you can determine the cause of the failure.
    • If it is determined that the control is not installed, you should copy the files into your application directory (where you have "wrun32.exe" installed) to avoid interfering with other software and to ensure the possibility of an easy cleanup and uninstall.
    • If the control is not installed and it has a ".dll" extension, you can install it from within your COBOL application. You must copy the component files to the /bin directory and then register the files via:
      DllRegisterServer

      and

      DllUnregisterServer

      Alternatively, you can use "regsvr32" like this:

      regsvr32 activexfilename

      If you want to unregister, use this:

      regsvr32 activexfilename /U
      Note: If the control has the extension ".ocx", you may rename it to ".dll" in order to install it in ACUCOBOL-GT. The control's behavior is the same. The runtime does not recognize an ".ocx" as a ".dll". Once renamed, a control should not be renamed again.
Parent topic: Using ActiveX Controls and COM Objects


Creating COM Objects on Remote Network Servers

ACUCOBOL-GT includes a special verb to accommodate COM objects: CREATE. The Format 1 CREATE statement creates a new instance of a COM object. (Use the Screen section or Format 14 DISPLAY to create an instance of an ActiveX control.) See CREATE Statement for a detailed description of the CREATE statement.

If you have access privileges to do so, you can create a COM object on a remote-networked computer by passing the name of the computer in SERVER-NAME. That name is the same as the machine-name portion of a share name. For example, for a share named \\MyServer\Public, server name is MyServer. Note that CREATE cannot be used to create an object on a UNIX or VMS server. SERVER-NAME must be the name of a Windows machine.

The following code returns the version number of an instance of Excel running on a remote computer named MyServer:

CREATE Application of Excel
    SERVER-NAME is "MyServer"
    HANDLE in xl-app.
INQUIRE xl-app Version in xl-vers.
DISPLAY xl-vers.

If the remote server does not exist or is unavailable, then an exception is raised and xl-app is set to NULL.

You might think of using CREATE if you want to use an ActiveX object that does not have a user interface. However, the CREATE verb does not create ActiveX controls. If you want to create an ActiveX control that does not have a visual representation on the screen, set VISIBLE = 0 in the DISPLAY statement or Screen section item. If you do not want any screen at all, create the initial window also with VISIBLE = 0.

The CREATE statement can be used with thin client applications to create instances of an object on the client or on remote Windows servers.

For instance, you can use the CREATE statement to provide Microsoft Office functions such as spell check and mail merge to end users. The clients must be Windows workstations, but they can be naked of all software except for Windows and the ACUCOBOL-GT Thin Client. The server running AcuConnect can be Windows, UNIX, or Linux. Note that clients must have execution privileges on the computer hosting Office, and use of the Office technology is subject to Microsoft licensing terms.

You use the Format 1 CREATE statement to create a remote instance of the desired application on the Windows computer hosting Office. When executed, your thin client application CREATEs the Office object on the Windows host, sends it instructions and data, gets results, then either displays results on the client or performs further processing on them.

Although CREATE cannot be used to create an object on a UNIX or VMS server, non-Windows servers running AcuConnect can provide connectivity to Windows servers in a multiple-tier configuration.

Parent topic: Using ActiveX Controls and COM Objects


Qualified ActiveX Control and Object Names

In a Screen Section item, Format 14 DISPLAY statement, and a CREATE statement, "control-type-name" or "object-name" can be a qualified or unqualified name of an ActiveX control or COM object. ActiveX control and COM object names are defined in the Special-Names paragraph. The AcuBench Screen Designer or AXDEFGEN generates a COPY file for each ActiveX control or COM object type. You should copy this COPY file into the Special-Names paragraph. In rare cases, two different ActiveX controls or COM objects may have the same name. To use both in a single COBOL source file, you must qualify the names using "IN" or "OF" followed by the name of the "root" object. The "root" object name is defined in the ActiveX COPY file following the word OBJECT.

For example, if a single COBOL source file invokes methods in the Application object of both Microsoft Word and Microsoft Excel, it must qualify the Application object name as in the following two CREATE statements:

CREATE Application OF Word HANDLE IN WORD-HANDLE.
CREATE Application OF Excel HANDLE IN EXCEL-HANDLE.
Parent topic: Using ActiveX Controls and COM Objects


Enumerators

The CLASS clause is also used to define enumerations. For example, the VtBrushStyle class is defined by the Microsoft Chart Control in the COPY file as follows:

      * Brush Styles
      * VtBrushStyle
           CLASS @VtBrushStyle
               CLSID, B8CC5B99-BD29-11D1-B137-0000F8753F5D
               NAME, "VtBrushStyle"
      * long VtBrushStyleNull
               ENUMERATOR, @VtBrushStyleNull, 0
      * long VtBrushStyleSolid
               ENUMERATOR, @VtBrushStyleSolid, 1
      * long VtBrushStylePattern
               ENUMERATOR, @VtBrushStylePattern, 2
      * long VtBrushStyleHatched
               ENUMERATOR, @VtBrushStyleHatched, 3

Enumerators are used just like level-78 data items.

Note that ActiveX enumerators should always be prepended with an "@" sign in case they clash with COBOL reserved words or ACUCOBOL-GT graphical control property and style names. The "@" character identifies the relationship of the name to ActiveX. The same holds true for ActiveX properties and methods.

Parent topic: Using ActiveX Controls and COM Objects


ActiveX Color Representation

Many ActiveX controls use a special type named OLE_COLOR to represent colors. Methods and properties that accept a color specification of OLE_COLOR type expect that specification to be a number representing an RGB color value. For specific information regarding the OLE_COLOR type, refer to ACUCOBOL-GT User Interface Programming > Color Mapping > ActiveX Color Settings.

Parent topic: Using ActiveX Controls and COM Objects


ActiveX Error Handling

The runtime handles errors that occur during operations involving ActiveX controls similar to the way it handles errors during file I/O or during transactions. If an error cannot be naturally understood and dealt with by the COBOL program by looking at the return value or out-values of a statement, an exception is raised. The system then searches for a USE After EXCEPTION On OBJECT statement in the Declaratives section. If such a statement is found, the search stops, and the error handler is executed. If the program has not been terminated, program execution continues after the statement that raised the error. If no USE After EXCEPTION On OBJECT statement is found, the runtime determines the action. Usually, a message is presented and the program halts. See USE Statement for more information about USE.

Parent topic: Using ActiveX Controls and COM Objects


ActiveX Debugging

If you encounter problems when trying to run a program that contains ActiveX or COM objects, you should first try to determine whether the failure is related to the object or to the COBOL program. Try to run the ActiveX or COM object in another ActiveX container program to see if it works there. For instance, try to run it using the AcuBench Screen Designer. If you have Visual Basic on your machine, you can try to run the ActiveX or COM object in Visual Basic, or you can simply insert it on a Web page and try to run it in a browser. In addition, you can try to run the ActiveX or COM object on a different machine using ACUCOBOL-GT. If it works in other ActiveX containers or on other machines, then you have isolated the problem to your local environment or program. Check the COBOL syntax surrounding the control.

If necessary, you can use the screen trace option in the debugger to get more information about an error and to help debug your program. To enable the screen trace feature, type "ts" at the debugger command prompt. See Screen Tracing for more information on using this option.

Parent topic: Using ActiveX Controls and COM Objects


ActiveX Troubleshooting

Symptom | Cause
Control does not work within AcuBench (e.g., you receive a message such as "Can't create OCX.MSFlexGrid Control"). | Control is not properly installed or registered on the development system. Refer to Adding ActiveX Controls or COM Objects to Your COBOL Program for instructions on installing and registering controls.
Control does not appear within the AXDEFGEN list. | Control is not properly installed or registered on the development system. Refer to Adding ActiveX Controls or COM Objects to Your COBOL Program for instructions on installing and registering controls.
Control does not work correctly with the ACUCOBOL-GT runtime on the end-user's machine. | Control is not properly installed or registered on the end-user's system. Refer to Distributing Applications Containing ActiveX Controls for instructions on distributing ActiveX files along with your application.
Parent topic: Using ActiveX Controls and COM Objects


ActiveX Examples

Use of the Windows Media Player control is demonstrated in an AcuBench sample project located in the Support area of the Micro Focus Web site. To download the project, go to: http://supportline.microfocus.com/examplesandutilities/index.asp. Select ACUCOBOL-GT Samples > Graphical User Interface Sample Programs > Media_Player.zip.

Following is an excerpt of the COPY file generated by AXDEFGEN for Microsoft's Calendar Control 8.0. The COPY file includes object names so that the compiler can distinguish between two classes with the same name in different objects. For example, you might want to create an "Application of Word" and an "Application of Excel" in the same COBOL program. In the Calendar COPY file, the line "OBJECT @MSACAL" specifies the object name.

* CAL.DEF - ActiveX control definitions for MSACAL
* Generated: Tuesday, June 22, 1999

    OBJECT @MSACAL

* Calendar control

*** Primary Interface ***

* Calendar
     CLASS @Calendar
         CLSID, 8E27C92B-1264-101C-8A2F-040224009C02
         NAME, "Calendar"
         PRIMARY-INTERFACE
         ACTIVE-X-CONTROL
         DEFAULT-INTERFACE, "ICalendar"
         DEFAULT-SOURCE, "DCalendarEvents"
* BackColor
         PROPERTY-GET, -501, @BackColor
                 RETURNING "OLE_COLOR"
* BackColor
         PROPERTY-PUT, -501, @BackColor,
             "OLE_COLOR (Property Value)"
* Day
         PROPERTY-GET, 17, @Day
                 RETURNING "short"
* Day
         PROPERTY-PUT, 17, @Day,
             "short (Property Value)"
* DayFont
         PROPERTY-GET, 1, @DayFont
                 RETURNING "IFontDisp*"
* DayFont
         PROPERTY-PUT, 1, @DayFont,
             "IFontDisp* (Property Value)"
* DayFontColor
         PROPERTY-GET, 2, @DayFontColor
                 RETURNING "OLE_COLOR"
* DayFontColor
         PROPERTY-PUT, 2, @DayFontColor,
             "OLE_COLOR (Property Value)"
* NextDay
         METHOD, 22, @NextDay
* NextMonth
         METHOD, 23, @NextMonth
* NextWeek
         METHOD, 24, @NextWeek
* NextYear
         METHOD, 25, @NextYear
* PreviousDay
         METHOD, 26, @PreviousDay
* PreviousMonth
         METHOD, 27, @PreviousMonth
* PreviousWeek
         METHOD, 28, @PreviousWeek
* PreviousYear
         METHOD, 29, @PreviousYear
* Refresh
         METHOD, -550, @Refresh
* Today
         METHOD, 30, @Today
* AboutBox
         METHOD, -552, @AboutBox
* Click
         EVENT, -600, @CalendarClick
*            No Parameters
* DblClick
         EVENT, -601, @CalendarDblClick
*            No Parameters
* KeyDown
         EVENT, -602, @CalendarKeyDown
*            2 Parameters
                 short* KeyCode
                 short Shift
* KeyPress
         EVENT, -603, @CalendarKeyPress
*            1 Parameter
*                short* KeyAscii
* KeyUp
         EVENT, -604, @CalendarKeyUp
*            2 Parameters
*                short* KeyCode
*                short Shift
* BeforeUpdate
         EVENT, 2, @CalendarBeforeUpdate
*            1 Parameter
*                short* Cancel
* AfterUpdate
         EVENT, 1, @CalendarAfterUpdate
*            No Parameters
* NewMonth
         EVENT, 3, @CalendarNewMonth
*            No Parameters
* NewYear
         EVENT, 4, @CalendarNewYear
*            No Parameters

After generating the COPY file, you may create and use a Calendar control. You can add the control to your Screen Section as described in Adding ActiveX Controls or COM Objects to Your COBOL Program, or you can use the DISPLAY statement in the Procedure DivisioN to create the control. Note that the following two statements are equivalent:

    DISPLAY Calendar HANDLE IN my-cal.
    DISPLAY Calendar OF MSACAL HANDLE IN my-cal.

Here is an example of how you might update your Procedure Division to create, and then modify, the control:

* Declare the calendar control's handle.
77 CALENDAR-1 USAGE IS HANDLE OF Calendar.
...
* Declare the @KeyPress event parameter
77 KEY-ASCII PIC X USAGE COMP-X.
77 KEY-CHAR PIC X REDEFINES KEY-ASCII.
...
* Calendar @Value is the current date
01 DATE-1
    03 MONTH PIC 99.
    03 FILLER PIC X VALUE '/'.
    03 DAY PIC 99.
    03 FILLER PIC X VALUE '/'.
    03 YEAR PIC 9999.
...
* Create an instance of the calendar control
       DISPLAY Calendar LINE 4 COLUMN 6 LINES 10 SIZE 40
               EVENT PROCEDURE IS CALENDAR-EVENT-HANDLER
               HANDLE IN CALENDAR-1.
...
* Set the calendar's "day" font to Courier 10 pt Bold
       USE CALENDAR-1 DayFont
           MODIFY Name = "Courier" Size = 10 Bold = 1.
...
* Set the calendar's year to 2000
       MODIFY CALENDAR-1 Year = 2000.
...
* Invoke the NextDay method
       MODIFY CALENDAR-1 NextDay.
...
* Invoke the PreviousDay method
       MODIFY CALENDAR-1 PreviousDay.
...
* Handle events
...
CALENDAR-EVENT-HANDLER.
       EVALUATE EVENT-TYPE
           WHEN MSG-AX-EVENT
               EVALUATE EVENT-DATA-2
                   WHEN CalendarBeforeUpdate
* Don't allow years >= 2000
                       INQUIRE EVENT-CONTROL-HANDLE
                          @Value IN DATE-1
                       IF YEAR OF DATE-1 >= 2000
* Cancel the update (set the 'Cancel' parameter to 1)
                           CALL "C$SETEVENTDATA" USING
                           EVENT-CONTROL-HANDLE, 1
                       END-IF
                   WHEN CalendarKeyPress
* Stop run if the user presses 'X'
                       CALL "C$GETEVENTDATA" USING
                       EVENT-CONTROL-HANDLE, KEY-ASCII
                   IF KEY-CHAR = 'X' STOP RUN END-IF
...
Parent topic: Using ActiveX Controls and COM Objects


AXDEFGEN Utility Reference

The ActiveX Definitions Generator (AXDEFGEN) utility is a dialog-based application designed to facilitate the addition of ActiveX controls and COM objects to Windows-based ACUCOBOL-GT programs. AXDEFGEN locates the names of ActiveX controls and COM objects currently registered on the system and generate a COBOL COPY file for the control or object that you select. This COPY file is used by the ACUCOBOL-GT compiler for syntax and parameter type checking as well as efficient code generation. Where the control or object requires additional runtime licensing, AXDEFGEN also creates and embeds the required license key.

AXDEFGEN is located in the \AcuGT\bin directory wherever you installed ACUCOBOL-GT on your machine. If you run AXDEFGEN without command-line parameters, a dialog box appears.

AXDEFGEN dialog box

The dialog box has two tabs: Components and Libraries. The Components tab lists all ActiveX controls and other COM objects that have registered type libraries. The items on this list are derived from the HKEY_CLASSES_ROOT\CLSID registry key and then matched by the Globally Unique IDentifier (GUID) of the type library against the HKEY_CLASSES_ROOT\TypeLib registry entries. The Libraries tab contains a list of libraries derived directly from the HKEY_CLASSES_ROOT\TypeLib registry key. Therefore, some items may appear under both tabs, and some items in the Libraries list may represent collections of items from the Components list. AXDEFGEN generates a COPY file for the entire type library, whether you select the library name from the Libraries list or the name of an individual component from the Components list.

Select the name of an ActiveX control or COM object that you want to include in your COBOL program, then browse to choose an output path and filename for the COPY file. (The extension ".def" is automatically appended to the filename you specify.) When done, click OK to generate the COPY file.

Note: To prevent compiler errors, AXDEFGEN automatically converts any embedded spaces that it finds to hyphens when generating the COPY file, including spaces found in object methods, events, properties, parameters, and enumerators.

Many ActiveX controls and COM objects have documentation available. If they do, the ActiveX Help push button on the right side of this box is enabled. Click the button to read the help file for the selected ActiveX control or COM object. If the ActiveX Help push button is disabled, it means that AXDEFGEN could not locate a help file for the selected control.

If desired, you can execute AXDEFGEN from the command line. It takes two optional command line parameters. The first is the registry name of an ActiveX control or other COM object. The second is the name of the COPY file you want AXDEFGEN to create. For example:

AXDEFGEN MSCAL.Calendar cal.def

creates a COPY file named "cal.def" in the current directory containing the definitions for the Microsoft Calendar Control, which is an ActiveX control registered as "MSCAL.Calendar" in the system registry. Likewise:

AXDEFGEN Word.Application word.def

creates a COPY file named "word.def" in the current directory containing the definitions for Microsoft Word, which is registered as Word.Application in the system registry.

For more information on ActiveX and COM programming, including instructions on what to do with the COPY files generated by AXDEFGEN, refer to Adding ActiveX Controls or COM Objects to Your COBOL Program.

  • AXDEFGEN COPY Files
Parent topic: Using ActiveX Controls and COM Objects


AXDEFGEN COPY Files

Following is a list of TYPE codes that you might find in a COPY file generated by AXDEFGEN. The TYPE names are acronyms and/or abbreviations for the type descriptions. VT stands for Variant Type. For example, VT_I2 is a type of variant that contains a 2-byte signed integer. VT_UI2 is a 2-byte unsigned integer. VT_R4 is a 4-byte real number (floating point). For a more complete reference of these codes, refer to the Microsoft Developer's Network at msdn.microsoft.com.

Note that you may pass an alphanumeric data item or literal as a parameter to a property or method that expects a numeric item. The runtime automatically "parses" the alphanumeric string and extracts a number from it if possible.

In general, if a parameter is passed by reference (usually an I/O or output parameter), then it has 16384 (hex 4000) added to its value in the COPY file. For example a boolean output parameter would be 16384 + 11 (the value for VT-BOOL), or 16395. For this reason, if the TYPE in the COPY file is between 16384 and 16456, then you can subtract 16384 to find the associated TYPE code.

This table also includes possible C types that you may find in AXDEFGEN COPY files along with the corresponding COBOL data class.

AXDEFGEN COPY File Type Codes

TYPE Code | TYPE Name | C Type | COBOL Data Class | Description of Data
 | VT_EMPTY | void | N/A | Nothing
1 | VT_NULL | null | numeric | SQL style Null; any numeric data item, 0, zero, null, or low-values
2 | VT_I2 | short | numeric | 2-byte signed int; a 16-bit signed integer, any numeric data item or literal
3 | VT_I4 | int | numeric | 4-byte signed int; a 32-bit signed integer, any numeric data item or literal
4 | VT_R4 | single | numeric | 4-byte real; a single (4-byte) floating point number, any numeric data item or literal, typically USAGE FLOAT
5 | VT_R8 | double | numeric | 8-byte real; a double (8-byte) floating point number, any numeric data item or literal, typically USAGE DOUBLE
6 | VT_CY | CURRENCY | numeric | Currency; a currency value, any numeric data item or literal, usually containing a decimal point
7 | VT_DATE | DATE | alphanumeric | Date; a date in either numeric or alphanumeric form
8 | VT_BSTR | BSTR | alphanumeric | COM Automation string; a character string, any data item or literal, typically USAGE DISPLAY
9 | VT_DISPATCH | IDispatch | numeric | IDispatch; a pointer to the IDispatch interface, a USAGE POINTER, or USAGE HANDLE item
10 | VT_ERROR | SCODE | numeric | SCODE; a 32-bit unsigned integer, any numeric data item or literal
11 | VT_BOOL | boolean | numeric | True=-1, False=0; any alphanumeric or numeric data item or literal, pass 1, -1 or "True" for True, 0 or "False" for False
12 | VT_VARIANT | VARIANT | any | VARIANT; any alphanumeric or numeric data item or literal
13 | VT_UNKNOWN | IUnknown | numeric | IUnknown; a pointer to the IUnknown interface, a USAGE POINTER, or USAGE HANDLE item
14 | VT_DECIMAL | N/A | numeric | 16-byte fixed point
16 | VT_I1 | char | alphanumeric | Signed char; a single 8-bit signed character, any data item or literal, typically USAGE DISPLAY
17 | VT_UI1 | unsigned char | numeric | Unsigned char; a single 8-bit unsigned character, any numeric data item or literal
18 | VT_UI2 | unsigned short | numeric | Unsigned short; a 16-bit unsigned integer, any numeric data item or literal
19 | VT_UI4 | unsigned long | numeric | Unsigned long; a 32-bit unsigned integer, any numeric data item or literal
20 | VT_I8 | int64 | numeric | Signed 64-bit int; a 64-bit signed integer, any numeric data item or literal
21 | VT_UI8 | uint64 | numeric | Unsigned 64-bit int; a 64-bit unsigned integer, any numeric data item or literal
22 | VT_INT | int | numeric | Signed machine int; a 32-bit signed integer, any numeric data item or literal
23 | VT_UINT | unsigned int | numeric | Unsigned machine int; a 32-bit unsigned integer, any numeric data item or literal
24 | VT_VOID | void | N/A | C style void
25 | VT_HRESULT | HRESULT | numeric | Standard return type; a 32-bit unsigned integer, any numeric data item or literal
26 | VT_PTR | PTR | numeric | Pointer type; a USAGE HANDLE or USAGE POINTER data item
27 | VT_SAFEARRAY | SAFEARRAY | table | One- or two-dimensional table with one USAGE HANDLE or USAGE HANDLE OF VARIANT elementary item
28 | VT_CARRAY | CARRAY | N/A | C style array
29 | VT_USERDEFINED | USERDEFINED | N/A | User-defined type
30 | VT_LPSTR | LPSTR | alphanumeric | Null terminated string; any alphanumeric data item or literal
31 | VT_LPWSTR | LPWSTR | alphanumeric | Wide null terminated string; any alphanumeric data item or literal
36 | VT_RECORD |  | N/A | User-defined type
64 | VT_FILETIME | FILETIME | N/A | FILETIME
65 | VT_BLOB | BLOB | N/A | Length prefixed bytes
66 | VT_STREAM | STREAM | N/A | Name of the stream follows.
67 | VT_STORAGE | STORAGE | N/A | Name of the storage follows.
68 | VT_STREAMED _OBJECT | STREAMED _OBJECT | N/A | Stream contains an object.
69 | VT_STORED _OBJECT | STORED _OBJECT | N/A | Storage contains an object.
70 | VT_BLOB_OBJECT | BLOB_OBJECT | N/A | Blob contains an object.
71 | VT_CF | CF | N/A | Clipboard format
72 | VT_CLSID | CLSID | alphanumeric | A Class ID; any alphanumeric data item or literal

If DATE is in numeric form, days are represented by whole number increments starting with 30 December 1899, midnight as time zero. Hour values are expressed as the absolute value of the fractional part of the number. For example:

0.00 is 30 December 1899, 12:00 A.M.

5.25 is 4 January 1900, 6 A.M.

5.875 is 4 January 1900, 9 P.M.

If DATE is in alphanumeric form, the date can be in a variety of formats. For example, the following are all valid formats:

"25 January 1996"

"8:30:00"

"20:30:00"

"January 25, 1996 8:30:00"

"8:30:00 Jan. 25, 1996"

"½5/1996 8:30:00"

You may pass a USAGE POINTER item that was filled in by a prior method or property call, or you may pass a USAGE HANDLE item which contains a handle to an ActiveX control or COM object. You may not pass a Screen Section item name as a handle of an ActiveX control. Instead, use the Format 11 SET verb to get a handle to the ActiveX control (e.g., SET my-handle to HANDLE OF screen-section-item). The IUnknown interface is part of the Microsoft COM standard. Any COM object or ActiveX control exports interfaces that are used to create, use, and destroy objects. Each interface is based on a single interface called IUnknown. This means that you may pass a pointer to any of these interfaces (objects) to a method or property that expects an IUnknown*.

The runtime automatically converts a handle to an ActiveX control or COM object to the IUnknown* type when you pass it to a method or property.

Any of these types may be followed by an asterisk to indicate that the parameter will be passed "by reference". This means that the ActiveX control or COM object method or property may modify the contents of the passed data item.

Any type name other than those in the list is a user-defined type. User-defined types are those that are created by the ActiveX control or COM object programmer or vendor. They always resolve to one of the types in the list but have different names to indicate their functions. For example, OLE_COLOR is a user-defined type that is commonly used to represent colors in ActiveX controls and COM objects. It resolves to a unsigned long which is a 32-bit unsigned integer. You must read the programmer's documentation of the particular ActiveX control or COM object in order to determine how to use user-defined types. For example, after reading about OLE_COLOR you may learn a formula to allow you to construct an OLE_COLOR if you know the red (0-255), green (0-255), and blue (0-255) components of the color you are trying to represent.

Another common user-defined type is IFontDisp*. This type is used to represent fonts. Some ActiveX controls and/or COM objects have properties whose values are fonts, or methods whose parameters are fonts. You may use INQUIRE to get a IFontDisp* into a HANDLE OF IFontDisp item. IFontDisp is defined in "acuclass.def". Then you may modify the NAME, SIZE, BOLD, ITALIC, UNDERLINE, STRIKETHROUGH, WEIGHT, or CHARSET properties of the IFontDisp item using the MODIFY verb. For example:

copy "acuclass.def"
...
77  my-font-disp  usage handle of IFontDisp
...
INQUIRE Calendar-1 DayFont in my-font-disp.
MODIFY my-font-disp Name = "Courier New"
     @Size = 15, Bold = 1.
Note: Because SIZE is a common ACUCOBOL-GT property name, @Size uses the "at" sign to distinguish it as an ActiveX property name.

Alternatively, you may use the double colon ("::") operator to set these properties in a single MODIFY statement. For example:

MODIFY Calendar-1 DayFont::Name = "Courier New"
    DayFont::Size = 15, DayFont::Bold = 1.

In this case, you do not use a HANDLE OF IFontDisp item. Instead, the runtime creates a temporary HANDLE OF IFontDisp item, does the INQUIRE, and sets the properties "behind the scenes" in the processing of the MODIFY statement.

Another user-defined type that you might see is DataSource*, which is sometimes used as the value of a DataSource property in an ActiveX control. It resolves to the IUnknown * type. For example, to use the Microsoft DataGrid control and the Microsoft ADO control together, set the DataGrid control's DataSource property to the IUnknown* of the ADO control. As stated above, to pass an ActiveX control or COM object as a IUnknown* you must pass the handle of the control or COM object.

For example:

01  main-screen.
    03 adoctrl, Adodc,
       COL 14 LINE 21 LINES 2.20 CELLS
       SIZE 29.00 CELLS
       LICENSE-KEY "C4145310-469C-11d1-B182-00A0C922E820".
    03 testgrid, Datagrid,
       COL 14 LINE 9 LINES 10 CELLS
       SIZE 28 CELLS
       LICENSE-KEY "CDE57A55-8B86-11D0-b3C6-00A0C90AEA82".

    03 PUSH-BUTTON LINE 27 COL 23 TITLE "Exit"
       CANCEL-BUTTON LINES 4 CELLS SIZE 10 CELLS.

...

DISPLAY main-screen.

MODIFY adoctrl ConnectionString = "DSN=Customers".
MODIFY adoctrl DatasourceName = "Customers".
MODIFY adoctrl RecordSource = "Select * from publishers".

MODIFY testgrid Caption = "Test".
SET adoctrl-handle TO HANDLE OF adoctrl.
MODIFY testgrid DataSource = adoctrl-handle.

DISPLAY testgrid.

The handle of the "adoctrl" is obtained with the SET verb. It is then passed as the value of the DataSource property in the MODIFY statement that follows.

Parent topic: AXDEFGEN Utility Reference


Working with .NET Assemblies

  • COBOL and .NET
  • What Is .NET?
  • What Is an Assembly?
  • Calling COBOL from .NET
  • Calling .NET from COBOL
  • Interacting with .NET Web Services
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


COBOL and .NET

ACUCOBOL-GT includes many facilities for interoperating with Microsoft® .NET technologies.

It includes compiler options that generate Microsoft Intermediate Language (MSIL) objects capable of calling and running your COBOL program. These objects can be managed and run by the .NET Common Language Runtime (CLR) and instantiated by a .NET assembly.

It includes a .NET interface that lets .NET programmers interact with the COBOL program at the API level. A .NET version of the ACUCOBOL-GT® programs can be included in any Visual Studio .NET project.

ACUCOBOL-GT also includes a utility, NETDEFGEN, that translates .NET assemblies into COBOL COPY files, making it easy to invoke .NET assemblies from your COBOL program.

Web services are supported via .NET client control proxies. These proxies are simple .NET controls that interact with Web services and communicate with an ACUCOBOL-GT program using native .NET event declarations, methods, and properties.

UNIX users can interact with .NET assemblies using our Thin Client technology. If you want, you can mix Win32, ActiveX, and .NET graphical controls on the same ACUCOBOL-GT screen.

All of these options are discussed in this chapter.

Parent topic: Working with .NET Assemblies


What Is .NET?

.NET is a set of Microsoft software technologies designed to facilitate the development and execution of large, interoperable Web-based, desktop, distributed, and server applications, both for e-commerce and global electronic businesses. .NET is the Microsoft solution for Web services. Like other Web service environments, it relies heavily on eXtensible Markup Language (XML) and SOAP.

.NET has been incorporated across Microsoft's clients, servers, services, and tools. For developers, .NET is manifested in the programming model delivered in the Microsoft .NET Framework. .NET is based on the reuse of services. Microsoft defines services as small, discrete, building-block applications that connect to each other as well as to other, larger applications via the Internet or an intranet.

.NET supports many different programming languages. Normally .NET applications are compiled into Microsoft intermediate language (MSIL) and run in a sort of virtual operating system, the CLR. The compiled code is called managed code, because it is managed by the CLR.

Applications compiled in other languages can also run in .NET environments under the Windows operating system, and Microsoft has provided many facilities to allow such programs to interoperate with managed code.

Parent topic: Working with .NET Assemblies


What Is an Assembly?

In .NET parlance, all controls or programs are called assemblies. An assembly is a single file or a group of files that comprise a program, including the security management, versioning, sharing, and deployment information as well as the individual services that the program utilizes.

Services perform discrete functions ranging anywhere from simple requests to complicated business processes that combine information from multiple sources. A .NET assembly is a group of services that can be assembled like building blocks into a cohesive business application, or it can be as simple as an individual program that performs some discrete functions.

An assembly may appear as a single ".dll" or ".exe" file. Assemblies can be listed in a Global Assembly Cache (GAC) on an end user's machine.

Parent topic: Working with .NET Assemblies


Calling COBOL from .NET

There are three ways to call and interact with an ACUCOBOL-GT program from a .NET assembly. You can:

  • Use ACUCOBOL-GT's .NET compiler options to package your ACUCOBOL-GT program as a .NET assembly. .NET programmers can then invoke these objects as they would any other .NET assembly.

    Though perhaps easiest, this option limits data passing as discussed in Using the .NET MSIL Compiler Options.

    Note:

    To use the .NET compiler options, you must have Microsoft .NET Development Framework Version 2.0. However, you can create Version 1.1 and 2.0 assemblies.

  • Use our .NET interface assembly, "wrunnet.dl". This gives .NET programmers more direct access to and control of the ACUCOBOL-GT Windows runtime module. "wrunnet.dll" contains a singleton class, CVM, that encapsulates the ACUCOBOL-GT runtime. With the CVM, the .NET programmer can programmatically instantiate the ACUCOBOL-GT runtime and invoke a COBOL program without a COM interface or knowledge of the Windows API or .NET PINVOKE.

    .NET programmers can include "wrunnet.dll" in a Visual Studio .NET project and take advantage of the native .NET development environment. This interface gives them lower-level control over the COBOL program, and is very similar to the ACUCOBOL-GT C and Java interfaces.

  • Use ACUCOBOL-GT's COM server technology. The COM server is a COM object containing the ACUCOBOL-GT Windows runtime DLL. When the COM server is added to a .NET project, a proxy is created to communicate with the ACUCOBOL-GT runtime. The proxy provides all interface and data marshalling between .NET and the COM server. (Marshalling is the process of gathering data and transforming it into a standard format before transmitting it over a network.)
  • Using the .NET MSIL Compiler Options
  • Using the .NET Interface Assembly, "wrunnet.dll"
  • Using the ACUCOBOL-GT COM Server
Parent topic: Working with .NET Assemblies
Related information
Using the .NET MSIL Compiler Options


Using the .NET MSIL Compiler Options

The easiest way to provide COBOL services to a .NET assembly is to use one of ACUCOBOL-GT's .NET compiler options to generate managed objects that can call your ACUCOBOL-GT program. These objects are compiled in Microsoft Intermediate Language (MSIL), so they can be managed directly by the .NET Common Language Runtime (CLR). They are MSIL stubs capable of calling the ACUCOBOL-GT run time and executing your .acu object.

There are two compiler options that you can use for this purpose:

Compiler Option Description
--netexe Generates a .NET executable file from your COBOL source.

By default this command generates a .NET Version 2.0-compatible assembly or the latest version if 2.0 is not installed. You can also specify the desired version by adding the appropriate qualifier to the option.

For example: --netexe:2.0 verifies that .NET Version 2.0 is installed and generates a 2.0-compatible assembly if so.

Valid versions include 2.0, 2.0, 3.5, and 4.0.

--netdll Generates a .NET dynamic link library (DLL) file from your COBOL source.

By default this command generates a .NET Version 2.0-compatible assembly or the latest version if 2.0 is not installed. You can also specify the desired version by adding the appropriate qualifier to the option.

For example: --netdll:2.0 verifies that .NET Version 2.0 is installed and generates a 2.0-compatible assembly if so.

Valid versions include 2.0, 2.0, 3.5, and 4.0.

  • --netexe
  • --netdll
  • Data Passing Limitations
  • Example - TestNetToCobol
Parent topic: Calling COBOL from .NET


--netexe

The --netexe compiler option generates a .NET executable file for command line execution. The name of the executable is the name of the program followed by .exe. All valid ACUCOBOL-GT command line options can be specified with the executable, as well as any of the following Linkage Section parameters:

  • -int:
  • -string:
  • -uint:
  • -short:
  • -ushort:
  • -float:
  • -double:
  • -long:
  • -ulong:
  • -byte:

For example, the compiler command:

ccbl32 --netexe MyCobol.cbl

results in two files being created: the COBOL object, MyCobol.acu, and the .NET executable, MyCobol.exe.

You can execute the .NET version from the command line with MyCobol.exe or you can include command line options and linkage section parameters. For example:

MyCobol.exe -d -int:1234 -string:"Enter customer name"
The --netexe compiler option also accepts the following .NET version-specific modifiers to create .NET version-specific files:
  • :2.0
  • :3.0
  • :3.5
  • :4.0
Parent topic: Using the .NET MSIL Compiler Options


--netdll

The --netdll compiler option generates a .NET dynamic link library (DLL) that gives .NET both executables and DLL assemblies a programmatic interface to your COBOL program. All COBOL entry points are exposed as .NET methods along with ACUCOBOL-GT run-time properties and methods. This lets .NET programmers set ACUCOBOL-GT command options and call run-time interfaces from their .NET assembly.

By referring to an ACUCOBOL-GT .NET DLL in a project solution, .NET programmers can view ACUCOBOL-GT run-time properties, run-time initialization and control methods, COBOL entry points, the main COBOL entry point, and Linkage section parameters in the Visual Studio .NET object browser.

Compilng a COBOL program using the --netdll option creates three files. All three begin with the program file name. For example, the compiler command:

ccbl32 --netdll MyProgram.cbl

results in MyProgram.dll, MyProgram.netmodule, and MyProgram_CVM.dll. .NET programmers would reference MyProgram.dll and MyProgram_CVM.dll in their project.

MyProgram_CVM.dll contains all the COBOL program entry points and ACUCOBOL-GT run-time interfaces exposed as .NET methods. ACUCOBOL-GT run-time options are exposed as properties.

The class in MyProgram.dll derives from class CVM which resides in MyProgram_CVM.dll allowing the instantiation of namespace class MyProgram.MyProgram myPgm = new MyProgram.MyProgram(). All methods and properties in MyProgram_CVM.dll class CVM are exposed to object myPgm.

MyProgram.netmodule contains ACUCOBOL-GT setup routines that are automatically executed during object instantiation. MyProgram.dll works in conjunction with MyProgram.netmodule to perform this task. The namespace and class are always generated using the COBOL file name without the extension. In this case the namespace and class are MyProgram.MyProgram.

As mentioned previously, COBOL entry names and the main COBOL program entry point generate .NET methods. Method parameters are generated when entry statements contain USING parameters or a Procedure Division statement contains USING parameters. There are two additional parameters added to each generated .NET method. They follow all the COBOL USING parameters for the entry name or Procedure Division statement. The first parameter, string, is for program execution command parameters. They are -d (debug) and -cache. All other run-time command options must be set via properties before calling AcuInitialize or in the string parameter of AcuInitialize.

The second parameter is for a return code. This is the return code from the COBOL program. The method return code is from the COBOL Virtual Machine interface and is documented in CVM Class. You can also view the values using the Visual Studio .NET object browser under ErrorTypes in class CVM.

The --netexe compiler option also accepts the following .NET version-specific modifiers to create .NET version-specific files:
  • :2.0
  • :3.0
  • :3.5
  • :4.0
Note:

All of the criteria that apply to the CVM class also apply to the .NET component. See CVM Class for details on these criteria.

Parent topic: Using the .NET MSIL Compiler Options


Data Passing Limitations

The compiler options limit data passing to the following data types: integer, string, unsigned integer, short, unsigned short, float, double, long, unsigned long, and byte.

Parent topic: Using the .NET MSIL Compiler Options


Example - TestNetToCobol

Following is the COBOL source for a sample program, "TestNetToCobol.cbl".

identification division.
program-id. TestNetToCobol.
environment division.
configuration section.
data division.
working-storage section.

linkage section.
77 string-in-out          pic x(32) value spaces.
77 int-in-out             USAGE IS SIGNED-INT.

procedure division using string-in-out, int-in-out.
main-logic.

     move "hey whats doin" to string-in-out.
     entry "int-only" using int-in-out.
     move 9999 to int-in-out.
     exit program.

View of Managed Code in Visual Studio .NET Object Browser

Following is a screen that shows what "TestNetToCobol_CVM" looks like to a .NET programmer in the Visual Studio .NET object browser (once you've generated a .NET DLL for this program with the "--netdll" option). Notice that there are methods other than the COBOL program entry points and main Procedure Division paragraph in this browser. These ACUCOBOL-GT runtime interfaces are documented in the section CVM Class.

.NET Object Browser

C# Source

Here is a C# program that makes reference to "TestNetToCobol_CVM".

using System;
using System.Drawing;
using System.Collections;
using System.ComponentModel;
using System.Windows.Forms;
using System.Data;
using testnettocobol;
//using testnettocobol_CVM;

namespace TestDll
{
     /// <summary>
     /// Summary description for Form1.
     /// </summary>
     public class Form1 : System.Windows.Forms.Form
     {
          testnettocobol.testnettocobol cblObj;
          private System.Windows.Forms.Button button1;
          /// <summary>
          /// Required designer variable.
          /// </summary>
          private System.ComponentModel.Container components = null;

          public Form1()
          {
               //
               // Required for Windows Form Designer support
               //
               InitializeComponent();

               //
               // TODO: Add any constructor code after InitializeComponent call
               //
          }

          /// <summary>
          /// Clean up any resources being used.
          /// </summary>
          protected override void Dispose( bool disposing )
          {
               if( disposing )
               {
                    if (components != null)
                    {
                         components.Dispose();
                    }
               }
               base.Dispose( disposing );
          }

          #region Windows Form Designer generated code
          /// <summary>
          /// Required method for Designer support - do not modify
          /// the contents of this method with the code editor.
          /// </summary>
          private void InitializeComponent()
          {
               this.button1 = new System.Windows.Forms.Button();
               this.SuspendLayout();
               //
               // button1
               //
               this.button1.Location = new System.Drawing.Point(104, 24);
               this.button1.Name = "button1";
               this.button1.TabIndex = 0;
               this.button1.Text = "Test";
               this.button1.Click += new System.EventHandler(this.button1_Click);
               //
               // Form1
               //
               this.AutoScaleBaseSize = new System.Drawing.Size(5, 13);
               this.ClientSize = new System.Drawing.Size(292, 101);
               this.Controls.Add(this.button1);
               this.Name = "Form1";
               this.Text = "Form1";
               this.ResumeLayout(false);

          }
          #endregion

          /// <summary>
          /// The main entry point for the application.
          /// </summary>
          [STAThread]
          static void Main()
          {
               Application.Run(new Form1());
          }

          private void button1_Click(object sender, System.EventArgs e)
          {
               testnettocobol_CVM.errorTypes err = testnettocobol_CVM.errorTypes.CS_OK;
               IntPtr pInfo = IntPtr.Zero;
               int cblReturn = 0;
               string err_msg;
               int some_int = 777;
               string some_string;

               // Instantiate COBOL object and CVM, COBOL VIRTUAL MACHINE
               cblObj = new testnettocobol.testnettocobol();
               // Set ACUCOBOL-GT runtime options (properties)
               cblObj.RunPath = "D:\\branch_7_1\\cobolgt\\bin";
               cblObj.Debug = true;
               cblObj.LinkageLength = true;
               //cblObj.Cache = true;
               // Initialize the ACUCOBOL-GT runtime
               cblObj.Initialize();

               try
               {

                    //  The second to last parameter is for options specific
                    //  to a method call.  They may also be set via properties
                    //  before the method call is executed.
                    //  The last parameter is the return code from the COBOL program.

                    // call an ENTRY in the ACUCOBOL-GT program
                    some_int = 1111;
                    cblReturn = 0;

                    err = cblObj.int_only(ref some_int, null, ref cblReturn);

                    // call the main ENTRY, 1st COBOL line in PROCEDURE DIVISION
                    some_int = 1422;
                    some_string = "The hills are Alive             ";

                    err = cblObj.testnettocobol_CVM_main(ref some_string,
                                             ref some_int,
                                             null,
                                             ref cblReturn);
               }
               catch (System.Exception e2)
               {
                    Exception innerE = e2.InnerException;
                    if ((innerE != null) && (innerE.Message.Length > 0))
                         err_msg = innerE.Message;
                    else
                    {
                         if (e2.Message.Length > 0)
                              err_msg = e2.Message;
                         else
                              err_msg = "AcuNet Temp Object Create Error";
                    }
                    MessageBox.Show(err_msg);
                    return;
               }
               // test runtime return code
               if (err != testnettocobol_CVM.errorTypes.CS_OK)
               {
                    // get error text property
                    MessageBox.Show(cblObj.LastErrorMsg);
               }
               cblObj.ShutDown(0);
          }
     }
}
Parent topic: Using the .NET MSIL Compiler Options
Related information
CVM Class


Using the .NET Interface Assembly, "wrunnet.dll"

A more precise way to call COBOL from .NET is using the application programming interface (API) contained in the dynamic link library, "wrunnet.dll". .NET developers can use this interface to call COBOL functionality (programs, entry points, etc.) from their .NET class.

The API consists of one .NET class: CVM. CVM class allows .NET developers to programmatically manage the ACUCOBOL-GT runtime, giving them low-level control of COBOL objects from .NET.

Note that you can call COBOL from .NET locally or remotely. You can even have the runtime execute remotely without a COBOL object executing on the client. All you need on the client is a .NET program and a runtime. For this to work, you set CODE_PREFIX in the configuration file that you provide with the runtime initialization to point to a remote server hosting your COBOL application. The remote server must also be running AcuConnect. AcuConnect is able to execute a COBOL object remotely and share data with the local runtime. For more information on executing remote COBOL programs with AcuConnect, please see the AcuConnect User's Guide.

  • CVM class
  • Properties
  • Error codes
  • CompilerTypes
Parent topic: Calling COBOL from .NET


CVM class

CVM is a .NET class representing the ACUCOBOL-GT runtime. The CVM class exposes public methods for setting runtime options, calling and cancelling programs, getting object libraries, and more.

CVM contains the following methods within the name space "acucobol":

  • Initialize
  • Call
  • Cancel Program
  • CancelAllPrograms
  • UnloadProgram
  • UnloadAllPrograms
  • ShutDown

Each of these methods corresponds to the runtime interfaces acu_initv, acu_cobol, acu_cancel, acu_unload, and acu_shutdown. More details are provided in the following sections.

  • Initialize
  • Call
  • CancelProgram/CancelAllPrograms
  • UnloadProgram/UnloadAllPrograms
  • ShutDown
Parent topic: Using the .NET Interface Assembly, "wrunnet.dll"


Initialize

Initializes the COBOL Virtual Machine (runtime) with command line options before calling CallAcuCobol. Initialize is optional; Call will call Initialize with defaults if it has not been previously called.

Usage:

public unsafe bool Initialize (string cmdline)
public bool Initialize ()

where:

Variable | Definition
cmdline | Includes ACUCOBOL-GT runtime options. You can set runtime options using key value pairs or by setting properties. see Properties below.

Use "public bool Initialize ()" to set defaults.

Parent topic: CVM class


Call

Executes an ACUCOBOL-GT program.

Usage:

public unsafe errorTypes Call (string        pgmName,
                               ref object[]  CobolParams,
                               ref byte[]    CobolTypes,
                               string        CallOptions,
                               ref int       ProgramReturnCode)

where:

Variable | Definition
pgmName | Is the file path of an ACUCOBOL-GT program.
CobolParams | Is an array of parameter objects. They must match the Procedure Division USING parameters and be native types int, uint, short, ushort, long, ulong, float, double, char, byte, and/or string. Parameters should correspond one-to-one with the Linkage section of the COBOL program.
CobolTypes Is an array of COBOL types. This field is optional, meaning it can be a null reference. When used, it must be allocated with the same number of entries as CobolParams, one type corresponding to each parameter. These entries are needed when a COBOL program has a mix of unicode, double byte, and ANSI strings. .NET treats all strings as unicode and "wrunnet", by default, converts them to ANSI strings. In order for "wrunnet" to convert the unicode to a wide character, double byte, or pass it as a unicode string to a COBOL program, the corresponding entry in CobolTypes must be set.

If all strings in the COBOL program are unicode or all are double byte, a property may be set. This field is automatically generated when using the compiler option, "--netdll". The applicable fields are NAT, NATJ, NATE, WID, WIDJ and EWID. See CompilerTypes for more information.
CallOptions The following runtime options can be set using the Call method:
  • "-d", debug
  • "-show", display error text
  • " -uni", unicode
  • "-wide", double byte characters
  • "-cache", cache program
  • These are the only options that can be set after Initialize is called. They may also be set using a property assignment before a Call is executed. For example:

    "-d 1" or "-d 0" turns debug mode on in the first instance and off in the second instance.

    This is the only place where a boolean option can be set on and off in this manner. All other boolean options set via Initialize can be turned only on. In this case the syntax does not include a "1" or "0".

ProgramReturnCode | Upon return from Call, ProgramReturnCode contains the COBOL program return code.
Parent topic: CVM class
Related information
CompilerTypes


CancelProgram/CancelAllPrograms

Cancels program(s) and resets working storage. Optional.

Usage:

public unsafe bool CancelProgram (string name)
public unsafe bool CancelAllPrograms ()

Where:

Variable | Definition
name | The COBOL program to cancel.

"public unsafe bool CancelAllPrograms ()" cancels all programs.

Parent topic: CVM class


UnloadProgram/UnloadAllPrograms

Unloads a cached program from memory. Optional.

Usage:

public unsafe bool UnloadProgram (string name,  bool subprograms)
public unsafe bool UnloadAllPrograms ()

Where:

Variable | Definition
name | The COBOL program to unload.
subprograms | When true, unloads all subprograms

"public unsafe bool UnloadAllPrograms ()" unloads all cached programs from memory.

Parent topic: CVM class


ShutDown

ShutDown terminates the ACUCOBOL-GT runtime and is sometimes called when the runtime is no longer needed by the application . Please note that ShutDown should rarely be executed in a .NET application. This is because CVM provides an interface to the ACUCOBOL-GT runtime that is a standard Windows DLL, and there is only one instance of the DLL in the application. Even though you might destroy the instance of the CVM assembly, Windows keeps the DLL loaded until the application terminates. If you later create a new instance of CVM, Windows gives it a handle to the loaded DLL. Once an instance of CVM executes the ShutDown method, then any current or subsequent instances will not work because the DLL is now in a shutdown state and can not be reactivated.

ShutDown is automatically called when CAcuCobol is destoyed. This method is useful in other contexts as well and is provided to maintain compatibility.

Usage:

public void ShutDown(int msg)

Where:

Variable | Definition
msg 0 | Is the default return code

FreeInfo de-allocates IntPtr pInfo control blocks that were allocated during a call to CallAcuCobol. If this is not called the blocks will be de-allocated when "wrunnet" is removed from the system or when class CVM is destroyed.

Parent topic: CVM class


Properties

The following table contains a description of each property and its associated method. Please note that the get property, LastErrorMsg, returns the string of the last error message. The set properties set the string or property value.

When "wrunnet.dll" is referenced in a Visual Studio .NET project or the compiled COBOL program used the "--netdll" option, properties can be viewed using the object browser of Visual Studio .NET. When the "--netdll" option is used, properties are inluded in the "ProgramName_CVM.dll".

Property Name | Get/Set | Description | Command Option | Platform | Method
ConfigFile | Set | Alternate configuration file | -c | Win, UNIX | Initialize
DebugCmds | Set | File containing debugger commands | -r | Win, UNIX | Initialize
DisplayAppend | Set | File to append display output | +o | Win, UNIX | Initialize
DisplayOut | Set | File for display output | -o | Win, UNIX | Initialize
EmbeddedLib | Set | Load configuration file from COBOL object library | --embedded | Win, UNIX | Initialize
ErrorsAppend | Set | Append to error messages file | +e | Win, UNIX | Initialize
ErrorsOut | Set | Error messages file | -e | Win, UNIX | Initialize
Import | Set | A variable for importing graphical screens | -import | Win | Initialize
KeyFile | Set | Keyboard input file | -i | Win, UNIX | Initialize
LastErrorMsg | Get | Returns the last error message string |  | Win, UNIX | No restriction
ObjLib | Set | Object file library | -y | Win, UNIX | Initialize
Plays | Set | File of input keystroke script | -k | Win, UNIX | Initialize
RunPath | Set | Folder where "wrun32.dll" is located | -runpath: | Win, UNIX | Initialize
Switches | Set | List of Special Names switches to turn on | -# | Win, UNIX | Initialize
TerminalOut | Set | Capture terminal output to a file | -t | Win, UNIX | Initialize
Property Name | Get/Set | Description | Command Option | Platform | Method
Cache | Set | Leave program in cache after execution | -cache | Win, UNIX | Call
CGIWarnings | Set | Suppress warning messages in CGI programs | -f | Win | Initialize
CharToGui | Set | Convert character screens to GUI equivalent | --CharToGui | Win | Initialize
Debug | Set | Execute ACUCOBOL-GT debugger | -d | Win, UNIX | Call
DumpMem | Set | Dump memory for memory access violations | -z | Win, UNIX | Initialize
ExtendedError | Set | Display extended error codes for file error "30" | -x | Win, UNIX | Initialize
IgnoreSignals | Set | Ignore terminal hang-up signals | -h | UNIX | Initialize
LinkageLength | Set | Disable Linkage item length test | -u | Win, UNIX | Initialize
ListConfig | Set | List contents of configuration file | -l | Win, UNIX | Initialize
NonNumeric | Set | Suppress warnings when non-numeric data is used as numeric data | -w | Win, UNIX | Initialize
NoSaveDebug | Set | Prevent debugger from reading and writing adb | --no-save-debug | Win, UNIX | Initialize
SafeMode | Set | Run in safe mode | -s | UNIX | Initialize
ShowError | Set | Display error message text in a MesssageBox | -show | Win | Call
TerminalInit | Set | Inhibit terminal initialization | -b | UNIX | Initialize
Unicode | Set | Pic X() parameters passed as unicode | -uni | Win, UNIX | Call
Wide | Set | Pic X() parameters passed As DBC strings | -wide | Win, UNIX | Call
ZipErrorFile | Set | Suppress warning messages in CGI programs | -g | Win, UNIX | Initialize
Parent topic: Using the .NET Interface Assembly, "wrunnet.dll"


Error codes

Call returns the following error codes to the .NET environment. The .NET programmer can refer to the error code, an enumerator, to get more information.

When ShowError is "true", Call displays the message text. The property, LastErrorMsg, is also available to retrieve the last error text string. When "wrunnet.dll" is referenced in a Visual Studio .NET project or the compiled COBOL program used the "--netdll" option, error codes can be viewed using the object browser of Visual Studio .NET. When the "--netdll" option is used, errorTypes is inluded in the "ProgramName_CVM.dll".

public enum errorTypes : int
{
/* runtime is not thread-safe */
CS_MULTIPLE_OS_THREADS = -4,
CS_WIN_INIT_FAILED     = -3,
CS_STOP_RUN            = -2,
CS_CONT                = -1,
CS_OK                  = 0,  /* program executed with no errors */
CS_MISSING             = 1,  /* Program missing or inaccessible */
CS_NOT_COBOL           = 2,  /* Not a COBOL program */
CS_INTERNAL            = 3,  /* Corrupted program */
CS_MEMORY              = 4,  /* Inadequate memory available */
CS_VERSION             = 5,  /* Unsupported version of object code */
CS_RECURSIVE           = 6,  /* Program already in use */
CS_EXTERNAL            = 7,  /* Too many external segments */
CS_LARGE_MODEL         = 8,  /* Large-model program not supported */
CS_JAPANESE            = 14, /* Japanese extensions not supported */
CS_MULTITHREADED       = 22, /* Multithreaded CALL RUN illegal */
CS_AUTHORIZATION       = 23, /* Access denied */
CS_CONNECT_REFUSED     = 25, //Connection refused
//Program contains object code for a different processor
CS_MISMATCHED_CPU      = 27,
CS_SERIAL_NUMBER       = 28  /* Incorrect serial number */
//user count exceeded on remote server
CS_USER_COUNT_EXCEEDED = 29,
CS_LICENSE             = 30, /* License error */
CS_UNSUPPORTED_PARAM   = 31, /* unsupported parameter */
CS_COBOL_SIGNAL        = 65,
CS_COBOL_FATAL_ERROR   = 66
};
Parent topic: Using the .NET Interface Assembly, "wrunnet.dll"


CompilerTypes

When "wrunnet.dll" is referenced in a Visual Studio .NET project or the compiled COBOL program used the "--netdll" option, CompilerTypes can be viewed using the object browser in Visual Studio .NET. When the "--netdll" option is used, CompilerTypes is included in the "ProgramName_CVM.dll".

public enum CompilerTypes : byte
{
 NSE  = 0,
 NSEZ  = 1,
 CONS  = 2,
 ANL  = 3,
 ABS  = 4,
 ABSJ  = 5,
 PARAM  = 6,
 GRPL  = 7,
 ANSE  = 8,
 GRPVL  = 9,
 ANS  = 10,
 ANSJ  = 11,
 GRP  = 12,
 GRPV  = 13,
 NPU  = 14,
 NNCU  = 15,
 NSU  = 16,
 NNU  = 17,
 NSS  = 18,
 NSSL  = 19,
 NCU  = 20,
 NBU  = 21,
 NCS  = 22,
 NNCS  = 23,
 NIS  = 24,
 NISL  = 25,
 NPS  = 26,
 NFP  = 27,
 TEMP  = 28,
 NPP  = 29,
 NBS  = 30,
 NNS  = 31,
 NAT  = 32,  /* codes are for double byte */
 NATJ  = 33, /* codes are for double byte */
 NATE  = 34, /* codes are for double byte */
 WID  = 35,  /* codes are for double byte */
 WIDJ  = 36, /* codes are for double byte */
 EWID  = 37, /* codes are for double byte */
 TMP_PFX = 38,
 NEFP  = 39,
 NBFP  = 40
};
Parent topic: Using the .NET Interface Assembly, "wrunnet.dll"


Using the ACUCOBOL-GT COM Server

An alternate way to provide COBOL services to a .NET assembly is through the ACUCOBOL-GT COM server.

The COM server is a COM object containing the ACUCOBOL-GT Windows runtime DLL. It provides a COM interface between the ACUCOBOL-GT runtime and programs running outside the runtime. For more information on the COM server, see Using the ACUCOBOL-GT COM Server.

When the COM server is added to a .NET project, .NET creates a proxy object, "Interop.AcuGTObjects.dll", that provides an interface between .NET and the ACUCOBOL-GT COM server object. The .NET proxy gathers data intended for use by the COBOL program and packages it in COM variant formats before sending it to the ACUCOBOL-GT COM server. This process is known as data marshalling. The COBOL program uses C$GETVARIANT and C$SETVARIANT to retrieve and update data held by the ACUCOBOL-GT COM server object. The proxy also unmarshals data received from ACUCOBOL-GT COM server before delivering it back to the .NET program. The proxy is designed to manage the interchange between the .NET and COBOL worlds.

Invoke an ACUCOBOL-GT program from a .NET assembly as follows:

  1. Install and register the ACUCOBOL-GT COM server on the system running .NET. Install the COBOL object file there as well. Instructions are provided in Using the ACUCOBOL-GT COM Server.

    Once the COM server is registered on the .NET system, the ACUCOBOL-GT runtime is then exposed to any program running in that environment.

  2. To use the ACUCOBOL-GT COM Server, select a .NET application that requires the ACUCOBOL-GT interface.
    1. In Visual Studio .NET, right-click the project name in the Solution Explorer window to display a selection menu.
    2. Select Add Reference from the resulting pop-up menu to display the Add Reference dialog box.
    3. Select the COM tab from the Add Reference dialog box.
    4. Select ACUCOBOL-GT 8.0 Type Library (Acugt.tlb) from the list and click OK.

    Visual Studio generates a .NET proxy module to interface with your COM object identified as "Interop.AcuGTObjects.dll".

    Visual Studio .NET Add Reference dialog box

  3. Add the proxy interface to the .NET application source. For example, if you are using Visual Basic or C#, you would add the following:

    Visual Basic:

    Dim AcugtInterface As Object
AcugtInterface = New AcuGTObjects.AcuGTClass

    C#:

    AcuGTObjects.AcuGTClass AcugtInterface = new  AcuGTObjects.AcuGTClass();
  4. Run the .NET service and it will invoke the COBOL program as necessary.
Parent topic: Calling COBOL from .NET


Calling .NET from COBOL

ACUCOBOL-GT gives you access to .NET assemblies, both graphical and non-graphical, including user controls and Windows forms controls. You do not need to know object-oriented programming or the NET Framework.

This interface includes a graphical utility known as the .NET Definitions Generator, or NETDEFGEN.exe. This utility allows you to view and select .NET assemblies for translation to a COBOL COPY file. COBOL programmers already familiar with the DISPLAY, CREATE, MODIFY, INQUIRE, and DESTROY statements can immediately write COBOL programs that consume .NET assemblies.

The runtime starts the .NET CLR, loads and executes the requisite .NET components, and returns the results to the COBOL program. There is a runtime configuration variable for tracing the CLR control module: NET_FILE_TRACE. To turn on tracing set NET_FILE_TRACE to 1. This creates NetTraceFile.txt in the directory where atermmgr.dll is located. The Default is 0 [off].

The next section provides details on adding and using .NET assemblies in COBOL programs by using NETDEFGEN and AcuToNET.dll.

Note: ACUCOBOL-GT requires Microsoft .NET Development Framework Version 2.0. However, with NETDEFGEN, you can process Version 1.0 - 3.5 assemblies.
Note: Prior to version 9, the AcuToNet.dll was used to provide .NET support. By default, this interface is no longer needed in versions 9 or higher of ACUCOBOL-GT. A new internal method of .NET support was added to version 9 that enables greater .NET support than what could be achieved with the previous AcuToNet.dll method. However, if you experience issues with the new method you can revert to using the AcuToNet.dll method. See Using the AcuToNet.dll interface for instructions.
  • Using .NET Assemblies in COBOL
  • NETDEFGEN Utility Reference
Parent topic: Working with .NET Assemblies


Using .NET Assemblies in COBOL

The .NET bridging interface includes a graphical utility known as NETDEFGEN. This utility allows you to view and select .NET assemblies for translation to a COBOL COPY file. It is similar to the AXDEFGEN utility that ACUCOBOL-GT provides for programming with ActiveX and COM objects. However, NETDEFGEN is designed to work with .NET assemblies.

The COPY files generated by NETDEFGEN supply the ACUCOBOL-GT compiler with all the necessary information for interfacing with .NET assemblies. When you include the COPY files in your COBOL program, you can interact with the .NET assembly via these COBOL statements: DISPLAY, CREATE, MODIFY, INQUIRE, and DESTROY.

Invoke .NET assemblies from your ACUCOBOL-GT program as follows:

  1. If it is not installed already, install and register the .NET framework on your development system.
  2. Run "netdefgen.exe". It is located in the \AcuGT\bin directory wherever you installed ACUCOBOL-GT on your machine. NETDEFGEN locates the .NET assemblies in the Global Assembly Cache (GAC) on the machine and lists them. For more information on the NETDEFGEN utility, see the NETDEFGEN Utility Reference later in this chapter.)
  3. From the list of cached assemblies displayed in the NETDEFGEN dialog box, select the .NET assembly that you want to include in your COBOL program, then select the NameSpace class or classes that you specifically want to access.
    Note: If the assembly of interest is not in the GAC, use the Browse button to navigate to the directory where the assembly resides.
  4. Specify an output path and filename for the COBOL COPY file that will be generated. Click Generate when done.

    The utility automatically generates a COPY file for the chosen assembly. For information on the contents of NETDEFGEN COPY files, see the NETDEFGEN Utility Reference.

    The utility also generates something known as an event DLL. The event DLL is named after the NameSpace class found in the COPY file, appended by the suffix ".dll".

  5. In a code editor, open your ACUCOBOL-GT program and go to its Environment Division/Configuration Section.
  6. In the COBOL program's Special-Names paragraph, enter a COPY statement for the COPY file that you specified in step 4. If you are adding several .NET assemblies, copy several COPY files into this paragraph. Add a period at the end of the paragraph. For example:
    SPECIAL-NAMES
COPY "netcontrol1.def".
COPY "netcontrol2.def".
.
  7. Add the .NET control to your program. Minimally, you must include the ASSEMBLY-NAME, NAMESPACE, and CLASS-NAME parameters that are found in the COPY file.

    If the .NET control that you are adding is graphical, (i.e., it has the word "Visual" in the COPY file NameSpace class definition), you can add it to your program in one of two ways:

    1. Go to the Screen section of your program and add the new control to your screen. For example:
      screen section.
01  screen-1.
    03 SOME-NETCONTROL, "@My.Assembly",
       LINE 1, COL 2,
       NAMESPACE IS "My.Test.Namespace",
       CLASS-NAME IS "MyGUIClass",
        CONSTRUCTOR IS CONSTRUCTOR2(PARM1, PARM2, PARM3,
       PARM4, PARM5, PARM6, PARM7),
       EVENT PROCEDURE IS USERCONTROL-EVENTS.
    2. Go to your program's Procedure Division and create the control using the DISPLAY statement. For example:
      DISPLAY "@My.Assembly"
     NAMESPACE IS "My.Test.Namespace"
     CLASS-NAME IS "MyGUIClass"
     EVENT PROCEDURE IS MY-EVENT-PROCEDURE
     HANDLE IS MY-GUI-HANDLE.
If the .NET assembly that you are adding is non-graphical, use the CREATE statement to add it to your program as shown below:
CREATE "@My.Assembly"
     NAMESPACE IS "My.Test.Namespace"
     CLASS-NAME IS "MyClass"
     HANDLE IS MY-NONGUI-HANDLE.

      Note that .NET properties, methods, and events should always be prepended with an "@" sign in case they clash with COBOL reserved words or ACUCOBOL-GT graphical control property and style names. The "@" character identifies the relationship of the name to .NET or ActiveX.

  8. Add any optional .NET parameters to the Screen Section, DISPLAY, or CREATE statement. For example, add the FILE-PATH parameter to point to assemblies that will not be placed in the end-user's GAC (you must first create an XML file containing the file path), or add the CONSTRUCTOR parameter to instantiate a class. Valid .NET parameters are described in NETDEFGEN COPY files.
  9. Perform whatever functions you want on the control. If desired, you can modify a .NET control's properties or invoke methods using the MODIFY statement. For example:
    MODIFY MY-NONGUI-HANDLE printIteration = NUMBRPRINTS.
MODIFY MY-NONGUI-HANDLE lastName = LAST-NAME.
MODIFY MY-NONGUI-HANDLE "ToLog"("Hello From COBOL", 99, "It's a Good Thing").
If you want to retrieve a property value, you can use the INQUIRE statement.  For example:
INQUIRE MY-NONGUI-HANDLE printIteration IN QPRINTS.
INQUIRE MY-NONGUI-HANDLE lastName IN LAST-NAME.
  10. To destroy .NET controls, use the DESTROY statement. Ultimately, all controls that you instantiated in step 7 should be destroyed. You can use DESTROY ALL to destroy all controls in the Screen section or created with a DISPLAY statement. However, if the control was created with a CREATE statement, then it must be destroyed with a Format 1 DESTROY handle-name statement.
    Note: For details on using the CREATE, DISPLAY, MODIFY, INQUIRE, and DESTROY statements, see Procedure Division Statements. A complete sample program is provided below for your reference.
  11. Compile the COBOL program.
  12. Update the configuration file named "NetEvents.ini" with path statements of the event DLL(s) created when you ran NETDEFGEN, or place the DLL(s) in the same directory as the ACUCOBOL-GT runtime, "wrun32.exe". The runtime must be able to access these event DLLs as well as the .NET assembly itself.
  13. Run your COBOL program via "wrun32.exe MyProgram.acu".

At run time, your COBOL program transparently starts the .NET CLR, loads the requisite .NET assemblies and event handlers, executes .NET assembly methods, and returns the results to the COBOL program.

  • CoCreate Instance Failed Error
  • Creating and Passing .NET Objects as Parameters
  • Sample Program
  • Limits and Restrictions
  • Using AcuToNet.dll Interface
  • .NET Control Distribution and Licensing
  • Name Clashes
Parent topic: Calling .NET from COBOL


CoCreate Instance Failed Error

When attempting to run your program, there is a special case that will cause you to receive a runtime error message of "CoCreate Instance failed". This case involves running on a Microsoft Vista or Windows 2008 machine that previously (or currently) had ACUCOBOL-GT Version 8.0 installed on that machine.

This error is due to a combination of versions 8.0 and 8.1 using different CLSIDs (a unique identifier) for AcuToNet.dll, and Microsoft's more restrictive version control methods for side by side DLLs.

To correct this situation you need to use the ACUCOBOL-GT utility RegAsm20Acu.exe to register the version 8.1 AcuToNet.dll. Do this by performing the following steps:

  1. From a command prompt, navigate to the bin directory of AcuGT (Program Files\Acucorp\Acucbl810\AcuGT)
  2. Entering the following command:
    regasm20acu /register /codebase AcuToNet.dll
Note: When distributing Version 8.1 ACUCOBOL-GT applications with .NET controls to Vista or Windows 2008 machines that previously had version 8.0 installed, you must perform the registration step on the target machine. In this case you would go to the directory containing the AcuToNet dll, and issue the RegAsm20Acu command as described in step 2 above. If the machine you are distributing to never had version 8.0 installed than it is not necessary to perform this step.
Parent topic: Using .NET Assemblies in COBOL


Creating and Passing .NET Objects as Parameters

ACUCOBOL-GT programs can retrieve .NET objects or pass .Net objects as parameters. These .Net objects can also be acted upon using the MODIFY and INQUIRE statements.

.Net objects are supported by identifying them as belonging to a generic namespace of "MICROFOCUS" and class "NETOBJECT". a COBOL program that wants access to .NET objects must have defined the @MICROFOCUS.NETOBJECT in the special names paragraph.

.Net objects must be stored in a data type identified by "USAGE HANDLE OF OBJECT". If you wish to invoke MODIFY and INQUIRE statements for certain GET/PUT properties or methods on the .Net object, you need to create the equivalent COBOL definitions as part of the @MICROFOCUS.NETOBJECT namespace/class. You can create the def file for this generic object with NetDefGen.

Limits and Restrictions

  • .NET objects cannot be created in your COBOL program. They are only retrieved or passed as a paramter.
  • Overloaded methods are not supported with .NET objects. Only one definition may be used.
  • .Net objects cannot be retrieved or passed if they are part of an array/list.
  • .Net objects cannot be retrieved from events using the C$GETNETEVENTDATA library routine.
  • .Net objects as parameters are not supported when using the runtime switch - -a2n
  • To Create and Pass .NET Objects as Parameters
Parent topic: Using .NET Assemblies in COBOL


To Create and Pass .NET Objects as Parameters

  1. In the special names paragraph of your COBOL program, define the namespace/class of @MICROFOCUS.NETOBJECT. For example:
    SPECIAL-NAMES.
COPY NetObjects.def

    The definition file generated by NetDefGen should not be modified.

  2. In the working storage section of the COBOL program define the data type that will hold the reference to the .Net object. For example:
    77 MyTimeObject1       usage handle of OBJECT value 0.
77 MyTimeObject2       usage handle of OBJECT value 0.
77 MyFontObject        usage handle of OBJECT value 0.

    The data type must be identified as HANDLE OF OBJECT.

  3. Use the new data type to refer to .Net objects that can be retrieved or passed. For example:
    inquire NetListBox1 @MyClickTime MyTimeObject1
inquire NetListBox2 @MyClickTime MyTimeObject2
inquire NetFontSelect @SelectedFont MyFontObject
.
.
.
modify NetListBox1 "@compareTimes" (MyTimeObject2)
                          giving ws-ticks
modify NetListBox2 "@setFont" (MyFontObject)
  4. To invoke GET/PUT properties or method calls on the .Net object, add the def file you careated with NetDefGen to the SPECIAL-NAMES section of your COBOL program.
  5. Since all GET/PUT properties and method calls for all .Net objects are defined under a single, generic NetObject class, you must take care not to call a method or use a property that does not belong with the object you are trying to modify. Errors of this nature will not be detected until runtime and will result in the property/method not being found.
  6. Prior to invoking the inquire/modify statements on a .Net object, make sure that the object handle has a value greater than 0, otherwise you will encounter an error. Finally it is good programming practice to destroy objects that outlive their usefulness.
Parent topic: Creating and Passing .NET Objects as Parameters


Sample Program

The following example shows how to use the CREATE, DISPLAY, MODIFY, and INQUIRE statements to create and interact with the .NET control once its COPY file has been included in your COBOL program. First, you'll find a sample COPY file. Then you'll find a sample COBOL program, with comments, in bold.

NETDEFGEN COPY File

-----  Generated by NetDefGen  -----
OBJECT @ASSEMBLY
NAME "@My.Assembly"
VERSION "1.0.0.0"
CULTURE "neutral"
STRONG "3f6e8fa90dc2951b"

NAMESPACE "My.Test.Namespace"
CLASS "MyClass "

CONSTRUCTOR,  0, @CONSTRUCTOR1

* printIteration
                PROPERTY_GET, 0, @printIteration
                         RETURNING, "int", TYPE 3
* printIteration
                PROPERTY_PUT, 0, @printIteration
                        "int (Property Value)", TYPE 3

* Int32 ToLog(System.String, Int32, System.String)
                METHOD,  0, "@ToLog"
                         "BSTR" @StringIn, TYPE 8
                         "int" @someNumber, TYPE 3
                         "BSTR" @anotherString, TYPE 8
                         RETURNING "int", TYPE 3
*  Public fields
FIELD,   0, @lastName
                         RETURNING, "BSTR", TYPE 8

NAMESPACE "My.Test.Namespace"
CLASS "MyGUIClass"
VISUAL

CONSTRUCTOR,  0, @CONSTRUCTOR1

* LogRecordRead  (Int32)
               EVENT, -709034780, @MyGUIClasss_LogRecordRead

* LogRecordWritten  (Int32, System.String)
               EVENT, -1411090252, @MyGUIClass_LogRecordWritten

NAMESPACE "My.Test.Namespace"
CLASS "UserControl1"
VISUAL

        CONSTRUCTOR,  0, @CONSTRUCTOR1

        CONSTRUCTOR,  0, @CONSTRUCTOR2
                         "BSTR" @userStuff, TYPE 8
                         "int" @intData, TYPE 3
                         "unsigned int" @uintData, TYPE 19
                         "single" @floatData, TYPE 4
                         "double" @doubleData, TYPE 5
                         "short" @shortintData, TYPE 2
                         "unsigned short" @ushortintData, TYPE 18

 -----  End Generated NetDefGen Code  -----

COBOL Program

* Handles can be associated with a specific
* Assembly.NameSpace.Class
* Use this form when the COBOL statement, MODIFY - INQUIRE, etc.,
* uses the handle before a CREATE or DISPLAY statement occurs
* in the program.
77 MY-NONGUI-HANDLE USAGE IS HANDLE OF "@My.Assembly.My.Test.Namespace.MyClass".

77  MY-GUI-HANDLE       USAGE IS HANDLE.
77  NUMBRPRINTS         USAGE IS SIGNED-INT VALUE 3.
77  QPRINTS             USAGE IS SIGNED-INT.
77  PARAM1              USAGE IS SIGNED-INT.
77  PARAM2              PIC x(128).
77  LAST-NAME           PIC x(32).
77  PARM1               pic x(12) VALUE "HELLO WORLD".
77  PARM2               USAGE IS SIGNED-INT VALUE 1111.
77  PARM3               USAGE IS UNSIGNED-INT VALUE 2222.
77  PARM4               USAGE IS FLOAT VALUE 0.3333.
77  PARM5               USAGE IS DOUBLE VALUE 123456.55.
77  PARM6               USAGE IS SIGNED-SHORT VALUE 4444.
77  PARM7               USAGE IS UNSIGNED-SHORT VALUE 5555.

*CREATE  - instantiate a NON-GUI CLASS.
CREATE "@My.Assembly"
NAMESPACE IS "My.Test.Namespace"
CLASS-NAME IS "MyClass"
EVENT PROCEDURE IS EVENT-PROC
HANDLE IS MY-NONGUI-HANDLE.

*DISPLAY - instantiate a GUI CLASS. GUI classes have a keyword
*VISUAL in the COPY file after the CLASS keyword.
DISPLAY "@My.Assembly"
NAMESPACE IS "My.Test.Namespace"
CLASS-NAME IS "MyGUIClass"
EVENT PROCEDURE IS MY-EVENT-PROCEDURE
HANDLE IS MY-GUI-HANDLE.

*INQUIRE - retrieve the value of a PROPERTY OR FIELD.
INQUIRE MY-NONGUI-HANDLE printIteration IN QPRINTS.
INQUIRE MY-NONGUI-HANDLE lastName IN LAST-NAME.

*MODIFY  - execute a method.  Methods are case sensitive. They
*must match the COPY file case and be enclosed in quotes.
MODIFY MY-NONGUI-HANDLE "ToLog"("Hello From COBOL", 99, "It's a Good Thing").

*MODIFY  - set the value of a PROPERTY OR FIELD.
MODIFY MY-NONGUI-HANDLE printIteration = NUMBRPRINTS.
MODIFY MY-NONGUI-HANDLE lastName = LAST-NAME.

*Capture events and retrieve event data - Use EVENT-DATA-2 or the
*COPY file event name.

*EVENT-DATA-2 and the COPY file event name are an event ID.  The
*runtime tries to locate the last event thrown by matching the
*event ID.  If you use CONTROL-HANDLE or HANDLE IS from the CREATE
*and DISPLAY statements, the runtime tries to locate the last
*event thrown by matching the .NET Interface for the control.
*Using a CONTROL-HANDLE or COPY file event name/numeric ID makes
*a difference when event procedures cause another event before
*collecting the first event's DATA.  If the events are different,
*use the COPY file event name to retrieve the desired event data.
*If you use CONTROL-HANDLE, the most recent event, that is, the
*Last In First Out (LIFO), received by the runtime for a .NET
*interface is returned to a COBOL program possibly resulting in
*incorrect event data.

MY-EVENT-PROCEDURE.
EVALUATE EVENT-TYPE
    WHEN MSG-NET-EVENT
EVALUATE EVENT-DATA-2
    WHEN @MyGUIClass_LogRecordWritten
CALL "C$GETNETEVENTDATA" USING @MyGUIClass_LogRecordWritten PARAM1 PARAM2
    WHEN @MyGUIClass_LogRecordRead
CALL "C$GETNETEVENTDATA" USING EVENT-DATA-2 PARAM1
END-EVALUATE
END-EVALUATE.

*Screen section .NET Control with a Constructor

screen section.
01  screen-1.
    03  SOME-NETCONTROL, "@My.Assembly",
        LINE 1, COL 2,
        NAMESPACE IS "My.Test.Namespace",
        CLASS-NAME IS "UserControl1",
          CONSTRUCTOR IS CONSTRUCTOR2(PARM1, PARM2, PARM3, PARM4, PARM5,
        PARM6, PARM7),
        EVENT PROCEDURE IS USERCONTROL-EVENTS.

*Coding exceptions. NameSpace is optional in C# and VB NET and
*therefore may not appear in a COPY file. However, DISPLAY,
*CREATE, and Screen Section COBOL statements require a NameSpace
*entry. When a COPY file is missing a NameSpace keyword, use the
*class name as the NameSpace value on DISPLAY, CREATE, and Screen
*Section statements.
Parent topic: Using .NET Assemblies in COBOL


Limits and Restrictions

Starting with version 9, ACUCOBOL-GT programs can now retrieve .NET objects or pass .Net objects as parameters. These .Net objects can also be acted upon using the MODIFY and INQUIRE statements. However, MODIFY and INQUIRE is not supported if a .Net object has an Event and the Event (or Events) are stored_object.

If using the AcuToNet.dll method of .NET support, the .NET interface cannot be used to instantiate .NET executables. The CREATE and DISPLAY statements associated with this interface support only .NET DLLs and controls. However, you can make a call to the C$SYSTEM library routine to spawn a .NET executable. This routine is described in C$SYSTEM.

ACUCOBOL-GT supports methods that have integer, unsigned integer, byte, string, float single, and double precision data types, all known as blittable data types in the .NET world. Blittable data types are those that have a common representation in both managed (MSIL) and unmanaged (COBOL) code. Non-blittable types are ambiguous and not supported.

A special case generates a runtime error of "CoCreate Instance failed". See CoCreate Instance Failed Error for details on the case and how to overcome the error.

Parent topic: Using .NET Assemblies in COBOL
Related information
CoCreate Instance Failed Error


Using AcuToNet.dll Interface

To enable your COBOL programs to interface with languages such as C#, the .NET Framework requires that any variables passed to the framework from the COBOL program are marshalled. From extend version 9 onwards, marshalling and .NET support is handled internally. However, if you experience problems with this, you may revert to the previous method of using the AcuToNet.dll interface by following these steps from a command prompt:

  1. To register AcuToNet.dll for use with the .NET Framework, navigate to C:\Program Files (x86)\Micro Focus\extend x.x.x\AcuGT\bin, and enter one of the following commands:
    regasm20acu /register /codebase AcuToNet.dll
    regasm40acu /register /codebase AcuToNet.dll
    Note: regasm20acu is compatible with .NET Framework 2.0 and later, and regasm40acu is compatible with .NET Framework 4.0 and later.
  2. To register the marshalling executable required for COBOL to interop with .NET, whilst in the same location, enter the following command:
    marshal.exe /RegServer
    Note: This file is automatically registered during product installation. Manual registration such as this will be required if you have copied the extend software from one machine to another.
  3. When running your COBOL program, use the - -a2n runtime option.
  • Optimizing the "AcuToNet.dll" Interface
Parent topic: Using .NET Assemblies in COBOL


Optimizing the "AcuToNet.dll" Interface

At run time, your COBOL program transparently communicates with an interface file called "AcuToNet.dll". This interface starts the .NET CLR, loads the requisite .NET assemblies and event handlers, executes .NET assembly methods, works with properties, and returns the results to the COBOL program.

The ACUCOBOL-GT to .NET bridging interface is delivered in compiled MSIL format. Any time a .NET assembly or "AcuToNet.dll" is loaded, it undergoes an additional compilation in the Microsoft Just-In-Time (JIT) compiler. This can raise questions about performance and whether it's possible to create native code "executables" in .NET.

Microsoft provides a tool in the .NET Framework directory called the Native Image Generator ("NGen.exe") that can be used for this purpose. This utility compiles an assembly into a "native image". You could run the NGen utility on "AcuToNet.dll", located in the ACUCOBOL-GT /bin directory. NGen will compile and place it in the GAC under the same name. To avoid confusion you could rename the original file to "ORIG_AcuToNet.dll". Then when the CLR loads the assembly, it will check the cache to see if a precompiled version exists, and if it does, it will load that.

Although you might think this will improve performance, there a number of drawbacks to consider (including maintenance issues), and you may not obtain the performance improvement you expect either. NGen creates a native image for a hypothetical machine architecture. The advantage is that it runs on any x86 processor, for example. However, when the JIT compiler executes, it takes the specific machine it's running on into account and makes appropriate optimizations. The result is that assemblies dynamically compiled at run time often out perform precompiled assemblies.

Another drawback is that changes to a system's hardware configuration or operating system (like service pack updates) often invalidate the precompiled assembly.

Parent topic: Using AcuToNet.dll Interface


.NET Control Distribution and Licensing

If you want to include a .NET assembly in your COBOL application, you must first acquire it and install it on the development machine. In some cases, a partner may provide the control. In others, you may download it off the Internet and license it for distribution.

Unlike ActiveX, .NET does not have a specific parameter for licensing but does have a class that performs this function. .NET uses a design-time licensing model that is verified again at run time, usually in the CONSTRUCTOR phase. Because ACUCOBOL-GT supports constructors, it also supports custom run-time licensing that requires parameters.

If you encounter an ActiveX control that was converted to .NET using Microsoft's "Aximp.exe" utility and you experience licensing conflicts and violations, use the ActiveX version of the control instead of the converted .NET version.

To use ActiveX controls with ACUCOBOL-GT, use the AXDEFGEN utility rather than NETDEFGEN.

Parent topic: Using .NET Assemblies in COBOL


Name Clashes

Often a .NET assembly may have property, method, or event names that are the same as COBOL reserved words or ACUCOBOL-GT standard property or style names. This creates ambiguity for the compiler. In addition, because .NET class names are used in the USAGE HANDLE clause of data description entries, in Screen Section items, and in DISPLAY statements, they may also cause ambiguities with COBOL reserved words.

To avoid these ambiguities, NETDEFGEN prepends an "at" sign character ("@") to every class, property, method, and event name in the generated COPY file.

In addition, ambiguity may occur with event names when two or more .NET assemblies define the same event name. To reduce this possibility, NETDEFGEN prepends the control name to each event name. For example, if a .NET control named "MyControl" has an event called "RightMouseButtonClick", NETDEFGEN names the control "@MyControl" and the event "@MyControlRightMouseButtonClick".

The "@" sign is not required unless ambiguities in the meaning exist in a certain context. However, to guard against unanticipated name conflicts and to ensure clarity in the reading and maintenance of the source code, we strongly recommend that you always use "@" when referring to a .NET property, style, or method in your source code. If you do not use an "@" sign and a clash occurs, a compiler error results.

Parent topic: Using .NET Assemblies in COBOL


NETDEFGEN Utility Reference

The NETDEFGEN utility is a wizard-based application designed to facilitate the consumption of .NET assemblies from Windows-based ACUCOBOL-GT programs. The role of NETDEFGEN is to locate the names of .NET assemblies on the user’s machine and generate a COBOL COPY file for the selected assembly.

The COPY file is used by the ACUCOBOL-GT compiler for syntax and parameter type checking as well as efficient code generation. For instructions on how to use NETDEFGEN and what to do with the COPY file once it is generated, see Using .NET Assemblies in COBOL.

NETDEFGEN interrogates the assembly and produces an English translation for NameSpaces, classes, methods, enumerations, properties, and events that the ACUCOBOL-GT compiler understands. At run time, the COBOL program accesses the assembly using a NameSpace and class from the COPY file.

The resultant COPY file is included in a COBOL program for use by the compiler and programmer. In addition to the COPY file, NETDEFGEN generates event handlers for each class in the assembly. This is native MSIL code that listens for .NET assembly events, routes them to the ACUCOBOL-GT runtime, which in turn delivers events to the COBOL program. Event handlers are loaded by the runtime when the COBOL program executes a DISPLAY or CREATE statement or has a reference to an assembly in a Screen Section. The runtime locates event handlers from a configuration file called "NetEvents.ini". This file contains a list of directory paths indicating where to search for event handlers. "NetEvents.ini" must be located in the same directory as the runtime. If "NetEvents.ini" is not present, the runtime attempts to load event handlers from the folder where the runtime is located.

Windows base types-such as integer, unsigned integer, float, double, byte, character, and character string-are supported. Any method or constructor requiring parameter object creation by the COBOL program fails. For instructions on how to use .NET objects as parameters, see Creating and Passing .NET Objects as Parameters.

Note: If you want to include a .NET assembly in your COBOL application,you must first acquire it and install it on the development machine. If you have downloaded the control off the Internet, you may need to license it for distribution. see .NET Control Distribution and Licensing for more information.

The netdefgen.exe file is located in the \AcuGT\bin directory wherever you installed ACUCOBOL-GT. It is accessible from the Windows Start menu. When you run NETDEFGEN, the opening wizard screen appears:

Field or Button | Description
Assembly Location | Browse to the directory where the assembly from which you want to produce a COPY file resides. By default, this is the computer’s path to the Global Assembly Cache (GAC). Click the GAC button to restore this field to the GAC path at any time.
Assemblies

If the Global Assembly Cache (GAC) is the currently selected Assembly Location, then a tree view is displayed that contains all the assemblies found in the GAC. Due to the large number of assemblies, the list is grouped by processor architecture.

If the directory selected is other than the GAC, then all of the DLL and EXE files in that directory are listed (both assemblies and non-assemblies).

Select the assembly of interest from the list. All NameSpaces and classes found in that assembly display in the list box labeled Namespace Classes.

Help | Click the Help button to view the help file for the utility.
Exit | Select Exit from the menu bar to exit the utility.
Settings | Select Settings from the menu bar to change the default settings of the utility, including diagnostic settings. See Changing Default NETDEFGEN Settings for more information.

After selecting the Assembly desrired, click Next to continue to the next page.

Field or Button | Description
Namespace Classes | By default, when an assembly has been selected from the Assemblies list, all of the items found in the assembly are selected. Assemblies can contain many NameSpaces and classes, which can result in very large COPY files containing many references and declaration that are unused by your application. To reduce the size of your COPY file, select only those items that are needed by your application.

Click Next to continue to the next page.

Field or Button | Description
Class Members | The Tree View shows the Data Members (constructors, methods. fields, properties, and events) for the selected classes. By default, all members are selected. Uncheck the boxes next to any members you do not need in your COBOL application. Constructors cannot be unchecked. If the class is an enumerator, you may uncheck the whole class but not individual value fields.
Show Inherited Members | Checking this box will display all data members that are inherited from every ancestor. This will usually add a massive number of data members to the list. Use this option if a property, method, etc. that you want to use in your COBOL application is inherited from a parent class.

Click Next to continue to the next page.

Field or Button | Description
Copy File Location | Browse to the directory and filename of the COPY file to generate. If event handlers are generated, they will be located in the same directory with a filename prefix of the NameSpace and Class and a suffix of .dll.

Click Next to continue to the next page.

Field or Button | Description
Stored Objects.

If any of the Properties, Methods, etc., have parameters that are .NET objects, they will be listed here. To use MODIFY or INQUIRE on these objects, they must be included in the generic NETOBJECT class. If you only need to pass these objects from one strongly defined class to another, you do not need a definition for them.

For detailed information on using objects as parameters, see Creating and Passing .NET objects as parameters.

Skip | Don't care about Stored Objects? Click the Skip button and no NetObject definition file will be generated.

Click Next to continue to the next page.

Field or Button | Description
Stored Object Master List | These are the Stored Objects whose members will be included in the NetObject definition file. It starts out with the objects that were selected on the previous page. You can add more objects as needed (see Add to Master List below). Select an object to display its Data Members.
Data Members | The Tree View shows the Data Members (methods. fields, and properties) for the selected object. By default, all members are checked. Uncheck the boxes next to any members you do not need in your COBOL application. If the object is an enumerator, you may uncheck the whole class but not individual value fields.
Show Inherited Members | Checking this box will display all data members that are inherited from every ancestor. This will usually add a massive number of data members to the list. Use this option if a property, method, etc. that you want to use in your COBOL application is inherited from a parent class.
More Stored Objects | If any of the selected members have parameters that are also objects, they will be listed here.
Add to Master List | To add nested objects to the master list for inclusion in the NetObject COPY file, select the objects and click this button. You may then select them and edit their Data Members.

Click Next to continue to the next page.

Field or Button | Description
Stored Object Copy File Location | Browse to the directory and filename of the NetObject COPY file to generate.
Append or Overwrite | All Fields, Properties, and Methods for all Stored Objects that will be used in the COBOL program must be defined in the generic NETOBJECT class. Select Append to add the Stored Object definitions to an existing NetObject copy file. Select Overwrite to generate a new file. These options only appear if the file exists.

Click Next to continue to the next page.

Field or Button | Description
Generate | Click this button to generate the COPY file, any required event handlers, and the NetObject COPY file if necessary. Success or failure messages appear when the process is complete.
  • Changing Default NETDEFGEN Settings
  • NETDEFGEN COPY Files
  • Passing Data as Parameters
  • NETDEFGEN Methods
  • NETDEFGEN Properties
  • NETDEFGEN Events
  • NETDEFGEN Enumerators
  • NETDEFGEN Errors
  • Sample COPY File
  • Sample Controls
Parent topic: Calling .NET from COBOL


Changing Default NETDEFGEN Settings

To enter settings that will change the default behavior of the NETDEFGEN utility, select Settings from the menu bar. The Settings dialog appears.

Settings dialog box

Field or Button | Description
Directory Location Control:
Remember the Last Startup Directory | When this radio button is selected, as it is by default, the utility remembers the last Assembly Location selected and restores the selection on subsequent executions. Note that this is not affected by using the GAC button. You can select the GAC at any time and your previously selected directory is still retained.
Set a Fixed Startup Directory: | Use this selection if you want the NETDEFGEN utility to always start in the same Assembly Location directory. You can always Browse to a different directory if needed.
Remember the Last Copy File Name and Directory | When this radio button is selected, as it is by default, the utility remembers the last filename and directory selected under Copy File to Create and restores the selection on subsequent executions. Uncheck it if you want the utility to always assume that the startup location is the destination.
This option allows you to use up to two different versions of .NET. Enter the paths of the versioned tools and select the radio button for the version you want the utility to use. For example, enter the path to Microsoft .NET Development Framework Version 2.0 and select that version if you want the utility to process .NET 2.0-compatible assemblies. By default, it processes the latest version that you have installed. Double-clicking the field clears it, causing the utility to use whichever version is the current default on the development machine.
Create a debug version of event DLLs. | Causes the utility to include debug information in any event DLLs it creates.
Keep the generated event source. | Keeps the intermediate language source code that the utility generates when creating an event DLL. This can be most useful when working with our Technical Support to resolve a problem.
Parent topic: NETDEFGEN Utility Reference


NETDEFGEN COPY Files

COPY files that have been generated by the NETDEFGEN utility can contain any of several .NET parameters. The parameters are described below. The same parameters have been added to the ACUCOBOL-GT DISPLAY, CREATE, and Screen Section statements.

To access a .NET assembly, your COBOL program must pass at least the ASSEMBLY-NAME, NAMESPACE, and CLASS-NAME parameters. The rest of the .NET parameters are optional. That is because the compiler extracts these parameters from the COPY file if they are not included in your program. The exception is FILE-PATH, which is never included in the COPY file. If you want to include a FILE-PATH, you must encode it as described in the table below.

You pass .NET parameters when you first instantiate a .NET control in your COBOL program, that is, in the CREATE, DISPLAY, or Screen Section statement.

Note that the returning value of any field in the parameter list can be updated and returned to your COBOL program if desired.

COPY File Parameter | Parameter to Pass | Required/ Optional | Description
NAME | ASSEMBLY-NAME | Required | Filename of assembly, without extension
NAMESPACE | NAMESPACE | Required | Assembly NameSpace
CLASS | CLASS-NAME | Required | Class name
VERSION | VERSION | Optional | Version number of assembly
CULTURE | CULTURE | Optional | Cultural information like language, country, region; default is neutral.
STRONG | STRONG-NAME | Optional | PublicKeyToken; a cryptographic key that is generated by the Microsoft utility "sn.exe". All assemblies that are loaded in the GAC must include a STRONG-NAME key. If an assembly has a key, the compiler automatically retrieves it from the COPY file when it encounters a NAMESPACE/CLASS parameter.
CONSTRUCTOR(n) CONSTRUCTOR Optional if a default constructor exists All classes that result in an object have a constructor, which is a sort of method. When a class is instantiated with a CREATE, DISPLAY, or Screen Section statement in COBOL, this constructor is the first thing that is executed. It is executed once during the instantiation phase of an object.

Constructors, like methods, can have parameters, although most do not. The default constructor usually has no parameters. But if a .NET programmer has written a control that has constructors with parameters, you will see the word "CONSTRUCTOR" in the COPY file, followed by a number and the parameters associated with the constructor. This is called overloading. It occurs when the same method name has different parameters.

Following is an example of a constructor that has been generated by the NETDEFGEN utility:

OBJECT @ASSEMBLY NAME "@My.Assembly"
VERSION "1.0.0.0"
CULTURE "neutral"
STRONG "3f6e8fa90dc2951b"
NAMESPACE "My.Test.NameSpace"
CLASS "MyClass"
CONSTRUCTOR, 0, @CONSTRUCTOR1
CONSTRUCTOR, 0, @CONSTRUCTOR2
"BSTR" @value, TYPE 8
CONSTRUCTOR, 0, @CONSTRUCTOR3 "int" @overloadedconstruct, TYPE 3

Because CONSTRUCTOR1 has no parameters, you can use a CREATE, DISPLAY, or Screen Section entry without a CONSTRUCTOR parameter.

If you want to pass values, then you would select CONSTRUCTOR2 or CONSTRUCTOR3. The following depicts a CONSTRUCTOR parameter in a CREATE statement.

77 MY-ASSEMBLY-HANDLE USAGE IS HANDLE.
   CREATE "My.Assembly"
     NAMESPACE IS
     "My.Test.NameSpace"
     CLASS-NAME IS "MyClass"
       CONSTRUCTOR IS CONSTRUCTOR3
     123456)
     HANDLE IS MY-ASSEMBLY-HANDLE.
MODULE identifier | MODULE | Optional | Assemblies can have multiple modules within them; that is, assemblies constructed from other assemblies. MODULE identifies the file where this NameSpace class combination resides. It is used by the runtime to select a module within an assembly.
n/a FILE-PATH

Version 9.0 and above require .Net Framework 4.0, to access remote assemblies create a text file (in the runtime bin directory)called

wrun32.exe.config

Use the following XML in this file.

<configuration> <runtime> <loadFromRemoteSources enabled="true"/> </runtime> </configuration>

The O/S will use this file to allow the local runtime to access a remote assembly.

Optional

By default, the runtime looks for .NET assemblies in the end user's GAC. If it can't find the requested assembly in the GAC, it looks in the same directory as the runtime, "wrun32.exe".

Use FILE-PATH when the assembly that the program must access does not reside in the user's GAC or in the same directory as "wrun32.exe".

To include a FILE-PATH, first create an XML file containing the full file path where the assembly is located. Then in your COBOL program, include the FILE-PATH parameter followed by the full path of an XML file. If the FILE-PATH contains a filename only, the file is loaded from the same directory as the runtime.

Following is an example of a FILE-PATH XML file:

<?xml version="1.0"
    encoding="utf-8" ?>
<FILESPEC>
<Assembly>AmortControl</Assembly>
<Module>amortcontrol.dll</Module>
<StrongName />
<Version>1.0.1242.11216</Version>
<Culture>neutral</Culture>
<FilePath>E:\AmortControl\bin\Debug\AmortControl.dll</FilePath>
</FILESPEC>
Parent topic: NETDEFGEN Utility Reference


Passing Data as Parameters

The .NET CLR is type-sensitive and generates or throws an error if an exact match on a data type does not occur. At run time, ACUCOBOL-GT attempts to convert data types to the format expected by the CLR. For the best possible results, when passing data as parameters to .NET functions, use the table below to determine what parameter to pass.

For example, when the COPY file says "int", pass "SIGNED-INT" for the parameter type in your COBOL program. The ACUCOBOL-GT runtime converts this to "System.Int32" before passing it to the .NET assembly. The "int", "SIGNED-INT", and "System32.Int32" parameters all represent a 4-byte field holding signed binary data. The runtime also converts PIC s999 to a SIGNED-INT field.

COPY File Parameter | Parameter to Pass | Converted to .NET
BSTR - TYPE 8 | PIC X(n) | System.String
int - TYPE 3 | SIGNED-INT | System.Int32
unsigned int - TYPE 19 | UNSIGNED-INT | System.UInt32
single - TYPE 4 | FLOAT | System.Single
double - TYPE 5 | DOUBLE | System.Double
short - TYPE 2 | SIGNED-SHORT | System.Int16
unsigned short - TYPE 18 | UNSIGNED-SHORT | System.UInt16
unsigned char - TYPE 17 | PIC X | System.Byte

Be aware that the compiler does not always know which method declaration to use when methods are overloaded. In your COBOL program, be sure to use COBOL types that match the COPY file method declaration.

Parent topic: NETDEFGEN Utility Reference


NETDEFGEN Methods

The NETDEFGEN COPY file contains methods for classes within NameSpaces. These are the program functions for that .NET object. For example:

METHOD, 0, "@TypesTest"
           "unsigned int" @someUint, TYPE 19
           "single" @someFloat, TYPE 4
           "unsigned char" @someByte, TYPE 17
           "double" @someDouble, TYPE 5
           "boolean" @someBool, TYPE 11
            RETURNING "int", TYPE 3

Use the COBOL MODIFY statement to execute a method. The RETURNING value of any field in the parameter list may be updated and returned to the COBOL program. Update fields, IN/OUT, can be identified by types in the 16000 range. For example:

"int" @somefield TYPE 16387

Be aware that the compiler does not always know which method declaration to use when methods are overloaded. In your COBOL program, be sure to use COBOL types that match the COPY file method declaration.

Listed below are some guidelines on passing parameters to methods. Following these guidelines should help you ensure that the correct overloaded definition is compiled.

  • You can pass character strings as a PIC X...X defined variable or a quoted string literal. For example "This is a quoted string".
  • You can pass an unsigned integer as a USAGE UNSIGNED-INT defined variable or as a constant. For example, "0", "1", "356", and so on.
  • You can pass a signed integer as a USAGE SIGNED-INT defined variable or as a constant. For example, "+0", "+1", "+356", "-34", and so on.
  • You can pass a byte data type as a PIC X COMP-X defined variable.
  • You can pass a boolean data type as a PIC 9 defined variable that is casted as a boolean type:
    BOOL-PARAM    PIC 9.
"@methodname" (BOOL-PARAM AS VT_BOOL)

    or as a constant. For example, 00 = false, 01 = true.

    "@methodname" (01)
    Note:

    When casting data types is required, you must refer to the ACUCOBOL-GT provided COPY file "activex.def" in the Working-Storage section of your program.

  • You can pass a signed byte data type as a USAGE SIGNED-INT defined variable and then casted as a signed byte type:
    SBYTE-PARAM    USAGE SIGNED-INT.
"@methodname" (SBYTE-PARAM AS VT-I1)
  • You can pass a Microsoft date data type as a USAGE DOUBLE defined variable and then casted as a date type:
    DATE-PARAM    USAGE DOUBLE.
"@methodname" (DATE-PARAM AS VT-DATE)

For more examples of these and other forms of .NET method calls, see the sample application "NetObjects" in your Acucorp \sample\dotnet\NetObjects directory.

Parent topic: NETDEFGEN Utility Reference


NETDEFGEN Properties

NETDEFGEN translates all properties in the NameSpace class and includes them in the COPY file. For example:

* myPet
       PROPERTY_GET, 0, @myPet
          RETURNING, "int", TYPE 3
* myPet
       PROPERTY_PUT, 0, @myPet
          "int (Property Value)", TYPE 3

To retrieve a property value, use the INQUIRE statement. To change a property value, use the MODIFY statement.

Parent topic: NETDEFGEN Utility Reference


NETDEFGEN Events

NETDEFGEN generates event handlers for each class in the assembly. This MSIL code listens for .NET assembly events and routes them to the ACUCOBOL-GT runtime, which in turn delivers events to the COBOL program. If you see EVENT in the NETDEFGEN COPY file, as shown below, you know that event handlers were generated for this particular class.

* ooHHello  (Int32, System.String)
       EVENT, 1984084948, @MyClass_ooHHello

To capture events and data, write an event procedure using the COBOL EVENT PROCEDURE IS phrase on the DISPLAY, CREATE, and Screen section statements. Call the C$GETNETEVENTDATA library routine described in C$GETNETEVENTDATA. For example:

EVALUATE EVENT-DATA-2
  WHEN @MyClasss_ooHHello
  CALL "C$GETNETEVENTDATA" USING EVENT-DATA-2 PARAM1
Parent topic: NETDEFGEN Utility Reference


NETDEFGEN Enumerators

If the .NET assembly has enumerators, the NETDEFGEN COPY file lists them all and makes them accessible to the COBOL program. For example, the COPY file might list:

* "int animals_horses"
          ENUMERATOR, @animals_horses,  1

If the COPY file lists enumerators, you can use the enumerators in your COBOL program to set properties or invoke methods. This allows you to use a text name in place of a value, enhancing the readability of your program. The compiler checks the COPY file and substitutes the value associated with the name. For example, to set a property to the enumerator shown above, you could code:

MODIFY MyHandle  myPet = @animals_horses.

rather than

MODIFY MyHandle  myPet = 1.
Parent topic: NETDEFGEN Utility Reference


NETDEFGEN Errors

Occasionally when using NETDEFGEN, you may encounter the error message:

C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\ilasm.exe Event Handler Compilation Failed

as shown on the bottom of the screen below.

NETDEFGEN error message

This is a Microsoft message indicating that "ilasm.exe," a Microsoft executable, could not generate an event handler, probably because the assembly did not specify events. Our NETDEFGEN did not generate this message. It generates the COPY file normally despite the Microsoft error.

Parent topic: NETDEFGEN Utility Reference


Sample COPY File

Following is an example of a COBOL COPY file generated by the NETDEFGEN utility:

* .NET Copy Book - Generated On 1/28/2004 12:25:20 PM

     OBJECT @ASSEMBLY
     NAME "@AmortControl"
            VERSION "1.0.1266.13363"
            CULTURE "neutral"
            STRONG "null"

* FULLY-QUALIFIED-NAME AmortControl.AmortCalc, AmortControl, Version=1.0.1266.13363, Culture=neutral, PublicKeyToken=null

* AmortControl.AmortCalc
     NAMESPACE "AmortControl"
     CLASS "AmortCalc"
     MODULE "amortcontrol.dll"

          CONSTRUCTOR,  0, @CONSTRUCTOR1

* Void ProcData(Double, UInt32, Double, Double)
          METHOD,  0, "@ProcData"
                   "double" @AmortizAmount, TYPE 5
                   "unsigned int" @Months, TYPE 19
                   "double" @InterestRate, TYPE 5
                   "double" @WhatIfMonthlyPayment, TYPE 5

* Public - fields
          FIELD,   0, @MonthlyPayment
                   RETURNING, "double", TYPE 5
          FIELD,   0, @TotalInterest
                   RETURNING, "double", TYPE 5
          FIELD,   0, @TotalPayment
                   RETURNING, "double", TYPE 5
          FIELD,   0, @WhatIfTotalInterest
                   RETURNING, "double", TYPE 5
          FIELD,   0, @WhatIfTotalPayment
                   RETURNING, "double", TYPE 5
          FIELD,   0, @WhatIfMonths
                   RETURNING, "unsigned int", TYPE 19
          FIELD,   0, @Yearly_Interest
                   RETURNING, "STORED_OBJECT", TYPE 69
          FIELD,   0, @Yearly_Principal
                   RETURNING, "STORED_OBJECT", TYPE 69
          FIELD,   0, @Life_Interest
                   RETURNING, "STORED_OBJECT", TYPE 69
          FIELD,   0, @Life_Principal
                   RETURNING, "STORED_OBJECT", TYPE 69
          FIELD,   0, @Month_Interest
                   RETURNING, "STORED_OBJECT", TYPE 69
          FIELD,   0, @Month_Principal
                   RETURNING, "STORED_OBJECT", TYPE 69

* FULLY-QUALIFIED-NAME AmortControl.CalcFired, AmortControl, Version=1.0.1266.13363, Culture=neutral, PublicKeyToken=null

* AmortControl.CalcFired
     NAMESPACE "AmortControl"
     CLASS "CalcFired"
     MODULE "amortcontrol.dll"

         CONSTRUCTOR,  0, @CONSTRUCTOR1
                   "STORED_OBJECT" @object, TYPE 69
                   "STORED_OBJECT" @method, TYPE 69

* Void EndInvoke(System.IAsyncResult)
          METHOD,  0, "@EndInvoke"
                   "STORED_OBJECT" @result, TYPE 69

* System.IAsyncResult BeginInvoke(System.AsyncCallback, System.Object)
          METHOD,  0, "@BeginInvoke"
                   "STORED_OBJECT" @callback, TYPE 69
                   "STORED_OBJECT" @object, TYPE 69
                     RETURNING "STORED_OBJECT", TYPE 69

* Void Invoke()
          METHOD,  0, "@Invoke"

* Public - fields

* FULLY-QUALIFIED-NAME AmortControl.UserControl1, AmortControl, Version=1.0.1266.13363, Culture=neutral, PublicKeyToken=null

* AmortControl.UserControl1
     NAMESPACE "AmortControl"
     CLASS "UserControl1"
     MODULE "amortcontrol.dll"
         VISUAL

          CONSTRUCTOR,  0, @CONSTRUCTOR1

* Void Dispose(Boolean)
          METHOD,  0, "@Dispose"
                   "boolean" @disposing, TYPE 11

* Void add_FireCalc(AmortControl.CalcFired)
          METHOD,  0, "@add_FireCalc"
                   "STORED_OBJECT" @value, TYPE 69

* Void remove_FireCalc(AmortControl.CalcFired)
          METHOD,  0, "@remove_FireCalc"
                   "STORED_OBJECT" @value, TYPE 69

* System.String get_TotalInterest()
          METHOD,  0, "@get_TotalInterest"
                     RETURNING "BSTR", TYPE 8

* System.String get_TotalPayment()
          METHOD,  0, "@get_TotalPayment"
                     RETURNING "BSTR", TYPE 8

* System.String get_MonthPayment()
          METHOD,  0, "@get_MonthPayment"
                     RETURNING "BSTR", TYPE 8

* System.String get_WhatIfTotalInterest()
          METHOD,  0, "@get_WhatIfTotalInterest"
                     RETURNING "BSTR", TYPE 8

* System.String get_WhatIfTotalPayment()
          METHOD,  0, "@get_WhatIfTotalPayment"
                     RETURNING "BSTR", TYPE 8

* System.String get_WhatIfMonths()
          METHOD,  0, "@get_WhatIfMonths"
                     RETURNING "BSTR", TYPE 8

* Void InitializeComponent()
          METHOD,  0, "@InitializeComponent"

* Void calcBtn_Click(System.Object, System.EventArgs)
          METHOD,  0, "@calcBtn_Click"
                   "STORED_OBJECT" @sender, TYPE 69
                   "STORED_OBJECT" @e, TYPE 69

* Public - fields
          FIELD,   0, @columnHeader1
                   RETURNING, "STORED_OBJECT", TYPE 69

* TotalInterest
          PROPERTY_GET, 0, @TotalInterest
                   RETURNING, "BSTR", TYPE 8

* TotalPayment
          PROPERTY_GET, 0, @TotalPayment
                   RETURNING, "BSTR", TYPE 8

* MonthPayment
          PROPERTY_GET, 0, @MonthPayment
                   RETURNING, "BSTR", TYPE 8

* WhatIfTotalInterest
          PROPERTY_GET, 0, @WhatIfTotalInterest
                   RETURNING, "BSTR", TYPE 8

* WhatIfTotalPayment
          PROPERTY_GET, 0, @WhatIfTotalPayment
                   RETURNING, "BSTR", TYPE 8

* WhatIfMonths
          PROPERTY_GET, 0, @WhatIfMonths
                   RETURNING, "BSTR", TYPE 8

* FireCalc  ()
         EVENT, 520214344, @UserControl1_FireCalc
Parent topic: NETDEFGEN Utility Reference


Sample Controls

Sample .NET controls have been included on the ACUCOBOL-GT samples directory (%PUBLIC%\Documents\Micro Focus\extend x.x.x\sample\dotnet). Refer to ReadMeSetup.txt in each sample directory for an overview of each control and setup instructions. The samples include:

  • AmortControl, Composite control
  • netdb, .NET database sample

The amortization control sample consists of an ACUCOBOL-GT program displaying edit boxes, an exit button, and a .NET amortization user control. AmortControl.dll fires an event when the control's Calculate button is clicked. The COBOL file AmortControl.acu receives the event, retrieves updated properties, and displays the results in edit controls. To view the contents of the AmortControl COPY file, the COBOL program, and the GUI screen, refer to the /AcuGT/sample directory.

Parent topic: NETDEFGEN Utility Reference


Interacting with .NET Web Services

ACUCOBOL-GT supports Web services via .NET client-side control interfaces. This means that an ACUCOBOL-GT program can consume or invoke a Web service via a .NET control. Also, a server-side Web service can consume or invoke an ACUCOBOL-GT server-side program.

  • Invoking .NET Web Services from COBOL
  • Invoking COBOL Services from .NET
Parent topic: Working with .NET Assemblies


Invoking .NET Web Services from COBOL

As a rule, .NET Web services include a C# proxy. This C# proxy contains program code that resolves function calls and connections to the server -side .NET Web service. The proxy is compiled into the client application which uses the proxy to connect to and retrieve information from the server-side .NET Web service.

  1. A .NET programmer writes a .NET Web service using ASP.NET, C#, or VB.NET.
  2. This programmer generates a C# proxy from the Web service using the Microsoft WSDL utility that comes with .NET.

    The client needs this proxy so that it can connect to the service over the Internet and call methods that reside in the service.

  3. The programmer writes a client-side .NET control in C# or VB.NET that accesses the Web service (via the proxy).
  4. A COBOL programmer runs the NETDEFGEN utility on the control as he would any .NET control. refer to the section Using .NET assemblies in COBOL for instructions.
  5. The COBOL programmer copies the resulting COPY file into the ACUCOBOL-GT program, then uses the CREATE, DISPLAY, INQUIRE, and MODIFY statements to access the .NET control methods and events.
Parent topic: Interacting with .NET Web Services
Related information
Using .NET assemblies in COBOL


Invoking COBOL Services from .NET

There are two ways to invoke COBOL-based services from .NET:

  1. Via the ACUCOBOL-GT COM Server as described in Calling COBOL from .NET.
  2. Via the .NET API, "wrunnet.dll" described in Using the .NET Interface Assembly, "wrunnet.dll".
Parent topic: Interacting with .NET Web Services
Related information
Calling COBOL from .NET
Using the .NET Interface Assembly, “wrunnet.dll”


Working with C and C++ Programs

  • COBOL and C/C++
  • Matching C Data Items
  • Calling C Programs From COBOL
  • Calling COBOL from C
  • Using the C API: Two Approaches
  • Other Interface Paths for COBOL and C
  • Tracking, Monitoring and Debugging Memory
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


COBOL and C/C++

In many applications, enterprise systems, and operating systems, C and C++ provide core capabilities and support functions. To help you build integrated applications that make the best use of COBOL programs, ACUCOBOL-GT® provides several robust methods for interoperating with C programs. These technologies work equally well with C++ programs that conform to C calling conventions.

ACUCOBOL-GT provides methods for both calling C from COBOL and calling COBOL from C. Methods for calling C from COBOL include:

  • Direct calls to C programs located in Windows dynamic link libraries (DLLs) and UNIX/Linux shared object libraries.
  • Direct calls to C programs linked into the ACUCOBOL-GT runtime.
  • Interface calls, through a special interface, to C programs linked into the ACUCOBOL-GT runtime.

To support the ability of C programs to call COBOL, ACUCOBOL-GT includes an extensive C Application Programming Interface (API).

All of these facilities are described in detail in this chapter.

Note:

ACUCOBOL-GT does not support the Object COBOL elements of the 2002 ISO/IEC COBOL Standard. Neither does ACUCOBOL-GT provide direct object-level interoperability with OO elements and structures.

Parent topic: Working with C and C++ Programs


Matching C Data Items

To successfully interoperate with C programs, you need to understand and properly implement data type matching and data exchange between COBOL and C programs.

Note: In addition to the information given here, see USAGE Clause for extensive reference-level information. If you are working in a Windows environment, see also Data Mapping.
  • Matching Simple Data Items
  • Matching Complex Data Items
Parent topic: Working with C and C++ Programs


Matching Simple Data Items

To match simple C external variables or passed data items, you must choose the appropriate USAGE type. For example, to share an integer variable with a C routine, declare it in COBOL as:

77  MY-SHARED-INT  SIGNED-INT, EXTERNAL.

In C, this item is then declared as:

int my_shared_int;
Note:

You must also name my_shared_int in the table of external identifiers, as described in the "direct.c" file.

Here is an example of passing an "int" value in a portable fashion to a C routine:

77  MY-INT   SIGNED-INT.
MOVE 123 TO MY-INT.
CALL "C-ROUTINE" USING, BY VALUE, MY-INT.

The ANSI C routine could then read:

void c_routine( int param1 )
{
 printf( "This should be '123': %d\n", param1 );
}
Parent topic: Matching C Data Items


Matching Complex Data Items

Matching complex data items such as C structure (struct) items or arrays is more involved. The challenge arises in trying to match the FILLER that may follow the COBOL data items. For example, consider the following group item:

01  GROUP-1.
    03  DATA-1  PIC X(5).
    03  INT-1   SIGNED-INT.

Assuming that each item is allocated 4 bytes, this would seem to match the following C structure:

struct {
    char  data_1[5];
    int   int_1;
} group_1;

However, it most likely won't match up with the default structure packing due to alignment. If you must match complex C data types, you can take one of three approaches:

  1. You can use fixed-size COMP-5 COBOL data types that match your C structures. You will then have to change your COBOL code and recompile when you move to a different target environment.
  2. You can use the variable-size COBOL data types described in this section and adjust your C structures accordingly. This approach requires a change to your C code when you move to a new environment.
  3. You can use the variable-size COBOL data types described in this section and select different target architectures with the "-Dw" compile option. In this scenario, you do not have to change code to go to a new environment; you just have to recompile with a different "-Dw" setting. For example, you could set up two different directories on the development machine, one for "-Dw32" objects, and one for "-Dw64" objects. This approach would provide you with COBOL objects for all currently supported machines.
Note:

Most C compilers align structure elements according to their own needs. The automatic synchronization that occurs with variable-size data items matches the most natural alignment boundaries. But the automatically synchronized data items may not match with the alignment rules used by a particular C compiler. As a result, you may find yourself forced to make some code adjustments for a particular machine.

Parent topic: Matching C Data Items


Calling C Programs From COBOL

ACUCOBOL-GT supports three methods of calling C programs from COBOL:

  • Loading C routines packaged in a DLL or UNIX shared object library and then calling the programs directly
  • Via ACUCOBOL-GT's direct method (without interfacing routines), when the routine is linked into the runtime
  • Via ACUCOBOL-GT's interface method (using "sub" or "sub85"), when the routine is linked into the runtime

Wherever possible, we recommend that you package routines in a DLL or shared object library. This allows you to call the routines without having to relink the runtime. Note, however, that the method for packaging routines is platform specific.

Alternatively, the direct method and the interface method require that you link the external routines into the runtime. However, on Windows platforms, the interface method can be used with a DLL, in which case the runtime does not have to be relinked. See The "Sub" Interface.

All of these methods may be used in combination in the same program.

Note:

On UNIX and Linux systems, the runtime also attempts to resolve calls that are in its global symbol space. It does this by calling dlopen(NULL, ...) and adding the return value to the list of shared libraries to search. While not all functions are available, many are, including all of the standard C library functions (those in "libc.a" or "libc.so").

Note: To successfully interface to C routines, you need to analyze and implement appropriate data type matching and data exchange between COBOL and C programs.
  • Calling C Programs in DLLs or Shared Object Libraries
  • Calling C Programs via the Direct Method
  • Calling C Programs via the Interface Method
  • Cancelling a CALLed C Program
  • Managing the Terminal
  • Relinking the Run-time System
Parent topic: Working with C and C++ Programs
Related information
Relinking the Runtime System
The Sub Interface
Matching C Data Items


Calling C Programs in DLLs or Shared Object Libraries

The simplest way to call a C program from ACUCOBOL-GT is to:

  1. Package the routine into a Windows DLL or UNIX/Linux shared object library.
  2. Load the DLL or shared object at startup by using one of the following options:
    • Use the "-y" runtime option
    • Use the SHARED_LIBRARY_LIST runtime configuration variable
    • Load the DLL or shared object during program execution with a CALL statement or via the SHARED_LIBRARY_LIST variable and a SET ENVIRONMENT statement.
  3. Call the routine with a CALL statement.

For a detailed description of using this method with DLLs, see Calling DLLs from COBOL.

This section contains detailed information on calling routines in UNIX/Linux shared objects. An important advantage of this method is that it is not necessary to relink the runtime.

In this section, we describe the following methods of loading and calling programs in shared object libraries:

  • Loading libraries with the "-y" runtime option
  • Loading libraries with the SHARED_LIBRARY_LIST configuration variable
  • Loading libraries with the CALL statement
  • Calling routines with the CALL statement

Once loaded, any exported function can be called with a COBOL CALL statement.

  • Loading Shared Libraries with the "-y" Runtime Option
  • Loading Shared Libraries with the SHARED_LIBRARY_LIST Configuration Variable
  • Loading Shared Libraries with the CALL Statement
  • Calling Routines in Shared Libraries with the CALL Statement
Parent topic: Calling C Programs From COBOL
Related information
Calling DLLs from COBOL


Loading Shared Libraries with the "-y" Runtime Option

You can use the "-y" runtime command-line option to specify the name of a shared object library to load when the runtime starts. When the program calls a routine in the library, the runtime applies its standard logic to resolve the CALL. For more information, see Calling Subprograms.

For example, to call any function exported by "mylibc.so", start the runtime with the following command:

runcbl -y mylibc.so mycobol

You must specify a new "-y" for each shared library. The default filename extension for shared libraries is ".so". You can change the default by specifying another extension in the SHARED_LIBRARY_EXTENSION configuration variable. See SHARED_LIBRARY_EXTENSION for more information.

You can use the SHARED_LIBRARY_PREFIX configuration variable to specify a list of directories to search when the runtime attempts to load a shared library. The values are applied if the shared library is specified without path information and the runtime fails to find the object in the default directories. For more information, see the SHARED_LIBRARY_PREFIX.

Parent topic: Calling C Programs in DLLs or Shared Object Libraries


Loading Shared Libraries with the SHARED_LIBRARY_LIST Configuration Variable

You can use the SHARED_LIBRARY_LIST configuration variable to specify a list of shared libraries to load at program startup, or as the result of a SET ENVIRONMENT statement during program execution. You can set SHARED_LIBRARY_LIST in three ways:

  • In the environment
  • In the runtime configuration file
  • Programmatically with the SET ENVIRONMENT statement

Library names in SHARED_LIBRARY_LIST are delimited by spaces or colons. You can set SHARED_LIBRARY_LIST with the SET ENVIRONMENT statement any number of times during program execution. Each time, the runtime loads the libraries listed. Previously loaded libraries remain loaded.

On some systems, if the shared module is a member of an archive, you must specify the name of the member in parentheses after the name of the archive. For example, on AIX:

SHARED_LIBRARY_LIST=/usr/opt/program/lib/archive.a(lib.o)

SHARED_LIBRARY_LIST is similar to the runtime "-y" command-line option except that:

  • You do not need to set SHARED_LIBRARY_EXTENSION when you use SHARED_LIBRARY_LIST.
  • With SHARED_LIBRARY_LIST, you can mix ".a" and ".so" libraries.

You can use the SHARED_LIBRARY_PREFIX configuration variable to specify a list of directories to search when the runtime attempts to load a shared library. The values are applied if the shared library is specified without path information and the runtime fails to find the object in the default directories. For more information, see SHARED_LIBRARY_PREFIX.

Parent topic: Calling C Programs in DLLs or Shared Object Libraries


Loading Shared Libraries with the CALL Statement

You can load a shared object library programatically with the CALL statement. Once the shared library is loaded, you can call any function exported by the library with a CALL statement. For syntax and rules, see CALL Statement. For example, the following statement loads "sharedlibrary.so":

CALL "sharedlibrary.so"

Filename Extensions

The default filename extension of shared libraries is ".so". You can specify a different extension in the CALL statement, or the default extension can be redefined with the SHARED_LIBRARY_EXTENSION runtime configuration variable. See SHARED_LIBRARY_EXTENSION.

You can also NOT specify a file extenstion in which case the runtime will search for the file. The runtime will prepend various prefixes and append various suffixes to the name given, searching sequentially through the list of names until a name is found that can be loaded.

On UNIX, the runtime will first try the name as given and then prepend in order "lib" or "cob". It will also append in order ".so", ".sl", ".a".

On 64-bit UNIX machines, the runtime will also append the following suffixes in order: "64", "64.so", "64.sl", "64.a".

For example, when trying to load "aclnt" on UNIX, the runtime attempts to load the following library names, stopping when one is found:

aclnt

aclnt.so

aclnt.sl

aclnt.a

aclnt64 (64-bit only)

aclnt64.so (64-bit only)

aclnt64.sl (64-bit only)

aclnt64.a (64-bit only)

libaclnt

libaclnt.so

libaclnt.sl

libaclnt.a

libaclnt64 (64-bit only)

libaclnt64.so (64-bit only)

libaclnt64.sl (64-bit only)

libaclnt64.a (64-bit only)

cobaclnt

cobaclnt.so

cobaclnt.sl

cobaclnt.a

cobaclnt64 (64-bit only)

cobaclnt64.so (64-bit only)

cobaclnt64.sl (64-bit only)

cobaclnt64.a (64-bit only)

File Locations

If no relative or absolute path is specified, the runtime looks for the library in the current working directory, the locations specified in the operating system's environment variable for shared libraries; for example, LIBPATH, LD_LIBRARY_PATH, or SHLIB_PATH), and then in the locations specified in the SHARED_LIBRARY_PREFIX configuration variable. See Configuration Variables for more information.

Like other programs that are loaded with a CALL statement, you can unload a CALLed shared library with a CANCEL statement. When you CANCEL a shared library, you may no longer call its exported functions. Unless the logical cancels feature is enabled, all memory used by the program is released. For information about runtime memory management and the logical cancels feature, see Memory Management.

Note: While most UNIX systems use a binary format that supports calling subroutines in shared libraries exactly as described in this section, SCO UNIX (and possibly some other UNIX systems) uses different binary formats, namely COFF and ELF. On those systems, in order to support calling shared libraries, the objects and executables must be in the ELF format. See the UNIX "man" page for your C compiler on how to create ELF format objects (on some systems, for example, you specify the "-b elf" C compiler option).
Parent topic: Calling C Programs in DLLs or Shared Object Libraries


Calling Routines in Shared Libraries with the CALL Statement

After a shared library has been loaded, any of its exported routines can be called. For example:

CALL "sharedfunction"
Note:

By default, the runtime first attempts to find a COBOL program with a matching name. To do this, the runtime can apply several extensions and look in several locations. Only if all of those attempts fail does the runtime attempt to locate the function in the current process or in one of the loaded shared libraries. However, you can use the DYNAMIC_FUNCTION_CALLS configuration variable to specify a list of functions or function name prefixes that the runtime will treat as dynamic functions, which it searches before searching the disk for COBOL programs. See DYNAMIC_FUNCTION_CALLS for more information.

Parent topic: Calling C Programs in DLLs or Shared Object Libraries


Calling C Programs via the Direct Method

The direct method allows you to pass arguments to C functions without writing special interfacing routines. Parameters are passed directly to the C function according to the CALL statement that invoked the function, using the standard C calling conventions. This direct method simulates the actions of a native code compiler such as Micro Focus or VAX/COBOL.

Note:

The runtime has an internal limit of 30 parameters that it can pass to a C routine called through the direct method; it aborts if more than 30 parameters are passed and suggests ways to work around the abort. You can change this limit by modifying the file "lib/callc.c" and relinking the runtime.

Use the BY VALUE phrase of the CALL statement to pass numeric parameters in a way that is compatible with C calling conventions. Use the BY REFERENCE phrase to pass address parameters.

With the direct method, using BY VALUE causes the actual value to be passed to the routine (as expected). Using NULL causes binary zeros to be passed to the routine (matching the NULL concept in C). With the direct method, passing a zero BY VALUE is much the same as specifying NULL (contrast this with the corresponding note under the interface method described in the topic Calling C Programs via the Interface Method).

When a C function is called by the direct method, its return value is placed in the special register RETURN-CODE.

You should note that the direct method makes it easy to generate memory access violations. You may omit a BY REFERENCE or BY VALUE phrase or forget to terminate strings properly with a NULL value (as required by C).

To use the direct method, add the name of the C function to be called to DIRECTTABLE in the file "direct.c". The table has three columns:

  • In the first column, place the name you want to use in the COBOL CALL statement. Use all uppercase characters, and place the name in quotation marks.
  • In the second column, place the address of the routine to be called. (You can accomplish this by specifying "FUNC" followed by the exact name of the routine as declared in C. "FUNC" is a macro that generates the appropriate cast of the routine name.)
  • In the third column, place the function's return type, which may be one of these seven types:
    C_int
C_long
C_unsigned
C_pointer
C_short
C_void
C_char

You may need to prototype the function if it is not prototyped in an included header file. For example, to call the C function "open" directly, you would include the following code in the "direct.c" file:

extern int open();
struct  DIRECTTABLE LIBDIRECT[] = {
    { "OPEN",  FUNC open,  C_int },
    {NULL,     NULL,       0 }
    };

After you make the change to "direct.c", be sure to relink the runtime system.

To use the "open" function in COBOL, you might do something like this:

77   FILE-NAME      PIC X(20)
77   FILE-HANDLE    SIGNED-INT

MOVE "myfile" TO FILE-NAME.
INSPECT FILE-NAME REPLACING TRAILING SPACES
     BY LOW-VALUES.
CALL "OPEN" USING BY REFERENCE FILE-NAME BY VALUE 0.
MOVE RETURN-CODE TO FILE-HANDLE.
Note:

Strings passed to C routines should have LOW-VALUE terminators. Variables that are not passed by address should have the BY VALUE qualifier in COBOL and should be COMP-5 or one of the C data types.

In the example above, FILE-NAME cannot be more than 19 characters, because the 20th, or last, character must be the string terminator.

Up to 20 parameters may be passed via the direct method. If you need to pass more than 20, call our Technical Support and request the routine "callc.c". The comments within the code explain how to use the "callc.c" routine.

External C variables and system functions can also be linked with COBOL EXTERNAL data items. One function in particular called "ERRNO" can be used to obtain error information from those system functions. The runtime exports the errno variable so that COBOL programs can reference it easily and without requiring a relink.

ERRNO should be shown as defined as:

77  ERRNO EXTERNAL SIGNED-INT.

Consult your preferred C manual for information on using ERRNO.

Parent topic: Calling C Programs From COBOL


Calling C Programs via the Interface Method

The interface method uses special routines that are passed the name of the called function. Use this method when you want to simulate the actions of a non-native system. ACUCOBOL-GT supports two types of interfaces that simulate interfaces available in two versions of RM/COBOL:

  • the "sub85" interface, which is source-compatible with C routines written for RM/COBOL-85.
  • the "sub" interface, which is compatible with RM/COBOL version 2.

You may use either or both of these interfaces. With the interface method, parameters are passed to the interface routines in a standardized format. The parameters must typically be converted to a format that is usable in C.

Every ACUCOBOL-GT compiler comes with a sample C subroutine interface. The "sub.c" file implements the "sub" interface. The "sub85.c" file implements the "sub85" interface. The "sub.h" file contains some useful definitions, particularly if you are using the "sub85" interface. These files contain extensive comments describing how they are used. They also contain the source to the SYSTEM library routine. You can use these files as the starting point for your code. The two interfaces are described in the following sections.

Note: At run time, the "sub" interface performs a linear search for a called routine. This process can be inefficient when a very large number of "sub" routines are present. If your program calls a large number of C routines, we recommend that you use the "sub85" or "direct" interface.

Also, in the "sub85" and "sub" interface methods, parameters are not passed directly to the C routine. Instead, an array of pointers is passed, and each pointer points to the corresponding parameter (or in the case of "sub85," a description of the parameter). In this case, the notion of BY VALUE has no reasonable definition, because there is no place to put the value. Because of this, the runtime ignores the BY VALUE phrase and passes an address to a copy of the value (essentially treating BY VALUE as BY CONTENT). It must do this because there is no C variable available in which to pass the value. However, specifying NULL does have a reasonable definition: The pointer corresponding to that parameter is set to binary zeros. Therefore, with the interface method, NULL and BY VALUE ZERO have different meanings (contrast this with the corresponding note under the direct method described in the topic Calling C Programs via the Direct Method).

  • The "Sub" Interface
  • The "Sub85" Interface
Parent topic: Calling C Programs From COBOL


The "Sub" Interface

Every time a CALL statement executes, it calls a C routine called "sub". This routine is passed the name of the called program and its USING parameters. You may modify this routine to recognize the call name that you want to assign to a C subprogram and perform the appropriate code. This routine is contained in the "sub.c" file.

The "sub" routine is passed two arguments: argc and argv. The argv parameter is an array of character pointers. The argc parameter is an integer count of the number of elements in the argv array. The first element in argv points to the call name exactly as it appears in the COBOL CALL statement. This name is terminated with a NULL character. The remaining elements of argv point to each of the USING arguments.

The "sub" function should check to see if the called name is one that should be handled in C. It can do this by comparing "argv[0]" with the desired routine name using the "strcmp" C library routine. If the routine is one that is not handled by a C subroutine, then "sub" should return a negative value. This indicates to runcbl that the CALL statement has not been fulfilled and that it should try to find a COBOL subprogram by that name. If the routine is handled by the "sub" function, then a zero should be returned. In this case, runcbl assumes that the CALL statement has been completed and it continues with the next statement. Finally, if "sub" returns a positive value, then runcbl executes a STOP RUN, returning the value to the operating system as runcbl's exit value. See "sub.c" for an example of this interface.

When processing a USING parameter, note that the C subroutine must know what internal format the parameter uses. Also note, that in COBOL, literal values are not terminated by a NULL character. Thus, you should not treat a passed value as a C string unless the calling program ensures that the passed value is NULL terminated. This can be accomplished in the following fashion:

STRING   "literal", LOW-VALUES, DELIMITED BY SIZE
         INTO ITEM-1
CALL NAME-1 USING ITEM-1.
Note:

The "sub" interface provides compatibility with the RM/COBOL-85 interface. At run time "sub" performs a linear search for a called routine. This can be inefficient if your program calls a large number of C routines. We recommend that you use the "sub85" or "direct" interface.

Placing the "Sub" Routine in a DLL

In addition to linking the "sub" function directly into the runtime, Windows users may place the "sub" routine into one or more DLL files.

You must specify which routine to use as the "sub" interface routine by setting the DLL_SUB_INTERFACE configuration variable. Then you call the DLL from your COBOL program. The runtime loads the DLL, then checks DLL_SUB_INTERFACE for the name of the routine to use as the "sub" interface routine. For example, the following C program (subdll.c) is the source for the DLL that contains the "sub" interface, called AcuSub in this example:

#include <stdio.h>
#include <windows.h>
#include "sub.h"

#define   DllExport             __declspec(dllexport)
#define   CCallingConvention    __cdecl

DllExport int CcallingConvention
AcuSub( int argc, char *argv[] )
{

    if ( strcmp( argv[0], "MSGBOX" ) == 0 ) {
             MessageBox( NULL, argv[1], NULL, MB_OK );
             return Okay;
    }

    return NotFound;

}   /* AcuSub */

/* end of subdll.c */

The following COBOL program ("callsub.cbl") shows how the DLL is loaded and called:

program-id.  test.
working-storage section.

77  message-text          pic x(80).

procedure division.
main-logic.
    display standard window.

* Load DLL and establish "sub" interface

    set environment "dll-sub-interface" to "AcuSub".
    call "subdll".

* Call "MSGBOX", one of the routines handled by "AcuSub"

    move "This is a test message" to message-text.
    inspect message-text replacing trailing spaces by
        low-values.
    call "msgbox" using message-text.

    accept omitted.
    stop run.

If DLL_SUB_INTERFACE is blank when the DLL is loaded, no "sub" routine is used in that DLL.

When a CALL statement executes, the "sub" interface routine in each loaded DLL is called, in the order that they were loaded, until one of them returns that it has executed the subroutine. If none of the DLLs returns success, the normal, or linked-in, "sub" routine is called. If that does not return success, then the standard calling sequence resumes. As soon as any routine returns success, the CALL is considered satisfied and no further processing of the CALL is done.

If you CANCEL a DLL with an active "sub" interface, that interface is removed from the list of available interfaces and the DLL is unloaded.

Parent topic: Calling C Programs via the Interface Method


The "Sub85" Interface

The "sub85" interface can be more useful than the "sub" interface because more information about each USING parameter is passed to the C subroutines. However, using the "sub85" interface also involves more programming.

The "sub85.c" file contains a table called LIBTABLE. This table consists of a variable number of entries. Each entry contains a routine name and the name of the corresponding C subroutine. The last entry in this table must be NULL to mark the end of the table. When a CALL statement executes, this table is searched for a matching routine name. If a match is found, the corresponding routine is executed.

When the routine is called, it is passed four parameters: name, num_args, args, and initial (in that order). The name argument is a character pointer to the name that the CALL statement used to access the subroutine. The num_args parameter is an integer that contains the number of USING arguments specified by the CALL statement.

The args parameter is defined as an array of type Argument. This type (a structure) is declared in "sub.h". For each USING parameter, the corresponding array element contains the following series of fields that describes that parameter:

a_address — a character pointer that points to the first byte of the USING parameter

a_length — a long integer that contains the number of bytes contained in the USING parameter

a_type — a short integer that contains one of the following values depending on the passed data type:

0 | Numeric edited
1 | Unsigned numeric (DISPLAY)
2 | Signed numeric (DISPLAY, trailing separate)
3 | Signed numeric (DISPLAY, trailing combined)
4 | Signed numeric (DISPLAY, leading separate)
5 | Signed numeric (DISPLAY, leading combined)
6 | Signed COMP-2
7 | Unsigned COMP-2
8 | Unsigned COMP-3
9 | Signed COMP-3
10 | COMP-6
11 | Signed binary (COMP-1, COMP-4, COMP-X)
12 | Unsigned binary (COMP-1, COMP-4, COMP-X)
13 | Signed native (COMP-5, COMP-N, SIGNEDSHORT, SIGNED-INT, SIGNED-LONG)
14 | Unsigned native (COMP-5, COMP-N, UNSIGNEDSHORT, UNSIGNED-INT, UNSIGNED-LONG)
15 | Floating point (FLOAT, DOUBLE)
16 | Alphanumeric
17 | Alphanumeric (justified)
18 | Alphabetic
19 | Alphabetic (justified)
20 | Alphanumeric edited
21 | Not used
22 | Group

Note that setting the u.pass_type member of the Argument structure controls how data is passed back and forth between a program running on the client and a remote COBOL object. Set u.pass_type to "0" to pass data by reference. Use this when the COBOL application is to read and write data to the variable. Use BY REFERENCE for string literals. Set u.pass_type to "1" to pass data by content. Use this when you want to allow read access to the data item, but the COBOL application should not write to the address. Use BY CONTENT for constants. Set u.pass_type to "2" to pass data by value. Use BY VALUE for numbers.

a_digits — a char that contains the total number of digits in a numeric data type. For non-numeric data types, this value is always zero.

a_scale — a char that contains the power of 10 to multiply the number by. This indicates the location of the decimal point. For example, a value of "-1" indicates that there is one digit to the right of the decimal point. Note that since this is defined as a "char", you may not be able to treat this as a signed value on all machines. The macro "Scale" in "sub.h" converts one of these fields to a signed integer in a machine independent manner.

The final argument to the C subroutine, initial, is set to a non-zero value if the routine is being called for the first time. It is also set to a non-zero value for the first call after a CANCEL statement has been executed for the routine. On any other call, initial is set to zero.

The external variable return-code can be set to any value. The COBOL variable RETURN-CODE will have that value when control returns to the COBOL program. By convention, when a C routine finishes it should return zero if everything was okay. Any other positive return value causes a STOP RUN to be executed, and that value is returned to the operating system as the RETURN-CODE for the run. The C routine should never return a negative value.

Parent topic: Calling C Programs via the Interface Method


Cancelling a CALLed C Program

Shared objects loaded with a CALL statement can be unloaded with a CANCEL statement. For information about the CANCEL statement, see CANCEL Statement.

Shared objects loaded with the "-y" runtime option or via the SHARED_LIBRARY_LIST configuration variable cannot be unloaded.

Note:

The CANCEL_ALL_DLLS configuration variable can be used to control whether a CANCEL ALL statement frees shared object libraries and DLLs. See CANCEL_ALL_DLLSfor details.

Parent topic: Calling C Programs From COBOL


Managing the Terminal

If a called C routine accepts input from the user or performs screen I/O, those routines need to manage the terminal. This is because ACUCOBOL-GT programs and C programs expect the terminal to be in different initial states.

When the ACUCOBOL-GT runtime initializes the terminal manager on a character-based system, it puts the terminal into a "half-cooked" state. This allows the runtime to optimize certain screen I/O and provides support for auto-terminated fields and other screen niceties. C programs, on the other hand, expect the terminal to be in its default state. Therefore, C routines called from COBOL that interact with the user or display information to the screen must manage the state of the display device. Specifically, the C routine must set the terminal to its default mode before performing screen I/O, and restore the terminal to the "half-cooked" state before returning to COBOL. This is accomplished with the w_reset_term() and w_set_term() functions. These functions are built into the runtime.

To prepare the terminal for C screen I/O, at the top of your C routine call w_reset_term() to place the terminal in its default state.

To prepare the terminal for COBOL screen I/O, before your C routine returns call w_set_term() to place the terminal back into the "COBOL" state.

Parent topic: Calling C Programs From COBOL


Relinking the Run-time System

You must relink the ACUCOBOL-GT runtime when you:

  • Modify the .c files located in $ACUCOBOL/lib, including config85.c, filetbl.c, and others.
  • Call C routines that are not available in DLLs or shared object libraries. This means that you are using the direct method or interface method to call C routines.

The exact procedure for relinking depends on the host system. On most UNIX and Linux systems, you have the option of linking with either the makerun script or the make utility.

Relinking the runtime requires that you have the appropriate C development system for your host. Required software is specified in the host-specific subsections that follow.

  • Linking on Windows Systems
  • Linking on UNIX and Linux Systems
  • Linking on VMS Systems
Parent topic: Calling C Programs From COBOL
Related information
Calling C Programs via the Direct Method
Calling C Programs via the Interface Method


Linking on Windows Systems

On Windows systems, routines are linked into the ACUCOBOL-GT runtime DLL (wrun32.dll), not the runcbl program (wrun32.exe). Note that both the standard runtime and the Web runtime use the same DLL.

Required Software

Visual Studio 2017

Linking the Standard Runtime

To make a new standard runtime for Windows, load the wrun32.sln solution file into Visual Studio 2017 and build. By default, wrun32.sln is located in the AcuGT\lib subdirectory of your product installation directory.

Linking the Alternate Terminal Manager Runtime

To make a new Alternate Terminal Manager runtime for Windows, load the run32.sln solution file into Visual Studio 2017 and build. By default, run32.sln is located in the AcuGT\lib subdirectory of your product installation directory.

Linking the Console Runtime

To make a new console runtime for Windows, load the crun32.sln solution file into Visual Studio 2017 and build. By default, crun32.sln is located in the AcuGT\lib subdirectory of your product installation directory.

Parent topic: Relinking the Run-time System


Linking on UNIX and Linux Systems

On most UNIX and Linux systems, ACUCOBOL-GT provides two ways to relink the runtime. The first is the traditional make facility for which ACUCOBOL-GT includes a Makefile. The second is with a script named makerun. makerun allows you to specify the names of libraries and objects on the command line. make is immediately familiar to most UNIX and Linux developers. Both facilities are described below.

On UNIX and Linux systems where extend® products are delivered as shared object libraries, relinking the runtime requires relinking the appropriate shared object. In the case of the runtime, this is "libruncbl.so" or "libruncbl.sl". On systems where extend products are delivered as statically linked executables, the runtime executable is named runcbl by default.

Note:

After relinking, be sure to move or copy the new object to the required directory. The default location is $ACUCOBOL/lib for shared object libraries, and $ACUCOBOL/bin for static libraries.

Required Software

An ANSI 89-compliant C compiler supplied by the vendor of your UNIX system, either included as part of your UNIX system or as an add-on option. Check with your operating system vendor to see if the C compiler is capable of building shared libraries. If it is not, you will need a full version of the compiler to relink the ACUCOBOL library.

Using the "Make" Utility

On all supported UNIX and Linux platforms, the ACUCOBOL-GT runtime can be relinked with "make" using the Makefile included with the extend distribution.

For your convenience, two environment variables can be used to specify object files and object libraries to be added to the link line of the Makefile. Set EXTLIBS to a list of libraries, and set EXTOBJS to a list of objects. For example, the following command links the C routines in the object file "myroutines.o" into the ACUCOBOL-GT runtime:

EXTOBJS="myroutines.o" make

Linking with "Make"

To create a new runtime, cd to the lib directory and type:

   "make"

Using the Makerun Script

On most UNIX and Linux systems, ACUCOBOL-GT comes with a makerun script that can be used to relink the runtime. makerun is a UNIX Korn shell script that relinks the runtime executable (runcbl) or shared object ("libruncbl.so" or "libruncbl.sl").

The makerun command format is:

makerun [ldflags] [objects] [libraries]

where ldflags, objects, and libraries are optional arguments passed to the "ld" command as described below.

ldflags | A list of any valid "ld" options
objects | A list of additional objects to be linked into the runtime.
libraries | A list of additional libraries to be linked into the runtime. Instead of specifying absolute paths to library files, you can also use "-L" and "-l" to specify path and library names. For example, "/home/joe/lib/libacme.so" can be specified as "-L /home/joe/lib –lacme".

For example, the following command links C routines contained in the object file "myroutines.o" into the ACUCOBOL-GT runtime:

makerun myroutines.o

You can also execute makerun from your own script. For example, the following script links three object files and three libraries into the ACUCOBOL-GT runtime:

#!/bin/ksh
OBJDIR=/home/appuser/appobj
OBJECTS="$OBJDIR/a.o \
   $OBJDIR/b.o \
   $OBJDIR/c.o"
LIBDIR=/home/appuser/applib
LIBRARIES="$LIBDIR/lib1.a \
   $LIBDIR/lib2.a \
   $LIBDIR/lib3.a"
cd /usr/acu/lib
makerun $OBJECTS $LIBRARIES

The makerun script passes the additional linker options in the EXTLIBS environment variable.

Everything specified on the makerun command line is passed to the C linker from the Makefile.

Linking with Makerun

To use the makerun script:

  1. Copy the files from the lib subdirectory of your ACUCOBOL-GT installation into the directory of your choice and cd into that directory.
  2. Type the makerun command line. For example:
    makerun myroutines.o
Parent topic: Relinking the Run-time System


Linking on VMS Systems

On VMS systems, a command file is included with ACUCOBOL-GT to relink the runtime system. To invoke it, simply type:

   "@ACU_LINK"

Required Software

Digital Equipment Corporation's VAX C or DEC C compiler for VMS

Parent topic: Relinking the Run-time System


Calling COBOL from C

If you are working in an environment that includes programs written in both COBOL and C or C++, refer to information in this section for details on using the ACUCOBOL-GT C API. You will find a reference for all the functions in the C API and instructions for calling COBOL from C.

Note that you can call COBOL from C locally or remotely. You can even have the runtime execute remotely without a COBOL object executing on the client. All you need on the client is a C or C++ program and a runtime. For this to work, you set CODE_PREFIX in the configuration file that you provide with the runtime initialization to point to a remote server hosting your COBOL application. The remote server must also be running AcuConnect. AcuConnect is able to execute a COBOL object remotely and share data with the local runtime. For more information on executing remote COBOL programs with AcuConnect, please refer to the AcuConnect User's Guide.

Unless noted otherwise, references to C also apply to C++ code that conforms to the C calling conventions.

  • Include Files
  • Using the C API
  • Function Reference
Parent topic: Working with C and C++ Programs


Include Files

The declarations, constants, and return values of the C API are defined in two files:

  • lib/sub.h
  • lib/acusetjmp.h (for the acusavenv() and aculongjmp() functions)

The "sub.h" file includes a declaration of the routines for all platforms to ensure that you use the correct calling convention with these routines.

Parent topic: Calling COBOL from C


Using the C API

The most efficient way to call COBOL from C is to use the C application programming interface (API). This interface can be used by C developers to call COBOL functionality (programs, entry points, etc.) from their C program.

To use the C API, you need to do the following:

  1. Install and configure ACUCOBOL-GT runtime. On Windows systems, optionally install AcuBench® if the system is also used for COBOL development.
  2. Include "sub.h" and "acusetjmp.h" in any source files that use API calls.
  3. Install and configure your C compiler.
  • Using the C API in Windows
Parent topic: Calling COBOL from C


Using the C API in Windows

You can use the C API for calling ACUCOBOL-GT programs on Windows, as well as on UNIX/Linux systems. Call the ACUCOBOL-GT runtime DLL from other languages in one of two ways.

  1. Use the functions acu_initv(), acu_cobol(), acu_shutdown(), and others fully described in the topic, Function Reference.

    These functions offer more control and are designed to be called from C. They are portable between Windows and UNIX; the same C source code calling ACUCOBOL-GT on Windows compiles and runs on UNIX.

  2. Use the corresponding functions, AcuInitialize(), AcuCall(), AcuShutdown() and so on, that are described in the topic Calling the Runtime DLL.

    These functions are designed for use with programming languages like VisualBasic that use Variant type arguments. For example:

    extern void  __stdcall AcuRunMain(char *command_line);

    In Visual Basic, for example, the declaration is:

    Declare Function AcuRunMain Lib "wrun32.dll" _
   (ByVal cmdLine As String)

    This has the same functionality and use as acu_runmain(). It is optional to call AcuInitialize before AcuRunMain. For example:

    if ( AcuInitialize(lpCmdLine) >= 0 )
   AcuRunMain(lpCmdLine);
Parent topic: Using the C API
Related concepts
Calling the Runtime DLL
Related information
Function Reference


Function Reference

Functions in the C API include the following:

Function | Description
acu_abend() | Performs the ACUCOBOL-GT signal handling logic
acu_cancel() | Simulates the COBOL CANCEL verb from C
acu_cancel_all() | Simulates the COBOL CANCEL ALL verb from C
acu_cobol() | Allows you to call COBOL programs and control how they are executed
acu_initv() | Initializes the runtime with command-line options
aculongjmp() | Cuts the C and COBOL call stacks to the point recorded in the buffer
acu_register_sub() | Registers a COBOL subroutine that calls a C routine, so you can locate the routines in the calling executable file
acu_runmain() | Starts up a COBOL program that will be treated like the main program of the run unit
acusavenv() | Records information about the state of the C and COBOL call stack
acu_shutdown() | Halts the ACUCOBOL-GT runtime
acu_unload() | Removes a cached program from memory
acu_unload_all() | Removes all cached programs from memory
  • acu_abend()
  • acu_cancel()
  • acu_cancel_all()
  • acu_cobol()
  • acu_initv()
  • aculongjmp()
  • acu_register_sub()
  • acu_runmain()
  • acusavenv()
  • acu_shutdown()
  • acu_unload()
  • acu_unload_all()
Parent topic: Calling COBOL from C


acu_abend()

The acu_abend() function allows you to perform the ACUCOBOL-GT signal handling logic in selected programs when the runtime is initialized with the "--no-signal-handlers" option. If you run with "--no-signal-handlers", error conditions that raise signals are not detected automatically by the runtime. acu_abend() causes the runtime to output error messages and resets the state of the runtime. This function is designed for use in transaction processing environments that call the ACUCOBOL-GT runtime from a C main program.

Refer to the ACUCOBOL-GT User's Guide for more information on "--no-signal-handlers".

Usage

C programs that specify the "--no-signal-handlers" option in the call to acu_initv() may call the acu_abend() function from their own signal-handling code as follows:

void
 acu_abend( int signal_number )

where signal_number is the signal number or "-1" if no signal information is available.

Although you can call acu_abend() at any time, we recommend that you call it only if the application was executing COBOL code when the signal occurred; otherwise, the error messages reported by the runtime may be misleading. For example, you do not need to call acu_abend() if:

  1. Your application calls acu_cobol() to execute a COBOL program.
  2. The COBOL program exists.
  3. After acu_cobol() returns, your application executes other non-COBOL processing.
Note:

acu_abend() does not shut down the runtime. It reports the current COBOL program and execution address. It also reports the COBOL source file and line number if you have compiled with "-Gl" or "-Ga". It then resets the runtime to its initial state. Therefore, even if you have called acu_abend(), you still need to call acu_shutdown() to actually shut down the runtime.

Parent topic: Function Reference


acu_cancel()

The acu_cancel() function marks a program as "cached" and resets Working Storage to its initial state for the next call. This function is equivalent to the CANCEL verb.

Usage

void ASTDCALL acu_cancel(char *name);

If the user has specified that the program is not to be cached, then acu_cancel() also unloads the program from memory so that a new copy is loaded from disk the next time the program is called.

For more information on using this function, refer to the topic Unloading Programs from Memory.

Parent topic: Function Reference


acu_cancel_all()

The acu_cancel_all() function performs an acu_cancel() on all "Loaded but inactive" programs. This function is equivalent to the CANCEL ALL verb.

Usage

void ASTDCALL acu_cancel_all(void);

Application servers such as CICS should call acu_cancel_all() after every acu_cobol() call returns. Subsequent calls to the same program and its called subprograms will then have Working-Storage items in their initial state.

For more information on using this function, refer to the topic Unloading Programs from Memory.

Parent topic: Function Reference


acu_cobol()

The acu_cobol() function allows you to call COBOL programs and control how they are executed. This function is required in order to build and invoke the ACUCOBOL-GT runtime with a transaction processing environment like CICS.

Note: This function deprecates the cobol() and cobol_no_stop() functions.

To call COBOL subroutines directly from C, you can use the acu_cobol() routine anytime after acu_initv() has been called and before acu_shutdown() has been called.

For more information, see Calling the Runtime From a C Main Program.

Usage

The acu_cobol() function has the following prototype:

int ASTDCALL acu_cobol(ACUCOBOLINFO *data);

The struct a_cobol_info structure is defined in lib/sub.h:

struct  a_cobol_info
{
size_t       a_cobol_info_size;
char         *pgm_name;
int          num_params;
Argument     *params;
int          exit_code;
const char   *exit_msg;
int          signal_number;
int          call_error;
long         cobol_return_code;
unsigned     no_stop:1;
unsigned     cache:1;
ADM_t        debug_method;
char         *debug_method_string;
void         *internal; /* internal should be NULL */
};
typedef struct a_cobol_info ACUCOBOLINFO;

The ADM_t type is described in lib/sub.h as an enumeration.

typedef enum tag_ACUCOBOL_DEBUG_METHODS
 {
ADM_NONE,
ADM_XTERM,
ADM_TERMINAL,
ADM_THINCLIENT,
} ACUCOBOL_DEBUG_METHOD, ADM_t;

The enumeration values describe the debugging method to be used for the program. See the Parameters section below for more information.

Parameters

The a_cobol_info structure has the following parameters. Input variables are set before the call to acu_cobol() and output variables set after acu_cobol() returns:

a_cobol_info_size | A size_t initialized to sizeof(a_cobol_info) to allow for future expansion (input)
pgm_name | A char* that contains the name of the COBOL program to call (input)
num_params | An int that contains the number of elements in the params array (input)
params | An Argument* that contains an array of arguments sent to the COBOL program (input)
exit_code | An int that contains the exit code. refer to the exit_code values in the Return Values section below (output)
exit_msg | A const char* that contains the exit message. Its contents should not be modified. This pointer may be NULL. (output)
signal_number | An int value of a signal that caused the COBOL_SIGNAL or COBOL_FATAL_ERROR. If the value is non-zero, the error was caused by this signal. (output)
call_error | An int value that contains the call error. refer to the call_error values listed in the Return Values section below (output)
cobol_return_code | A long value returned in "exit program.nnn" by a COBOL program called from acu_cobol(). The COBOL program can set this value by either setting the return-code or exiting the program. (output)
no_stop | An unsigned value that, when set to "1", causes STOP RUN to be ignored (input)
cache An unsigned value that determines whether the runtime should maintain the program in a memory cache after it has been canceled. This parameter is useful for application servers like CICS that allow each program to be configured as resident or nonresident. (input)

If cache is FALSE ("0"), acu_cancel() removes the program from memory and sets the Working-Storage to its initial state on subsequent calls.

If cache is TRUE ("1"), acu_cancel() marks the program as "cached" and resets Working-Storage for the next call; the program remains in memory according to the caching rules. For information on managing logical and physical cancels that may affect the behavior of cache, see LOGICAL_CANCELS.

debug_method An ADM_t type that defines the debugger method to use for the program when acu_cobol() is called. The debug_method is deinitialized when the COBOL program returns. (input)

To enable background debugging, specify one of the following types:

  • ADM_NONE — For no debugging
  • ADM_XTERM — Debug using a new xterm
  • ADM_TERMINAL — Debug using an existing terminal through runcbl
  • ADM_THINCLIENT — Debug using a waiting thin client
Based on the debug_method selected, you may need to also specify debug_method_string:
debug_method_string A char* that sets the display setting for the debug_method (input)
  • For ADM_XTERM, set to the Xservername:displaynumber of the xterm or set to NULL to allow the xterm to use the default display given by the DISPLAY environment variable.
  • For ADM_TERMINAL, set the string to the tty device on which you will execute runcbl.
  • For ADM_THINCLIENT, set to client:port where the client is the host on which acuthin is executing and port is the port on which it is listening.
Note: The value of debug_method_string overrides the value, if any, in the DISPLAY configuration variable for the xterm.

See Background Debugging Options for more information.

internal | a void pointer that is used by other extend products. Initialize the pointer internal to NULL.

Return values

The acu_cobol() function returns "0" if the call is successful and "-1" if the call failed.

The exit_code returns one of the following values defined in "sub.h":

Value |  | Description
COBOL_EXIT_PROGRAM | 1 | The called program finished via an EXIT PROGRAM statement (or equivalent, such as GOBACK).
COBOL_REMOTE_CALL | 2 | The called program is a remote program being run by AcuConnect®. In this case, the exact reason why the remote program finished is not available.
COBOL_STOP_RUN | 3 | The run unit halted due to a STOP RUN statement, and the runtime has been configured to return to the caller instead of exiting to the system.
COBOL_CALL_ERROR | 4 | The called program could not be run and the acu_cobol() function has returned "-1". This applies only to programs called directly by acu_cobol(). On an error loading a subroutine, acu_cobol() returns COBOL_FATAL_ERROR.
COBOL_SIGNAL* | 5 | The runtime caught a system signal that would normally shut down the runtime, but the runtime has been configured to return to the caller instead. Any error message associated with this signal is returned in exit_msg.
COBOL_FATAL_ERROR* | 6 | A fatal error has occurred that would normally shut down the runtime, but the runtime has been configured to return to the caller instead. Any message associated with the error is returned in exit_msg.
COBOL_NONFATAL_ERROR | 7 | An error has occurred that causes the acu_cobol() function to return and prevents the runtime from continuing to run the current program only. The runtime remains in a stable state and it is safe to make subsequent calls to acu_cobol().
COBOL_DEBUGGER | 8 | The user has quit the ACUCOBOL-GT debugger. It is safe to make subsequent calls to acu_cobol() after this error occurs.

* After a COBOL_SIGNAL or COBOL_FATAL_ERROR error, the process should not make any further calls to acu_cobol(). If another call is necessary, you must first unload and reload the runtime. If you are dynamically loading the runtime shared library on UNIX/Linux or runtime DLL on Windows, you can do this using dlclose()/dlopen() or FreeLibrary()/LoadLibrary() respectively. If you are linking directly to the runtime libraries, you will need to exit and restart the current process. Consider wrapping your executable in a shell script or another main() program that checks for a particular exit code and then loops.

The call_error can be one of the following values:

Value |  | Description
CS_SUCCESSFUL | 0 | Call was successful.
CS_MISSING | 1 | Program file is missing or inaccessible.
CS_NOT_COBOL | 2 | Called file is not a COBOL program.
CS_INTERNAL | 3 | Corrupted program file
CS_MEMORY | 4 | Inadequate memory is available to load program.
CS_VERSION | 5 | Unsupported object code version number
CS_RECURSIVE | 6 | Recursive CALL of a program; program already in use.
CS_EXTERNAL | 7 | Too many external segments
CS_LARGE_MODEL | 8 | Large-model program is not supported.
CS_JAPANESE | 14 | Japanese extensions are not supported.
CS_MULTITHREADED | 22 | Multithreaded CALL RUN is illegal.
CS_AUTHORIZATION | 23 | Access denied.
CS_CONNECT_REFUSED | 25 | Connection refused; user count is exceeded on remote server.
CS_MISMATCHED_CPU | 27 | Program contains object code for a different processor.
CS_SERIAL_NUMBER | 28 | Incorrect serial number
CS_USER_COUNT_EXCEEDED | 29 | Connection refused; user count is exceeded on remote server.
CS_LICENSE | 30 | License error
Parent topic: Function Reference


acu_initv()

The acu_initv() function performs all of the initialization needed to run a COBOL program. This includes loading the COBOL configuration file, initializing the user's station, and initializing each available file system.

Usage

int ASTDCALL acu_initv(int argc, char **argv);

The acu_initv() function also registers various signal handlers so that the runtime can catch certain signals and perform an orderly shutdown or some other function.

Using acu_abend() with the --no-signal-handlers runtime option allows you to control signal handlers based on the signal type.

For more information on acu_initv(), see Initializing the Runtime.

Parameters

  • argc — the number of arguments passed in argv, at least 1
  • argv — an array of arguments. It must contain at least one argument in argv[0]. This should be a pointer to the name of the executable file, that is, the same as the argv[0] passed to your own main routine.

Note that in some situations, this array of character pointers is needed after acu_initv() returns. Therefore, the variable passed in this parameter must remain in scope until the runtime shuts down. You can accomplish this in one of several ways:

  1. Make argv a static variable in the C function where it is defined.
  2. Make argv a global variable to the C module.
  3. Call the functions, acu_initv(), acu_cobol(), and acu_shutdown() from within a single function of your application (or in subfunctions of the C function that calls acu_initv()).
Note: If you do not keep argv in scope for the duration of the runtime's life, you may experience unwanted results.

No other arguments are required. To pass additional arguments, format them in the same manner as a typical runcbl command line, where arguments to the runtime are followed by the COBOL program name, and then by any arguments to that COBOL program.

Return Values

This function returns the argument number of the COBOL program name in argv (or the value of argc if there isn't one), if there is not a failure and the --xreturn argument is not present in argv. The runtime's own main routine uses this to easily locte the name of the program to load. If there is a failure and --xreturn is present in argv, a negative number is returned indicating the source of the failure. Use the following symbols, defined in sub.h, to interpret the failure code.

AINITV_SUCCESS | Sucess
AINITV_LICENSE_EXPIRED | License had expired
AINITV_LICENSE_NOT_FOUND | License not found
AINITV_LICENSE_EXCEEDED | License user count exceeded
AINITV_INIT_LIBRARY_FAILED | Library initialization failed
AINITV_LOAD_LIBRARY_FAILED | Library load failure
AINITV_CFG_FAILED | Configuration error
AINITV_DEBUG_FAILED | Debug initialization failed
AINITV_FILE_FAILED | File manager initialization failed
AINITV_MEM_FAILED | Memory allocation failure
AINITV_RMT_FILE_FAILED | Remote file manager initialization failed
AINITV_STARTUP_FAILED | Runtime initialization failed
AINITV_PROFILE_FAILED | Profile initialization failed
AINITV_MISMATCHED_VERSIONS | Mismatched version between runtime and support module
AINITV_EXCEPTION | Exception encountered
Parent topic: Function Reference


aculongjmp()

This aculongjmp() routine cuts the C and COBOL call stacks to the point recorded in passed "acujmp_buf". This point must have been recorded by a prior call to both acusavenv() and setjmp(). Once a state has been recorded, you can only jump to it one time using aculongjmp(). After that, it must be recorded again.

Usage

void

aculongjmp(acujmp_buf *buffer)
Note:

Like acusavenv(), aculongjmp() is intended for use with batch programs or programs written for a transaction processing system and therefore is not recommended for programs that use the ACUCOBOL-GT graphical user interface.

Return Values

This routine does not return; instead, it internally calls the C library longjmp() routine which transfers control to the point of the prior setjmp() call and causes setjmp() to return a value of "1".

Example

#include "acusetjmp.h"
acujmp_buf  mark1;

/* A COBOL or 'C' subroutine can CALL "myexception" to transfer
/* control
back to the point where "mark1" was recorded.  */

void myexception()
{
aculongjmp( &mark1 );
}

/* Prototypical 'C' service routine to run a COBOL program with
/* the ability
 to exit out of the COBOL code via call to
/* 'myexception' */

void myservice()

{
/* Record our position in the 'C' and COBOL call stacks.
/* 'Setjmp' will return "0" when executed first. We
/* call it in a "while" loop so that the location
/* recording re-executes in case we end
/* up jumping here via 'aculongjmp' */
while( setjmp( *acusavenv(&mark1) ) )
{
/* If we get here, it's because 'aculongjmp' jumped
/* here. Put recovery/cleanup code here.
/* If you do not want to re-execute the COBOL routine,
/* add
 a "return" here.  Otherwise, just fall out of the
/* while
 loop to re-execute the COBOL routine */
}

/* Setup to call COBOL here and call a COBOL routine */
/* The COBOL program can jump back to the top of this
/* routine by calling "myexception" at some point.  This
/* will transfer control to the point of the 'setjmp'
/* call above and cause 'setjmp' to return "1".  */

struct a_cobol_info cblinfo;
memset(&cblinfo, 0, sizeof(cblinfo));
cblinfo.a_cobol_info_size = sizeof(cblinfo);
cblinfo.pgm_name = "cblprog";
cblinfo.num_params = 0;
cblinfo.params = NULL;
acu_cobol(&cblinfo);
}

Restrictions

  • As with setjmp(), the function that calls acusavenv() must not exit before any calls to aculongjmp() that use the same buffer. Programs that do this will have undefined (and usually fatal) results.
  • aculongjmp() works by simulating EXIT PROGRAM statements for each of the COBOL programs being exited. This EXIT PROGRAM has all its normal effects. If a program cannot exit for some reason, the call to aculongjmp() fails and the runtime shuts down with a fatal error. Reasons that EXIT PROGRAM can fail include:
    • The program is the main program.
    • The program is currently running an event procedure.
    • The program is the root program of a thread.
    • The program is currently in a Declarative called directly by the BULK-ADDITION feature of Vision.
  • Because the caller of aculongjmp() must be in the same run unit as the caller of the corresponding acusavenv(), avoid using the CHAIN verb.
  • The caller of aculongjmp() must be in the same COBOL thread as the caller of the corresponding acusavenv(). In addition, the effect of aculongjmp() on other COBOL threads is undefined. We recommend that you stop any other threads prior to calling aculongjmp().
  • After aculongjmp() uses a buffer, that buffer is no longer valid and must be re-recorded by a new call to acusavenv() and setjmp(). This behavior is different from the normal setjmp()/longjmp() convention. If converting existing setjmp() logic, you can usually accomplish this by replacing the "if" statement that contains the call to setjmp() with a "while" statement. For example:
    if ( setjmp(mybuf) == 1 )
{
/* longjmp lands here */
}
becomes:
while ( setjmp(*acusavenv(&myacubuf)) == 1 )
{
/* aculongjmp lands here */
}
Parent topic: Function Reference


acu_register_sub()

The acu_register_sub() function allows you to register a subroutine in your C main program.

Usage

typedef int (*ACU_SUB_FUNC) (int argc, char **argv);
ACU_SUB_FUNC *acu_register_sub( ACU_SUB_FUNC *pFunc );

See Calling COBOL subroutines that call C routines, for more information on using this function.

Return Values

This function returns the previously registered function, or NULL if no function was registered.

Parent topic: Function Reference


acu_runmain()

The acu_runmain() function can be used to start up a COBOL program which is treated like the main program of the run unit.

Usage

void ASTDCALL acu_runmain(int argc, char **argv, int pgm_arg);

Parameters

argc and argv are main-style arguments. Typically, they are the same as the values passed to acu_initv().

program_arg is the argument number (in argv) of the name of the COBOL program.

Example

For an example of using acu_runmain(), see Starting a COBOL main program.

Return Values

When the COBOL program stops, the acu_runmain() function halts but does not return.

Parent topic: Function Reference


acusavenv()

The acusavenv() routine records information about the state of the COBOL call stack and returns a pointer to a jmp_buf structure that can be passed to setjmp. You pass this routine an acujmp_buf structure, which carries the combined C and COBOL stack states.

Usage

jmp_buf *
acusavenv(acujmp_buf *buffer)

refer to the entry on aculongjmp() for more information on using acusavenv(). See your C documentation for information on the setjmp and longjmp routines, as you need a working understanding of these routines to use acusavenv() and aculongjmp().

Note:

The acusavenv() function is intended for use with batch programs or programs written for a transaction processing system, allowing such systems to restart or recover from a failed service component. Therefore, they are not recommended for programs that use the ACUCOBOL-GT graphical user interface, which are typically event-driven and multithreaded.

Parent topic: Function Reference


acu_shutdown()

This routine performs all the necessary exit handling needed by the runtime. It also ensures that all COBOL files are closed and that the screen is returned to its normal operating state.

Usage

void ASTDCALL acu_shutdown(int place_cursor);
Note: After acu_shutdown() returns, do not call any COBOL subroutines again during this run. In particular, do not try to re-initialize the runtime with another call to acu_initv().

Parameters

If you pass a non-zero value in place_cursor, the runtime places the screen's cursor on the last line of the screen and scrolls the screen one line. This is the normal behavior that you see when you execute a STOP RUN. If you pass a zero in place_cursor, the cursor is not moved and the screen is not changed.

The value of place_cursor overrides the EXIT_CURSOR configuration variable, which also controls the handling of the cursor at shutdown.

Example

For an example of using acu_shutdown(), see Shutting down the runtime.

Parent topic: Function Reference


acu_unload()

The acu_unload() function removes a "cached" program from memory. If "called_programs = 1", acu_unload() also unloads called subprograms.

Usage

void ASTDCALL acu_unload(char *name, int called_programs);
Note: The DYNAMIC_MEMORY_LIMIT configuration variable affects how memory is released by calls to this function. See DYNAMIC_MEMORY_LIMIT for information on this configuration variable.

For more information on caching programs, see Unloading Programs from Memory.

Parent topic: Function Reference


acu_unload_all()

The acu_unload_all() function removes all cached programs from memory.

Usage

void ASTDCALL acu_unload_all(void);
Note: The DYNAMIC_MEMORY_LIMIT configuration variable affects how memory is released by calls to this function. See DYNAMIC_MEMORY_LIMIT for information on this configuration variable.

For more information on caching programs, see Unloading Programs from Memory.

Parent topic: Function Reference


Using the C API: Two Approaches

Using the C API, you can:

  • Call ACUCOBOL-GT programs from C
  • Call the ACUCOBOL-GT runtime from a C main program.

You can use the same basic method to perform both of these tasks.

  • Simple Use Case for acu_cobol()
  • Calling the Runtime From a C Main Program
  • Calling COBOL Routines
  • Exception Handling
  • Unloading Programs from Memory
  • Signal Handling
  • Setting a Debug Method with acu_cobol()
Parent topic: Working with C and C++ Programs


Simple Use Case for acu_cobol()

The following example demonstrates a call to the acu_cobol() C function:

int
main(int argc, char *argv[])
{
char *initv[3];
struct a_cobol_info cblinfo;
initv[0] = argv[0];
initv[1] = "-c";
initv[2] = "myconfig";
acu_initv(3, initv);
memset(&cblinfo, 0, sizeof(cblinfo));
cblinfo.a_cobol_info_size = sizeof(cblinfo);
cblinfo.pgm_name = "MYCBLPGM";
acu_cobol(&cblinfo);
acu_shutdown(1);
return 0;
}
This is equivalent to running a program from the command line as:
runcbl -c myconfig "MYCBLPGM"

If you add the no_stop parameter to the a_cobol_info structure, the COBOL program returns to the caller if the program executes a STOP RUN:

struct a_cobol_info cblinfo;

memset(&cblinfo, 0, sizeof(cblinfo));
cblinfo.a_cobol_info_size = sizeof(cblinfo);
cblinfo.pgm_name = "MYCBLPGM";
cblinfo.no_stop = 1;
acu_cobol(&cblinfo);

Otherwise, you can remove the no_stop parameter and force the executable to halt:

struct a_cobol_info cblinfo;

memset(&cblinfo, 0, sizeof(cblinfo));
cblinfo.a_cobol_info_size = sizeof(cblinfo);
cblinfo.pgm_name = "MYCBLPGM";
acu_cobol(&cblinfo);
Note:

The acu_cobol() function does return to the caller when the program performs a STOP RUN if the call is made through the Web runtime or if the runtime is running as an automation server.

Parent topic: Using the C API: Two Approaches


Calling the Runtime From a C Main Program

ACUCOBOL-GT uses a runtime system to execute its compiled COBOL programs. This runtime system is a fully linked executable program and, as such, contains its own main routine. The runtime assumes that the first program to run will be a COBOL program.

If, however, you have a "server" program in an OLTP environment that waits for requests from clients and then calls COBOL to handle those requests, you can choose to replace the runtime's own main routine with another.

Note:

You do not need to start a COBOL main program to call COBOL subroutines. If you use a C main program, note that certain COBOL verbs can prevent you from returning from a called COBOL subroutine to your C main program.

  • Creating the Runtime
  • Initializing the Runtime
  • Shutting Down the Runtime
  • Notes on COBOL Verbs
Parent topic: Using the C API: Two Approaches


Creating the Runtime

The ACUCOBOL-GT runtime library (used to relink the runtime system) comes with its own main routine. The library contains this routine in a separate object module. To create a runtime system that uses your own main routine, you simply add a routine called "main" to one of your C source files and re-create the runtime. Because the linker uses your C object files before searching the library, your main routine is used and the one in the library is not linked.

To relink the runtime system, follow the instructions in the topic Relinking the Runtime System. The technique for relinking the runtime depends on the machine type.

Parent topic: Calling the Runtime From a C Main Program


Initializing the Runtime

If you are calling the runtime from a C main program, you must initialize the runtime prior to calling any COBOL programs from your C code. To do this, call the following routine:

int
acu_initv( argc, argv )
int     argc;
char    *argv[];

You pass this routine's arguments in a format identical to those passed to the C main function. The COBOL program's name is used during initialization to determine the default title of any GUI-based window, but the program itself is not loaded or executed. Arguments to the COBOL program are not used by initialization and may be omitted. If you omit the COBOL program name, initialization occurs using the default name of "cbl.out".

The acu_initv() function calls the user-supplied routines exam_args (passing argc and argv) and Startup (passing the name of the COBOL program). These routines are normally empty, but may be modified by you. They can be found in the "sub.c" file supplied with the runtime system.

Note: Since argv is an array of character pointers that may be needed after acu_initv() returns, keep argv in scope until you shut down the runtime. For more information, see acu_initv().

Example

The following code might be used by a server routine that intends to use COBOL subroutines to perform various file operations. In this scenario, no screen operations are done from COBOL, so we want to inhibit ACUCOBOL-GT's default screen initialization. To do this, we must pass the "-b" command-line option. Because the program will perform no screen operations, we do not care about the default window title and, thus, do not need to pass a COBOL program name.

int
main( argc, argv )
int     argc;
char    *argv[];
{
     char     *initv[2];
     initv[0] = argv[0];
     initv[1] = "-b";
     acu_initv( 2, initv );
     /* other code follows */
}
Parent topic: Calling the Runtime From a C Main Program


Shutting Down the Runtime

You can halt the runtime from COBOL by executing a STOP RUN statement and the runtime terminates normally. Note that this action calls the user-supplied C routine called Shutdown found in "sub.c".

To halt the runtime from C, call the following routine:

void
acu_shutdown( place_cursor )
int     place_cursor;

Example

The following C program calls a single COBOL routine once, passing it one argument. After the COBOL routine returns, it cancels that program and halts. While it is not necessary to cancel the program in this example, the code is shown for completeness.

#include <stdio.h>
#include "sub.h"
main( argc, argv )
int     argc;
char    *argv[];
    {
    struct a_cobol_info cblinfo;
    Argument cblargs[1];
    acu_initv(argc, argv);
    cblargs[0].a_address = "Hello World";
    cblargs[0].a_length = 11;
    memset(&cblinfo, 0, sizeof(cblinfo));
    cblinfo.a_cobol_info_size = sizeof(cblinfo);
    cblinfo.pgm_name = "cblprog";
    cblinfo.num_params = 1;
    cblinfo.params = cblargs;
    acu_cobol(&cblinfo);
    acu_cancel( "cblprog" );
    acu_shutdown( 0 );
    exit( 0 );
}

A simple example of "cblprog" might be:

identification division.
program-id.  cblprog.
data division.
linkage section.
77   hello-world     pic x(11).
procedure division using hello-world.
main-logic.
     display hello-world.
     exit program.
Parent topic: Calling the Runtime From a C Main Program


Notes on COBOL Verbs

The following notes describe special considerations for COBOL verbs when you are calling the ACUCOBOL-GT runtime from a C main program.

CALL and CALL RUN

The CALL and CALL RUN verbs work normally. You return from a CALL with EXIT PROGRAM and from a CALL RUN with STOP RUN.

EXIT PROGRAM

The EXIT PROGRAM verb works normally. Use EXIT PROGRAM to return from a COBOL subroutine to the C function that called it.

STOP RUN

A STOP RUN causes the runtime to shut down (except when a STOP RUN returns to a CALL RUN statement). If you need to control the shutdown in C (to perform clean-up for example), do not code any STOP RUN statements. Alternatively, you can place any clean-up code you need in the acu_shutdown() routine found in "sub.c". This routine is automatically executed during runtime shutdown.

Refer to the no_stop element of the ACUCOBOLINFO structure for more information.

CHAIN and CALL PROGRAM

Both the CHAIN and CALL PROGRAM verbs halt the current run unit and initiate a new run unit. Use these verbs with care as they prevent you from returning to your C main program. The chained-to COBOL program is now treated as the start of a new run unit, essentially meaning that it acts like a main program. Because it is treated like a main program, the EXIT PROGRAM verb in it is ignored. The only way to halt the program is with a STOP RUN (which halts the entire runtime) or with another CHAIN.

If you do execute a CHAIN or CALL PROGRAM, any C routines that are part of the call stack leading to the first COBOL subroutine will be left in place. Although you cannot access these routines, their stack memory remains allocated. On the other hand, any C routines that are on the call stack after the first COBOL subroutine will be removed from the stack.

There is one case where you can still return to your C routine after executing a CHAIN. This case occurs when you use the CALL RUN verb to initiate a new run unit without halting the original. The new run unit can use CHAIN. When the new run unit finally executes a STOP RUN, control returns to the original run unit, which may still return to your C routine via an EXIT PROGRAM.

However, we suggest avoiding these verbs.

Parent topic: Calling the Runtime From a C Main Program


Calling COBOL Routines

When calling a COBOL routine, you can either start a COBOL main program (which is what the runtime normally does), or you can just call COBOL subroutines.

  • Starting a COBOL Main Program
  • Calling COBOL Subroutines that Call C Routines
  • Canceling a COBOL Subroutine
Parent topic: Using the C API: Two Approaches


Starting a COBOL Main Program

You can start a COBOL main program by calling the acu_runmain() routine as follows:

void
acu_runmain( argc, argv, program_arg )
int     argc;
char    *argv[];
int     program_arg;

This routine initiates a COBOL main program and never returns.

If you omit the COBOL program name (defaulting to "cbl.out"), then program_arg should be the same as argc. Any arguments in argv following program_arg are passed as CHAINING arguments to the COBOL program. Note that program_arg is usually the same as the return value from acu_initv().

Note:

The arguments in argv before program_arg are not actually used in acu_runmain(). This form is simply used for calling convenience.

Parent topic: Calling COBOL Routines


Calling COBOL Subroutines that Call C Routines

If you are calling COBOL subroutines in Windows, which in turn call C routines, you may want to locate those routines in the calling executable file. You can do this without relinking the runtime by registering your own "sub" function in the C main program. You must add the following declaration to your main program:

typedef    int    (*ACU_SUB_FUNC)(int argc, char **argv);
ACU_SUB_FUNC      *acu_register_sub( ACU_SUB_FUNC *pFunc );

The routine acu_register_sub() registers its argument (pFunc) as an additional "sub" function to call. If pFunc is set to NULL, any existing registration is removed.

The registered function is called just like "sub", but it is called before "sub". Note that "sub" is still called if the registered function returns the constant NotFound.

Example

The following C routine calls a COBOL program which, in turn, calls a C program named "MSGBOX":

#include <stdio.h>
#include <windows.h>
#include "sub.h"

extern     int   __stdcall AcuInitialize( char *cmdLine );
extern    void   __stdcall AcuShutdown(void);

// This is the "sub" function that will be registered
int __cdecl local_sub( int argc, char **argv )
{
    if ( strcmp( argv[0], "MSGBOX" ) == 0 ) {
       MessageBox( NULL, argv[1], NULL, MB_OK );
       return Okay;
    }
    return NotFound;
}
// local_sub
int WINAPI WinMain( HINSTANCE hInstance, HINSTANCE
    hPrevInstance, LPSTR lpCmdLine, int nCmdShow )
{
    MessageBox( NULL, "Starting in 'C'", NULL, MB_OK );

// Initialize the runtime using the Visual Basic initializer.
// This prevents the runtime from calling exit() when halting.
    AcuInitialize( "" );

// Install our "sub" handler
   acu_register_sub( local_sub );

// Call the COBOL program. This one takes no parameters
// Assume that this program calls MSGBOX at some point.
// MSGBOX is located in "cblprog".  It will be found
// because "cblprog" got registered with the runtime.
    struct a_cobol_info cblinfo;
    memset(&cblinfo, 0, sizeof(cblinfo));
    cblinfo.a_cobol_info_size = sizeof(cblinfo);
    cblinfo.pgm_name = "cblprog";
    cblinfo.num_params = 0;
    cblinfo.params = cblinfo.no_stop = 1;
    acu_cobol(&cblinfo);

// De-initialize the runtime.
    AcuShutdown();
    MessageBox( NULL, "Back in 'C' - finished", NULL,
        MB_OK );
    return 0;
}

Here is the COBOL program called above:

program-id. test.
working-storage section.
77  message-text         pic x(80).
procedure division.
main-logic.
    display "In COBOL program".
    display "Calling MSGBOX"
    move "This is a message" to message-text
    inspect message-text replacing trailing spaces by
       low-values
    call "MSGBOX" using message-text
    display "Back from MSGBOX".
    display "Press enter to execute STOP RUN ", no
       advancing.
    accept omitted.
    stop run.
Parent topic: Calling COBOL Routines


Canceling a COBOL Subroutine

If you wish to simulate the COBOL CANCEL verb from C, you can do so by calling the following routine:

void
acu_cancel( program )
char    *program;

You pass this routine the name of the program you want to cancel. This name should be identical to the string that you passed to the acu_cobol() function to call that program. Canceling a program releases the memory it occupies and resets its internal data to its initial state if you call the program again. Also, any files left open in the program are closed. If program does not match the name of any COBOL program in memory, then nothing happens when you call this routine.

Parent topic: Calling COBOL Routines


Exception Handling

The C library routines setjmp and longjmp provide functionality that cannot typically be used in the context of the ACUCOBOL-GT runtime. These routines provide "mark" and "goto" points in the call stack of C routines and sometimes provide a convenient exception-handling mechanism.

Because these routines do not know about the COBOL call stack, they cannot be used in cases where C routines call COBOL. However, the acusavenv() and aculongjmp() functions allow batch programs or programs written for a transaction processing system to restart or recover from a failed service component.

Note:

The acusavenv() and aculongjmp() functions are only usable from C and are not recommended for programs that use the ACUCOBOL-GT graphical user interface, which are typically event-driven and multithreaded.

Parent topic: Using the C API: Two Approaches


Unloading Programs from Memory

The ACUCOBOL-GT runtime allows you to cancel and unload programs from memory based on the state of the object module. By default, the CANCEL statements and corresponding C functions, acu_cancel() and acu_cancel_all(), perform a physical cancel, placing programs in their initial state. The runtime also allows you to enable logical cancels, which may improve performance. For a description of runtime memory management and physical and logical cancels, see Memory Management.

Both logical and physical cancels close open files and ensure that any VALUE clauses are in effect when the program is called again. Physical cancels also release any memory used by the program

The following C functions unload one or all programs from memory based on the state of the object module:

  • acu_cancel()
  • acu_cancel_all()
  • acu_unload()
  • acu_unload_all()

The acu_cancel() and acu_cancel_all() functions perform a logical cancel. The acu_unload() and acu_unload_all() functions perform a physical cancel and force a subsequent call to load the new object file from disk.

Using these functions, an object module can be in one of four states:

  • Active
  • Loaded but inactive
  • Not loaded
  • Cached, which means the same as "Loaded but inactive" except that the files and data items are set to their initial state.

Note that the LOGICAL_CANCELS and DYNAMIC_MEMORY_LIMIT configuration variables affect how canceled programs are handled. For information on these variables, see Configuration Variables.

Parent topic: Using the C API: Two Approaches


Signal Handling

The ACUCOBOL-GT runtime normally installs default signal handlers to ensure that the runtime system is cleaned up before terminating. In some environments, the runtime may frequently need to switch back and forth between executing COBOL programs and C programs. Used with the runtime option, "--no-signal-handlers", the acu_abend() function allows you to optimize performance by specifying when to preserve signal handlers based on the signal type.

In OLTP environments, for example, the server may need to install and uninstall signal handlers while processing an EXEC CICS statement. In this case, you can enable the ACUCOBOL-GT signal handlers when an application is running COBOL code and enable the previously installed signal handlers when the application is not running COBOL programs.

When you initialize the runtime with "--no-signal-handlers", the runtime does not call the ACUCOBOL-GT signal handlers. You can then install your own signal handlers and call the acu_abend() function to perform the equivalent of the ACUCOBOL-GT signal handlers when needed.

  • When to Call acu_abend()
Parent topic: Using the C API: Two Approaches


When to Call acu_abend()

We recommend calling acu_abend() from your own signal handlers only when an application is executing COBOL code when the signal occurs. Otherwise, you can omit the call to acu_abend(). For example, under the following circumstances, you do not need to call acu_abend():

  1. You made a call to acu_cobol() to execute a COBOL program that then exited, and
  2. After acu_cobol() returns, your application executes some other non-COBOL processing during which a signal is caught.

In fact, calling acu_abend() at this point may result in misleading error messages because the signal did not occur when running a COBOL program.

Parent topic: Signal Handling


Setting a Debug Method with acu_cobol()

Using the a_cobol_info structure in the acu_cobol() function, you can debug COBOL programs from within a transaction processing environment using an xterm window, a terminal, or the thin client. Note that implementing this feature requires support from the vendor of the environment (for example, an OLTP environment provider).

For more information, see the ACUCOBOL-GT supplement for your OLTP environment and Background Debugging Options.

Parent topic: Using the C API: Two Approaches


Other Interface Paths for COBOL and C

Calling C programs through the runtime and calling ACUCOBOL-GT through the C API are the primary methods for interoperating with C. However, the following three methods may be valuable in special cases:

  • Using the C$SOCKET runtime routine, you can establish interprocess communication via sockets. C$SOCKET is a low-level conduit that provides lots of flexibility.
  • Using the C$SYSTEM runtime library routine, you can send a C command line to the program's host system.
  • Using named pipes, you can pass data between COBOL and C programs. Named pipes are a method for exchanging information between two unrelated processes.

These methods are described in the next three sections.

  • Connecting with C$SOCKET
  • Starting a Program with C$SYSTEM
  • Passing Data with Named Pipes
Parent topic: Working with C and C++ Programs


Connecting with C$SOCKET

If desired, you can facilitate communication between C and COBOL programs at a socket level. ACUCOBOL-GT includes a C$SOCKET library routine, which supports socket-level interprocess communication.

When communicating with sockets between COBOL and C, or any other language, you must:

  1. Determine which side is the client and which is the server.
  2. Open a listening socket from the server process.
  3. Open a connecting socket from the client process.

Of course, because the data format is totally open and undefined, the COBOL and C programmers must agree on a common format.

The following sample code demonstrates this capability:

*The following code creates a server socket.
CALL "C$SOCKET" USING AGS-CREATE-SERVER, 8765
   GIVING SOCKET-HANDLE-1.

*The following code waits for a connection.
CALL "C$SOCKET" USING AGS-NEXT-READ, SOCKET-HANDLE-1, TIMEOUT.

*If you have a connection request, accept the connection.
CALL "C$SOCKET" USING AGS-ACCEPT, SOCKET-HANDLE-1.

*Read data from the connecting socket.
CALL "C$SOCKET" USING AGS_READ, SOCKET-HANDLE-2,
   SOCKET-IN, IN-DATA-LENGTH
   GIVING READ-AMOUNT.

*Write outgoing data back to the client socket.
CALL "C$SOCKET" USING AGS-WRITE, SOCKET-HANDLE-2,
   SOCKET-OUT, OUT-DATA-LENGTH.

See C$SOCKET for more information on the C$SOCKET library routine.

Parent topic: Other Interface Paths for COBOL and C


Starting a Program with C$SYSTEM

Another way to invoke a C program from COBOL is via the operating system command line using the C$SYSTEM library routine. This routine combines the functionality of SYSTEM and C$RUN.

To call a C program from COBOL via C$SYSTEM, you:

  1. Call the C$SYSTEM library routine. The C$SYSTEM routine submits the command line to the host operating system as if it were a command keyed in from the terminal.

    Note that you can call C$RUN instead of C$SYSTEM to run the command asynchronously.

  2. Pass data from the C program to the COBOL program through a disk file or database.

C$SYSTEM and C$RUN for complete information on these library routines.

Parent topic: Other Interface Paths for COBOL and C


Passing Data with Named Pipes

Another way to pass data between COBOL and C programs is through named pipes. Named pipes are a method for exchanging information between two unrelated processes.

Note:

To communicate via named pipes, the COBOL and C programs must be on the same host machine.

Technically, named pipes are files with known pathnames. Because a named pipe is associated with a pathname, unrelated processes can open the file to begin communications with one another. Because a C program can open a named pipe just as it would a normal file, no special code is required. By opening the file for reading, a process has access to the reading end of the pipe, and by opening the file for writing, a process has access to the writing end of the pipe. In effect, named pipes allow independent processes to "rendezvous" their I/O streams.

Named pipes can be created in two ways: via the command line or from within a program.

In UNIX, to create a named pipe with the file named "npipe" you can use the following command on the command line:

% mkfifo npipe

Alternatively, you could create the named pipe from within your program using:

int mkfifo(const char *path, mode_t mode)

where path is the path of the file and mode_t is the mode (permissions) with which the file should be created.

A named pipe can be opened using the open( ) system call or the fopen( ) standard C library function.

As with normal files, if the call succeeds, you get either a file descriptor or a "FILE" structure pointer, depending on how you opened the file. You can then use this information for reading or writing, depending on the parameters you passed to open( ) or fopen( ).

Reading from and writing to a named pipe are very similar to reading from and writing to a normal file. You can use the standard C library function calls read( ) and write( ).

Named pipes can also be used on Windows systems. You create Windows pipes with the CreateNamedPipe( ) API. You can then use the CreateFile( ) API to access the other end of the newly created named pipe.

Although named pipes can be very effective for communicating between COBOL and C applications, bear in mind the following:

  • Named pipes work only for processes on the same host machine.
  • Named pipes can be created only in the local file system of the host.
  • Named pipe data is a byte stream, and no record identification exists.
  • Named pipes provide only a half-duplex flow of data. They are also known as "fifos" for their method of "first in, first out" communication. To establish full-duplex communication, you must create and manage two pipes, which can be complicated and result in file deadlocks if you are not careful.
Parent topic: Other Interface Paths for COBOL and C


Tracking, Monitoring and Debugging Memory

Several tools help you track, test, and debug memory in extend products, including the runtime and linked C programs. These facilities are particularly helpful when ACUCOBOL-GT programs interface frequently with C programs.

All products have the ability to monitor, test, and debug memory allocations in three ways. They can:

  • Track memory boundaries, so that if any boundaries are corrupted a report is generated. This facility is called memory bounds checking.
  • Track how much memory is allocated in each of six subsystems. This facility is referred to as memory tracking.
  • Output a description of each memory allocation, reallocation, and release by file and line. Each action can also include a programmed text message. This facility is called memory handling descriptions.

These facilities are described in detail in Memory Testing and Error Handling. How these facilities are accessed via C is described in the following sections.

Note: The memory allocation features can be turned on and off using the appropriate runtime options (described in Memory Testing and Error Handling), and the available monitoring, testing, and debugging features are determined by the state of the parallel runtime option. For example, when boundary checking is turned off, memory boundaries are not set and executing dbg_test() does not test the boundaries of blocks allocated. Similarly, turning off memory tracking will stop keeping track of newly allocated memory, and the numbers reported will not reflect blocks allocated while the feature is off.
  • Memory Debugging via C
  • Turning Memory Debugging Features On and Off
  • Reporting Allocated Blocks
  • Getting Memory Amounts
  • Testing Memory Boundaries
Parent topic: Working with C and C++ Programs


Memory Debugging via C

If you are using and writing C routines, you can access an abundance of memory tracking information.

If you allocate memory and want to tie into the ACUCOBOL-GT memory debugging facilities, you can use the following functions to allocate, reallocate, and free memory.

void *Amalloc(size_t size, int subsys, const char *file, long line,
             const char *call_desc);

void *Arealloc(void *ptr, size_t newsize, const char *file, long line,
             const char *call_desc);

void  Afree(void *ptr, const char *file, long line,
             const char *call_desc);

size, ptr, and newsize are equivalent to the same parameters passed to malloc(), realloc() and free().

subsys is one of: M_OVERHEAD (0), M_PROGRAMS (1), M_FILES (2), M_WINDOWS (3), M_DYNAMIC (4), M_NOT_TRACKED (5). It can be modified by ORing with the value M_NO_ZERO (0x8000) in order for the memory to not be set to low-values before being returned to the application. This parameter is used only if the memory tracking debugging feature is turned on. The first five values (0 - 4) are what the runtime sends to the debugger to report memory usage when the "U" command is specified.

file and line are the filename and line number of the operation, and are best set by the standard C macros __FILE__ and __LINE__. These values are used only if the memory description debugging feature is turned on.

description is a text description of the memory and is printed in the memory description report.

call_desc is a text description of the call. If null, it defaults to M_alloc(size) for Amalloc, M_realloc(ptr, newsize) for Arealloc, and M_free(ptr) for Afree. This text is printed in the memory description report.

Note that you are not required to use these functions to allocate and free memory used by your C routines. However, it is essential that memory allocated by Amalloc() or Arealloc() not be freed by the system free() function. It must be freed with Afree(). Similarly, memory allocated by malloc(), calloc(), or realloc() must be freed with the system free() function, and not the ACUCOBOL-GT Afree() function. Disregarding these rules will almost certainly result in a memory access violation.

Parent topic: Tracking, Monitoring and Debugging Memory


Turning Memory Debugging Features On and Off

To use the memory debugging functions from C, you must use the following functions:

Aget_memory_debug_flag()

This function gets the current state of the memory debugging feature. It returns an int.

Aset_memory_debug_flag(int flag)

This function sets the current state of the memory debugging feature. The int values are described as follows:

The memory description value, as used by the runtime, is the low six bits (though currently only three bits are used). In other words, the memory description value can be retrieved by ANDing the returned flag with 0x003F.

The memory tracking feature is turned on if (flag & 0x0040) is non-zero.

The memory bounds checking feature is turned on if (flag & 0x0080) is non-zero.

You can turn on memory handling descriptions by calling the function:

void Aset_mem_file_name(const char *filename);

Note that if memory descriptions are turned on but a filename is not given, memory descriptions are not reported.

Parent topic: Tracking, Monitoring and Debugging Memory


Reporting Allocated Blocks

A list of all allocated blocks can be written to the memory description file by calling the function:

void Amem_dump(int final);

If final is non-zero, it is considered the final memory dump. The memory description file is closed, and the memory description feature is turned off.

Parent topic: Tracking, Monitoring and Debugging Memory


Getting Memory Amounts

To get a report of how much memory each subsystem has allocated, you can call:

size_t Aget_mem_used(int subsys);

subsys must be a value from 0 – 5. The function returns the amount of memory allocated for that subsystem. The subsystem is the same as the subsys passed to Amalloc().

Parent topic: Tracking, Monitoring and Debugging Memory


Testing Memory Boundaries

When the boundary checking feature is turned on, the dbg_test() function can be used to check that all memory boundaries are still intact. dbg_test() has the following prototype:

void dbg_test(const char *description);

This checks all memory blocks allocated while boundary checking is on to verify that memory boundaries have not been violated. It checks both the beginnings and the endings of all such blocks.

Note:

Memory bounds testing has a significant impact on performance and should only be enabled to assist in program testing and debugging.

Parent topic: Tracking, Monitoring and Debugging Memory


Deploying ACUCOBOL-GT Applications on the Web

  • COBOL on the Web
  • Web Thin Client
  • COBOL CGI Interface
  • Web Runtime
  • Internet Helper Application
  • Web Browsing from COBOL
  • COBOL Web Services
  • Other Internet Solutions
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


COBOL on the Web

We offer a variety of solutions for deploying COBOL applications on the Internet. Some allow you to make your COBOL programs and data accessible on the Web from popular Internet browsers. Others allow you to harness the Internet in a more secure TCP/IP networking configuration.

Following are some of the Web-based solutions available to our customers:

  • Web thin client – You can add the ACUCOBOL-GT® Web Thin Client to your Web page so that when users visit your site, the thin client downloads and installs on their machines and automatically launches your application on the server. In thin client architectures, the application logic runs on the server. Only the user interface displays on the client.
  • Web runtime – You can add the ACUCOBOL-GT Web Runtime to your Web page so that when users visit that page, the runtime downloads and installs on their machines and automatically launches your application locally.
  • COBOL CGI interface – You can create a Web interface to your COBOL application and allow users to interact with pages on your Web site via an HTTP browser or mobile device using ACUCOBOL-GT's Common Gateway Interface (CGI) extensions.
  • Internet helper application – If your users already have a licensed copy of the ACUCOBOL-GT runtime on their machine, they can gain access to your applications on the Web by setting up the runtime as an Internet helper application or viewer inside their browser. When they click a link on your Web site, the browser knows to associate the application with the ACUCOBOL-GT runtime.
  • Web browsing from COBOL – ACUCOBOL-GT includes a Web browser control that lets you add a variety of Internet features to your COBOL program. With this control, your programs can support Web browsing; display HTML pages; invoke e-mail, telnet, and FTP services; and more. You can even give your program Windows print, file, and clipboard capabilities.
  • COBOL Web services – Using our Java and .NET interfaces, you can expose your COBOL applications as Web services for use in Web services deployments.

These options are described in detail in A Programmer's Guide to the Internet, available on your product distribution media.

Parent topic: Deploying ACUCOBOL-GT Applications on the Web


Web Thin Client

If you want Windows users to launch applications from your Web site and have the applications run exclusively on the remote server, you can use the ACUCOBOL-GT Web Thin Client. In this scenario, end users simply visit your Web site. The Web browser searches for the Web thin client on their machines. If successful, it launches the program on the server. If it cannot locate the Web thin client, it provides the software automatically with users' permission. It then invokes the server application transparently and "projects" the user interface back onto the client. The Web thin client is an ActiveX version of our thin client solution.

Alternatively, end users can install the standard ACUCOBOL-GT Thin Client on their local machine. They can install it from any ACUCOBOL-GT media or, subject to appropriate licensing agreements, you can distribute it on your Web site so that end users can download and install it from there. Using an Active Server Page (ASP), Java Server Page (JSP), Visual Basic, or perl script, you can automate the download and install process for users if you like. Alternatively, they can download the thin client at no cost from the Micro Focus Web site, http://www.microfocus.com/support/downloads/. Once they have the thin client installed, they can visit your Web site and click a link to invoke your application.

Thin client users always have the option of executing the acuthin command with an Internet server or IP address as part of the command parameters. acuthin can launch programs on any server in a TCP/IP network, including the Internet. The only components required on the client in this case are the thin client software and an Internet connection. Users don't even need to have a Web browser.

With any of these thin client options, all application processing is performed on the server. Usually, data access is considered local because the data resides on the same server machine as the application. If you want to keep data on a different server in a multi-tiered configuration, you can combine the thin client with our AcuServer® technology. Please note that although the thin client supports only Windows clients, it gives access to both Windows and UNIX servers running the AcuConnect® application server software.

Parent topic: Deploying ACUCOBOL-GT Applications on the Web


COBOL CGI Interface

Perhaps you want customers or users to run your applications by clicking a link on your Web site, but you don't want to require anything special of the user's machine (for instance, the presence of any ACUCOBOL-GT runtime, be it a standard, thin client, or Web runtime). In this case, you can create a new interface to your application using a markup language such as HTML, WML, or XML. With a Web interface, your application can be interpreted directly by the user's HTTP browser or mobile device, and the processing logic can remain in COBOL on the Web server.

In this scenario, you create your Web interface using one of many popular authoring tools. Then you write a CGI program that can read CGI variables submitted by the client to the server. This program can launch your COBOL application or it can be a COBOL program itself. You can write it using ACUCOBOL-GT or any other language you choose. If you write the program in ACUCOBOL-GT, you do not have to UNSTRING the CGI variables in the program, because ACUCOBOL-GT takes care of this for you through special "IS EXTERNAL-FORM" syntax.

By default, your CGI program reads and writes HTML content for use in standard HTTP browsers and mobile devices. But using configuration variables, you can associate your program with the MIME content type for WML so that data can be displayed on WML-based devices as well.

Once you build a Web front end and write a CGI program, your customers or users can then visit your Web site and gain instant access to your COBOL application running on the server.

Note that CGI programs are inherently stateless–that is, they do not store information about previous browser actions. If you require a persistent connection to the browser, you can achieve this by adding pointers and cookies to your CGI program, or you may choose a different method.

This option runs on any platform where ACUCOBOL-GT runs, but it also requires the most coding. You can employ the CGI method wherever a user interface via DISPLAY/ACCEPT statements is not used. This includes batch processes, processes that use socket routines to communicate with an external UI, BEA® Tuxedo® processes, and processes launched via AcuConnect in distributed processing mode, to name a few.

Parent topic: Deploying ACUCOBOL-GT Applications on the Web


Web Runtime

Another way to give end users access to your applications on the Web is to provide runtime services through the ACUCOBOL-GT Web Runtime.

Using this approach, you set up a Web site and embed a link to your ACUCOBOL-GT application. You embed the Web runtime in the link as well by designating the URL of Acucorp's download center in your HTML coding. Users can then visit your site and click a link to launch the program. If the Web browser detects that users do not yet have a runtime installed on their machine, it automates the install process, with the users' permission, and then launches the COBOL program locally.

The Web runtime is available only on supported Windows machines, but it gives users access to programs or data hosted on other platforms using AcuServer and AcuConnect.

The ACUCOBOL-GT Web Runtime is geared for Microsoft Internet Explorer environments. It relies on ActiveX technology and does not run on any current versions of Netscape.

Parent topic: Deploying ACUCOBOL-GT Applications on the Web


Internet Helper Application

If your users already have a licensed copy of the ACUCOBOL-GT runtime on their machine and they want to be able to access COBOL applications on a Web site, one way to do this is to set up their runtime as an Internet helper application or viewer inside their browser. Helper application and viewer are browser terms referring to user-based software that can read and process files of a given type. Netscape uses the term "helper application" to refer to such software. Microsoft Internet Explorer uses the term "viewer."

Because the ACUCOBOL-GT runtime has the ability to read and process COBOL objects, it allows users to run COBOL programs that they encounter when browsing your Web page. The main difference between this and a standard runtime configuration is that your COBOL object files are on the Web server and transmitted to the client machine via HTTP.

Keep in mind that the helper application/viewer is a full-featured runtime; it has full access to your users' machines, including system calls, memory, disk and network access. Therefore, it should be used only with programs from trusted sources, or in conjunction with the Internet security you have in place.

Parent topic: Deploying ACUCOBOL-GT Applications on the Web


Web Browsing from COBOL

The ACUCOBOL-GT Development System includes an Internet-related Web browser graphical control. The Web browser control lets you:

  • Facilitate seamless Web browsing from your COBOL application.
  • Display Web pages containing HTML, scripting, ActiveX controls, and Java applet content.
  • Display HTML pages distributed with your COBOL application.
  • Include a variety of graphical and multimedia file types in your COBOL application.
  • Invoke e-mail, telnet, and FTP services from your COBOL application.
  • Display word processing, accounting, or presentation documents from your COBOL application.
  • Display Windows objects such as folders and files from your COBOL application.
  • Display Windows dialog boxes such as "Print," "Print Preview," and "Page Setup," allowing users to print the contents delivered by the control.
  • Display the Windows "Save As" dialog box allowing the user to save the current control content to a file.
  • Perform "Select All" and "Copy" clipboard operations.

ACUCOBOL-GT's Web browser control is used in the same manner as other graphical controls in ACUCOBOL-GT, except it opens a resource such as an HTML page, graphical image, video, audio, e-mail program, file folder, or any other resource that a Web browser can open. When you include the Web browser control in your source code, your application launches Microsoft Internet Explorer on your user's machine and displays the resource you specified.

For the control to work, your users must have Microsoft Internet Explorer Version 4.0 or later on their machine.

Parent topic: Deploying ACUCOBOL-GT Applications on the Web


COBOL Web Services

With extend technologies, you can expose your COBOL applications as Web services for use in Web services deployments. Java technologies are discussed in Working with Java Technology. .NET technologies are discussed in Working with .NET Assemblies.

  • Providing Web Services from COBOL
  • Consuming Web Services
Parent topic: Deploying ACUCOBOL-GT Applications on the Web


Consuming Web Services

To enable a COBOL program to consume a Web service, we provide the C$JAVA library routine and the NETDEFGEN utility.

If the Web service is running on J2EE, the Java programmer packages the WSDL from the Web service in a WAR file with all the necessary resources including a Java client proxy, and the COBOL programmer invokes the service by calling the C$JAVA routine and naming the proxy as a USING parameter.

If the Web service is running under .NET, the .NET programmer generates a client proxy from the Web service and incorporates that proxy into a .NET assembly. The COBOL programmer then uses NETDEFGEN to create a COBOL COPY file for the proxy. The programmer then copies the COPY file into the COBOL program and uses the CREATE, DISPLAY, INQUIRE, and MODIFY statements to access the Web service methods and events.

Parent topic: COBOL Web Services


Other Internet Solutions

Not all Internet deployments involve Web browsers and HTTP. Our file server, file interface, and/or application server technologies support IP addresses and URL syntax so that you may leverage the Internet in virtual LAN/WAN configurations and broaden the reach of your legacy assets in a highly controlled setting.

  • AcuServer can be used to provide access to Vision data over the Internet.
  • AcuConnect can be used to provide access to server-resident COBOL programs over the Internet, even programs that are distributed across a number of different servers.
  • AcuXDBC® can be used to provide access to ODBC data over the Internet. AcuXDBC is combined with AcuXDBC Server for remote processing of SQL requests.
  • Acu4GL® and AcuSQL® can be used to provide access to relational databases over the Internet.
  • AcuXML can be combined with AcuServer to provide access to XML documents over the Internet.

All extend technologies are designed to work in TCP/IP networks. Because the Internet is just a large TCP/IP network, you can use these same proven technologies in Internet deployments.

Parent topic: Deploying ACUCOBOL-GT Applications on the Web


Accessing ACUCOBOL-GT Applications from Mobile Devices

  • Overview of Mobile Computing
  • Key Mobile Terminology
  • Mobile Platform Trends
  • Mobile System Design Issues
  • Service-oriented Architecture (SOA)
  • Methods for Mobile Computing
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


Overview of Mobile Computing

What do we mean when we use the term mobile computing? Is it sending a short text message via a mobile phone? Having wireless access to the Internet from a PDA? Connecting to the office computer system from a hotel room using a laptop? Using a barcode reader to collect data in the field? Mobile computing is all these things, and more. The exact definition varies with individual needs.

We can consider the concept of mobile computing as computers on the road: a device/system combination that you use to conduct business at a location removed from your office desktop machine. The remote location can be a hotel room or branch office, or it can be your office at home. Your computing needs can range from a simple query or "look-up" function from a handheld device to obtain important information, to a portable office system with real-time communication with the home office. For example, a field worker might use a handheld device to collect data, such as water or power usage or the current inventory level for a particular item. Or after finishing one job, a plumber might use a handheld device to identify his or her next service stop.

It's also possible that "mobile" employees aren't leaving your office building at all. So-called "campus workers" can use a notebook or tablet to continue working when they are not actually sitting at their desks. They can, for example, be working in the lunch room or taking notes in a meeting.

We see that mobile computing comprises an array of activities and devices. This chapter explores some of the concepts you'll need to know about as you consider how to take advantage of mobile systems. We'll start with definitions of some basic mobile technology terms and a description of the existing infrastructure. Then we'll discuss current trends in mobile platforms and some mobile system design issues. Finally, we describe a sample mobile system and some helpful methods for achieving mobile computing.

Parent topic: Accessing ACUCOBOL-GT Applications from Mobile Devices


Key Mobile Terminology

Mobile computing today is associated with an interesting lexicon that seems to expand on a daily basis. WAP, WML, TCP/IP, 3G, WiFi–what do these acronyms mean and how do they apply to the business of mobile computing?

  • Languages
  • Protocols
  • Wireless Communication Standards
Parent topic: Accessing ACUCOBOL-GT Applications from Mobile Devices


Languages

Hypertext Markup Language (HTML) is the familiar language used to display Web pages. A subset of HTML, Wireless Markup Language (WML) is specifically designed to present Web-based information on small handheld devices like mobile phones.

Extensible Markup Language (XML) is a language for documents that contain structured information. You can define custom tags and the structural relationships between them based on the content of your document. Because an XML document contains information about itself, it is an excellent vehicle for transporting data from one location to another, for example, between applications or between organizations.

Parent topic: Key Mobile Terminology


Protocols

Several sets of protocols determine how voice and data are transmitted over short and long distances. They include protocols for software, hardware, and networks.

The standard protocol governing World Wide Web communications is the well-known Hypertext Transfer Protocol (HTTP), which supports HTML for Web page display. For wireless devices like mobile phones, the Wireless Application Protocol (WAP) controls your access to information on the Internet. WAP supports WML for display.

Bluetooth technology (named for the tenth century Danish king who unified Denmark) allows wireless, radio-based communication between devices. Bluetooth is a general-purpose standard that targets communication between technical "gadgets." For example, it could connect your laptop to a major kitchen appliance like your refrigerator, if you so desired.

Transmission control protocol/Internet protocol (TCP/IP) is the layered network protocol that has become the global standard for system-to-system communications. It is designed to allow dissimilar systems to transmit data to one another.

Parent topic: Key Mobile Terminology


Wireless Communication Standards

Mobile communications are managed by wireless networks, which have system standards that govern the communications process. Each succeeding generation of wireless standards has been developed to increase bandwidth and speed of data transmission as well as the quality of voice transmission. In this section, we present some background information about how these standards have evolved.

  • The Past and the Present
  • The Future
  • 3G Status
Parent topic: Key Mobile Terminology


The Past and the Present

Nordic Mobile Telephone (NMT) and the Advanced Mobile Phone System (AMPS) were among the first standards for analog mobile phone systems. Both are first-generation, or 1G, technology standards.

GSM, named for the group that developed it (Groupe Speciale Mobile), is another wireless standard for mobile communication. Originally developed as a common digital wireless standard for Europe, GSM is second-generation, or 2G, technology. The GSM standard is based on Time Division Multiple Access (TDMA), which divides a radio frequency into time slots and then allocates each slot to a user.

Whereas TDMA has been the standard used in Europe, Code Division Multiple Access (CDMA) is the standard used in the United States. CDMA uses a digital encoding system to spread the signal for a call across a range of frequencies. This technique allows more users to share the network simultaneously.

The General Packet Radio Service (GPRS) uses GSM to handle data transmission. This standard is known as 2.5G technology. GPRS is a packet-switching technology, which means that users are always connected.

The 2.5G technology is currently the most widely used standard for mobile communications. Mobile devices using this standard can provide voice and data transmission, along with Web browsing capabilities. These types of phones can also transmit e-mail. Networks using the 2.5G standard have been implemented worldwide.

WiFi, short for Wireless Fidelity, is more commonly known as the 802.11b standard for wireless communication. WiFi provides short-range wireless connectivity (approximately 150 feet) between devices, primarily for computer networks. So-called "WiFi zones" may be located in airports, hotels, and even warehouses in order to facilitate wireless communications.

Parent topic: Wireless Communication Standards


The Future

The Universal Mobile Telecommunications System (UMTS), also known as 3G, is a specification for the third generation of mobile communications. It is based on an enhanced version of CDMA called Wideband CDMA (W-CDMA).

Perceived as the successor to 2.5G technology, the 3G systems are intended to provide higher data transfer rates than GPRS and are based on packet-switching networks that are "always on." Unlike GPRS, the UMTS standard provides a dynamic connection, so that the bandwidth varies depending on the requirements, providing a more efficient utilization of the network.

An enhancement to GSM networks is EDGE, which stands for Enhanced Data rates for Global Evolution. This technology is complementary to the GPRS network upgrade to GSM and might be considered a "bridge" between the 2.5G GPRS and future 3G technologies. EDGE allows increased high-speed data transfer capabilities.

CDMA2000 wireless technologies build on CDMA to provide improved transfer rates for users. Evolution Data Optimized (EV-DO) technology is expected to provide high-speed data transmission, whereas Evolution Data Voice (EV-DV) would allow increased network capacity for voice transmissions and higher speeds for data transfers.

For enhanced wireless high-speed connectivity technology, the next step may be WiMAX. WiMAX will operate like WiFi, but is expected to provide high-speed connectivity from 1-10 miles, a much larger range than that in your neighborhood WiFi hot spot. WiMAX could be the key to Internet connectivity that covers entire communities without the huge investment in cable or phone networks.

Parent topic: Wireless Communication Standards


3G Status

A mobile device that uses the 3G standard with its higher frequency and larger bandwidth can be expected to provide users with more capabilities and much faster speeds for their mobile communications. The first applications available for 3G devices have been primarily entertainment-oriented rather than for business purposes. With phones that use 3G technology, users can access video services covering the latest news and sporting events and make video phone calls. At this time, however, 3G networks are implemented only on a limited basis worldwide, and compatible mobile devices are expensive and in short supply. Recent trends indicate that Europe may adopt a different 3G standard (UMTS) than Asia and North America (CDMA, EV-DO), setting the stage for global network incompatibilities. Expected high throughput rates have not been proved in reality, but the widespread rollout of this type of network is still eagerly anticipated by users who want faster, feature-rich mobile communications.

Parent topic: Wireless Communication Standards


Mobile Platform Trends

With the proliferation of devices and operating systems in the market today, possible combinations for mobile systems seem limitless. Today, mobile computing technologies are evolving at an incredibly fast pace. From handheld devices like Personal Digital Assistants (PDAs) and intelligent mobile phones to solutions involving laptop computers and high-speed, wireless Internet connections–how do you begin to choose the solution that best fits your needs?

Research into current industry offerings reveals three major platforms competing for dominance in the mobile device market–Pocket PC, Palm, and Symbian. Each platform, in turn, uses its own operating system–Windows Mobile OS, Palm OS, and Symbian OS, respectively. Each has its own unique development and runtime environment. Because none of these players has achieved industry dominance and standards in this area are lacking, your choice among these three options is not clear-cut. And if you want a single application to run on all three devices/operating systems, you need third-party middleware to accomplish the interoperability.

But the basic question is, can a device running a non-COBOL front-end application communicate with your back-end COBOL program? The fact is, with a carefully designed system architecture for your information system, any one of these platforms/operating systems can be a viable front end to your legacy COBOL application. If you already have a particular preference for mobile device and operating system, the choice is easier. Odds are that it can connect to and run your COBOL application.

Parent topic: Accessing ACUCOBOL-GT Applications from Mobile Devices


Mobile System Design Issues

Several important elements must be carefully researched during the design phase of a mobile computing system. User interface functions, security issues, degree of connectivity, and record-locking requirements are some topics that should be considered part of a complete system design. The following sections provide more detail in these areas.

  • User Interface
  • Security
  • Degree of Connectivity
  • Record Locking
Parent topic: Accessing ACUCOBOL-GT Applications from Mobile Devices


User Interface

User interface design for a mobile device involves several issues. You should consider exactly what tasks your users need to accomplish. Are they monitoring inventory, recording sales, or inquiring about a customer's current credit status? Because the screen size is much smaller than a standard desktop computer, you cannot simply transfer your application from the desktop to a mobile device. Concentrating on specific user tasks can help you narrow down the information your screen should contain.

Ease of use is an important consideration in interface design. For example, keyboards on mobile devices are quite small and may be very difficult to use in the field. You might consider allowing users to choose options via check boxes and radio buttons in the device display area. If you still require an on-screen keyboard, be aware that it occupies valuable screen space.

Application operating rules are also different on mobile devices compared with desktop operating systems. For example, a PDA operating system allows only one application to be active at any one time. The user controls which application is active, and the system makes the previously active program dormant.

Parent topic: Mobile System Design Issues


Security

When you consider security for wireless operations, you need to cover three main areas–device, application, and communications security.

Any valuable company data that resides on your mobile device must be protected. The small size of a mobile device increases the chances of its being misplaced or stolen. Device security can be achieved via the use of power-on authentication functions that are usually available on PDA devices. This password feature can protect data by ensuring that only the device's owner can access data. Another possibility is password protection for such mobile device functions as the infrared communications feature. You might decide to encrypt the data on your mobile device so it is unreadable to anyone who does not have an appropriate algorithm and key.

As on desktop systems, data on a mobile device can be corrupted. Although less common than on desktop systems, viruses can still attack and compromise data on a wireless device. Third-party anti-virus software can provide needed protection for the data stored on your mobile device.

Securing your application can involve a variety of user password authentication and permissions protections. Your application can require a password or other user authentication before it executes, or the database may require a password for access.

Security for your communications is essential for wireless systems. The nature of wireless networks can leave them more vulnerable to attack from external sources than wired solutions. Wireless access points reside in an unlicensed frequency band that can be easily breached by wireless hackers. Secure Sockets Layer (SSL), a secure protocol based on TCP/IP, uses key encryption and digital certificates to encrypt communication. A Virtual Private Network (VPN) can also provide authentication and encryption features to protect communications.

Parent topic: Mobile System Design Issues


Degree of Connectivity

Another question is how your users are connected to the network. Does your application require users to be always connected, mostly not connected, or somewhere in between?

Some applications may require a constant connection to the network in order to function properly. This architecture is sometimes called thin client. Depending on a constant wireless connection can be risky. The technology is still not completely reliable, with long distances or other obstacles that can interrupt an important data transfer.

Will your users collect data in the field on a mobile device and be connected to the network only when they want to download the data to a server? In this situation, a device needs to allow local data storage until it can be "cradle-connected" to the server.

A mobile device can also store data locally for an application that may or may not be connected to the network at any point in time. With this smart client architecture, the application can still function and a user can access data with or without a network connection.

Parent topic: Mobile System Design Issues


Record Locking

Record-locking issues require careful consideration in wireless operations. Business applications rely heavily on record locking to ensure consistent data quality and to guard against conflicting updates by multiple users, a concept known as concurrency. Unreliable wireless connections can complicate record-locking issues. Mobile solutions may generally support three types of concurrency–destructive, optimistic, or pessimistic concurrency.

With destructive concurrency, the last update to a record "wins." The application does not attempt to settle any update conflicts, giving it no control over data updates. This situation can leave your data in an inconsistent state if updates aren't completed in the correct order.

Optimistic concurrency assumes that no data update conflicts exist. When a user updates a data record, the original record is checked to see if it has changed since the user accessed the record. If a conflict is detected, the user is given the option to overwrite the record. If no change is detected, the record is overwritten.

Pessimistic concurrency is probably the most familiar version of record locking. This concept assumes a high probability of data update conflict. A record selected for update remains locked until the user writes the update to the database. Accomplishing this form of concurrency with desktop network systems is relatively straightforward. For a mobile application, the process is a bit more complicated. In a mobile environment, we accomplish this by having the application maintain lock information in individual records or in a lock table. This solution is not foolproof. If the data is also available via ODBC or another data source, these locks do not prevent other users from accessing and updating data.

Parent topic: Mobile System Design Issues


Service-oriented Architecture (SOA)

What we need to achieve our mobile computing solution is a technology that allows us to integrate our COBOL back-end application with a non-COBOL front end in a wireless environment. A business application designed with service-oriented architecture (SOA) is well suited to this task. What is SOA?

SOA is a methodology for developing applications with standards-based interfaces that accept specific inputs and deliver expected outputs. It uses the simple design principles from various structured programming methods. SOA has emerged in recent years as a logical way for organizations to keep and reuse existing legacy applications while integrating them with new technologies.

With SOA, the front-end program can be written in Java/JSP, VB/ASP, Delphi, XML, HTML, or a variety of other languages. Your front-end operating system can be Windows Mobile, Palm, or Symbian. This platform-independent solution provides insurance for your back-end architecture against any major changes in language or platform on the front end. Best of all, you can leverage your proven COBOL back-end application in a modern, wireless environment.

Parent topic: Accessing ACUCOBOL-GT Applications from Mobile Devices


Methods for Mobile Computing

You can use the following ACUCOBOL-GT technologies as part of a mobile computing strategy:

  • ACUCOBOL-GT COM Server
  • ACUCOBOL-GT Common Gateway Interface (CGI) language extensions
  • ACUCOBOL-GT runtime and Short Message Service (SMS) processing

The following sections provide brief descriptions of these technologies.

  • ACUCOBOL-GT COM Server
  • ACUCOBOL-GT CGI Language Extensions
  • ACUCOBOL-GT Runtime and Short Message Service (SMS) Processing
Parent topic: Accessing ACUCOBOL-GT Applications from Mobile Devices


ACUCOBOL-GT COM Server

The ACUCOBOL-GT COM Server is a COM object that contains the ACUCOBOL-GT Windows dynamic link library (DLL). It allows your ACUCOBOL-GT application to be called by a program written in any COM-compliant language or by a third-party, off-the-shelf package that includes a COM interface for a mobile device. The front-end application connects to the ACUCOBOL-GT COM Server via the TCP/IP network. Your back-end application is in ACUCOBOL-GT. This deployment can be a handy solution when you want to transfer data to a server, which processes the raw data into useful information like summary reports and inventory lists.

Parent topic: Methods for Mobile Computing


ACUCOBOL-GT CGI Language Extensions

With the ACUCOBOL-GT runtime, users who need to access query or look-up services have a way to quickly and easily obtain important information. The front end consists of WML- or HTML-compliant software like a mobile device browser that can communicate via CGI with a Web server. The communication link is TCP/IP. On the back end, you have your COBOL application, a COBOL-based CGI program for interfacing between the mobile device and the COBOL application, and the ACUCOBOL-GT runtime. You can use this technology for applications in which you initiate a request for information, for example, up-to-the-minute currency exchange rates or the status of product shipments.

Parent topic: Methods for Mobile Computing


ACUCOBOL-GT Runtime and Short Message Service (SMS) Processing

The SMS system of text messaging is gaining in popularity as the use of mobile phones increases worldwide. An ACUCOBOL-GT application can send and receive SMS text messages by using the C$SOCKET library routine to communicate over TCP/IP with a telnet service available through a mobile service network provider. With this technology, your ACUCOBOL-GT application can be written to send an alert message to your mobile device, for example, when inventory for a particular item falls below a specified level or when report generation is completed.

Combining this solution with the ACUCOBOL-GT CGI option opens the door to an even more interesting possibility. For example, when SMS alerts you to that change in inventory, and your mobile device supports WAP, our CGI extensions allow access to a supplier's Web page so you can replenish your stock.

Parent topic: Methods for Mobile Computing


Working with Transaction Processing Systems

  • Introduction
  • What Is Transaction Processing?
  • IBM CICS
  • Working with the IBM CICS Transaction Gateway
  • Working with IBM TXSeries CICS
  • Working with UniKix Mainframe Rehosting Software
  • Working With BEA Tuxedo
  • Background Debugging Options
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


Introduction

Because much of the world's business data is processed by COBOL, and billions of COBOL transactions occur daily, it's important for enterprise-level COBOL applications to interoperate smoothly with online transaction processing (OLTP) software. Transaction processing software furnishes applications with secure access to one or more data sources, both within local networks and across wide-area networks or the Internet. Regardless of the individual transaction processing package, the key features of this type of software are its ability to maintain data integrity, its scalability, and the security mechanisms it provides.

For more information on the use of ACUCOBOL-GT with IBM TXSeries® CICS or Sun™ Mainframe Rehosting environments, please contact your Acucorp Sales Professional.

Parent topic: Working with Transaction Processing Systems


What Is Transaction Processing?

A transaction is unit of work consisting of one or more requests or updates to a system. A transaction is successfully completed with a commit command that finalizes all changes. If the transaction is not successful, a rollback command is used to undo changes and return the system to its previous state. A transaction, therefore, processes either all or none of its changes.

Consider, for example, the common transaction of withdrawing money from a checking account. The customer enters the request at an automated teller, causing a program to check the availability of funds, dispense the money, and update the balance of the user account. Each step must be completed before a successful transaction can occur.

Transaction processing software keeps track of each part of the transaction, ensuring data integrity by verifying that the transaction has been successfully completed before performing any updates.

The four basic properties of a transaction are known as the ACID properties:

  • Atomicity – A transaction as a whole is either done or undone. If a transaction involves more than one discrete piece of information, all pieces are committed or none are.
  • Consistency – A transaction leaves the data in a valid state. Either a change has been committed and the data has a new valid state, or no change occurs and the data returns to its previous valid state.
  • Isolation – Each transaction occurs independently of other transactions taking place in the same environment.
  • Durability – The effects of a transaction are permanent, so that even in the event of a system failure, upon restart, the data is available in its correct state.
Parent topic: Working with Transaction Processing Systems


IBM CICS

The IBM Customer Information Control System (CICS) is a widely installed transaction processing software system. A large number of transaction processing requirements running on mainframes today are handled by CICS systems. IBM designed CICS to support large numbers of terminals and a large transaction volume with fast and consistent response time. CICS can be described as an interface between CICS applications and the operating system.

CICS or CICS-compatible environments are now available for many platforms, including server support for OS/2, AIX, Windows NT, MVS/ESA, AS/400, HP-UX, Digital OSF/1, Siemens SINIX, Sun Solaris, and other UNIX platforms.

In supported environments, ACUCOBOL-GT offers the following features:

  • Dynamic loading of shared libraries, including EXTFH libraries used for batch programs, so you can customize your environment by simply specifying an environment variable
  • Debugging of CICS COBOL programs with the ACUCOBOL-GT runtime debugger
  • The ability to interoperate with a wide variety of utilities that help you replicate mainframe functionality on open systems, such as external sort modules and utilities to handle complex calculations
Parent topic: Working with Transaction Processing Systems


Working with the IBM CICS Transaction Gateway

The Windows versions of the ACUCOBOL-GT runtime support calls to the IBM CICS Universal Client Interface for Windows. The runtime attempts to automatically load the CICS dynamic link library (DLL) if any subroutine beginning with "CICS" is called. If the DLL is available and loadable, the CICS function is called using the standard DLL call interface.

In some cases, the IBM CICS Transaction Gateway product may include a ".lib" file instead of a DLL. When this occurs, the Windows runtime DLL must be relinked to include the ".lib" file in order to access CICS functions. The relinking process is described below.

Whether you are working with a DLL or ".lib" file, a properly configured ACUCOBOL-GT runtime allows you to access IBM applications on a mainframe or other host, and to use ACUCOBOL-GT graphical interface capabilities as a front end to your IBM COBOL applications.

Accessing IBM Applications

To take advantage of these capabilities, you must install the appropriate combination of the CICS Transaction Gateway and CICS Universal Client Interface on your machine and configure it according to the IBM documentation. IBM documentation includes specific information on CICS and sample COBOL programs that you can use to test your client/server connection.

  • Including the Transaction Gateway Routines in the Runtime
  • Connecting to CICS Applications
Parent topic: Working with Transaction Processing Systems


Including the Transaction Gateway Routines in the Runtime

For Windows systems, IBM may supply the Transaction Gateway library as a ".lib" file rather than a DLL. As mentioned earlier, the Transaction Gateway routines must be linked into the ACUCOBOL-GT runtime. The process uses the direct call method described in Working with C and C++ Programs.

To link the Transaction Gateway library into "wrun32.dll", you must:

  1. Include the following lines in the file "direct.c", located in the acugt\lib folder of your ACUCOBOL-GT installation.
    extern short CICS_ExternalCall();
extern short CICS_EciListSystems();
struct DIRECTTABLE LIBDIRECT[] = {
   { "CICSEXTERNALCALL", FUNC CICS_ExternalCall, C_short },
   { "CICSECILISTSYSTEMS", FUNC CICS_EciListSystems, C_short },
   { NULL, NULL, 0 }
   };
  2. Open Visual Studio .NET and load the solution file "wrun32.sln", located in the acugt\lib folder.
  3. Open the Project/Properties interface, expand the Linker folder, and do the following:
    1. Select Input, then add the name of the Transaction Gateway library, "cclwin32.lib", next to "Additional Dependencies".
    2. Select General and add the path to "cclwin32.lib" on the "Additional Library Directories" line. For example:
      C:\Program Files\IBM\IBM CICS Transaction Gateway\lib
  4. On the main menu bar, select Build/Rebuild Solution. This command recompiles all of the required files, including "direct.c", and links "cclwin32.lib" into "wrun32.dll".
Parent topic: Working with the IBM CICS Transaction Gateway


Connecting to CICS Applications

If you are using the CICS client, you must compile your ACUCOBOL-GT application with the "-Dw32" and "-Da4" options. These are data format switches. The runtime does not require any special switches to use the IBM library routines or COPY files once you have compiled with the correct options. You must also set the USE_CICS runtime configuration variable to a value of "1".

Note:

Compiling with any other "-D" flags could cause problems in compilation, so use them with caution.

ACUCOBOL-GT supports the External Call Interface (ECI) portion of CICS. The ECI allows a non-CICS application to call a CICS program that resides on a CICS server. The non-CICS application does not issue any CICS commands itself; these commands are issued by the called program running on the server. The call is no different from any other call built into a library or COBOL program. The CICSEXTERNALCALL ECI call can be used to:

  • Call programs (synchronously or asynchronously).
  • Request STATE information (synchronously or asynchronously).
  • Check on previous asynchronous calls using a number of GET REPLY options.

ACUCOBOL-GT also supports the CICSECILISTSYSTEMS call, which is used to determine the servers available to receive CICSEXTERNALCALL requests.

Parent topic: Working with the IBM CICS Transaction Gateway


Working with IBM TXSeries CICS

Based on the solid foundation of mainframe CICS, the IBM TXSeries products allow you to build on technologies that offer interoperability with mainframe systems and the flexibility to integrate with modern programming models. TXSeries CICS provides an application environment for running COBOL programs in high-volume, OLTP systems. Because TXSeries supports the CICS API and SPI (Systems Programming Interface), many CICS application programs can run on TXSeries without any changes.

The TXSeries CICS platform includes:

  • A wide range of supported relational database managers
  • Full interoperability with other CICS-compatible environments
  • Familiar EXEC CICS APIs
  • Integration with modern desktop environments
  • Easy access to enterprise-wide e-business applications
  • Options to extend existing investments while taking advantage of new technologies like the IBM WebSphere® platform
  • Communication with back-end CICS and the Information Management System (IMS)

As with mainframe CICS, TXSeries launches a transaction and then initializes the entire operating environment, performing virtually all of the data access and communication services, launching the application programs, and handling calls from one program to another.

For more information on using ACUCOBOL-GT with TXSeries CICS, please contact your Acucorp Sales Professional.

For additional information on TXSeries, refer to the IBM Web site at http://www.ibm.com/software/htp/txseries/support.

  • How TXSeries CICS Works with ACUCOBOL-GT
  • Modernizing Applications
Parent topic: Working with Transaction Processing Systems


How TXSeries CICS Works with ACUCOBOL-GT

With the integrated TXSeries and ACUCOBOL-GT environment, you can take advantage of features such as:

  • A prelinked version of the ACUCOBOL-GT runtime system shipped with TXSeries that eliminates the manual build process as you configure and deploy on TXSeries CICS
  • A range of security options that address processing requirements in the distributed environment, including CICS-based security for resource and transaction access, or open systems models such as the Distributed Computing Environment (DCE)
  • Communication between TXSeries and the mainframe CICS TS via the standard CICS Intersystem Communication (ISC) facilities. With this feature, you can stage your migration process over time to help reduce risks and extend strategic ACUCOBOL-GT applications as you migrate them.

The existing mainframe process to compile and deploy COBOL programs remains largely unchanged: CICS programs are precompiled in TXSeries to translate EXEC CICS syntax to COBOL verbs. Programs are then compiled with the ACUCOBOL-GT compiler. TXSeries initializes the runtime, waits for requests from clients, and processes those requests, allowing ACUCOBOL-GT programs to communicate with databases and other programs or clients, and to display screens using CICS services.

Parent topic: Working with IBM TXSeries CICS


Modernizing Applications

After you move your COBOL CICS applications to the TXSeries environment and ACUCOBOL-GT, you have extensive options for modernization, such as:

  • Invoking CICS programs through the ECI to perform back-end processing for Web services.
  • Increasing developer productivity with the AcuBench® integrated development environment from Acucorp, which extends and enhances the ACUCOBOL-GT compiler and runtime system with a powerful suite of GUI-based development tools.
  • Updating the user interface for migrated applications by adding .NET clients to invoke CICS programs through the ECI.
Parent topic: Working with IBM TXSeries CICS


Working with UniKix Mainframe Rehosting Software

UniKix Mainframe Rehosting Software, from Clerity Solutions, enables customers to rehost legacy mainframe applications on open systems platforms such as IBM AIX, HP-UX, Sun Solaris, and Linux, making it feasible to replicate mainframe functionality on open systems without needing to rewrite applications in a new language. Two products, Unikix Transaction Processing Environment (TPE) and UniKix Batch Processing Environment (BPE), together provide an environment for running CICS and batch applications on open systems.

Similar to mainframe CICS, Unikix TPE software launches a transaction and then initializes the entire operating environment, handling all the data access, communication, and calls between programs. UniKix also provides several facilities to share resources and data between UniKix regions and IBM CICS systems. An IBM CICS mainframe system appears as a remote region to UniKix through Intersystem Communication (ISC).

UniKix BPE software provides a complete batch job execution facility. The software is composed of independent processes that manage and schedule batch programs according to configuration parameters, such as start time and job priority. UniKix provides functionality to allow administrators to assign job attributes, change job attributes, and determine the current status of a job.

ACUCOBOL-GT supports CICS mainframe logic running in the UniKix TPE and UniKix BPE environment in a number of ways:

  • Dynamic loading of shared libraries, including EXTFH libraries used to run batch programs
  • Interoperability with a variety of utilities that replicate mainframe functionality, such as external sort modules and utilities that handle complex calculations
  • Debugging of CICS COBOL programs using the ACUCOBOL-GT runtime debugger
  • Familiar EXEC CICS APIs
  • Integration with modern desktop environments
  • Easy access to enterprise-wide e-business applications

For more information on using ACUCOBOL-GT with UniKix, please contact your Acucorp Sales Professional.

Parent topic: Working with Transaction Processing Systems


Working With BEA Tuxedo

ACUCOBOL-GT developers using the BEA Tuxedo platform for distributed transaction processing and message-based application development can create Tuxedo clients and Tuxedo services from ACUCOBOL-GT applications. Acucorp is certified for Tuxedo 9.1 on all supported platforms.

ACUCOBOL-GT and BEA Tuxedo can work together in either a distributed processing (client/server) environment or a thin client environment. In a distributed processing environment, the interaction occurs as shown in the following diagram:
ACUCOBOL-GT and BEA Tuxedo in distributed processing

In this environment, ACUCOBOL-GT interoperates with BEA Tuxedo using the same routines used to call C programs (COBOL-calling-C routines on the client and C-calling-COBOL routines on the server).

In BEA Tuxedo client/server distributed applications, the client requests the services of a server, which may have multiple services to provide, and the outcome of the request is returned to the client by the service. This architecture lets you divide application processing among multiple machines to optimize performance.

ACUCOBOL-GT and BEA Tuxedo can also work together using Acucorp's Thin Client technology. The thin client architecture uses AcuConnect®, Acucorp's remote application server, as shown in the following diagram:

ACUCOBOL-GT and BEA Tuxedo and thin client

Because BEA Tuxedo is based on C, the procedure for interfacing with Tuxedo is much like the procedure for interfacing with C routines in general. This means that external C variables need to be defined in "direct.c".

To prepare BEA Tuxedo to interface with ACUCOBOL-GT, C code must be added to the initialization and termination routines of BEA Tuxedo servers, then linked into the server using the BEA Tuxedo buildserver command. This process is further explained in the sections that follow.

  • Creating a Tuxedo Client Program
  • Creating a Tuxedo Server
  • Running Your Tuxedo Application
Parent topic: Working with Transaction Processing Systems


Creating a Tuxedo Client Program

A BEA Tuxedo client is a software module that collects a user request and forwards it to a server that offers the requested service. To create a Tuxedo client with ACUCOBOL-GT, you must relink the ACUCOBOL-GT runtime with the Tuxedo libraries. This section provides an overview of the steps necessary to create the Tuxedo client.

  1. Add the necessary Tuxedo calls to your ACUCOBOL-GT program. These calls–used to open and close resources, begin and end transactions, and support communication between clients and servers–are collected in a Tuxedo API known as the Application to Transaction Monitor Interface (ATMI). ATMI functions are described in the Tuxedo documentation.
  2. Recompile your program to establish it as a BEA Tuxedo client.
  3. Relink the ACUCOBOL-GT runtime on the client machine to include the BEA Tuxedo client libraries. The client libraries vary, depending on the BEA Tuxedo version and the platform you are using. To determine the Tuxedo client libraries used on a particular client, use the BEA Tuxedo command:
    buildclient -C -v -w
    where:
    C | Specifies COBOL compilation
    -v | Specifies that buildclient should work in verbose mode, displaying the compilation command on standard output
    -w | Specifies that the client is to be built using the workstation libraries; used only with the WSL

    Because the Tuxedo libraries are external C routines, link the libraries into the ACUCOBOL-GT runtime using the direct method of calling C routines described in.

  4. Set client environment variables.
Parent topic: Working With BEA Tuxedo


Creating a Tuxedo Server

A BEA Tuxedo server is a process that provides one or more services to a client. To build server processes, applications combine their service subroutines with a controlling program provided by the BEA Tuxedo system. Using ACUCOBOL-GT, this involves the following steps:

  1. Create and compile an ACUCOBOL-GT program that performs a specific task or service.
  2. Create a configuration file for the service to establish the identifiers
  3. Edit the "appinit.c" program (provided by BEA) to include runtime initialization and shutdown functions specific to ACUCOBOL-GT.

    The program calls the standard BEA Tuxedo ATMI initialization and shutdown subroutines tpsvrinit() and tpsvrdone(). The tpsvrinit routine calls two functions: tpopen opens the resource manager, and userlog posts a message that the server has started. The tpsvrdone routine also calls a tpclose function, which closes the resource manager

  4. Link the ACUCOBOL-GT runtime libraries into the controlling program provided by the BEA Tuxedo system.

    On UNIX/Linux servers, use the buildserver command, adding the ACUCOBOL-GT runtime libraries. Acucorp supplies a makefile that can be used to simplify this process.

    On Windows servers, relink the required Tuxedo libraries into the ACUCOBOL-GT runtime DLL, then issue the buildserver command with the ACUCOBOL-GT runtime libraries.

Parent topic: Working With BEA Tuxedo


Running Your Tuxedo Application

  1. Use the tmloadcf command to load the server configuration file.
  2. Use the tmboot command to boot the application.
  3. Run the client application using the runcbl command.
Parent topic: Working With BEA Tuxedo


Background Debugging Options

Various methods are available for debugging programs running in background mode in a transaction processing environment. These are described in in this section.

  • Background Debugging with an xterm
  • Defining Debugging Methods with "ADM_t"
Parent topic: Working with Transaction Processing Systems


Background Debugging with an xterm

With a properly configured X Window System, you can debug programs executing in background mode (with the "-b" runtime flag) by specifying that debugging I/O be sent to an xterm window on a specified X server. Use the following procedures:

  1. Set the DISPLAY environment variable on the system executing the program to point to a valid X server. This setting must be made before the runtime is invoked.
  2. Give the user executing the program rights to start an xterm on the specified X server.
  3. Modify the PATH environment variable on the system executing the program to point to the xterm directory.
  4. Add both the "-b" and the "d" flags to the runtime command line.

Use the standard debugging commands described in the rest of this section to manage your debug session.

Some users may want to debug with an xterm, but don't actually want to debug with the xterm executable because it doesn't have some of the abilities they need (such as displaying non-ASCII characters). You can specify the executable used to show the debugger on UNIX by setting the " XTERM_PROGRAM" runtime configuration variable.

Its default value is "xterm", but it can be set to any compatible program such as dtterm or kterm. The runtime executes this program when it tries to create the program for background debugging. Note that the runtime passes some arguments to this program, so this program must be able to execute with those arguments. These arguments are:

-title "title of the window"

-Sccn

-display Xserver-name

The "-Sccn" option allows the program to be used as the input and output channel for the runtime, and is absolutely required. Without this option, the program won't know to display data from the runtime.

Parent topic: Background Debugging Options


Defining Debugging Methods with "ADM_t"

All of the methods described in this section require support from the vendor of the transaction processing software. Please refer to your vendor's documentation for implementation details.

The a_cobol_info structure described in lib/sub.h includes the variable ADM_t debug_method, which describes which debugging method is used. The ADM_t type is described in lib/sub.h as an enumeration with the following values:

ADM_NONE | no debugging
ADM_XTERM | debug using a new xterm
ADM_TERMINAL | debug using an existing terminal through runcbl
ADM_THINCLIENT | debug using a waiting thin client

A separate char *debug_method_string setting depends on debug_method, as described in the following sections.

  • Using an xterm
  • Using a Terminal
  • Using the Thin Client
Parent topic: Background Debugging Options


Using an xterm

To debug using an xterm, first set debug_method to ADM_XTERM. If the DISPLAY environment variable is not set (or set incorrectly), set debug_method_string to point to your X server.

At execution time, the ACUCOBOL-GT runtime creates an xterm with the COBOL program stopped at the first line of the program.

Note that when the debugger starts, debugger settings are loaded from a file, and changes to settings are saved to that file as the debugger runs. By default, that file is given the name of the user who started the background or server process. In some environments, this could mean that multiple users of the debugger could share the same debugger settings. In such a case, breakpoints set or cleared by one user, for example, would affect what appeared in every other user's debugger window.

To avoid this potential problem, use the "acudebug.user" X resource to specify separate debugger settings files for different users. For example, in your "/.Xdefaults" file, you could add the line:

acudebug.user:  dsmith

Debugger settings would then be loaded from and saved to a file called "dsmith.adb".

See your X server resource database documentation ("man xrdb") for additional instructions on how to set X server resource properties.

Parent topic: Defining Debugging Methods with "ADM_t"


Using a Terminal

To debug using an existing terminal, use the following procedures:

  1. Set debug_method to ADM_TERMINAL, then set debug_method_string to the tty string on which you will execute runcbl.
  2. Log on to the UNIX machine that hosts the OLTP software and note the tty device used.
  3. On that machine, execute the runtime with the "--wait" flag. When this option is used, the runtime waits for the OLTP runtime to contact it.

    Note that if you use an additional command-line option, "--restart", the runtime restarts itself after each debugging session. This option is particularly helpful if you have transactions that require multiple COBOL programs and you want to debug all of them. Keep in mind, however, that if you use the "--restart" option, you must use the interrupt sequence (Ctrl+C) to terminate the runtime process when you are finished debugging.

  4. Execute the transaction you intend to debug, ensuring that the tty variable in your transaction debugging screen is set correctly. When the transaction executes, the runtime debugger appears on the terminal, allowing you to set breakpoints, step, evaluate variables, and so on. Once the OLTP runtime terminates the transaction, the terminal returns to a shell prompt.
Parent topic: Defining Debugging Methods with "ADM_t"


Using the Thin Client

Set debug_method to ADM_THINCLIENT. Set debug_method_string to client:port, where client is the host on which acuthin is executing and port is the port on which it is listening.

  • On the Windows Client
  • On the Server
Parent topic: Defining Debugging Methods with "ADM_t"


On the Windows Client

  1. Execute the acuthin command with "--wait [--port nnnn]" where nnnn is the desired port number. The thin client waits for a runtime to connect to it and behaves as the thin client normally does.

    In this mode, acuthin has an additional command-line option, "--restart". When you specify this option, the thin client restarts itself after each debugging session. If you have transactions that require multiple COBOL programs, you can easily debug all of them. Keep in mind, however, that when you use the "--restart" option, you must use the Windows Task Manager to terminate the thin client process when you have finished debugging.

  2. When the runtime debugger screen appears, you can debug your application with all the usual runtime debugger options.

Please note that in a transaction processing environment, if the server program attempts to connect to acuthin and acuthin is not running, the return value will be "7", which is COBOL_NONFATAL_ERROR.

Parent topic: Using the Thin Client


On the Server

If you are using a UNIX server, set the A_DEBUG_USING_THIN environment variable to a non-zero numeric value before the transaction server initializes the runtime. This tells the runtime to initialize in a mode which allows it to communicate with the thin client. After you enable this mode, you may not use terminal or xterm debugging.

In Windows server environments, the transaction runtime is automatically initialized in the mode that allows it to communicate with the thin client whenever it is run from within a transaction server (such as CICS).

Parent topic: Using the Thin Client


Working with Messaging Middleware

  • Support for IBM WebSphere MQ
  • Support for IBM Shared Libraries
  • Support for WebSphere MQ COPY Files
  • Connecting to WebSphere MQ Applications
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


Support for IBM WebSphere MQ

IBM WebSphere MQ, formerly MQSeries®, is messaging middleware designed to enable application integration. The WebSphere MQ products help business applications to exchange information across different platforms by sending and receiving data as messages. WebSphere MQ provides base messaging functions for servers and clients. It handles network interfaces, communications protocols, and workload distribution so that messages can be delivered promptly.

WebSphere MQ provides a consistent multiplatform, application-programming interface for coding messaging tasks. It supports many different platforms, including AIX, Compaq NSK, DOS, DYNIX/ptx, HP UX, Linux, Mac OS, MVS/ESA, NUMA-Q, OpenVMS Alpha, OpenVMS VAX, OS/2, OS/390, OS/400, Solaris, UNIX, Unisys 2200 Series, Unisys A Series, UnixWare, VM/ESA, VSE/ESA, Windows 2000, Windows 3.x, Windows 95, Windows 98, Windows NT, and Java.

ACUCOBOL-GT supports IBM WebSphere MQ in the following ways:

  • The Windows versions of the ACUCOBOL-GT runtime support calls to WebSphere MQ. When properly configured, the Windows runtime attempts to automatically load the WebSphere MQ DLL if any subroutine beginning with "MQ" is called. If the DLL is available and loadable, the WebSphere MQ function is called via the standard DLL call interface.
  • The ACUCOBOL-GT runtime for UNIX supports the shared libraries provided with IBM WebSphere MQ without relinking.
  • Both the Windows and UNIX runtimes use the COBOL COPY files supplied by IBM WebSphere MQ

Properly configured, the ACUCOBOL-GT runtime allows you to access IBM applications on a mainframe or other host, and to use ACUCOBOL-GT GUI interfaces as a front end to your IBM COBOL applications.

Parent topic: Working with Messaging Middleware


Support for IBM Shared Libraries

For UNIX and similar systems, the ACUCOBOL-GT runtime supports the shared libraries provided by IBM WebSphere MQ. Your programs running on UNIX can call platform-specific shared libraries to load them, and then call the necessary WebSphere MQ routines. You should not need to relink the runtime with the libraries in order to call the routines.

If you are in a UNIX environment, after installation of the client, identify the location of the shared libraries that contain the call routines. Confirm that the path matches the path you provided in the shared library environment variable. If the paths don't match, modify the variable as required.

On Linux, "libmqic_r.so" and "libmqmcs_r.so" are the shared libraries that IBM provides containing WebSphere MQ routines.

Windows-based ACUCOBOL-GT programs do not need to load the DLL file, "mqic32.dll", provided by IBM for accessing the routines.

Parent topic: Working with Messaging Middleware


Support for WebSphere MQ COPY Files

Both the Windows and UNIX runtimes use the set of COBOL COPY files that IBM provides with WebSphere MQ. These COPY files contain constant definitions and data structures used in the WebSphere MQ calls. Listed below are the IBM COPY files that our compiler can use:

cmqbol.cpy | cmqbov.cpy | cmqcnol.cpy | cmqcnov.cpy
cmqdhl.cpy | cmqdhv.cpy | cmqdlhl.cpy | cmqdlhv.cpy
cmqgmol.cpy | cmqgmov.cpy | cmqiihl.cpy | cmqiihv.cpy
cmqmd1l.cpy | cmqmd1v.cpy | cmqmdel.cpy | cmqmdev.cpy
cmqmdl.cpy | cmqmdv.cpy | cmqodl.cpy | cmqodv.cpy
cmqorl.cpy | cmqorv.cpy | cmqpmol.cpy | cmqpmov.cpy
cmqrmhl.cpy | cmqrmhv.cpy | cmqrrl.cpy | cmqrrv.cpy
cmqtmc2l.cpy | cmqtmc2v.cpy | cmqtml.cpy | cmqtmv.cpy
cmqv.cpy cmqxqhl.cpy cmqxqhv.cpy

Depending on the functionality of your application, you may not require all of the COPY files that IBM provides, but if you are not sure which COPY files to use, it is safest to include them all in your program.

Parent topic: Working with Messaging Middleware


Connecting to WebSphere MQ Applications

To use your ACUCOBOL-GT program with IBM's WebSphere MQ, you must perform the following steps:

  1. Install and configure the WebSphere MQ client software as described in the IBM documentation.
  2. Add the necessary WebSphere MQ calls to your ACUCOBOL-GT program.
  3. Define a message buffer and any other variables in Working-Storage.
  4. Compile your program using the "-D5" data format switch.
  5. Configure the runtime and environment by setting the USE_MQSERIES configuration variable and MQSERVER environment variable.

These steps are described in more detail in the following sections.

  • Adding WebSphere MQ Calls to Your ACUCOBOL-GT Program
  • Setting Up Working-Storage
  • Compiling Your Application
  • Configuring the Runtime and Environment
Parent topic: Working with Messaging Middleware


Adding WebSphere MQ Calls to Your ACUCOBOL-GT Program

In order to interface with IBM WebSphere MQ, your ACUCOBOL-GT program must be able to connect to the queue manager, open specific queues, read messages from queues, write messages to queues, close queues, and disconnect from the queue manager. Once the WebSphere MQ Client software is loaded and configured, you can set up a queue on the message queue manager or server to receive messages. We support calls to the message queues and the message queue manager.

Once they are defined, the queue manager and queue names are case sensitive.

The runtime uses the following WebSphere MQ calls to communicate with other WebSphere MQ applications by sending and receiving messages:

Connection Calls

MQCONN - Connect to queue manager

MQCONNX - Connect to queue manager (extended)

MQDISC - Disconnect queue manager

Queue Manipulation Calls

MQOPEN - Open object (usually a queue)

MQCLOSE - Close Object

MQINQ - Inquire about an object

MQGET - Get a message off of the queue

MQPUT - Put a message on the queue

MQPUT1 - Open, put single message, close in one call

MQSET - Set object attributes

Transaction Support

MQBEGIN - Begin Unit of work

MQBACK - Back out changes

MQCMIT - Commit changes

These routines can be called directly from COBOL, as shown in the subsequent sections. Please note that for Windows-based applications, it is not necessary to use the parameter qualifiers "BY VALUE" or "BY REFERENCE" if the runtime is configured to load the WebSphere MQ DLL automatically. However, if you load the DLL manually, or if you are operating under UNIX or Linux, you must use these qualifiers.

For all of these calls, we recommend that you check the COMP-CODE and REASON variables to verify that the calls executed successfully.

For a detailed description of all available commands and their usage, refer to the IBM WebSphere MQ manuals.

See Configuring the Runtime and Environment for details.

  • Connecting to the Queue Manager
  • Opening Specific Queues
  • Reading Messages from Queues
  • Writing Messages to Queues
  • Closing Queues
  • Disconnecting from the Queue Manager
Parent topic: Connecting to WebSphere MQ Applications


Connecting to the Queue Manager

To connect to the WebSphere MQ queue manager from your ACUCOBOL-GT program, use the following code:

CALL 'MQCONN'
    USING QM-NAME, by reference HCONN,
    COMPCODE, REASON

in the following modes:

Input Mode:

Variable | Description | Definition
QM-NAME | Variable string that contains the name of the queue manager | User-defined

Output Mode:

Variable | Description | Definition
HCONN | S9(9) BINARY handle to queue manager | User-defined
COMPCODE | S9(9) BINARY returns the completion code | User-defined
REASON | S9(9) BINARY returns the reason | User-defined
Parent topic: Adding WebSphere MQ Calls to Your ACUCOBOL-GT Program


Opening Specific Queues

To open specific message queues in WebSphere MQ, use the following code:

CALL 'MQOPEN'
    USING by value HCONN, by reference OBJDESC,
    by value OPTS, by reference HQUEUE,
    COMPCODE, REASON

in the following modes:

INPUT Mode:

Variable | Description | Definition
HCONN | S9(9) BINARY handle to queue manager | User-defined
OBJDESC | Structure that identifies the object to be opened | cmqodv.cpy
OPTS | S9(9) BINARY options that control the action of MQOPEN | User-defined

The available OPTS S9(9) BINARY options are specified in "cmqv.cpy". From the options that are available, at least one of the following options must be specified:

  • MQOO-BROWSE - Open in browse messages
  • MQOO-INPUT - Open in read messages
  • MQOO-OUTPUT - Open to write messages
  • MQOO-SET - Open to set properties of objects
  • MQOO-INQUIRE - Open to inquire about objects

To specify multiple options, add them together.

OUTPUT Mode:

Variable | Description | Definition
HQUEUE | S9(9) BINARY handle to queue | User-defined
COMPCODE | S9(9) BINARY returns the completion code | User-defined
REASON | S9(9) BINARY returns the reason | User-defined
Parent topic: Adding WebSphere MQ Calls to Your ACUCOBOL-GT Program


Reading Messages from Queues

To read messages from a WebSphere MQ queue, use the following code:

CALL 'MQGET'
    USING by value HCONN, by value HQUEUE,
    by reference MSGDESC, by reference GETMSGOPTS,
    by value BUFFER-LEN, by reference BUFFER-REP,
    by reference DATA-LEN,
    COMPCODE, REASON

in the following modes:

INPUT Mode:

Variable | Description | Definition
HCONN | S9(9) BINARY handle to queue manager | User-defined
HQUEUE | S9(9) BINARY handle to queue | User-defined
BUFFER-LEN | S9(9) BINARY length in bytes of buffer area | User-defined
DATA-LEN | S9(9) BINARY length in bytes of data in the message | User-defined

OUTPUT Mode:

Variable | Description | Definition
BUFFER-REP | Area to contain the message data | User-defined
COMPCODE | S9(9) BINARY returns the completion code | User-defined
REASON | S9(9) BINARY returns the reason | User-defined

I-O Mode:

Variable | Description | Definition
MSGDESC | Structure describes the attributes of the message required and the attributes of the message retrieved | cmqmdv.cpy
GETMSGOPTS | Options that control the action of MQGET For example, if you want to read a specific message, then you can specify the option MQMO_MATCH_CORREL_ID which causes only messages with the specified correl-id to be retrieved. | cmqgmov.cpy
Parent topic: Adding WebSphere MQ Calls to Your ACUCOBOL-GT Program


Writing Messages to Queues

To write messages to queues in WebSphere MQ, use the following code:

CALL "MQPUT"
    USING by value HCONN, by value HQUEUE,
    by reference MSGDESC,PUTMSGOPTS,
    by value BUFFER-LEN, by reference BUFFER-REQ,
    by reference COMPCODE, REASON.

in the following modes:

INPUT Mode:

Variable | Description | Definition
HCONN | S9(9) BINARY handle to queue manager | User-defined
HQUEUE | S9(9) BINARY handle to queue | User-defined
BUFFER-LEN | S9(9) BINARY length in bytes of buffer area | User-defined

OUTPUT Mode:

Variable | Description | Definition
BUFFER-REQ | Message data area | User-defined
COMPCODE | S9(9) BINARY returns the completion code | User-defined
REASON | S9(9) BINARY returns the reason | User-defined

I-O Mode:

Variable | Description | Definition
MSGDESC | Structure describes the attributes of the message sent and receives information about the message after sending | cmqmdv.cpy
PUTMSGOPTS | Options that control the action of MQPUT | cmqpmov.cpy
Parent topic: Adding WebSphere MQ Calls to Your ACUCOBOL-GT Program


Closing Queues

To close message queues in WebSphere MQ, use the following code:

CALL 'MQCLOSE'
    USING by value HCONN, by reference HQUEUE,
    by value OPTS,
    by reference COMPCODE, REASON.

in the following modes:

INPUT Mode:

Variable | Description | Definition
HCONN | S9(9) BINARY handle to queue manager | User-defined
OPTS | S9(9) BINARY options that control the action of MQCLOSE | User-defined

The available OPTS S9(9) BINARY options are specified in "cmqv.cpy". Only one of the following options should be specified:

  • MQCO_NONE
  • MQCO_DELETE
  • MQCO_DELETE_PURGE

OUTPUT Mode:

Variable | Description | Definition
COMPCODE | S9(9) BINARY returns the completion code | User-defined
REASON | S9(9) BINARY returns the reason | User-defined
Parent topic: Adding WebSphere MQ Calls to Your ACUCOBOL-GT Program


Disconnecting from the Queue Manager

To disconnect from the WebSphere MQ queue manager, use the following code:

CALL 'MQDISC'
    USING by reference HCONN, COMPCODE, REASON.

in the following modes:

INPUT Mode:

Variable | Description | Definition
HCONN | S9(9) BINARY handle to queue manager | User-defined

OUTPUT Mode:

Variable | Description | Definition
COMPCODE | S9(9) BINARY returns the completion code | User-defined
REASON | S9(9) BINARY returns the reason | User-defined
Parent topic: Adding WebSphere MQ Calls to Your ACUCOBOL-GT Program


Setting Up Working-Storage

In addition to adding WebSphere MQ calls to your program, you will need to define a message buffer and any other variables in Working-Storage. For example:

01 QM-NAME         PIC X(48) VALUE SPACES.
01 HCONN           PIC S9(9) BINARY.
01 COMPCODE        PIC S9(9) BINARY.
01 REASON          PIC S9(9) BINARY.
01 OPTIONS         PIC S9(9) BINARY.
01 HOBJ            PIC S9(9) BINARY.
01 BUFFER-LENGTH   PIC S9(9) BINARY.
01 max-buff-length PIC S9(9) BINARY.
01 BUFFER          PIC X(1024).
Parent topic: Connecting to WebSphere MQ Applications


Compiling Your Application

When your ACUCOBOL-GT program is ready, compile it using the "-D5" data format switch. This causes data items declared as BINARY to be treated as COMP-5. This means that the data values are stored in the host machine's native byte-order instead of the machine-independent byte-order normally used. Such data items can contain values of magnitude up to the capacity of the native binary representation (2, 4, or 8 bytes) instead of being limited to the value implied by the number of 9s in the picture. The runtime will not require any special switches to use the IBM library routines or COPY files once you have compiled with this option.

Use caution when compiling with any other "-D" flags because this could cause problems in compilation

Parent topic: Connecting to WebSphere MQ Applications


Configuring the Runtime and Environment

The configuration variable USE_MQSERIES indicates that the program makes calls to WebSphere MQ. If you plan to load the WebSphere MQ DLL yourself, then there is no need for this variable (however you must use the "BY VALUE" and "BY REFERENCE" phrases when calling an MQ routine).

If you do not plan to load the DLL yourself, set this variable to "1" (on, true, yes). The runtime will automatically load the DLL and pass calls beginning with the string "MQ" to the WebSphere MQ client. If the named routine does not exist, the runtime uses the normal search sequence to find a matching function. The "BY VALUE" and "BY REFERENCE" phrases are not required if you are using the USE_MQSERIES variable.

If you are running on a Windows client machine, you must set the MQSERVER environment variable to the name of the physical server as defined in the Host file, or to a fixed IP address. On Windows NT, XP or 2000 systems, set the variable in the "Environment Variables" dialog, accessed from the Advanced tab of the Control Panel's "System" applet. On Windows 98/ME systems, set the variable in the "autoexec.bat" file. The variable takes effect after the system has been rebooted.

Even though you are setting this definition on a Windows system, you must use only a forward slash. Back slashes are not recognized by WebSphere MQ.

Parent topic: Connecting to WebSphere MQ Applications


Working with Non-Vision Data

  • Introduction
  • Working with XML Data
  • Working with Web Site and Web Service Data
  • Working with Relational Data
  • Working with C-ISAM and KSAM
  • Working with an EXTFH Interface
  • File System Configuration
  • File System Initialization
Parent topic: A Guide to Interoperating with ACUCOBOL-GT Version 10.2.0


Introduction

ACUCOBOL-GT® includes a native indexed sequential file system known as Vision. Although many of our customers convert their data to the Vision format, many others choose to keep their data in other COBOL and non-COBOL data formats. This preference is no problem for ACUCOBOL-GT. ACUCOBOL-GT programs can interoperate with many kinds of external data sources, including:

  • XML documents
  • SQL databases
  • ODBC-compliant data sources
  • C-ISAM and KSAM files
  • File systems that use an EXTFH interface to access files, such as those in transaction processing environments

In addition, ACUCOBOL-GT programs can work with a variety of external data types such as:

  • Java data types and arrays
  • C data types
  • Variant data types and safearrays

These types are described elsewhere in this guide.

Parent topic: Working with Non-Vision Data


Working with XML Data

Applications written in ACUCOBOL-GT can interact with many different forms of data, including data marked with eXtensible Markup Language (XML).

ACUCOBOL-GT provides a variety of ways to interact with XML data. Characteristics of the XML data in a particular usage might be a major factor in determining which technique is best suited to your needs.

While XML concepts are described in more detail below, most XML data can be most simply characterized into document-oriented and record-oriented applications. Document-oriented XML data might exhibit deep nesting of data structures, mixed content, external entities and the like. Record-oriented XML data is much more flat and typically have many repetitions of the same flat structure; this structure is often seen in use with data transmitted to or from relational databases.

The XML data mechanisms provided by ACUCOBOL-GT are summarized in this section.

AcuXML

AcuXML is a runtime-resident file system interface. AcuXML reads XML data and transparently converts it to sequential files for COBOL processing, and similarly converts COBOL output data into XML format when required. Using Extended File Descriptors (XFDs) created at compile time, AcuXML maps the data transparently, making it easy to read and write record-oriented XML data.

To facilitate the use of AcuXML, ACUCOBOL-GT includes a developer utility called xml2fd that creates File Descriptors (FDs) and SELECT statements from existing XML files. Although you may need to tune the results, you can include the FDs and SELECTS in your ACUCOBOL-GT program to prepare it for use with XML data.

XML Extensions Library

The XML Extensions Library is provided as a DLL/shared object library. XML Extensions allows data to be imported from an XML document by converting data elements (as necessary) and storing the results directly into a matching COBOL data structure in the DATA DIVISION. Similarly, data is exported directly from a COBOL data structure by converting the COBOL data elements (as necessary) and storing the results in an XML document. XML Extensions is particularly suited to document-oriented XML data.

XML GENERATE and PARSE

ACUCOBOL-GT supports the IBM Enterprise COBOL XML GENERATE and XML PARSE statements. XML PARSE gives you a way to parse XML and process it in a COBOL program, associating processing procedures with the exception and non-exception cases that can result from the parse. XML GENERATE gives you a way to translate COBOL data into XML.

C$XML

For those who want more control over the parsing of data, ACUCOBOL-GT provides the C$XML library routine. This routine lets you define precisely which elements or attributes of the data to parse. For instance, you can request the handle of the entire XML tree, the first child element of the handle passed, the next sibling element, the number of attributes in an element, the name and value of the attributes, and so on. C$XML gives you much lower-level control over the parsing of XML data compared to AcuXML, but it requires more programming effort and XML knowledge.

  • XML Concepts
  • The XML-to-FD Utility
  • The AcuXML Interface
  • Using AcuXML
  • AcuXML Error Reporting
  • Using the C$XML Routine
  • Using XML Extensions
  • XML Extensions Statement Reference
  • XML Extensions Error Messages
Parent topic: Working with Non-Vision Data


XML Concepts

XML is a markup language for documents containing structured information. At first glance, XML is similar to hypertext markup language (HTML); with both, you mark up document content with descriptive tags surrounded by angle brackets. In XML, documents commonly include the following elements:

Comments | <!-- -->
Headers | <?xml version = "1.0"?>
Start tags | <record>
End tags | </record>

Elements can have children, which can have children, and so on. The main difference between HTML and XML, however, is that in HTML, the markup defines hypertext structure or display formatting. In XML, the markup defines the document content itself.

Unlike HTML, XML contains no predefined tag set or preconceived semantics for the markup. Rather, XML lets you define tags and the structural relationships between them based on the content of your document. For example, you may define tags called <lender>, <borrower>, and <due-date>. Because XML documents contain information about themselves, they are an excellent vehicle for transporting data from one location to another.

  • XML Documents
  • XML Parsers
  • Usage
Parent topic: Working with XML Data


XML Documents

XML documents are strictly text files. In the context of data transport, the phrase "XML document" refers to a file or data stream containing any form of structured data. Examples include e-commerce transactions, server APIs, mathematical equations, customer information, and inventory status.

XML documents contain only markup and content. All of the rules and semantics of the document are defined by the applications that process them. Like HTML documents, XML documents can be displayed in a Web browser. In this case, the semantics are usually derived from style sheets or Resource Description Framework (RDF) files.

XML documents are said to be either "well-formed" or "valid." Well-formed documents follow all of the XML rules for a document–for example, for every start tag, there is a corresponding end tag. Valid XML documents are well-formed, but they also contain a document type definition (DTD), and they obey the constraints of that definition. For example, the following XML file contains a DTD that describes all the elements of the file:

<?xml version = "1.0"?>
<!DOCTYPE ORDERFILE [
<!ELEMENT ORDERFILE (CUSTOMER)*>
<!ELEMENT CUSTOMER (NAME, DATE, ORDERS)>
<!ELEMENT NAME (LAST-NAME, FIRST-NAME)>
<!ELEMENT LAST-NAME (#PCDATA)>
<!ELEMENT FIRST-NAME (#PCDATA)>
<!ELEMENT DATE (#PCDATA)>
<!ELEMENT ORDERS (ITEM)*>
<!ELEMENT ITEM (PRODUCT, NUMBER, (PRICE | CHARGEACCT | SAMPLE))>
<!ELEMENT PRODUCT (#PCDATA)>
<!ELEMENT NUMBER (#PCDATA)>
<!ELEMENT PRICE (#PCDATA)>
<!ELEMENT CHARGEACCT (#PCDATA)>
<!ELEMENT SAMPLE (#PCDATA)>
]>
<ORDERFILE>
    <CUSTOMER>
        <NAME>
            <LAST-NAME>Smith</LAST-NAME>
            <FIRST-NAME>Sam</FIRST-NAME>
        </NAME>
        <DATE>October 15, 2001</DATE>
        <ORDERS>
            <ITEM>
                <PRODUCT>Tomatoes</PRODUCT>
                <NUMBER>8</NUMBER>
                <PRICE>1.25</PRICE>
            </ITEM>
            <ITEM>
        <PRODUCT>Apples</PRODUCT>
                <NUMBER>12</NUMBER>
                <PRICE>2.50</PRICE>
            </ITEM>
            <ITEM>
        <PRODUCT>Bananas</PRODUCT>
                <NUMBER>6</NUMBER>
                <PRICE>.50</PRICE>
            </ITEM>
        </ORDERS>
    </CUSTOMER>
    <CUSTOMER>
        <NAME>
            <LAST-NAME>Snead</LAST-NAME>
            <FIRST-NAME>Todd</FIRST-NAME>
        </NAME>
        <DATE>October 17, 2001</DATE>
        <ORDERS>
            <ITEM>
                <PRODUCT>Slicer/Dicer</PRODUCT>
                <NUMBER>1</NUMBER>
                <CHARGEACCT>1234-5678-3456-7890</CHARGEACCT>
            </ITEM>
        </ORDERS>
    </CUSTOMER>
</ORDERFILE>

Documents that include and obey a schema rather than a DTD are considered to be "schema-valid." Schemas are files describing the XML document and its precise structure. XML documents that are accompanied by schemas produce the most reliable FDs and SELECT statements when run through the xml2fd utility, especially if the schema has information about data types and lengths.

Note:

Please note that the xml2fd utility is used exclusively with AcuXML. If you are calling the C$XML library routine, you do not need to run XML documents through xml2fd.

Following is an example of a schema file for the same XML document. As you can see, it is much more descriptive than the DTD.

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:annotation>
    <xs:documentation>
      Created by AcuXML(tm) version 6.0.0 (2002-11-12) on 2002/11/12
    </xs:documentation>
  </xs:annotation>

  <xs:element name="TEST-ORDERFILE">
    <xs:complexType>
      <xs:sequence>
        <xs:element maxOccurs="unbounded" ref="CUSTOMER"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name="CUSTOMER">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="NAME"/>
        <xs:element ref="DATE"/>
        <xs:element ref="ORDERS"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name="NAME">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="LAST-NAME"/>
        <xs:element ref="FIRST-NAME"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name="ORDERS">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="ITEM" maxOccurs="3"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name="ITEM">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="PRODUCT"/>
        <xs:element ref="NUMBER"/>
        <xs:element ref="PRICE"/>
        <xs:element ref="CHARGEACCT"/>
        <xs:element ref="SAMPLE"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name="LAST-NAME">
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:maxLength value="5"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

  <xs:element name="FIRST-NAME">
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:maxLength value="4"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

  <xs:element name="DATE">
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:maxLength value="16"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

  <xs:element name="PRODUCT">
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:maxLength value="12"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

  <xs:element name="NUMBER">
    <xs:simpleType>
      <xs:restriction base="xs:integer">
        <xs:totalDigits value="2"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

  <xs:element name="PRICE">
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:maxLength value="4"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

  <xs:element name="CHARGEACCT">
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:maxLength value="19"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

  <xs:element name="SAMPLE">
    <xs:simpleType>
      <xs:restriction base="xs:integer">
        <xs:totalDigits value="1"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

</xs:schema>

ACUCOBOL-GT applications can read and write any type of XML data. Typically, the party with whom you are exchanging data will require that the data include a DTD. Occasionally, they may require a schema for their own development work.

With AcuXML, you can specify the type of XML output that you want to generate. You use the configuration variable AXML_CREATE_STYLE. If you want the output to include a schema, you set AXML_CREATE_STYLE to "schema", and then use another configuration variable to define the schema name (AXML_SCHEMA_NAME). By default, a schema is then created each time ACUCOBOL-GT generates XML output. To prevent this for subsequent output, you can set a third configuration variable, AXML_CREATE_SCHEMA, to "false", then just the name of the schema file is included. Configuration variables are described in Configuration Variables.

Parent topic: XML Concepts


XML Parsers

An XML parser is a processor that reads and interprets the contents of an XML document and determines the structure and properties of the data. Both AcuXML and C$XML are XML parsers. AcuXML automatically reads and interprets XML data based on XFDs created at compile time. C$XML parses XML data based on operation codes passed to the library call. The term "parse" is used throughout the following sections to mean "read" or "decode." ACUCOBOL-GT's XML parsers read and decode XML data so that it can be processed by your COBOL program.

Parent topic: XML Concepts


Usage

AcuXML was designed for data exchange, but it can be beneficial for other uses as well. Following are some possibilities:

  • Business-to-business data exchange – You can use AcuXML to enable efficient business-to-business data exchange in wide-area networks and over the Internet. Business partners such as manufacturers and suppliers, hospitals and insurance companies, buyers and sellers can exchange vital business data through the common adoption of XML.

    B2B Data Exchange Using XML

    In order for two parties to exchange documents, both parties need to explicitly agree on the meaning of tags and data within documents. For instance, in a procurement situation, both the buyer and seller must agree on what <STATUS> means in an invoice document.

  • Application integration – If one of your goals is to merge data from multiple sources in order to integrate business processes, AcuXML can help. Converting your COBOL data to and from XML can enable it to be used throughout the enterprise, so long as the meaning of the data is expressly understood. Similarly, data from other enterprise applications can be read and processed by your COBOL program, if your enterprise chooses to use XML as the common transport mechanism. Application integration can replace the isolated stovepipe systems of the past.

    Application Integration with XML

  • Enterprise Resource Planning (ERP) – ERP software promises to save companies money by centralizing processing functions that would otherwise be redundant in an organization. Enterprises that use ERP packages can choose XML as the data format used by the centralized system. AcuXML can be used to integrate your COBOL program with the data.
  • Internet deployment – By combining AcuXML with AcuServer®, your end users can access XML documents residing on remote servers, whether those servers are in a local-area network, wide-area network, or Internet configuration. If you want to display your COBOL-based XML documents on the Web or inside a user's browser, you may do this as well using stylesheets or RDF files. With additional development effort, you may even develop an XML front end to interface with your COBOL program across the Internet. Most commonly, XML is being used as the language of Web services. It provides a standard by which Web services written in any language can communicate.

These are just a few of the many possible uses of XML. The capabilities of the XML language are far-reaching. However you choose to use it, you can make your ACUCOBOL-GT programs ready to read, process, and output XML data.

Parent topic: XML Concepts


The XML-to-FD Utility

In order to prepare your COBOL program for use with XML documents, you must first determine the nature of the data in the documents and the meaning of the tags.

The ACUCOBOL-GT Development System includes an xml2fd utility to read XML documents and produce FDs and SELECT statements suitable for inclusion in a COBOL program. Because the structure of valid XML documents is very specific and well defined, the utility produces the best results using valid documents.

The FD created by the utility has the same structure as the XML file. The parent/child relationships of all the data elements are present. Array definitions are included. The data types are defined. If a schema is included with the file, the DTD has a high degree of accuracy. If a DTD is included, the utility analyzes the content and makes an intelligent guess at the data types (e.g., numerical data is assigned the NUMBER type, and so on). Raw XML produces FDs that are a best guess based on the structure of the elements.

The utility also creates a SELECT statement for each data file. Once the FDs and SELECTs are created, you should modify them as required, then include them in the COBOL program. When you include the FDs and SELECT statements in your COBOL program, it can understand, process, and even output XML data that is structured like the existing file.

  • xml2fd Output
  • xml2fd Command Options
Parent topic: Working with XML Data


xml2fd Output

The utility understands three types of XML files:

  • XML files with a DTD – When you run XML files with DTDs through the utility, the record structure created for the FD is structurally correct, but may require manual modification in the sizes and types of the data items.
  • XML files with an associated schema file or pointers to a schema file that is available to the local system – When you run XML files with schemas through the utility, the resulting FD is structurally correct, but depending on the completeness of the schema may need to be manually modified in order to correct the sizes of the data items. If the schema includes size information, that information is used and no modification is necessary.

    Note that xml2fd supports schema includes. It detects the attributes "schema=filename" or "nonamespaceschemalocation=filename" and uses the named file to determine the structure of the FDs. However, the file must be available locally. You may need to locate the schema file on the Internet, download it onto your local development machine, and then point to it before you run the XML file through the utility.

  • Raw XML files (with no DTD and no schema) – When you run raw files through the utility, the structure created is a best guess based on reading all or part of the XML file and creating a structure from the structure of the elements. The more homogeneous the XML data, the more precise the record structure is. Again, it may require manual modification to fix the sizes.

Note that xml2fd ignores attributes of XML tags, because no natural mapping exists between attributes and COBOL data items. In the following code snippet, type="personal" is an attribute that would be ignored:

<customer type="personal">
     <name>Acu</name>
</customer>

The xml2fd utility creates two files: a ".fd" file and a ".sl" file. The ".fd" file contains the FD and record structure for the data file. The ".sl" file contains the file type and SELECT for the data file. The base name of the files are the same as the base name of the XML file provided. For example, "mydata.xml" produces "mydata.fd" and "mydata.sl". It is your responsibility to include the output files in your COBOL program.

Parent topic: The XML-to-FD Utility


xml2fd Command Options

You can invoke the xml2fd utility from the command line or from the AcuBench® Tools menu. To invoke it from the command line, type:

xml2fd options xmlfile ...

where:

"xmlfile ..." is one or more XML files. For each XML file named, separate ".fd" and ".sl" files are created.

Note that xml2fd is not designed to work with remote schema files. If the XML file refers to a remote schema file (using http syntax), the xml2fd utility will crash when trying to open the file. Make sure that the XML file used on this command line refers to a local schema or no schema at all.

Options include:

-d output_directory | Use this option to name the directory into which the ".fd" and ".sl" files should be placed. The default is the current directory. Note that the "-f" and "-s" options described below override this value.
-f fd_directory | Use this option if you want the ".fd" file to be placed into a different directory than the ".sl" file. The ".fd" file is then stored in the named directory.
-s sl_directory | Use this option if you want the ".sl" file to be placed into a different directory than the ".fd" file. The ".sl" file is then stored in the named directory.
-n count | Use this option to specify the number of records to read from the XML file before calculating the sizes of data items and table occurrences and arriving at field descriptions in the FD. In very large XML files, it may not be desirable to read the entire file to derive the FD. On the other hand, it may be necessary to read more than one record to confirm a "best guess" for intended field descriptions in a record. The more data the utility reads, the better the guess will be, but the more time it will take to process the data and create the file. The value of "-n" must be numeric and greater than "0".
-o occurs | Use this option to define a default value for any tables found in the XML file. Designating a numeric value greater than "0" instructs xml2fd to look for cases within the record where it is appropriate to assign an OCCURS clause, and gives a default number to assign in the clause. Schema parsed uses any maxOccurs attributes found, but DTDs don't have the syntax to describe a maximum number of occurrences. If records are read and the number of occurrences in any record is larger than the value you enter here, the larger value is used.
Please note that in complex cases where an FD has more than one OCCURS clause and where the number of OCCURS differs, you must manually change the generated representation of the FD.
-p prefix Use this option to prepend all data items in the FD with a standard prefix. This option is especially useful if the XML file has elements that use reserved words as their names. For example, If your XML file looks like the following:
<company>

  <name>Acucorp</company>
  <address>8515 Miralani Drive</address>
  <city>San Diego</city>
  <state>CA</state>
  <ZIP>92126</ZIP>
  <remarks>This company sells development
   products for COBOL</remarks>
</company>
Then xml2fd will generate an FD that looks like:
07 company.
   09 name pic x(30).
   09 address pic x(30).
   09 city pic x(15).
   09 state pic x(2).
   09 ZIP pic 9(5).
   09 remarks pic x(128).

However, ADDRESS and REMARKS are COBOL reserved words, so this would not compile. Instead, an error such as this would result: "Unexpected character. System will ignore it."

If you use "-p cust-" when running xml2fd, then the utility generates:

07 cust-company.
   09 cust-name pic x(30).
   09 cust-address pic x(30).
   09 cust-city pic x(15).
   09 cust-state pic x(2).
   09 cust-ZIP pic 9(5).
   09 cust-remarks pic x(128).

Using this option causes XFD NAME directives to be placed into the ".fd" file so that the resulting XFD file has data item names that match the XML file.

Parent topic: The XML-to-FD Utility


The AcuXML Interface

The AcuXML interface is a transparent interface between ACUCOBOL-GT applications and XML documents. Part of the standard ACUCOBOL-GT runtime system, AcuXML dynamically reads and generates XML using data dictionaries created at compile time. As the ACUCOBOL-GT runtime module executes your COBOL application, the interface runs "behind the scenes" to match up the requirements of both the application and the data. You do not need to know XML to use the interface.

Transparent Access to XML Data

With the interface, an ACUCOBOL-GT program can read whichever XML files a user indicates. Because XML files are by nature sequential, AcuXML can read the files specified for input, process them, and return files in the desired data format.

The ACUCOBOL-GT program can also open any COBOL file that is required for a user request (whether it is indexed, relative, or sequential), read and process that data, and output a sequential file that is in XML format. Using configuration variables, you can specify which files you want to be XML documents, and whether you want ACUCOBOL-GT to generate raw XML, XML documents with DTDs, or XML documents with schemas. For our purposes, the XML documents are considered transient–more of a data transport mechanism than a data storage mechanism.

Please note that reading an XML file and then writing it as XML with the same data does not necessarily produce an identical file. The information is the same, but the markup or "wrappers" likely are not.

  • Data Dictionaries
  • AcuXML Configuration Variables
Parent topic: Working with XML Data


Data Dictionaries

ACUCOBOL-GT's XML interface depends on XFDs, or data dictionaries, to map COBOL records to the XML data type. These dictionaries are based on the standard COBOL file descriptors (FDs). XFD Files for more details.) These files are created at compile time. The structure of XFDs used by alfred and the Acu4GL® and AcuXDBC® interfaces has been enhanced in order to mirror the rich structure of XML.

To create the XFDs, you specify "-Fa" on the command line when you compile your COBOL source. This option signals the compiler to create an XFD file for every indexed, relative, or sequential file contained in the program. To prevent naming errors, you should also include the "-Fc" option, which tells the compiler that the field names in the resulting XFDs must match the element names in the COBOL source exactly.

XFDs include information about the structure of their associated data files. They provide a map between the COBOL files used by the program and the external data file that the program receives (in this case, an XML document).

Using the XFDs and the new XML interface, the COBOL program can open an XML document and read from it or write to it using COBOL file I/O syntax.

To control precisely how the XFDs are built, you can use data dictionary directives with AcuXML, as you can with any ACUCOBOL-GT file system interface. Directives are optional comments that you place into your FDs in your COBOL source code. For more information, see How the Terminal Manager Works.

For instance, to store items at group level, you can change the database table names in the XFDs. Likewise, you can store dates as database "date" fields. This is all done with directives. Note that if you use the XFD Name directive to define XML data elements, you must use the name exactly as it appears in the XML tag, including case. If you do not match the name or case exactly, the FD items do not get filled when the interface parses the XML data.

Parent topic: The AcuXML Interface


AcuXML Configuration Variables

ACUCOBOL-GT includes several configuration variables for configuring the XML output that is generated by the AcuXML interface. These include:

Configuration Variable | Purpose
AXML_CREATE_STYLE | Defines whether a DTD or schema is included with the XML output that is generated
AXML_CREATE_SCHEMA | Tells AcuXML whether to create a schema file, or simply include the name of a schema file in the output
AXML_SCHEMA_DOC | Adds a documentation element to the schema if created
AXML_SCHEMA_NAME | Defines the name of the schema file to generate, if any
AXML_SCHEMA_NAMESPACE_DATA | Defines the precise schema namespace string to include in the XML output
AXML_ENCODING | Specifies a character encoding method for the XML files that AcuXML creates
AXML_STYLESHEET_TYPE | Adds a stylesheet comment to the beginning of generated XML files. This associates a style sheet with the XML documents.
AXML_STYLESHEET_HREF | Names the XML style sheet to use
AXML_IGNORE_EMPTY_DATA | When writing tags, ignores data items that are all blank (in the case of alpha data) or "0" (in the case of numeric data)

All of the variables are optional. If desired, you include them in your runtime configuration file, just as you would any ACUCOBOL-GT configuration variable. In addition, you should also use the configuration file to specify the location of your XML files, which particular files are of XML type, and perform additional configuration as desired.

See Configuration Variables for usage details on all of the configuration variables that are listed here.

Parent topic: The AcuXML Interface


Using AcuXML

To interact with XML data from an ACUCOBOL-GT application, you must prepare your application, then set up and configure the end-user system. Your program can be designed to read XML data and/or generate XML output.

  • To enable your program to read XML data:
  • To enable your program to generate XML output:
  • AcuXML output structures
  • Restrictions
Parent topic: Working with XML Data


To enable your program to read XML data:

Step 1: Prepare your ACUCOBOL-GT application

  1. Obtain a representative XML document from the anticipated source of your files. For the best results, the document should refer to a DTD or schema.
  2. Use the xml2fd utility to create FDs and SELECT statements for the XML document. See The XML-to-FD Utility for more information on using this utility.
  3. Include the new FDs and SELECT statements in your program as you would any FD and SELECT.
  4. Compile your program with the "-Fa" option specified. This option tells the compiler to generate XFDs for each COBOL data file included in the program. The "-Fa" option is described in Compiler File Options. To prevent naming errors, you should also include the "-Fc" option, which tells the compiler that the field names in the resulting XFDs must match the element names in the COBOL source exactly, including case, hyphen usage, etc.

Step 2: Set up and configure the runtime system

  1. Install the ACUCOBOL-GT runtime, object code, data dictionaries, and COBOL data files on the end-user system.
  2. Acquire XML data from your data source, or if reading data from the Internet, acquire the exact URL of the XML data stream.
  3. Create a configuration file for the runtime. In the configuration file:
    • Specify the location of your data files. If the files are local or accessed via AcuServer, use the FILE_PREFIX configuration variable to specify the location. If the files will be accessed over the Internet, map the data files directly to a URL. For example, to read "bookfile.xml" over the Internet, you could add the following line to the configuration file:
      bookFILE  http://myserver.mycomp.com/data/bookfile.xml
    • Specify which files should be treated as XML data files by setting the filename_HOST variable to "XML", where filename is the base name of the XML document with no file extension (e.g., "custdata_HOST XML"). Include a separate entry for each XML document name. Make sure that the files you indicate are sequential files. For example:
      bookFILE_HOST XML
    • Tell the runtime to keep the case of your XFD field names intact by setting the 4GL-COLUMN-CASE variable to "unchanged". XML (unlike HTML) is case sensitive. If you do not set 4GL-COLUMN-CASE, the runtime converts the field names to lower case and hyphens to underscores. Then the runtime may not be able to read your XML data properly.
    • Configure the XML output as desired using a set of AcuXML-specific configuration variables. (These variables all start with the "AXML" prefix. See AcuXML Configuration Variables.) With these variables, you can tell the runtime whether to create a DTD or schema when creating XML data, whether to associate a style sheet with the output, and more.
    • Perform additional configuration as desired. You can use any configuration variables that affect XFD parsing, such as XFD-PREFIX and XFD-DIRECTORY. Note that XFD files must be available in the named XFD_DIRECTORY even when the XML data stream is read over the Internet via HTTP.

    See Configuration Variables for details on any of these configuration file entries. Following is a sample cblconfig file for use with AcuXML:

    file-prefix           . /usr/data
orderfile-host        xml
bookfile-host         xml
customer-host         xml
4gl-column-case       unchanged
  4. Run your ACUCOBOL-GT program normally.

The rest is automatic. When your ACUCOBOL-GT program READs a file designated as XML, the AcuXML interface converts the XML data to COBOL using XFDs, your program performs the request, and then returns data in desired format. Your program automatically WRITEs output in sequential XML format as specified in configuration file.

Parent topic: Using AcuXML


To enable your program to generate XML output:

If your program needs only to output XML data, the process is even simpler:

Prepare your ACUCOBOL-GT application

  1. Decide what data is needed in the XML file.
  2. Write an FD that describes that data in the desired way. Note that if you have a sequential file that already describes the data, this step is not necessary.
  3. COPY the FD into your COBOL program, and compile with the "-Fa" option.

Step 2: Set up and configure the runtime system

  1. Install the ACUCOBOL-GT runtime, object code, data dictionaries, and COBOL data files on the end-user system.
  2. Create a configuration file for the runtime as described in step 2c above. Include output variables, such as:
    axml-create-style     schema
axml-schema-name      myschema
axml-create-schema    false
axml-stylesheet-type  text/css
axml-stylesheet-href  mystyle.css

Step 3: Run your ACUCOBOL-GT program normally

Parent topic: Using AcuXML


AcuXML output structures

When AcuXML generates XML data, the hierarchical structure of the XML file matches the record structure of the COBOL file. For example, iobench has a sequential file SEQ1, whose record structure is defined as:

01  SEQ-1-RECORD.
   03  SEQ-1-KEY                       PIC 9(10).
   03  SEQ-1-ALT-KEY.
       05  SEQ-1-ALT-KEY-A             PIC X(30).
       05  SEQ-1-ALT-KEY-B             PIC 9(10).
   03  SEQ-1-BODY                      PIC X(50).

If this file were written as an XML file, a typical record would look like this:

 <SEQ-1-RECORD>
   <SEQ-1-KEY>20</SEQ-1-KEY>
   <SEQ-1-ALT-KEY>
     <SEQ-1-ALT-KEY-A>032472140976086473026412339002
     </SEQ-1-ALT-KEY-A>
     <SEQ-1-ALT-KEY-B>20</SEQ-1-ALT-KEY-B>
   </SEQ-1-ALT-KEY>
 <SEQ-1-BODY>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrst
 </SEQ-1-BODY>
 </SEQ-1-RECORD>

Note that in XML, it is possible for two data elements to have the same name. For instance:

<Lender phone="607.555.2222">
    <name>Doug Glass</name>
    <street>416 Disk Drive</street>
    <city>Medfield</city>
    <state>MA</state>
</Lender>
<Borrower phone="310.555.1111">
    <name>Britta Regensburg</name>
    <street>219 Union Drive</street>
    <city>Medfield</city>
    <state>CA</state>
</Borrower>

However, XFDs are designed to mirror the structure of databases which do not allow duplicate element names. For this reason, compiling a COBOL program with this record structure will result in an XFD compiler warning. If you are working with XML data files, you may disregard this warning.

Parent topic: Using AcuXML


Restrictions

Some restrictions are associated with reading or writing an XML document from ACUCOBOL-GT programs. For instance, programs can open files INPUT or OUTPUT, but not I-O or EXTEND. Attempting to open a file EXTEND or I-O fails and returns a NO-SUPPORT error (error 9B in the ANSI-85 code set).

In addition, the XML file system interface can write only sequential XML files. Because XML is intended as a data delivery mechanism and not a data store mechanism, this is not much of a limiting factor.

As any XML parser would, this interface fails to read a record if a parsing error occurs. The error returned is 9D/05 in this case. See AcuXML Error Reporting for a list of specific parsing errors.

Finally, the XML data file to be read must contain only a single document. Do not try to concatenate documents into a single data file. The top-level element of the XML document corresponds to a sequential file. Each element at the next level corresponds to a record in that file.

For example, the SEQ1 file iobench looks like the following after three records have been written to the file:

<SEQ-1-FILE>
 <SEQ-1-RECORD>
   <SEQ-1-KEY>10</SEQ-1-KEY>
   <SEQ-1-ALT-KEY>
     <SEQ-1-ALT-KEY-A>164424914991684123046492639014
   </SEQ-1-ALT-KEY-A>
     <SEQ-1-ALT-KEY-B>10</SEQ-1-ALT-KEY-B>
   </SEQ-1-ALT-KEY>
   <SEQ-1-BODY>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvw</SEQ-1-BODY>
 </SEQ-1-RECORD>
 <SEQ-1-RECORD>
   <SEQ-1-KEY>20</SEQ-1-KEY>
   <SEQ-1-ALT-KEY>
     <SEQ-1-ALT-KEY-A>032472140976086473026412339002
   </SEQ-1-ALT-KEY-A>
     <SEQ-1-ALT-KEY-B>20</SEQ-1-ALT-KEY-B>
   </SEQ-1-ALT-KEY>
   <SEQ-1-BODY>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvw</SEQ-1-BODY>
 </SEQ-1-RECORD>
 <SEQ-1-RECORD>
   <SEQ-1-KEY>30</SEQ-1-KEY>
   <SEQ-1-ALT-KEY>
     <SEQ-1-ALT-KEY-A>110640971904282743006692139010
   </SEQ-1-ALT-KEY-A>
     <SEQ-1-ALT-KEY-B>30</SEQ-1-ALT-KEY-B>
   </SEQ-1-ALT-KEY>
   <SEQ-1-BODY>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvw</SEQ-1-BODY>
 </SEQ-1-RECORD>
</SEQ-1-FILE>

Note that the end of the file in this example is signaled by the XML command, </SEQ-1-FILE>. ACUCOBOL-GT ignores other documents in the file. For example, if you have an XML file which looks like the this:

<SEQ-1-FILE>
 <SEQ-1-RECORD>
   <SEQ-1-KEY>10</SEQ-1-KEY>
   <SEQ-1-ALT-KEY>
     <SEQ-1-ALT-KEY-A>164424914991684123046492639014
     </SEQ-1-ALT-KEY-A>
     <SEQ-1-ALT-KEY-B>10</SEQ-1-ALT-KEY-B>
   </SEQ-1-ALT-KEY>
   <SEQ-1-BODY>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvw</SEQ-1-BODY>
 </SEQ-1-RECORD>
</SEQ-1-FILE>
<SEQ-1-FILE>
 <SEQ-1-RECORD>
   <SEQ-1-KEY>20</SEQ-1-KEY>
   <SEQ-1-ALT-KEY>
     <SEQ-1-ALT-KEY-A>032472140976086473026412339002
     </SEQ-1-ALT-KEY-A>
     <SEQ-1-ALT-KEY-B>20</SEQ-1-ALT-KEY-B>
   </SEQ-1-ALT-KEY>
   <SEQ-1-BODY>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvw</SEQ-1-BODY>
 </SEQ-1-RECORD>
</SEQ-1-FILE>
<SEQ-1-FILE>
 <SEQ-1-RECORD>
   <SEQ-1-KEY>30</SEQ-1-KEY>
   <SEQ-1-ALT-KEY>
     <SEQ-1-ALT-KEY-A>110640971904282743006692139010
     </SEQ-1-ALT-KEY-A>
     <SEQ-1-ALT-KEY-B>30</SEQ-1-ALT-KEY-B>
   </SEQ-1-ALT-KEY>
   <SEQ-1-BODY>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvw</SEQ-1-BODY>
 </SEQ-1-RECORD>
</SEQ-1-FILE>

then ACUCOBOL-GT ignores everything after the tenth line, because the </SEQ-1-FILE> XML command signaled the end of the file. You should use the C$XML library routine instead of AcuXML to read files like these.

Parent topic: Using AcuXML


AcuXML Error Reporting

If AcuXML encounters a parsing error, it returns the error code "9D05,nn" where nn is one of the following:

1 | Out of memory
2 | Syntax error
3 | No element found
4 | Not well formed (invalid token)
5 | Unclosed token
6 | Partial character
7 | Mismatched tag
8 | Duplicate attribute
9 | Junk after document element
10 | Illegal parameter entity reference
11 | Undefined entity
12 | Recursive entity reference
13 | Asynchronous entity
14 | Reference to invalid character number
15 | Reference to binary entity
16 | Reference to external entity in attribute
17 | XML processing instruction not at start of external entity
18 | Unknown encoding
19 | Encoding specified in XML declaration is incorrect
20 | Unclosed CDATA section
21 | Error in processing external entity reference
22 | Document is not standalone
23 | Unexpected parser state – please send a bug report
24 | Entity declared in parameter entity
Parent topic: Working with XML Data


Using the C$XML Routine

The C$XML library routine is designed for those who want low-level control over the parsing of XML data. It lets you define precisely which elements or attributes of the data to parse. C$XML can be used for both record- and non-record-based XML documents.

C$XML contains detailed descriptions of the library routine's individual operation codes, parameters, usage, etc. The following sections describe how to use the C$XML library routine in more general terms.

  • General procedure
  • Understanding C$XML Terminology
  • Parsing an XML File
  • Moving to an Element
  • Retrieving Data
  • Adding, Modifying, or Deleting Data
  • Writing a File
  • Releasing the Parser
  • Retrieving Errors
  • Retrieving Attributes
  • Retrieving Comments
  • C$XML Examples
Parent topic: Working with XML Data


General procedure

When using the C$XML routine, you should perform the following basic functions:

  1. Parse an XML file.
  2. Move to an element in the file.
  3. Retrieve data from the element.
  4. Add, modify, or delete data as desired.
  5. Write to the file to save your changes.
  6. Release the parser from memory.

If an error occurs, you can also retrieve error information. If desired, you can retrieve element attributes or comments as well.

Each function is performed through C$XML operation codes (op-codes) as described in this section. Most C$XML operations return element handles. A separate handle is provided for each element. You should move the return codes to an ACUCOBOL-GT handle that you've declared in Working-Storage. The handle should be defined as USAGE IS HANDLE. You will refer to these handles when you move deeper into a record and retrieve or update specific data.

refer to C$XML Examples for sample code.

Note: You don't necessarily have to open a file to read XML data. You can parse a string directly using the CXML-PARSE-STRING op-code.
Parent topic: Using the C$XML Routine


Understanding C$XML Terminology

The C$XML routine uses XML terminology that may not be familiar to you–terms like element, attribute, parent, child, and sibling. To understand the terminology of C$XML, consider the following XML file (line numbers added for discussion purposes):

 1 <?xml version="1.0"?>
 2 <bookfile
 3   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 4   xsi:noNamespaceschemaLocation="bookfile.xsd">
 5   <transaction borrowDate="2001-10-15">
 6     <Lender phone="607.555.2222">
 7       <name>Doug Glass</name>
 8       <street>416 Disk Drive</street>
 9       <city>Medfield</city>
10       <state>MA</state>
11     </Lender>
12     <Borrower phone="310.555.1111">
13       <name>Britta Regensburg</name>
14       <street>219 Union Drive</street>
15       <city>Medfield</city>
16       <state>CA</state>
17     </Borrower>
18     <note>Lender wants these back in two weeks!</note>
19     <books>
20       <book bookID="123-4567-890">
21         <bookTitle>Earthquakes for Breakfast</bookTitle>
22         <pubDate>2001-10-20</pubDate>
23         <replacementValue>15.95</replacementValue>
24         <maxDaysOut>14</maxDaysOut>
25       </book>
26       <book bookID="123-4567-891">
27         <bookTitle>Avalanches for Lunch</bookTitle>
28         <pubDate>2001-10-21</pubDate>
29         <replacementValue>19.99</replacementValue>
30         <maxDaysOut>14</maxDaysOut>
31       </book>
32       <book bookID="123-4567-892">
33         <bookTitle>Meteor Showers for Dinner</bookTitle>
34         <pubDate>2001-10-22</pubDate>
35         <replacementValue>11.95</replacementValue>
36         <maxDaysOut>14</maxDaysOut>
37       </book>
38       <book bookID="123-4567-893">
39         <bookTitle>Snacking on Volcanoes</bookTitle>
40         <pubDate>2001-10-23</pubDate>
41         <replacementValue>17.99</replacementValue>
42         <maxDaysOut>14</maxDaysOut>
43       </book>
44     </books>
45   </transaction>
46 </bookfile>

When you call C$XML with the CXML-PARSE-FILE op-code, you get a handle to this entire file.

An "element" is a name that appears immediately after a less than sign (<), and terminated with a greater than sign (>) or by a forward slash followed by a greater than sign (/>). So "bookfile" (line 2) is the top-level element. "transaction" (line 5) is an element, as is "city" (lines 9 and 15 - these are two separate elements, both named "city").

There are two different ways in XML to signify that an element is finished:

  1. With a tag that is the element name preceded immediately by a less than sign and a forward slash (</).
  2. The corresponding greater than sign (>) is immediately preceded by a forward slash (/).

This sample has instances of the first method only. For example, the termination of the bookfile element is on line 46.

An "attribute" is included within the element description as a name followed by an equals sign (=), followed by a quoted string. The name is the attribute name, and the quoted string is the attribute value. There is no limit to the number of space-delimited attribute name/value pairs in an element. For example, the "transaction" element (line 5) has a single attribute whose name is "borrowDate" and whose value is "2001-10-15".

The "data" of an element is any non-element, non-comment text between the element start and end. Elements that end with a /> can't have data. And some elements don't have data. For example, the Lender element (line 6) has no data. The "street" element on line 8 has data of "416 Disk Drive".

A "child" of an element is an element one level below an element. For example, "Lender" is a child of "transaction", as is "Borrower". "name" is a child of "Lender", and there is a separate element named "name" which is a child of "Borrower". But neither of those "name" elements is considered a child of "transaction" because there is an element at a level between "name" and "transaction". There are two separate "city" elements, one of which is a child of "Lender", and the other a child of "Borrower". The elements between "city" and "Lender" are all at the same level as "city", which is why "city" is considered a child of "Lender".

A "parent" of an element is one who has that element as a child.

A "sibling" of an element is an element with the same parent.

So "transaction" is the parent of "Lender", "Borrower", "note" and "books" (lines 6, 12, 18 and 19, respectively). "Lender", "Borrower", "note" and "books" are all siblings.

A "record" is child of the top-level element.

Parent topic: Using the C$XML Routine


Parsing an XML File

You can use three main op-codes to parse an XML file with C$XML: CXML-PARSE-FILE, CXML-OPEN-FILE, and CXML-NEW-PARSER. Each has a slightly different function, as described below. Choose the one that best suits your needs.

Op-code | Description
CXML-PARSE-FILE | Opens and parses the specified file
CXML-OPEN-FILE | Opens the specified file, so you can parse individual records
CXML-NEW-PARSER | Opens a new, empty XML file
Note: C$XML can parse local or remote files–even files located on the Internet. You simply specify the server, IP address, or URL in the pathname. You cannot write to URLs, however.

If you prefer, you can parse an XML file directly without opening a file with the CXML-PARSE-STRING op-code. Examples for using these op-codes appear in the following paragraphs.

Opening and parsing a file

To open and read an entire XML file, use the CXML-PARSE-FILE op-code. Once a file is parsed, all its elements are immediately retrievable. Parsing entire files can take some time, depending on the size of the file. Use this option when you plan to work extensively with the whole file or when the file is small.

For instance:

call "C$XML" using CXML-PARSE-FILE "http://www.nws.noaa.gov/data/current_obs/KMYF.xml"
move return-code to parser-handle

Opening a file, parsing individual records

To simply open the file, but not parse it, use the CXML-OPEN-FILE op-code. With the file open, you can then parse individual records using the CXML-PARSE-NEXT-RECORD op-code. For instance:

CALL "C$XML" using CXML-OPEN-FILE "http://www.nws.noaa.gov/data/current_obs/KMYF.xml"
move return-code to parser-handle
CALL "C$XML" using CXML-PARSE-NEXT-RECORD parser-handle
move return-code to record-handle

This option is more efficient than parsing entire files, but you must remember to parse the record before you try to retrieve its elements.

Creating a new parser

To create a new XML file, use the CXML-NEW-PARSER op-code. An empty file is opened, into which you can add children, siblings, attributes, and comments as described in the topic Adding Modifying or Deleting Data. Note that the file is not "created" until you write to the file using the CXML-WRITE-FILE op-code.

Parsing an XML string directly

If you get XML text from another source and need to parse it, you can parse the string directly using the CXML-PARSE-STRING op-code. You don't have to write the data to a file, then parse the file. You simply specify the string directly in the call. For example:

call "C$XML" using CXML-PARSE-STRING,
"<?xml version=""1.0""?><group1><subgroup1><item1>data</item1></subgroup1></group1>".
move return-code to parse-handle.

Then you can use the return code elsewhere in your program.

Parent topic: Using the C$XML Routine


Moving to an Element

Once a file has been opened and parsed, you can navigate the file in many different ways. In XML, you must move to an element of interest before you can retrieve its data. Listed below are several op-codes that you can call from the C$XML routine for this purpose. Be sure to specify the handle of the element or parser to move to, as in:

call "C$XML" using CXML-GET-FIRST-CHILD
                   parser-handle.
Op-code | Description
CXML-GET-FIRST-CHILD | Moves to the first child of an element
CXML-GET-NEXT-SIBLING | Moves to the subsequent sibling of an element
CXML-GET-PREV-SIBLING | Moves to the previous sibling; one way to move backward in a file
CXML-GET-PARENT | Moves to the parent; another way to move backward in a file

More advanced options include:

  • CXML-GET-CHILD-BY-NAME
  • CXML-GET-CHILD-BY-CDATA
  • CXML-GET-CHILD-BY-ATTR-NAME
  • CXML-GET-CHILD-BY-ATTR-VALUE
  • CXML-GET-SIBLING-BY-NAME
  • CXML-GET-SIBLING-BY-CDATA
  • CXML-GET-SIBLING-BY-ATTR-NAME
  • CXML-GET-SIBLING-BY-ATTR-VALUE

These options allow you to navigate to a specific child or sibling in an element rather than simply the next or previous one. Details are provided in General Syntax and Library List.

Note that these op-codes do not retrieve element data. They simply move to the element and return the element handle. Once you have the handle to the element of interest, you can call CXML-GET-DATA to retrieve the data associated with the element.

Note: If desired, you can retrieve element attributes and comments as well. See Retrieving attributes and Retrieving comments, for more information.
Parent topic: Using the C$XML Routine


Retrieving Data

To retrieve data from an element, you use the CXML-GET-DATA op-code. In this operation, you must specify the handle for the element of interest, down to the field level. You can obtain the handle by looking at the return code for the other operations, such as CXML-GET-SIBLING-BY-NAME. For example:

*Get the handle for the Weather element
   call "C$XML" using CXML-GET-SIBLING-BY-NAME
                   ele-1-handle
                   "weather"
                   0.
   move return-code to ele-2-handle.
*Get the weather data using that handle
   call "C$XML" using CXML-GET-DATA
                   ele-2 handle
                   throw-away-info
                   weather-val.

Once the XML data is returned, you can then pass it to other parts of your COBOL program for processing or display.

Parent topic: Using the C$XML Routine


Adding, Modifying, or Deleting Data

You can add, modify, or delete data in the XML document using any of the following C$XML op-codes:

  • CXML-SET-DATA
  • CXML-MODIFY-ATTRIBUTE
  • CXML-ADD-CHILD
  • CXML-ADD-SIBLING
  • CXML-ADD-ATTRIBUTE
  • CXML-ADD-COMMENT
  • CXML-APPEND-COMMENT (useful for documenting why you modified an XML document)
  • CXML-DELETE-ATTRIBUTE
  • CXML-DELETE-ELEMENT
  • CXML-DELETE-COMMENT

For the majority of these op-codes, you must pass the element handle as a parameter as well as the new value of that element or attribute. Other parameters may apply as well. See Library Routines for more details.

Parent topic: Using the C$XML Routine


Writing a File

If you modify the XML file in any way, you must write to the file in order for your changes to take effect. Use the CXML-WRITE-FILE op-code for this purpose. For example:

call "C$XML" using CXML-WRITE-FILE
                   parser-handle
                   "bookfile.xml"

You can write to the same file that you opened, or you can write to a new file. The filename that you specify can be anything you want. You cannot, however, write to a URL.

Note:

If you do not write to the file, your changes are lost.

Parent topic: Using the C$XML Routine


Releasing the Parser

When you are finished writing to the file, you are responsible for releasing the parser from memory. This operation is not performed automatically. To release the parser, use the CXML-RELEASE-PARSER op-code. For example:

call "C$XML" using CXML-RELEASE-PARSER
                   parser-handle.
Parent topic: Using the C$XML Routine


Retrieving Errors

If a return code from any other operation is "0" or "1", a call to C$XML has failed. To retrieve error information, call the CXML-GET-LAST-ERROR op-code. For example:

77 errors-storage PIC x(60).
77 errors-value PIC x(70).
.
.
.
CALL "C$XML" using CXML-GET-LAST-ERROR error-storage.
move "Err No:" to error-value(1:).
move return-code to errors-value(9:).
move errors-storage to errors-value(20:).
display message " " errors-value.

General Syntax and Library List lists all of the error codes that can be returned by this library routine.

Parent topic: Using the C$XML Routine


Retrieving Attributes

If desired, you can retrieve element attributes using one of the following C$XML op-codes:

Op-code | Description
CXML-GET-ATTRIBUTE-COUNT | Gets the number of attributes in an element
CXML-GET-ATTRIBUTE | Gets the next attribute
CXML-GET-ATTRIBUTE-BY-NAME | Gets the named attribute

Attributes have special characteristics:

  • Attributes don't have a handle; they are attached to the element handle for which they are an attribute.
  • There can be more than one attribute per element, thus more than one attribute per element handle.
  • You don't need to call CXML-GET-DATA to fetch the attribute data. The CXML-GET-ATTRIBUTE op-codes retrieve the data.

Before you use CXML-GET-ATTRIBUTE, we recommend that you use CXML-GET-ATTRIBUTE-COUNT. This op-code tells you how many attributes are in the element of interest. Then when you use CXML-GET-ATTRIBUTE, you know which attribute you are getting (the first attribute is number 0, the second number 1, etc.).

Alternatively, if you know the name of the attribute you want and not the number of the attribute, you can use CXML-GET-ATTRIBUTE-BY-NAME. If you have an unknown number of attributes like this:

Limousine xmlns:tsd="http://namespaces.softwareag.com/tamino/TaminoSchemaDefinition" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

and you are searching for a particular attribute, say "xmlns:xsi", you can search for the value with CXML-GET-ATTRIBUTE-BY-NAME, or you can get the count and read the attributes one by one searching for the one you want.

See General Syntax and Library List for more details on the CXML-GET-ATTRIBUTE op-codes.

Parent topic: Using the C$XML Routine


Retrieving Comments

You can obtain element comments using CXML-GET-COMMENT op-code. You don't need to call CXML-GET-DATA to fetch the comment data. The CXML-GET-COMMENT op-code retrieves the data.

Parent topic: Using the C$XML Routine


C$XML Examples

This section includes two sample files.

Sample 1: Open, parse, and read weather file

The following sample program calls an XML file from the National Weather Service Web site and retrieves weather data for use in a COBOL program. (It does not modify or write to the file in any way.)

*Retrieve the xml data and parse it
   call "C$XML" using CXML-PARSE-FILE
       "http://www.nws.noaa.gov/data/current_obs/KMYF.xml
   move return-code to parser-handle

*Move to the data item of the record, which is a
*child of the record name element.
   call "C$XML" using CXML-GET-FIRST-CHILD
                      parser-handle.
   move return-code to ele-1-handle

*Get the desired fields, which are all siblings of the first *child.  Get the handle to the desired sibling, then get the *data for that element using that handle.

*General outlook field
   call "C$XML" using CXML-GET-SIBLING-BY-NAME
                      ele-1-handle
                      "weather"
                      0
   move return-code to ele-2-handle
   call "C$XML" using CXML-GET-DATA
                      ele-2-handle
                      throw-away
                       weather-val.

*Temperature field
   call "C$XML" using CXML-GET-SIBLING-BY-NAME
                      ele-1-handle
                      "temperature_str"
                      0
   move return-code to ele-2-handle
   call "C$XML" using CXML-GET-DATA
                      ele-2-handle
                      throw-away
                      temp-val.

*Relative humidity field
   call "C$XML" using CXML-GET-SIBLING-BY-NAME
                      ele-1-handle
                      "relative_humidi"
                      0
   move return-code to ele-2-handle
   call "C$XML" using CXML-GET-DATA
                      ele-2-handle
                      throw-away
                      humid-val.

*Wind direction field
   call "C$XML" using CXML-GET-SIBLING-BY-NAME
                      ele-1-handle
                      "wind_dir"
                       0
   move return-code to ele-2-handle
   call "C$XML" using CXML-GET-DATA
                      ele-2-handle
                      throw-away
                       wind-dir.

*Wind speed field
   call "C$XML" using CXML-GET-SIBLING-BY-NAME
                      ele-1-handle
                      "wind_mph"
                      0
move return-code to ele-2-handle
   call "C$XML" using CXML-GET-DATA
                      ele-2-handle
                      throw-away
                       wind-mph.

*Visibility field
   call "C$XML" using CXML-GET-SIBLING-BY-NAME
                      ele-1-handle
                      "visibility"
                      0
   move return-code to ele-2-handle
   call "C$XML" using CXML-GET-DATA
                      ele-2-handle
                      throw-away
                       vis-val.

Sample 2: Create file, add elements and attributes, write data to file

The following sample shows how to create an XML file, add elements to it, and write data to the elements.

program-id. test.
working-storage section.
01 parser-handle usage is handle.
01 element-handle usage is handle.
COPY "acucobol.def".
procedure division.
main-logic.
*Create a new XML file
   call "C$XML" using CXML-NEW-PARSER
   move return-code to parser-handle.

*Add a top element (using the name of the file)
   call "C$XML" using CXML-ADD-CHILD
                  parser-handle
                  "custRec"
   move return-code to element-handle.

*Add some namespace information
   call "C$XML" using CXML-ADD-ATTRIBUTE
                  element-handle
                  "xmlns:xsi"
                  "http://www.w3.org/2001/XMLSchema-instance".

*Add the first field of the record, which will be a child of
*the last element.
   call "C$XML" using CXML-ADD-CHILD
                  element-handle
                  "cus-key"
                  "555-55-5555"
   move return-code to element-handle.

*Add the rest of the record
   call "C$XML" using CXML-ADD-SIBLING
                  element-handle
                  "cus-name"
                  "Acucorp"
   move return-code to element-handle.

   call "C$XML" using CXML-ADD-SIBLING
                  element-handle
                  "cus-addr"
                  "8515 Miralani Drive"
   move return-code to element-handle.

   call "C$XML" using CXML-ADD-SIBLING
                  element-handle
                  "cus-city"
                  "San Diego"
   move return-code to element-handle.

   call "C$XML" using CXML-ADD-SIBLING
                  element-handle
                  "cus-state"
                  "CA"
   move return-code to element-handle.

   call "C$XML" using CXML-ADD-SIBLING
                  element-handle
                  "cus-zip"
                  "92126"

*write the file
   call "C$XML" using CXML-WRITE-FILE,
                  parser-handle
                  "custRec.xml".
   call "C$XML" using CXML-RELEASE-PARSER,
                  parser-handle.
   stop run.
Parent topic: Using the C$XML Routine


Using XML Extensions

XML Extensions allows ACUCOBOL-GT applications to interoperate freely and easily with other applications that use the Extensible Markup Language (XML) standard. To accomplish this, XML Extensions leverages the similarities between the COBOL data model and the XML data model in order to turn ACUCOBOL-GT into an XML engine. Of primary importance to this goal is the ability to import and export XML documents to and from standard COBOL data structures.

Note: A COBOL data structure, as used in this document, is a COBOL data item. The data item is frequently, but not necessarily, an 01 record-name. In general, it is a group data item, but in some cases, it may be a single elementary data item. The ACUCOBOL-GT compiler generates and embeds an XML-format symbol table in the COBOL object file when the -Ze compilation option is specified. The XML-format symbol table is used to import and export data at runtime. This XML-format symbol table is sometimes referred to in this document as the template or model.

Extensible Stylesheet Language Transformations (XSLT) of the XML data representation can be used to match XML element names to COBOL data-names in situations where the names and/or document structures differ.

By allowing standard COBOL data structures to be imported from and exported to XML documents, XML Extensions enables the direct processing and manipulation of XML-based electronic documents by the ACUCOBOL-GT application programmer. Furthermore, XML Extensions does this without requiring the application programmer to become thoroughly familiar with the numerous XML-related specifications and the time-consuming process required to emit and consume well-formed XML.

Specifically, an XML document may be imported into a COBOL data structure under COBOL program control using a single, simple COBOL statement, and, similarly, the content of a COBOL data structure may be used to generate an XML document with equal simplicity. XML Extensions' approach handles both simple and extremely complex structures with ease. Individual data elements are automatically converted as needed between their COBOL internal data types and the external coding used by XML. Not only can the transition to and from XML take place when this happens, but powerful transforms, which are coded using XSLT, can be applied at the same time. This mechanism gives XML Extensions the capabilities needed to be useful in a wide range of e-commerce and Web applications.

To add this capability to a COBOL application, the programmer need only describe the information to be received or transmitted to the external components as COBOL data definitions. This description is not required to match the XML document and, in many cases, this description will simply be an already-existing data area defined in the COBOL application.

Tip: The sample\xmlext directory of your installation contains numerous samples that use XML Extenstions and Xcentrisity BIS.
  • Typical Development Process Example
  • COPY Files Simplify Coding
  • Data Representation
  • COBOL and Character Encoding
  • XML Extension Examples
    XML Extension Examples.
Parent topic: Working with XML Data


Typical Development Process Example

The basic steps to developing an XML-enabled application are as follows:

  1. Design the COBOL data structure and program logic. Develop a COBOL program, or modify an existing one, using XML Extensions statements. (Note that it is quite reasonable to use a data structure that already exists in your application. In this case, you would create an XSLT transformation to adapt the existing data structure to the requirements of the XML document.)
  2. Make sure the lixml*.cpy copy files are accessible to the compiler; this can be done by setting the COPYPATH environment variable to include the sample/xmlext directory from the installation directory in the search sequence for copy files. See COPY Files Simplify Coding for more information.

    Compile the program. Use the -Ze compilation option which results in the production of the XML-format symbol table.

  3. Run the COBOL program. On Windows use -y xmlif.dll. On UNIX use -y xmlif.so. Test the program and repeat steps 1 and 2, as necessary.
  4. Deploy the application. Distribute the XML Extensions deployable files. These files consist of the xmlif library (the DLL on Windows or shared object on UNIX) and the underlying XML parser that the xmlif library uses (MSXML 6 on Windows; the libxml2 parser is linked with the xmlif library on UNIX).
Parent topic: Using XML Extensions


COPY Files Simplify Coding

The interface to the XML Extensions library is through COBOL CALL statements. Developing code for this interface is simplified by the use of source text replacement and data values contained in COBOL copy files described below. These copy files are located in the sample/xmlext directory of your installation.

Code developed using the suggested source text replacement will produce XML Extensions source code that appears more like standard COBOL procedural statements.

Documentation for the XML Extensions library is in terms of these suggested source text replacements, rather than the underlying COBOL CALL statements.

lixmlall.cpy | Required to define the XML statements and to define some data-items that are referenced. This copy file should be copied at the beginning of the Working-Storage Section of the source program. This copy file copies the other copy files used by XML Extensions. In general, do not modify or edit the contents of this copy file or the copy files that it copies (lixmdef.cpy and lixmlrpl.cpy).
lixmlrpl.cpy | Replacement strings used in the REPLACE statement contained in lixmlall.cpy.
lixmldef.cpy | XML Extensions data definitions.
lixmldsp.cpy | Optional COPY file used with lixmltrm.cpy to display the result status of an XML Extensions operation.
lixmltrm.cpy | Optional COPY file which may be used to display the status of an XML Extensions operation, and then terminate XML Extensions.

These copy files are located in the sample/xmlext directory of your installation.

Note that the COBOL language standard allows only one COBOL REPLACE statement to be in effect at a time; a COBOL REPLACE statement overrides any lexically preceding REPLACE statement. Thus, in cases where the program contains a REPLACE statement, it may not be possible to use the lixmlall.cpy file. Instead, the existing REPLACE statement may be augmented by copying lixmlrpl.cpy into the REPLACE statement as follows:

REPLACE
  *> include user’s replacements here
  COPY "lixmlrpl.cpy”.  *> define XML statements
  . *> end of combined REPLACE statement

COPY "lixmldef.cpy".  *>  XML data definitions

When this is done, the lixmlall.cpy file need not be copied in the source program.

An alternative solution to the REPLACE statement issue is to isolate the XML Extensions statements in a new COBOL subprogram. The data structures to be imported or exported can be passed as CALL statement parameters to the linkage section of this new subprogram. XML Extensions searches the caller's symbol table for the description (ModelDataName) of the item actually being imported or exported and thus can properly import or export from the linkage section item.

The lixmltrm.cpy and lixmldsp.cpy COPY files may be used together to supply an orderly shutdown of an XML Extensions application; note this is optional and may not be useful in all situations. The appropriate way to combine these COPY files is as follows:

Z.
Copy "lixmltrm.cpy".
    Stop Run.
Copy "lixmldsp.cpy".

(Z is a paragraph-name where the shutdown logic begins.)

Parent topic: Using XML Extensions


Data Representation

COBOL numeric data items are exported to XML as numeric strings. A leading minus sign is added for negative values. Leading zeros (those appearing to the left of the decimal point) are removed. Non-significant trailing zeros (those appearing to the right of the decimal point) are likewise removed. If the value is an integer, no decimal point is present in the XML numeric string. The decimal point in XML numeric items is always represented with .; thus if the COBOL program is using DECIMAL POINT IS COMMA, this conversion is also handled by XML Extensions.
Note: Numeric edited data items are treated as nonnumeric by XML Extensions and thus are exported according to the following paragraph.

COBOL nonnumeric data items are exported to XML as text strings and have trailing spaces removed. (If the item is described with the JUSTIFIED phrase, leading spaces are also removed.) Note, however, that for edited and FILLER data items, leading and trailing spaces are preserved. In addition, any embedded XML special characters not in FILLER data items are represented by escape sequences; the ampersand (&), less than (<), greater than (>), quote ("), and apostrophe (') characters are examples of such XML special characters.

XML strings are imported to COBOL numeric items by storing the algebraic value of the string into the COBOL numeric data item per the rules for its data description. A data conversion error will occur if the XML string does not represent a valid numeric value. (Note: Numeric edited data items are treated as nonnumeric by XML Extensions and thus are imported per the following paragraph.)

XML strings are imported to COBOL nonnumeric items by removing leading and trailing spaces from the XML string and storing the result either left or right justified, depending on the data description of the receiving item. However, for edited and FILLER data items, leading and trailing spaces in the XML string are preserved and no editing is performed when storing into an edited data item. XML escaped characters in the string are converted back to the represented character before storing the string value.

On Windows platforms, nonnumeric displayable data are normally encoded using Microsoft's OEM or ANSI data format. On output, these data are converted to the standard Unicode 8-bit transformation format , UTF-8. On input, data is converted to the OEM or ANSI data format. If the XML SET ENCODING statement is used to specify UTF-8, then the internal data format is UTF-8.

On UNIX platforms, nonnumeric displayable data are normally encoded using a local character encoding that the UNIX system uses. Typically, this may be Latin-1 or Latin-9. On output, these data are converted to the standard Unicode 8-bit transformation format, UTF-8. On input, data is converted to the systems internal format. If the XML SET ENCODING statement is used to specify UTF-8, then the internal data format is UTF-8.

Parent topic: Using XML Extensions


COBOL and Character Encoding

XML Extensions uses UTF-8 character encoding for exporting XML documents. (UTF-8 is a byte-oriented encoding form of Unicode that has been designed for ease-of-use with existing ASCII-based systems.) Imported documents are interpreted according to the character encoding specified in the XML header, resulting in an internal Unicode representation of the characters. Because XML is Unicode-based and ACUCOBOL-GT is not, a transcoding is generally required when moving character data between COBOL and XML. XML Extensions supports various means of specifying the transcoding that should occur in these cases. The following sections have related information regarding character encoding considerations.

The COBOL_CHARACTER_SET runtime configuration variable is used to determine the local character encoding on Windows.

The A_XMLIF_ENCODING runtime configuration variable is used to specify the local character encoding on UNIX. This environment variable is ignored if the XML SET ENCODING statement sets the encoding to UTF-8.

Windows Character Encoding

Under Windows, the runtime uses OEM or ANSI character encoding. Therefore, the Windows implementation also supports OEM or ANSI character encoding for local character encoding. The COBOL_CHARACTER_SET runtime configuration variable is used to determine ANSI or OEM encoding (other values are ignored, and the data is returned in UTF-8 encoding). (The A_XMLIF_ENCODING runtime configuration variable is ignored by the Windows implementation of XML Extensions.)

Note: Microsoft originally introduced OEM character encoding for MS-DOS. While there are multiple OEM code pages in use, the Windows operating system provides interfaces that allow conversion between the OEM code page in use and Unicode. XML Extensions does not need to differentiate between OEM code pages.

The ANSI code page is the default local character set of the runtime, in which case, XML Extensions uses the ANSI code page in use for the conversion to/from Unicode when using the local character encoding.

UNIX Character Encoding

On UNIX systems, the runtime is normally not concerned with the data encoding used by the underlying operating system. However, Latin-1 (ISO-8859-1) is important for the U.S. and Latin-9 (ISO-8859-15) is significant for Western Europe because it contains the Euro currency symbol.

The A_XMLIF_ENCODING runtime configuration variable may specify the built-in and predefined values of XMLIF_LATIN_1 and XMLIF_LATIN_9. These values are used to designate that either Latin-1 or Latin-9 is being used as the local character encoding. Internal translation functions convert between either Latin-1 or Latin-9 (in COBOL memory) and UTF-8 (in the XML document). The value of the environment variable is case insensitive, with hyphen and underscore characters being optional. For example, XMLIF_LATIN_9, xmlif-Latin-9, and xmliflatin9 are equivalent.

If the value of the A_XMLIF_ENCODING runtime configuration variable is not specified, then XMLIF_LATIN_9 is used as the default.

If the value of the A_XMLIF_ENCODING runtime configuration variable is specified with a value that is neither equivalent to XMLIF_LATIN_1 nor XMLIF_LATIN_9, then the value that is passed must be a name recognized by the iconv library. The iconv library can perform other conversions. In this case, the spelling may need to be exact (for example, the value may be case sensitive, and hyphens and underscores would be required). The exact spelling of the value of the A_XMLIF_ENCODINGruntime configuration variable is specific to the iconv library on the platform in use.

Note: An iconv library is not provided. The developer must acquire an appropriate package.

The value of the A_XMLIF_ICONV_NAME runtime configuration variable, if one is defined, is used to locate the iconv library (which must be a shared object) on the local system. For example:

 A_XMLIF_ICONV_NAME=/usr/local/bin/libiconv.so

If the A_XMLIF_ICONV_NAME runtime configuration variable is not set, then the PATH environment variable is searched for either of the specific names, iconv.so or libiconv.so (in that order).

Parent topic: Using XML Extensions
Related reference
COBOL_CHARACTER_SET


XML Extension Examples

XML Extension examples are found in the sample\xmlext directory.

Document Generation

Modern applications often produce PDF documents. Apache FOP (Formatting Objects Processor) is a print formatter driven by XSL formatting objects (XSL-FO) and an output independent formatter. Apache FOP is an open source project of The Apache Software Foundation licensed under the terms of the Apache License, Version 2.0, which permits redistribution under friendly terms to an application developer. Binary distributions of Apache FOP are available for many popular platforms. See http://xmlgraphics.apache.org/fop/ for more information.

XSL Formatting Objects (XSL-FO) is a standardized, XML-based technology for describing output documents. As such, it is excellent to use with XML Extensions. The examples that use XSL are Envelop, Microsoft Office and OpenOffice documents, and HTML: form-url-encoded.

  • XML Extensions - Bar Chart
    Shows a simple bar chart example, using a method to color the bars. The XSLT stylesheet uses several standard techniques to ‘draw’ the bar chart.
  • XML Extensions - Stacked Bar Chart
    Building on the bar chart example, a stacked bar chart (StackedGraph.cbl) adds a nested OCCURS in the data.
  • XML Extensions - Pie Chart
    A pie chart is more involved than the bar chart, since trigonometry is involved.
  • XML Extensions - Gauge
    This widget has several features that make it useful in a dashboard mashup.
  • XML Extensions - Scalable Vector Graphics Widget Applets
    For users who use Xcentrisity BIS to return SVG widgets to a browser dashboard mashup.
  • XML Extensions - United States Postal Service Bar Codes
    This is an example of a United States Postal Service bar code used to sort and track letters and flats.
  • XML Extensions - Casino Floor Simulation
    This data visualization example is a simulation of a casino slot machine floor diagram.
  • XML Extensions - Envelop
    This is a simple illustration of the power of XSL-FO.
  • XML Extensions - Microsoft Office and OpenOffice Documents
    This example uses XML to create and/or consume documents for these products.
  • XML Extensions - HTML: form-url-encoded
    This example uses a call to an extend web service to process an HTML form request
Parent topic: Using XML Extensions


XML Extensions - Bar Chart

A bar chart (SimpleGraph.cbl) is the first example. It is purposely simple, with the exception of the method used to color the bars. In many ways this example violates the principle of separation of data from the presentation layer. However, instead of specifying a bar color, an ‘urgency’ is specified for each data value. The XSLT stylesheet, which transforms the data into the SVG image of a bar chart, translates ‘urgency’ into a color.

The XSLT stylesheet uses several standard techniques to ‘draw’ the bar chart, including recursion for layout of various elements. The urgency is translated to a color in the template that matches graph-bar, in the computation of the bar_color variable. A second XML document, named urgency.xml, is used to look up the urgency number and place the corresponding color name as the value of $bar_color.

Parent topic: XML Extension Examples


XML Extensions - Stacked Bar Chart

Building on the bar chart example, a stacked bar chart (StackedGraph.cbl) adds a nested OCCURS in the data. The XSLT stylesheet becomes more complex because you must stack colored rectangles.

Parent topic: XML Extension Examples


XML Extensions - Pie Chart

A pie chart is more involved than the bar chart, since trigonometry is involved. From the data side, though, there is little difference between a pie chart and a simple bar graph, so the COBOL program (piechart.cbl) is similar to the Bar Chart example. The XSLT stylesheet, piechart.xsl, is adapted from several examples found on the web.

Note: For this stylesheet to work, you need trignm.xsl which can be found at http://fxsl.sourceforge.net. This example was tested with the version of trignm.xsl found in fxsl-MS-1.1.zip (see the download area of the referenced site). FXSL has an accumulation of XSLT knowledge.
Parent topic: XML Extension Examples


XML Extensions - Gauge

Because of dashboard popularity, gauge widgets are popular. This widget has several features that make it useful in a dashboard mashup. While bar charts and pie charts can display many values, a gauge generally shows only one value, or a very few values at most. Therefore, most of the gauge control resides with the presentation, rather than data values. This widget allows up to nine pointers, and the data presented is the percent-of-scale value. In addition, you can divide scales into different colored segments The gauge example (gauge.cbl) uses the familiar red-yellow-green segmentation.

Note: For this stylesheet to work, you need trignm.xsl which can be found at http://fxsl.sourceforge.net. This example was tested with the version of trignm.xsl found in fxsl-MS-1.1.zip (see the download area of the referenced site). FXSL has an accumulation of XSLT knowledge.
Parent topic: XML Extension Examples


XML Extensions - Scalable Vector Graphics Widget Applets

You may use Xcentrisity BIS to return SVG widgets to a browser dashboard mashup. SVG has an assigned MIME type, so the appropriate ContentType tag is {{ContentType image/svg+xml}}. To set up this applet, use or create a directory served by BIS for the gauge applet, and copy the following files to that directory:

  • cblconfig.txt
  • drawgauge.xsl
  • gaugeApplet.acu
  • gaugeApplet.srf
  • and trignm.xsl (see the Gauge topic for instructions on obtaining trignm.xsl.)

Then, fetch the applet via the .srf file. For example, if the applet is installed in a directory named gauge in the samples directory, you would direct the browser to http://localhost/acuxbis/samples/gauge/gaugeapplet.srf.

Parent topic: XML Extension Examples


XML Extensions - United States Postal Service Bar Codes

The Intelligent Mail bar code, formerly known as the 4-State Customer bar code, is a United States Postal Service bar code used to sort and track letters and flats. The Postal Service promotes using the Intelligent Mail bar code because it expands individual mail piece tracking and provides customers with greater visibility into the mail stream. However, creating the bar code is complex and uses bit manipulations not familiar in COBOL. USPS provides a subprogram for several platforms, but an ‘all COBOL’ solution is more portable. extend provides logical bit manipulation capabilities in its subprogram library. The example contained in xmlext\USPSBarcodes uses these capabilities to implement the algorithm set forth in USPS-B-3200, without using the USPS provided DLL and shared object.

A test program is also enclosed that demonstrates results identical to the main examples found in USPS- B-3200. The resulting character string may be used directly with USPS provided bar code fonts. The test program also demonstrates the use of an XSL stylesheet to produce an SVG graphics document rendering the bar code for XML/SVG capable rendering engines. Finally, the test program confirms that all successful test cases found in the USPS encoder reference set produce identical character strings.
Note: This all-COBOL implementation may not be appropriate for high-volume mailers. Better performance might be obtained by using the USPS supplied DLL/shared objects. This implementation was tested only to ascertain conformance with the examples provided in USPS-B-3200 and the reference set found in the file uspsIMbEncoderTestCases.xml, which can be downloaded from the link uspsReferenceSetEncoder1.0.0.zip located at https://ribbs.usps.gov/onecodesolution/download.cfm.
Parent topic: XML Extension Examples


XML Extensions - Casino Floor Simulation

This data visualization example is a simulation of a casino slot machine floor diagram. It illustrates the use of a more complicated SVG document which is dynamically modified using JavaScript/ECMAScript. BIS for extend is used to provide machine state change information. To set up this applet, create a directory served by BIS for extend and unzip the contents of FloorPlan.zip into this directory. For the purpose of the following description, this directory is assumed to be C:\inetpub\wwwroot\acuxbis\samples\simulation.

Note: The JavaScript contained in this example assumes this directory naming. Be sure to change the JavaScript if you decide to use a different directory name.

The SVG that contains the floor plan is named floorplan.svg. The creation of this SVG is not covered in this example, but you can inspect the design of this document (using a text editor) to see the approach taken. The document has three main sections. The first contains the JavaScript necessary to produce the dynamic modification of the SVG. The second section is surrounded by the <defs>…</defs> XML tags. This section contains definitions of the icons and buttons which are used in the third section. The third section is surrounded by <g id=”FloorPlan”> … </g> XML tags, and contains several hundred <use> XML elements. Each <use> element is identified by an id attribute that contains a machine name.

Each of the <use> tags in the third section also contains an attribute named xlink:href. This attribute is used to refer to elements in the <defs> section, specifically by referring to the id attribute of a <g> tag subordinate to the <def> tag. In this manner, icons defined in the second section can be used repeatedly in the third section, thereby reducing the complexity of the overall SVG document. The xlink:href attribute also supplies the means to change the icon dynamically. The JavaScript in the first section starts a recurring timer to obtain updates from a web service every few seconds. The changes, consisting of machine name/state name pairs, are delivered to the function updateMachineState in the form of JavaScript Object Notation (JSON), which parses the JSON. Then, for each machine name/state name pair, the xlink:href attribute for the <use> element for the machine name is updated to contain the new state name.

A BIS for extend web service program, mstate.acu , provides a simulation of machine state changes. This program maintains a set of machine names in an XML document, machines.xml. Each time a web service request is made by the JavaScript running in the browser, mstate.srf uses mstate.acu to return a small set of randomly generated machine state changes. The XSLT stylesheet, statechangejson.xsl, creates the JSON representation of the data exported from the state-changes group item.

Note: Several third-party open source tools were used in the creation of this example. The ECMAScript network library was obtained from carto:net (www.carto.net) and is provided under the LGPL license. The machine state icons were created using Inkscape, an open source vector graphics editor for the desktop (www.inkscape.org). The bigger/smaller/normal buttons were created using svg-edit, a browser-based, JavaScript driven SVG editor (http://code.google.com/p/svg-edit/). Table Trac, Inc. (http://www.tabletrac.com ) provided the original concept of the casino floor plan, which is used with permission.
Parent topic: XML Extension Examples


XML Extensions - Envelop

This sample provides a simple illustration of the power of XSL-FO. The extend program creates an XML document containing the data used to address an envelope, and then uses CALL “C$SYSTEM” to invoke the Apache FOP processor.

Note: This sample program was created on Windows, and the Apache FOP processor binary distribution is assumed to be installed in C:\FOP. To use this example on Linux or UNIX, you must make two changes to the CALL C$SYSTEM statement:
  • A change to reflect the differences in CALL “C$SYSTEM” between Windows and Linux/UNIX.
  • A change to reflect the differences in installation of the Apache FOP binary distribution.

The sample data is exported from the COBOL program to envelope.xml. The Apache FOP process uses envelope.xml as its input document, transforming the input document using the XSL style sheet envelope.xsl, to produce the resulting PDF document, envelope.pdf. The XSL style sheet imports two other XSL style sheets, postnet.xsl and postnet-svg.xsl, which create the POSTNET bar code (using SVG graphics) for the addressee. The XSL style sheet also uses the JPEG file, MicroFocusLogo.jpg, to show how to include graphical elements in the output document.

Several commercial products are available to assist in creating an XSL style sheet that converts the data from XML to XSL-FO (envelope.xsl in the example). To find these products enter the search term XSL-FO WYSIWYG in a search engine. An XSL style sheet is a text document, so use a text editor to modify existing XSL style sheets, or to create style sheets for simple documents.

Parent topic: XML Extension Examples


XML Extensions - Microsoft Office and OpenOffice Documents

Microsoft Office and OpenOffice documents have closely related XML document formats. While these XML documents can become complex, using XML is probably the easiest mechanism to create and/or consume documents for these products. (See http://msdn.microsoft.com/en-us/library/aa338205%28office.12%29.aspx for additional information about Microsoft Office Open XML Formats, and http://xml.openoffice.org/#ODF for additional information about OpenOffice OASIS/ISO standard document formats.)

A simple way for creating Microsoft Office XML documents is creating a document using sample placeholder data. After examining the XML document, add XSLT processing instructions to the XML document to create an XSLT stylesheet that places values supplied by your extend application program during an XML EXPORT FILE into the overall structure of the sample document.

The sample XMLSpreadsheet is an example of creating Office documents. Copy the files from XMLSpreadsheet into a directory that is served by BIS for extend. For the purpose of the following description, this directory is assumed to be C:\inetpub\wwwroot\acuxbis\samples\XMLSpreadsheet.

A spreadsheet was created using Microsoft Excel 2007 and four placeholder data values. A formula was also included (summing the four values) to illustrate XML document capabilities.. The spreadsheet was saved using Save As > Other Formats and selecting ‘XML Spreadsheet 2003’ as the Save as type. The result is Book1.xml, located in the bin directory. Book1.xml is copied to numbers_to_xmlss.xsl. Using a text editor, XSLT processing instructions were added to numbers_to_xmlss.xsl to turn it into an XSLT stylesheet. You can see the extent of the changes in the difference.txt file.

A sample BIS extend service program was derived from tutorial3.cbl (which was functionally similar to the behavior desired for the spreadsheet applet) to produce getss.cbl. Similarly, tutorial3.srf was used to create GetXMLSS.srf, which was changed to call getss.acu in the {{StartService}} tag and add a {{ContentType}} tag. A significant amount of debug output was included in the COBOL program, both as tracing in the trace file (DISPLAY … UPON SYSERR) and as intermediate XML files which illustrate the changes created by the XSLT being used. The applet looks for query parameters named N1, N2, N3 and N4, and substitutes the numeric values associated with those query parameters for the default values of 1, 2, 3 and 4. You can view the spreadsheet applet in two ways, by fetching the spreadsheet directly using Microsoft Excel or indirectly by using a browser.

To view directly from Microsoft Excel, Start Microsoft Excel 2007 and select Open. In the Filename field, paste http://localhost/acuxbis/samples/XMLSpreadsheet/GetXMLSS.srf?N1=5&N2=10&N3=15&N4=20
Note: If Microsoft Excel warns that the srf type is a different format, click Yes to allow the spreadsheet to load. You can eliminate this warning on a per-machine basis by changing your registry to add the following registry value: [HKEY_CURRENT_USER\Software\Microsoft\Office\12.0\Excel\Security] "ExtensionHardening"=dword:00000000 Likewise, you can eliminate the warning with a group policy. However, be aware that you will eliminate a warning that may be useful at times.

To view directly from a browser, use a compatible browser, such as Firefox or Opera, and enter the URL used above when opening the applet directly from Microsoft Excel. The browser recognizes the content type and suggests an appropriate application for opening the response data. Change the values of the query parameters N1, N2, N3 and N4 to see that the data changes in the returned spreadsheet, and also to see the formula recalculation by Microsoft Excel (not the extend service program).

Parent topic: XML Extension Examples


XML Extensions - HTML: form-url-encoded

You can call an extend web service to process an HTML form request, which is transmitted using the form-url-encoded encoding.

For example, web applications using REST architecture are not constrained to SOAP web services or simple applets. BIS places the form variables inside the <bis:content> element of the BIS request document (exchange file), with the form variable name as the name of an element, and the form variable value as the value of that element.

Use the XSLT stylesheet, form_post_to_cobol.xsl, provided in the BIS samples/common directory to simplify import of form-url-encoded content from the exchange file. This XSLT creates an import targeted at a group named form-request-response, but you can override this name by specifying an XSL Parameter named Document_Element prior to the XML IMPORT FILE.

form_post_to_cobol.xsl needs form variables to follow a specific format. In the simplest form, the form variable name is translated directly to the COBOL name, and underscore characters in the form variable name are translated to hyphens. If the form variable name contains a double underscore, the characters before the double underscore are translated to the COBOL element name, and the characters (digits) after the double underscore are converted to a subscript. This naming translation enables importing of form variables (as might be present in an HTML table) into a COBOL array.

Parent topic: XML Extension Examples


XML Extensions Statement Reference

XML Extensions statements are grouped into the following categories:

  • Document Processing Statements. These statements are used to process, manipulate, or validate XML documents.
  • Document Management Statements. These statements are used to copy an XML document from an external file to an internal text string and vice versa.
  • Directory Management Statements. These statements are useful when implementing directory-polling schemes.
  • State Management Statements. These statements are used to control the state or condition of XML Extensions statements .
Note: Each statement contains zero or more positional parameters. These parameters are used to specify such items as the source or destination data item, source or destination XML document, and flags. In some statements, trailing positional parameters are optional and may be omitted, as specified in the statement descriptions below.
  • Document Processing Statements
  • Document Management Statements
  • Directory Management Statements
  • State Management Statements
Parent topic: Working with XML Data


Document Processing Statements

Document processing statements are used to process, manipulate, or validate XML documents. They are grouped by function as follows:

  • Export statements. XML EXPORT FILE and XML EXPORT TEXT are available to convert the content of a COBOL data item to an XML document that may be represented as an external file or an internal text string.
  • Import statements. XML IMPORT FILE and XML IMPORT TEXT are available to convert the content of an XML document-either an external file or an internal text string-to a COBOL data item.
  • Test and validation statements. XML TEST WELLFORMED-FILE, XML TEST WELLFORMED-TEXT, XML VALIDATE FILE, and XML VALIDATE TEXT are available to verify that an XML document-either an external file or an internal text string-is well-formed or valid with respect to a specified schema.
  • Transformation statements. XML TRANSFORM FILE and XML TRANSFORM TEXT transform an XML document in an external file or internal text into a new external file or internal text by applying an XSLT stylesheet. The resulting file or internal text may have almost any form, including XML, HTML, PDF, RTF, and so forth.
  • XML EXPORT FILE
  • XML EXPORT TEXT
  • XML IMPORT FILE
  • XML IMPORT TEXT
  • XML TEST WELLFORMED-FILE
  • XML TEST WELLFORMED-TEXT
  • XML TRANSFORM FILE
  • XML TRANSFORM TEXT
  • XML VALIDATE FILE
  • XML VALIDATE TEXT
Parent topic: XML Extensions Statement Reference


XML EXPORT FILE

This statement has the following parameters:

Parameter | Description
DataItem | Identifier of the COBOL data item that contains the data to be exported. (Since this represents a sending item, it can be a literal, but since the value must conform to the structure specified by the ModelDataName parameter, this would rarely to never be meaningful in an actual XML Extensions application.)
DocumentName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of a file that will contain the exported XML document upon successful completion of this statement. If an extension is not specified in the filename, the extension .xml is appended to the specified filename.
ModelDataName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the name of the model data structure. (Note, this is often the same 'name' that is specified in DataItem, but as a literal enclosed in quotation marks). If the name is not found in the symbol table of the current program, then the symbol tables in the calling programs are searched in order of the call stack from nearest to farthest caller. The name may include qualifiers using // as a separator. The specification A//B//C is equivalent to the COBOL specification C OF B OF A. The top-level qualifier (A in the preceding example) may be a program-name when the name is specific to a particular program in the call stack.
[StyleSheetName] | Optional. Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of an XSLT stylesheet file to be used to transform the generated XML document before it is stored. If an extension is not specified in the filename, the extension .xsl is appended to the specified filename.

Description

The XML EXPORT FILE statement exports the content of the COBOL data item indicated by the DataItem parameter. The content of the data item is converted to an XML document using the structure of the ModelDataName parameter. The output of this conversion is to the file specified by the DocumentName parameter. If the optional StyleSheetName parameter is present, the specified XSLT stylesheet is used to transform the document after it has been generated but before it is stored in the data file.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Examples

XML EXPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT"
    "MY-DATA-ITEM".
IF NOT XML-OK GO TO Z.

XML EXPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-DATA-ITEM"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.

XML SET XSL-PARAMETERS
     "MY-COUNT", 7,
     "MY-NAME”, "Henry”.
IF NOT XML-OK GO TO Z.
XML EXPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-DATA-ITEM"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z
Parent topic: Document Processing Statements
Related information
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML EXPORT TEXT

This statement has the following parameters:

Parameter | Description
DataItem | Identifier of the COBOL data item that contains the data to be exported.
DocumentPointer | Identifier of a COBOL pointer data item that will point to the generated XML document as a text string after successful completion of this statement.
DocumentLength | Identifier of a COBOL numeric data item that will contain the length of the generated XML document after successful completion of this statement.
ModelDataName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the name of the model data structure. (Note, this is often the same 'name' that is specified in DataItem, but as a literal enclosed in quotation marks). If the specified name is not found in the symbol table of the current program, then the symbol tables in the calling programs are searched in order of the call stack from nearest to farthest caller. The name may include qualifiers using // as a separator. The specification A//B//C is equivalent to the COBOL specification C OF B OF A. The top-level qualifier (A in the preceding example) may be a program-name when the name is specific to a particular program in the call stack.
[StyleSheetName] | Optional. Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of an XSLT stylesheet file to be used to transform the generated XML document before it is stored. If an extension is not specified in the filename, the extension .xsl is appended to the specified filename.

Description

The XML EXPORT TEXT statement exports the content of the COBOL data item indicated by the DataItem parameter. The content of the data item is converted to an XML document using the structure of the ModelDataName parameter. The address of the resulting text string is placed in the COBOL pointer data item specified by the DocumentPointer parameter, and the length of the resulting text string is placed in the numeric data item specified by DocumentLength. If the optional StyleSheetName parameter is present, the specified XSLT stylesheet is used to transform the document after it has been generated but before it is stored as a text string.

A block of memory is allocated to hold the exported XML document. The COBOL application is responsible for releasing this memory when it is no longer needed by using XML FREE TEXT.

A status value is returned in the data item XML-Status of XML-data-group , which is defined in the copy file lixmldef.cpy.

Examples

XML EXPORT TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-DATA-ITEM"
IF NOT XML-OK GO TO Z.

XML EXPORT TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-DATA-ITEM"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.

XML SET XSL-PARAMETERS
     "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
XML EXPORT TEXT
   MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-DATA-ITEM"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.
Parent topic: Document Processing Statements
Related information
XML EXPORT FILE
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML IMPORT FILE

This statement has the following parameters:

Parameter | Description
DataItem | Identifier of the COBOL data item that is to receive the data being imported.
DocumentName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of a file that contains the XML document to be imported. If an extension is not specified in the filename, the extension .xml is appended to the specified filename.
ModelDataName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the name of the model data structure. (Note, this is often the same 'name' that is specified in DataItem, but as a literal enclosed in quotation marks). If the name is not found in the symbol table of the current program, then the symbol tables in the calling programs are searched in order of the call stack from nearest to farthest caller. The name may include qualifiers using // as a separator. The specification A//B//C is equivalent to the COBOL specification C OF B OF A. The top-level qualifier (A in the preceding example) may be a program-name when the name is specific to a particular program in the call stack.
[StyleSheetName] | Optional. Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of an XSLT stylesheet file to be used to transform the XML document before it is imported. If an extension is not specified in the filename, the extension .xsl is appended to the specified filename.

Description

The XML IMPORT FILE statement imports the content of the file indicated by the DocumentName parameter. If the optional StyleSheetName parameter is present, the specified XSLT stylesheet is first used to transform the document. The content of the resulting document is converted to COBOL format using the structure of the ModelDataName parameter and then is stored in the data item specified by the DataItem parameter.

A status value is returned in the data item XML-Status of XML-data-group , which is defined in the copy file lixmldef.cpy.

Examples

XML IMPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT"
    "MY-DATA-ITEM".
IF NOT XML-OK GO TO Z.

XML IMPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-DATA-ITEM"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.

XML SET XSL-PARAMETERS
     "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
XML IMPORT FILE
    MY-DATA-ITEM
    "MY-DOCUMENT.XML"
    "MY-DATA-ITEM"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z
Parent topic: Document Processing Statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML IMPORT TEXT

This statement has the following parameters:

Parameter | Description
DataItem | Identifier of the COBOL data item that is to receive the imported data.
DocumentPointer | Identifier of a COBOL pointer data item that points to an XML document stored in memory as a text string.
DocumentLength | Numeric literal or identifier of a COBOL numeric data item that specifies the length of the XML document stored in memory as a text string.
ModelDataName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the name of the model data structure. (Note, this is often the same 'name' that is specified in DataItem, but as a literal enclosed in quotation marks). If the name is not found in the symbol table of the current program, then symbol tables in the calling programs are searched in order of the call stack from nearest to farthest caller. The name may include qualifiers using // as a separator. The specification A//B//C is equivalent to the COBOL specification C OF B OF A. The top-level qualifier (A in the preceding example) may be a program-name when the name is specific to a particular program in the call stack.
[StyleSheetName] | Optional. Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of an XSLT stylesheet file to be used to transform the generated XML document before it is stored. If an extension is not specified in the filename, the extension .xsl is appended to the specified filename.

Description

The XML IMPORT TEXT statement imports the content of the text string indicated by the DocumentPointer and DocumentLength parameters. If the optional StyleSheetName parameter is present, the specified XSLT stylesheet is used to transform the document before being converted to COBOL data format. The content of the resulting document is converted to COBOL format using the structure of the ModelDataName parameter, and then is stored in the data item specified by the DataItem parameter.

A status value is returned in the data item XML-Status of XML-data-group , which is defined in the copy file lixmldef.cpy.

Examples

XML IMPORT TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-DATA-ITEM"
IF NOT XML-OK GO TO Z.
XML IMPORT TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-DATA-ITEM"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.
XML SET XSL-PARAMETERS
     "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
XML IMPORT TEXT
   MY-DATA-ITEM
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-DATA-ITEM"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.
Parent topic: Document Processing Statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML TEST WELLFORMED-FILE

This statement has the following parameter:

Parameter | Description
DocumentName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of the file that specifies the XML document to be tested. If an extension is not specified in the filename, the extension .xml is appended to the specified filename.

Description

The XML TEST WELLFORMED-FILE statement tests the XML document specified by the DocumentName parameter to see if it is well-formed. A well-formed XML document is one that conforms to XML syntax rules, but is not necessarily valid with respect to any schema. see XML VALIDATE FILE and XML VALIDATE TEXT for testing whether a document is valid with respect to a schema.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML TEST WELLFORMED-FILE
    "MY-DOCUMENT".
IF NOT XML-OK GO TO Z.
Parent topic: Document Processing Statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML TEST WELLFORMED-TEXT

This statement has the following parameter:

Parameter | Description
DocumentPointer | Identifier of a COBOL pointer data item that points to an XML document stored in memory as a text string.
DocumentLength | Numeric literal or identifier of a COBOL numeric data item that specifies the length of the XML document stored in memory as a text string.

Description

The XML TEST WELLFORMED-TEXT statement tests the XML document specified by the DocumentPointer and DocumentLength parameters to see if it is well-formed. A well-formed XML document is one that conforms to XML syntax rules, but is not necessarily valid with respect to any schema. see XML VALIDATE FILE and XML VALIDATE TEXT for testing whether a document is valid with respect to a schema.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML TEST WELLFORMED-TEXT
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH.
IF NOT XML-OK GO TO Z.
Parent topic: Document Processing Statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML TRANSFORM FILE

This statement has the following parameters

Parameter | Description
InputDocumentName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of the document to transform (the input document). If an extension is not specified in the filename, the extension .xml is appended to the specified filename.
StyleSheetName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of the XSLT stylesheet file to be used for the transformation. If an extension is not specified in the filename, the extension .xsl is appended to the specified filename.
OutputDocumentName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of the transformed document (the output document). If an extension is not specified in the filename, the extension .xml is appended to the specified filename.

Description

The XML TRANSFORM FILE statement transforms the XML document specified by the InputDocumentName parameter using the XSLT stylesheet specified by the StyleSheetName parameter into a new document specified by the OutputDocumentName parameter. The new document may or may not be an XML document depending on the XSLT stylesheet.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Examples

XML TRANSFORM FILE
    "MY-IN-DOCUMENT"
    "MY-STYLESHEET"
    "MY-OUT-DOCUMENT”.
IF NOT XML-OK GO TO Z.

XML SET XSL-PARAMETERS
    "MY-COUNT"  7
    "MY-NAME"  "ACUCOBOL-GT"
    MY-PARAM-NAME-ITEM  MY-PARAM-VALUE-ITEM.
IF NOT XML-OK GO TO Z.
XML TRANSFORM FILE
    "MY-DOCUMENT.XML"
    "MY-PDF-XFORM.XSL"
    "MY-NEW-FILE.PDF”.
IF NOT XML-OK GO TO Z.
Parent topic: Document Processing Statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM TEXT
XML VALIDATE FILE
XML VALIDATE TEXT


XML TRANSFORM TEXT

This statement has the following parameters

Parameter | Description
InputDocumentPointer | The name of a COBOL pointer data item that points to an XML document that is stored in memory as a text string (the input document).
InputDocumentLength | Numeric literal or identifier of a COBOL numeric data item that specifies the length of the XML document to be transformed.
StyleSheetName | The filename of the XSLT stylesheet used for the transformation.
OutputDocumentPointer | The name of a COBOL pointer data item that will point to the generated XML document as a text string after successful completion of the statement (the output document).
OutputDocumentLength | Numeric literal or identifier of a COBOL numeric data item that specifies the length of the transformed XML document.

Description

The XML TRANSFORM TEXT statement transforms the XML document specified by the InputDocumentPointer and InputDocumentLength parameters, using the XSLT stylesheet specified by the StyleSheetName parameter, into a new document specified by the OutputDocumentPointer and OutputDocumentLength parameters. The new document may or may not be an XML document depending on the XSLT stylesheet.

A status value is returned in the XML-data-group data item, which is defined in the copybook, lixmldef.cpy.

A block of memory is allocated to hold the transformed XML document. The COBOL application is responsible for releasing this memory when it is no longer needed by using XML FREE TEXT.

Examples

With an External XSLT Stylesheet:

XML TRANSFORM TEXT
    MY-IN-DOCUMENT-POINTER
    MY-IN-DOCUMENT-LENGTH
    "MY-STYLESHEET"
    MY-OUT-DOCUMENT-POINTER
    MY-OUT-DOCUMENT-LENGTH
IF NOT XML-OK GO TO Z.

With an External XSLT Stylesheet and Parameters:

XML SET XSL-PARAMETERS
     "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
XML TRANSFORM TEXT
    MY-DATA-ITEM
    MY-DOCUMENT-LENGTH
    "MY-DOCUMENT.XML"
    "MY-MODEL-FILE"
    "MY-STYLE-SHEET"
IF NOT XML-OK GO TO Z.
Parent topic: Document Processing Statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML VALIDATE FILE
XML VALIDATE TEXT


XML VALIDATE FILE

This statement has the following parameters:

Parameter | Description
DocumentName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of the file that specifies the XML document to be validated. If an extension is not specified in the filename, the extension .xml is appended to the specified filename.
SchemaName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of the XML schema file to be used to validate the XML document specified by DocumentName. The filename extension is forced to .xsd by replacing any existing extension in the filename or, if no extension is present, the extension .xsd is appended to the specified filename.

Description

The XML VALIDATE FILE statement tests the XML document specified by the DocumentName parameter to see if it is well-formed and valid with respect to the XML schema specified by the SchemaName parameter.

A well-formed XML document is one that conforms to XML syntax rules. A valid XML document is one that is both well-formed and has content that conforms to rules specified by an XML schema file.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy. A text description of an error, if any, in the validity of the document can be obtained using XML GET STATUS-TEXT.

Example

XML VALIDATE FILE
    "MY-DOCUMENT"
    "MY-SCHEMA".
IF NOT XML-OK GO TO Z.
Parent topic: Document Processing Statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE TEXT


XML VALIDATE TEXT

This statement has the following parameters:

Parameter | Description
DocumentPointer | Identifier of a COBOL pointer data item that points to an XML document stored in memory as a text string.
DocumentLength | Numeric literal or identifier of a COBOL numeric data item that specifies the length of the XML document stored in memory as a text string.
SchemaName | Numeric literal or identifier of a COBOL alphanumeric data item that specifies the filename of the schema file to be used to validate the XML document specified by DocumentPointer and DocumentLength. The filename extension is forced to .xsd by replacing any existing extension in the filename or, if no extension is present, the extension .xsd is appended to the specified filename.

Description

The XML VALIDATE TEXT statement tests the XML document specified by the DocumentPointer and DocumentLength parameters to see if it is well-formed and valid with respect to the XML schema specified by the SchemaName parameter.

A well-formed XML document is one that conforms to XML syntax rules. A valid XML document is one that is both well-formed and has content that conforms to rules specified by an XML schema file.

A block of memory is allocated to hold the XML document whilst it is validated. The COBOL application is responsible for releasing this memory when it is no longer needed by using XML FREE TEXT.

A status value is returned in the data item XML-Status of XML-data-group , which is defined in the copy file lixmldef.cpy.

Example

XML VALIDATE TEXT
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-SCHEMA".
IF NOT XML-OK GO TO Z.
Parent topic: Document Processing Statements
Related information
XML EXPORT FILE
XML EXPORT TEXT
XML IMPORT FILE
XML IMPORT TEXT
XML TEST WELLFORMED-FILE
XML TEST WELLFORMED-TEXT
XML TRANSFORM FILE
XML TRANSFORM TEXT
XML VALIDATE FILE


Document Management Statements

A number of statements are available to copy an XML document from an external file to an internal text string and vice versa.

  • XML FREE TEXT
  • XML GET TEXT
  • XML PUT TEXT
  • XML REMOVE FILE
Parent topic: XML Extensions Statement Reference


XML FREE TEXT

This statement has the following parameter:

Parameter | Description
DocumentPointer | Identifier of a COBOL pointer data item that points to an area of memory allocated by the XML EXPORT TEXT or XML GET TEXT statements.

Description

The XML FREE TEXT statement releases the memory referred to by the COBOL pointer data item specified by the DocumentPointer parameter, which should have a value that has been set by one of the statements XML EXPORT TEXT, XML EXPORT FILE, or XML TRANSFORM TEXT.

Example

XML FREE TEXT
    MY-DOCUMENT-POINTER
IF NOT XML-OK GO TO Z.
Parent topic: Document Management Statements


XML GET TEXT

This statement has the following parameters:

Parameter | Description
DocumentPointer | Identifier of a COBOL pointer data item that will point to the in-memory text after successful completion of the statement.
DocumentLength | Identifier of a COBOL numeric data item that will contain the length of the in-memory text after successful completion of the statement.
DocumentName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of the file containing the text to load into memory. If an extension is not specified in the filename, the extension .xml is appended to the specified filename.

Description

The XML GET TEXT statement copies the content of a file specified by the DocumentName parameter to COBOL memory. A block of memory is allocated to contain the text. The address and size of the memory block are returned in the DocumentPointer and DocumentLength parameters, respectively. The text is normally, but not necessarily, an XML document.

When the program has finished using the in-memory document, a call to XML FREE TEXT should be made to release the allocated memory.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML GET TEXT
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-DOCUMENT".
IF NOT XML-OK GO TO Z.
Parent topic: Document Management Statements


XML PUT TEXT

This statement has the following parameters:

Parameter | Description
DocumentPointer | Identifier of a COBOL pointer data item that points to the in-memory text to put into the file specified by the DocumentName parameter.
DocumentLength | Numeric literal or identifier of a COBOL numeric data item that specifies the length of the in-memory text.
DocumentName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of the file to contain the content of the memory area upon successful completion of the statement. If an extension is not specified in the filename, the extension .xml is appended to the specified filename.

Description

The XML PUT TEXT statement copies the content of the memory area specified by the DocumentPointer and DocumentLength parameters to the external file specified by the DocumentName parameter. The text is normally, but not necessarily, an XML document. A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML PUT TEXT
    MY-DOCUMENT-POINTER
    MY-DOCUMENT-LENGTH
    "MY-DOCUMENT".
IF NOT XML-OK GO TO Z.
Parent topic: Document Management Statements


XML REMOVE FILE

This statement has the following parameter:

Parameter | Description
FileName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of the file to be removed. If an extension is not specified in the filename, the extension .xml is appended to the specified filename.

Description

The XML REMOVE FILE statement deletes the file specified by the FileName parameter.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML REMOVE FILE
    MY-FILE-NAME.
IF NOT XML-OK GO TO Z.
Parent topic: Document Management Statements


Directory Management Statements

This section describes the statements that are useful when implementing directory-polling schemes:

  • XML FIND FILE
  • XML GET UNIQUEID

Directory polling, as related to XML documents, allows two or more independent processes to pass XML documents between the processes. For example, one or more writer processes may place XML documents in a well-known directory, that is, a directory with a directory name that is known to all of the interested processes. Each XML document must have been given a unique name. A reader process finds, processes, and removes XML documents from the same well-known directory.

Directory polling may be used to communicate with message-driven communications systems. It is a technique that may also be used between various ACUCOBOL-GT applications.

Note that XML FIND FILE when used with multiple reader processes on the same directory could find the same file. An external conflict resolution mechanism must be used to avoid this situation.

  • XML FIND FILE
  • XML GET UNIQUEID
Parent topic: XML Extensions Statement Reference


XML FIND FILE

This statement has the following parameters:

Parameter | Description
DirectoryName | Nonnumeric literal or identifier of an alphanumeric data item that specifies the pathname of the directory to check for documents (files ending with .xml or the extension specified in the Extension parameter).
FileName | Identifier of an alphanumeric data item that will contain the filename of one document that was found in the specified directory after successful completion of the statement.
[Extension] | Optional. Nonnumeric literal or identifier of an alphanumeric data item that specifies a user-defined extension having the format of a leading period followed by the extension name; the extension name may be any length from one to the number of characters permitted by the operating system. If Extension is not specified, the extension .xml is used.

Description

The XML FIND FILE statement looks in the directory specified by the DirectoryName parameter for a document (a file with the .xml extension, unless the Extension parameter is specified). If there are one or more documents in the specified directory with the specified extension, the name of one of the files will be returned in the data item specified by the FileName parameter.

If the statement succeeds (the condition-name XML-IsSuccess is true), the filename in the data item specified by the FileName parameter, when it is an XML document, may be processed by using it in an XML IMPORT FILE statement .

Before calling XML FIND FILE again (to process the next file), you must call XML REMOVE FILE to delete the XML document that was just processed. Otherwise, the next call to the XML FIND FILE statement may return the same file.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy. The condition-name

XML-IsDirectoryEmpty will be true if the directory is empty.

Example

FIND-DOCUMENT.
    PERFORM WITH TEST AFTER UNTIL 0 > 1
        XML FIND FILE
            "MY-DIRECTORY"
            MY-FILE-NAME
        IF XML-IsSuccess
            EXIT PERFORM
        END-IF
        IF XML-IsDirectoryEmpty
            CALL "C$DELAY" USING 0.1
        END-IF
        IF NOT XML-OK GO TO Z.
    END-PERFORM
*> Process found document
Parent topic: Directory Management Statements


XML GET UNIQUEID

This statement has the following parameter:

Parameter | Description
UniqueID | Identifier of an alphanumeric data item that will contain the unique ID value after successful completion of this statement. The data item must be at least 38 characters in length.

Description

The XML GET UNIQUEID statement generates a unique identifier that may be used to form a unique filename. Please note that the return value might not contain any alphabetic characters. Therefore, it would be a good programming practice to add an alphabetic character to the name for those operating systems where filenames require at least one alphabetic character (see the following example).

The unique value returned by this statement is a string representation having the same format as a Windows UUID (Universal Unique Identifier). The string is a series of hexadecimal digits with embedded hyphen characters. The string is enclosed in brace characters ({ and }). The entire string is 38 characters in length.

On Windows systems, the value is an actual UUID. On UNIX systems, the value is a string having the same format as a Windows UUID, but constructed by an internal algorithm. This algorithm uses various components, including the system ID, the start time of the run unit, the current time, and an internal counter, to generate a unique value.

This statement may be used in conjunction with the COBOL STRING statement to generate a unique filename.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

MOVE SPACES TO MY-FILE-NAME.
XML GET UNIQUEID
    MY-UNIQUEID.
IF NOT XML-OK GO TO Z.
STRING "mydir\a"   DELIMITED BY SIZE
       MY-UNIQUEID DELIMITED BY SPACE
       ".xml"      DELIMITED BY SIZE
    INTO MY-FILE-NAME.
Parent topic: Directory Management Statements


State Management Statements

Calls to the following XML statements control several states or conditions, including:

  • Initialization and termination. Before issuing a call to any other XML Extensions statement, XML INITIALIZE must be called. (If XML INITIALIZE has not been called, any subsequent calls, for example, XML EXPORT FILE, will fail.) Similarly, XML TERMINATE should be called when the COBOL application is finished using XML Extensions statements. (If XML TERMINATE has not been called prior to program termination, there are no consequences.)
  • Empty array occurrences. As an optimization, trailing empty occurrences of arrays (COBOL tables) are normally not generated by the statements, XML EXPORT FILE or XML EXPORT TEXT.

    An empty occurrence of an array is defined to be one where the numeric items have a zero value and the nonnumeric items have a value of all spaces. This is the default state and is equivalent to calling XML DISABLE ALL-OCCURRENCES. It is possible to force all occurrences to be output by calling XML ENABLE ALL-OCCURRENCES.

  • COBOL attributes. For each element generated by the statements, XML EXPORT FILE or XML EXPORT TEXT, there is a series of COBOL attributes that describe that element.

    The default state is not to output these attributes. However, it is sometimes necessary for a following activity (such as an XSLT stylesheet transformation) to have access to these attributes (specifically, length and subscript are often important to a follow-on activity). Using XML DISABLE ATTRIBUTES prevents attributes from being written (this is the default) to the output file. Using XML ENABLE ATTRIBUTES forces these attributes to be written to the output file, although the optional StyleSheetName parameter might specify an XSLT stylesheet transformation that removes some or all of the attributes from the final output file.

  • Document caching. XML documents, such as XSLT stylesheets, templates, and schemas, are normally considered to be static during the use of a production version of the application. That is, they are generated when the application is developed and are not modified until the application is modified.

    To optimize performance, when XML Extensions loads an XSLT stylesheet, a template, or a schema, the document is cached (that is, retained in memory) for an indefinite period of time. This is the default behavior. However, even with the default behavior, a document in the cache may be flushed from memory if the cache is full and an XSLT stylesheet, template, or schema document not already in the cache is required for the current operation.

    If XSLT stylesheets, templates, or schemas are being generated dynamically, the user may selectively enable or disable caching. Executing XML ENABLE CACHE, which sets the default behavior, enables caching of documents. Executing XML DISABLE CACHE disables caching, thus forcing all documents to be loaded each time they are referenced. Executing XML FLUSH CACHE flushes all documents and local memory from the cache without changing the state of caching (that is, if caching was enabled it remains enabled). Executing any of the following statements causes the contents of the cache to be flushed: XML INITIALIZE, XML ENABLE CACHE, XML DISABLE CACHE, XML FLUSH CACHE, and XML TERMINATE. Executing XML ENABLE CACHE, XML DISABLE CACHE, or XML FLUSH CACHE also causes local memory to be flushed.

  • Data conversion flags. The data conversions performed by the statements, XML EXPORT FILE, XML EXPORT TEXT, XML IMPORT FILE, and XML IMPORT TEXT, may be modified from their defaults. By default, the following data conversion flags are set: PF-Trailing-Spaces, PF-Leading-Spaces, PF-Leading-Minus, and PF-Rounded. (However, PF-Trailing-Spaces and PF-Leading-Spaces are ignored in several instances as described in XML SET FLAGS.)

    XML GET FLAGS and XML SET FLAGS are available to alter these defaults.

  • Internal character encoding. Characters within alphanumeric data elements in a COBOL program are normally encoded using the conventions of underlying operating systems Under some conditions, it may be desirable to encode these same data items using UTF-8 encoding. (UTF-8 is a format for representing Unicode.) XML SET ENCODING is provided to switch between the local encoding format and UTF-8.

    Note Both the UNIX and Windows implementations of XML Extensions allow the in-memory representation of element content to use UTF-8 encoding. This may be useful for COBOL applications that wish to pass UTF-8-encoded data to other processes. XML documents are normally encoded using Unicode. XML Extensions always generates UTF-8 data in exported documents. For more information, see COBOL and Character Encoding.

  • Tracing. Trace information can be generated to a designated file using the XML TRACE statement. Trace information includes the status from each XML Extensions statement and can frequently be useful in analyzing errors in an application.
  • Stylesheet parameters. The passing of parameters to stylesheets can be controlled by the XML SET XSL-PARAMETERS and XML CLEAR XSL-PARAMETERS statements.
  • XML INITIALIZE
  • XML TERMINATE
  • XML DISABLE ALL-OCCURRENCES
  • XML ENABLE ALL-OCCURRENCES
  • XML DISABLE ATTRIBUTES
  • XML ENABLE ATTRIBUTES
  • XML DISABLE CACHE
  • XML ENABLE CACHE
  • XML FLUSH CACHE
  • XML GET FLAGS
  • XML TRACE
  • XML GET STATUS-TEXT
  • XML SET ENCODING
  • XML SET FLAGS
  • XML GET WHITESPACE-FLAGS
  • XML SET WHITESPACE-FLAGS
  • XML SET XSL-PARAMETERS
  • XML CLEAR XSL-PARAMETERS
Parent topic: XML Extensions Statement Reference


XML INITIALIZE

This statement has no parameters.

Description

The XML INITIALIZE statement opens a session with XML Extensions. It ensures that the AcuCOBOL-GT runtime system is the required version and retrieves required information from the runtime system. The underlying XML parser is also initialized.

The execution of this statement causes the document cache to be flushed from memory.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy. It is not considered an error to execute an XML INITIALIZE statement when XML Extensions has already been initialized and not terminated.

Example

XML INITIALIZE.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML TERMINATE

This statement has no parameters.

Description

The XML TERMINATE statement flushes the document cache and closes a session with XML Extensions. The interface to the underlying XML parser is also closed. Any memory blocks that were allocated by XML Extensions are freed.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy. Errors can occur under the following circumstances:

  • The calls to free memory fail.
  • The underlying XML parser termination fails.

It is not considered an error to execute an XML TERMINATE statement when XML Extensions has not been initialized or has already been terminated.

Example

XML TERMINATE.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML DISABLE ALL-OCCURRENCES

This statement has no parameters.

Description

The XML DISABLE ALL-OCCURRENCES statement causes unnecessary empty array (COBOL table) occurrences not to be generated by the statements, XML EXPORT FILE and XML EXPORT TEXT. An empty array occurrence is one in which all numeric elements have a zero value and all nonnumeric elements have a value of all spaces.

There is some interoperation with whether attributes are enabled or disabled. If attributes are enabled (that is, XML ENABLE ATTRIBUTES has been used), then no empty occurrences are exported; when attributes are enabled, the subscript is present in the exported document and thus empty occurrences need not be exported as placeholders to ensure that the correct subscript is calculated on import. If attributes are disabled (the default state or when XML DISABLE ATTRIBUTES has been used), then only trailing empty occurrences are not exported, except that, if all occurrences are empty, the first empy occurrence will be exported.

The A_XMLIF_EXPORT_EMPTY_ARRAY runtime configuration variable can be used to modify the export behavior for an array that is empty, that is, all the occurrences are empty. When set to the value 1, Y, T or ON (case-insensitively), XML Extensions exports one empty occurrence regardless of whether attributes are enabled or disabled. When set to the value 0, N, F or OFF (case-insensitively), XML Extensions does not export any occurrences for the empty array regardless of whether attributes are enabled or disabled. When not set or set to a value not listed (for example, “UNSET”), the behavior for an empty array varies as described above, that is, the behavior depends on whether attributes are enabled or disabled

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML DISABLE ALL-OCCURRENCES.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML ENABLE ALL-OCCURRENCES

This statement has no parameters.

Description

The XML ENABLE ALL-OCCURRENCES statement causes all occurrence of an array (COBOL table) to be generated by the statements, XML EXPORT FILE and XML EXPORT TEXT, regardless of the content of the array.

All occurrences of an array are generated regardless of whether attributes are enabled or disabled.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML ENABLE ALL-OCCURRENCES.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML DISABLE ATTRIBUTES

This statement has no parameters.

Description

The XML DISABLE ATTRIBUTES statement causes the COBOL attributes of an XML element to be omitted from an exported XML document. This is the default state.

See XML DISABLE ALL-OCCURRENCES regarding the behavior of array (COBOL table) output when attributes are enabled or disabled.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML DISABLE ATTRIBUTES.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML ENABLE ATTRIBUTES

This statement has no parameters.

Description

The XML ENABLE ATTRIBUTES statement causes the COBOL attributes of an XML element to be generated in an exported XML document

See XML DISABLE ALL-OCCURRENCES regarding the behavior of array (COBOL table) output when attributes are enabled or disabled.

Some of the COBOL attributes (such as length and subscript) may be useful to an XSLT stylesheet.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML ENABLE ATTRIBUTES.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML DISABLE CACHE

This statement has no parameters.

Description

The XML DISABLE CACHE statement disables the caching of XSLT stylesheets, templates, and schemas. Besides disabling caching, executing this statement also flushes the document cache as well as local memory.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML DISABLE CACHE.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML ENABLE CACHE

This statement has no parameters.

Description

The XML ENABLE CACHE statement enables the caching of XSLT stylesheets, templates, and schemas, and flushes the document cache and local memory immediately, even if document caching was already enabled.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML ENABLE CACHE.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML FLUSH CACHE

This statement has no parameters.

Description

The XML FLUSH CACHE statement flushes the cache of XSLT stylesheet, templates, and schema documents, and flushes the document cache and local memory. The enabled or disabled state of caching is not changed by this statement.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML FLUSH CACHE.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML GET FLAGS

This statement has the following parameter:

Parameter | Description
Flags | Identifier of a numeric data item to receive the current data conversion flags value after successful execution of this statement. The data item should be described with at least 9 decimal digits to avoid possible truncation of the returned value.

Description

The XML GET FLAGS statement retrieves the setting of the flags that are used for internal data conversion. Valid flag values are specified in the copy file lixmldef.cpy . The initial setting of the flags has the following flag values set: PF-Leading-Spaces, PF-Trailing-Spaces, PF-Leading-Minus, and PF-Rounded. The setting of the flags can be changed with the XML SET FLAGS statement.

Note: These flag values are 78-level constant-names. They are case insensitive and require the use of the hyphen character.

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML GET FLAGS
   MY-FLAGS.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML TRACE

This statement has the following parameters:

Parameter Description
Flags Numeric literal or identifier of a numeric data item that specifies the sum of the desired flag values, which are the following:
  • 0 = Turn tracing off and keep any existing trace file.
  • 1 = Turn tracing on and keep any existing trace file.
  • 2 = Turn tracing off and delete any existing trace file.
  • 3 = Turn tracing on and delete any existing trace file.
[Filename] Optional. Nonnumeric literal or identifier of an alphanumeric data item that specifies the filename of the trace file. If omitted, a value of XMLTrace.log is assumed.

If an extension is not specified in the filename, the extension .log is appended to the specified filename. This parameter is ignored if the flags indicate that tracing is being turned off.

Description

The XML TRACE statement generates trace information to a designated file for each statement executed. The statement name and parameter values (as well as the calling program name and the time executed) are recorded on entry. Updated parameter values are displayed on exit along with the status returned from the statement.

Examples

XML TRACE
        MY-FLAGS.
IF NOT XML-OK GO TO Z.

XML TRACE
    MY-FLAGS
    MY-TRACE-FILE.
IF NOT XML-OK GO TO Z.

XMLImportFile - entry
 DocumentName[test1in]
 ModelDataName[XYZ-Data--Document]
 StyleSheetName[]
Date-Time: Fri Jul 02 12:42:53 2010
Called from line 100 in test1.acu(test1.acu),
                  compiled 2010070212412500000.
XMLImportFile - exit
 Status[0000]
 FullDocumentName[C:\acucobol9\code\test1in.xml]
 FullStyleSheetName[]
Parent topic: State Management Statements


XML GET STATUS-TEXT

This statement has no parameters.

Description

A non-successful termination of an XML statement may cause one or more lines of descriptive text to be placed in a queue. The XML GET STATUS-TEXT statement fetches the next line of descriptive text into XML-StatusText of XML-data-group.

The statement is always successful (that is, does not set XML-Status of XML-data-group), but returns an indicator of whether there are additional lines of descriptive text available. The following condition-name on the indicator is also described in the copy file lixmldef.cpy:

  • XML-NoMore. There are no further lines of descriptive text available.

An example of processing the status information in this item is found below and in the copy file lixmldsp.cpy.

Example

Display-Status.
    If Not XML-IsSuccess
        Perform With Test After Until XML-NoMore
            XML GET STATUS-TEXT
            Display XML-StatusText
        End-Perform
    End-If.
Note: In the lixmldef.cpy copy file, the definition of the XML-StatusText field may be changed from the default of PIC X(80) to change the size of the buffer used to contain XML status information One way to accomplish this is to use the phrase REPLACING ==XML-StatusText PIC X(80)== BY ==XML-StatusText PIC X(320)== in the COPY statement that copies lixmlall.cpy to set the returned status text line to 320, for example. A less desirable method to change the buffer size is to edit the copy file directly.
Parent topic: State Management Statements


XML SET ENCODING

This statement has the following parameter:

Parameter | Description
Encoding | Nonnumeric literal or identifier of an alphanumeric data item with a value that must be either local or utf-8. If the value is local, then the character encoding used by the operating system is used. If the value is utf-8, then the data is treated as UTF-8 encoded. The parameter value is case insensitive. Any hyphen and underscore characters are optional. For example, LOCAL, Local, and local are equivalent. UTF-8, Utf_8, and utf8 are also equivalent.

Description

The XML SET ENCODING statement allows the developer to specify the character encoding of data within a COBOL data structure. The developer may use this statement to switch between the local character encoding and UTF-8. For more information on this environment variable, see COBOL and Character Encoding.

Although the XML SET ENCODING statement does not affect the character encoding of the XML document, it does affect the character encoding of the data in the COBOL program. For more information, see Data Representation. Be particularly aware that when the encoding is set to UTF-8, non-ASCII characters require more than one byte to encode and thus the size of data items that might contain such characters must be adjusted accordingly to avoid truncation on import. Further, UTF-8 data in the COBOL program generally cannot be handled correctly by normal COBOL statements other than MOVE. UTF-8 encoding is mostly useful only to guarantee preservation of non-ASCII characters on import that cannot be represented in the local character encoding, but are going to be exported later with XML Extensions.

The XML SET ENCODING statement returns an error status value if the value of the Encoding parameter is not recognized.

Example

XML SET ENCODING "local".
IF NOT XML-OK GO TO EXIT-1.
The default value is local. If XML SET ENCODING is never called, the default is used.
Parent topic: State Management Statements


XML SET FLAGS

This statement has the following parameter:

Parameters | Description
Flags | A numeric literal or identifier of a numeric data item with a value that represents one or more data conversion flags.

Description

The XML SET FLAGS statement establishes the setting of the flags that are used for internal data conversion for import and export. Valid flag values are specified in the copy file, lixmldef.cpy.

The initial setting of the flags has the following flag values set: PF-Leading-Spaces, PF-Trailing-Spaces, PF-Leading-Minus, and PF-Rounded.

Note:
  • These flag values are 78-level constant-names defined in lixmldef.cpy. They are case insensitive and require the use of the hyphen character.
  • On export and import of nonnumeric items, the PF-Trailing-Spaces and PF-Leading-Spaces flags are ignored for edited and FILLER data items; that is, leading and trailing spaces are preserved for edited and FILLER data items. On export of nonnumeric data items, the PF-Leading-Spaces flag is ignored except for right justified data items; that is leading spaces are preserved except for right justified data items. This note applies regardless of whether the default flags or user-specified flags are in effect. (The PF-Trailing-Spaces and PF-Leading-Spaces flags do not affect conversion of numeric data items.)

A status value is returned in the data item XML-Status of XML-data-group, which is defined in the copy file lixmldef.cpy.

Example

XML SET FLAGS
   MY-FLAGS.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML GET WHITESPACE-FLAGS

This statement has the following parameter:

Parameter Description
Flags A numeric literal or identifier of a numeric data item with a value that represents one or more states of whitespace preservation. Valid flags and their numerical values are:
78 WHITESPACE-DEFAULT-FLAGS Value 0.  *> keep all whitespace
78 WHITESPACE-STRIP-CONTROL Value 1.  *> strip all (TAB, LF, CR) characters
78 WHITESPACE-PRESERVE-TAB  Value 16. *> keep TAB characters when stripping
78 WHITESPACE-PRESERVE-LF   Value 32. *> keep LF characters when stripping
78 WHITESPACE-PRESERVE-CR   Value 64. *> keep CR characters when stripping
78 WHITESPACE-NORMALIZE     Value 65536. *>collapse whitespace (space, LF, TAB, CR)

Description

The XML GET WHITESPACE-FLAGS statement displays the whitespace preservation behavior (as set by XML SET WHITESPACE-FLAGS) in effect.

The valid flags are defined in the COPY file lixmldef.cpy.

Example

The following example sets the value of CURRENT-WS-FLAGS to the current value of the whitespace flags in use by XML Extensions:

XML GET WHITESPACE-FLAGS CURRENT-WS-FLAGS
Note: CURRENT-WS-FLAGS is a numeric data item with at least 6 digits.
Parent topic: State Management Statements
Related reference
XML SET WHITESPACE-FLAGS


XML SET WHITESPACE-FLAGS

This statement has the following parameter:

Parameter Description
Flags A numeric literal or identifier of a numeric data item with a value that represents one or more states of whitespace preservation. Valid flags and their numerical values are:
78 WHITESPACE-DEFAULT-FLAGS Value 0.  *> keep all whitespace
78 WHITESPACE-STRIP-CONTROL Value 1.  *> strip all (TAB, LF, CR) characters
78 WHITESPACE-PRESERVE-TAB  Value 16. *> keep TAB characters when stripping
78 WHITESPACE-PRESERVE-LF   Value 32. *> keep LF characters when stripping
78 WHITESPACE-PRESERVE-CR   Value 64. *> keep CR characters when stripping
78 WHITESPACE-NORMALIZE     Value 65536. *>collapse whitespace (space, LF, TAB, CR)

The values for flags 1 to 64 can be added together to achieve combined behaviors.

Description

The XML SET WHITESPACE-FLAGS statement controls the preservation of whitespace during an XML IMPORT statement. The default behavior is to preserve all whitespace; that is, all space characters, line feeds (LF), carriage returns (CR), and tab characters (TAB). Use this statement to determine which elements are stripped out. You can combine the flag values (see Description above) to strip out more than one element; for example, set Flags to 65 preserve the CR elements, but strips out all LF and TAB elements.

You can also normalize whitespace (stripping out consecutive whitespace elements, replacing them with a single space character), but this action cannot be combined with any other action.

The XML TERMINATE statement will revert the whitespace setting back to its default behavior (all whitespace preserved). It does not revert back to its default behavior following an XML INITIALIZE statement.

The valid flags are defined in the COPY file lixmldef.cpy, and so this file must be in effect when using the statement.

Example

The following example uses the values 1 and 16 to have the effect of only striping out the LF and CR elements, but preserving the TAB elements.

XML SET WHITESPACE-FLAGS 17
Parent topic: State Management Statements
Related reference
XML GET WHITESPACE-FLAGS


XML SET XSL-PARAMETERS

This statement has the following parameter:

Parameter | Description
Parameter list | A list containing at least one and no more than 20 name/value pairs to be used whenever transform operations are performed. The name portion of an entry is a nonnumeric literal or identifier of an alphanumeric data item that specifies the name of the parameter. The value portion of an entry is a literal or identifier of a data item that specifies the value of the parameter named by its associated name portion; the value may be numeric or nonnumeric.

Description

The XML SET XSL-PARAMETERS statement passes a list of name/value pairs to XML Extensions, where they are stored until one of the following occurs:

  • They are replaced by a subsequent execution of an XML SET XSL-PARAMETERS statement.
  • They are cleared by executing an XML CLEAR XSL-PARAMETERS statement.
  • They are cleared by flushing the cache (the statements XML INITIALIZE, XML ENABLE CACHE, XML DISABLE CACHE, XML FLUSH CACHE, and XML TERMINATE all clear the cache ).
  • The COBOL run-unit terminates.

The saved parameters are used whenever any of the following transform operations occur:

  • The XML TRANSFORM FILE statement is executed.
  • The XML EXPORT FILE, XML EXPORT TEXT, XML IMPORT FILE, or XML IMPORT TEXT statements reference an optional stylesheet.

A maximum of 20 name/value pairs may be specified. If more than 20 pairs are specified or the parameters are not specified as pairs, an error will be reported.

Example

XML SET XSL-PARAMETERS
    "MY-COUNT", 7.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML CLEAR XSL-PARAMETERS

This statement has no parameters.

Description

The XML CLEAR XSL-PARAMETERS statement clears all sets of name/value pairs that have been stored in XML Extensions by the XML SET XSL-PARAMETERS statement.

Example

XML CLEAR XSL-PARAMETERS.
IF NOT XML-OK GO TO Z.
Parent topic: State Management Statements


XML Extensions Error Messages

  • Error Message Format
  • Summary of Error Messages
Parent topic: Working with XML Data


Error Message Format

XML Extensions error messages may be several lines long. The general format of an error message includes the text of the message, and, if available, the COBOL traceback information, the name of the file or data item, and the parser information.

Message Text

The first line of the error message has the following format:

severity - message number message text

severity indicates the gravity and type of message: Informative, Warning, or Error.

message number is the documented message number followed by an internal message number in bracket characters. The internal number provides information for Micro Focus support to use in diagnosing problems.

message number is a brief explanation for the cause of the error.

An example of the first line of an error message is shown below:

Error: 28[12] - in function:
LoadDocument

COBOL Traceback Information

The second line of the error message, present if the information is available, contains COBOL traceback information such as the following:

Called from line 69 in
example6.acu(example6.acu),
compiled 2010070611461200000.

Or, if line numbers are not available:

Called from location 43 in
example6.acu(example6.acu),
compiled 2010070611461200000.

The error-reporting facility will try to break up lines that are too long for the line buffer provided in the COBOL program (default is 80 characters). This prevents long lines from being truncated. A backward slash character (\) is placed in the last position of the buffer and the line is continued on the subsequent line. For example, the traceback line shown above may be broken up as follows:

Called from location 43 in
example6.acu(example6.acu),
co\ mpiled 2010070611461200000.

Filename or Data Item in Error

The third line of the error message, present if the information is available, normally contains the name of the file or data item in error being referenced.

Parser Information

Additional lines may be present that contain parser or schema diagnostics from the underlying XML parser, such as, for Windows:

Error parsing 'a9' as number datatype.
line 5, position 25 <ItemCount>a9</ItemCount>
----------- --|

The first line of parser or schema diagnostic information contains an error message. The second line contains the line number and column position within the XML document. The third line contains the line of XML text in error. The fourth line contains an indicator that draws attention to the column position.

An example for UNIX would be:

2: element zip: Schemas validity error :
Element 'zip': 'ABCDE' is not a valid value
of the atomic type 'type_Q8_example-a'.

where, the 2 is a line number and everything following the colon is a description of the error.

For errors on UNIX where the XML document is not well-formed, a second line with a portion of the input and a third line with a caret pointing to the syntax error position may be shown as follows:

2: parser error : Opening and ending tag
mismatch: acu1 line 2 and acu2
/state><zip>78730</zip></address-3><time-stamp>14525751</time-stamp></acu2
^
Parent topic: XML Extensions Error Messages


Summary of Error Messages

This table describes the messages that may be generated when an error occurs in XML Extensions.

Message Number | Severity and Message Text | Description
-6 | Warning - ambiguous import name | An element name in an imported XML document is defined more than once in the symbol table determined by the ModelFileName#DataFileName parameter of the XML IMPORT statement. Further, the element name is defined more than once subordinate to the model data name. XML Extensions assumes the first of the duplicates found, which is the lexically last defined duplicate, should be used and continues. If that name already has an imported value for the current import, the next duplicate is assumed, that is, a lexically previous duplicate definition. If there is no duplicate name without a previously imported value, a -02 extraneous element warning is produced and the imported text value is discarded. This warning is not produced if the XML document does not have any text content, after ignoring whitespace, for the element. This warning is also not produced if the XML document contains sufficient qualification, that is, parent element names, to make the reference unique. When a duplicate name is not subordinate to the model data name, this warning is not produced unless all duplicate names are not subordinate to the model data name.
-5 | Warning - ambiguous import target name (model dataname) | The model data name determined by the ModelFileName#DataFileName parameter of the XML IMPORT statement is defined more than once in the symbol table determined by that parameter (either in the object program or from a model template file). Additional qualification is necessary to uniquely define the model data name, which is the description of the target data structure for the import. (Note that in the case of nested programs, the program name can be used as a qualifier and might be necessary to differentiate duplicate data-names defined in different programs.)
-4 | Warning - subscript out of range | A subscript is out of range on import, either due to a subscript specified explicitly as an attribute or an implicit subscript inferred from repeated elements in the input document. The offending item is not imported.
-3 | Warning - data truncation | A nonnumeric import item has been truncated to fit the associated COBOL data item.
-2 | Warning - extraneous element | The import data contains one or more elements that do not belong anywhere in the COBOL data structure; the element(s) have been ignored.
-0 | Success | A normal completion occurred. No informative, warning, or error message was detected.
1 | Informative - directory contains no documents | An XML FIND FILE statement did not find any XML documents (files with an .xml extension) in the specified directory.
2 | Informative - document file - no data | An XML EXPORT FILE or an XML EXPORT TEXT statement generated a document that contained no element values.
3 | Warning - internal logic - memory not deallocated | During process cleanup, memory blocks that should have already been deallocated were still allocated.
9 | Error - in function: CreateDocument | The underlying XML parser detected an error while trying to create an XML document.
10 | Error - cannot create URL | A URL (a string beginning with the sequence Error! Hyperlink reference not valid., Error! Hyperlink reference not valid., or file://) was used as an output document name.
13 | Error - document file - create failure | An attempt to create an XML document file failed.
14 | Error - document file - file open failure | An error was detected while attempting to open an input document file. The file might not exist or there might be a problem with permissions.
15 | Error - extraneous element | An extra occurrence of a scalar data element was detected.
17 | Error - in function: GetFirstChild | There was insufficient memory to process a document.
18 | Error - in function: GetNextSibling | There was insufficient memory to process a document.
19 | Error - in function: GetNodeData | There was insufficient memory to process a document.
20 | Error - in function: GetRootNode | There was insufficient memory to process a document.
21 | Error - internal logic - memory allocation | An attempt to allocate a block of memory failed.
22 | Error - internal logic - memory corruption | An attempt to deallocate (free) a block of memory failed either because memory management information was corrupted or because the free memory call returned an error.
23 | Error - internal logic - node not found | An inconsistency in its internal tables, specifically a missing entry in the Document Object Model, has been detected.
24 | Error - in function: Initialization | Either an XML statement (other than XML INITIALIZE) was executed without first executing the XML INITIALIZE statement or the XML INITIALIZE statement failed.
28 | Error - in function: LoadDocument | An error was detected while trying to load an XML document. This normally means that there was a problem locating the document (either the document does not exist or there is a problem with permissions). This error may also occur if the input document contains an XML header but no elements.
29 | Error - in function: LoadSchema | An error was detected while trying to load an XML schema file. This normally means that there was a problem locating the document (either the document does not exist or there is a problem with permissions) or that the schema itself is in error.
30 | Error - in function: LoadStyleSheet | An error was detected while trying to load an internal or external XSLT stylesheet. This normally means that there was a problem locating the document (either the document does not exist or there is a problem with permissions). Another possible cause is that the XML parser software is not properly installed.
32 | Error - in function: LoadTemplate | An error was detected while trying to load a program's XML symbol table.
36 | Error - temporary file access error | An error has been encountered while attempting to access a temporary intermediate file. This error can occur during the XML IMPORT TEXT, XML EXPORT TEXT, XML VALIDATE TEXT, or XML TEST WELLFORMED-TEXT statements.
37 | Error - in function: TransformDOM | An error occurred while performing an XSLT transform of an XML document. This error may occur during the XML EXPORT FILE, XML IMPORT FILE and XML IMPORT TEXT statements.
38 | Error - in function: TransformText | An error occurred while performing an XSLT transform of an XML document. This error may occur during the XML EXPORT FILE and XML TRANSFORM FILE statements.
39 | Error - symbol table - not present in COBOL object | The ACUCOBOL-GT compiler did not produce an XML-format symbol table.
41 | Error - old runtime version | The ACUCOBOL-GT runtime system is too old for this version of XML Extensions.
42 | Error - in function: WriteDocument | An error occurred while attempting to write an XML document from the internal Document Object Model representation.
45 | Error - invalid encoding selection | The value of the Encoding parameter of the XML SET ENCODING statement was neither local nor utf-8.
46 | Error - invalid UTF-8 data | An XML export operation failed because the data supplied was not valid for UTF-8.
47 | Error - invalid RM_ENCODING value | The value of the X_XMLIF_ENCODING environment variable on UNIX is not any of XMLIF_LATIN_1, XMLIF_LATIN_9, or a name recognized by the available iconv library.
48 | Error - unable to locate iconv library | The value of the X_XMLIF_ENCODING environment variable on UNIX is not any of XMLIF_LATIN_1, XMLIF_LATIN_9, but an iconv library for character conversions could not be found.
49 | Error - directory open failure | The XML FIND FILE statement was not able to locate and open the specified directory.
50 | Error - missing XML parser (MSXML6) | The XML parser could not be found. This error occurs only on Windows and indicates the MSXML 6.0 parser is not installed in the Windows system. The MSXML 6.0 parser is normally installed when ACUCOBOL-GT is installed on Windows, but could not be found. MSXML 6.0 can be obtained by downloading it from Microsoft's web site.
51 | Error - data item - illegal name format | A data-name being exported does not begin with an initial name character (letter, colon or underscore). XML Extensions attempts to modify data item names that do not conform to XML tag name requirements. This error indicates a data item name has been encountered that was not successfully modified.
52 | Error - data conversion failure | The attempted conversion of data between a COBOL data type and a displayable string acceptable to XML failed.
53 | Error - Name specified is not a data-item | When specifying a data structure name, a name was provided that is not a data item. For example, it might be a file-name, an index-name, a constant-name, and so forth. A data item name is required.
63 Error - resolved file name is too long The resolved filename from one of the following statements is too large to fit in the buffer provided:
  • XML EXPORT FILE
  • XML EXPORT TEXT
  • XML IMPORT FILE
  • XML IMPORT TEXT
65 | Error - name / value pair required | The XML SET XSL-PARAMETERS statement requires an even number of parameters (name / value pairs).
66 | Error - excessive number of XSL parameters | The XML SET XSL-PARAMETERS statement is limited to a maximum of 40 parameters (20 name / value pairs).
67 | Error - unique identifier too long for buffer | The buffer supplied in the XML GET UNIQUEID statement is too small. Unique identifiers require 38 character positions.
68 | Error in function: AddAttribute | An attribute node could not be added during export of a document. Attributes are only added by XML Extensions when the XML ENABLE ATTRIBUTES statement has been executed. This error will not normally happen. One cause could be that the XML engine did not have enough memory to add the attribute node to the document.
69 | Error in function: AddElement | An element node could not be added during export of a document. This error will not normally happen. One cause could be that the XML engine did not have enough memory to add the element node to the document.
70 | Error in function: AddText | A text node could not be added during export of a document. This error will not normally happen. One cause could be that the XML engine did not have enough memory to add the text node to the document. The error can also happen if incorrect parameters are passed to the XML EXPORT FILE or XML EXPORT TEXT statement.
71 | Error in function: ValidateDOMDocument | An attempt to validate a document failed. This normally means that the document is not valid, but could also mean the supplied schema is not a valid schema or there was not enough memory to validate the document. Additional error lines are produced to indicate why the validation failed.
72 | Error - import offset outside target data structure | An attempt to store outside the target data structure determined by the DataItem parameter of the XML IMPORT statement has been detected. This can happen because of a model template file that is out-of-date with the executing COBOL program; in this case, the model template file needs to be regenerated from the revised COBOL program. Another cause can be duplicate data names in the symbol table and insufficient qualification (parent elements) in the imported XML document to choose the correct data item target for the import. The attempted import is suppressed along with any further import operations for the affected XML IMPORT statement.
73 | Trace file open failed | This message is produced if the XML TRACE statement is unable to open the specified file. When this occurs, tracing is disabled. If subsequent file operations fail to open the file from other XML Extensions statements, tracing is suppressed, but will be resumed if a later open operation is successful.
Parent topic: XML Extensions Error Messages


Working with Web Site and Web Service Data

  • Tutorial: Using RMNet to Move Data Between Your Program and a Web Server
  • Maintaining State Cookies
    Describes how to use HttpSetCookieFile to inform RMNet about cookies when calling RMNET from extend to extract data from a web site or service.
  • Secure Sockets (SSL)
    Describes RMNet compatibility with secure HTTP.
  • Response Header Processing
Parent topic: Working with Non-Vision Data


Tutorial: Using RMNet to Move Data Between Your Program and a Web Server

  1. Introduction
  2. Tutorial Prerequisites
  3. Building a SOAP Web Service Client
  4. Starting SoapUI and Creating the Project
  5. Creating Request and Response Prototypes
  6. Creating XSLT Stylesheets to Use with XML Extensions
  7. Converting the Request and Response to XSLT
  8. Creating the Web Service Client Program
Parent topic: Working with Web Site and Web Service Data


Introduction

This tutorial introduces RMNet, an HTTP web client callable from ACUCOBOL-GT extend. The tutorial shows you how to use the RMNet Application Programming Interface (API) to emulate a browser that extracts information from a web site or interacts with a web service using SOAP.

RMNet moves data between the a web client, which is typically an ACUCOBOL-GT extend program, and a web server. A Universal Resource Locator (URL) describes the resource. The resource dictates the data format. For example, if submitting data to a web form used by a browser, the data must be formatted to comply with the W3C specification for application/x-www-form-urlencoded. When interacting with a SOAP web service, XML documents are exchanged.

This tutorial also describes how the temperature conversion sample program was created. This program is in the %PUBLIC%\Documents\Micro Focus\extend x.x.x\sample\rmnet folder. Additional information is also provided that may be used when scripting an HTTP interaction with a web server.

Parent topic: Tutorial: Using RMNet to Move Data Between Your Program and a Web Server
Next topic: Tutorial Prerequisites


Tutorial Prerequisites

This tutorial has prerequisites. Please make sure you have the following available before proceeding.

  • The XML Extensions reference documentation, this can be found in the section Working with Non-Vision Data in A Guide to Interoperating with ACUCOBOL-GT.
  • A web services client is needed to obtaining web services metadata. This tutorial uses soapUI, which may be found at www.soapui.org. Download and install soapUI.
  • RMNet is a web client that uses the HyperText Transfer Protocol (HTTP). While it is not necessary to be an HTTP expert, this tutorial presumes familiarity with basic HTTP terminology such as the HTTP methods GET and PUT, HTTP headers, and cookies. Several web-based HTTP tutorials are available.
  • This tutorial creates XSLT documents for creating SOAP requests and consuming SOAP responses. Familiarity with basic XSLT is presumed. Several web-based XSLT tutorials are available.
Parent topic: Tutorial: Using RMNet to Move Data Between Your Program and a Web Server
Previous topic: Introduction
Next topic: Building a SOAP Web Service Client


Building a SOAP Web Service Client

The temperature conversion web service is an sample web service provided by the w3schools.com tutorial web site, which provides a large offering of tutorials on many web technologies. A web service provides a Web Services Definition Language document, also called a WSDL, that defines the location of the service, its methods (or functions) and the request and response documents for those methods. The temperature conversion web service is located at URL http://www.w3schools.com/webservices/tempconvert.asmx.

You can use SoapUI to obtain the WSDL for the temperature conversion web service by entering the WSDL for the URL in a SOAP project. To do this, you enter the URL http://www.w3schools.com/webservices/tempconvert.asmx?WSDL for the SOAP project. Using an initial WSDL performs an HTTP GET on the URL, which is a fairly conventional mechanism of publishing the WSDL for a web service. Since SOAP requests always use POST to a URL, a GET can be interpreted as a request for the WSDL or, as in this case, a GET of the URL with a query parameter 'WSDL' is interpreted as a request for the WSDL.

Note:

Some web services do not make a WSDL available via the web, due to security or other concerns, but rather have some other means to deliver a file containing the WSDL. If you use a browser to GET the WSDL, you may need to look at the page source to see the XML information that makes up the WSDL.

A WSDL is a very complex document and not readily decipherable. This tutorial uses SoapUI, an open source web services testing tool to obtain the WSDL. soapUI can create much more usable request and response documents which can in turn be modified to create XSLT style sheets to be used with XML Extensions.

See Prerequisites for more information about using SoapUI for this tutorial.

Parent topic: Tutorial: Using RMNet to Move Data Between Your Program and a Web Server
Previous topic: Tutorial Prerequisites
Next topic: Starting SoapUI and Creating the Project


Starting SoapUI and Creating the Project

  1. Start the SoapUI application from the start menu. Once you close a start up dialog box or Version Update dialog box, the SoapUI work area appears.

    The left pane provides an area to define and navigate projects and their assets. The right pane contains windows that are associated with a selected project.

    Follow these steps to create a project to test the first example.

  2. Click File > New SOAP Project.
  3. In the New SOAP Project dialog box, type a name for the project.
  4. Enter http://www.w3schools.com/webservices/tempconvert.asmx?WSDL for the WSDL. Since the temperature conversion web service provides a WSDL as the result of a GET on the endpoint URL with the WSDL query parameter appended, only a name for the project and the URL of the web service end point is needed.
  5. Ensure the Create Requests: check box is checked. This lets SoapUI create a prototype request document for each method. Click OK.

Two bindings display in the left pane, named TempConvertSoap and TempConvertSoap12. Each binding has two methods, CelsiusToFahrenheit and FahrenheitToCelsius. This tutorial uses theTempConvertSoap binding.

Tip: A binding is a set of operations or functions that can be invoked. This web service presents the same set of functions available in each binding. The bindings differ in the technical details between different versions of SOAP.
Parent topic: Tutorial: Using RMNet to Move Data Between Your Program and a Web Server
Previous topic: Building a SOAP Web Service Client
Next topic: Creating Request and Response Prototypes


Creating Request and Response Prototypes

  1. Under the TempConvertSoap binding in the SoapUI right pane, expand the selection for the FahrenheitToCelsius method. A prototype request named Request 1 appears in the node under the FahrenheitToCelsius method.
  2. Double-click Request 1 to open the prototype request as XML in an editor window. The XML contents should be similar to the following:
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.w3schools.com/webservices/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:FahrenheitToCelsius>
         <!--Optional:-->
         <web:Fahrenheit>?</web:Fahrenheit>
      </web:FahrenheitToCelsius>
   </soapenv:Body>
</soapenv:Envelope>

    The prototype request displays the question mark (?) character anywhere input values are required to create a valid request. For this tutorial, you must supply a numeric value for Fahrenheit. The web service uses this value to compute the Celsius equivalent to return.

  3. In the line <web:Fahrenheit>?</web:Fahrenheit>, replace the question mark character (?) with 212.
    Note: 212 is the Fahrenheit temperature at which water boils.
  4. Press the green arrowhead at the upper left of the request window. This sends the request to the endpoint URL.

    SoapUI sends the request to the web service and displays the result in another window, which contains the result of 100 as the Fahrenheit value of 212 converted to Celsius:

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <FahrenheitToCelsiusResponse xmlns="http://www.w3schools.com/webservices/">
         <FahrenheitToCelsiusResult>100</FahrenheitToCelsiusResult>
      </FahrenheitToCelsiusResponse>
   </soap:Body>

    You now have prototypes for both the request and response and can create XSLT style sheets to use with XML extensions

Parent topic: Tutorial: Using RMNet to Move Data Between Your Program and a Web Server
Previous topic: Starting SoapUI and Creating the Project
Next topic: Creating XSLT Stylesheets to Use with XML Extensions


Creating XSLT Stylesheets to Use with XML Extensions

Now that prototypes are created for the request and response, you can create the XSLT stylesheets to be used with these XML Extensions.

  1. Make sure SoapUI is still open and the windows showing the request and the response are both open.
  2. Open any simple text editor.
  3. Copy the lines of the request from the request window in SoapUI to the text editor, and save as a text file with the name TempConvertRequestF2C.xsl.
  4. Open another editor window in the text editor, and copy the lines of the response from the response window in SoapUI to the text editor. Same this file with the filename TempConvertResponseF2C.xsl.
  5. Determine whether a SOAPAction HTTP binding parameter is needed. The SOAPAction parameter is an optional part of a SOAP 1.1 and SOAP 1.2 web service definition. SOAPAction is an HTTP header that assists the web server's determination of the type of the SOAP request without investigating the XML payload.

    To determine whether the parameter is needed, click the Fahrenheit to Celsius binding entry in the Soap UI Projects navigation pane. The Operation Properties pane below the Projects navigation pane displays parameters present in the WSDL. If the SOAPAction property for the WSDL contains a value, the value must be used in a SOAP request.

Parent topic: Tutorial: Using RMNet to Move Data Between Your Program and a Web Server
Previous topic: Creating Request and Response Prototypes
Next topic: Converting the Request and Response to XSLT


Converting the Request and Response to XSLT

XSLT is used convert the XML output of an XML OUTPUT FILE/TEXT operation from the XML dictated by the COBOL record layout to the desired XML. The COBOL record layout for the request is:
    01  Fahrenheit-To-Celsius.
        02  Fahrenheit     pic x(3) value zeros.

When exported, the untransformed XML document has the following structure:

    <fahrenheit-to-celsius>
        <fahrenheit>0</fahrenheit>
    </fahrenheit-to-celsius>

However, the desired XML document for the request is:

    <soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”>
       <soapenv:Header/>
       <soapenv:Body>
          <FahrenheitToCelsius xmlns="http://tempuri.org/">
             <Fahrenheit>?</Fahrenheit>
          </FahrenheitToCelsius>
       </soapenv:Body>
    </soapenv:Envelope>
Note that the desired document has been simplified in these ways:
  • The XML comment has been removed.
  • The XML namespace alias tem is removed and the namespace declaration is moved to the <FahrenheitToCelsius> element. This simplified document is logically equivalent to the original copied from SoapUI.

You can create an XSLT for this transformation by adding a few XSLT processing instructions to the desired XML document. Where values are required from the input document (that is, the untransformed document shown above), the processing instruction <xsl:value-of…> is used. The resulting XSLT style sheet is as follows:

<xsl:stylesheet	version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
   <xsl:output method="xml" encoding="UTF-8" indent="yes"/>
   <xsl:template match="/">
    <soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”>
       <soapenv:Header/>
       <soapenv:Body>
          <FahrenheitToCelsius xmlns="http://tempuri.org/">
             <Fahrenheit><xsl:value-of select="fahrenheit-to-celsius/fahrenheit"/></Fahrenheit>
          </FahrenheitToCelsius>
       </soapenv:Body>
    </soapenv:Envelope>
   </xsl:template>
</xsl:stylesheet>

The information shown in bold are the added lines.

Creating the XSLT to process the response is similar, but targets the XML structure derived from the COBOL record layout. The COBOL layout to receive the response is:

01  Fahrenheit-To-Celsius-Response.
    02  Fahrenheit-To-Celsius-Result   pic X(20).

The XML document derived from this record layout has the following structure:

<fahrenheit-to-celsius-response>
    <fahrenheit-to-celsius-result></fahrenheit-to-celsius-result>
</fahrenheit-to-celsius-response>

The web service SOAP response is (omitting unused namespace alias declarations):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <FahrenheitToCelsiusResponse xmlns="http://tempuri.org/">
         <FahrenheitToCelsiusResult>100</FahrenheitToCelsiusResult>
      </FahrenheitToCelsiusResponse>
   </soap:Body>
</soap:Envelope>

Like the request, XSLT response processing instructions must be added into the desired XML document (that is, the one derived from the COBOL record layout), and <xsl:value-of…> fetches values from the input document (the SOAP response).

<xsl:stylesheet	version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                              xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
                              xmlns:a="http://tempuri.org/">
    <xsl:output method="html" encoding="UTF-8" indent="yes"/>
    <xsl:template match="/">
        <Fahrenheit-To-Celsius-Response>
            <Fahrenheit-To-Celsius-Result>
                <xsl:value-of
     select="soap:Envelope/soap:Body/a:FahrenheitToCelsiusResponse/a:FahrenheitToCelsiusResult"/>
            </Fahrenheit-To-Celsius-Result>
        </Fahrenheit-To-Celsius-Response>
    </xsl:template>
</xsl:stylesheet>

This response style sheet is only slightly more complex than the request style sheet. A SOAP document uses XML namespaces for the SOAP envelope and the SOAP body content. Therefore, the required namespace aliases are declared in the <xsl:stylesheet> processing instruction and used in the XPath expression in the <xsl:value-of> instruction. This style sheet does not do any error processing as might be needed if the web service returned a SOAP fault.

Parent topic: Tutorial: Using RMNet to Move Data Between Your Program and a Web Server
Previous topic: Creating XSLT Stylesheets to Use with XML Extensions
Next topic: Creating the Web Service Client Program


Creating the Web Service Client Program

This part of the tutorial looks at the COBOL program that issues the web request, focusing on the XML manipulations as well as the CALLs that interact with RMNet.

After a Fahrenheit temperature is accepted from the operator, the following statements create the SOAP envelope for the request:

XML EXPORT FILE
    Fahrenheit-To-Celsius
    "TempFahrenheitRequest.xml"
    "Fahrenheit-To-Celsius"
    "TempConvertRequestF2C.xsl".
if not XML-OK go to z.
XML EXPORT TEXT
    Fahrenheit-To-Celsius
    request-payload
    request-len
    "Fahrenheit-To-Celsius"
    "TempConvertRequestF2C.xsl".
if not XML-OK go to z.

The XML EXPORT FILE is for illustrative purposes only. It produces a copy of the XML that is created by the XML EXPORT TEXT. A production program would not include the XML EXPORT FILE. At the end of these statements, request-payload and request-len point at the text string that contains the XML to be sent to the web service as the payload in the HTTP request.

call "NetInit"
  giving
    response-status.

call "HttpPost"
  using
    Post-Address
    Content-Type
    request-payload
    request-len
    response-payload
    response-len
    Desired-SOAP-Action
  giving
    response-status.

NetInit is called to initialize the RMNet interface. Then, HttpPost is called to make a POST request to the URL contained in Post-Address. The Content-Type parameter describes the MIME type and character encoding of the payload. In the case of a SOAP request, the MIME type should always be text/xml.

If you were creating a POST to a web form, then your payload would not be XML, and the content type would be application/x-www-form-urlencoded.

The request-payload and request-len parameters are the pointer and length of the request payload (created in the XML EXPORT TEXT). The response-payload and response-len parameters receive the pointer and length of the response payload received in the HTTP response to the POST. Finally, the last parameter, used to supply extra HTTP headers, (named Desired-SOAP-Action here) adds the SOAPAction header name/value pair. (The need for a SOAPAction header was discovered when we used soapUI to look at the WSDL.)

Following the CALL to HttpPost, there follows some error checking:

set address of http-response to response-payload.

display "Response: ", response-status.

if not response-status = 0
  call "NetGetError" using response-payload response-len
                     giving response-status-2
  set address of http-response to response-payload
  display "Error! ", response-status
  display "Error message: ", http-response(1:response-len)
  call "NetFree" using response-payload
  go to z
end-if

This is 'normal' error processing if the response status is nonzero. Note that the reuse of response payload pointer is a convenience

Finally, the response document, a SOAP envelope containing the response value, needs to be imported.

           XML FREE TEXT
               request-payload.

           if response-payload = NULL
               display "Error:  NULL pointer returned", line 10, blink
               accept a-single-char prompt
               go to z
           end-if.

           XML PUT TEXT
               response-payload
               response-len
               "TempFahrenheitResponse.xml".
           if not XML-OK go to z.

           XML IMPORT TEXT
               Fahrenheit-To-Celsius-Response
               response-payload
               response-len
               "Fahrenheit-To-Celsius-Response"
               "TempConvertResponseF2C.xsl".
           if not XML-OK go to z.

           call "NetFree"
             using
               response-payload.

           call "NetCleanup".

The request, which is memory allocated by XML Extensions, is returned; it is no longer needed. The XML PUT TEXT is for illustrative purposes, and would not be present in a production environment. The XML IMPORT TEXT imports the required data from the response SOAP envelope, using the XSLT developed above. At this point the response payload is no longer needed and the memory is returned using NetFree. Finally, NetCleanup is called to terminate RMNet processing, allowing it to release any resources that may have been acquired during its processing.

Parent topic: Tutorial: Using RMNet to Move Data Between Your Program and a Web Server
Previous topic: Converting the Request and Response to XSLT


Maintaining State Cookies

Some web services and many form-based web sites rely on a web client mechanism to maintain information that allows the server to reestablish a request context or reconnect with a process awaiting the request. The mechanism most often used for this purpose is cookies.

Cookies come in two forms:
  • Persistent cookies - Maintained between sessions in a disk file on the client machine
  • Session cookies - Exist only during the lifetime of a web client instance.

Cookies work behind the scenes in browsers. You must enable cookies in your web client to inform RMNet about the files that maintain persistent cookies. You do this by calling HttpSetCookieFile at the beginning of your client session. HttpSetCookieFile may be called multiple times to inform RMNet about several files that maintain persistent cookies. To use only session cookies, call HttpSetCookieFile without using the cookie file parameter or set the file name parameter to spaces. In RMNet terms, a session exists between the call to NetInit and the call to NetCleanup.

Parent topic: Working with Web Site and Web Service Data


Secure Sockets (SSL)

Some web services require a secure HTTP for data transfer. The most common protocol to implement a secure HTTP transfer over a network is known as HTTPS (or HTTP over SSL). RMNet is compatible with SSL (or TLS as the latest version of the standard is called). SSL encrypts all the data that is sent and received over a network. In an HTTPS environment, certificates can be used to validate the identity of the server and/or client.

RMNet supports the use of both server-side and client-side SSL certificates. While you may have programs that need to access data from secure web sites when using RMNet , this tutorial, does not employ SSL/HTTPS and does not teach this subject.

Search the OpenSSL Project web site at http://www.openssl.org/ for additional information about SSL. OpenSSL is used by libcurl, and therefore by RMNet, for SSL support.

Parent topic: Working with Web Site and Web Service Data


Response Header Processing

Some web sites have used an ad hoc approach to providing information over the web. Although HTTP is normally treated as a transport layer, existing only to move content, some web developers have chosen to return information in the HTTP headers of the response.

Note: Cookies are also transmitted by HTTP headers. However, cookies are normally used to associate a series of messages, which is a reasonable function for the transport layer.

If you need to get data from the HTTP headers of the response, you must call HttpSetResponseHeader prior to the call to HttpPost or HttpGet.

Parent topic: Working with Web Site and Web Service Data


Working with Relational Data

We provide several ways to integrate COBOL applications with relational databases based on Structured Query Language (SQL):

  • using the seamless Acu4GL interface
  • using embedded SQL (ESQL) and an ESQL pre-compiler
  • AcuXDBC relational database system

See each of these product's user guides for details.

Parent topic: Working with Non-Vision Data


Working with C-ISAM and KSAM

We provide interfaces between ACUCOBOL-GT programs and data on file systems such as C-ISAM and KSAM.

C-ISAM files can be accessed through a special interface routine that is linked into the ACUCOBOL-GT runtime system and is invoked when your program is executed. You do not need to embed C-ISAM commands in your code. This interface is described in a supplement to the ACUCOBOL-GT manual set titled, "Interfacing to the C-ISAM File System."

KSAM files can be accessed through HP COBOL system intrinsic functions or via standard COBOL I/O statements. Specific instructions for accessing these files are provided the Transitioning to ACUCOBOL-GT guide.

Parent topic: Working with Non-Vision Data


Working with an EXTFH Interface

You can readily configure the ACUCOBOL-GT runtime to use an EXTFH interface for communicating with external file systems that contain indexed, relative, or sequential files. The EXTFH interface is enabled and linked into the runtime by default.

The EXTFH interface provides a way for applications to transparently access a file system such as DB2 for record storage. In transaction processing environments, EXTFH is typically used to handle data access for batch programs. For online programs, you can easily add data access methods to an application.

  • Using the EXTFH Interface
  • Making EXTFH Libraries Available to the Runtime
Parent topic: Working with Non-Vision Data


Using the EXTFH Interface

Two basic requirements are needed to configure the ACUCOBOL-GT runtime to utilize the EXTFH interface:

  1. Specify the file system(s) that is using the EXTFH interface to access files.
  2. Dynamically load the EXTFH libraries using runtime configuration variables or by statically linking the EXTFH-compatible libraries with the runtime.

After you configure the runtime, the COBOL data access methods are unchanged. The same COBOL file I/O statements are used whether accessing native file systems or using EXTFH.

Parent topic: Working with an EXTFH Interface


Making EXTFH Libraries Available to the Runtime

To use an EXTFH interface, you must make a library available to the runtime that implements an EXTFH-compatible function and include all the necessary support libraries.

Note: The vendor of your environment must supply the libraries that contain EXTFH-compatible functions for any data sources you want to access. ACUCOBOL-GT does not supply these libraries.

Use the following procedures to make the libraries available:

  1. Specify that the file system is EXTFH.
  2. Specify the library using one of these options:
    1. Rely on the default EXTFH function names or specify one or more function names in a configuration variable.
  3. Specify a single EXTFH library name or different library names for relative, sequential, and/or indexed files using configuration variables.
  4. Relink the ACUCOBOL-GT runtime.

We recommend that you set the A_EXTFH runtime configuration variable to dynamically load the EXTFH library or use other A_EXTFH configuration variables to specify different libraries for specific file types.

Regardless of what method you use, you also need to set at least one of the file system configuration variables to access files through the EXTFH interface.

  • Accessing Files Through EXTFH
  • Searching for Function Names
  • Setting Libraries for Indexed, Relative, and Sequential Files
Parent topic: Working with an EXTFH Interface


Accessing Files Through EXTFH

By default, all file access is handled by the ACUCOBOL-GT native file handler. For those file types you want to access using an EXTFH library, you need to set one (or more) of the following configuration variables to "EXTFH":

DEFAULT_FILESYSTEM

DEFAULT_IDX_FILESYSTEM

DEFAULT_REL_FILESYSTEM

DEFAULT_SEQ_FILESYSTEM

filename_FILESYSTEM

Note that when you use filename_FILESYSTEM, the file suffix is not included in the configuration variable definition. If the filename is "outputfile.tmp", for example, set this variable as:

outputfile_FILESYSTEM

To use the DB2 library to access indexed files and the ACUCOBOL-GT native file handler for sequential and relative files, set the following two configuration variables:

A_EXTFH_LIB=/pathname/libraryname.o
DEFAULT_IDX_FILESYSTEM=EXTFH

For more information on these configuration variables, see Configuration Variables.

  • Specifying a Single EXTFH Library Name
Parent topic: Making EXTFH Libraries Available to the Runtime


Specifying a Single EXTFH Library Name

The simplest way to implement the EXTFH interface is to specify the file name or absolute path of a single EXTFH shared object library as the value of A_EXTFH_LIB. When you use this method, the runtime loads the specified library in order to find the necessary EXTFH function or functions.

For example, to use the EXTFH library supplied with TXSeries CICS for DB2, specify:

A_EXTFH_LIB /usr/lpp/cics/lib/libxfhdb2sa.a(libxfhdb2_shr.o)

where "libxfhdb2_shr.o" contains the entry point to the DB2 EXTFH library and resides in the "libxfhdb2sa.a" AIX archive. In this case, if your LIBPATH variable includes the path where the library resides, you can omit the path; otherwise, include the path as part of A_EXTFH_LIB.

You can also specify the EXTFH library as an environment variable. For example, you can specify the same EXTFH library for accessing DB2 files from TXSeries using:

export A_EXTFH_LIB="/usr/lpp/cics/lib/libxfhdb2sa.a(libxfhdb2_shr.o)"
Note:

An AIX archive file (".a") can contain shared objects. You must specify the shared object in parentheses after the archive name unless you link to the archive.

Parent topic: Accessing Files Through EXTFH


Searching for Function Names

By default, the runtime searches for functions named "cics_xfh", "cobol_extfh", and "EXTFH" in that order. If your EXTFH function uses a different name, you may also need to set a configuration variable to specify the function name (such as A_EXTFH_FUNC). If necessary, you can also specify a different function name for relative, sequential, and/or indexed files. For more information on A_EXTFH_FUNC and related configuration variables, see A_EXTFH_FUNC.

Parent topic: Making EXTFH Libraries Available to the Runtime


Setting Libraries for Indexed, Relative, and Sequential Files

To use different EXTFH libraries for indexed, relative, and sequential files, you can set the file names or paths of the libraries in one or more of the following variables:

  • A_EXTFH_IDX_LIB
  • A_EXTFH_REL_LIB
  • A_EXTFH_SEQ_LIB

The ACUCOBOL-GT runtime uses A_EXTFH_LIB as the default EXTFH library for all three file types. If one or more of these three variables is also set, the runtime uses its value instead of A_EXTFH_LIB for the corresponding file type.

Remember that when you use configuration variables to identify the library names and specify file names instead of absolute paths, the operating system must be able to find the files in the locations it normally searches for shared libraries. You may need to set the correct search path environment variable, such as LIBPATH on AIX.

Calling conventions for DLLs

All the configuration variables that allow you to specify an EXTFH library name also allow you to specify the calling convention for a particular DLL and thereby override the setting of the DLL_CONVENTION runtime configuration variable. For more information, see DLL_CONVENTION.

Parent topic: Making EXTFH Libraries Available to the Runtime


File System Configuration

As described previously in this chapter, you can use many other file systems in place of, or in combination with ACUCOBOL-GT's Vision file system. Supported file systems include:

XML | enabled and available on all platforms
RMS | used in place of Vision on VMS and OpenVMS platforms
EXTFH interface | enabled and available on all platforms; allows access to most files for which an EXTFH library is available
MPE | available on HP e3000 emulators
C-ISAM | licensed separately; available on most UNIX/Linux platforms
P.SQL/Btrieve | licensed separately; available on most Windows platforms
DB2 | licensed separately; through Acu4GL, or by embedded SQL and the DB2 preprocessor
Oracle | licensed separately; through Acu4GL, or by embedded SQL and the Oracle preprocessor
MS SQL | licensed separately; through Acu4GL, or by embedded SQL with AcuSQL
Informix | licensed separately; through Acu4GL, or by embedded SQL with AcuSQL
Sybase | licensed separately; through Acu4GL, or by embedded SQL with AcuSQL
ODBC-compliant | licensed separately; through Acu4GL, or by embedded SQL with AcuSQL

On most platforms, ACUCOBOL-GT comes preconfigured to work with Vision, XML, and EXTFH. On VMS and OpenVMS systems, Vision is replaced by RMS.

Configuration information for file systems that use a separately licensed product is included in the documentation provided with that product. For information about Acu4GL, AcuSQL, and compatible embedded SQL technologies, see their respective user's guides, or contact your Micro Focus extend Sales Professional.

Parent topic: Working with Non-Vision Data


File System Initialization

By default, with the exception of the EXTFH interface, ACUCOBOL-GT initializes enabled file systems upon runtime startup, before the first COBOL program begins execution. Initialization of the EXTFH interface, by default, is deferred until the first file operation on the file system. This provides the best runtime performance.

If you want to force initialization of EXTFH at startup, or you want to defer initialization of another file system, you can do so by setting a variable in "filetbl.c" and relinking the runtime. "filetbl.c" holds the ACUCOBOL-GT file system table. Settings in "filetbl.c" determine which file systems are enabled and when each system is initialized. "filetbl.c" is located in the lib subdirectory of your ACUCOBOL-GT installation.

To specify file system initialization for a given file system:

  1. Open "filetbl.c" in a text editor.
  2. Locate the TABLE_ENTRY for the file system you want to control, and change the defer_init parameter to the desired value. A value of "0" causes the file system to be initialized at startup. A value of "1" causes file system initialization to be deferred. The defer_init flag is set to "0" by default for all file systems except EXTFH.

    For example, following is the TABLE_ENTRY for Vision:

    TABLE_ENTRY  file_table[] = {
#if   USE_VISION
   {   &v5_dispatch,   "VISIO", 0 },
#endif /* USE_VISION */

    The defer_init value is the value that follows "VISIO" on the third line.

  3. When you have made your changes, save and close the file and relink the runtime. See Relinking the Runtime System for more information.

If a deferred file system initialization fails, the file status is set to 9B (32 for IBM DOS/VS) to indicate that the requested operation is not supported.

Note: Starting the runtime with the "-v" option forces startup initialization of all enabled file systems, as well as output of version information. For a complete description of the "-v" option, see Standard Options.
Parent topic: Working with Non-Vision Data


Properties, Styles, and Methods

ActiveX controls have properties and styles just like ACUCOBOL-GT controls. In addition, ActiveX controls provide functions called methods. To set a property or style or to invoke (call) a method, you use the MODIFY verb. Use INQUIRE to get the value of a property or to get the style flags.

ActiveX methods can take any number of parameters or no parameters. They can also take optional parameters (i.e., parameters that can be omitted). You specify the parameters in COBOL by enclosing them in parentheses. If there are no parameters, include empty parentheses (). Optional parameters are always last. For example, if a method has three parameters, one of which is optional, the first two are required. The last one is optional and therefore may be omitted. For more information on ActiveX methods, refer to ACUCOBOL-GT User Interface Programming > Supporting Concepts > Methods .

Note that ActiveX properties and methods should always be prepended with an "@" sign in case they clash with COBOL reserved words or ACUCOBOL-GT graphical control property and style names. The "@" symbol identifies the relationship of the name to ActiveX. The same holds true for ActiveX enumerators.

When programming with ActiveX controls and COM objects, you can create simpler statements by using named parameters. ActiveX controls and COM objects provide the option of using named parameters as a shortcut for typing parameter values in MODIFY and INQUIRE statements. With named parameters, you can provide any or all of the parameters, in any order, by assigning a value to the named parameter. This is especially useful when an ActiveX/COM method or property has several optional arguments that you do not always need to specify.

Note: You cannot use named parameters to avoid entering required parameters. You can omit optional parameters only.

Generally, if the COBOL program passes a parameter in binary or numeric form with no decimal point, the runtime creates a variant of type VT_I4 (4-byte signed integer) before passing it to the property or method. If the program passes the parameter in numeric with a decimal point or in floating point, then the runtime creates a variant of type VT_R8 (8-byte floating point number). And if the COBOL program passes an alphabetic or alphanumeric parameter, then the runtime creates a variant of type VT_BSTR (Unicode string) before passing it to the property or method.

Note that you do not have to make a conversion from an ACUCOBOL-GT Working Storage item to a variant datatype in order to pass data to an ActiveX/COM property or method. The runtime handles all conversion that is required for you. For example, if you have a method in your definition file like this:

METHOD, 10, @Send,
     "VARIANT" @From, TYPE 12,
     "VARIANT" @To, TYPE 12,
     "VARIANT" @Subject, TYPE 12,
     "VARIANT" @Body, TYPE 12,
     "VARIANT" @Importance, TYPE 12
        OPTIONAL5

You do not have to convert your data before passing it. Rather, all you need to consider is what data to pass. (The runtime does the conversion so focus on the content.) In this case, you would pass sender, recipient, subject, message, and importance.

If the ActiveX or COM object with which your program is interacting expects the parameter of a different variant type, you must tell the runtime by using the AS type-num phrase in the parameter expression of the MODIFY or INQUIRE statement (where type-num indicates the variant type to pass). The runtime then converts the parameter to the variant type that you specify before passing it to the object.

You can tell from the object's documentation and the name of the parameter whether the object expects a particular variant type, such as boolean.


Starting AcuXDBC on the Server (Network Only)

If you or your users are operating in a network environment, the final step is to start the AcuXDBC Server daemon on the server. If you are operating on a local machine, this step is not necessary; you can begin using ODBC applications to access your data right away.

AcuXDBC Server can be started under any user ID on the system. In this mode, all file access will be performed using the user and group ID under which the daemon was started. You also have the option of startingAcuXDBC under the root or superuser account and turning on operating system (OS) authorization checking with the -a option. This option lets one user start a process and pass ownership to another. In this mode, you must pass a valid operating system user ID and password as part of the connect string. AcuXDBC Server uses this information to perform an OS authentication of the user and then spawn a process to handle the requests using this user information.

To perform these functions on a Windows NT or Windows 2000 server, you should be logged in from the Administrator account or from an account that belongs to the Administrators group.


Windows Client Procedure

If you will be using AcuXDBC in a client/server configuration, you will first need to set up and configure AcuXDBC on the server machine for local access. Once you have completed this configuration, you can start the server and test client/server connections locally.
  1. Install AcuXDBC software on the client.
  2. Set up a Data Source Name (DSN) for your Vision data. This step is not required if you plan to use a query tool to issue SQL queries and do not require ODBC integration.
Related tasks
Server Procedure
Related information
AcuXDBCServer_Installations


UNIX/Linux Client Procedure

  1. Install AcuXDBC on the client.
  2. Download an ODBC driver manager for UNIX/Linux, such as unixODBC.
  3. Add DSN information to an ODBC text file according to the driver's instructions.
  4. Modify environment and configuration variables.
Related tasks
ServerProcedure_Install
WindowsClientProcedure_Install
Related information
AcuXDBCServer_Installations


CREATEXFD directive

Use the CREATEXFD directive to tell the compiler to generate XFDs for the COBOL files contained in your program.

Syntax

$SET CREATEXFD(version=n, xfd-directory=pathname, file-type=all)

All of the arguments are optional, and can be given in any order.

"version=n" | Causes XFD files of type n to be used. Currently, "6" is the only valid value here. Any other value causes XFD files of the latest version to be created
"xfd-directory=path" | Causes the XFD files to be created in the directory named by pathname. pathname must be a valid directory, either absolute or relative, and must be writable to the user
"file-type=all" | Causes XFD files for all file types to be created. Without this argument, the compiler creates XFD files for only indexed files. If anything other than "all" is specified, the compiler creates XFD files only for indexed files

Example

In the following example, the CREATEXFD directive tells the compiler to generate Version 7 XFDs in the directory v:\animals\xfds for all file types found in the FD — indexed, relative, and fixed-length sequential.

You will need to add the CREATEXFD directive before the first COBOL “SELECT” statement.

$SET CREATEXFD
     SELECT jr-file
        ASSIGN TO "animals"
        ORGANIZATION IS INDEXED
        ACCESS IS DYNAMIC
        RECORD KEY IS patient-id
        FILE STATUS IS jr-file-status.

 DATA DIVISION.
 FILE SECTION.
 FD  jr-file.
 01  jr-record.
     03  animal-info.
         05  patient-id                  pic 9(5).
         05  atype                       pic x.
         05  ctype redefines atype       pic x.