CHART       (chart_control, data_control, x, y, keys, labels, heading)

   APL code               1200
   PGF RCP code           X'14000000' (335544320)

chart_control (specified by user) (124-byte character string)
A structure giving invocation control information and describing the contents of later parameters. The format and more detailed information are given in "Format of the chart_control parameter" in topic 4.101.

ADM0700 E

INVALID PRINTER WIDTH, DEPTH, OR OFFSET

ADM0701 E

FIRST DATA GROUP DOES NOT HAVE 3 VALUES FOR VENN DIAGRAM

ADM0702 S

INVALID PRIMARY DEVICE

ADM0704 S

SCREEN IS TOO SMALL (n1 BY n2 REQUIRED)

ADM0706 E

'a' (=n) IS INVALID

ADM0707 E

NUMBER OF COPIES FOR PRINT (=n) IS INVALID

ADM0708 E

MISSING X VALUES NOT ALLOWED IN 'FREE' DATA

ADM0716 E

INVALID {PRINT|GRAPHIC DATA FORMAT (GDF)} DESTINATION NAME

ADM0717 E

PRINT NAME IS '*OPEN' BUT NO ALTERNATE DEVICE IS IN USE

             


   Figure 16. Parameters passed in a CHART call

• LEVEL (offset 0; fullword integer)
  Indicates whether chart_control contains all the currently defined fields, or only those that were defined at Version 1, Releases 1 and 2 of GDDM-PGF. See page 4.101 for details of using LEVEL.

• DISPLAY (offset 4; fullword integer)
  The value supplied in this field controls the overall function of the CHART call. For example, it controls whether operator interaction is supported, and if so, whether the Home Panel or the Display Panel is displayed initially.
  The DISPLAY field of the chart_control parameter may be set by the calling application program to a value from 0 through 9.
  Values 0 and 9 apply to the CHART call only and are described fully below with possible applications. Values 1 through 8 are very similar to those of element 1 of the control parameter of the CSSICU call. A brief description of these values is given below. Fuller explanations and possible applications are given with "CSSICU - Start an ICU session for a chart" in topic 4.125.
  • DISPLAY = 0
    Meaning - Save a chart
    When DISPLAY = 0, the only action taken by the ICU is to create a new Chart Data file from the data supplied in the remaining parameters of the CHART call. No operator interaction occurs and no chart is drawn.
    The DATANAME field must contain the name to be assigned to the newly created Chart Data file. If a Chart Data file with the same name already exists, no action is taken, and control is returned to the calling program with an error message.
    The data is supplied by setting fields NG, NE, LABELL, KEYL, and HEADINGL in chart_control appropriately, and by supplying corresponding data arrays in the remaining parameters of the CHART call. The string supplied in the heading parameter is used for the description text associated with the saved chart data file, as well as for the chart heading.
    Possible application
    Data derived from an application file or data base may be converted and stored as Chart Data files with DISPLAY = 0 for later access by operator action during an ICU interactive session. Or, instead, a Chart Data file created in this way may be passed to the ICU on a later call (when the original application file or data base may no longer be accessible) by placing the Chart Data name in DATANAME.

  • DISPLAY = 1, 2, or 3
    Meaning - Display panels
    These are the only values by which a CHART call can initiate an interactive session, defined as access by the operator (at the GDDM primary device) to the ICU Display panel and to some or all of the other panels and help information, using the standard ICU interpretation of interrupts (ENTER key, PF keys, and so on).
    Note: An interactive session in the above sense cannot be initiated by a program running under the IMS subsystem. In general, when DISPLAY=1, 2, or 3, the primary device must be one that supports input.
    DISPLAY = 1 causes the Home Panel to be displayed to the operator initially, and so gives access to the panel hierarchy. All panels are accessible except possibly the Save, Restore, and Directory panels (see the ISOLATE field) and possibly the Print panel (see the DESTNAME field). Chart format and data are initialized according to the values of FORMNAME and DATANAME.

  • DISPLAY = 4
    Meaning - Print or plot a chart
    This value is used to invoke the ICU as a subroutine that causes a specified chart to be printed on a specified GDDM printer or plotter. The chart is specified in FORMNAME and DATANAME, and the printer or plotter is specified by the value in the DESTNAME field.
    For a valid print destination name in DESTNAME, the specified chart is printed as one print file. A header page is added, unless otherwise specified in PRTHEAD. The number of copies is given by PRTCOPY. The size of the printed chart is given by PRTDEP and PRTWID, in units defined by PRTUNIT. The position of the chart on the page is controlled by PRTVOFF and PRTHOFF, which specify the vertical and horizontal offsets, also in units defined by PRTUNIT.
    Or, instead, the calling program may add the chart to a print file that it has already opened, by specifying '*OPEN' as the value of DESTNAME. In this case, PRTCOPY is ignored because the number of copies to be printed was specified on the FSOPEN or DSOPEN call issued by the application program to open the print file. PRTHEAD is also ignored. However, PRTDEP, PRTWID, PRTVOFF, and PRTHOFF can be used to specify the size and position of the chart on the printed page.

  • DISPLAY = 5 or 6
    Meaning - Construct a chart
    These values cause a specified chart to be constructed in the calling program's current GDDM page. The chart constructed is that specified by FORMNAME and DATANAME.

  • DISPLAY = 7
    Meaning - Only display a chart
    This value causes the ICU to construct a chart on a GDDM page inaccessible to the calling program (as for DISPLAY = 1, 2, 3, and 4), and then to output the constructed chart with a GDDM ASREAD call. On return from this ASREAD call, the ICU immediately returns control to the calling program.

  • DISPLAY = 8
    Meaning - Only show the directory
    This value restricts the ICU to the Directory panel in advanced mode format, and its associated Help panel.

  • DISPLAY = 9
    Meaning - Create a GDF file
    The only action taken by the ICU is to create a new Graphics Data Format (GDF) file from the Chart Format and Chart Data supplied in the CHART call parameters. No operator interaction occurs.
    Chart Data can be supplied with the CHART call parameters by setting DATANAME = '*', or can be taken from an existing Chart Data file by specifying DATANAME = 'file-name'.
    The Chart Format used can be the default if FORMNAME = '*', or can be taken from an existing Chart Format file if FORMNAME = 'file-name'.
    Any string supplied with the heading parameter is used as a file descriptor for the GDF file, as well as any possible use as part of the Chart Data.
    The destination name DESTNAME = 'file-name' is used to determine the name of the GDF file that is produced.
    Possible application
    Data derived from an application file or data base may be merged with a Chart Format to produce a GDF file that contains a chart picture using specific data.
    GDF files can be used by a wider range of applications than the ICU; this type of file may, therefore, find wider usage than Chart Format and Chart Data files.

• HELP (offset 8; fullword integer)

  0

  PF key information is not displayed initially on the Display and GDF Display panels. This setting can be changed by using ENTER whenever either panel is displayed.

  1

  PF key information is displayed initially on the Display and GDF Display panels. This setting may be changed by using ENTER whenever either panel is displayed.

  Ignored unless DISPLAY = 1, 2, 3, or 8.

• ISOLATE (offset 12; fullword integer)

  0

  Save, Restore, and Directory panels are made available to the operator. The setting is taken from the value of the ICUISOL option in GDDM's external defaults (see the GDDM System Customization and Administration book).

  1

  Save, Restore, and Directory panels are not made available to the operator.

  2

  Save and Restore panels are made available to the operator, but the Directory panel is not.

  Ignored unless DISPLAY = 1, 2, or 3.

• FORMNAME (offset 16; 8-byte character)
  and

• DATANAME (offset 24; 8-byte character)
  These two fields specify the use of Chart Format and Chart Data files respectively. The name of an existing Chart Format file may be supplied by the calling program in FORMNAME. If specified in FORMNAME, the named Chart Format file is used by the ICU to initialize the chart format. Similarly, DATANAME may be used to initialize chart data.
  If FORMNAME contains the reserved name '*', the chart format is initialized to the default format. This is the format used when the ICU is used in stand-alone mode. It specifies a line graph with autoscaled axes, a legend in the center of the right margin, and so on.
  The '*' is also a reserved name for DATANAME. It specifies that chart data is to be initialized from data supplied in the other parameters of the CHART call. These parameters define the x- and y-data values, the data labels (used instead of x-data values for bar charts, pie charts, and Venn diagrams), the keys (which describe data groups), and the chart heading.
  Only when DATANAME = '*' (or when DISPLAY = 0) are these remaining parameters accessed during ICU execution. If no data is to be supplied on the CHART call, DATANAME should be set to '*' and other fields (NG, NE, KEYL, LABELL, and HEADINGL - see below), which describe the data supplied in the remaining parameters, should be set to zero.

• BINDING (offset 32; fullword integer)
  The BINDING field is used only when DATANAME = '*' or when DISPLAY = 0. It indicates whether the data supplied is free or tied. In free mode, each data group has its own set of x values that are different from other data groups. A typical example where free data mode is appropriate is a scatter plot, where each data group is an arbitrary set of (x,y) pairs, and is unrelated to other data groups. In tied data mode, all data groups have the same set of x values.
  Free data was formerly known as paired data, and tied as non-paired.
  In both free and tied modes there is only one set of data labels, which is common to all data groups (but only used for bar charts, pie charts, Venn diagrams, and table charts).
  Valid values are:

  0

  Sets of x and y values are tied. There is one set of x values, against which each set of y values is plotted.

  1

  Sets of x and y values are free. For each set of y values there is a corresponding set of x values. The sets of x values are distinct.

  Note: For further details on free and tied data see "Free (paired) and tied (non-paired) data" in topic 2.5.1.

• NG (offset 36; fullword integer)
  The NG field is used only when DATANAME = '*' or when DISPLAY = 0. It specifies the number of data groups supplied.
  For tied data, NG specifies the number of sets of y values in the y-array parameter.
  For free data, NG specifies the number of sets of values in each of the x- and y-array parameters, and the number of values in the data_control parameter.
  For both free and tied data, NG also specifies the number of character-string elements in the keys array parameter (if the length of each string, given by KEYL, is nonzero).
  If BINDING = 0, the number of data groups for which values are specified in the y-array parameter. If BINDING = 1, the number of data groups for which values are specified in the x- and y-array parameters, and the number of values in the data_control array parameter. Range 0 through 999.

• NE (offset 40; fullword integer)
  The NE field is used only when DATANAME = '*' or when DISPLAY = 0. It specifies the exact number of points in each data group (for tied data), or the maximum number of points in any data group (for free data).
  For tied data, NE specifies the number of y values in each set of values in the y-array parameter, and the number of x values in the x-array parameter (which is common to all data groups).
  For free data, NE specifies the maximum value of any element in the data_control array parameter. The values in data_control specify the actual number of elements in each data group.
  For both free and tied data, NE also specifies the number of data label character string elements in the labels array parameter (provided the length of each string, given by LABELL, is non-zero).
  The calling program may choose whether to supply just data labels, or just x data values, or both data labels and x data values. Specifies the number of elements (per data group) in x and y. Also specifies the number of label strings in labels (if LABELL>0). Range -999 through 999. A positive value causes either labels (if LABELL>0) or x (if LABELL=0) to be passed, but not both. A negative value acts in the same way as the corresponding positive value except that x is passed even if LABELL>0. (This allows both x and labels to be passed.)
  If BINDING = 1, the absolute value of NE gives the maximum number of elements in any data group. The actual number in each data group is specified in the data_control array parameter.

• Length fields
  The length fields KEYL, LABELL, and HEADINGL are used only when DATANAME = '*' or when DISPLAY = 0. They specify respectively the number of characters in each key in the keys parameter, the number of characters in each label in the labels parameter, and the number of characters in the heading parameter. In each case, a zero value is allowed, and the corresponding parameter is then ignored.
  • KEYL (offset 44; fullword integer) Length of each string in keys. Range 0 through 132.
    Ignored unless NG=0 and either DISPLAY = 0 or DATANAME='*'.

  • LABELL (offset 48; fullword integer) Length of each string in labels. Range 0 through 132.
    Ignored unless NE=0 and either DISPLAY = 0 or DATANAME='*'.

  • HEADINGL (offset 52; fullword integer) Length of heading. Range 0 through 132.
    Ignored unless DISPLAY=0, DISPLAY=9, or DATANAME='*'.

• DESTNAME (offset 56; 8-byte character)
  IF DISPLAY=1, 2, 3, 4, the DESTNAME field describes the destination name for a print or plot operation.
  DESTNAME=' ' indicates no printer is available (for DISPLAY = 1, 2, or 3 this makes the Print panel inaccessible). DESTNAME='*' indicates that the name is unknown (for DISPLAY = 1, 2, or 3 the name appears blank initially on the Print panel). DESTNAME='*OPEN' indicates that only the current open alternate device supplied by the calling program may be used. These three names are reserved names. Any other name is used as follows:
  • For DISPLAY = 1, 2, or 3 the name appears on the Print panel and cannot be modified by the operator.

  • For DISPLAY = 4 the name identifies the print destination device.
    The reserved names ' ' and '*' are not valid for DISPLAY = 4.

  IF DISPLAY=9, DESTNAME is the name of the GDF file to be produced.

  Ignored unless DISPLAY = 1, 2, 3, 4, or 9.

• Printing fields
  The PRTDEP, PRTWID, PRTCOPY, PRTHEAD, PRTVOFF, PRTHOFF, and PRTUNIT fields may be used to control the printing action of the ICU.
  If DISPLAY = 1, 2, or 3, used to initialize the Print panel.
  • PRTDEP (offset 64; short floating point)
    Depth of the chart area on the printer, in units given by PRTUNIT. A 0 gives the default depth (the same as '*' on the ICU Print panel). Ignored unless DISPLAY = 1, 2, 3, or 4, and DESTNAME=' '.

  • PRTWID (offset 68; short floating point)
    Width of the chart area on the printer, in units given by PRTUNIT. A 0 gives the default width (the same as '*' on the ICU Print panel). Ignored unless DISPLAY = 1, 2, 3, or 4, and DESTNAME=' '.

  • PRTCOPY (offset 72; fullword integer)
    Number of copies to be printed. Range 0 through 99 (0 is treated as a request for the ICU default value of 1). Ignored unless DISPLAY = 1, 2, 3, or 4, and DESTNAME=' ' and DESTNAME = '*OPEN'.

  • PRTHEAD (offset 76; fullword integer)
    Specifies the type of identification that is to precede the output. The identification can have combinations of a header page, an origin identification (userid/time/date), neither, or both.

    0

    default (same meaning as 1)

    1

    header page, no origin identification

    2

    no header page, no origin identification

    3

    header page plus origin identification

    4

    origin identification, no header page

    Ignored unless DESTNAME = ' ' and DESTNAME = '*OPEN'.

  • PRTVOFF (offset 80; short floating point)
    Vertical offset of chart area on the printer from top of page, in units given by PRTUNIT. -1 gives the default offset (the same as '*' on the ICU Print panel.)
    Ignored unless DESTNAME=' '.

  • PRTHOFF (offset 84; short floating point)
    Horizontal offset of chart area on the printer from the left-hand edge of the page, in units given by PRTUNIT. -1 gives the default offset (the same as '*' on the ICU Print panel.)
    Ignored unless DESTNAME=' '.

  • PRTUNIT (offset 88; fullword integer)
    Units of measurement for page layout fields PRTDEP, PRTWID, PRTVOFF, and PRTHOFF.

    0

    default (same meaning as 1)

    1

    percent of corresponding page dimension (depth or width)

    2

    inches

    3

    centimeters

    4

    printer rows for PRTDEP and PRTVOFF, or columns for PRTWID and PRTHOFF

    Ignored unless DESTNAME=' '.

• RESERVED (offset 92; fullword integer)
  Reserved field.

• Directory fields
  DRYNAME, DRYTYPE, DRYTYPEQ, and DRYLIB are used to control the content of the initial Directory panel. Ignored unless DISPLAY=8.
  • DRYNAME (offset 96; 8-byte character)
    Names of objects to be listed on initial Directory panel. Can begin and/or end with '*', to specify a set of object to list. Blank means list all names.

  • DRYTYPE (offset 104; fullword integer)
    Type of object to be listed on initial Directory panel. Some types must be further defined by the type qualifier field, DRYTYPEQ.

    0

    list nothing

    1

    list symbol sets (as qualified)

    2

    list generated mapgroups

    3

    list pictures stored with FSSAVE

    4

    list chart descriptor(s) (as qualified)

    5

    list chart descriptor(s) (as qualified)

    7

    list GDF files

    9

    list data definitions

    10

    list image projection files

    11

    list image data files.

  • DRYTYPEQ (offset 108; fullword integer)
    Qualifier for type of object to be listed on initial Directory panel.
    If DRYTYPE = 1 then

    0

    default: same effect as 2

    1

    list image symbol sets

    2

    list vector symbol sets

    If DRYTYPE = 4 then

    0

    default: same effect as 1

    1

    list chart format objects only

    2

    list chart data objects only

    3

    list chart format and data objects

    If DRYTYPE = 5 then

    0

    default: same effect as 2

    1

    list chart format objects only

    2

    list chart data objects only

    3

    list chart format and data objects

    Ignored unless DRYTYPE = 1, 4, or 5.

  • DRYLIB (offset 112; 8-byte character)
    Library containing objects to be listed on initial Directory panel. Must be left-justified and padded with blanks.
    • Under TSO, a ddname
    • Under CICS, a symbolic data set name
    • Under VM, a 1- or 2-character filemode
    • Under IMS, a DBD name

    In all cases, a blank means that the library defined by ESLIB calls (or GDDM defaults) is listed.

• EXPLVL (offset 120; fullword integer)
  The EXPLVL field defines the experience level mode (standard or advanced) of the initial Directory panel, as discussed under "Format of the chart_control parameter" in topic 4.101. Initial experience level mode for Directory panel.
  The ICU provides two modes, called standard and advanced. They differ in the amount of function available.

  0

  default, same effect as 1

  1

  standard

  2

  advanced

  Ignored unless DISPLAY = 1, 2, or 3.

1. By specifying the name of an existing Chart Data file in DATANAME. Such a Chart Data file must have been created previously by operator action during an ICU session, or by invocation of the ICU with DISPLAY=0, supplying data by method 2 below, or by using CSSAVE.

2. By specifying '*' in DATANAME, and supplying chart data in array parameters of the CHART call.
   One use of this method is to supply no data with the CHART call (in order, for example, to invoke the ICU with a specific initial format, but without supplying any data). To achieve this result, put DATANAME='*', NG=0, NE=0, KEYL=0, LABELL=0 and HEADINGL=0. Only the chart_control parameter is accessed by the ICU in this case; values for the other parameters may be dummy values.

Tower charts have z-axes, but you cannot pass z-axis data in the CHART call. However, you can still create tower charts because, in the absence of z-axis data, the ICU creates a logical z axis with the data groups spaced evenly along it. If you want to pass z-axis data, use the CSxxxx calls.

       PRTHEAD=0
       PRTVOFF=0
       PRTHOFF=0
       PRTUNIT=4
       DRYNAME=' '
       DRYTYPE=0
       DRYLIB=' '
       EXPLVL=0