COMPOSE

#### Search Results

Search

# COMPOSE

This statement can only be used if the office system Con-nect and the text formatter Con-form are installed.

`COMPOSE`
[RESETTING-clause]
[MOVING-clause]
[ASSIGNING-clause]
[FORMATTING-clause]
[EXTRACTING-clause]

If you specify more than one clause, these clauses and their subclauses will be processed in the order shown above.

This document covers the following topics:

- COMPOSE Usage

- COMPOSE Syntax Description

- Formatting Process

- Dialog Mode Processing

- Input/Output Processing by Non-Natural Programs

- COMPOSE Examples

For an explanation of the symbols used in the syntax diagrams, see Syntax Symbols.

## COMPOSE Usage

The `COMPOSE` statement may be used to initiate text formatting by Con-form directly from a Natural program. Con-form is a text formatter which is automatically installed with Con-nect.

The text to be formatted can either be supplied using variables or it may be retrieved from a Con-nect text block (a document containing Con-form formatting instructions).

The contents of Natural variables can be passed to Con-form as variables for dynamic inclusion in the formatted text.

The values contained in a Con-form variable can also be returned to the Natural program from the text formatter.

When the Con-form instructions are completed (resulting in a formatted document), the output is passed to one of the following places:

- a Natural report,

- a document in the Con-nect system file,

- variables in the Natural program that executes the `COMPOSE` statement,

- a non-Natural program.

## COMPOSE Syntax Description

- RESETTING-clause

- MOVING-clause

- ASSIGNING-clause

- FORMATTING-clause

- EXTRACTING-clause

### RESETTING-clause

This clause may be used to delete information from the text format area of the Con-form buffer and to release memory from the Con-form buffer allocated by the `CSIZE` profile parameter in the Natural parameter module.

`RESETTING` |  | `DATAAREA` `TEXTAREA` `MACROAREA` `ALL` |

Syntax Element Description:

Syntax Element | Description
--- | ---
`DATAAREA` | Deletes all active text variables.
`TEXTAREA` | Deletes all text input data. Note For compatibility reasons, the keyword `TEXTAREA` refers to `DATAAREA` as used in the `MOVING` clause.
`MACROAREA` | Deletes all text macros.
`ALL` | Deletes all of the above.

See also Example 1 and Example 2.

### MOVING-clause

You can use this clause to move text lines to the text format area of the Con-form buffer, or directly to the formatter, and to retrieve formatted text output from the Con-form buffer.

It may be used to move one or more text values to the text format area (see Syntax 1). This area may be used as a source of input for formatting operations.

If the text formatter is currently waiting for input (see Dialog Mode Processing), the text will be passed directly to it without being stored in Con-form's buffer (see Syntax 1 and Syntax 2). The source input is terminated with the `LAST` option.

If the formatted text is currently waiting for output (see Dialog Mode Processing), Syntax 3 of the `MOVING` clause is used to pass control back from the Natural program to the formatter.

For description of the status variables, see FORMATTING-clause.

Depending on the status of the dialog mode processing, one of the following forms of the `MOVING` clause may be used:

#### Syntax 1 - Dialog Mode for Input

Syntax 1 of the `MOVING` clause is applicable when formatting has not begun or the formatter is in dialog mode for input and is waiting for input (`TERM` in the status variable "State").

`MOVING` [operand1] 37 [`TO DATAAREA`] [`LAST`]
[`STATUS` [`TO`] operand2 [operand3 [operand4 [operand5]]]]

#### Syntax 2 - Dialog Mode for Both Input and Output

Syntax 2 of the `MOVING` clause is applicable when the formatter is in dialog mode for both input and output, and is waiting for further input (status `TERM` in the status variable "State"). The formatter will not accept more than one line of input in this mode.

The execution context may change between succession of executed `COMPOSE` statements. Therefore, it is necessary to re-specify the output variables even when the formatter is waiting for input.

`MOVING` |  |  | operand1 [`TO DATAAREA`] `LAST` |  |  | [`OUTPUT`] `TO` `VARIABLES` operand6 20
[`STATUS` [`TO`] operand2 [operand3 [operand4 [operand5]]]]

#### Syntax 3 - Dialog Mode for Output

Syntax 3 of the `MOVING` clause is applicable when the formatter is in dialog mode for output (and possibly for input at the same time), and is passing output to the Natural program (status `STRG` in the status variable "State").

`MOVING` `OUTPUT` [`TO VARIABLES`] operand6 20
[`STATUS` [`TO`] operand2 [operand3 [operand4 [operand5]]]]

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` | C | S | A |  |  | A | N | P |  |  |  |  |  |  |  |  |  | yes | no
`operand2` |  | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | yes
`operand3` |  | S |  |  |  |  |  |  |  |  | B |  |  |  |  |  |  | yes | yes
`operand4` |  | S |  |  |  |  |  |  |  |  | B |  |  |  |  |  |  | yes | yes
`operand5` |  | S |  |  |  |  |  |  |  |  | B |  |  |  |  |  |  | yes | yes
`operand6` |  | S | A |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no

Syntax Element Description:

Syntax Element | Description
--- | ---
`operand1` | Contains the input (unformatted) text lines. Format/length: (An), where n is a maximum value of 253, (Nn) or (Pn), where n is a maximum value of 29.
`operand2` | Contains the status variable "State". Format/length: (A4)
`operand3` | Contains the status variable "Position" (page number). Format/length: (B4)
`operand4` | Contains the status variable "Position" (line number). Format/length: (B4)
`operand5` | Contains the status variable "Amount of output data" (number of lines). Format/length: (B4)
`operand6` | Contains the output (formatted) text lines. Format/length: (An), where n is a maximum value of 253.

### ASSIGNING-clause

You can use this clause to assign the values of Natural variables to Con-form text variables. These text variables may subsequently be referred to in formatting operations.

`ASSIGNING` [`TEXTVARIABLE`] {operand1=operand2}, 19

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand2` | C | S |  |  |  | A | N | P |  |  |  |  |  |  |  |  |  | yes | yes

Syntax Element Description:

Syntax Element | Description
--- | ---
`operand1` | `operand1` is the name of the Con-form text variable. The text variable must be specified in upper case. Format/length: (An), where n is a maximum value of 253.
`operand2` | `operand2` is the name of a given Natural variable. Format/length: (An), where n is a maximum value of 253, (Nn) or (Pn), where n is a maximum value of 29.

See also Example 3 and Example 4.

### FORMATTING-clause

This clause causes Con-form to produce formatted output. You can use it to create text in final form, that is, with correct line and page breaks, using input which can be a combination of text and Con-form instructions.

The formatting options are specified in one or more subclauses. If subclauses are omitted, Con-form will apply default formatting options.

The status variable is used in dialog mode.

`FORMATTING` |  | OUTPUT-subclause INPUT-subclause STATUS-subclause PROFILE-subclause MESSAGES-subclause ERRORS-subclause ENDING-subclause STARTING-subclause |  |

Syntax Element Description:

Syntax Element | Description
--- | ---
`OUTPUT-subclause` | The output medium. This can be a Natural report, a document in a Con-nect cabinet, one or more Natural variables (or an array of Natural variables), or a non-Natural program. See Output-subclause in the following section.
`INPUT-subclause` | The input medium. This can be a Con-nect document, the text format area of the Con-form buffer (see `DATAAREA` in the `MOVING` clause), the environment of the Natural program(s) executing the `COMPOSE` statement(s) (see the `MOVING` clause), a non-Natural program, or a mixture of these four possibilities.
`STATUS-subclause` | The status of the formatting operation. The formatting operation may involve multiple executions of a `COMPOSE` statement (in dialog mode processing). For example, the input is fed into the text format area by a Natural program, and the output is passed from the text format area into the environment of a Natural program (that is, one or more Natural variables). Therefore it is necessary to inform the Natural program of the formatting status. The following variables are passed to the Natural program during the formatting process:
State | `TERM` when the dialog mode is ready for input.
`STRG` when the dialog mode is ready for output.
`END` if the formatting process was completed successfully.
`ENDX` if the formatting process was completed unsuccessfully.
Position | Page and line number of the document that is being formatted. The page and line numbers are kept separately in two variables (page position and line position).
Amount of Output Data | The number of lines of formatted output which are being passed to the Natural program. The formatter uses this number as the pointer to the next output variable to be filled. The value is incremented by `1` before the output line is issued. If the current value is out of range, the value is set to `1`.
`PROFILE-subclause` | Text block to be processed before input is processed. See PROFILE-subclause in the following section.
`MESSAGES-subclause` | Controls the output of warning messages and statistical information and error processing. See MESSAGES-subclause and ERRORS-subclause in the following section.
`ERRORS-subclause`
`ENDING-subclause` | Defines the page where output of formatted text is to stop. See ENDING-subclause in the following section.
`STARTING-subclause` | Defines the page where output of formatted text is to start. See STARTING-subclause in the following section.

#### OUTPUT-subclause

This subclause enables you to direct Con-form's formatted text output to a specific destination.

If this subclause is omitted, Natural's main printer will be used as the default output device.

`OUTPUT` |  | (rep) `SUPPRESSED` `CALLING` operand1 `TO VARIABLES` [`CONTROL` operand2 operand3] operand4 20 DOCUMENT-option |

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand2` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand3` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand4` |  | S | A |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no

Syntax Element Description:

Syntax Element | Description
--- | ---
`(rep)` | If the output is directed to a printer (that is, the report number is not 0 and a Con-nect printer profile has been loaded (by the Con-nect API subprogram `Z-DRIVER`), the settings of that profile will be used to control the text highlighting options of the formatted output text. If a printer profile is active and the logical form feed controls were not specified, page ejects will be inserted by use of the appropriate internal Natural nucleus functions. Any other highlighting text option which is not reflected in the currently active Con-nect printer profile will be ignored. Note Executions of the `COMPOSE RESETTING ALL` or `COMPOSE FORMATTING` statement with non-report output destination will unload a printer profile from the text format area. If output is directed to Report 0 or if a printer profile is not active, Con-nect will pass the responsibility of the output handling to the Natural nucleus routines. In this case, only the highlighting text options boldface, underline and italics will be recognized. Note A report which is referred to in a `DEFINE PRINTER (n) OUTPUT 'CONNECT'` statement must not be specified as output destination in a `COMPOSE FORMATTING` statement.
`SUPPRESSED` | This option causes the output to be suppressed.
`CALLING operand1` | `operand1` is the name of the called program. Format/length: (An), where n is a maximum value of 8. See the section Input/Output Processing by Non-Natural Programs.
`TO VARIABLES [CONTROL operand2 operand3] operand4` | Generally, the formatted text will be passed in final format to an array of Natural variables. Each line fills one variable (if necessary, the line may be truncated to fit into the variables). Text highlighting options will be ignored, with the exception of the `CONTROL` variables specified, which will be used to emphasize sections of the text (that is, boldface or underscore). If the `CONTROL` variables `I` and `N` are specified, the formatted text will be produced in an intermediate format (that is, with interspersed logical control sequences). `operand2` is the starting character. Format/length: (A1). `operand3` is the ending character. Format/length: (A1). Example using angle brackets as starting and ending characters:
    <ABC...XYZ>
`operand4` is the output field. Format/length: (An), where n is a maximum value of 253. For further information, see the section Dialog Mode Processing, and in particular the subsection Dialog Mode for Output.
`DOCUMENT-option` | See DOCUMENT-option below.

#### DOCUMENT-option

The `DOCUMENT` option of the `OUTPUT` subclause enables you to direct Con-form's formatted text to a Con-nect cabinet in final (Txt) or intermediate (Int) format. The document text of Int format cannot be modified.

`DOCUMENT` |  | `INTO` |  |  | `FINAL` `INTERMEDIATE` |  |  | [`CABINET`] operand1 [`PASSW=`operand2] |
| [`GIVING`] |  | operand3 [operand4] operand4 [operand3] |  |

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand2` |  | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand3` |  | S |  |  |  |  |  |  |  |  | B |  |  |  |  |  |  | yes | yes
`operand4` |  | S |  |  |  |  |  |  |  |  | B |  |  |  |  |  |  | yes | yes

Syntax Element Description:

Syntax Element | Description
--- | ---
`INTO FINAL | INTERMEDIATE CABINET` | If the keyword `FINAL` is specified, the document will be created in final form text. In this case, specific text highlighting options such as boldface or italics will be ignored. If the keyword `INTERMEDIATE` is specified, the document will be added to the folder `COMPOSE` without a document name. The subject line will be filled with the name of the program executing the `COMPOSE FORMATTING` statement along with the date and time of execution.
`CABINET operand1` | `operand1` may be used to identify a specific cabinet. Format/length: (An), where n is a maximum value of 8. If `operand1` is not specified, the document will be added to the current user's cabinet (that is, to the cabinet whose ID is identical to the currently active Natural user ID). Con-form enforces adherence to Con-nect access restrictions and only accepts cabinet IDs which have been defined to Con-nect. Note Cabinet IDs must be specified in upper case.
`PASSW=operand2` | A password must be specified if storing the document in a cabinet to which the currently assumed user ID has no access. Format/length: (An), where n is a maximum value of 8.
`operand3` | `operand3` is used by the formatter to pass a unique key from the document back to the Natural program. It is supported for compatibility reasons only. Format/length: (B10)
`operand4` | `operand4` is used by the formatter to pass an ISN, which points to the formatted output document, back to the Natural program. This ISN can be useful when referencing the document in successive calls to Con-nect APIs. Format/length: (B4)

#### INPUT-subclause

This subclause may be used to specify the sources which will supply input for the text formatter.

Note
If this subclause is omitted, the `DATAAREA` (text format area of the Con-form buffer) will be processed by default.

`INPUT` |  | `DATAAREA` |  | `FROM` |  | `EXIT` operand2 `CABINET` operand2 [`PASSW=`operand3] | 9 |  |
operand1 `FROM` |  | `EXIT` operand2 `CABINET` operand2 [`PASSW=`operand3] | 10 |

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand2` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand3` |  | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no

Syntax Element Description:

Syntax Element | Description
--- | ---
`DATAAREA` | The input may be taken from Con-form's data area (or a mixture of text from the text format area and from the dialog mode is also possible) which must be filled by one or more `MOVING` operations; see the `MOVING` clause.
`operand1` | Alternatively, the input may be taken from a text block. The name of the text block is specified by `operand1`. Note Text block IDs must be specified in upper case. Format/length: (An), where n is a maximum value of 253. The text block may be contained in a Con-nect cabinet, or it may be supplied by a non-Natural program. It will be invoked using the same conventions which apply to the `CALL` statement. A hierarchy of Con-nect cabinets or non-Natural programs may be specified, each of which will be scanned in turn for the text block specified in `operand1`.
`CABINET operand2` | The input (a text block specified by `operand1`) might be taken from a specific Con-nect cabinet. `operand2` is the name of the Con-nect cabinet. Note Cabinet IDs must be specified in upper case. Format/length: (An), where n is a maximum value of 8.
`EXIT operand2` | `operand2` is the name of the exit. Format/length: (An), where n is a maximum value of 8.
`PASSW=operand3` | A password must be specified if the document is stored in a cabinet to which the currently assumed user ID has no access. Format/length: (An), where n is a maximum value of 8. Con-form enforces adherence to Con-nect access restrictions and only accepts cabinet IDs which have been defined to Con-nect.

See also Example 4.

#### STATUS-subclause

The `STATUS` subclause used in the `FORMATTING` clause corresponds to the `STATUS` subclause of the `MOVING` clause. It should be used to make sure that the formatting process is always in the appropriate status for a given processing step.

`STATUS` operand1 [operand2 [operand3 [operand4]]]

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` |  | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand2` |  | S |  |  |  |  |  |  |  |  | B |  |  |  |  |  |  | yes | no
`operand3` |  | S |  |  |  |  |  |  |  |  | B |  |  |  |  |  |  | yes | no
`operand4` |  | S |  |  |  |  |  |  |  |  | B |  |  |  |  |  |  | yes | no

Syntax Element Description:

Syntax Element | Description
--- | ---
`operand1` | Contains the status variable "State" (status of formatting process). Format/length: (A4)
`operand2` | Contains the status variable "Position" (page number). Format/length: (B4)
`operand3` | Contains the status variable "Position" (line number). Format/length: (B4)
`operand4` | Contains the status variable "Amount of Output Data" (number of lines). Format/length: (B4)

#### PROFILE-subclause

This subclause causes the content of the specified text block to be processed prior to any input which has been specified with the `INPUT` subclause (by default, a text block will not be processed as a profile).

`PROFILE` operand1

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no

Syntax Element Description:

Syntax Element | Description
--- | ---
`operand1` | `operand1` is the name of the text block (for example, `FPROFILE` - formatting profile). Format/length: (An), where n is a maximum value of 32.

#### MESSAGES-subclause

When this subclause is specified, warning messages and statistical information are to be displayed upon completion of formatting or the error may be simply suppressed (ignored).

`MESSAGES` |  | [`LISTED`] [`ON`] (rep) `SUPPRESSED` |

Syntax Element Description:

Syntax Element | Description
--- | ---
(rep) | The notation `(rep)` specifies the report for which the subclause is applicable. A value in the range `0 - 31` or a logical name which has been assigned using the `DEFINE PRINTER` statement may be specified. For information on how to control the format of an output report created with Natural, see Report Format and Control in the Programming Guide.
`SUPPRESSED` | When specified, this keyword indicates that no messages are to be displayed and errors are to be ignored.

#### ERRORS-subclause

You can use the `ERRORS` subclause to specify the actions to be performed when a formatting error occurs. The error may be processed by Natural's standard error-processing routine, or it may be listed on a specified Natural report.

`ERRORS` |  | [`LISTED`] [`ON`] (rep) `INTERCEPTED` |

Syntax Element Description:

Syntax Element | Description
--- | ---
`(rep)` | The notation `(rep)` specifies the report for which the subclause is applicable. A value in the range `0 - 31` or a logical name which has been assigned using the `DEFINE PRINTER` statement may be specified. For information on how to control the format of an output report created with Natural, see Report Format and Control in the Programming Guide.
`INTERCEPTED` | When specified, this keyword indicates that the error is to be processed by Natural's standard error-processing routine.

Note
Errors and messages are mutually exclusive. Some errors may cause the standard Natural error-process routine to be invoked, even if a different option was specified. Errors or messages must not be directed to a report which is directed to the Con-nect system by a `DEFINE PRINTER (n) OUTPUT 'CONNECT'` statement.

#### ENDING-subclause

This subclause causes output of formatted text to be suppressed after a specific page number. Alternatively, it limits the amount of formatted output to a specified number of pages.

`ENDING` |  | [`AT`] [`PAGE`] operand1 `AFTER` operand1 [`PAGES`] |

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` | C | S |  |  |  |  | N | P |  |  |  |  |  |  |  |  |  | yes | no

Syntax Element Description:

Syntax Element | Description
--- | ---
`[AT] [PAGE] operand1` | Causes output of formatted text to be suppressed following a page with a number specified in `operand1`. Format/length: (Nn) or (Pn), where n is a maximum value of 5.
`AFTER operand1 [PAGES]` | Limits the amount of formatted output to a number of pages as specified with `operand1`.

#### STARTING-subclause

This subclause causes output of formatted text to be suppressed until the page with the specified number (`operand1`) is reached.

`STARTING` [`FROM`] [`PAGE`] operand1

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` | C | S |  |  |  |  | N | P |  |  |  |  |  |  |  |  |  | yes | no

Syntax Element Description:

Syntax Element | Description
--- | ---
`operand1` | The output of formatted text to be suppressed until the page with the number specified in `operand1` is reached. Format/length: (Nn) or (Pn), where n is a maximum value of 5.

### EXTRACTING-clause

You can use this clause to assign the values of Con-form text variables to Natural variables. The current text variable settings may be the result of previous formatting operations.

`EXTRACTING` [`TEXTVARIABLE`] {operand1=operand2}, 19

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` |  | S |  |  |  | A | N | P |  |  |  |  |  |  |  |  |  | yes | yes
`operand2` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | no

Syntax Element Description:

Syntax Element | Description
--- | ---
`operand1` | `operand1` is the name of a given Natural variable. Format/length: (An), where n is a maximum value of 253, (N) or (Pn), where n is a maximum value of 29.
`operand2` | `operand2` is the name of a Con-form text variable. It must be specified in upper case. Format/length: (An), where n is a maximum value of 253.

See also Example 6.

## Formatting Process

The formatting process begins when the `FORMATTING` clause of the `COMPOSE` statement is executed (even if text input via a `MOVING` clause is intended, but no such input has been provided yet). While the formatting process is active, the text input resulting from the execution of the `COMPOSE MOVING` statement is fed directly for formatting (and cannot be re-used in a later formatting process). If the formatting process is inactive, the text input is stored intermediately in the text format area of the Con-form buffer. Thus the input can be re-used for multiple formatting processes.

Since the Con-form buffer is not cleared at the end of the Natural program, the respective `COMPOSE` statements need not be executed within one Natural program; they can be issued in several successively invoked programs.

The execution of a `RESETTING` or `FORMATTING` clause, or a serious formatting error, causes the termination of an ongoing formatting pass.

End-of-input is specified by the `LAST` subclause of the `MOVING` clause.

When a Con-nect document is specified as the source of input, end-of-input is assumed when the end of that document is reached.

Note
It is recommended to use the `STATUS` subclause of the `FORMATTING` or `MOVING` clause to make sure that the formatting process is always in the appropriate status for a given processing step.

## Dialog Mode Processing

Dialog mode processing is the set of interactions which are performed between a user program and the formatter while formatting input and producing output.

Dialog mode allows a user program to supply raw text as input to the formatter at any level of the input hierarchy. It also accepts formatted output directly in the current program environment.

The dialog is achieved by subdividing the formatting process into a series of steps, each of which is separately invoked by a `COMPOSE` statement.

- Dialog Mode for Input

- Dialog Mode for Output

- Dialog Mode for Input and Output

- Execution of COMPOSE Statements in Dialog Mode

### Dialog Mode for Input

Dialog mode for input is activated if the source of the input text is `DATAAREA` (text format area), or if the Con-form instruction `.TE ON` for terminal input is encountered, and the text format area does not contain any more text to be processed. Dialog mode for input is signaled by the value `TERM` in the status variable "State".

The user program should respond by supplying the required input by invoking the `MOVING` function in a subsequently-processed `COMPOSE` statement. The user program can terminate terminal input by specifying the `LAST` option of the `MOVING` clause (or `.TE OFF` if terminal input was invoked by `.TE ON`) as text through the `MOVING` function. The formatter will signal the end of the formatting process with `END`, or `ENDX` in the case of an error, in the status variable "State".

See also Example 7.

### Dialog Mode for Output

Dialog mode for output is activated if the destination of the output is `TO VARIABLES`. The formatter passes control back to the Natural program environment as soon as the supplied Natural variables are filled or a page break is reached (whichever occurs first). Dialog mode for output is signaled with `STRG` in the status variable "State".

The user program should respond by taking the formatted output just placed into the Natural variables and designate another set of Natural variables as the output destination in a subsequently processed `COMPOSE MOVING` statement. The end of the formatting process is indicated with `END` (or `ENDX` in the case of an error) in the status variable "State".

Note
When dialog mode is used (see the `INPUT` and `OUTPUT` subclauses), the formatting operation is usually spread across several executions of a `COMPOSE` statement.

### Dialog Mode for Input and Output

Dialog mode can be activated for combined input and output processing. Therefore, when the formatter requests for further input (indicated in the status variable "State" by `TERM`) or when the formatter provides output (indicated by `STRG`), the Natural program must take the appropriate action.

When dialog mode is entered for combined input and output processing, only one line of input is accepted by the formatter at a time. In the case of input mode only, multiple lines are accepted at one time.

### Execution of COMPOSE Statements in Dialog Mode

While it has been pointed out that dialog mode is entered via a `COMPOSE FORMATTING` statement which encompasses a series of `COMPOSE MOVING` executions, please note the following:

- `COMPOSE ASSIGNING` and `COMPOSE EXTRACTING` statements are valid while dialog mode is active.

- `COMPOSE RESETTING` and `COMPOSE FORMATTING` will force the immediate termination of all formatting.

## Input/Output Processing by Non-Natural Programs

Depending on the parameters specified with the `FORMATTING` clause, input and output may be processed by non-Natural programs. Such programs are invoked by the same mechanism that is used within the Natural `CALL` statement.

The `COMPOSE` statement exchanges parameters with these programs using the standard linkage conventions (dynamic loading is not possible in a CICS environment).

Note
Input/output processing by non-Natural programs is only possible on z/OS; on other platforms, the appropriate parts of the `COMPOSE` statement are ignored.

Depending on the status of the formatting process, two or three parameters are passed between the formatter and the non-Natural programs:

Parameter 1 (format/length A1) | Function code is passed from the formatter to non-Natural programs. Possible values:
`I` | Initiate (input, output).
`O` | Open document (input).
`R` | Read one line of document (input).
`W` | Write one line of output (output).
`C` | Close document (input).
`T` | Terminate (input, output).
Parameter 2 (format/length B1) | Response code is passed from non-Natural programs to the formatter. Possible values:
`X'00'` | Function successfully completed.
`X'01'` | In response to function `O`: document could not be found.
In response to function `R`: end of document was reached.
`X'FF'` | Function not completed.
Parameter 3 (format A1/256) | In the case of the functions `O` and `W`, these parameters are passed from the formatter to non-Natural programs. However, the parameters from the function `R` are passed from non-Natural programs to the formatter.
Bytes 1 - 2 | Signify the length `n` of this parameter.
Bytes 3 - 4 | Empty.
Bytes 5 - n | Function `O`: Document name.
Function `R`: Line read by the non-Natural program.
Function `W`: Line of output from the formatter.
Output is preceded by `N` if a form feed is required, otherwise by `1`. Specific options for highlighting text such as boldface and italics are ignored if the output is passed to a non-Natural program.

## COMPOSE Examples

- Example 1

- Example 2

- Example 3

- Example 4

- Example 5

- Example 6

- Example 7

### Example 1

The following `COMPOSE` statement results in a formatted output of the text block `TEXT` within the Con-nect cabinet `TLIB` which is produced on Report 1. Errors and statistical messages are displayed on Report 0 (the default printer).

    COMPOSE RESETTING ALL
            FORMATTING INPUT 'TEXT' FROM CABINET 'TLIB'
            OUTPUT (1)
            MESSAGES LISTED ON (0)

### Example 2

The following `COMPOSE` statements result in a formatted output of text on Report 0 (default printer).

    COMPOSE RESETTING ALL
    COMPOSE MOVING '.FI ON' 'This is an example'
    COMPOSE MOVING 'for use of Con-form from'
                   'within Natural applications' LAST
    COMPOSE FORMATTING

### Example 3

The following `COMPOSE` statement results in the assignment of values to Con-form text variables `&VAR1` and `&VAR2` in a Con-nect procedure.

    COMPOSE ASSIGNING 'VAR1' = 'Text1', 'VAR2' = 540

### Example 4

Text block `XYZ` in cabinet `XYLIB`:

    .FI ON
    Dear Mr &name.,
    .IL
    I am pleased to invite you to a presentation of our new product &prod..

Natural program:

    ...
    INPUT #NAME (A32) #PROD (A32)
    COMPOSE ASSIGNING 'NAME' = #NAME, 'PROD' = #PROD
            FORMATTING INPUT 'XYZ' FROM CABINET 'XYLIB'
            OUTPUT (1) MESSAGES SUPPRESSED
    ...

Input map produced by program:

    #NAME Davenport
    #PROD NaturalONE

Resulting output:

    Dear Mr Davenport,

    I am pleased to invite you to a presentation of our new product NaturalONE.

### Example 5

This is an example of formatting in dialog mode with combined input/output handling. The example program initiates the line-oriented formatting mode of Con-form, passes some instructions/variables to Con-form, and performs a subroutine which displays status information and formatted output lines on the screen.

    DEFINE DATA LOCAL
    01 #LINES_PER_PERFORM(P5)   /* counts repeat loops per PERFORM CNF_OUT
    01 #TRACE(A1) IINT<'N'>     /* if 'Y' displays additional trace info
    01 #OUT_FORM(A1) INIT<'F'>  /* output format
    01 #START_PAGE (P3) INIT<1> /* beginning of display
    01 #CNTR (P5)               /* Loop counter
    01 #STATI                   /* Status information
     02 #STATUS   (A4)          /* can be STRG TERM END or ENDX
     02 #PAGE     (B4)          /* current page number
     02 #LINE     (B4)          /* current line number on page (not .tt/.bt)
     02 #NO_LINES (B4)          /* number of lines returned
     02 REDEFINE #NO_LINES
      03 #NO_LINES_I (I4)
    01 #OUTPUT(A30/4)           /* output of formatted line
    01 #INDEX (P3)              /* index as pointer to output line
    END-DEFINE
    *
    SET KEY ALL
    SET CONTROL 'M9'
    INPUT
       008/008 'Demonstration of formatted output to variable'(I)
       /   08X 'Enter page to start display    :' #START_PAGE(AD=MIL)
       /   08X 'Display additional trace data ?:' #TRACE(AD=MIT)
       /   08X 'Please select the output format:' #OUT_FORM(AD=MIT)
               '(F=Final without BP/US-marks'
       /   44X 'M=Final with BP/US marks "<>"'
       /   44X 'I=Intermediate)'
       /   50X 'PF3=Exit'(I)
    *
    IF *PF-KEY EQ 'PF3'
       SET CONTROL 'MB'
       STOP
    END-IF
    *
    IF NOT (#OUT_FORM EQ 'F' OR EQ 'M' OR EQ 'I')
       REINPUT ' Please enter valid code!' MARK *#OUT_FORM ALARM
    END-IF
    *
    WRITE TITLE LEFT
         'Stat * Page     * Line     * No.Lines >> Formatted Output'(I)
       / '-'(79)(I)
    *
    SET CONTROL 'MB'
    COMPOSE RESETTING ALL /* clear all text format area of Con-form buffer
    RESET #NO_LINES
    *
    * start line-oriented formatting-mode here
    * starting from 0
    DECIDE ON FIRST VALUE OF #OUT_FORM
       VALUE 'F'
          COMPOSE FORMATTING
               OUTPUT TO VARIABLES #OUTPUT (1:4)      /* to Output
               STATUS #STATUS #PAGE #LINE #NO_LINES   /* get Status
       VALUE 'M'
          COMPOSE FORMATTING
               OUTPUT TO VARIABLES CONTROL '<' '>'
                                   #OUTPUT (1:4)      /* to output
               STATUS #STATUS #PAGE #LINE #NO_LINES   /* get Status
       VALUE 'I'
          COMPOSE FORMATTING
               OUTPUT TO VARIABLES CONTROL 'I' 'N'
                                   #OUTPUT (1:4)      /* to output
               STATUS #STATUS #PAGE #LINE #NO_LINES   /* get Status
       NONE
          STOP
    END-DECIDE
    *
    RESET #NO_LINES
    *
    * Put some commands to Con-form to see something
    *
    COMPOSE MOVING
         '.pl 16;.hs 2;.tt 1Formatting in Variable//;.tt 2//' /* Cmd
         OUTPUT TO VARIABLES #OUTPUT (1:4)           /* to Output
         STATUS #STATUS #PAGE #LINE #NO_LINES        /* get Status
    *
    COMPOSE MOVING
         '.fs 1;.bt Page End #//;.fi on;.tb *=15' /* Commands
         OUTPUT TO VARIABLES #OUTPUT (1:4)           /* to Output
         STATUS #STATUS #PAGE #LINE #NO_LINES        /* get Status
    *
    *
    * loop 40-times, send commands to con-form and display output
    *
    COMPOSE ASSIGNING 'Value' = '1-20' /* Assign value to variable &Value
    *
    FOR #CNTR 1 40                      /* Loop some time
       IF #STATUS NE 'TERM' /* no wait-for-input => error!!!!
          IF #STATUS EQ 'STRG'
             IGNORE
          ELSE
             WRITE 'Unexpected Status-code' #STATUS(AD=OI) 'found!'
                 / 'Execution has stopped....'
             STOP
          END-IF
       END-IF
    *
       IF #CNTR EQ 21
          COMPOSE ASSIGNING 'Value' = '21-40' /* Assign a variable-value
       END-IF
       COMPOSE ASSIGNING 'CNTR' = #CNTR /* Again assignment
       COMPOSE MOVING
            '.BP;&Value *Pass &CNTR;.BR'      /* Commands
            OUTPUT TO VARIABLES #OUTPUT (1:4)     /* to output
            STATUS #STATUS #PAGE #LINE #NO_LINES  /* get status
       PERFORM CNF-OUT                            /* show result
    END-FOR
    COMPOSE MOVING
         LAST                                  /* End of processing
         OUTPUT TO VARIABLES #OUTPUT (1:4)     /* to output
         STATUS #STATUS #PAGE #LINE #NO_LINES  /* get status
    *
    IF #TRACE EQ 'Y'
       WRITE 'End of processing...'(I)
    END-IF
    *
    * Subroutines
    *
    PERFORM CNF-OUT
    *
    * Subroutine to display any waiting output from Con-form
    *
    DEFINE SUBROUTINE CNF-OUT
       RESET #LINES_PER_PERFORM
       REPEAT UNTIL #STATUS EQ 'TERM' /* TERM = input waiting
          PERFORM BREAK               /* do some break processing
          AT BREAK OF #PAGE
             IF #PAGE GT #START_PAGE
                WRITE '-'(79)(I)
             END-IF
             IF #TRACE EQ 'Y'
                WRITE 'End of this page...'(I)
             END-IF
             NEWPAGE
          END-BREAK
          IF #PAGE GE #START_PAGE     /* show line of output
             IF #NO_LINES_I GT 0
                FOR #INDEX 1 #NO_LINES_I
                   ADD 1 TO #LINES_PER_PERFORM /* count loops
                   WRITE NOTIT NOHDR #STATUS '*' #PAGE '*' #LINE
                                             '*' #NO_LINES
                                             '>>' #OUTPUT (#INDEX)
                END-FOR
             END-IF
          END-IF
          IF #STATUS NE 'STRG'         /* if no wait on output
             ESCAPE BOTTOM
          END-IF
          RESET #NO_LINES
          COMPOSE MOVING
               OUTPUT TO VARIABLES #OUTPUT (1:4)    /* get output
               STATUS #STATUS #PAGE #LINE #NO_LINES /* Status
       END-REPEAT
    *
       IF #TRACE EQ 'Y'
        WRITE 'Count of lines per PERFORM was'(I) #LINES_PER_PERFORM(AD=OI)
       END-IF
    *
     END-SUBROUTINE
     SET CONTROL 'MB'
    END

### Example 6

Text block `'ABC'` in cabinet `'ZLIB'`:

    .op das=6
    .CV c=(&A+&B+&D)*&A/12345678901234567.89

Natural Program:

    DEFINE DATA LOCAL
     . . .
    01 NA       (P14.1) INIT <-12345678.1>
    01 NB       (N15.1) INIT <1234567890.1>
    01 ND       (P15.1) INIT <1122334455.1>
    01 NC       (N03.6)
    01 NCOMP    (N03.6)
    . . .
    END-DEFINE
    COMPOSE RESETTING ALL
    COMPOSE ASSIGNING 'A'=NA,'B'=NB,'D'=ND
    COMPOSE FORMATTING INPUT 'ABC' FROM CABINET 'ZLIB'
    COMPOSE EXTRACTING NC='C'
    COMPUTE ROUNDED NCOMP=(NA+NB+ND) * NA /12345678901234567.89
    WRITE (0) 'CONFORM C =' NC / 'NATURAL C =' NCOMP
    END

Resulting Output:

    CONFORM C =   -2.344557
    NATURAL C =   -2.344557

### Example 7

The following is an example of using the Con-form instruction `.TE ON/OFF` in dialog mode for input. A Natural program calls the Con-form document `LETTER` containing this instruction from cabinet `XYLIB`.

Natural program:

Note
This simplified Natural program is intended for demonstration purposes only; for example, the required fields `SALUTATION`, `LASTNAME`, `STREET`, `CITY` are not verified.

    DEFINE DATA LOCAL
    01 #ENTER (A15) INIT <'Special offer:'>
    01 SLINE  (A15) INIT <'.SL 1'>
    01 #TEXT   (A60/1:4)
    01 SALUTATION (A30)
    01 LASTNAME   (A30)
    01 STREET     (A30)
    01 CITY       (A30)
    01 #STATUS (A4)
    01 #PAGE   (B4)
    01 #LINE   (B4)
    01 #NUMBER (B4)
    END-DEFINE
    COMPOSE RESETTING ALL
    INPUT 25X 'Advertising letter'
            /  '-' (75)
            /  'Salutation: ' SALUTATION (AD='_')
            /  'Lastname  : ' LASTNAME (AD='_')
            /  'Street    : ' STREET (AD='_')
            /  'City      : ' CITY (AD='_')
            /  '-' (75)
           //  '-' #ENTER (AD=OI)
            /  '-' #TEXT(1) (AD='_')
            /  '-' #TEXT(2) (AD='_')
            /  '-' #TEXT(3) (AD='_')
            /  '-' #TEXT(4) (AD='_')
    COMPOSE ASSIGNING   'SALUT' = SALUTATION,
                        'NAME'  = LASTNAME,
                        'STREET'= STREET,
                        'TOWN'  = CITY
    COMPOSE FORMATTING INPUT 'LETTER' FROM CABINET 'XYLIB   '
    DECIDE FOR FIRST CONDITION
      WHEN #TEXT(4) NE ' '
           COMPOSE MOVING SLINE #TEXT(1) #TEXT(2) #TEXT(3) #TEXT(4)
                   '.TE OFF' STATUS #STATUS #PAGE  #LINE  #NUMBER
      WHEN #TEXT(3) NE ' '
           COMPOSE MOVING SLINE #TEXT(1) #TEXT(2) #TEXT(3)
                   '.TE OFF' STATUS #STATUS #PAGE  #LINE  #NUMBER
      WHEN #TEXT(2) NE ' '
           COMPOSE MOVING SLINE #TEXT(1) #TEXT(2)
                   '.TE OFF' STATUS #STATUS #PAGE  #LINE  #NUMBER
      WHEN #TEXT(1) NE ' '
           COMPOSE MOVING SLINE #TEXT(1)
                   '.TE OFF' STATUS #STATUS #PAGE  #LINE  #NUMBER
      WHEN NONE
           COMPOSE MOVING
                   '.TE OFF' STATUS #STATUS #PAGE  #LINE  #NUMBER
    END-DECIDE
    END

Con-form document `LETTER`:

    .PL 22;.LM 0;.RM 60;.HS 0;.HM 0;.FM 0;.FS 0
    &salut &name
    &street
    &town
    .SL 2
    Dear &salut &name.,
    .SL
    .LM 0;.JU OFF;.FI ON
    Your subscription with MAGNIFICENT WILDLIFE magazine will soon expire.
    If you act now and renew your subscription for one full year, you will
    receive a 40% discount - a savings of $25.00 off the newsstand price!$
    .TE ON
    .SL 2
    Sincerely,$
    J. Baker$
    Vice President of Sales

Screen prior to input:

                             Advertising letter
    ---------------------------------------------------------------------------
    Salutation:  ______________________________
    Lastname  :  ______________________________
    Street    :  ______________________________
    City      :  ______________________________
    ---------------------------------------------------------------------------

    Special offer:
    ____________________________________________________________
    ____________________________________________________________
    ____________________________________________________________
    ____________________________________________________________

Screen after input:

                             Advertising letter
    ---------------------------------------------------------------------------
    Salutation:  Mister________________________
    Lastname  :  Poe___________________________
    Street    :  203 North Amity Street________
    City      :  Baltimore, Maryland___________
    ---------------------------------------------------------------------------

    Special offer:
    Take $500 off a trip to one of the world's premier wildlife-
    viewing destinations through our travel partner.____________
    ____________________________________________________________
    ____________________________________________________________

Resulting letter after formatting is complete:

    MISTER POE
    203 NORTH AMITY STREET
    BALTIMORE, MARYLAND

    Dear MISTER POE,

    Your subscription with MAGNIFICENT WILDLIFE magazine will
    soon expire. If you act now and renew your subscription for
    one full year, you will receive a 40% discount - a savings
    of $25.00 off the newsstand price!

    TAKE $500 OFF A TRIP TO ONE OF THE WORLD'S PREMIER WILDLIFE-
    VIEWING DESTINATIONS THROUGH OUR TRAVEL PARTNER.

    Sincerely,
    J. Baker
    Vice President of Sales

### On this page

- COMPOSE Usage
- COMPOSE Syntax Description
- Formatting Process
- Dialog Mode Processing
- Input/Output Processing by Non-Natural Programs
- COMPOSE Examples