DEFINE STREAM statement

Defines a stream for use in one or more procedures, or within a single class. Use this statement when you want to use streams other than the two ABL built-in unnamed streams. Using additional streams allows you to get input from more than one source simultaneously or to send output to more than one destination simultaneously.

Syntax


DEFINE { [ [ NEW [ GLOBAL ] ] SHARED ] \| [ PRIVATE ] } STREAM `stream-name`

NEW SHARED STREAM stream-name

Defines and identifies a stream that can be shared by other procedures. When the procedure using the DEFINE NEW SHARED STREAM statement ends, the stream is no longer available to any procedure.

NEW GLOBAL SHARED STREAM stream-name

Defines and identifies a stream that can be shared by other procedures and that will remain available even after the procedure that contains the DEFINE NEW GLOBAL SHARED STREAM statement ends.

SHARED STREAM stream-name

Defines and identifies a stream that was created by another procedure using the DEFINE NEW SHARED STREAM statement or the DEFINE NEW GLOBAL SHARED STREAM statement.

[ PRIVATE ] STREAM stream-name

Defines and identifies a stream as a class-scoped object. A class-scoped handle-based object is not a member of a class, but provides a resource that is privately available to the class definition similar to a non-shared data element in a procedure definition. The option to specify the PRIVATE access mode is provided for readability. You cannot specify PRIVATE when defining a stream as a data element in a method or procedure.

Note: This option is applicable only when defining a class-scoped stream in a class definition (.cls) file.

STREAM stream-name

Defines and identifies a stream for access only within the current procedure, class, or method of a class.

Examples

This procedure, in a single pass through the item table, uses the rpt stream to create a report and the exceptions stream to create a list of exceptions:

r-dfstr.p
DEFINE VARIABLE fnr AS CHARACTER NO-UNDO FORMAT "x(12)". DEFINE VARIABLE fne AS CHARACTER NO-UNDO FORMAT "x(12)". DEFINE VARIABLE excount AS INTEGER NO-UNDO LABEL "Total Number of exceptions". DEFINE NEW SHARED BUFFER xitem FOR item. DEFINE NEW SHARED STREAM rpt. DEFINE STREAM exceptions. SET fnr LABEL "Enter filename for report output" SKIP(1) fne LABEL "Enter filename for exception output" WITH SIDE-LABELS FRAME fnames. OUTPUT STREAM rpt TO VALUE(fnr) PAGED. OUTPUT STREAM exceptions TO VALUE(fne) PAGED. FOR EACH xitem: IF on-hand < alloc THEN DO: DISPLAY STREAM exceptions xitem.ItemNum xitem.ItemName xitem.OnHand xitem.Allocated WITH FRAME exitem DOWN. excount = excount + 1. END. RUN r-dfstr2.p. END. DISPLAY STREAM exceptions SKIP(1) excount WITH FRAME exc SIDE-LABELS. DISPLAY STREAM rpt WITH FRAME exc. OUTPUT STREAM rpt CLOSE. OUTPUT STREAM exceptions CLOSE.

r-dfstr.p

DEFINE VARIABLE fnr     AS CHARACTER NO-UNDO FORMAT "x(12)". 
DEFINE VARIABLE fne     AS CHARACTER NO-UNDO FORMAT "x(12)". 
DEFINE VARIABLE excount AS INTEGER   NO-UNDO 
  LABEL "Total Number of exceptions". 
DEFINE NEW SHARED BUFFER xitem FOR item. 
DEFINE NEW SHARED STREAM rpt. 
DEFINE STREAM exceptions. 
SET fnr LABEL "Enter filename for report output" SKIP(1) 
  fne LABEL "Enter filename for exception output" 
  WITH SIDE-LABELS FRAME fnames. 
OUTPUT STREAM rpt TO VALUE(fnr) PAGED. 
OUTPUT STREAM exceptions TO VALUE(fne) PAGED. 
FOR EACH xitem: 
  IF on-hand < alloc THEN DO: 
    DISPLAY STREAM exceptions  
      xitem.ItemNum xitem.ItemName xitem.OnHand xitem.Allocated 
      WITH FRAME exitem DOWN. 
    excount = excount + 1. 
  END. 
  RUN r-dfstr2.p. 
END. 
DISPLAY STREAM exceptions SKIP(1) excount WITH FRAME exc SIDE-LABELS. 
DISPLAY STREAM rpt WITH FRAME exc. 
OUTPUT STREAM rpt CLOSE. 
OUTPUT STREAM exceptions CLOSE.

Include the DISPLAY statement in the r-dfstr2.p procedure in the r-dfstr.p procedure for efficiency. (It is in a separate procedure here to illustrate shared streams.)

r-dfstr2.p
DEFINE SHARED STREAM rpt. DEFINE SHARED BUFFER xitem FOR Item. DISPLAY STREAM rpt ItemNum ItemName WITH NO-LABELS NO-BOX.

Notes

You cannot define a SHARED or NEW SHARED stream in a user-defined function, an internal procedure, or a persistent procedure. If you do, the AVM raises an ERROR on the RUN statement that creates the procedure.

You cannot define a SHARED or NEW SHARED stream in a class definition (.cls) file. If you do, ABL generates a compilation error.

You can overcome the limitations on SHARED or NEW SHARED streams by using stream handles. For more information, see the Stream object handle reference entry and the chapter on alternate I/O sources in OpenEdge Development: Programming Interfaces.

ABL automatically provides two unnamed streams to each procedure: the input stream and the output stream. These streams give the procedure a way to communicate with an input source and an output destination. For example, the following statement tells ABL to use the unnamed input stream to get input from the file named testfile:


INPUT FROM testfile.

Using the DEFINE STREAM statement creates a stream, but it does not actually open that stream. To open a stream, you must use the STREAM option with the INPUT FROM, INPUT THROUGH, OUTPUT TO, OUTPUT THROUGH, or INPUT-OUTPUT THROUGH statements. You must also use the STREAM option with any data handling statements that move data to and from the stream.

After you open the stream, you can use the SEEK function to return the offset value of the file pointer, or you can use the SEEK statement to position the file pointer to any location in the file.

For information about limits on the number of streams per procedure, see the application limits appendix in OpenEdge Deployment: Managing ABL Applications.