CSSICU      (chart-id, count, control)

   APL code               1204
   PGF RCP code           X'14000004' (335544324)

chart-id (specified by user) (fullword integer)
Gives the identification number of the chart to be used.

1

Full interactivity, with the Home panel seen first

2

Full interactivity, with the Display panel seen first

3

Only the Save/load and Display panels available

4

Print or plot a chart

5,

6 Draw a chart in the current page

7

Only the Display panel available

8

Only the Directory panel available

Element 2 - Help

0

PF key information is not shown initially on the Display and GDF Display panels. This can be changed by pressing ENTER on either panel.

1

PF key information is shown initially on the Display and GDF Display panels. This can be changed by pressing ENTER on either panel.

0

Panels specified by the ICUISOL option in the GDDM external defaults are available (see the GDDM System Customization and Administration book). If this is 0, all Save/load and Directory panels are available.

1

No Save/load or Directory panels available.

2

Save/load panels are available, but not the Directory panels.

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

ADM0720 E

CHART IDENTIFIER (=n) IS INVALID

ADM0721 E

CHART WITH IDENTIFIER n DOES NOT EXIST

• DISPLAY = 1, 2, or 3
  Meaning - Display panels
  These values 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). For interactive sessions, the ICU constructs charts using a unique GDDM page that is not accessible to the calling application program. This means that once an interactive session starts, GDDM calls cannot affect the chart. Conversely, ICU internal processing does not affect the calling program. (There is one exception: whenever the ICU constructs a chart, the PG routines call CHTERM to reinitialize the PG routines, and this may affect a calling program that uses PG routines.)
  DISPLAY = 5 and DISPLAY = 6 (see below) should be used if further control over charts constructed by the ICU is desired.
  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/load, and Directory panels (see element 3 of the control parameter) and possibly the Print panel.
  DISPLAY = 2 causes the Display panel, showing a chart constructed from the specified data and format, to be displayed initially to the operator (if there is data to display). The operator can then choose to exit directly from the Display panel to the calling program, or may use the Home PF key to display the Home Panel and so get access to the panel hierarchy, as for DISPLAY = 1. In this case, if a chart cannot be constructed because there is no data available, the Home Panel is displayed as for DISPLAY = 1.
  DISPLAY = 3 causes the Display panel to be displayed initially to the operator as for DISPLAY = 2, but with access to panels and help very much restricted. Only the Print and Save panels, at most, are accessible. Help information for the Display panel, and for the Print and Save panels, is available.
  Possible application
  DISPLAY = 1 is used to give normal full access to the ICU panels, as in stand-alone mode.
  DISPLAY = 2 may be used, for example, where normally the operator wants only to see the chart, but sometimes may want access to all the ICU panels.
  DISPLAY = 3 may be used, for example, to present a given set of data values in a given graphical format, and to allow the operator additional choices of printing or saving the chart, or both. Note that the interpretation of the ENTER and PF keys is the normal interpretation in an interactive ICU session. If the requirement is simply to display a chart for an operator who is not experienced in the use of the ICU, DISPLAY = 7 (see below) may be a better choice, because in that case any interrupt returns control to the calling program.

• DISPLAY = 4
  Meaning - Print or plot a chart
  This value is used to invoke the ICU as a subroutine that causes a created or loaded chart to be printed on a specified GDDM printer or plotter with a name specified by CSCHA type 3. (Note that, under VM/SP, a print file is created, but may have to be printed separately.)
  If a valid print destination name has been specified, the specified chart is printed as one print file. A header page is added, unless otherwise specified by CSINT type 45. The number of copies is also given by CSINT type 45. The size and position of the printed chart are given by CSFLT type 1 in units defined by CSINT type 45.
  Another way is for the calling program to add the chart to a print file that it has already opened, by specifying '*OPEN' as the value of CSCHA type 3. In this case, the type of heading page and the number of copies as specified by CSINT type 45 are 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. However, CSFLT type 1 can still be used to specify the size and position of the chart on the printed page.
  As for DISPLAY = 1, 2, or 3, the application program cannot modify or access the chart constructed for printing, because it is created using a GDDM page inaccessible to the calling program.
  Possible application
  DISPLAY = 4 may be used to print charts without operator interaction (or create a print file under VM/SP). Setting CSCHA type 3 to '*OPEN' may be used to include a chart in a print file already being created by an application program. In this case, the application program should open a print file, set CSCHA type 3 to '*OPEN', and use the CSSICU call with DISPLAY = 4 for each chart to be printed, then close the print file.

• 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. Control is returned to the calling program with the chart available for modification or use in the current page. ICU action is limited to chart construction; the chart is not written to a device.
  The chart constructed differs from the form in which it would be displayed in the Display panel of an ICU interactive session in that it contains no alphanumeric fields. (The Display panel, as shown with DISPLAY = 3 or 7, may show PF key information and error message information in alphanumeric fields overlaying the displayed chart.)
  If an error message is returned from a CSSICU call when DISPLAY = 5 or 6, the error is the first one of highest severity generated during chart construction.
  The chart constructed is that created or loaded by the application object names already specified, as usual. On return to the calling program, the chart exists in the current page as a collection of unnamed (zero-id) graphics segments in a GDDM graphics field. The graphics field and picture space are those defined by the caller, or defaulted by GDDM. The window and viewport are set as follows:
  • If the chart constructed is a line graph, surface chart, histogram, or bar chart the viewport boundaries are defined by the edges of the plotting area (in picture space coordinates), and the window boundaries are defined by the extreme values of the horizontal and vertical axis ranges (in axis coordinates).

  • If the chart constructed is a pie chart, Venn diagram, polar chart, tower chart, or table chart, both viewport and window boundaries are undefined.

  DISPLAY = 5 and DISPLAY = 6 differ in the following way:
  • DISPLAY = 5 causes the ICU to issue a CHRNIT call (to initialize the PG routines) before chart construction, and a CHTERM call (to terminate the PG routines) after chart construction. This is the same action as is taken for DISPLAY = 1, 2, 3, and 4. The effect is that chart construction is isolated from PG routine calls issued by the calling program. The chart is drawn as large as possible within the graphics field.

  • DISPLAY = 6 causes the ICU to construct the chart without issuing the CHTERM call after chart construction. The effect is that the chart constructed can be modified by PG routine calls issued by the calling program after the CSSICU call. Control is returned to the calling program with the PG routines in state-2. Any further PG routine calls issued by the application program must be valid in state-2 (for example, plotting routine calls), unless the program first returns to state-1 with a CHRNIT or CHSTRT call. With DISPLAY = 6, the chart is drawn as large as possible within the area specified with the CHAREA call. This area may be a subset of the graphics field.

  Possible application
  DISPLAY = 5 and DISPLAY = 6 allow the CSSICU call to be used as a high-level graphics call that may be combined with other GDDM or PGF calls in a straightforward manner to construct a picture. Any further use of the constructed picture (for example, to display it, print it, or save it) is under the control of the application program issuing the CSSICU call.
  DISPLAY = 5 is used when the calling program does not issue PG routine calls, or when the calling program does not need to modify chart construction by PG routine calls. For example, a chart may be constructed with DISPLAY = 5 and then saved in data-stream form by the calling program issuing the GDDM FSSAVE call.
  DISPLAY = 6 allows the calling program to modify the chart by issuing PG routine calls after the CSSICU call. Some examples follow, to illustrate the power of this technique:
  • CHAREA can be issued before the CSSICU call to specify the size and position of the chart area within which the chart is to be constructed. Thus CHAREA may be used, for example, to specify a chart area occupying the top left-hand quarter of the picture space. With normal GDDM defaults, this causes the chart constructed by the CSSICU call and displayed by means of FSFRCE or ASREAD to appear one-quarter its normal size, in the top left-hand corner of the screen.

  • Additional data groups can be added to the chart by plotting routine calls issued after the CSSICU call. For example, the CSSICU call can construct a bar chart. A subsequent CHPLOT call can be used to plot a line (a data group of a line graph) over this bar chart, thus mixing chart types.
    Note that the CSSICU call leaves the PG routines in state-2. A plotting routine call such as CHPLOT is valid in state-2, and has the effect of plotting the specified data against the axes already constructed by the CSSICU call (the x coordinates of the points of the line are plotted against the bar chart x axis).
    Note that no entry appears in the legend for the added line. This is because the ICU issues a CHKEY call (in state-1) for the keys of the plotted bar chart data groups. All the keys in the list specified in this CHKEY call are used in the bar chart legend, so there is no key available for the additional data group constructed by the CHPLOT call.

  • Secondary axes may be utilized by a similar technique. If the CHPLOT call is preceded by CHYSEL(2) (in order to select the secondary y axis), the effect is that the line graph is plotted against the bar chart x axis already constructed by the CSSICU call, and against a secondary y axis that is constructed by the CHPLOT call.

  • Finally, two (or more) charts can be overlaid by a sequence such as:

    
                     CALL CSSICU(...);    /*with element = 6*/
                        .
                        .
                        .
                        .
                     Specify another chart
                        .
                        .
                        .
                        .
                     CALL CSSICU(...);    /*with element = 6*/
    
    

    The main difference between this case and the examples discussed above is that two sets of axes, and two legends, are constructed (one from each CSSICU call). With appropriate chart formats, the sets of axes may be made to coincide, or they may be made to appear in left/right and top/bottom pairs (like primary and secondary axes). Again, with suitable chart format specifications, the two legends can be made to appear as parts of a single legend, or they can be separated (one on the left and one on the right of the chart, for example).

• DISPLAY = 7
  Meaning - Only display a chart
  DISPLAY = 7 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.
  The chart is displayed without the error message or PF key information lines that may appear in alphanumeric fields on the Display panel during an interactive session.
  Possible application
  DISPLAY = 7 can be used as a simple means of causing a specified chart to be displayed on the GDDM primary device. The application programmer need not know anything about GDDM concepts such as pages or graphics fields, because the ICU action is completely isolated from the calling program. The primary device is normally a display terminal, but could also be a queued printer (for example). This allows the same application program to be used to present a chart on different types of device.
  In the normal case where the primary device is a screen, the ASREAD is terminated when the operator causes an interrupt of any kind (by pressing any key, for example). Hence DISPLAY = 7 can be used by an operator unfamiliar with the input conventions of an interactive ICU session. For example, an application program can display a sequence of charts by using a sequence of CSSICU calls with DISPLAY = 7. The operator can examine each chart for as long as is required, then press any key to get the next chart in the sequence. However, the calling program cannot determine what type of interrupt completed the ASREAD. Thus, the application cannot take different actions depending upon which PF key was pressed.
  Note: If the primary device is defined as output-only (as under IMS, for example) the ASREAD call acts like FSFRCE. In this case the chart remains on a display screen until the application program causes further output, and operator input is disallowed.

• DISPLAY = 8
  Meaning - Only display a chart
  This value restricts the ICU to the Directory panel in advanced mode format, and its associated Help panel. The Directory panel is displayed initially, not the Home panel, and no other panel, apart from Help panels, can be accessed. Library management functions only are included on the panels: chart display and printing functions are not accessible, nor are the chart update, save, or restore facilities. However, GDF files can be displayed and printed.
  The Directory panel may be used to list those objects that are listed when the ICU is started in stand-alone mode (namely, chart data and formats, vector and image symbol sets, pictures saved with FSSAVE calls, GDF files, and generated mapgroups). Delete, list and copy functions are available for all these objects.
  Possible application
  DISPLAY = 8 allows the ICU to be used as an interactive library manager.