AFP structured fields included in line data

For more flexibility in formatting your line data applications, you can include certain AFP control records and you can embed certain AFP structured fields in the data. By mixing structured fields with line data, you change the formatting of selected pages in a data set, or include images or blocks of page data on a page, such as:

• Change a copy group to change electronic overlays, duplexing, paper source, or field suppressions.
• Change a page format to change print direction, data formatting, or conditional processing specifications.
• Include page segments from a library.
• Include page overlays from a library.
• Include image data inline with the application print data.
• Use text control sequences to include MO:DCA-P data, or to draw vertical and horizontal rules on a page.

For a description of the structured fields that can be mixed with line data, see Advanced Function Presentation: Programming Guide and Line Data Reference, S544-3884.

When you mix structured fields with line data records, these apply:

• All records in the data set must contain either the X'5A' control character or one of the valid carriage control characters listed in Table 4. If no control characters are specified, the data set can contain only line data records.
• The RECFM subparameter of the DCB parameter must specify "A" for American National Standard control characters or "M" for machine-code control characters.
• If the length of the structured field records is greater than or equal to the logical record length defined for the print data set, the record format of the data set must be specified as variable. These record formats can be specified:
  • Variable ANSI (VA)
  • Variable machine (VM)
  • Variable-blocked ANSI (VBA)
  • Variable-blocked machine (VBM)

  If the length of the structured field records is less than the logical record length defined for the print data set, a fixed-length record format can be specified.

• Structured fields that change copy groups or page formats cause PSF to eject to a new page. The first print record following one of these structured fields is the first record on the new page.
• Structured fields other than those that change copy groups or page formats do not affect the placement of line data records, nor can they affect the font or the orientation used for printing the line data records. These characteristics of line data records are defined in the page definition. Line data records mixed with structured fields print as defined in the page definition, regardless of whether structured fields are present. For example, if line data record two prints on line two of the page when the data set contains no structured fields, the record still prints on line two of the page even if a structured field to write MO:DCA-P data or to include a page overlay is written before it.

  A structured field can affect the printing of line data records if it contains text control sequences that change the spacing between characters and between words. Spacing between characters and between words in the line data record is changed, because these characteristics are not controlled in the page definition.

• Line data records can affect the placement, the font, and the orientation of MO:DCA-P data defined with structured fields. If the font ID, the orientation, or the placement is not defined in the structured field, or if the placement is defined as "relative", the values specified in the page definition for the current line data record is used for the MO:DCA-P data.

  If ANSI control characters are defined, the current line data record is the line data record that immediately precedes the structured field record. If machine-code controls are defined for the print data set, the current line data record is the line data record following the structured field record.

• Line data records can also affect the placement of page segments, page overlays, and images. The structured fields used to include page segments or page overlays can specify absolute position relative to the page origin, or placement at the current print line position. Images included directly in a line data set are always placed relative to the current print line. When you include these objects in line data, you can control their position by controlling the placement of the current line data record, which might involve writing a blank line data record at the position desired, or using carriage control characters to place the current line data record at the correct position.

To include a structured field in a print data set, you can either edit the print data set or include instructions in the application program to put the record in the print data set at the correct location, as in the segment from a sample application program shown in Figure 33.

Figure 33 shows a segment of a sample application program that is writing an Invoke Data Map (IDM) structured field to change the page format to be DATAMAP2, which defines 90° rotated text with an underscored font. The IDM structured field is written between the fifth and sixth line data records to call a new page format. The sixth line data record becomes the first print record on the new page to be formatted with the DATAMAP2 page format. Notice that the carriage control byte for the sixth line data record contains the "+" sign, which is the ANSI code to space zero lines. If the carriage control byte is a blank (ANSI code to skip one line before printing), the sixth record will not print on line 1 of the new page, but on line 2.

The coding in Figure 33 shows the layout and the description of the IDM record. The structured field begins with the X'5A' carriage control byte. A record descriptor word (RDW) field is coded in front of the structured field, because this is an assembly language program that is writing variable-length records. No RDW would be coded if fixed-length records were being written or if the program were written in a high-level language such as COBOL, which does not require user-coded RDW fields.

For information about coding carriage control bytes or variable-length records, see the publications for your programming language. For descriptions of the AFP structured fields, see Advanced Function Presentation: Programming Guide and Line Data Reference, S544-3884.

•
•
•
    OPEN (PRINT,(OUTPUT)) OPEN OUTPUT DATA SET
*****************************************************************************
*   PUT FIRST 5 LINES OF DATA                                            *
*****************************************************************************
PUT PRINT,LINE1
•
•
PUT PRINT,LINE5
*****************************************************************************
*   PUT A Structured Field TO CHANGE THE PAGE FORMAT SO                     *
*   THAT THE TEXT IS ROTATED 90 AND PRINTED USING AN UNDER-                 *
*   SCORED FONT.  A NEW PAGE IS STARTED.                                    *
*****************************************************************************
PUT PRINT,IDM
*****************************************************************************
*   PUT REMAINING LINES OF DATA                                             *
*****************************************************************************
PUT PRINT,LINE6
•
•
PUT PRINT,LINE10
CLOSE PRINT                                 CLOSE OUT DATA SET
•
•
*****************************************************************************
*   DECLARES FOR FIRST 5 LINES OF DATA                                   *
*****************************************************************************
LINE1    DS OCL19                           FIRST LINE
RDW1     DC X'00130000'                     RECORD DESCRIPTOR WORD
DATA1    DC CL15'+THIS IS LINE 1'           CARRIAGE CONTROL AND DATA
•
•
LINE5    DS OCL19                           FIFTH LINE
RDW5     DC X'00130000'                     CARRIAGE DESCRIPTOR WORD
DATA5    DC CL15'+THIS IS LINE 5'           CARRIAGE CONTROL AND DATA
*****************************************************************************
*   DECLARES FOR THE STRUCTURED FIELD                                       *
*****************************************************************************
IDM      DS 0XL21                           INVOKE DATAMAP STRUCTURED FIELD
RDW      DC X'00150000'                     RECORD DESCRIPTOR WORD
CC       DC X'5A'                           5A CONTROL CHARACTER
SFILEN   DC X'0010'                         LENGTH OF STRUCTURED FIELD
SFICODE  DC X'D3ABCA'                       HEX CODE FOR INVOKE DATAMAP
SFIFLAGS DC B'00000000'                     FLAGS
SFISEQ   DC X'0001'                         SEQUENCE NUMBER
PARMS    DC C'DATAMAP2                      DATAMAP NAME
*****************************************************************************
*        DECLARES FOR SECOND 5 LINES OF DATA                             *
*****************************************************************************
LINE6    DS OCL19                           SIXTH LINE
RDW6     DC X'00130000'                     RECORD DESCRIPTOR WORD
DATA6    DC CL15'+THIS IS LINE 6'           CARRIAGE CONTROL AND DATA
•
•
PRINT    DCB DSORG=PS,DDNAME=PRINT,MACRF=PM,BLKSIZE=25,                   X
              LRECL=21,RECFM=VBA
END