%GRAPH (Convert to Graphic Value)

%GRAPH(char-expr | graph-expr | UCS-2-expr { : ccsid })

%GRAPH converts the value of the expression from character, graphic, or UCS-2 and returns a graphic value. The result is varying length if the parameter is varying length.

The second parameter, ccsid, is optional and indicates the CCSID of the resulting expression. The CCSID defaults to the default graphic CCSID of the module as specified by control keyword CCSID(*GRAPH). If CCSID(*GRAPH : *IGNORE) is specified on the control specification or assumed for the module, the %GRAPH built-in is not allowed.

If the parameter is a constant, the conversion will be done at compile time. In this case, the CCSID is the graphic CCSID related to the CCSID of the source file.

If the parameter is character data with an EBCDIC CCSID, the character data must be in the form

shift-out graphic-data shift-in

For example, 'oAABBCCi'.

See Conversions for information about the possibility that converting some data to graphic may not be able to convert all the data successfully.

For more information, see Graphic Format, Conversion Operations, or Built-in Functions.

Figure 1. %GRAPH Examples

 *..1....+....2....+....3....+....4....+....5....+....6....+....7...+....
H*Keywords+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
H ccsid (*graph: 300)

D*Name++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++++++++++++++++++
D  char           S              8A   inz('oXXYYZZi')
 * The %GRAPH built-in function is used to initialize a graphic field
D  graph          S             10G   inz (%graph ('oAABBCCDDEEi'))
D  ufield         S              2C   inz (%ucs2 ('oFFGGi'))
D  graph2         S              2G   ccsid (4396) inz (*hival)
D  isEqual        S              1N
D  proc           PR
D    gparm                       2G   ccsid (4396) value

 /FREE
    graph = %graph (char) + %graph (ufield);
    // graph now has the value XXYYZZFFGG.
    // %graph(char) removes the shift characters from the
    // character data, and treats the non-shift data as
    // graphic data.
 
    isEqual = graph = %graph (graph2 : 300);
    // The result of the %GRAPH built-in function is the value of
    // graph2, converted from CCSID 4396 to CCSID 300.
 
    graph2 = graph;
    // The value of graph is converted from CCSID 300 to CCSID 4396
    // and stored in graph2.
    // This conversion is performed implicitly by the compiler.
 
    proc (graph);
    // The value of graph is converted from CCSID 300 to CCSID 4396
    // implicitly, as part of passing the parameter by value.
 /END-FREE

Note: The literals containing DBCS data in this example, such as 'oFFGGi', do not have valid DBCS data or valid shift characters. See Graphic Format for more information.