=========================================================================
M I C R O F O C U S
D I A L O G S Y S T E M V 2.5
C H A R A C T E R
V4.1.10
Running Under The DG/UX
Operating System Version R4.11MU03
On The AViiON
=========================================================================
DOCUMENTATION UPDATE NOTES
==========================
TABLE OF CONTENTS
=================
INTRODUCTION
RELEASE NOTES
ON-DISK SUPPLEMENTS
CHANGES TO PRINTED BOOKS
SUPPLEMENTARY INFORMATION
INTRODUCTION
============
These documentation update notes give information that was not available
when the books were printed:
- Large additions are documented in separate documents called on-disk
supplements, listed in the section "On-disk Supplements" below.
- Where practicable, smaller additions are given as changes to the text
of the books, in the section "Changes to Printed Books" below.
- Otherwise, smaller additions are given in the "Supplementary
Information" sections below.
Changes made to the software in maintenance releases are reflected in
additions to this document. New features available only to subscribers to
an Annual Maintenance Agreement (see your main release notes) are not
reflected in this document.
RELEASE NOTES
=============
Dialog System includes the following on-disk documents, called release
notes, containing "stop press" and administrative information. They will
be updated at every maintenance release.
dialog.1 Main Release Notes
dsdun.1 Documentation Update Notes
dsfeat.1 New Features
ON-DISK SUPPLEMENTS
===================
Dialog System contains the following on-disk supplements.
None
CHANGES TO PRINTED BOOKS
========================
Getting Started with Dialog System
==================================
Chapter 1 (Welcome to Dialog System)
------------------------------------
o On page 1-9, the UNIX information should be changed to read:
Your Micro Focus Product Reference number (PRN). This number can
be found in a file called dsmotver.
o On page 1-10, add the following line to the list of telephone numbers
for the Micro Focus Bulletin Boards:
Spain (343) 347 05 76
o On page 1-11, add the following line to the list of fax numbers for
the Micro Focus offices:
Spain (343) 435 67 33
Chapter 4 (Sample Session in Character Mode)
--------------------------------------------
o On page 4-15, replace the opening paragraph in the section "The
Program" with the following:
Use an editor to enter the program listed below, and save it as
test1.cbl.
Dialog System Character Mode User Guide
=======================================
Chapter 2 (Getting Started)
---------------------------
o On page 2-8, change the description of the * prefix character to be !
(exclamation mark) under UNIX, instead of - (hyphen).
o On page 2-8, add the following information to the end of the chapter:
When running in batch mode, the command line is displayed on the
screen. After run completion you receive either the message
'Completed OK' or an error message.
A log file (DS.LOG) is either created in the current directory,
or, if it already exists, is appended with the information that
is displayed on the screen. Every log file entry contains a date
and time stamp.
This file is in text format, and can be listed or edited. You can
delete the file, in which case a new log file will be created in
the current directory during the next batch run.
Chapter 4 (Data Definition)
---------------------------
o Page 4-18, 4-19. Replace the section headed User Validation (F7) with
the following text:
User Validation (F7)
Pressing \bF7=user-validation\p from the Validation menu enables
you to apply your own validation type to any field, cross-validate
with other fields, set flags or change data in the data block, and
dynamically change the error message for display.
The user validation menu is displayed.
Allow/ Disallow User-validation (F2)
Pressing \bF2=allow/disallow-user-validation\p from the
User-validation menu enables you to toggle between the allow and
disallow user validation options. If you choose the "allow
user-validation" option, you can assign an error message number to
this validation.
Default: Disallow user-validation.
At run time, when you are about to exit a field which has user
validation enabled, the module DSUSRVAL is called. This module is
passed the Control Block and full Data Block, as well as a small
Status Block. DSUSRVAL contains validation code written by you.
Micro Focus ships a skeleton source of this module, containing
comments to help you add your own code.
You use the Control Block to establish the screenset, panel,
field-number and occurrence of the current field. Because of this
level of control, the single module DSUSRVAL can be used by many
different screensets, panels and fields.
To simplify the setting up of the current field in the user code,
Dialog System can generate a copybook for each screenset you need
to include in the source of \bdsusrval.cbl\p. These copybooks
are similar to the standard screenset copybooks (\b.cpb\p), but
are tailored for use specifically for inclusion in the user
validation source file. You generate these copybooks using
\bF5=Generate\p from the main menu.
Note:
The copybook generated for screenset use is not interchangeable
with the copybook generated for user validation. Therefore, ensure
you use two different extensions for them. For example, \b.cpb\p
and \b.cpu\p.
You use the copybook code to reference fields in the Data Block by
name, and to identify the current field from the Control Block
field number by using the associated constant (level-78) names in
the copybook.
After validating the field, you can flag it as valid or invalid.
If invalid, any error message you associated with this validation
is, by default, displayed in your message data item. You can
override this by specifying an error message number which will
cause the corresponding message to be displayed.
See the chapter \bProgramming\p for more details of the DSUSRVAL
module.
Chapter 5 (Panels)
-----------------
o Page 5-12. Add the following text to the description of Generate (F6):
You can generate additional dialog that allows the mouse to be
used to control the menu bar and the drop down menus when the
application is run.
You need to use a CALLOUT program, dsactbar.cbl, which is supplied
with Dialog System. Amend it to include a special copyfile,
created by Dialog System at CUA generation time, called
screenset-basename.cua. The source file, dsactbar.cbl, is clearly
documented to show where the copyfile is to be inserted. This file
can hold as many copyfiles as you want, so that this single
program can cater for many screensets with mouse controlled CUA
menus.
Generating CUA menus for mouse control does not alter the keyboard
control that is normally supported; the two interfaces coexist.
Although the mouse support code and dialog is automatically
created for supporting the mouse once the top level CUA menu has
been selected, you must add a small piece of code to allow the top
level menu itself to be activated by the mouse.
Chapter 6 (Setting Up the Configuration File)
---------------------------------------------
o Page 6-11. Add the following two new configuration parameters:
Enable Mouse Support
The configuration parameter MOUSE-ENABLE adds mouse support.
Clicking the left mouse button anywhere within the current input
field causes the cursor to relocate to that position. You do not
need to add new dialog code: the behavior is instantly available
on existing screensets when this parameter is set.
Syntax: MOUSE-ENABLE
Default: No mouse support.
NLS Folding
The configuration parameter NLS causes alphabetic characters
entered into a panel field to be folded (see the chapter \bPanel
Fields\p. If the required NLS routines are not linked into the
application, the application will abort on failing to invoke the
NLS folding routines. If no setting is included, the application
will operate in NLS folding mode if the NLS support routine are
linked in; otherwise, it will default to non-NLS behavior.
Syntax: NLS
Default: No NLS.
Chapter 7 (Panel Fields)
------------------------
o Page 7-4. Add the following text to the descriptions of UPPER and
LOWER:
NLS is supported, for the folding of alphabetic characters. This
feature is optional, and is controlled by either setting NLS in
the sidefile \bdsdef.cfg\p, or by linking \bdsnlsrtn.obj\p as
well as the COBOL system file \bcobnlsmg.obj\p when creating the
executable application.
o Page 7-6. Add a paragraph below the last year format, as follows:
You should note that if your application(s) need to work with the
year 2000 and beyond, you should be using this format. You might
need to revise your existing screenset(s).
-added V2.5.64
Chapter 9 (Dialog)
-----------------
o Page 9-17. Add the following text to the description of Repeat Key
(F8):
When deliberately defining recursive dialog, you can press
\bEnter\p to override the warning message produced.
Chapter 10 (Running the Screenset)
----------------------------------
o Page 10-8. Add the following lines of code below the one for VALUE E:
78 DS-MULTI-POP VALUE "M".
78 DS-TRACE-OFF VALUE "O".
78 DS-TRACE-ON VALUE "T".
78 DS-USE-SET VALUE "U".
78 DS-WHAT-SET VALUE "W".
added V2.5.64
o Page 10-8. Delete the line 05 DS-RESERVED-2, and replace it with the
following lines:
05 DS-MOUSE-DETAILS. PIC X(6).<R>
07 DS-OUTPUT-MOUSE-X PIC 9(2) COMP.<R>
07 DS-OUTPUT-MOUSE-Y PIC 9(2) COMP.<R>
07 DS-OUTPUT-MOUSE-FLD PIC 9(2) COMP.<R>
07 DS-OUTPUT-MOUSE-OCCURRENCE PIC 9(4) COMP.<R>
Chapter 12 (Programming)
------------------------
o Throughout this chapter, change all occurrences of dscerrhn.* to
dserrhan.*
o Page 12-6. Add the following new section before Control of User-defined
Field Formats:
User Validation in Screensets
If you want to use user-validation on your screensets, you must
write a module called DSUSRVAL. Micro Focus ships a skeleton
source of this module, containing comments to help you add your
own code.
The Dialog System Run-time System calls Dsusrval when you are
about to exit a field.
The parameters passed to the routine are:
Dialog Control Block input
Use this to determine the current screenset, panel and field.
Any changes you make to this Control Block are ignored by Dialog
System.
Screenset Data Block input/output
You can access and change any fields for the current screenset in
this Data Block.
DS-User-Val-Status output
If you want to flag a field validation failure, set this flag to
1. If validation is OK, set this field to 0.
DS-User-Error-Number output
This field is ignored unless DS-User-Val-Status is non-zero. When
a field validation error has occurred, if this field is set to 0,
the error message associated with this validation will be
displayed. You can force a different error message to be displayed
by placing its number in this field.
Chapter 13 (Linking)
--------------------
o Throughout this chapter, change all occurrences of dscerrhn.* to
dserrhan.*
o Page 13-2. Delete DSUXPATH.o from the list of modules provided.
o Page 13-2. Add to the list of modules provided, for UNIX:
DSVRSCRN.o Handles variable screen size for menu placement
DSUSRVAL.o User validation
DSUSRFMT.o User field formatting
o Page 13-2. Delete DSUXPATH.o from the list of modules required by all
Dialog System applications.
o Page 13-2. Alter the last paragraph to read:
Depending on the features your application uses, you might not
require all of these object modules. Under UNIX, use -X
module-name to exclude any such modules. The following sections
list the object modules that production applications and
applications in development require.
o Page 13-3. Add to the list of object modules required, for UNIX:
DSUSRVAL.o User validation
DSUSRFMT.o User field formatting
o Page 13-5. References to Dschlink should be changed to read DSCLINK.
o Page 13-5. Add /nls and /st to the dsclink command line.
o Page 13-6. Add the following descriptions to the parameter list:
/nls National language (case folding) support.
/st Static linked application (lcobol). Default is shared
run-time linked application (coblib).
-added V2.5.64
Chapter 15 (Character Set Support on UNIX)
------------------------------------------
o Page 15-3. Replace the first paragraph of The Screenset Conversion
Utility with the following text:
You can use the utility, SSTRAN, to either convert between
screensets using the extended DOS character set, and screensets
using DOS, Windows or OS/2 character sets, or convert attributes
in a screenset. You can also use the utility to convert between
different DOS character sets (codepages).
o Page 15-3. Add a new parameter to the conversion utility command line,
as follows:
cobrun SSTRAN -a [-y] input-screenset output-screenset trans-file
where:
a is a flag indicating that this is an attribute conversion.
o Page 15-4. Add the following sentence below the translation-file
description:
Text and attributes cannot be converted at the same time: a
separate run is needed for each.
o Page 15-5. Add the following section after the Translation Files
section:
Attribute Conversion
When converting attributes, you do not need to define the
screenset type, so the SOURCE and TARGET directives are not used.
To leave some characters unconverted, specify hex FF in the
appropriate position in the conversion string.
If none of the corresponding characters are to be converted, so
the entire translation line would contain FF, you do not have to
specify a line in the translation table for the range.
Micro Focus provides two attribute translation files:
Translation File Converts...
DOSC2M.TRN Colors in a screenset to monochrome
attributes supported by DOS
OLD2NEWM.TRN Old style UNIX monochrome attributes (DS1.1)
to new fully portable style
Chapter 16 (Setting Up the Configuration File)
----------------------------------------------
o Page 16-15. Add the following new configuration parameter:
Keyboard Timeout
The configuration parameter TIMEOUT causes a regular invocation of a
user-supplied program. This provides a degree of system control to
carry out various functions, for example, to initiate regular
backups or cause an emergency shutdown.
This timeout is active only when the cursor is in an input field;
it is a keyboard timeout, and is reset whenever the user hits a
key.
Syntax: TIMEOUT user-written-program-name n...nn
Parameters: user-written-program-name
Is the name of a program written by you, to be
invoked at a given interval.
n...nn
Is the time, in seconds, between each automatic
invocation of the user-written program (theoretically up
to 9999999 seconds). 0 is treated as invalid, and no
calls are made to the user-written-program.
Remarks: The Dialog Screenset itself might use timeout in its
own logic - for example, displaying a help panel if
the user has not entered any data for 1 minute. The
new timeout mechanism described here is designed to
coexist with and not affect any other screenset
timeouts.
In cases where the screenset timeout period is
shorter than the period set for configuration timeout
in dsdef.cfg, then configuration timeout may never
occur. It is thus important that the user-written
program is activated for all timeouts. A flag in the
parameters passed to the user-written program
indicates which sort of timeout triggered the entry.
Where the configuration timeout period is shorter
than the screenset timeout period, then an entry will
be made to the user-written program for each elapsed
configuration timeout period up until the total
elapsed time matches the screenset timeout period,
when an entry will be made for this too.
The single parameter passed to the user written
program is in the form of a parameter block:
01 param-block.
03 screenset-name pic x(8).
03 screen-name pic x(8).
03 field-name pic x(30).
03 timeout-type pic x.
88 screenset-timeout value "S".
88 config-timeout value "C".
03 action pic x comp-x.
88 retc-timeout value 1.
where the first three fields identify the current
screenset, screen and field in the system, the next
identifies whether the timeout is a screenset timeout
(that is, the conventional timeout), or a
configuration file timeout (that is, the new type),
and the last is an action field which the user
written program may set to value 1 to cause an
immediate return to the application, with an error
status of 17 in DS-SYSTEM-ERROR-NO.
This error status is really a notification signal to
the application rather than a true error, and DSRUN
may be subsequently called again. When the
user-written program exits back to Dialog System
without requesting an immediate return to the
application, then Dialog System will take different
courses of action depending on the type of timeout
that occurred:
- For screenset timeout, processing will continue by
executing the user defined timeout procedure, as
usual.
- For configuration timeout, Dialog System will
return to waiting for a keystroke, with the screen
unchanged. The cursor will be positioned as before
timeout, and the contents of the current field (if
one exists) will also be the same as before
timeout. This means that the terminal user should
be unaware that any configuration timeout has
occurred at all.
Dialog System determines which sort of timeout has
occurred by inspecting the timeout-type field on
return from the user-written program.
Thus, in general your own program should not amend
this field.
Chapter 18 (Key Code List)
--------------------------
o Page 18-3. Remove the second paragraph and the line following it
in the section "Any Other Key", describing ANYX ("Within a local
..."). This is not implemented for this product.
o Page 18-3. Add the following new section:
Mouse Support
Mouse support is available via two dialog key mnemonics, MSL and
MSR.
The mouse is visible only when Dialog System is waiting for use
keyboard input.
The left and right mouse buttons have dialog key mnemonics MSL and
MSR respectively. These represent a single click. They can be used
in the same way as other keys to drive dialog functions.
Since in general it is required that the action triggered by a
mouse click be dependent on the mouse position, the position of
the mouse at the time of the click is recorded in the Dialog
System control block.
The X and Y coordinates are character positions, with the position
1,1 being top left of the screen. Note that the coordinates are
relative to the screen and not to the panel.
The last two fields give the field number and its occurrence if
the mouse was positioned within an input field when the mouse was
clicked, otherwise zero valued.
The MSL procedure is not triggered when the cursor is already
located in the same field as the mouse when the left mouse button
is clicked. The cursor simply relocates itself to the mouse
location as described above.
There are thus two methods of taking action on a mouse click.
These are either by returning to the application (RETC) so the
mouse postion can be established and the appropriate action taken,
or by using CALLOUT to a user program, which is passed the control
block and hence the mouse information, and also the data block
which it can modify (or in addition/alternatively the user program
can directly set $REG or the dialog exception condition.
Chapter 19 (Function Code List)
-------------------------------
o Page 19-5. Amend the description of callout-type to read:
callout-type numeric. Must be 0000 or 0006.
When the value 0006 is specified, then the
content of RETURN-CODE on exiting the callout
program is moved into $REG, unless the value is
-9999, when $REG is unaffected, but the dialog
exception condition is set. RETURN-CODE is
always cleared to zero.
o Page 19-6. Amend the description of CLEAR to read:
CLEAR clears all of the fields on the current panel.
o Page 19-9. Add the following new function code:
GOMOUSE
GOMOUSE enables mouse support, without you having to return to the
application or execute a CALLOUT.
Syntax: GOMOUSE number
Parameters: number numeric.
A number that represents the following settings:
+1 Will relocate the cursor to the start of a
different input field (which is not in a
group) after validating the current input
field. If validation fails, no cursor
movement occurs.
+2 Will relocate the cursor to the start of a
different input field (which is in a group
and at the current action bar position) after
validating the current input field. If
validation fails, no cursor movement occurs.
+4 Will relocate the cursor to the start of a
different input field (which is in a group),
relocating the action bar if necessary, after
validating the cursor input field. If
validation fails, no cursor movement occurs.
Remarks: These settings exhibit cumulative behavior.
Example: MLS GOMOUSE 0007
Enables all of these actions for a panel.
o Page 19-29. Amend the description of the SFAT field parameter to read:
field(sub) or register.
Chapter 21 (Error Messages)
---------------------------
o Page 21-3. Add the following error message:
018 Screenset not found (fatal)
This error is returned by the common GUI/Character dsrun module for
the first screenset load of the run. It indicates that the named
screenset has been searched for in character form and in GUI, but
has not been located.
-added V2.5.64
Chapter 22 (Tutorials)
----------------------
o Page 22-1. Remove the first sentence from the section "Tutorial 1 -
Cutting and Pasting Experiment".
SUPPLEMENTARY INFORMATION
=========================
This section gives notes supplementing your manuals.
o When you create applications as full executables, you must link the
file DSLCONV.OBJ. This file supports DBCS transparency.
=========================================================================
Micro Focus is a registered trademark, and Dialog System, Micro Focus
COBOL, and Toolbox are trademarks of Micro Focus Limited.
UNIX is a registered trademark of X/Open Company Limited.
CUA and Current are trademarks of International Business Machines
Corporation.
=========================================================================
@(#)Vrn/dsdun.1/2.5.08/25Apr97/nrV
Copyright (C) 1992-97 Micro Focus Limited.