Enhanced Source Code Format

This section describes the syntax conventions for entering code in the source code window provided by the program editor.


Syntax Conventions

Syntax is described using the following meta-notation:

syntax_element_name :=: description
Syntax Element Represents
syntax_element_name :=: Identifies the construct whose structure is defined by description.
description Program code displayed in UPPER-CASE letters.

The Syntax Symbols used in this section are explained in the Statements documentation. In addition, the following symbols are used within the diagrams:

Symbol Represents
{element1 | element2} Elements contained within braces and separated by vertical bars indicate that exactly one of the elements must be specified.
< > Pairs of angle brackets indicate that code is separated into multiple lines. Each pair of brackets represents the end of a Natural source line.
/*[ and /*] These bracket pairs form a collapsible block in list mode, even in user code sections.

Line-number references are explicitly not supported within dialogs, as the dialog editor will generate line numbers for dialog sources without consideration of any line-number references.

Line length and source size are subject to the general limits imposed by Natural.

Note:
Where syntax elements are shown separated by blanks, blanks are required, but the exact number of blanks is not significant.

How Natural Dialogs Work

This section gives you some background information so you can better understand what the various elements of the dialog source do.

A Natural dialog is an executable module. You invoke it either directly from the Natural environment or from another executing module with an OPEN DIALOG statement. Invoking the dialog causes the dialog's executable to be instantiated and executed with the system variables *CONTROL equal to NULL-HANDLE and *EVENT equal to OPEN. This OPEN event is processed by calling the inline subroutine *DLG$SUBR$CREATE$WINDOW which creates the dialog window. Window creation invokes the dialog with *CONTROL equal to NULL-HANDLE and *EVENT equal to AFTER-OPEN, to which the dialog responds by calling the inline subroutine *DLG$SUBR$CREATE$CONTROLS. This subroutine creates any dialog elements defined for the dialog, and then calls PROCESS GUI ACTION AFTER-CREATION to notify Natural that window creation is complete.

Depending on further application processing and user input, the dialog will repeatedly be executed with *CONTROL and *EVENT set appropriately. The dialog remains instantiated until it is explicitly unloaded as a result of the window being destroyed. This is the default reaction to the CLOSE event which in turn occurs as a result of either end-user interaction or the CLOSE DIALOG statement.

The same dialog module may be instantiated more than once, resulting in more than one dialog and its window and dialog elements being active. Each dialog has a unique numeric ID which is available as *DIALOG-ID during execution of that dialog, and as window_handle.CLIENT-DATA wherever that dialog's window handle is accessible (the window must be created with that attribute setting).

Syntax

General Syntax

This is the complete source of a dialog.

dialog_source_22D 
 :=: 
 /** DIALOG SOURCE 22D dialog_info_section_22D 
 [dialog_options_section_22D] 
 dialog_data_section_22D [user_subroutines_section_22D] 
 window_definition_22D control_definitions_22D 
 default_handler_section_22D 
 error_handler_section_22D before_any_section_22D 
 event_handlers_22D after_any_section_22D 
 END /** END-DIALOG-SOURCE

Subsections of the General Syntax

dialog_info_section_22D

dialog_info_section_22D 
 :=: 

The dialog's "info" section, consisting of a banner line, frame gallery information,

and an optional comment.

/*[ DEFINE DIALOG INFO

The following line is always generated by the dialog editor, but ignored on input.

 
/*D* Natural Dialog Description version_string / date 
 time

One or more following lines are present in dialogs generated using the frame gallery.

If present, they are preserved by (but cannot be changed in) the dialog editor.

[/*DF frame_gallery_info]... 

The empty comment line is generated by the dialog editor if no user comment is

present, but ignored on input.

[dialog_comment :=: {/** EMPTY DIALOG COMMENT | [user_code_line_protected_by_/**_prefix]...}] 
 /*] END-DIALOG-INFO 

dialog_options_section_22D

dialog_options_section_22D 
 :=: 

These option settings are only generated by the dialog editor if the "Save settings

with dialog" option is on (see Dialog Editor Options and Setting the Options in the Using Natural Studio documentation). When a dialog is being loaded and this section is present,

the option is turned on.

[/*[ DEFINE OPTION SETTINGS {/** SET option_name option_value}... 
 /*] END-OPTION-SETTINGS] 

dialog_data_section_22D

dialog_data_section_22D 
 :=:

The dialog's data section, consisting of a global, parameter, and local data area.

The sequence is fixed.

 DEFINE DATA gda_section_22D 
 pda_section_22D lda_section_22D 
 END-DEFINE 

Subsections of the dialog_data_section_22D

gda_section_22D

gda_section_22D 
 :=: 

The optional global data area specification. Note that it may reference blocks.

/*[ DEFINE GLOBAL DATA [GLOBAL USING gda_specification] /*] END-GLOBAL-DATA 
 

pda_section_22D

pda_section_22D 
 :=: 

The dialog's parameter data area must always contain the parent handle as the

first field.

/*[ DEFINE DIALOG PARAMETERS PARAMETER 01 #DLG$PARENT HANDLE OF 
 GUI BY VALUE user_data_section_22D 
 /*[ DEFINE USING [PARAMETER USING pda_name]... /*] END-USING /*] END-DIALOG-PARAMETERS 
 

lda_section_22D

lda_section_22D 
 :=: 

The dialog's local data area. The handle declarations for all dialog elements are

necessary if the dialog is to be compiled, but are ignored by the dialog editor

on input and re-generated from the actual dialog element definitions below.

/*[ DEFINE LOCAL DATA LOCAL /*[ DEFINE HANDLES {01 control_name 
 HANDLE OF control_class[<>]}... /*] END-HANDLES user_data_section_22D 
 /*[ DEFINE USING [LOCAL USING lda_name]... /*] END-USING /*] END-LOCAL-DATA 
 

user_subroutines_section_22D

user_subroutines_section_22D 
 :=: 

The list of user-defined subroutines. The enclosing pseudo-syntax is generated

only if there actually are subroutines.

/*[ DEFINE SUBROUTINES [DEFINE SUBROUTINE subroutine_name 
 user_code_section_22D END-SUBROUTINE]... 
 /*] END-SUBROUTINES 

window_definition_22D

window_definition_22D 
 :=: 

The window is defined within a standard subroutine (this must always be present).

DEFINE SUBROUTINE #DLG$ SUBR$CREATE$WINDOW /** DEFINE CONTROL window_name 
 non_array_control_definition_22D 
  END-SUBROUTINE /** END-CONTROL 

control_definitions_22D

control_definitions_22D 
 :=: 

All dialog elements are defined within one standard subroutine (this must

always be present). The sequence generated by the dialog editor is: menu bar,

tool bar, font controls, timers, any other dialog elements.

DEFINE SUBROUTINE #DLG$SUBR$CREATE$CONTROLS /** DEFINE DIALOG 
 ELEMENTS [control_definition :=: 

Each dialog element definition is enclosed in pseudo-comments.

/*[ 
 DEFINE CONTROL control_name[array_bounds] 

The following optional comment appears in the source code only.

[control_comment 
 :=: {user_code_line_protected_by_/**_prefix}...] 

The following code creates the dialog element.

{non_array_control_definition_22D 
 | array_control_definition_22D} 
 

List box controls and selection-box controls may have items lists defined as one

array of dialog elements. These follow the dialog element creation code.

[control_items :=: /* DEFINE ITEMS control_name_array_bounds 
 array_control_definition_22D 
 /*] END-ITEMS ] /*] END-CONTROL
]... 
 END-SUBROUTINE /** END-DIALOG-ELEMENTS 

default_handler_section_22D

default_handler_section_22D 
 :=: 

The DEFAULT event handler, specified as subroutine. For compilation, it must be

present, as this subroutine is called from various places.

DEFINE SUBROUTINE 
 #DLG$HANDLER$DEFAULT /** DEFINE EVENT DEFAULT user_code_section_22D 
  END-SUBROUTINE /** END-EVENT 

error_handler_section_22D

error_handler_section_22D 
 :=: 

The ERROR event handler, specified as ON ERROR section. Optional.

ON ERROR /** DEFINE 
 EVENT ERROR user_code_section_22D  
 END-ERROR /** END-EVENT 

before_any_section_22D

before_any_section_22D 
 :=: 

The BEFORE-ANY event handler, that is, the code which precedes the DECIDE

statements which evaluate *CONTROL and *EVENT.

/*[ DEFINE EVENT BEFORE-ANY user_code_section_22D 
 /*] END-EVENT 

event_handlers_22D

event_handlers_22D 
 :=: 

The DECIDE statements which evaluate first *CONTROL, then *EVENT,

activating the appropriate event handlers.

DECIDE 
 ON FIRST *CONTROL /** DEFINE ALL EVENTS {dialog_events :=: /*[ DEFINE 
 EVENTS FOR DIALOG VALUE NULL-HANDLE 

*CONTROL = NULL-HANDLE indicates an event associated either with the

window or with the dialog itself.

DECIDE ON FIRST *EVENT /*[ 
 DEFINE EVENT OPEN VALUE 'OPEN' 

The OPEN event handler starts with any BEFORE-OPEN user code and ends

with the window creation call.

user_code_section_22D 
 PERFORM #DLG$SUBR$CREATE$WINDOW /*] END-EVENT /*[ DEFINE EVENT AFTER-OPEN VALUE 
 'AFTER-OPEN' 

The AFTER-OPEN event occurs while the window creation call is being

processed, that is, it is a nested call of the dialog. It includes the creation of all

dialog elements and the assignment of those window attributes which use

dialog element handles (for example, the handle of the menu bar). User

code may follow.

PERFORM #DLG$SUBR$CREATE$CONTROLS [extra_window_attributes_22D] 
 PROCESS GUI ACTION AFTER-CREATION WITH window_name PROCESS GUI ACTION 
 RESET-ATTRIBUTES 

The user's after-open code follows.

user_code_section_22D 
 /*] END-EVENT /*[ DEFINE EVENT CLOSE 

The CLOSE event occurs either because the end user directly closes the

window, or because the parent window is closed, or as the result of a CLOSE

DIALOG statement.

VALUE 'CLOSE' 
 {dialog_close_handler_22D :=: user_code_section_22D} 
 

The following call "destroys" the window and unloads the dialog.

PROCESS GUI ACTION DELETE-WINDOW WITH window_name 
 

The following statement leaves the dialog, bypassing the AFTER-ANY

handler.

ESCAPE ROUTINE IMMEDIATE /*] END-EVENT 

The following dialog event handlers are optional and include any user-defined

events.

[event_handler_section_22D...] 
 NONE PERFORM #DLG$HANDLER$DEFAULT END-DECIDE /*] END-EVENTS 
} 

All event handlers for dialog elements defined in

*DLG$SUBR$CREATE$CONTROLS are listed below.

[control_events_section_22D...] 
 NONE PERFORM #DLG$HANDLER$DEFAULT END-DECIDE /** END-ALL-EVENTS 

All events that are not processed and have not been suppressed are handled in the

DEFAULT event handler. Any dialog elements created outside

DLG$SUBR$CREATE$CONTROLS are handled there.

after_any_section_22D

after_any_section_22D 
 :=: 

The AFTER-ANY event handler, that is, the code which follows the DECIDE

statements evaluating *CONTROL and *EVENT.

/*[ DEFINE EVENT AFTER-ANY user_code_section_22D 
 /*] END-EVENT 

Subordinate Syntax Sections

user_data_section_22D

user_data_section_22D 
 :=: 

A section with data declarations. The dialog editor generates a comment if no user

code is present. The user code layout is preserved, except that the whole section is

indented appropriately.

[frame_code_section_22D] 
 {/** EMPTY USER CODE SECTION | user_code_line_22D...} 
 [frame_code_section_22D] 

user_code_section_22D

user_code_section_22D 
 :=: 

A section with executable statements. The dialog editor generates a comment if

no user code is present. The user code layout is preserved, except that the whole

section is indented appropriately.

[frame_code_section_22D] 
 {;/** EMPTY USER CODE SECTION | user_code_line_22D...} 
 [frame_code_section_22D] 

frame_code_section_22D

frame_code_section_22D 
 :=: 

This protected section is code in a frame gallery dialog. Do not change this code.

/*[ DEFINE FRAME CODE [user_code_line_22D...] 
 /*] END-FRAME-CODE 

user_code_line_22D

user_code_line_22D 
 :=: 

A code line within an event section or subroutine. Indentation is preserved by the

dialog editor. However, a minimum indentation is enforced.

indented_code_line 

event_handler_section_22D

event_handler_section_22D 
 :=: 

A single event handler section, that is, the VALUE clause for the event in a DECIDE

statement for the relevant dialog element.

/*[ DEFINE EVENT event_name 
 VALUE 'event_name' user_code_section_22D 
  /*] END-EVENT 

control_events_section_22D

control_events_section_22D 
 :=: 

The collection of all event handlers for one dialog element, that is, a VALUE clause

for the dialog element's handle containing a DECIDE statement for *EVENT. If th

dialog element is an array, all elements are handled in this section.

/*[ 
 DEFINE EVENTS FOR control_name VALUE control_name[(*[,*)] DECIDE 
 ON FIRST *EVENT event_handler_section_22D... 
 NONE PERFORM #DLG$HANDLER$DEFAULT END-DECIDE /*] END-EVENTS 

non_array_control_definition_22D

non_array_control_definition_22D 
 :=: 

A non-array dialog element definition corresponds to the PROCESS GUI statement

action that creates the dialog element. As the WITH PARAMETERS ...

END-PARAMETERS clause is used, all attributes not mentioned have their default

values. The dialog editor does not generate such attributes.

The first and the second attributes must be HANDLE-VARIABLE and TYPE.

The dialog editor uses the predefined attribute value names defined

in the standard local data area NGULKEY1 if this data area has been included in

the dialog. If it is not included, the dialog cannot be compiled. Note that variable

references are allowed for only a subset of the attributes.

PROCESS GUI ACTION ADD WITH 
 PARAMETERS {attribute_name = {constant | variable_reference}<>}... 
 END-PARAMETERS [frame_code_line_22D...] /*] END-CONTROL 

array_control_definition_22D

array_control_definition_22D 
 :=: 

An array definition of a dialog element consists of one PROCESS GUI statement for

each array element. Only a subset of dialog elements may be defined as arrays (for

example, not the dialog window or list box controls). Instead of the WITH

PARAMETERS ... END-PARAMETERS clause, explicit attribute assignments and

the simple WITH clause are used, as array elements will share many equal but

non-default attribute values.

The dialog editor is quite restrictive with respect to dialog element arrays:

a maximum of two dimensions is allowed; elements cannot be placed individually;

only a subset of the attributes may vary between elements.

The dialog editor will, when scanning dialog element array definitions, take those

attribute values which may not vary from the first element's definition. Specifically,

all coordinate definitions but the first will be derived from the pseudo-attributes

H-SPACING, V-SPACING, and ARRANGE-IN-COLUMNS. (Note, however,

that not all dialog elements have coordinates.) All attributes not mentioned explicitly

have their default values; this is enforced by the initial PROCESS GUI ACTION

RESET-ALL.

PROCESS GUI ACTION RESET-ATTRIBUTES [spacing_info:=: 
 /** H-SPACING = horiz_spacing /** V-SPACING = vert_spacing /** 
 ARRANGE-IN-COLUMNS = {TRUE|FALSE}<>] ] { 

Creation of one array element. Numeric references to a message file string must

be handled in an explicit PROCESS GUI statement action for that string, as

direct assignment to a number would simply convert that number to a string.

[attribute_assignment:=:{ 
  control_name_and_index.attribute_name := attribute_value| 
 PROCESS GUI ACTION GET-MESSAGE-TEXT WITH number indexed_control_name 
 }<>]... PROCESS GUI ACTION ADD WITH parent_name type_name control_name_and_index 
 
}... 

extra_control_attributes_22D

extra_control_attributes_22D 
 :=: 

Some attributes cannot be defined meaningfully in the PROCESS GUI ACTION

ADD that creates the dialog element; an example is a non-modifiable selection-box

control's STRING, which must be one of the items' STRING values. This attribute

is therefore defined after all items have been added.

control_name_and_index.attribute_name 
 := attribute_value 

extra_window_attributes_22D

extra_window_attributes_22D 
 :=: 

Some attributes cannot be defined meaningfully in the PROCESS GUI ACTION

ADD that creates the dialog, for example, the default button can only

be defined after that button has been created.

window_name.attribute_name 
 := attribute_value