COMPOSE

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

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:

• Function

• Syntax Description

• Formatting Process

• Dialog Mode Processing

• Input/Output Processing by Non-Natural Programs

• Examples

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

Function

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.

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.

Syntax Element Description:

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:

Syntax Element Description:

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:

Syntax Element Description:

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.

Syntax Element Description:

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.

Operand Definition Table:

Syntax Element Description:

<ABC...XYZ>

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:

Syntax Element Description:

INPUT-subclause

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

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

Operand Definition Table:

Syntax Element Description:

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.

Operand Definition Table:

Syntax Element Description:

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).

Operand Definition Table:

Syntax Element Description:

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).

Syntax Element Description:

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.

Syntax Element Description:

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.

Operand Definition Table:

Syntax Element Description:

STARTING-subclause

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

Operand Definition Table:

Syntax Element Description:

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:

Syntax Element Description:

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.

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".

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).

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

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:

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