SAS Institute. The Power to Know

FOCUS AREAS
DATA step

Base SAS

Methods for the ODS DATA Step Object

This document provides syntax for the methods of the ODS DATA step object. For more information, see the SUGI 28 paper Next Generation Data _NULL_ Report Writing Using ODS OO Features and download the example code (.zip).

Warning: This feature is preproduction for SAS 9.1.3 and later, and it can change at any time. Please direct questions or comments to Daniel O’Connor.

Constructor( <Name: string | character variable>, <Label: string | character variable > );

or

_New_ ( <Name: string | character variable>, <Label: string | character variable > );

Create an instance of the ODSOUT class.

Returns: ObjectPtr
Arguments:
<Input> Name
A character string used in ODS processing to identify the object. Used in the ODS select and exclude processing as well as the ODS Results window.

<Input> Label
A more descriptive character string than the Name used in ODS processing to identify the object. Used in the ODS select and exclude processing as well as the ODS Results window.
Optional Arguments: None
Example: 
Dcl odsout obj;

...

Obj = _new_ ( Name: "Object 1",

Label:
"Example of using the _ new_ method to instantiate an object" );

Dcl odsout obj ( Name: "Object 2",

Label:
"Example of using the constructor to instantiate an object" );

Rc = Delete ( objectPtr );

Delete an instance of the ODSOUT class.

Returns:
0
success

Any other number
failure
Arguments:
<Input> objectPtr
The object instance returned from the constructor/new() call.

Rc = Body_Start ()

Marks the start of the table body (data rows).

See also HEAD_START, ROW_START, CELL_START, and FOOT_START.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Body_End ()

Marks the end of the table body.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Cell_Start ( )

This is used to start a cell. 

It must be used for stacked cells and other special effects; for simple cases, FORMAT_CELL will generally suffice.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Overrides < string | character variable >
Style Overrides.

<Input> TEXT < string | character variable >
Text to display in the cell.

<Input> Split < string | character variable >
Split character.

<Input> Column_Span < int >
Number of columns that this cell should take up. Defaults to 1, of course. Extra cells extend to the right.

<Input> Row_Span < int >
Number of rows that this cell should span. Extra cells extend down. Defaults to 1, of course.

<Input> No_Clean < int >

<Input> Col_Start < int >
The starting column for this cell.

Use either this and OA_COLEND, OA_COLSPAN, but not both, for multi-column cells. To entirely skip columns, you must use this. Columns are 1-indexed from the left.

Defaults to the column after the previous column, or to 1if this is the first CELL_START after a ROW_START.

<Input> Col_End < int >
The ending column for this cell.

<Input> Underline < int >
Underline this cell.

<Input> Overline < int >
Draw a line over this cell.

<Input> Inhibit < string | character variable >
Tells aspects of the cells that may be inhibited. This option can only be honored for certain destinations; in particular, HTML does not currently support it.

‘T’
INHIBIT_TOP

Don't draw the top rule. Note that some destinations will have already drawn a rule at the bottom of the previous row, so this one may not be effective.

‘B’
INHIBIT_BOTTOM

Don't draw the bottom rule. Looks as if this cell and the one below are a single cell, sort of.

‘L’
INHIBIT_LEFT

Don't draw the left rule. Ineffective if the destination already drew that rule on the right of the previous cell.

‘R’
INHIBIT_RIGHT

Don't draw the right rule. Looks as if this cell and the one to the right are a single cell, sort of.

‘X’
INHIBIT_TEXT

Don't draw the contents of the cell, just the background. Usually desirable on one of the two cells which are using the INHIBIT_BOTTOM or INHIBIT_RIGHT.

Rc = Cell_end ( )

Marks the end of the cell.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Open_Dir ( )

Not supported.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Close_Dir ( )

Not supported.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Foot_Start ( )

Marks the start of the foot rows of the table.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: <Input> At_End < int >

Rc = Foot_End ( )

Marks the start of the foot rows of the table.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Format_Cell ( )

A call to FORMAT_CELL(…) is exactly the same as calling CELL_START() with the same arguments, and the immediately calling CELL_END(). In practice, of course, the TEXT argument is required for FORMAT_CELL() (else the cell is empty).

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Overrides < string | character variable >
Style Overrides.

<Input> TEXT < string | character variable >
Text to display in the cell.

<Input> Split < string | character variable >
Split character.

<Input> Column_Span < int >
Number of columns that this cell should take up. Defaults to 1, of course. Extra cells extend to the right.

<Input> Row_Span < int >
Number of rows that this cell should span. Extra cells extend down. Defaults to 1, of course.

<Input> No_Clean < int >

<Input> Col_Start < int >
The starting column for this cell.

Use either this and OA_COLEND, OA_COLSPAN, but not both, for multi-column cells. To entirely skip columns, you must use this. Columns are 1-indexed from the left.

Defaults to the column after the previous column, or to 1if this is the first CELL_START after a ROW_START.

<Input> Col_End < int >
The ending column for this cell.

<Input> Underline < int >
Underline this cell.

<Input> Overline < int >
Draw a line over this cell.

<Input> Inhibit < string | character variable >
Tells aspects of the cells that may be inhibited. This option can only be honored for certain destinations; in particular, HTML does not currently support it.

‘T’
INHIBIT_TOP

Don't draw the top rule. Note that some destinations will have already drawn a rule at the bottom of the previous row, so this one may not be effective.

‘B’
INHIBIT_BOTTOM

Don't draw the bottom rule. Looks as if this cell and the one below are a single cell, sort of.

‘L’
INHIBIT_LEFT

Don't draw the left rule. Ineffective if the destination already drew that rule on the right of the previous cell.

‘R’
INHIBIT_RIGHT

Don't draw the right rule. Looks as if this cell and the one to the right are a single cell, sort of.

‘X’
INHIBIT_TEXT

Don't draw the contents of the cell, just the background. Usually desirable on one of the two cells which are using the INHIBIT_BOTTOM or INHIBIT_RIGHT.

Rc = Format_Paragraph ( )

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Overrides < string | character variable >
Style Overrides.

<Input> TEXT < string | character variable >
Text to display in the Paragraph.

<Input> Top_Space < int >
The space to put before the paragraph. This will certainly be ignored by HTML, and while it is expected to be the same as the line count supplied to monospace for the same purpose, other viewers reserve the right to put a smaller or greater amount of vertical space as seems appropriate.

<Input> Required_Space < int >
This says that you want us to try to keep this many items together. It basically asks that this item be printed on the same page as the next REQUIRED_SPACE items, where an "item" is a paragraph or table row. It is, of course, meaningless for HTML.

Rc = Format_Table ( )

Not implemented.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Format_Text ( )

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Overrides < string | character variable >
Style Overrides.

<Input> Text < string | character variable >
Text to display in the cell.

<Input> Split < string | character variable >
Split character.

<Input> No_Clean < int >

<Input> New_Line < int >

Rc = Head_Start( )

Marks the start of the table head. 

This is necessary so that paginated viewers can tell which rows should be repeated at the top of every page. It does not necessarily cause any visual effects in the output, If you want the headings to be visually distinct, use a style on the cells in the header.

Required for any table which has headers and may possibly cross pages. (For a nested table, which can't break pages anyway, it could be skipped, though I'd recommend using it anyway.)

Related methods FORMAT_ROW, ROW_START, ROW_END, CELL_START, CELL_END, and FORMAT_CELL.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Head_End ( )

Marks the end of the headers.

Related methods FORMAT_ROW, ROW_START, ROW_END, CELL_START, CELL_END, and FORMAT_CELL.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Href ( )

Create a hyperlink.

Returns:
0
success

Any other number
failure
Required Arguments:
<Input> Text < string | character variable >
The text of the hyperlink.

<Input> File < string | character variable >
The file/URL resource to point to
Optional Arguments:
<Input> Id < string | character variable >
The text for the ID.

<Input> Split < int >

<Input> No_Base < int >
Don't prepend the base URL

Rc = Image ( )

This puts the image from the specified file into the document.

For some output destination this will have no effect.

Returns:
0
success

Any other number
failure
Required Arguments:
<Input> ID < string | character variable >
The name of the image file. Should be one of the formats supported by both HTML browsers and the SAS image code for maximum utility. In addition, it must be a format supported by RTF. Frankly, the only format that I'm certain is supported by all of this is ".jpg", but we should look into this . . .
Optional Arguments: None

Rc = Layout_Gridded ( )

This marks the start of a layout section of the document. 

A layout section is an area of the document which you are laying out explicitly placing yourself. The total area in which you lay out the items must be no larger than the size of a page; if it is too large for the page,

there is no guarantee that you will get sensible results.

The items must be layed out in order as if laying out a table; that is, from top to bottom and left to right; or, in other words, "BY Y X", in SAS terms.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Overrides < string | character variable >
Style Overrides.

<Input> Width < dimension >
The width of the layout area.

<Input> Height < dimension >
The height of the layout area.

<Input> Row_Gutter < dimension >
The amount of space between layout rows.

<Input> Column_Gutter < dimension >
The amount of space between layout columns.

<Input> Columns < int >
Number of columns in a gridded Layout.

<Input> Rows < int >
Number of Rows in a gridded Layout.

<Input> Row_Heights < dimension >
Heights of each row.

<Input> Column_Widths < dimension >
Widths of each Column.

<Input> Band < int >
Not Implemented

<Input> Page < int >
Not Implemented

<Input> Resume < int >
Not Implemented

Rc = Layout_Absolute ( )

Not supported.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Layout_End ( )

End a layout.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Line ( )

Draws a horizontal rule (line) across the page.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Size < dimension >
The thickness of the rule; including units (e.g., "5pt" or "0.05in").

Rc = Note ( )

Writes a note to the document.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Text < string | character variable >
The text of the note.

<Input> Just < string | character variable >
The justification of the note: Left Center Right

Rc = Page ( )

Forces a page eject or configures the page.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Top_Space < dimension >
Specifies the amount of space to be generated before each object is rendered. The default for this parm is 1.

Not Implemented

Rc = Region ( )

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Overrides < string | character variable >
Style Overrides.
<Input> Width < dimension >
The width of the layout area.

<Input> Height < dimension >
The height of the layout area.

<Input> Row_Gutter < dimension >
The amount of space between layout rows.

<Input> Column_Gutter < dimension >
The amount of space between layout regions.

<Input> x < int >
Specifies the left-most position of the region in an absolute layout.

<Input> y < int >
Specifies the top-most position of the region in an absolute layout.

<Input> Column < int >
Specifies the column number of the gridded layout to place the region.

<Input> Rows < int >
Specifies the row number of the gridded layout to place the region.

<Input> Row_Heights < dimension >
Heights of each row.

<Input> Column_Widths < dimension >
Widths of each Column.

<Input> Column_Span < int >
Number of columns that this cell should take up. Defaults to 1, of course. Extra cells extend to the right.

<Input> Row_Span < int >
Number of rows that this cell should span. Extra cells extend down. Defaults to 1, of course.

<Input> Chain < int >
If the output overflows the vertical position of the region, flow it into the top of the next region. Applies to absolute layout only.

<Input> Continue < int >
If the output overflows the vertical position of the region, duplicate the entire layout and continue the contents of this region onto the same region space in the duplicated layout. Repeat as necessary to keep from truncating the output. Applies to absolute layout only.

Rc = Row_Start ( )

Mark the start of a row.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Overrides < string | character variable >
Style Overrides.

<Input> Type < string | character variable >
The type will determine what style elements are used when displaying the row. Header Body Footer

<Input> Required_Space < int >
This says that you want us to try to keep this many items together. It basically asks that this item be printed on the same page as the next REQUIRED_SPACE items, where an "item" is a paragraph or table row. It is, of course, meaningless for HTML.

<Input> Keep_Next < int >
Keep this line with the next line. This is like a more limited version of REQUIRED_SPACE, in that it can only be used to provide attachment to the next line, but it can also be used to specify the strength of the attachment, which will come in handy under some circumstances. The strength should generally be kept in the range 0-99, since title lines are attached to each other and to the table with a default strength of 100. Also, if there are multirows, then PSO will automatically increment the keepNext by one for each additional multirow. (The REQUIRED_SPACE sets the KEEP_NEXT values to 1.) This parameter is only effect for PRINTER destinations.

Rc = Row_End ( )

Mark the end of the row.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Table_Start ( )

Marks the beginning of a table. 

This cannot appear within another cell; it must appear at the top level. This restriction is due to RTF which does not support nested tables.

Other destinations can support it, although sometimes with restrictions (e.g., PRINTER allows a cell to contain text or a table, but not both). Note that a nested table cannot be broken across pages; more generally, a single table row (including the row of the outer table) cannot be broken across pages vertically.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Name < string | character variable >
A character string used in ODS processing to identify the object. Used in the ODS select or exclude processing as well as the ODS Results window.

<Input> Label < string | character variable >
A more descriptive character string than the Name used in ODS processing to identify the object. Used in the ODS select or exclude processing as well as the ODS Results window.

<Input> Overrides < string | character variable >
Style Overrides.

<Input> Id_Count < int >
The number of id columns is the table. This is really only

relevant when paneling; id columns will be copied to each panel. If omitted, this defaults to 1.

Not Implemented

<Input> Panel < int >
Allows the code to control how the table is paneled, should it be too wide to fit on the page. It may take on one or more of a set of constant values.

GDOC_PANEL_ALIGNED
Align the panels on the left rather than centering each panel independently.

GDOC_PANEL_NOBALANCE
Don't try to make the panels even; just fit as many columns as you can (respecting the glue values) on the first panels and put leftover columns at the end.

GDOC_PANEL_WRAP
Wrap the panels in place, so that you get all the panels for the first row, then all the panels for the second row, and forth. With this option, titles are not repeated per panel, but are also wrapped at the top of the page.

GDOC_PANEL_ENTIRE
Print the entire first panel, then the entire second panel, and so forth.

GDOC_PANEL_ENTIRE_PAGE
Like GDOC_PANEL_ENTIRE but it fills up the whole first page with the first panel, then the second page with the second panel, and so forth.

GDOC_PANEL_FORCE
Force the panel to split any time the glue is as weak as the weakest glue that causes any panel to break. For example, if we are forced to break a table like to split between any two states, then we'd force it to break between each state. This can greatly increase the amount of paper required for your report, but can be more visually pleasing, too.

Bitwise-or them together if you want more than one. If no options are specified, the "regular" paneling behavior will be enabled, which is to put a slice from each panel on each page, unless there are too many panels or too little page, in which it will revert to GDOC_PANEL_ENTIRE_PAGE behavior instead. Note that the "regular" paneling behavior as defined here is in fact the PROC PRINT paneling behavior, which is <em>not</em> the behavior of the vast majority of SAS procedures. This is unfortunate; it's a historical artifact that reflects the fact that I used to support PROC PRINT and was confused about what was normal.

Not Implemented

<Input> Max_Width < int >
Used to artificially limit the maximum width allowed per panel. For formats with a real maximum width, this is ignored, but it can be used to force those without a natural maximum, such as HTML, SGML, and RTF to panel their output. It represents the maximum number of "characters" per panel. The characters per column are specified in the

COLSPEC(). If this is not specified, then those documents will use a default, which will probably be very large in the case of HTML so as to avoid paneling in favor of scrollbars normally.

Not Implemented

<Input> Top_Space < dimension >
The space to put before the table. This will certainly be ignored by HTML, and while it is expected to be the same as the line count supplied to monospace for the same purpose, other viewers reserve the right to put a smaller or greater amount of vertical space as seems appropriate.

Not Implemented

<Input> Required_Space < int >
This says that you want us to try to keep this many items together. It basically asks that this item be printed on the same page as the next REQUIRED_SPACE items, where an "item" is a paragraph or table row. It is, of course, meaningless for HTML.

Not Implemented

<Input> PageCols < int >
The number of page columns to attempt to use with this table. These are also known as "phone book panels."

Not Implemented

Rc = Table_End ( )

Marks the end of the table.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments: None

Rc = Title ( )

To add a new page title to the system.

Returns:
0
success

Any other number
failure
Required Arguments: None
Optional Arguments:
<Input> Text < string | character variable >
The text of the Title.

<Input> Just < string | character variable >
The justification of the note. Left Center Right

<Input> Start < int >
The title index to begin at.

<Input> Clear < int >
Clear the cashed titles.

Disclaimer

THIS PRELIMINARY DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. The Institute shall not be liable whatsoever for any damages arising out of the use of this documentation, including any direct, indirect, or consequential damages. The Institute reserves the right to alter or abandon use of this documentation at any time. In addition, the Institute will provide no support for the materials contained herein.